Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Advanced Color Imaging Reference /

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

MyCMMatchColors
Handles the kCMMMatchColors request by matching the specified colors to the gamut of the destination profile.
A CMM must respond to the kCMMMatchColors request code. The ColorSync Manager sends this request code to your CMM on behalf of an application or device driver that called the CWMatchColors 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 kCMMMatchColors request code by calling a CMM-defined function (for example, MyCMMatchColors) to handle the request by matching colors in the color list.
The MyCMMatchColors function is a color management module-defined subroutine.
pascal CMError MyCMMatchColors (
ComponentInstance CMSession,
CMColor *myColors,
unsigned long count); 
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. On input, this array contains the list of colors to match. 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. On output, this array contains the list of matched colors specified by your function in the data color space of the destination profile. 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.
function result
A result code of type CMError. See "Result Codes" (page 3-172) for a list of ColorSync-specific result codes.

DISCUSSION
Before the Component Manager calls your CMM with a ColorSync request to match colors, 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 your CMM to initialize the session.
If the Component Manager calls your CMM with a ColorSync kNCMMInit or kCMMInit request code, 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 application 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.
In response to this request code, you must support 16-bit components for color spaces other than multichannel components and 8-bit components for HiFi colors.
Using the profile data you set in your storage for this component instance, your MyCMMatchColors function should match the colors specified in the myColors array to the color gamut of the destination profile, replacing the color value specifications in the myColors array with the matched colors specified in the data color space of the destination profile. 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.
For a color-matching session with a named color space profile and other profiles, the named color profile must be first in the color world. A color world of this type cannot be used with bitmap or pixel map functions--it can only be used with a function such as MyCMMatchColors, with the myColors color list containing the named color indexes. For more information on the rules governing the types of profiles you can specify in a profile array, see the following sections:

"Profile Header Structure for ColorSync 1.0" (page 3-44)
"NCWNewColorWorld" (page 3-106)
"CWConcatColorWorld" (page 3-108)
"CWNewLinkProfile" (page 3-110)