CWMatchBitmap

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

Declaration

CMError CWMatchBitmap (
   CMWorldRef cw,
   CMBitmap *bitmap,
   CMBitmapCallBackUPP progressProc,
   void *refCon,
   CMBitmap *matchedBitmap
);

Parameters

cw:
A reference to a color world of type Cmworldref in which matching is to occur.
The functions 1805079 Ncwnewcolorworld and 1805087 Cwconcatcolorworld both allocate color world references of type Cmworldref.
bitmap:
A pointer to a bitmap of type Cmbitmap whose colors are to be matched.
progressProc:
A calling program–supplied universal procedure pointer to a callback function that allows your application to monitor progress or abort the operation as the bitmap colors are matched. The default 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 the function Cmbitmapcallbackprocptr.
refCon:
A pointer to a reference constant for application data passed through as a parameter to calls to the progressProc function.
matchedBitmap:
A pointer to a bitmap. On return, contains the color-matched image. You must allocate the pixel buffer pointed to by the image field of the structure Cmbitmap. If you specify NULL for matchedBitMap, then the source bitmap is matched in place.

Return Value

A CMError value. See Result Codes.

Overview

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

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

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.

Version-Notes

The color spaces currently supported for the CWMatchBitmap function are defined in CMBitmapColorSpace. Support for the following color space constants, was added with ColorSync version 2.5:

cmGray16Space
cmGrayA32Space
cmRGB48Space.
cmCMYK64Space
cmLAB48Space