Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

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

/

MyCMCheckColors

Handles the kCMMCheckColors request by checking the specified colors against the gamut of the destination profile.

A CMM must respond to the kCMMCheckColors request code. The ColorSync Manager sends this request code to your CMM on behalf of an application or device driver that called the CWCheckColors 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 kCMMCheckColors request code by calling a CMM-defined function (for example, MyCMCheckColors) to handle the request.

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

pascal CMError MyCMCheckColors (
ComponentInstance CMSession,
CMColor *myColors, 
unsigned long count, 
long *result); 

CMSession

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

myColors

A pointer to a color union array (page 3-57), specified by the calling application or device driver, that contains the list of colors to check against the destination device's color gamut. The color values are given in the data color space of the source profile specified by a previous kNCMMInit or kCMMConcatInit request to your CMM. For a description of the CMColor data type, see "The Color Union" (page 3-57).

count

A one-based count of the number of colors in the color list of the CMColor array.

result

A pointer to an array of long data types used as a bitfield, with each bit representing a color in the array pointed to by myColors. The result array contains enough members to allow for 1 bit to represent each color in the myColors array. Your function sets a bit in the array if the corresponding color-list color is out of gamut for the destination profile. On return, this array indicates the color-checking results.

function result

A result code of type CMError. See "Result Codes" (page 3-172) for a list of ColorSync-specific result codes.

DISCUSSION

When your CMM receives a kCMMCheckColors request code, your CMM should test the given list of colors against the gamut specified by the destination profile to report if the colors fall within a destination device's color gamut. Before the Component Manager calls your CMM with a ColorSync request to gamut check colors, it calls your CMM with a kNCMMInit, kCMMInit, or kCMMConcatInit request passing your CMM references to the profiles to use for the color-checking session and requesting your CMM 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 color-checking session. (If it calls your CMM with the ColorSync kCMMConcatInit request, 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-checking session.)

When the Component Manager calls your CMM with the kCMMCheckColors request code, it passes to your CMM in the CMSession parameter a handle to your CMM's storage for the calling application's or device driver's component instance. This is the storage whose data you initialized when the Component Manager called you to initialize the session for this component instance.

Using the profile data set in your storage for this component instance, your MyCMCheckColors function should check the colors specified in the myColors array against the color gamut of the destination profile. Your function should use the result array to return indication of whether the colors in the list are in or out of gamut for the destination device. 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. The color list may contain multichannel color data types, so your CMM must support them. If your CMM does not support these color data types, you should return an unimplemented error in response to the initialization request code. See MyNCMInit (page 4-10) and MyCMConcatInit (page 4-25) for more information.

For each color in the list, your MyCMCheckColors function should set the corresponding bit in the result bit array if the color is out of gamut for the destination device as specified by the destination profile. The leftmost bit in the field corresponds to the first color in the list.

The gamut test your function performs provides a preview of color matching. The ColorSync Manager returns the results to the calling application or device driver.