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 /

CWCheckBitMap

Tests the colors of the pixel data of a bitmap to determine whether the colors map to the gamut of the destination device.

pascal CMError CWCheckBitMap (
CMWorldRef cw,
const CMBitMap *bitMap,
CMBitmapCallBackUPP progressProc,
void *refCon,
CMBitMap *resultBitMap);

cw

A reference to the color world (page 3-66) to use for the color check.

bitMap

A pointer to a bitmap (page 3-61) whose colors are to be checked.

progressProc

A calling program-supplied callback function that allows your application to monitor progress or abort the operation as the bitmap's 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 bitmap 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 progressProc.

resultBitMap

A pointer to a bitmap. On output, contains the outcome of the color check. The bitmap must have bounds equal to the parameter of the source bitmap pointed to by bitMap. You must allocate the pixel buffer pointed to by the image field of the CMBitMap structure (page 3-61) and initialize the buffer to zeroes. Pixels are set to 1 if the corresponding pixel of the source bitmap indicated by bitMap is out of gamut. You must set the space field of the CMBitMap structure to cmGamutResult1Space color space storage format (see "Abstract Color Space Constants" (page 3-23)).

function result

A result code of type CMError. See "Result Codes" (page 3-174) for a list of ColorSync-specific result codes. CWCheckBitMap 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

When your application calls the CWCheckBitMap function, the ColorSync Manager dispatches the function to the preferred CMM. The ColorSync Manager determines the preferred CMM based on the color world configuration. If the color world you pass in was created by the NCWNewColorWorld function, the color world contains a source and destination profile, in which case the arbitration scheme described in "Introduction to the ColorSync Manager" in Advanced Color Imaging on the Mac OS is used to determine the preferred CMM. If the color world you pass in was created by the CWConcatColorWorld function, then the keyIndex field of the CMConcatProfileSet data structure identifies the preferred CMM. If the preferred CMM is not available, the default Apple CMM is used to perform the color matching.

For the CWCheckBitMap function to execute successfully, the source profile's dataColorSpace field value and the space field value of the source bitmap pointed to by the bitMap parameter must specify the same data color space. CWCheckBitMap is not supported if the color world was initialized with a named color space profile.

SEE ALSO

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