Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

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

/

MyCMMFlattenProfile

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 Apple 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, MyCMMFlattenProfile).

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

pascal CMError MyCMMFlattenProfile (
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 MyColorSyncDataTransfer function supplied by the calling application or device driver to perform the low-level data transfer. Your MyCMMFlattenProfile 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. See "Result Codes" (page 3-172) for a list of ColorSync-specific result codes.

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 Apple 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 MyCMMFlattenProfile 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 MyCMMFlattenProfile function calls the MyColorSyncDataTransfer function supplied by the calling application. Here is the prototype for the MyColorSyncDataTransfer function pointed to by the proc parameter:

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

Your MyCMMFlattenProfile function communicates with the MyColorSyncDataTransfer function using a command parameter to identify the operation to perform. Your function should call the MyColorSyncDataTransfer function first with the openWriteSpool command to direct the MyColorSyncDataTransfer function to begin the process of writing the profile data you pass it in the data buffer. Next, you should call the MyColorSyncDataTransfer function with the writeSpool command. After the MyColorSyncDataTransfer function returns in the size parameter the amount of data it actually wrote, you should call the MyColorSyncDataTransfer 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 MyColorSyncDataTransfer function with the closeSpool command.

When your function calls the MyColorSyncDataTransfer function, it passes in the data buffer the profile data to transfer to the MyColorSyncDataTransfer function and the size in bytes of the buffered data in the size parameter. The MyColorSyncDataTransfer function may not always write all the data you pass it in the data buffer. Therefore, on return the MyColorSyncDataTransfer 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 MyCMMFlattenProfile function is responsible for obtaining the profile data from the profile, allocating a buffer in which to pass the data to the MyColorSyncDataTransfer function, and keeping track of the amount of remaining data to transfer to the MyColorSyncDataTransfer function.

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