Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Advanced Color Imaging Reference /

Chapter 4 - ColorSync Manager Reference for Color Management Modules / Optional CMM-Defined Functions

MyCMCheckBitmap
Handles the kCMMCheckBitmap request by checking the colors of the source image bitmap against the color gamut of the destination profile.
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, MyCMCheckBitmap) to handle the request.
The MyCMCheckBitmap function is a color management module-defined subroutine.
pascal CMError MyCMCheckBitmap(
ComponentInstance CMSession,
const CMBitmap *bitmap,
CMBitmapCallBackUPP progressProc,
void *refCon, 
CMBitmap *resultBitmap);
CMSession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
bitmap
A pointer to the bitmap containing the source image data whose colors your function must check.
progressProc
A pointer to a callback function supplied by the calling application or device driver that monitors the color-checking progress or aborts the operation as your function checks the colors of the source image. Your MyCMCheckBitmap function must call this function periodically to allow it to report progress to the user.
refCon
A reference constant passed from the calling application or driver, which your MyCMCheckBitmap function must pass through as a parameter to calls it makes to the MyCMBitmapCallBackProc function.
resultBitmap
A pointer to the resulting bitmap allocated by the calling application or device driver. Your MyCMCheckBitmap function must set pixels of the bitmap image to 1 if the corresponding pixel of the source bitmap indicated by bitmap is out of gamut.
function result
A result code of type CMError. See "Result Codes" (page 3-172) for a list of ColorSync-specific result codes.

DISCUSSION
If your CMM supports this request code, your MyCMMCheckBitmap function should be prepared to receive any of the bitmap types defined by the ColorSync Manager. Your MyCMCheckBitmap 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 profile's 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. For information about the ConcatProfileSet data type, see "Profile Header Structure for ColorSync 1.0" (page 3-44).
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 CMM's storage for the calling applications's component instance. Your MyCMCheckBitmap 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 MyCMCheckBitmap 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 MyCMCheckBitmap 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 Apple-supplied CMM calls the MyCMBitmapCallBackProc function approximately every half-second, unless the gamut checking takes less time; this happens when there is a small amount of data to check.
Here is the prototype for the MyCMBitmapCallBackProc function pointed to by the progressProc parameter:
pascal Boolean MyCMBitmapCallBackProc (
                     long progress, 
                     void *refCon);
Each time your MyCMCheckBitmap function calls the MyCMBitmapCallBackProc 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 MyCMBitmapCallBackProc 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 MyCMMatchBitmap function calls the MyCMBitmapCallBackProc 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 profile's 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 MyCMMatchColors 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.