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 /

CWCheckColors

Tests a list of colors using a specified color world to see if they fall within the gamut of a destination device.

pascal CMError CWCheckColors (
CMWorldRef cw,
CMColor *myColors,
unsigned long count,
long *result);

cw

A reference to the color world (page 3-66) describing how the test is to occur.

myColors

A pointer to an array containing a list of colors (page 3-59) to be checked.This function assumes the color values are specified in the data color space of the source profile.

count

The number of colors in the array. This is a one-based count.

result

A pointer to a buffer of long data values. On output, each long value is interpreted as a bit field with each bit representing a color in the array pointed to by myColors. You allocate enough memory to allow for 1 bit to represent each color in the myColors array. Bits in the result field are set to 1 if the corresponding color is out of gamut for the destination device. Ensure that the buffer you allocate is zeroed out before you call this function.

function result

A result code of type CMError. See "Result Codes" (page 3-174) for a list of ColorSync-specific result codes. CWCheckColors 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 color test provides a preview of color matching using the specified color world.

All CMMs must support the CWCheckColors function. To determine which CMM to use for the color-checking session, the ColorSync Manager follows the arbitration scheme described in "Introduction to the ColorSync Manager" in Advanced Color Imaging on the Mac OS.

The result bit array indicates whether the colors in the list are in or out of gamut for the destination profile. If a bit is set, its corresponding color falls out of gamut for the destination device. The leftmost bit in the field corresponds to the first color in the list.

If you have set a profile's gamut-checking mask so that no gamut information is included--see "Flag Mask Definitions for Version 2.x Profiles" (page 3-29)--CWCheckColors returns the cmCantGamutCheckError error.

The CWCheckColors function supports matching sessions set up with one of the multichannel color data types. CWCheckColors 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.