PATHDocumentation > Mac OS 8 and 9 > Mutlimedia and Graphics > ColorSync Manager >

Managing Color With ColorSync


Required CMM-Defined Functions

This section describes the functions that your CMM should define to handle ColorSync Manager required request codes.


NCMInit

Handles the kNCMMInit request by performing any required private initialization.

A CMM must respond to the kNCMMInit request code. The ColorSync Manager sends this code to request your CMM to instantiate any private data it needs. A CMM responds to the kNCMMInit request code by calling a CMM-defined subroutine, for example, NCMInit to handle the request.

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

pascal CMError NCMInit (
                     ComponentInstance CMSession,
                     CMProfileRef srcProfile,
                     CMProfileRef dstProfile);
CMSession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
srcProfile
A reference to the source profile to use in the color-matching or color-checking session. Your CMM should store any profile information it requires before returning to the Component Manager. (The calling program obtained the profile reference passed in this parameter.)
dstProfile
A reference to the destination profile to use in the color-matching or color-checking session. Your CMM should store any profile information it requires before returning to the Component Manager. (The calling program obtained the profile reference passed in this parameter.)
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

The Component Manager calls your CMM with the kNCMMInit request code when a ColorSync-supportive application or device driver specifies your CMM for a color-matching or color-checking session. For example, when an application or device driver calls the NCWNewColorWorld function, the Component Manager calls your NCMInit function.

Using the storage pointed to by the CMSession handle, your NCMInit function should initialize any private data your CMM will need for the color session and for handling subsequent calls pertaining to this component instance. Your function must obtain required information from the profiles and initialize private data for subsequent color-matching or color-checking sessions with these values. After your function returns to the Component Manager, it no longer has access to the profiles.

This request gives you the opportunity to examine the profile contents before storing them. If you do not support some aspect of the profile, then you should return an unimplemented error in response to this request. For example, if your CMM does not implement multichannel color support, you should return an unimplemented error at this point.

In addition to the standard profile information you should preserve in response to this request, you should preserve the quality flag setting specified in the profile header and the rendering intent, also specified in the header.

The Component Manager calls your CMM with a standard open request to open the CMM when a ColorSync-supportive application or device driver requests that the Component Manager open a connection to your component. At this time, your component should allocate any memory it needs to maintain a connection for the requesting application or driver. You should allocate memory from the current heap zone. If that attempt fails, you should allocate memory from the system heap or the temporary heap. You can use the SetComponentInstanceStorage function to associate the allocated memory with the component instance. Whenever the calling application or driver requests services from your component, the Component Manager supplies you with the handle to this memory in the CMSession parameter.

The Component Manager may call your CMM with the kNCMMInit request code multiple times after it calls your CMM with a request to open the CMM. For example, it may call your CMM with an initialization request once with one pair of profiles and then again with another pair of profiles. For each call, you need to reinitialize the storage based on the content of the current profiles.

Your CMM should support all seven classes of profiles defined by the ICC. For information on the seven classes of profiles, see ColorSync Reference for Applications and Drivers .


CMMatchColors

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, CMMatchColors ) to handle the request by matching colors in the color list.

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

pascal CMError CMMatchColors (
                     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 of type CMColor 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.
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 . For possible values, see Result Codes for the ColorSync Manager .

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 link profile specified by the calling application to use for the color-matching session. For information about the ConcatProfileSet data type, see CMConcatProfileSet .

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 CMMatchColors 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 CMMatchColors , 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:


CMCheckColors

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, CMCheckColors ) to handle the request.

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

pascal CMError CMCheckColors (
                     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 of type CMColor , 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.
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 bit field, 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 . For possible values, see Result Codes for the ColorSync Manager .

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 link 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 CMCheckColors 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 the functions NCMInit and CMConcatInit for more information.

For each color in the list, your CMCheckColors 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.


© 1988-1999 Apple Computer, Inc. — (Last Updated 20 Jan 99)