kCMMCheckBitmaprequest by checking the colors of the source image bitmap against the color gamut of the destination profile.
A CMM should respond to the
kCMMCheckBitmaprequest 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
CWCheckBitMapfunction. The ColorSync Manager dispatches this request to the Component Manager, which calls your CMM to service the request. A CMM typically responds to the
kCMMCheckBitmaprequest 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);
- A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
- A pointer to the bitmap containing the source image data whose colors your function must check.
- 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
MyCMCheckBitmapfunction must call this function periodically to allow it to report progress to the user.
- A reference constant passed from the calling application or driver, which your
MyCMCheckBitmapfunction must pass through as a parameter to calls it makes to the
- A pointer to the resulting bitmap allocated by the calling application or device driver. Your
MyCMCheckBitmapfunction must set pixels of the bitmap image to 1 if the corresponding pixel of the source bitmap indicated by
bitmapis 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.
DISCUSSIONIf your CMM supports this request code, your
MyCMMCheckBitmapfunction should be prepared to receive any of the bitmap types defined by the ColorSync Manager. Your
MyCMCheckBitmapfunction must check the colors of the source image bitmap pointed to by
bitmapagainst the color gamut of the destination profile using the profiles specified by a previous
kCMMConcatInitrequest 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
resultBitmapparameter. 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
kCMMConcatInitrequest, 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
kCMMInitrequest, it passes references to the source and destination profiles to use for the session. If it calls your CMM with the ColorSync
kCMMConcatInitrequest code, it passes a pointer to an array of type
ConcatProfileSetcontaining a set of profiles specified by the calling application to use for the session. For information about the
ConcatProfileSetdata type, see "Profile Header Structure for ColorSync 1.0" (page 3-44).
When the Component Manager calls your CMM with the
kCMMMatchColorsrequest code, it passes to your CMM in the
CMSessionparameter a handle to your CMM's storage for the calling applications's component instance. Your
MyCMCheckBitmapfunction 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.
MyCMCheckBitmapfunction 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
MyCMCheckBitmapfunction 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
MyCMBitmapCallBackProcfunction 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
MyCMBitmapCallBackProcfunction pointed to by the
pascal Boolean MyCMBitmapCallBackProc ( long progress, void *refCon);Each time your
MyCMCheckBitmapfunction calls the
MyCMBitmapCallBackProcfunction, it must pass to the function any data stored in the reference constant. When the Component Manager called your CMM with the
request code, it passed to your CMM the reference constant from the calling program.
Each time your function calls the
MyCMBitmapCallBackProcfunction, your function must pass it a byte count in the
progressparameter identifying the remaining number of bytes to check. The last time your
MyCMMatchBitmapfunction calls the
MyCMBitmapCallBackProcfunction, 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
dataColorSpacefield value and the
spacefield value of the source bitmap pointed to by the
bitmapparameter 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
MyCMMatchColorsfunction, 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.