Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

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

/

MyCMMatchBitmap

Handles the kCMMMatchBitmap request by matching the colors of the source image bitmap to the color gamut of the destination profile.

A CMM should respond to the kCMMMatchBitmap 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 CWMatchBitMap 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 kCMMMatchBitmap request code by calling a CMM-defined function (for example, MyCMMatchBitmap) to handle the request.

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

pascal CMError MyCMMatchBitmap(
ComponentInstance CMSession,
const CMBitmap *bitmap,
CMBitmapCallBackUPP progressProc,
void *refCon, 
CMBitmap *matchedBitmap);

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 match.

progressProc

A pointer to a callback function supplied by the calling application or device driver that monitors the color-matching progress or aborts the operation as your function matches the bitmap colors. Your MyCMMatchBitmap 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 MyCMMatchBitmap function must pass through as a parameter to calls it makes to the MyCMBitmapCallBackProc function.

matchedBitmap

A pointer to a bitmap in which your function stores the resulting color-matched image. The calling program allocates the pixel buffer pointed to by the image field of the CMBitmap structure. If this value is NULL, then your MyCMMatchBitmap function must match the bitmap colors in place.

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 MyCMMatchBitmap function should be prepared to receive any of the bitmap types defined by the ColorSync Manager. Your MyCMMatchBitmap function must match the colors of the source image bitmap pointed to by bitmap to the color gamut of the destination profile using the profiles specified by a previous kNCMMInit, kCMMInit, or kCMMConcatInit request to your CMM. If the matchedBitmap parameter points to a bitmap, you should store the resulting color-matched image in that bitmap. Otherwise, you should store the resulting color-matched image in the source bitmap pointed to by the bitmap parameter. The color-matched bitmap image your function creates is returned to the calling application or driver.

Before the Component Manager calls your CMM with a ColorSync request to match the colors of a bitmap, it calls your CMM with a kNCMMInit, kCMMInit, or kCMMConcatInit request, passing your CMM references to the profiles to use for the color-matching session and requesting that your CMM 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 color-matching 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 or a device-linked profile specified by the calling program to use for the color-matching session. For information about the ConcatProfileSet data type, see "Concatenated Profile Set Structure" (page 3-46).

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 MyCMMatchBitmap 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 MyCMMatchBitmap 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 MyCMMatchBitmap 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 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 MyCMMatchBitmap function calls the MyCMBitmapCallBackProc function, it must pass to the function any data stored in the reference constant. When the Component Manager calls your CMM with the kCMMMatchBitmap request code, it passes 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 MyCMMatchBitmap function calls the MyCMBitmapCallBackProc function, it must pass a byte count of 0. A byte count of 0--meaning there is no more data to match--indicates the completion of the matching process and 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-matching process and return an error code.

Also, if the destination profile's dataColorSpace field value and the space field value of the resulting bitmap pointed to by the matchedBitmap parameter do not specify the same data color space, your function should terminate the color-matching 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 CMMMatchColors 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.