Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

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

/

MyCMCheckPixMap

Handles the kCMMCheckPixMap request by checking the colors of the specified pixel map image against the color gamut of the destination profile.

A CMM should respond to the kCMMCheckPixMap 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 that called the CWCheckPixMap 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 kCMMCheckPixMap request code by calling a CMM-defined function (for example, MyCMCheckPixMap) to handle the request.

The MyCMCheckPixMap function is a color management module-defined subroutine.

pascal CMError MyCMCheckPixMap(
ComponentInstance CMSession,
const PixMap *myPixMap,
CMBitmapCallBackUPP progressProc,
BitMap *myBitMap,
void *refCon);

CMsession

A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.

myPixMap

A pointer to a nonrelocatable pixel map whose colors are to be checked. A pixel map is a QuickDraw structure describing pixel data.

progressProc

A pointer to a callback function, supplied by the calling application or device driver, that monitors the color-checking progress or terminates the operation as your function checks the pixel map colors. Your MyCMCheckPixMap function must call this function at regular intervals to allow it to report progress to the user.

myBitMap

A pointer to a QuickDraw bitmap whose boundaries equal those of the pixel map indicated by the myPixMap parameter. Your MyCMCheckPixMap function must set a pixel to 1 if the corresponding pixel of the pixel map indicated by myPixMap is out of gamut.

refCon

A reference constant passed from the calling application or driver, which your MyCMCheckPixMap function must pass through as a parameter to calls it makes to the MyCMBitmapCallBackProc function.

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 MyCMCheckPixMap function should be prepared to receive any of the pixel map types defined by QuickDraw.Your MyCMCheckPixMap function must check the colors of the pixel map image pointed to by the myPixMap parameter against the color gamut of the destination profile to determine if the colors are within the gamut. If a pixel color of the pixel map indicated by myPixMap is out of gamut, your function must set to 1 the corresponding pixel of the bitmap indicated by myBitMap. The ColorSync Manager returns the bitmap showing the gamut check results to the calling application or device driver.

Before the Component Manager calls your CMM with a ColorSync request to check the colors of a pixel map, it calls your CMM with a kNCMMInit or kCMMConcatInit request. Your CMM sets up the destination profile information during initialization in response to the kNCMMInit or kCMMConcatInit request code.

When the Component Manager calls your CMM with the kCMMCheckPixMap request code, it passes to your CMM in the session parameter a handle to your CMM's private storage for the calling applications's component instance. Your MyCMCheckPixMap function should use the profile data you set in your storage for this component instance. 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 MyCMMatchPixMap 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 MyCMCheckPixMap function should monitor the progress function for a returned value of true, which indicates that the user interrupted the color-checking process. In this case, you should terminate the color-checking process. The Apple-supplied CMM calls the progress function approximately every half-second, unless color checking takes less time; this happens when there is a small amount of data to match.

Here is the prototype for the MyCMBitmapCallBackProc function pointed to by the progressProc parameter:

pascal Boolean MyCMBitmapCallBackProc (
                     long progress, 
                     void *refCon);

Each time your MyCMCheckPixMap 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 kCMMCheckPixMap 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. As your MyCMCheckPixMap function checks the pixels of the myPixMap map, it should set the corresponding pixel of myBitMap to 0 if the color is in gamut and 1 if it is out of gamut. The last time your MyCMCheckPixMap function calls the MyCMBitmapCallBackProc function, it must pass a byte count of 0 to indicate the completion of the color-checking process, signaling the progress function to perform any cleanup operations it requires.

The data color space of a pixel map is implicitly RGB. If the source and destination profiles' data color spaces (dataColorSpace field) are not also RGB, your function should not perform the color check. Instead, it should return an error.

If your CMM does not support a pixel map type that you receive, you can return an unimplemented error. In this case, the ColorSync Manager unpacks the colors of the pixel map and calls your MyCMMatchColors function, passing it the pixel map colors in a color list. You should avoid defaulting to this behavior, if possible, because it incurs overhead and slows down performance.