Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

CWCheckPixMap
Checks the colors of a pixel map using the profiles of a specified color world to determine whether the colors are in the gamut of the destination device.
pascal CMError CWCheckPixMap (
CMWorldRef cw,
PixMap *myPixMap,
CMBitmapCallBackUPP progressProc,
void *refCon,
BitMap *resultBitMap);
cw
A reference to the color world (page 3-66) in which color checking is to occur.
myPixMap
A pointer to the pixel map to check colors for. 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.
progressProc
A calling program-supplied callback function that allows your application to monitor progress or abort the operation as the pixel map colors are checked against the gamut of the destination device.

The Apple CMM calls your function approximately every half-second unless color checking occurs in less time; this happens when there is a small amount of data to be checked. If the function returns a result of true, the operation is aborted. Specify NULL for this parameter if your application will not monitor the pixel map color checking. For information on the callback function and its type definition, see MyCMBitmapCallBackProc (page 3-170).
refCon
A reference constant for application data passed as a parameter to calls to your MyCMBitmapCallBackProc function pointed to by progressProc.
resultBitMap
A pointer to a QuickDraw bitmap. On output, pixels are set to 1 if the corresponding pixel of the pixel map indicated by myPixMap is out of gamut. Boundaries of the bitmap indicated by resultBitMap must equal the parameter of the pixel map indicated by the myPixMap.
function result
A result code of type CMError. See "Result Codes" (page 3-174) for a list of ColorSync-specific result codes. CWCheckPixMap returns cmCantGamutCheckError if the color world does not contain gamut information. For more information, see "Flag Mask Definitions for Version 2.x Profiles" (page 3-29).

DISCUSSION
The CWCheckPixMap function performs a gamut test of the pixel data of the myPixMap pixel map to determine if its colors are within the gamut of the destination device as specified by the destination profile. The gamut test provides a preview of color matching using the specified color world.
The preferred CMM, as determined by the ColorSync Manager based on the profiles of 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 does not implement the CMCheckPixmap function, then the ColorSync Manager unpacks the colors in the pixel map to create a color list and calls the preferred CMM's CMCheckColors function, passing to this function the list of colors to match. Every CMM must support the CMCheckColors 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.
If you specify a pointer to a callback function in the progressProc parameter, the CMM performing the color checking 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 CWCheckPixMap function's refCon parameter.
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-checking 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).
You should ensure that the buffer pointed to by the baseAddr field of the bitmap passed in the resultBitMap parameter is zeroed out.

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