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 /

CWMatchBitmap

Matches the colors of a bitmap to the gamut of a destination device using the profiles specified by a color world.

pascal CMError CWMatchBitmap (
CMWorldRef cw,
CMBitMap *bitMap,
CMBitmapCallBackUPP progressProc,
void *refCon,
CMBitMap *matchedBitMap); 

cw

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

matchedBitMap

A pointer to the bitmap (page 3-61) whose colors are to be matched.

progressProc

A calling program-supplied callback function that allows your application to monitor progress or abort the operation as the bitmap colors are matched. The Apple CMM calls your function approximately every half-second unless color matching occurs in less time; this happens when there is a small amount of data to be matched. If the function returns a result of true, the operation is aborted. To match colors without monitoring the process, specify NULL for this parameter. For a description of the function your application supplies, see MyCMBitmapCallBackProc (page 3-170).

refCon

A reference constant for application data passed through as a parameter to calls to the progressProc function.

matchedBitMap

A pointer to a bitmap. On output, contains the color-matched image. You must allocate the pixel buffer pointed to by the image field of the CMBitMap structure (page 3-61). If you specify NULL for matchedBitMap, then the source bitmap is matched in place.

function result

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

DISCUSSION

The CWMatchBitmap function matches a bitmap using the profiles specified by the given color world.

The ColorSync Manager dispatches this 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, it 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 ColorSync Manager uses the default Apple CMM to perform the color matching.

You should ensure that the buffer pointed to by the image field of the bitmap passed in the bitMap parameter is zeroed out before you call this function.

The following color spaces are currently supported for the CWMatchBitmap function:

• cmGraySpace
• cmGrayASpace
• cmRGB16Space
• cmRGB24Space
• cmRGB32Space
• cmARGB32Space
• cmRGBA32Space
• cmCMYK32Space
• cmHSV32Space
• cmHLS32Space
• cmYXY32Space
• cmXYZ32Space
• cmLUV32Space
• cmLAB24Space
• cmLAB32Space
• cmNamedIndexed32Space
• cmMCFive8Space
• cmMCSix8Space
• cmMCSeven8Space
• cmMCEight8Space

The ColorSync Manager does not explicitly support a CMY color space. However, for printers that have a CMY color space, you can use either of the following circumventions to make the adjustment:

• You can use a CMY profile, which the ColorSync Manager does support, with a CMYK color space. If you specify a CMYK color space in this case, the ColorSync Manager zeroes out the K channel to simulate a CMY color space.
• You can use an RGB color space and pass in the bitmap along with an RGB profile, then perform the conversion from RGB to CMY yourself.

For this 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. Additionally, the destination profile's dataColorSpace field value and the space field value of the resulting bitmap pointed to by the matchedBitMap parameter must specify the same data color space, unless the destination profile is a named color space profile.

IMPORTANT

If you set matchedBitMap to NULL to specify in-place matching, you must be sure the space required by the destination bitmap is less than or equal to the size of the source bitmap.

SEE ALSO

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