Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

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

/

MyCMMatchPixMap

Handles the kCMMMatchPixMap request by matching the colors of the specified pixel map image to the destination profile's color gamut.

A CMM should respond to the kCMMMatchPixMap 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 CWMatchPixMap function or high-level QuickDraw operations. The ColorSync Manager dispatches this request to the Component Manager, which calls your CMM to service the request. A CMM typically responds to the kCMMMatchPixMap request code by calling a CMM-defined function (for example, MyCMMatchPixMap) to handle the request.

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

pascal CMError MyCMMatchPixMap(
ComponentInstance CMSession,
PixMap *myPixMap,
CMBitmapCallBackUPP progressProc,
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 the pixel map to match. A pixel map is a QuickDraw structure describing pixel data. The pixel map is stored in nonrelocatable memory. Your function replaces the original colors of the pixel image with the matched colors corresponding to the color gamut of the destination device.

progressProc

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

refCon

A reference constant passed from the calling application or driver, which your MyCMMatchPixMap 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 MyCMMatchPixMap function should be prepared to receive any of the pixel map types defined by QuickDraw.Your MyCMMatchPixMap function must match the colors of the pixel map image pointed to by myPixMap parameter to the destination profile's color gamut, replacing the original pixel colors with their corresponding colors as specified in the data color space of the destination device's color gamut.

Before the Component Manager calls your CMM with a ColorSync request to match 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 kCMMMatchPixMap 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 MyCMMatchPixMap function should use the profile data you set in your storage for this component instance to perform the color matching. 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 matching 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-matching session. Your MyCMMatchPixMap 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 progress function approximately every half-second, unless color matching 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 MyCMMatchPixMap 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 kCMMMatchPixMap 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. The last time your MyCMMatchPixMap function calls the MyCMBitmapCallBackProc function, it must pass a byte count of 0 to indicate the completion of the matching 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 matching. 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.