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

Managing Color With ColorSync


Responding to ColorSync Manager Optional Request Codes

This section describes some of the processes your CMM can perform in response to the optional ColorSync Manager requests if your CMM supports them. Before the Component Manager calls your CMM with any of these requests, it first calls your CMM with a can do request to determine if you support the specific optional request code. This section includes the following:

Validating That a Profile Meets the Base Content Requirements

When a C olorSync-supportive application or device-driver calls the CMValidateProfile function for your CMM to handle, the Component Manager calls your CMM with the what field of the ComponentParameters data structure set to kCMMValidateProfile if your CMM supports the request.

In response to this request code, your CMM should call its CMMValidateProfile subroutine. One way to do this, for example, is by calling the Component Manager's CallComponentFunction function, passing it the ComponentParameters data structure and the address of your CMMValidateProfile subroutine. To handle this request, you don't need private storage for ColorSync profile information, because the profile reference is passed to your function. However, if your CMM uses private storage for other purposes, you should call the Component Manager's CallComponentFunctionWithStorage function. For a description of the function prototype to which your subroutine must adhere, see CMMValidateProfile .

The CallComponentFunction function passes to your CMMValidateProfile subroutine a reference to the profile whose contents you must check and a flag whose value you must set to report the results.

To handle this request, your CMM should test the profile contents against the baseline profile elements requirements for a profile of this type as specified by the International Color Consortium. It should determine if the profile contains the minimum set of elements required for its type and set the response flag to true if the profile contains the required elements and false if it doesn't.

To obtain a copy of the International Color Consortium Profile Format Specification, version 2.x, visit the ICC Web site at http://www.color.org .

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.

If your CMM is dependent on optional or private tags, your CMMValidateProfile function should check for the existence of these tags also.

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 the default CMM and have it perform the minimum defaults requirements validation.

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

Matching the Colors of a Bitmap

Whe n a C olorSync-supportive application or device driver calls the CWMatchBitMap function for your CMM to handle, the Component Manager calls your CMM with the what field of the ComponentParameters data structure set to kCMMMatchBitmap if your CMM supports the request. If your CMM supports this request code, your CMM should be prepared to receive any of the bitmap types defined by the ColorSync Manager.

In response to this request code, your CMM should call its CMMatchBitmap subroutine. For example, to do this, your CMM may call the Component Manager's CallComponentFunctionWithStorage function, passing it the storage handle for this component instance, the ComponentParameters data structure, and the address of your CMMatchBitmap subroutine. For a description of the function prototype to which your subroutine must adhere, see CMMatchBitmap .

In addition to the storage handle for private storage for this component instance, the CallComponentFunctionWithStorage function passes to your CMMatchBitmap subroutine a pointer to the bitmap containing the source image data whose colors your function must match, a pointer to a callback function supplied by the calling program, a reference constant your subroutine must pass to the callback function when you invoke it, and a pointer to a bitmap in which your function stores the resulting color-matched image.

The callback function supplied by the calling function monitors the color-matching progress as your function matches the bitmap colors. You should call this function at regular intervals. 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.

To handle this request, your CMMatchBitmap function must match the colors of the source image bitmap to the color gamut of the destination profile using the profiles specified by a previous kNCMInit , kCMMInit , or kCMMConcatInit request to your CMM for this component instance. You must store the color-matched image in the bitmap result parameter passed to your subroutine. If you are passed a NULL parameter, you must match the bitmap in place.

For a description of the prototype of the callback function supplied by the calling program, see MyCMBitmapCallBackProc.

Checking the Colors of a Bitmap

When a ColorSync-supportive application or device driver calls the CWCheckBitMap function for your CMM to handle, the Component Manager calls your CMM with the what field of the ComponentParameters data structure set to kCMMCheckBitmap if your CMM supports the request. If your CMM supports this request code, your CMM should be prepared to receive any of the bitmap types defined by the ColorSync Manager.

In response to this request code, your CMM should call its CMCheckBitmap subroutine. For example, to do this, your CMM may call the Component Manager's CallComponentFunctionWithStorage function, passing it the storage handle for this component instance, the ComponentParameters data structure, and the address of your CMCheckBitmap subroutine. For a description of the function prototype to which your subroutine must adhere, see MyCMBitmapCallBackProc.

In addition to the storage handle for private storage for this component instance, the CallComponentFunctionWithStorage function passes to your CMCheckBitmap subroutine a pointer to the bitmap containing the source image data whose colors your function must check, a pointer to a callback progress-reporting function supplied by the calling program, a reference constant your subroutine must pass to the callback function when you invoke it, and a pointer to a resulting bitmap whose pixels your subroutine must set to show if the corresponding source color is in or out of gamut. A black pixel (value 1) in the returned bitmap indicates an out-of-gamut color, while a white pixel (value 0) indicates the color is in gamut.

The callback function supplied by the calling function monitors the color gamut-checking progress. You should call this function at regular intervals. Your CMCheckBitmap function should monitor the progress function for a returned value of true , which indicates that the user interrupted the color gamut-checking process. In this case, you should terminate the process.

For a description of the prototype of the callback function supplied by the calling program, see MyCMBitmapCallBackProc.

Using the content of the profiles that you stored at initialization time for this component instance, your CMCheckBitmap subroutine must check the colors of the source image bitmap against the color gamut of the destination profile. If a pixel is out of gamut, your function must set the corresponding pixel in the result image bitmap to 1. The ColorSync Manager returns the resulting bitmap to the calling application or driver to report the outcome of the check.

For complete details on the CMCheckBitmap subroutine parameters and how your CMCheckBitmap subroutine communicates with the callback function, see MyCMBitmapCallBackProc.

Matching the Colors of a Pixel Map Image

When a ColorSync -supportive application or device driver calls the CWMatchPixMap function for your CMM to handle, the Component Manager calls your CMM with the what field of the ComponentParameters data structure set to kCMMMatchPixMap if your CMM supports the request. If your CMM supports this request code, your CMMatchPixMap function should be prepared to receive any of the pixel map types defined by QuickDraw.

In response to this request code, your CMM should call its CMMatchPixMap subroutine. For example, to do this, your CMM may call the Component Manager's CallComponentFunctionWithStorage function, passing it the storage handle for this component instance, the ComponentParameters data structure, and the address of your CMMatchPixMap subroutine. For a description of the function prototype to which your subroutine must adhere, see CMMatchPixMap .

In addition to the storage handle for private storage for this component instance, the CallComponentFunctionWithStorage function passes to your CMMatchPixMap subroutine a pointer to the pixel map containing the source image to match, a pointer to a callback progress-reporting function supplied by the calling program, and a reference constant your subroutine must pass to the callback function when you invoke it.

To handle this request, your CMMatchPixMap subroutine must match the colors of the source pixel map image to the color gamut of the destination profile, replacing the original pixel colors of the source image with their corresponding colors expressed in the data color space of the destination profile. The ColorSync Manager returns the resulting color-matched pixel map to the calling application or driver.

The callback function supplied by the calling function monitors the color-matching progress. You should call this function at regular intervals. 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 process.

For a description of the prototype of the callback function supplied by the calling program, see MyCMBitmapCallBackProc.

Checking the Colors of a Pixel Map Image

When a ColorSync-supportive application or device-driver calls the CWCheckPixMap function f or your CMM to handle, the Component Manager calls your CMM with the what field of the ComponentParameters data stru cture set to kCMMCheckPixMap if your CMM supports the request.

In response to this request code, your CMM should call its CMCheckPixMap subroutine. For example, to do this, your CMM may call the Component Manager's CallComponentFunctionWithStorage function, passing it the storage handle for this component instance, the ComponentParameters data structure, and the address of your CMCheckPixMap subroutine. For a description of the function prototype to which your subroutine must adhere, see CMCheckPixMap .

In addition to the storage handle for private storage for this component instance, the CallComponentFunctionWithStorage function passes to your CMCheckPixMap subroutine a pointer to the pixel map containing the source image to check, a QuickDraw bitmap in which to report the color gamut-checking results, a pointer to a callback progress-reporting function supplied by the calling program, and a reference constant your subroutine must pass to the callback function when you invoke it.

Using the content of the profiles passed to you at initialization time, your CMCheckPixMap subroutine must check the colors of the source pixel map image against the color gamut of the destination profile to determine if the pixel colors are within the gamut. If a pixel is out of gamut, your subroutine must set to 1 the corresponding pixel of the result bitmap. The ColorSync Manager returns the bitmap showing the color gamut-checking results to the calling application or device driver.

Initializing the Component Instance for a Session Using Concatenated Profiles

When a ColorSync-supportive application or device driver calls the CWConcatColorWorld function for your CMM to handle, the Component Manager calls your CMM with the what field of the ComponentParameters data structure set to kCMMConcatInit if your CMM supports the request.

In response to this request code, your CMM should call its CMConcatInit subroutine. For example, to do this, your CMM may call the Component Manager's CallComponentFunctionWithStorage function, passing it the storage handle for this component instance, the ComponentParameters data structure, and the address of your CMConcatInit subroutine. For a description of the function prototype to which your subroutine must adhere, see CMConcatInit .

In addition to the storage handle for private storage for this component instance, the CallComponentFunctionWithStorage function passes to your CMConcatInit subroutine a pointer to a data structure of type CMConcatProfileSet containing an array of profiles to use in a subsequent color-matching or color gamut-checking session. The profiles in the array are in processing order--source through destination. The profileSet field of the data structure contains the array. If the profile array contains only one profile, that profile is a device link profile. For a description of the CMConcatProfileSet data structure, see CMConcatProfileSet .

Using the storage passed to your entry point function in the CMSession parameter, your CMConcatInit function should initialize any private data your CMM will need for a subsequent color session involving the set of profiles. Before your function returns control to the Component Manager, your subroutine should store any profile information it requires. In addition to the standard profile information, you should store the profile header's quality flags setting, the profile size, and the rendering intent. After you return control to the Component Manager, you cannot use the profile references again.

A color-matching or color gamut-checking session for a set of profiles entails various color transformations among devices in a sequence for which your CMM is responsible. Your CMM may use Component Manager functions to call other CMMs if necessary.

There are special guidelines your CMM must follow in using a set of concatenated profiles for subsequent color-matching or gamut-checking sessions. These guidelines are described in CMConcatInit .

Creating a Device Link Profile and Opening a Reference to It

When a ColorSync-supportive application or device driver calls the CWNewLinkProfile function for your CMM to handle, the Component Manager calls your CMM with the what field of the ComponentParameters data structure set to kCMMNewLinkProfile if your CMM supports the request.

In response to this request code, your CMM should call its CMNewLinkProfile subroutine. For example, to do this, your CMM may call the Component Manager's CallComponentFunctionWithStorage function, passing it the storage handle for this component instance, the ComponentParameters data structure, and the address of your CMNewLinkProfile subroutine. For a description of the function prototype to which your subroutine must adhere, see CMNewLinkProfile .

In addition to the storage handle for private storage for this component instance, the CallComponentFunctionWithStorage function passes to your CMNewLinkProfile subroutine a pointer to a data structure of type CMConcatProfileSet containing the array of profiles that will make up the device link profile.

To handle this request, your subroutine 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. Your CMM must create a file specification for the device link profile. A device link profile cannot be a temporary profile: that is, you cannot specify a location type of cmNoProfileBase for a device link profile. For information on how to specify the file location, see Profile Location Type .

The profiles in the array are in the processing order--source through destination--which you must preserve. After your CMM creates the device link profile, it must open a reference to the profile and return the profile reference along with the location specification.

Obtaining PostScript-Related Data From a Profile

There are three very similar PostScript-related request codes that your CMM may support. Each of the se codes requests that your CMM obtain or derive information required by a PostScript printer from the specified profile and pass that information to a function supplied by the calling program.

When a ColorSync-supportive application or device driver calls the high-level function corresponding to the request code and your CMM is specified to handle it, the Component Manager calls your CMM with the what field of the ComponentParameters data structure set to the corresponding request code if your CMM supports it. Here are the three high-level functions and their corresponding request codes:

In response to each of these request codes, your CMM should call its subroutine that handles the request. For example, to do this, your CMM may call the Component Manager's CallComponentFunctionWithStorage function, passing it the storage handle for this component instance, the ComponentParameters data structure, and the address of your subroutine handler.

For a description of the function prototypes to which your subroutine must adhere for each of these requests, see ColorSync Reference for Color Management Modules .

In addition to the storage handle for private storage for this component instance, the CallComponentFunctionWithStorage function passes to your subroutine a reference to the source profile containing the data you must obtain or derive, a pointer to the function supplied by the calling program, and a reference constant that you must pass to the supplied function each time your CMM calls it. For kCMMGetPS2ColorRendering , your CMM is also passed a reference to the destination profile.

To handle each of these requests, your subroutine must allocate a data buffer in which to pass the particular PostScript-related data to the function supplied by the calling application or driver. Your subroutine must call the supplied function repeatedly until you have passed all the data to it. For a description of the prototype of the application or driver-supplied function, see MyColorSyncDataTransfer .

For a description of how each of your subroutines must interact with the calling program's supplied function, see the descriptions of the prototypes for the subroutines in Application-Defined Functions for the ColorSync Manager .

Obtaining the Size of the Color Rendering Dictionary for PostScript Printers

When a ColorSync-supportive application or device driver calls the CMGetPS2ColorRenderingVMSize function for your CMM to handle, the Component Manager calls your CMM with the what field of the ComponentParameters data structure set to kCMMGetPS2ColorRenderingVMSize if your CMM supports the request.

In response to this request code, your CMM should call its CMMGetPS2ColorRenderingVMSize subroutine. For example, to do this, your CMM may call the Component Manager's CallComponentFunctionWithStorage function, passing it the storage handle for this component instance, the ComponentParameters data structure, and the address of your CMMGetPS2ColorRenderingVMSize subroutine. For a description of the function prototype to which your subroutine must adhere, see ColorSync Reference for Color Management Modules .

In addition to the storage handle for global data for this component instance, the CallComponentFunctionWithStorage function passes to your CMMGetPS2ColorRenderingVMSize subroutine a reference to the source profile identifying the rendering intent and a reference to the destination profile containing the color rendering dictionary (CRD) for the specified rendering intent.

To handle this request, your CMM must obtain or assess and return the maximum VM size for the CRD of the specified rendering intent.

If the destination profile contains the Apple-defined private tag 'psvm' , described in the next paragraph, 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.

The CMPS2CRDVMSizeType data type defines the Apple-defined 'psvm' optional tag that a printer 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. For a description of the data structures that define the tag's element data, see Color Rendering Dictionary Virtual Memory Size .

Flattening a Profile for Embedding in a Graphics File

Flattening refers to transferring a profile stored in an independent disk file to an external profile format that can be embedded in a graphics document. Unflattening refers to transferring from the embedded format to an independent disk file.

Starting With ColorSync 2.5

Starting with ColorSync version 2.5, when a ColorSync-supportive application or device driver calls the CMFlattenProfile function, the ColorSync Manager calls the flatten function provided by the calling program or driver directly, without going through the preferred, or any, CMM.

Prior to ColorSync 2.5

Prior to ColorSync version 2.5, when a ColorSync-supportive application or device driver calls the CMFlattenProfile function for your CMM to handle, the Component Manager calls your CMM with the what field of the ComponentParameters data structure set to kCMMFlattenProfile if your CMM supports the request.

In response to this request code, your CMM should call its CMMFlattenProfile subroutine. For example, to do this, your CMM may call the Component Manager's CallComponentFunctionWithStorage function, passing it the storage handle for this component instance, the ComponentParameters data structure, and the address of your CMMFlattenProfile subroutine. For a description of the function prototype to which your subroutine must adhere, see CMMFlattenProfile .

In addition to the storage handle for private storage for this component instance, the CallComponentFunctionWithStorage function passes to your CMMFlattenProfile subroutine a reference to the profile to be flattened, a pointer to a function supplied by the calling program, and a reference constant your subroutine must pass to the calling program's function when you invoke it.

To handle this request, your subroutine must extract the profile data from the profile, allocate a buffer in which to pass the profile data to the supplied function, and pass the profile data to the function, keeping track of the amount of data remaining to pass.

For a description of the prototype of the function supplied by the calling program, see MyColorSyncDataTransfer . See also CMMFlattenProfile for details on how your CMMFlattenProfile subroutine communicates with the function supplied by the calling program.

Unflattening a Profile

Unflattening refers to transferring from the embedded format to an independent disk file. Flattening refers to transferring a profile stored in an independent disk file to an external profile format that can be embedded in a graphics document.

Starting With ColorSync 2.5

Starting with ColorSync version 2.5, when a ColorSync-supportive application or device driver calls the CMUnflattenProfile function, the ColorSync Manager calls the unflatten function provided by the calling program or driver directly, without going through the preferred, or any, CMM.

Prior to ColorSync 2.5

Prior to ColorSync version 2.5, when a ColorSync-supportive application or device driver calls the CMUnflattenProfile function, the Component Manager calls your CMM with the what field of the ComponentParameters data structure set to kCMMUnflattenProfile , if your CMM supports that request code.

In re sponse to the kCMMUnflattenProfile request code, your CMM should call its CMMUnflattenProfile function. To do this, your CMM can call the Component Manager's CallComponentFunctionWithStorage function, passing it the storage handle for this component instance, the ComponentParameters data structure, and the address of your CMMUnflattenProfile function. For more information, see CMMUnflattenProfile .

In addition to the storage handle for private storage for this component instance, the CallComponentFunctionWithStorage function passes to your CMMUnflattenProfile function a pointer to a function supplied by the calling program and a reference constant. Your function passes the reference constant to the calling program's function when you invoke it. The calling program's function obtains the profile data and returns it to your subroutine. For a more information on the data transfer function, see MyColorSyncDataTransfer .

To handle this request, your subroutine must create a file in which to store the profile data. You should create the file in the temporary items folder. Your CMMUnflattenProfile subroutine must call the supplied ColorSyncDataTransfer function repeatedly to obtain the profile data. Before calling the ColorSyncDataTransfer function, your CMMUnflattenProfile function must allocate a buffer to hold the returned profile data.

Your CMMUnflattenProfile function must identify the profile size and maintain a counter to track the amount of data transferred and the amount of data remaining. This information allows you to determine when to call the ColorSyncDataTransfer function for the final time.

Supplying Named Color Space Information

When a ColorSync-supportive application or device driver calls the CMGetNamedColorInfo function for your CMM to handle, the Component Manager calls your CMM with the what field of the ComponentParameters data structure set to kCMMGetNamedColorInfo if your CMM supports the request.

In response to this request code, your CMM should call its CMMGetNamedColorInfo subroutine. To do this, your CMM might call the Component Manager's CallComponentFunctionWithStorage function, passing it the storage handle for this component instance, the ComponentParameters data structure, and the address of your CMMGetNamedColorInfo subroutine.

The CMMGetNamedColorInfo function returns information about a named color space from its profile reference. For a description of the function prototype to which your subroutine must adhere, see CMMGetNamedColorInfo .

A named color profile has a value of 'nmcl' in the Profile/Device class field of its header. If the source profile passed to your CMMGetNamedColorInfo subroutine is a named color profile, you can extract the necessary information to return in the parameters of the CMMGetNamedColorInfo routine.

Your CMM can obtain named color information as well as profile header information by reading the namedColor2Tag tag (signature 'ncl2' ). This tag's element data includes a count of named colors, the number of device channels, and a prefix and suffix for each named color name. The data also includes the named color names themselves, along with profile connection space (PCS) and device color information for each named color. For information on the format of the namedColor2Tag tag, see the International Color Consortium Profile Format Specification.

Your CMM responds similarly for other named color requests:


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