![]() |
PATH![]() |
![]() ![]() |
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
creates a color world for color matching based on the specified source and destination profiles;
changed in ColorSync 2.5
.CWConcatColorWorld
sets up a color world that includes a set of profiles for various color transformations among devices in a sequence;
changed in ColorSync 2.5
.CWNewLinkProfile
creates a device link profile based on the specified set of profiles.CMGetCWInfo
obtains information about the color management modules (CMMs) used for a specific color world;
changed in ColorSync 2.5
.CWDisposeColorWorld
releases the private storage associated with a color world when your application has finished using the color world.CWMatchPixMap
matches a pixel map in place based on a specified color world.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.CWMatchBitmap
matches the colors of a bitmap to the gamut of a destination device using the profiles specified by a color world.CWCheckBitMap
tests the colors of the pixel data of a bitmap to determine whether the colors map to the gamut of the destination device.CWMatchColors
matches colors in a color list, using the specified color world.CWCheckColors
tests a list of colors using a specified color world to see if they fall within the gamut of a destination device.Creates a color world for color matching based on the specified source and destination profiles.
pascal CMError NCWNewColorWorld (
CMWorldRef *cw,
CMProfileRef src,
CMProfileRef dst);
CMWorldRef
. You pass this reference to other functions that use the color world. 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
.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
.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
.
The parameter descriptions for src and dst describe changes in how this function is used starting with ColorSync version 2.5.
The function
CWConcatColorWorld
also allocates a color world reference of type
CMWorldRef
.
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);
CMWorldRef
. You pass the returned reference to other functions that use the color world for color-matching and color-checking sessions.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.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
.
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 .
Creates a device link profile based on the specified set of profiles.
pascal CMError CWNewLinkProfile (
CMProfileRef *prof,
const CMProfileLocation *targetLocation,
CMConcatProfileSet *profileSet);
CMProfileRef
. On output, points to the new device link profile reference. CMConcatProfileSet
data type, see
CMHeader
.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).
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 .
Obtains information about the color management modules (CMMs) used for a specific color world.
pascal CMError CMGetCWInfo (
CMWorldRef cw,
CMCWInfoRecord *info);
CMWorldRef
about which you want information.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.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 .
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 .
The functions
NCWNewColorWorld
and
CWConcatColorWorld
both allocate color world references of type
CMWorldRef
.
Releases the private storage associated with a color world when your application has finished using the color world.
pascal void CWDisposeColorWorld (CMWorldRef cw);
CMWorldRef
.
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.
Matches a pixel map in place based on a specified color world.
pascal CMError CWMatchPixMap (
CMWorldRef cw,
PixMap *myPixMap,
CMBitmapCallBackUPP progressProc,
void *refCon);
CMWorldRef
in which matching is to occur.MyCMBitmapCallBackProc
. 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
.
The functions
NCWNewColorWorld
and
CWConcatColorWorld
both allocate color world references of type
CMWorldRef
.
Note
Applications do not interact directly with the function
CMMatchColors
.
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);
CMWorldRef
in which color checking is to occur.MyCMBitmapCallBackProc
. 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.
The functions
NCWNewColorWorld
and
CWConcatColorWorld
both return color world references of type
CMWorldRef
.
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);
CMWorldRef
in which matching is to occur.CMBitmap
whose colors are to be matched. MyCMBitmapCallBackProc
.CMBitmap
. If you specify
NULL
for
matchedBitMap
, then the source bitmap is matched in place.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:
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:
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.
Support for the following color space constants, defined in Color Space Constants With Packing Formats , was added with ColorSync version 2.5:
The functions
NCWNewColorWorld
and
CWConcatColorWorld
both allocate color world references of type
CMWorldRef
.
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);
CMWorldRef
to use for the color check.CMBitmap
whose colors are to be checked. MyCMBitmapCallBackProc
. 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
.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.
The functions
NCWNewColorWorld
and
CWConcatColorWorld
both allocate color world references of type
CMWorldRef
.
Matches colors in a color list, using the specified color world.
pascal CMError CWMatchColors (
CMWorldRef cw,
CMColor *myColors,
unsigned long count);
CMWorldRef
that describes how matching is to occur in the color-matching session.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.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.
The functions
NCWNewColorWorld
and
CWConcatColorWorld
both allocate color world references of type
CMWorldRef
.
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);
CMWorldRef
describing how the test is to occur.CMColor
to be checked
.
This function assumes the color values are specified in the data color space of the source profile. 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.
The functions
NCWNewColorWorld
and
CWConcatColorWorld
both allocate color world references of type
CMWorldRef
.