PATHMac OS 8 and 9 Developer Documentation > Mutlimedia and Graphics > ColorSync Manager >

Managing Color With ColorSync


Optional CMM-Defined Functions

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


CMMValidateProfile

Handles the kCMMValidateProfile request by determining if the specified profile contains the minimum set of elements required for a profile of its type.

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

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

pascal CMError CMMValidateProfile (
                     ComponentInstance CMSession,
                                         CMProfileRef prof,
                                         Boolean *valid);
CMSession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
prof
A reference to the profile to validate.
valid
A pointer to a flag whose value you set to true if the profile contains the elements required for a color-matching or color-checking session for a profile of this type and false if it doesn't.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Your CMMValidateProfile function should test the profile whose reference is passed in the prof parameter to determine if the profile contains the minimum set of elements required for a profile of its type. For each profile class, such as a device profile, there is a specific set of required tagged elements defined by the ICC that the profile must include.

The ICC also defines optional tags, which may be included in a profile. Your CMM might use these optional elements to optimize or improve its processing. Additionally, a profile might include private tags defined to provide your CMM with processing capability it uses. The profile developer can define these private tags, register the tag signatures with the ICC, and include the tags in a profile.

Your CMMValidateProfile function should check for the existence of the required minimum set of profile elements for a profile of this type and any optional or private tags required by your CMM.

Instead of itself checking the profile for the minimum profile elements requirements for the profile class, your CMMValidateProfile function may use the Component Manager functions to call ColorSync's default CMM and have it perform the minimum defaults requirements validation. The signature of the default CMM is 'appl' .

To call the default CMM when responding to a kCMMValidateProfile request from an application, your CMM can use the standard mechanisms used by applications to call another component. For information, see the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox.


CMMatchBitmap

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

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

pascal CMError CMMatchBitmap(
                     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 CMMatchBitmap 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 CMMatchBitmap function must pass through as a parameter to calls it makes to the CMBitmapCallBackProc 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 CMMatchBitmap function must match the bitmap colors in place.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

If your CMM supports this request code, your CMMatchBitmap function should be prepared to receive any of the bitmap types defined by the ColorSync Manager. Your CMMatchBitmap 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 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-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 program 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. Your CMMatchBitmap 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 CMMatchBitmap 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 CMMatchBitmap 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 default CMM calls the CMBitmapCallBackProc 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 CMBitmapCallBackProc function pointed to by the progressProc parameter:

pascal Boolean CMBitmapCallBackProc (
                            long progress,
                            void *refCon);

Each time your CMMatchBitmap function calls the CMBitmapCallBackProc 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 CMBitmapCallBackProc function, your function must pass it a byte count in the progress parameter identifying the remaining number of bytes. The last time your CMMatchBitmap function calls the CMBitmapCallBackProc 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.


CMCheckBitmap

Handles the kCMMCheckBitmap request by checking the colors of the source image bitmap against the color gamut of the destination profile.

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

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

pascal CMError CMCheckBitmap(
                     ComponentInstance CMSession,
                                         const CMBitmap *bitmap,
                                         CMBitmapCallBackUPP progressProc,
                                         void *refCon,
                                         CMBitmap *resultBitmap);
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 check.
progressProc
A pointer to a callback function supplied by the calling application or device driver that monitors the color-checking progress or aborts the operation as your function checks the colors of the source image. Your CMCheckBitmap 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 CMCheckBitmap function must pass through as a parameter to calls it makes to the CMBitmapCallBackProc function.
resultBitmap
A pointer to the resulting bitmap allocated by the calling application or device driver. Your CMCheckBitmap function must set pixels of the bitmap image to 1 if the corresponding pixel of the source bitmap indicated by bitmap is out of gamut.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

If your CMM supports this request code, your CMMCheckBitmap function should be prepared to receive any of the bitmap types defined by the ColorSync Manager. Your CMCheckBitmap function must check the colors of the source image bitmap pointed to by bitmap against the color gamut of the destination profile using the profiles specified by a previous kNCMMInit , kCMMInit , or kCMMConcatInit request to your CMM. If a pixel is out of the destination profile's color gamut, your function should set the corresponding pixel in the image of the bitmap pointed to by the resultBitmap parameter. The ColorSync Manager returns the resulting bitmap to the calling application or driver to report the outcome of the gamut check.

Before the Component Manager calls your CMM with a ColorSync request to gamut check the colors of a bitmap, it calls your CMM with a kNCMMInit , kCMMInit , or kCMMConcatInit request, passing references to the profiles to use for the color-checking session and sending your CMM a request 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 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 specified by the calling application to use for the session. For information about the ConcatProfileSet data type, see CMHeader .

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 CMCheckBitmap function should use the profile data you set in your storage for this component instance to perform the color-checking process. 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-checking process from that storage.

Your CMCheckBitmap 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-checking session. Your CMCheckBitmap 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 default CMM calls the CMBitmapCallBackProc function approximately every half-second, unless the gamut checking takes less time; this happens when there is a small amount of data to check.

Here is the prototype for the CMBitmapCallBackProc function pointed to by the progressProc parameter:

pascal Boolean CMBitmapCallBackProc (
                            long progress,
                            void *refCon);

Each time your CMCheckBitmap function calls the CMBitmapCallBackProc function, it must pass to the function any data stored in the reference constant. When the Component Manager called your CMM with the kCMMCheckBitmap request code, it passed to your CMM the reference constant from the calling program.

Each time your function calls the CMBitmapCallBackProc function, your function must pass it a byte count in the progress parameter identifying the remaining number of bytes to check. The last time your CMMatchBitmap function calls the CMBitmapCallBackProc function, it must pass a byte count of 0 to indicate the completion of the color-checking process. This 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-checking 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 CMMatchColors 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.


CMConcatInit

Handles the kCMMConcatInit request by initializing any private data the CMM will need for a color session involving the specified set of profiles.

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

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

pascal CMError CMConcatInit (
                     ComponentInstance CMSession,
                                         CMConcatProfileSet *profileSet);
CMsession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
profileSet
A pointer to an array of profiles of type CMConcatProfileSet to use in a color-matching or color-checking session. The profiles in the array are in processing order--source through destination. The profileSet field of the data structure contains the array.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Using the private storage pointed to by the CMSession handle, your CMConcatInit function should initialize any private data your CMM will need for a color session involving the set of profiles specified by the profile array pointed to by the profileSet parameter. Your function should also initialize any additional private data needed in handling subsequent calls pertaining to this component instance.

A color-matching or color-checking session for a set of profiles entails various color transformations among devices in a sequence for which your CMM is responsible. 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.

When your CMM uses a device link profile or a set of concatenated profiles, you must adhere to the following guidelines and rules:

For specific guidelines on handling device link profiles and additional information on handling concatenated profiles, see ColorSync Reference for Applications and Drivers .

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 attempt to 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 session parameter. For complete details on the SetComponentInstanceStorage function, see the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox.

The Component Manager may call your CMM with the kCMMConcatInit 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 .


CMMatchPixMap

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

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

pascal CMError CMMatchPixMap(
                     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 CMMatchPixMap 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 CMMatchPixMap function must pass through as a parameter to calls it makes to the CMBitmapCallBackProc function.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

If your CMM supports this request code, your CMMatchPixMap function should be prepared to receive any of the pixel map types defined by QuickDraw.Your CMMatchPixMap 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 CMMatchPixMap 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 CMMatchPixMap 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 CMMatchPixMap 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 default 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 CMBitmapCallBackProc function pointed to by the progressProc parameter:

pascal Boolean CMBitmapCallBackProc (
                            long progress,
                            void *refCon);

Each time your CMMatchPixMap function calls the CMBitmapCallBackProc 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 CMBitmapCallBackProc function, your function must pass it a byte count in the progress parameter identifying the remaining number of bytes. The last time your CMMatchPixMap function calls the CMBitmapCallBackProc 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 CMMatchColors 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.


CMCheckPixMap

Handles the kCMMCheckPixMap request by checking the colors of the specified pixel map image against the color gamut of the destination profile.

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

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

pascal CMError CMCheckPixMap(
                     ComponentInstance CMSession,
                                         const PixMap *myPixMap,
                                         CMBitmapCallBackUPP progressProc,
                                         BitMap *myBitMap,
                     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 a nonrelocatable pixel map whose colors are to be checked. A pixel map is a QuickDraw structure describing pixel data.
progressProc
A pointer to a callback function, supplied by the calling application or device driver, that monitors the color-checking progress or terminates the operation as your function checks the pixel map colors. Your CMCheckPixMap function must call this function at regular intervals to allow it to report progress to the user.
myBitMap
A pointer to a QuickDraw bitmap whose boundaries equal those of the pixel map indicated by the myPixMap parameter. Your CMCheckPixMap function must set a pixel to 1 if the corresponding pixel of the pixel map indicated by myPixMap is out of gamut.
refCon
A reference constant passed from the calling application or driver, which your CMCheckPixMap function must pass through as a parameter to calls it makes to the CMBitmapCallBackProc function.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

If your CMM supports this request code, your CMCheckPixMap function should be prepared to receive any of the pixel map types defined by QuickDraw.Your CMCheckPixMap function must check the colors of the pixel map image pointed to by the myPixMap parameter against the color gamut of the destination profile to determine if the colors are within the gamut. If a pixel color of the pixel map indicated by myPixMap is out of gamut, your function must set to 1 the corresponding pixel of the bitmap indicated by myBitMap . The ColorSync Manager returns the bitmap showing the gamut check results to the calling application or device driver.

Before the Component Manager calls your CMM with a ColorSync request to check 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 kCMMCheckPixMap 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 CMCheckPixMap function should use the profile data you set in your storage for this component instance. 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-checking process from that storage.

Your CMMatchPixMap 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-checking session. Your CMCheckPixMap function should monitor the progress function for a returned value of true , which indicates that the user interrupted the color-checking process. In this case, you should terminate the color-checking process. The default CMM calls the progress function approximately every half-second, unless color checking takes less time; this happens when there is a small amount of data to match.

Here is the prototype for the CMBitmapCallBackProc function pointed to by the progressProc parameter:

pascal Boolean CMBitmapCallBackProc (
                            long progress,
                            void *refCon);

Each time your CMCheckPixMap function calls the CMBitmapCallBackProc function, it must pass to the function any data stored in the reference constant. When the Component Manager called your CMM with the kCMMCheckPixMap r equest code, it passed to your CMM the reference constant from the calling program.

Each time your function calls the CMBitmapCallBackProc function, your function must pass it a byte count in the progress parameter identifying the remaining number of bytes to check. As your CMCheckPixMap function checks the pixels of the myPixMap map, it should set the corresponding pixel of myBitMap to 0 if the color is in gamut and 1 if it is out of gamut. The last time your CMCheckPixMap function calls the CMBitmapCallBackProc function, it must pass a byte count of 0 to indicate the completion of the color-checking 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 check. 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 CMMatchColors 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.


CMNewLinkProfile

Handles the kCMMNewLinkProfile request by creating a single device link profile that includes the profiles in the specified profile set.

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

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

pascal CMError CMNewLinkProfile(
                     ComponentInstance CMSession,
                                         CMProfileRef *prof,
                     const CMProfileLocation *targetLocation,
                                         CMConcatProfileSet *profileSet);
CMsession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
prof
A pointer to a reference to a device link profile of type DeviceLink . Your CMNewLinkProfile function creates this profile, opens it to obtain a reference to it, and returns a pointer to the profile reference in this parameter. The profile may be a file-based profile or a handle-based profile. It must not be a pointer-based profile or a temporary profile.
targetLocation
A pointer to a location specification for the resulting profile, which your function returns. This is the file specification where you created the profile. For information on how to specify the location, see CMProfLoc and CMProfileLocation .
profileSet
A pointer to an array of profiles of type CMConcatProfileSet . Your function must include these profiles in order in any device link profile it creates. The profiles in the array are in processing order--source through destination. The profileSet field of the data structure contains the array.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Your CMNewLinkProfile function must create a single device link profile of type DeviceLink that includes the profiles passed to you in the array pointed to by the profileSet parameter. For information about profiles of type DeviceLink , see Profile Class . See also CWNewLinkProfile , which describes how to create a device-link profile.

After your function creates the device link profile, it must open the profile and return a reference to the profile in the prof parameter.

The International Color Consortium Profile Format Specification, version 2.x, document revision 3.x, also describes device link profiles. For information on how to obtain a copy of this document, contact the Developer Support organization of Apple Computer.


CMMGetPS2ColorSpace

Handles the kCMMGetPS2ColorSpace request by obtaining or deriving the color space element data from the source profile.

A CMM may respond to the kCMMGetPS2ColorSpace 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 CMGetPS2ColorSpace 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 kCMMGetPS2ColorSpace request code by calling a CMM-defined function (for example, CMMGetPS2ColorSpace ) to handle the request.

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

pascal CMError CMMGetPS2ColorSpace(
                     ComponentInstance CMSession,
                                         CMProfileRef srcProf,
                                         unsigned long flags,
                                         CMFlattenUPP proc,
                                         void *refCon);
CMsession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
srcProf
A profile reference to the source profile from which you must obtain or derive the color space element data.
flags
Reserved for future use.
proc
A pointer to a ColorSyncDataTransfer function supplied by the calling application or device driver. Your CMMGetPS2ColorSpace function calls this function repeatedly as necessary until you have passed all the source profile's color space element data to this function.
refCon
A reference constant, containing data specified by the calling application or device driver, that your CMMGetPS2ColorSpace function must pass to the ColorSyncDataTransfer function.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Only for special cases should a custom CMM need to support this request code. If your CMM supports this function, your CMMGetPS2ColorSpace function must obtain or derive the color space element data from the source profile whose reference is passed to your function in the srcProf parameter.

The color space data may be assigned to the PostScript Level 2 color space array ( ps2CSATag ) tag in the source profile. The byte stream containing the color space element data that your function passes to the ColorSyncDataTransfer function is used as the operand to the PostScript setColorSpace operator.

Your function must allocate a data buffer in which to pass the color space element data to the ColorSyncDataTransfer function supplied by the calling application or driver. Your CMMGetPS2ColorSpace function must call the ColorSyncDataTransfer function repeatedly until you have passed all the data to it. Here is the prototype for the ColorSyncDataTransfer function pointed to by the proc parameter:

pascal OSErr ColorSyncDataTransfer(
                        long command,
                        long *size,
                        void *data,
                        void *refCon);

Your CMMGetPS2ColorSpace function communicates with the ColorSyncDataTransfer function, using a command parameter to identify the operation to perform. Your function should call the ColorSyncDataTransfer function first with the openWriteSpool command to direct the ColorSyncDataTransfer function to begin the process of writing the profile color space element data you pass it in the data buffer. Next, you should call the ColorSyncDataTransfer function with the writeSpool command. After the ColorSyncDataTransfer function returns in the size parameter the amount of data it actually wrote, you should call the ColorSyncDataTransfer function again with the writeSpool command, repeating this process as often as necessary until all the color space data is transferred. After the data is transferred, you should call the ColorSyncDataTransfer function with the closeSpool command.

When your function calls the ColorSyncDataTransfer function, it passes in the data buffer the profile data to transfer to the ColorSyncDataTransfer function and the size in bytes of the buffered data in the size parameter. The ColorSyncDataTransfer function may not always write all the data you pass it in the data buffer. Therefore, on return the ColorSyncDataTransfer function command passes back in the size parameter the number of bytes it actually wrote. Your CMMGetPS2ColorSpace function keeps track of the number of bytes of remaining color space element data.

Each time your CMMGetPS2ColorSpace function calls the ColorSyncDataTransfer function, you pass it the reference constant passed to your function in the reference constant parameter.

SEE ALSO

For information about PostScript operations, see the PostScript Language Manual, second edition.


CMMGetPS2ColorRenderingIntent

Handles the kCMMGetPS2ColorRenderingIntent request by obtaining the rendering intent from the source profile.

A CMM may respond to the kCMMGetPS2ColorRenderingIntent 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 CMGetPS2ColorRenderingIntent 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 kCMMGetPS2ColorRenderingIntent request code by calling a CMM-defined function (for example, CMMGetPS2ColorRenderingIntent ) to handle the request.

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

pascal CMError CMMGetPS2ColorRenderingIntent(
                     ComponentInstance CMSession,
                     CMProfileRef srcProf,
                     unsigned long flags,
                                         CMFlattenUPP proc,
                     void *refCon);
CMSession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
srcProf
A profile reference to the source profile whose header contains the rendering intent.
flags
Reserved for future use.
proc
A pointer to a function supplied by the calling application or device driver. Your CMMGetPS2ColorRenderingIntent function calls this function repeatedly as necessary until you have passed all the source profile's rendering intent data to this function.
refCon
A reference constant, containing data specified by the calling application or device driver, that your CMMGetPS2ColorRenderingIntent function must pass to the ColorSyncDataTransfer function.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Only for special cases should a custom CMM need to support this request code. If your CMM supports this function, your CMMGetPS2ColorRenderingIntent function must obtain the rendering intent from the source profile whose reference is passed to your function in the srcProf parameter. The byte stream containing the rendering intent data that your function passes to the ColorSyncDataTransfer function is used as the operand to the PostScript findRenderingIntent operator.

Your function must allocate a data buffer in which to pass the rendering intent data to the ColorSyncDataTransfer function supplied by the calling application or driver. Your CMMGetPS2ColorRenderingIntent function must call the ColorSyncDataTransfer function repeatedly until you have passed all the data to it.

Here is the prototype for the ColorSyncDataTransfer function pointed to by the proc parameter:

pascal OSErr ColorSyncDataTransfer(
                        long command,
                        long *size,
                        void *data,
                        void *refCon);

Your CMMGetPS2ColorRenderingIntent function communicates with the ColorSyncDataTransfer function using a command parameter to identify the operation to perform. Your function should call the ColorSyncDataTransfer function first with the openWriteSpool command to direct the ColorSyncDataTransfer function to begin the process of writing the profile color-rendering intent element data you pass it in the data buffer. Next, you should call the ColorSyncDataTransfer function with the writeSpool command. After the ColorSyncDataTransfer function returns in the size parameter the amount of data it actually read, you should call the ColorSyncDataTransfer function again with the writeSpool command, repeating this process as often as necessary until all the color-rendering intent data is transferred. After the data is transferred, you should call the ColorSyncDataTransfer function with the closeSpool command.

When your function calls the ColorSyncDataTransfer function, it passes in the data buffer the profile data to transfer to the ColorSyncDataTransfer function and the size in bytes of the buffered data in the size parameter. The ColorSyncDataTransfer function may not always write all the data you pass it in the data buffer. Therefore, on return the ColorSyncDataTransfer function command passes back in the size parameter the number of bytes it actually wrote. Your CMMGetPS2ColorRenderingIntent function keeps track of the number of bytes of remaining color-rendering intent element data.

Each time your CMMGetPS2ColorRenderingIntent function calls the ColorSyncDataTransfer function, you pass it the reference constant passed to your function in the reference constant parameter.

SEE ALSO

For information about PostScript operations, see the PostScript Language Manual, second edition.


CMMGetPS2ColorRendering

Handles the kCMMGetPS2ColorRendering request by obtaining the rendering intent from the header of the source profile.

A CMM may r espond to the kCMMGetPS2ColorRendering 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 CMGetPS2ColorRendering 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 kCMMGetPS2ColorRendering request code by calling a CMM-defined function (for example, CMMGetPS2ColorRendering ) to handle the request.

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

pascal CMError CMMGetPS2ColorRendering(
                     ComponentInstance CMSession,
                                         CMProfileRef srcProf,
                     CMProfileRef dstProf,
                                         unsigned long flags,
                                         CMFlattenUPP proc,
                                         void *refCon);
CMSession
A handle to your CMM's private storage for the instance of your component associated with the calling application or device driver.
srcProf
A profile reference to the source profile whose header indicates the rendering intent for generating the color rendering dictionary (CRD).
dstProf
A profile reference to the destination profile from which you obtain or derive the CRD.
flags
Reserved for future use.
proc
A pointer to a function supplied by the calling application or device driver. Your CMMGetPS2ColorRendering function calls this function repeatedly as necessary until you have passed all the CRD element data to this function.
refCon
A reference constant, containing data specified by the calling application or device driver, that your CMMGetPS2ColorRendering function must pass to the ColorSyncDataTransfer function.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Only for special cases should a custom CMM need to support this request code. If your CMM supports this function, your CMMGetPS2ColorRendering function must obtain the rendering intent from the header of the source profile identified by the srcProf parameter. The rendering intent identifies the color rendering dictionary (CRD) data that you must obtain or derive from the destination profile whose reference is passed to your function in the dstProf parameter. The byte stream containing the specified rendering intent's CRD data that your function passes to the ColorSyncDataTransfer function is used as the operand to the PostScript setColorRendering operator.

A profile may contain tags that specify the CRD data for each rendering intent. A profile's ps2CRD0Tag element data contains the CRD for perceptual rendering. A profile's ps2CRD1Tag contains the CRD for relative colorimetric rendering. A profile's ps2CS2Tag contains the CRD for saturation rendering. A profile's ps2CS3Tag contains the CRD for absolute colorimetric rendering. If the profile does not contain a CRD tag, your CMM should create the CRD from the destination profile using the rendering intent specified by the source profile.

Your function must allocate a data buffer in which to pass the CRD data to the ColorSyncDataTransfer function supplied by the calling application or driver. Your CMMGetPS2ColorRendering function must call the ColorSyncDataTransfer function repeatedly until you have passed all the data to it. Here is the prototype for the ColorSyncDataTransfer function pointed to by the proc parameter:

pascal OSErr ColorSyncDataTransfer(
                        long command,
                        long *size,
                        void *data,
                        void *refCon);

Your CMMGetPS2ColorRendering function communicates with the ColorSyncDataTransfer function using a command parameter to identify the operation to perform. Your function should call the ColorSyncDataTransfer function first with the openWriteSpool command to direct the ColorSyncDataTransfer function to begin the process of writing the profile CRD data you pass it in the data buffer. Next, you should call the ColorSyncDataTransfer function with the writeSpool command. After the ColorSyncDataTransfer function returns in the size parameter the amount of data it actually wrote, you should call the ColorSyncDataTransfer function again with the writeSpool command, repeating this process as often as necessary until all the CRD data is transferred. After the data is transferred, you should call the ColorSyncDataTransfer function with the closeSpool command.

When your function calls the ColorSyncDataTransfer function, it passes in the data buffer the profile data to transfer to the ColorSyncDataTransfer function and the size in bytes of the buffered data in the size parameter. The ColorSyncDataTransfer function may not always write all the data you pass it in the data buffer. Therefore, on return the ColorSyncDataTransfer function command passes back in the size parameter the number of bytes it actually wrote. Your CMMGetPS2ColorRendering function keeps track of the number of bytes of remaining CRD data.

Each time your CMMGetPS2ColorRendering function calls the ColorSyncDataTransfer function, you pass it the reference constant passed to your function in the reference constant parameter.

SEE ALSO

For information about PostScript operations, see the PostScript Language Manual, second edition.


CMMGetPS2ColorRenderingVMSize

Handles the kCMMGetPS2ColorRenderingVMSize request by obtaining the maximum virtual memory (VM) size of the color rendering dictionary (CRD) for the rendering intent specified by the source profile.

A CMM may respond to the kCMMGetPS2ColorRenderingVMSize 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 CMGetPS2ColorRenderingVMSize 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 kCMMGetPS2ColorRenderingVMSize request code by calling a CMM-defined function (for example, CMMGetPS2ColorRenderingVMSize ) to handle the request.

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

pascal CMError CMMGetPS2ColorRenderingVMSize(
                     ComponentInstance CMSession,
                     CMProfileRef srcProf,
                                         CMProfileRef dstProf,
                                         unsigned long vmSize);
CMSession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
srcProf
A profile reference to the source profile specifying the rendering intent to use.
dstProf
A profile reference to the destination printer profile from which you obtain or assess the virtual memory (VM) size of the CRD.
vmSize
The VM size of the CRD, returned by the function.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Only for special cases should a custom CMM need to support this request code. If your CMM supports this function, your CMMGetPS2ColorRenderingVMSize function must obtain the maximum VM size of the CRD for the rendering intent specified by the source profile.

Your function must return the VM size in the vmSize parameter. (In turn, the ColorSync Manager returns the VM size to the calling application or device driver.) The CRD whose maximum size you return must be that of the dictionary for the rendering intent specified by the source profile.

If the destination profile contains the Apple-defined private tag 'psvm' , described later in this section, then your CMM may read the tag and return the CRD VM size data supplied by this tag for the specified rendering intent. If the destination profile does not contain this tag, then you must assess the VM size of the CRD. In this case, the assessment may be larger than the actual maximum VM size.

The CMPS2CRDVMSizeType data type defines the Apple-defined 'psvm' optional tag that a profile may contain to identify the maximum VM size of a CRD for different rendering intents. This tag's element data includes an array containing one entry for each rendering intent and its virtual memory size.

The CMIntentCRDVMSize data type defines the rendering intent and its maximum VM size:

struct CMIntentCRDVMSize {
    long            rendering   Intent;
    unsigned long   VMSize;
};

For example, a rendering intent might be 0 and its VM size 120 KB.

Constant descriptions

renderingIntent
The rendering intent whose CRD VM size you want to obtain. Rendering intent values are

0 ( cmPerceptual ) 1 ( cmRelativeColorimetric ) 2 ( cmSaturation ) 3 ( cmAbsoluteColorimetric )

VMSize
The VM size of the CRD for the rendering intent specified for the renderingIntent field.

The CMPS2CRDVMSizeType data type for the tag includes an array containing one or more members of type CMIntentCRDVMSize:

struct CMPS2CRDVMSizeType {
    OSType typeDescriptor;
    unsigned long reserved;
    unsigned long count;
    CMIntentCRDVMSize intentCRD[1];
};

Constant descriptions

typeDescriptor
The 'psvm' tag signature.
reserved
Reserved for future use.
count
The number of entries in the intentCRD array.
intentCRD
A variable-sized array of four or more members defined by the CMIntentCRDSize data type.

CMMFlattenProfile

Changed in ColorSync 2.5

Handles the kCMMFlattenProfile request by extracting profile data from the profile to flatten and passing it to the specified function.

A CMM may respond to the kCMMFlattenProfile request code, but it is not required to do so. Most CMMs can rely on the default CMM to handle this request code adequately. The ColorSync Manager sends this request code to your CMM on behalf of an application or device driver that called the CMFlattenProfile function. The ColorSync Manager dispatches this request to the Component Manager, which calls your CMM to service the request. A CMM that handles the kCMMFlattenProfile request code typically responds by calling a CMM-defined function (for example, CMMFlattenProfile ).

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

pascal CMError CMMFlattenProfile (
                     ComponentInstance CMSession,
                                         CMProfileRef prof,
                     unsigned long flags,
                     CMFlattenUPP proc,
                     void *refCon);
CMSession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
prof
A reference to the profile to flatten.
flags
Reserved for future use.
proc
A pointer to the ColorSyncDataTransfer function supplied by the calling application or device driver to perform the low-level data transfer. Your CMMFlattenProfile function calls this function repeatedly as necessary until all the profile data is transferred.
refCon
A reference constant containing data specified by the calling application or device driver.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Only in rare circumstances should a custom CMM need to support this request code. The process of flattening a profile is complex, and the default CMM handles this process adequately for most cases. A custom CMM might respond to this request code if the CMM provides special services such as profile data encryption or compression, for example. Read the rest of this description if your CMM handles this request code.

Your CMMFlattenProfile function must extract the profile data from the profile to flatten, identified by the prof parameter, and pass the profile data to the function specified in the proc parameter.

Your CMMFlattenProfile function calls the ColorSyncDataTransfer function supplied by the calling application. Here is the prototype for the ColorSyncDataTransfer function pointed to by the proc parameter:

pascal OSErr ColorSyncDataTransfer(
                        long command,
                        long *size,
                        void *data,
                        void *refCon);

Your CMMFlattenProfile function communicates with the ColorSyncDataTransfer function using a command parameter to identify the operation to perform. Your function should call the ColorSyncDataTransfer function first with the openWriteSpool command to direct the ColorSyncDataTransfer function to begin the process of writing the profile data you pass it in the data buffer. Next, you should call the ColorSyncDataTransfer function with the writeSpool command. After the ColorSyncDataTransfer function returns in the size parameter the amount of data it actually wrote, you should call the ColorSyncDataTransfer function again with the writeSpool command, repeating this process as often as necessary until all the profile data is transferred. After the data is transferred, you should call the ColorSyncDataTransfer function with the closeSpool command.

When your function calls the ColorSyncDataTransfer function, it passes in the data buffer the profile data to transfer to the ColorSyncDataTransfer function and the size in bytes of the buffered data in the size parameter. The ColorSyncDataTransfer function may not always write all the data you pass it in the data buffer. Therefore, on return the ColorSyncDataTransfer function command passes back in the size parameter the number of bytes it actually wrote. Your function keeps track of the number of bytes of remaining profile data.

Your CMMFlattenProfile function is responsible for obtaining the profile data from the profile, allocating a buffer in which to pass the data to the ColorSyncDataTransfer function, and keeping track of the amount of remaining data to transfer to the ColorSyncDataTransfer function.

Each time your CMMFlattenProfile function calls the ColorSyncDataTransfer function, you pass it the reference constant passed to your function in the reference constant parameter.

VERSION NOTES

Starting with ColorSync version 2.5, the ColorSync Manager calls the function provided by the calling program directly, without going through the preferred, or any, CMM. Your CMM only needs to handle the kCMMFlattenProfile request code for versions of ColorSync prior to version 2.5.


CMMUnflattenProfile

Changed in ColorSync 2.5

Handles the kCMMUnflattenProfile request by creating a uniquely-named file in the temporary items folder to store the profile data.

A CMM may respond to the kCMMUnflattenProfile request code, but it is not required to do so. Most CMMs can rely on the default CMM to handle this request code adequately. The ColorSync Manager sends this request code to your CMM on behalf of an application or device driver that called the CMUnflattenProfile function. The ColorSync Manager dispatches this request to the Component Manager, which calls your CMM to service the request. A CMM that handles the kCMMUnflattenProfile request code typically responds by calling a CMM-defined function (for example, CMMUnflattenProfile ).

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

pascal CMError CMMUnflattenProfile (
                     ComponentInstance CMSession,
                                         FSSpec *resultFileSpec,
                                         CMFlattenUPP proc,
                                         void *refCon);
CMSession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
resultFileSpec
A pointer to a file specification for the profile file. This is a temporary file specification. You must create this temporary file, which is returned to the calling application or device driver. The calling application or driver is responsible for disposing of the file when finished with it.
proc
A pointer to a function supplied by the calling application or device driver to perform the low-level data transfer. Your CMMFlattenProfile function calls this function repeatedly as necessary until all the profile data is transferred.
refCon
A reference constant containing data specified by the calling application program.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Only in rare circumstances should a custom CMM need to support this request code. The process of unflattening a profile is complex, and the default CMM handles this process adequately for most cases. A custom CMM might respond to this request code if the CMM provides special services such as profile data encryption or compression, for example. Read the rest of this description if your CMM handles this request code.

Your CMMUnflattenProfile function must create a file with a unique name in which to store the profile data. (You should create this file in the temporary items folder.) The ColorSync Manager returns the temporary file specification to the calling application or device driver.

To obtain the profile data, your CMMUnflattenProfile function calls the ColorSyncDataTransfer function supplied by the calling application or device driver. Here is the prototype for the ColorSyncDataTransfer function pointed to by the proc parameter:

pascal OSErr ColorSyncDataTransfer (
                        long command,
                        long *size,
                        void *data,
                        void *refCon);

Before calling the ColorSyncDataTransfer function, your CMMUnflattenProfile function must allocate a buffer to hold the profile data returned to you from the ColorSyncDataTransfer function in the data parameter.

Your CMMUnflattenProfile function communicates with the ColorSyncDataTransfer function using a command parameter to identify the operation to perform. Your function should call the ColorSyncDataTransfer function first with the openReadSpool command to direct the ColorSyncDataTransfer function to begin the process of transferring data. Following this, you should call the ColorSyncDataTransfer function with the readSpool command as often as necessary until the ColorSyncDataTransfer function has passed your function all the profile data from the graphics file. After you have received all the profile data, your function should call the ColorSyncDataTransfer function with the closeSpool command.

Each time you call the ColorSyncDataTransfer function, you should pass it a pointer to the data buffer you created, the size in bytes of the profile data to return to you in the buffer, and the reference constant passed to you from the calling application.

On return, the ColorSyncDataTransfer function passes to you the profile data that your function must write to the temporary file that you created for the new profile file. The ColorSyncDataTransfer function will not always transfer the number of bytes of profile data you requested. Therefore, the ColorSyncDataTransfer function returns in the size parameter the number of bytes of profile data it actually returned in the data buffer.

The profile file you create is returned to the calling application or device driver in the resultFileSpec parameter. Your CMMUnflattenProfile function must identify the profile size and maintain a counter tracking the amount of data transferred to you and the amount of remaining data to determine when to call the ColorSyncDataTransfer function with the closeSpool command. To determine the profile size, your function can obtain the profile header, which specifies the size.

The calling application or device driver uses the reference constant to pass to the ColorSyncDataTransfer function information the ColorSyncDataTransfer function requires to transfer the data.

VERSION NOTES

Starting with ColorSync version 2.5, the ColorSync Manager calls the function provided by the calling program directly, without going through the preferred, or any, CMM. Your CMM only needs to handle the kCMMUnflattenProfile request code for versions of ColorSync prior to version 2.5.


CMMGetNamedColorInfo

Handles the kCMMGetNamedColorInfo request by returning information about a named color space from its profile reference.

A CMM may respond to the kCMMGetNamedColorInfo request code, but it is not required to do so. Most CMMs can rely on the default CMM to handle this request code adequately. The ColorSync Manager sends this request code to your CMM on behalf of an application or device driver that called the CMMGetNamedColorInfo function. The ColorSync Manager dispatches this request to the Component Manager, which calls your CMM to service the request. A CMM that handles the kCMMGetNamedColorInfo request code typically responds by calling a CMM-defined function (for example, CMMGetNamedColorInfo ).

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

pascal CMError CMMGetNamedColorInfo(
                     ComponentInstance CMSession,
                     CMProfileRef srcProf,
                     unsigned long *deviceChannels,
                     OSType *deviceColorSpace,
                     OSType *PCSColorSpace,
                     unsigned long *count,
                     StringPtr prefix,
                     StringPtr suffix)
CMSession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
srcProf
A profile reference to a named color space profile to supply information about.
deviceChannels
A pointer to a count of device channels. On output, the number of device channels in the color space for the profile. It should agree with the "data color space" field in the profile header. For example, Pantone maps to CMYK, a 4-channel color space. A value of 0 indicates no device channels were available.
deviceColorSpace
A pointer to a device color space. On output, specifies a device color space, such as CMYK, for the srcProf profile.
PCSColorSpace
A pointer to a profile connection space color space. On output, specifies an interchange color space, such as Lab, for the srcProf profile.
count
A pointer to a named color count. On output, the number of named colors in the srcProf profile.
prefix
A pointer to a Pascal string. On output, the string contains a prefix, such as "Pantone", for each color name. The prefix identifies the named color system described by the srcProf profile.
suffix
A pointer to a Pascal string. On output, the string contains a suffix, such as "CVC", for each color name.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

The CMMGetNamedColorInfo function returns information about the named color space referred to by the passed profile reference.


CMMGetNamedColorValue

Handles the kCMMGetNamedColorValue request by returning device and PCS color values from a named color space profile for a specific color name.

A CMM may respond to the kCMMGetNamedColorValue request code, but it is not required to do so. Most CMMs can rely on the default CMM to handle this request code adequately. The ColorSync Manager sends this request code to your CMM on behalf of an application or device driver that called the CMMGetNamedColorValue function. The ColorSync Manager dispatches this request to the Component Manager, which calls your CMM to service the request. A CMM that handles the kCMMGetNamedColorValue request code typically responds by calling a CMM-defined function (for example, CMMGetNamedColorValue ).

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

pascal CMError CMMGetNamedColorValue(
                     ComponentInstance CMSession,
                     CMProfileRef prof,
                     StringPtr name,
                     CMColor *deviceColor,
                     CMColor *PCSColor)
CMSession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
prof
A profile reference of type CMProfileRef that identifies the named color space profile to extract named color information from.
name
A pointer to a Pascal color name string that identifies the named color to return color values for.
deviceColor
A pointer to a device color. On output, a device color value in CMColor union format. If the profile does not contain device values, deviceColor is undefined.
PCSColor
A pointer to a profile connection space color. On output, an interchange color value in CMColor union format.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Based on the passed color name, the CMMGetNamedColorValue function does a lookup into the named color tag in the profile whose reference is passed in the prof parameter and, if the name is found in the tag, returns device and PCS color values. Otherwise, CMMGetNamedColorValue returns an error code.


CMMGetIndNamedColorValue

Handles the kCMMGetIndNamedColorValue request by returning device and PCS color values from a named color space profile for a specific named color index.

A CMM may respond to the kCMMGetIndNamedColorValue request code, but it is not required to do so. Most CMMs can rely on the default CMM to handle this request code adequately. The ColorSync Manager sends this request code to your CMM on behalf of an application or device driver that called the CMGetIndNamedColorValue function. The ColorSync Manager dispatches this request to the Component Manager, which calls your CMM to service the request. A CMM that handles the kCMMGetIndNamedColorValue request code typically responds by calling a CMM-defined function (for example, CMMGetIndNamedColorValue ).

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

pascal CMError CMMGetIndNamedColorValue(
                     ComponentInstance CMSession,
                     CMProfileRef prof,
                     unsigned long index,
                     CMColor *deviceColor,
                     CMColor *PCSColor)
CMSession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
prof
A profile reference of type CMProfileRef to a named color space profile.
index
An index value for the named color to get color values for.
deviceColor
A pointer to a device color. On output, a device color value in CMColor union format. If the profile does not contain device values, deviceColor is undefined.
PCSColor
A pointer to a profile connection space color. On output, an interchange color value in CMColor union format.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Based on the passed named color index, the CMMGetIndNamedColorValue function does a lookup into the named color tag of the profile whose reference is passed in the prof parameter and returns device and PCS color values. If the index is greater than the number of named colors, CMMGetIndNamedColorValue returns an error code.


CMMGetNamedColorIndex

Handles the kCMMGetNamedColorIndex request by returning a named color index from a named color space profile for a specific color name.

A CMM may respond to the kCMMGetNamedColorIndex request code, but it is not required to do so. Most CMMs can rely on the default CMM to handle this request code adequately. The ColorSync Manager sends this request code to your CMM on behalf of an application or device driver that called the CMMGetNamedColorIndex function. The ColorSync Manager dispatches this request to the Component Manager, which calls your CMM to service the request. A CMM that handles the kCMMGetNamedColorIndex request code typically responds by calling a CMM-defined function (for example, CMMGetNamedColorIndex ).

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

pascal CMError CMMGetNamedColorIndex(
                     ComponentInstance CMSession,
                     CMProfileRef prof,
                     StringPtr name,
                     unsigned long *index)
CMSession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
prof
A profile reference of type CMProfileRef to a named color space profile.
name
A pointer to a Pascal color name string that identifies the named color to return the index value for.
index
A pointer to a value of type unsigned long . On output, it specifies the index value for the named color specified by name .
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Based on the passed color name, the CMMGetNamedColorIndex function does a lookup into the named color tag of the profile whose reference is passed in the prof parameter and, if the name is found in the tag, returns the index. Otherwise, CMMGetNamedColorIndex returns an error code.


CMMGetNamedColorName

Handles the kCMMGetNamedColorName request by returning a named color name from a named color space profile for a specific named color index.

A CMM may respond to the kCMMGetNamedColorName request code, but it is not required to do so. Most CMMs can rely on the default CMM to handle this request code adequately. The ColorSync Manager sends this request code to your CMM on behalf of an application or device driver that called the CMMGetNamedColorName function. The ColorSync Manager dispatches this request to the Component Manager, which calls your CMM to service the request. A CMM that handles the kCMMGetNamedColorName request code typically responds by calling a CMM-defined function (for example, CMMGetNamedColorName ).

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

pascal CMError CMMGetNamedColorName(
                     ComponentInstance CMSession,
                     CMProfileRef prof,
                     unsigned long index,
                     StringPtr name)
CMSession
A handle to your CMM's storage for the instance of your component associated with the calling application or device driver.
prof
A profile reference to a named color space profile.
index
An index value for a named color.
name
A pointer to a Pascal color name string. On output, it identifies the named color specified by index .
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Based on the passed color name index, the CMMGetNamedColorName function does a lookup into the named color tag of the profile whose reference is passed in the prof parameter and returns the name. If the index is greater than the number of named colors, CMMGetNamedColorName returns an error code.


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