![]() |
CMCheckBitmap |
||||
Header: | CMMComponent.h | Carbon status: | Unsupported | |
Handles the kCMMCheckBitmap request by checking the colors of the source image bitmap against the color gamut of the destination profile.
CMCheckBitmap ();
A CMM should respond to the kCMMCheckBitmap request code, but it is not required to do so. The ColorSync Manager sends this request code to your CMM on behalf of an application or device driver that called the CWCheckBitMap function. The ColorSync Manager dispatches this request to the Component Manager, which calls your CMM to service the request. A CMM typically responds to the kCMMCheckBitmap request code by calling a CMM-defined function (for example, CMCheckBitmap) to handle the request.
If your CMM supports this request code, your CMMCheckBitmap function should be prepared to receive any of the bitmap types defined by the ColorSync Manager. Your CMCheckBitmap function must check the colors of the source image bitmap pointed to by bitmap against the color gamut of the destination profile using the profiles specified by a previous kNCMMInit, kCMMInit, or kCMMConcatInit request to your CMM. If a pixel is out of the destination profiles color gamut, your function should set the corresponding pixel in the image of the bitmap pointed to by the resultBitmap parameter. The ColorSync Manager returns the resulting bitmap to the calling application or driver to report the outcome of the gamut check.
Before the Component Manager calls your CMM with a ColorSync request to gamut check the colors of a bitmap, it calls your CMM with a kNCMMInit, kCMMInit, or kCMMConcatInit request, passing references to the profiles to use for the color-checking session and sending your CMM a request to initialize the session.
If the Component Manager calls your CMM with a ColorSync kNCMMInit or kCMMInit request, it passes references to the source and destination profiles to use for the session. If it calls your CMM with the ColorSync kCMMConcatInit request code, it passes a pointer to an array of type ConcatProfileSet containing a set of profiles specified by the calling application to use for the session.
When the Component Manager calls your CMM with the kCMMMatchColors request code, it passes to your CMM in the CMSession parameter a handle to your CMMs storage for the calling applications component instance. Your CMCheckBitmap function should use the profile data you set in your storage for this component instance to perform the color-checking process. If you used some other method to store profile data for this component instance when you initialized the session, you should obtain the profile data you require for the color-checking process from that storage.
Your CMCheckBitmap function must call the progress function supplied by the calling application or device driver at regular intervals to allow it to report progress to the user on the color-checking session. Your CMCheckBitmap function should monitor the progress function for a returned value of true, which indicates that the user interrupted the color-matching process. In this case, you should terminate the color-matching process.
The default CMM calls the CMBitmapCallBackProcPtr function approximately every half-second, unless the gamut checking takes less time; this happens when there is a small amount of data to check.
Each time your CMCheckBitmap function calls the CMBitmapCallBackProcPtr function, it must pass to the function any data stored in the reference constant. When the Component Manager called your CMM with the kCMMCheckBitmap request code, it passed to your CMM the reference constant from the calling program.
Each time your function calls the CMBitmapCallBackProcPtr function, your function must pass it a byte count in the progress parameter identifying the remaining number of bytes to check. The last time your CMMatchBitmap function calls the CMBitmapCallBackProcPtr function, it must pass a byte count of 0 to indicate the completion of the color-checking process. This signals the progress function to perform any cleanup operations it requires.
If the source profiles dataColorSpace field value and the space field value of the source bitmap pointed to by the bitmap parameter do not specify the same data color space, your function should terminate the color-checking process and return an error code.
If your CMM does not support a bitmap type that you receive, you can return an unimplemented error. In this case, the ColorSync Manager unpacks the colors of the bitmap and calls your CMMatchColors function, passing it the bitmap colors in a color list. You should avoid defaulting to this behavior, if possible, because it incurs overhead and slows down performance.
Use CWCheckBitmap instead. CMCheckBitmap is an API to CMMs -- Component Manager structures that Mac OS X does not support. In Carbon, CMMs are replced by opaque structures of type CFBundle.
© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)