Carbon


CWMatchPixMap

Header: CMApplication.h Carbon status: Supported

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

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

A reference to the color world of type CMWorldRef in which matching is to occur.

The functions NCWNewColorWorld and CWConcatColorWorld both allocate color world references of type CMWorldRef.

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 default 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 function CMProfileFilterProcPtr.

refCon

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

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 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 function CWMatchBitmap.

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 Manager 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 progress bar 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 function CMBitmapCallBackProcPtr.

Applications do not interact directly with the function CWMatchColors.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when ColorSync 1.0 or later is present.


© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)