![]() |
CMMatchBitmap |
||||
Header: | CMMComponent.h | Carbon status: | Unsupported | |
Handles the kCMMMatchBitmap request by matching the colors of the source image bitmap to the color gamut of the destination profile.
CMMatchBitmap ();
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.
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.
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 CMMs storage for the calling applications 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 CMBitmapCallBackProcPtr 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 CMMatchBitmap function calls the CMBitmapCallBackProcPtr 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 CMBitmapCallBackProcPtr 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 CMBitmapCallBackProcPtr function, it must pass a byte count of 0. A byte count of 0meaning there is no more data to matchindicates the completion of the matching process and signals the progress function to perform any cleanup operations it requires.
If the source profiles 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 profiles 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.
CMMatchBitmap is an API to CMMs. Use CWMatchBitMap 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)