PATHMac OS 8 and 9 Developer Documentation > Mutlimedia and Graphics > ColorSync Manager >

Managing Color With ColorSync


Matching Colors Using General Purpose Functions

This section describes the functions you use to perform color matching with general purpose ColorSync Manager functions that are independent of QuickDraw. To use the general purpose functions, you first create a color-matching world, which establishes how matching will take place between the given profiles.

General Purpose Color-Matching Functions provides an overview of these functions, while Creating a Color World to Use With the General Purpose Functions provides a code sample for working with them.

Once you create a color world, it persists until you dispose of it, independent of the functions for which you use it. The QuickDraw-specific functions described in Matching Colors Using QuickDraw-Specific Functions take source and destination profile reference parameters and are state-based, whereas the general purpose functions described here are not state-based.

You use the following functions to perform color-matching using general purpose functions.


NCWNewColorWorld

Changed in ColorSync 2.5

Creates a color world for color matching based on the specified source and destination profiles.

pascal CMError NCWNewColorWorld (
                     CMWorldRef *cw,
                     CMProfileRef src,
                     CMProfileRef dst);
cw
A pointer to a color world. On output, a reference to a matching session color world of type CMWorldRef . You pass this reference to other functions that use the color world.
src
A profile reference of type CMProfileRef that specifies the source profile for the color-matching world. This profile's dataColorSpace element corresponds to the source data type for subsequent calls to functions that use this color world. Starting with ColorSync version 2.5, you can call CMGetDefaultProfileBySpace to get the default profile for a specific color space or CMGetProfileByAVID to get a profile for a specific display. With any version of ColorSync, you can specify a NULL value to indicate the ColorSync system profile. Note, however, that starting with version 2.5, use of the system profile has changed, as described in Setting Default Profiles .
dst
A profile reference of type CMProfileRef that specifies the destination profile for the color-matching world. This profile's dataColorSpace element corresponds to the destination data type for subsequent calls to functions using this color world. Starting with ColorSync version 2.5, you can call CMGetDefaultProfileBySpace to get the default profile for a specific color space or CMGetProfileByAVID to get a profile for a specific display. With any version of ColorSync, you can specify a NULL value to indicate the ColorSync system profile. Note, however, that starting with version 2.5, use of the system profile has changed, as described in Setting Default Profiles .
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

You must set up a color world before your application can perform general purpose color-matching or color-checking operations. To set up a color world for these operations, your application can call NCWNewColorWorld after obtaining references to the profiles to use as the source and destination profiles for the color world. The following rules govern the types of profiles allowed:

You should call the function CMCloseProfile for both the source and destination profiles to dispose of their references after execution of the NCWNewColorWorld function.

When you pass a color world to a color-matching or color-checking function, the ColorSync Manager uses the selection scheme described in How the ColorSync Manager Selects a CMM to determine the CMM or CMMs to use for the session.

The quality flag setting (indicating normal mode, draft mode, or best mode) specified by the source profile prevails for the entire session. The quality flag setting is stored in the flags field of the profile header. See CM2Header and Flag Mask Definitions for Version 2.x Profiles for more information on the use of flags. The rendering intent specified by the source profile also prevails for the entire session.

For more information on color worlds, see CMConcatProfileSet .

VERSION NOTES

The parameter descriptions for src and dst describe changes in how this function is used starting with ColorSync version 2.5.

SEE ALSO

The function CWConcatColorWorld also allocates a color world reference of type CMWorldRef .


CWConcatColorWorld

Changed in ColorSync 2.5

Sets up a color world that includes a set of profiles for various color transformations among devices in a sequence.

pascal CMError CWConcatColorWorld (
                     CMWorldRef *cw,
                     CMConcatProfileSet *profileSet);
cw
A pointer to a color world. On output, a reference to a color world of type CMWorldRef . You pass the returned reference to other functions that use the color world for color-matching and color-checking sessions.
profileSet
A pointer of type CMConcatProfileSet to an array of profiles describing the processing to carry out. You create the array and initialize it in processing order--source through destination. You set the keyIndex field of the CMConcatProfileSet data structure to specify the zero-based index of the profile within the profile array whose specified CMM should be used for the entire color-matching or color-checking session. The profile header's CMMType field specifies the CMM. This CMM will fetch the profile elements necessary for the session. Note that starting with ColorSync 2.5, the user can set a preferred CMM with the ColorSync control panel, as described in Setting a Preferred CMM . If that CMM is available, ColorSync will use that CMM for all color conversion and matching operations the CMM is capable of performing.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

The CWConcatColorWorld function sets up a session for color processing that includes a set of profiles. The array of profiles is in processing order--source through destination. Your application passes the function a pointer to a data structure of type CMConcatProfileSet to identify the profile array.

The quality flag setting--indicating normal mode, draft mode, or best mode--specified by the first profile prevails for the entire session; the quality flags of following profiles in the sequence are ignored. The quality flag setting is stored in the flags field of the profile header. See CM2Header and Flag Mask Definitions for Version 2.x Profiles for more information on the use of flags.

The rendering intent specified by the first profile is used to color match to the second profile, the rendering intent for the second profile is used to color match to the third profile, and so on through the series of concatenated profiles.

The following rules govern the profiles you can specify in the profile array pointed to by the profileSet parameter for use with the CWConcatColorWorld function:

A after executing the CWConcatColorWorld function, you should call the function CMCloseProfile for each profile to dispose of its reference.

For more information on color worlds, see CMConcatProfileSet .

VERSION NOTES

The parameter description for profileSet includes changes in how this function is used starting with ColorSync version 2.5.

When you pass a color world created with the CWConcatColorWorld function to a color-matching or color-checking function, the ColorSync Manager uses the selection scheme described in How the ColorSync Manager Selects a CMM to determine the CMM or CMMs to use for the session.

Note also that starting with version 2.5, use of the system profile has changed, as described in Setting Default Profiles .

SEE ALSO

Instead of passing in an array of profiles, you can specify a device link profile. For information on how to create a device link profile, see the CWNewLinkProfile function, which is described next.


CWNewLinkProfile

Changed in ColorSync 2.5

Creates a device link profile based on the specified set of profiles.

pascal CMError CWNewLinkProfile (
                     CMProfileRef *prof,
                     const CMProfileLocation *targetLocation,
                     CMConcatProfileSet *profileSet);
prof
A pointer to an uninitialized profile reference of type CMProfileRef . On output, points to the new device link profile reference.
targetLocation
On output, a pointer to a location specification for the resulting profile. A device link profile cannot be a temporary profile: that is, it cannot have a location type of cmNoProfileBase .
profileSet
On input, an array of profiles describing the processing to carry out. The array is in processing order--source through destination. For a description of the CMConcatProfileSet data type, see CMHeader .
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

This discussion is accurate for versions of ColorSync prior to 2.5. See the version notes below for changes starting with version 2.5.

You can use this function to create a new single profile containing a set of profiles and pass the device link profile to the function CWConcatColorWorld instead of specifying each profile in an array. A device link profile provides a means of storing in concatenated format a series of device profiles and non-device profiles that are used repeatedly in the same sequence.

IMPORTANT

The only way to use a device link profile is to pass it to the CWConcatColorWorld function as the sole profile specified by the array passed in the profileSet parameter.

The zero-based keyIndex field of the CMConcatProfileSet data structure specifies the index of the profile within the device link profile whose preferred CMM is used for the entire color-matching or color-checking session. The profile header's CMMType field specifies the preferred CMM for the specified profile. This CMM will fetch the profile elements necessary for the session.

The quality flag setting--indicating normal mode, draft mode, or best mode--specified by the first profile prevails for the entire session; the quality flags of profiles that follow in the sequence are ignored. The quality flag setting is stored in the flag field of the profile header. See CM2Header for more information on the use of flags.

The rendering intent specified by the first profile is used to color match to the second profile, the rendering intent specified by the second profile is used to color match to the third profile, and so on through the series of concatenated profiles.

The following rules govern the content and use of a device link profile:

When your application is finished with the device link profile, it must close the profile with the function CMCloseProfile .

This function privately maintains all the profile information required by the color world for color-matching and color-checking sessions. Therefore, after executing the CWNewLinkProfile function, you should call the CMCloseProfile function for each profile used to build a device link profile (to dispose of each profile reference).

VERSION NOTES

When you pass a color world created with the CWNewLinkProfile function to a color-matching or color-checking function, the ColorSync Manager uses the selection scheme described in How the ColorSync Manager Selects a CMM to determine the CMM or CMMs to use for the session.

Note also that starting with version 2.5, use of the system profile has changed, as described in Setting Default Profiles .


CMGetCWInfo

Changed in ColorSync 2.5

Obtains information about the color management modules (CMMs) used for a specific color world.

pascal CMError CMGetCWInfo (
                     CMWorldRef cw,
                     CMCWInfoRecord *info);
cw
A reference to the color world of type CMWorldRef about which you want information.
info
A pointer to a color world information record of type CMCWInfoRecord that your application supplies. On output, the ColorSync Manager returns information in this structure describing the number of CMMs involved in the matching session and the CMM type and version of each CMM used.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

This discussion is accurate for versions of ColorSync prior to 2.5. See the version notes below for changes starting with version 2.5.

To learn whether one or two CMMs are used for color matching and color checking in a given color world and to obtain the CMM type and version number of each CMM used, your application must first obtain a reference to the color world. To obtain a reference to a ColorSync color world, you (or some other process) must have created the color world using the function NCWNewColorWorld or the function CWConcatColorWorld .

The source and destination profiles you specify when you create a color world identify their preferred CMMs, and you explicitly identify the profile whose CMM is used for a device link profile or a concatenated color world. However, you cannot be certain if the specified CMM will actually be used until the ColorSync Manager determines internally if the CMM is available and able to perform the requested function. For example, when the specified CMM is not available, the default CMM is used.

The CMGetCWInfo function identifies the CMM or CMMs to use. Your application must allocate a data structure of type CMCWInfoRecord and pass a pointer to it in the info parameter. The CMGetCWInfo function returns the color world information in this structure. The structure includes a cmmCount field identifying the number of CMMs that will be used and an array of two members containing structures of type CMMInfoRecord . The CMGetCWInfo function returns information in one or both of the CMM information records depending on whether one or two CMMs are used.

For a brief description of a color world, see Matching Colors Using General Purpose Functions .

VERSION NOTES

Starting with ColorSync 2.5, a user can select a preferred CMM with the ColorSync control panel, as described in Setting a Preferred CMM . If the user has selected a preferred CMM, and if it is available, then it will be used for all color conversion and matching operations. For related information, see Color Management Modules and How the ColorSync Manager Selects a CMM .

SEE ALSO

The functions NCWNewColorWorld and CWConcatColorWorld both allocate color world references of type CMWorldRef .


CWDisposeColorWorld

Releases the private storage associated with a color world when your application has finished using the color world.

pascal void CWDisposeColorWorld (CMWorldRef cw);
cw
A color world reference of type CMWorldRef .
function result
This routine does not return an error value.

SEE ALSO

The function NCWNewColorWorld and the function CWConcatColorWorld both allocate color world references of type CMWorldRef .

The following functions use color worlds. If you create a color world to pass to one of these functions, you must dispose of the color world when your application is finished with it.


CWMatchPixMap

Matches a pixel map in place based on a specified color world.

pascal CMError CWMatchPixMap (
                     CMWorldRef cw,
                     PixMap *myPixMap,
                     CMBitmapCallBackUPP progressProc,
                     void *refCon);
cw
A reference to the color world of type CMWorldRef in which matching is to occur.
myPixMap
A pointer to the pixel map to match. 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 before you call this function.
progressProc
A function supplied by your application to monitor progress or abort the operation as the pixel map colors are matched. The default CMM calls your function approximately every half-second, unless matching is completed in less time.
If the function returns a result of true , the operation is aborted. You specify NULL for this parameter if your application will not monitor the pixel map color matching. For information on the callback function and its type definition, refer to the function MyCMBitmapCallBackProc.
refCon
A reference constant for application data that is passed as a parameter to calls to progressProc .
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

The CWMatchPixMap function matches a pixel map in place using the profiles specified by the given color world. The preferred CMM, as determined by the ColorSync Manager based on 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 CMM to perform the matching. If the preferred CMM is available but it does not implement the CMMatchPixMap function, then the ColorSync Manager unpacks the colors in the pixel map to create a color list and calls the preferred CMM's CMMatchColors function, passing to this function the list of colors to match. Every CMM must support the CMMatchColors 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. For color spaces other than RGB, you should use the function CWMatchBitmap .

If you specify a pointer to a callback function in the progressProc parameter, the CMM performing the color matching 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 CWMatchPixMap function's refCon parameter. If the ColorSync Manager performs the color matching, it calls your callback monitoring function once every scan line during this process.

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 progress bar to inform the user of the color-matching 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 function MyCMBitmapCallBackProc.

SEE ALSO

The functions NCWNewColorWorld and CWConcatColorWorld both allocate color world references of type CMWorldRef .

Note

Applications do not interact directly with the function CMMatchColors .


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 of type CMWorldRef 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 default 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 the function MyCMBitmapCallBackProc.
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, bits 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 . For possible values, see Result Codes for the ColorSync Manager . CWCheckPixMap returns cmCantGamutCheckError if the color world does not contain gamut information. For more information, see Flag Mask Definitions for Version 2.x Profiles .

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 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 progress bar 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 function MyCMBitmapCallBackProc.

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 functions NCWNewColorWorld and CWConcatColorWorld both return color world references of type CMWorldRef .


CWMatchBitmap

Changed With ColorSync 2.5

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 a color world of type CMWorldRef in which matching is to occur.
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 MyCMBitmapCallBackProc.
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 structure CMBitmap . If you specify NULL for matchedBitMap , then the source bitmap is matched in place.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

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

The ColorSync Manager dispatches this function to the CMM determined by the process described in How the ColorSync Manager Selects a CMM .

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, defined in Color Space Constants With Packing Formats , are currently supported for the CWMatchBitmap function:

  • cmGray16Space
  • cmGrayA32Space
  • cmRGB16Space
  • cmRGB24Space
  • cmRGB32Space
  • cmRGB48Space
  • cmARGB32Space
  • cmRGBA32Space
  • cmCMYK32Space
  • cmCMYK64Space
  • cmHSV32Space
  • cmHLS32Space
  • cmYXY32Space
  • cmXYZ32Space
  • cmLUV32Space
  • cmLAB24Space
  • cmLAB32Space
  • cmLAB48Space
  • cmGamutResult1Space
  • 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.

VERSION NOTES

Support for the following color space constants, defined in Color Space Constants With Packing Formats , was added with ColorSync version 2.5:

SEE ALSO

The functions NCWNewColorWorld and CWConcatColorWorld both allocate color world references of type CMWorldRef .


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 of type CMWorldRef to use for the color check.
bitMap
A pointer to a bitmap of type CMBitmap 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 default 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 the function MyCMBitmapCallBackProc.
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 results 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 structure CMBitmap 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, as described in Abstract Color Space Constants .
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager . CWCheckBitMap returns cmCantGamutCheckError if the color world does not contain gamut information. For more information, see Flag Mask Definitions for Version 2.x Profiles .

DISCUSSION

When your application calls the CWCheckBitMap function, the ColorSync Manager dispatches the function to the preferred CMM. The ColorSync Manager determines the ed 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 Selecting a CMM by the Arbitration Algorithm 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 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 functions NCWNewColorWorld and CWConcatColorWorld both allocate color world references of type CMWorldRef .


CWMatchColors

Matches colors in a color list, using the specified color world.

pascal CMError CWMatchColors (
                     CMWorldRef cw,
                     CMColor *myColors,
                     unsigned long count);
cw
A reference to the color world of type CMWorldRef that describes how matching is to occur in the color-matching session.
myColors
A pointer to an array containing a list of colors of type CMColor . On input, contains the list of colors to match. On output, contains the list of matched colors specified in the color data space of the color world's destination profile.
count
A one-based count of the number of colors in the color list of the myColors array.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

The CWMatchColors function matches colors according to the profiles corresponding to the specified color world. On input, the color values in the myColors array are assumed to be specified in the data color space of the source profile. On output, the color values in the myColors array are transformed to the data color space of the destination profile.

All color management modules (CMM)s must support this function. To determine which CMM to use for the color-matching session, the ColorSync Manager follows the arbitration scheme described in Introduction to ColorSync .

This function supports color-matching sessions set up with one of the multichannel color data types.

SEE ALSO

The functions NCWNewColorWorld and CWConcatColorWorld both allocate color world references of type CMWorldRef .


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 of type CMWorldRef describing how the test is to occur.
myColors
A pointer to an array containing a list of colors of type CMColor 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 32-bit data. On output, each 32-bit 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 . For possible values, see Result Codes for the ColorSync Manager . CWCheckBitMap returns cmCantGamutCheckError if the color world does not contain gamut information. For more information, see Flag Mask Definitions for Version 2.x Profiles .

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

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 -- 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 functions NCWNewColorWorld and CWConcatColorWorld both allocate color world references of type CMWorldRef .


© 1988-1999 Apple Computer, Inc. — (Last Updated 20 Jan 99)

Previous | Back Up One Level | Next