![]() |
CMMatchPixMap |
||||
Header: | CMMComponent.h | Carbon status: | Unsupported | |
Handles the kCMMMatchPixMap request by matching the colors of the specified pixel map image to the destination profiles color gamut.
CMMatchPixMap ();
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.
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 profiles color gamut, replacing the original pixel colors with their corresponding colors as specified in the data color space of the destination devices 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 CMMs private storage for the calling applications 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.
Each time your CMMatchPixMap function calls the CMBitmapCallBackProcPtr 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 CMBitmapCallBackProcPtr 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 CMBitmapCallBackProcPtr 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.
CMMatchPixMap is an API to CMMs. Use CWMatchPixMap instead. Application developers should avoid calling CMMs directly, since they may or may not support a given API.
© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)