Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

Chapter 3 - ColorSync Manager Reference for Applications and Device Drivers / ColorSync Manager Functions

Matching Colors Using Low-Level Functions Without QuickDraw /

CWMatchPixMap

Matches a pixel map in place based on a specified color world.

pascal CMError CWMatchPixMap (
CMWorldRef cw,
PixMap *myPixMap,
CMBitmapCallBackUPP progressProc,
void *refCon);

cw

A reference to the color world (page 3-66) in which matching is to occur.

myPixMap

A pointer to the pixel map to match. A pixel map is a QuickDraw structure describing pixel data. The pixel map must be nonrelocatable; to ensure this, you should lock the handle to the pixel map before you call this function.

progressProc

A function supplied by your application to monitor progress or abort the operation as the pixel map colors are matched. The Apple CMM calls your function approximately every half-second, unless matching is completed in less time.

If the function returns a result of true, the operation is aborted. You specify NULL for this parameter if your application will not monitor the pixel map color matching. For information on the callback function and its type definition, refer to the MyCMBitmapCallBackProc function (page 3-170).

refCon

A reference constant for application data that is passed as a parameter to calls to progressProc.

function result

A result code of type CMError. See "Result Codes" (page 3-174) for a list of ColorSync-specific result codes.

DISCUSSION

The CWMatchPixMap function matches a pixel map in place using the profiles specified by the given color world. The preferred CMM, as determined by the ColorSync Manager based on the color world configuration, is called to perform the color matching.

If the preferred CMM is not available, then the ColorSync Manager calls the default Apple CMM to perform the matching. If the preferred CMM is available but it does not implement the CMMatchPixMap function, then the ColorSync Manager unpacks the colors in the pixel map to create a color list and calls the preferred CMM's CMMatchColors function, passing to this function the list of colors to match. Every CMM must support the CMMatchColors function.

For this function to execute successfully, the source and destination profiles' data color spaces (dataColorSpace field) must be RGB to match the data color space of the pixel map, which is implicitly RGB. For color spaces other than RGB, you should use the CWMatchBitmap function (page 3-120).

If you specify a pointer to a callback function in the progressProc parameter, the CMM performing the color matching calls your function to monitor progress of the session. Each time the CMM calls your function, it passes the function any data you specified in the CWMatchPixMap function's refCon parameter. If the ColorSync dispatcher performs the color matching, it calls your callback monitoring function once every scan line during this process.

You can use the reference constant to pass in any kind of data your callback function requires. For example, if your application uses a dialog box with a thermometer to inform the user of the color-matching session's progress, you can use the reference constant to pass the dialog box's window reference to the callback routine. For information about the callback function, see the MyCMBitmapCallBackProc function (page 3-170).

SEE ALSO

The NCWNewColorWorld function (page 3-108) and the CWConcatColorWorld function (page 3-110) both allocate color world references of type CMWorldRef.

Note

Your application does not interact with the CMMatchColors function (page 4-12).