Deprecated ColorSync Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in OS X v10.4

CMEnableMatchingComment

Inserts a comment into the currently open picture to turn matching on or off. (Deprecated in OS X v10.4.)

void CMEnableMatchingComment (
   Boolean enableIt
);
Parameters
enableIt

A flag that directs the ColorSync Manager to generate a cmEnableMatchingPicComment comment if true, or a cmDisbleMatchingPicComment comment if false.

Discussion

If you call this function when no picture is open, it will have no effect.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Declared In
QuickdrawAPI.h

CMEndMatching

Concludes a QuickDraw-specific ColorSync matching session initiated by a previous call to the NCMBeginMatching function. (Deprecated in OS X v10.4.)

void CMEndMatching (
   CMMatchRef myRef
);
Parameters
myRef

A reference to the matching session to end. This reference was previously created and returned by a call to NCMBeginMatching function. See the QuickDraw Reference for a description of the PixMap data type.

Discussion

The CMEndMatching function releases private memory allocated for the QuickDraw-specific matching session.

After you call the NCMBeginMatching function and before you call CMEndMatching to end the matching session, embedded color-matching picture comments, such as cmEnableMatching and cmDisableMatching, are not acknowledged.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Declared In
QuickdrawAPI.h

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. (Deprecated in OS X v10.4.)

CMError CWCheckPixMap (
   CMWorldRef cw,
   PixMap *myPixMap,
   CMBitmapCallBackUPP progressProc,
   void *refCon,
   BitMap *resultBitMap
);
Parameters
cw

A reference to the color world of type CMWorldRef in which color checking is to occur.

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

See the QuickDraw Reference for a description of the PixMap data type.

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. See the QuickDraw Reference for a description of the PixMap data type.

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

See the QuickDraw Reference for a description of the PixMap data type.

refCon

A pointer to a reference constant for application data passed as a parameter to calls to your CMBitmapCallBack function pointed to by progressProc.

resultBitMap

A pointer to a QuickDraw bitmap. On return, 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. See the QuickDraw Reference for a description of the PixMap data type.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

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

You should ensure that the buffer pointed to by the baseAddr field of the bitmap passed in the resultBitMap parameter is zeroed out.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Declared In
QuickdrawAPI.h

CWMatchPixMap

Matches a pixel map in place based on a specified color world. (Deprecated in OS X v10.4.)

CMError CWMatchPixMap (
   CMWorldRef cw,
   PixMap *myPixMap,
   CMBitmapCallBackUPP progressProc,
   void *refCon
);
Parameters
cw

A reference to the color world of type CMWorldRef in which matching is to occur.

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

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. See the QuickDraw Reference for a description of the PixMap data type.

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

refCon

A pointer to a reference constant for application data that is passed as a parameter to calls to progressProc.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

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

Applications do not interact directly with the function CWMatchColors.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Declared In
QuickdrawAPI.h

NCMBeginMatching

Sets up a QuickDraw-specific ColorSync matching session, using the specified source and destination profiles. (Deprecated in OS X v10.4.)

CMError NCMBeginMatching (
   CMProfileRef src,
   CMProfileRef dst,
   CMMatchRef *myRef
);
Parameters
src

A profile reference of type CMProfileRef that specifies the source profile for the matching session. 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.

See the QuickDraw Reference for a description of the PixMap data type.

dst

A profile reference of type CMProfileRef that specifies the destination profile for the matching session. 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.See the QuickDraw Reference for a description of the PixMap data type.

myRef

A pointer to a matching session. On return, it specifies the QuickDraw-specific matching session that was set up. See the QuickDraw Reference for a description of the PixMap data type.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The NCMBeginMatching function sets up a QuickDraw-specific matching session, telling the ColorSync Manager to match all colors drawn to the current graphics device using the specified source and destination profiles.

The NCMBeginMatching function returns a reference to the color-matching session. You must later pass this reference to the function CMEndMatching to conclude the session.

The source and destination profiles define how the match is to occur. Passing NULL for either the source or destination profile is equivalent to passing the system profile. If the current device is a screen device, matching to all screen devices occurs.

The NCMBeginMatching and CMEndMatching functions can be nested. In such cases, the ColorSync Manager matches to the most recently added profiles first. Therefore, if you want to use the NCMBeginMatchingCMEndMatching pair to perform a page preview—which typically entails color matching from a source device (scanner) to a destination device (printer) to a preview device (display)— you first call NCMBeginMatching with the printer-to-display profiles, and then call NCMBeginMatching with the scanner-to-printer profiles. The ColorSync Manager then matches all drawing from the scanner to the printer and then back to the display. The print preview process entails multiprofile transformations. The ColorSync Manager general purpose functions (which include the use of concatenated profiles well suited to print-preview processing) offer an easier and faster way to do this. These functions are described in “Matching Colors Using General Purpose Functions”.

If you call NCMBeginMatching before drawing to the screen’s graphics device (as opposed to an offscreen device), you must call CMEndMatching to finish a matching session before calling WaitNextEvent or any other routine (such as Window Manager routines) that could draw to the screen. Failing to do so will cause unwanted matching to occur. Furthermore, if a device has color matching enabled, you cannot call the CopyBits procedure to copy from it to itself unless the source and destination rectangles are the same.

Even if you call the NCMBeginMatching function before calling the QuickDraw DrawPicture function, the ColorSync picture comments such as cmEnableMatching and cmDisableMatching are not acknowledged. For the ColorSync Manager to recognize these comments and allow their use, you must call the function NCMUseProfileComment for color matching using picture comments.

This function causes matching for the specified devices rather than for the current color graphics port.

The NCMBeginMatching function uses QuickDraw and performs color matching in a manner acceptable to most applications. However, if your application needs a finer level of control over color matching, it can use the general purpose functions described in “Matching Colors Using General Purpose Functions”.

Version Notes

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

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Declared In
QuickdrawAPI.h

NCMDrawMatchedPicture

Matches a picture’s colors to a destination device’s color gamut, as the picture is drawn, using the specified destination profile. (Deprecated in OS X v10.4.)

void NCMDrawMatchedPicture (
   PicHandle myPicture,
   CMProfileRef dst,
   Rect *myRect
);
Parameters
myPicture

The QuickDraw picture whose colors are to be matched. See the QuickDraw Reference for a description of the PixMap data type.

dst

A profile reference of type CMProfileRef to the profile of the destination device. Starting with ColorSync version 2.5, if you know the destination display device, you can call CMGetProfileByAVID to get the specific profile for the display, or you can call CMGetDefaultProfileBySpace to get the default profile for the RGB color space,.

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.

See the QuickDraw Reference for a description of the PixMap data type.

myRect

A pointer to a destination rectangle for rendering the picture specified by myPicture.

Return Value

This function does not return an error value. Instead, after calling NCMDrawMatchedPicture you call the QDError routine to determine if an error has occurred.

Discussion

The NCMDrawMatchedPicture function operates in the context of the current color graphics port. This function sets up and takes down a color-matching session. It automatically matches all colors in a picture to the destination profile for a destination device as the picture is drawn. It uses the ColorSync system profile as the initial source profile and any embedded profiles as they are encountered thereafter. (Because color-matching picture comments embedded in the picture to be matched are recognized, embedded profiles are used.)

The ColorSync Manager defines five picture comment kinds, as described in “Picture Comment Kinds.” For embedding to work correctly, each embedded profile that is used for matching must be terminated by a picture comment of kind cmEndProfile. If a picture comment is not specified to end the profile after drawing operations using that profile are performed, the profile will remain in effect until another embedded profile is introduced that has a picture comment kind of cmBeginProfile. To avoid unexpected matching effects, always pair use of the cmBeginProfile and cmEndProfile picture comments. When the ColorSync Manager encounters a cmEndProfile picture comment, it restores use of the system profile for matching until it encounters another cmBeginProfile picture comment.

The picture is drawn with matched colors to all screen graphics devices. If the current graphics device is not a screen device, matching occurs for that graphics device only.

If the current port is not a color graphics port, then calling this function is equivalent to calling DrawPicture, in which case no color matching occurs.

Version Notes

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

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Declared In
QuickdrawAPI.h

NCMUseProfileComment

Automatically embeds a profile or a profile identifier into an open picture. (Deprecated in OS X v10.4.)

CMError NCMUseProfileComment (
   CMProfileRef prof,
   UInt32 flags
);
Parameters
prof

A profile reference of type CMProfileRef to the profile to embed. See the QuickDraw Reference for a description of the PixMap data type.

flags

A flag value in which individual bits determine settings. “Embedded Profile Identifiers” describes constants for use with this parameter. For example, you pass cmEmbedWholeProfile to embed a whole profile or cmEmbedProfileIdentifier to embed a profile identifier. No other values are currently defined; all other bits are reserved for future use.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The NCMUseProfileComment function automatically generates the picture comments required to embed the specified profile or profile identifier into the open picture.

To embed a profile, you use the constant cmEmbedWholeProfile to set the flags parameter before calling NCMUseProfileComment. The NCMUseProfileComment function calls the QuickDraw PicComment function with a picture comment kind value of cmComment and a 4-byte selector that describes the type of data in the picture comment: cmBeginProfileSel to begin the profile, cmContinueProfileSel to continue, and cmEndProfileSel to end the profile. These constants are described in “Picture Comment Selectors.”

If the size in bytes of the profile and the 4-byte selector together exceed 32 KB, this function segments the profile data and embeds the multiple segments in consecutive order using selector cmContinueProfileSel to embed each segment.

To embed a profile identifier of type CMProfileIdentifier , you use the constant cmEmbedProfileIdentifier to set the flags parameter before calling NCMUseProfileComment. The function extracts the necessary information from the profile reference ( prof) to embed a profile identifier for the profile. The profile reference can refer to a previously embedded profile, or to a profile on disk in the ColorSync Profiles folder.

You can use this function to embed most types of profiles in an image, including device link profiles, but not abstract profiles. You cannot use this function to embed ColorSync 1.0 profiles in an image.

The NCMUseProfileComment function precedes the profile it embeds with a picture comment of kind cmBeginProfile. For embedding to work correctly, the currently effective profile must be terminated by a picture comment of kind cmEndProfile after drawing operations using that profile are performed. You are responsible for adding the picture comment of kind cmEndProfile. If a picture comment was not specified to end the profile following the drawing operations to which the profile applies, the profile will remain in effect until the next embedded profile is introduced with a picture comment of kind cmBeginProfile. However, use of the next profile might not be the intended action. Always pair use of the cmBeginProfile and cmEndProfile picture comments. When the ColorSync Manager encounters a cmEndProfile picture comment, it restores use of the system profile for matching until it encounters another cmBeginProfile picture comment.

Version Notes

In ColorSync 2.0, the flags parameter was ignored and the routine always embedded the entire profile.

In ColorSync 2.0, if the prof parameter refers to a version 1.0 profile, the profile is not embedded into the picture correctly. In ColorSync versions starting with 2.1, this bug has been fixed. One possible workaround for this problem in ColorSync 2.0 is to call CMCopyProfile to copy the 1.0 profile reference into a handle. The handle can then be embedded into the picture using CMUseProfileComment.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Declared In
QuickdrawAPI.h

Deprecated in OS X v10.5

CWNewLinkProfile

Creates a device link profile based on the specified set of profiles. (Deprecated in OS X v10.5.)

CMError CWNewLinkProfile (
   CMProfileRef *prof,
   const CMProfileLocation *targetLocation,
   CMConcatProfileSet *profileSet
);
Parameters
prof

A pointer to an uninitialized profile reference of type CMProfileRef. On return, points to the new device link profile reference.

targetLocation

On return, 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, a pointer to 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.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

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.

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:

  • The first and last profiles you specify in the profiles array for a device link profile must be device profiles.

  • You cannot specify a named color profile.

  • You cannot include another device link profile in the series of profiles you specify in the profiles array.

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

  • You cannot embed a device link profile in an image.

  • You cannot specify NULL to indicate the system profile.

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

Note that starting with version 2.5, use of the system profile has changed.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.5.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

Deprecated in OS X v10.6

CMCloneProfileRef

Increments the reference count for the specified profile reference. (Deprecated in OS X v10.6.)

CMError CMCloneProfileRef (
   CMProfileRef prof
);
Parameters
prof

A profile reference of type CMProfileRef to the profile whose reference count is incremented.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The ColorSync Manager keeps an internal reference count for each profile reference returned from a call to the CMOpenProfile, CMNewProfile, or CMCopyProfile functions. Calling the CMCloneProfileRef function increments the count; calling the function CMCloseProfile decrements it. The profile remains open as long as the reference count is greater than 0, indicating that at least one routine retains a reference to the profile. When the count reaches 0, the ColorSync Manager releases all private memory, files, or resources allocated in association with that profile.

When your application creates a copy of an entire profile with CMCopyProfile, the copy has its own reference count. The CMCloseProfile routine should be called for the copied profile, just as for the original. When the reference count reaches 0, private resources associated with the copied profile are freed.

When your application merely duplicates a profile reference, as it may do to pass a profile reference to a synchronous or an asynchronous task, it should call CMCloneProfileRef to increment the reference count. Both the called task and the caller should call CMCloseProfile when finished with the profile reference.

In your application, you must make sure that CMCloseProfile is called once for each time a profile reference is created or cloned. Otherwise, the memory and resources associated with the profile reference may not be properly freed, or an application may attempt to use a profile reference that is no longer valid.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMCloseProfile

Decrements the reference count for the specified profile reference and, if the reference count reaches 0, frees all private memory and other resources associated with the profile. (Deprecated in OS X v10.6.)

CMError CMCloseProfile (
   CMProfileRef prof
);
Parameters
prof

A profile reference of type CMProfileRef that identifies the profile that may need to be closed.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The ColorSync Manager keeps an internal reference count for each profile reference returned from a call to the CMOpenProfile, CMNewProfile, CMCopyProfile, or CWNewLinkProfile functions. Calling the function CMCloneProfileRef increments the count; calling the CMCloseProfile function decrements it. The profile remains open as long as the reference count is greater than 0, indicating there is at least one remaining reference to the profile. When the count reaches 0, the ColorSync Manager releases all private memory, files, or resources allocated in association with that profile.

When the ColorSync Manager releases all private memory and resources associated with a profile, any temporary changes your application made to the profile are not saved unless you first call the CMUpdateProfile function to update the profile.

When your application passes a copy of a profile reference to an independent task, whether synchronous or asynchronous, it should call the function CMCloneProfileRef to increment the reference count. Both the called task and the caller should call CMCloseProfile when finished with the profile reference.

You call CMCloneProfileRef after copying a profile reference, but not after duplicating an entire profile (as with the CMCopyProfile function).

When your application passes a copy of a profile reference internally, it may not need to call CMCloneProfileRef, as long as the application calls CMCloseProfile once for the profile.

In your application, make sure that CMCloseProfile is called once for each time a profile reference is created or cloned. Otherwise, the private memory and resources associated with the profile reference may not be properly freed, or an application may attempt to use a profile reference that is no longer valid.

If you create a new profile by calling the CMNewProfile function, the profile is saved to disk when you call the CMCloseProfile function unless you specified NULL as the profile location when you created the profile.

To save changes to a profile before closing it, use the function CMUpdateProfile.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
Declared In
ColorSyncDeprecated.h

CMConvertFixedXYZToXYZ

Converts colors specified in XYZ color space whose components are expressed as Fixed XYZ 32-bit signed values of type CMFixedXYZColor to equivalent colors expressed as XYZ 16-bit unsigned values of type CMXYZColor. (Deprecated in OS X v10.6.)

CMError CMConvertFixedXYZToXYZ (
   const CMFixedXYZColor *src,
   CMXYZColor *dst,
   size_t count
);
Parameters
src

A pointer to an array containing the list of Fixed XYZ colors to convert to XYZ colors.

dst

A pointer to an array containing the list of colors resulting from the conversion specified as XYZ colors.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertFixedXYZToXYZ function converts one or more colors defined in the Fixed XYZ color space to equivalent colors defined in the XYZ color space. The XYZ color space is device independent.

If your application does not require that you preserve the source color list, you can pass the pointer to the same color list array as the src and dst parameters and allow the CMConvertFixedXYZToXYZ function to overwrite the source colors with the resulting converted color specifications.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertHLSToRGB

Converts colors specified in the HLS color space to equivalent colors defined in the RGB color space. (Deprecated in OS X v10.6.)

CMError CMConvertHLSToRGB (
   const CMColor *src,
   CMColor *dst,
   size_t count
);
Parameters
src

A pointer to an array containing the list of HLS colors to convert to RGB colors.

dst

A pointer to an array containing the list of colors, resulting from the conversion, as specified in the RGB color space.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertHLSToRGB function converts one or more colors defined in the HLS color space to equivalent colors defined in the RGB color space. Both color spaces are device dependent.

If your application does not require that you preserve the source color list, you can pass the pointer to the same color list array as the src and dst parameters and allow the CMConvertHLSToRGB function to overwrite the source colors with the resulting converted color specifications.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertHSVToRGB

Converts colors specified in the HSV color space to equivalent colors defined in the RGB color space. (Deprecated in OS X v10.6.)

CMError CMConvertHSVToRGB (
   const CMColor *src,
   CMColor *dst,
   size_t count
);
Parameters
src

A pointer to an array containing the list of HSV colors to convert to RGB colors.

dst

A pointer to an array containing the list of colors, resulting from the conversion, as specified in the RGB color space.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertHSVToRGB function converts one or more colors defined in the HSV color space to equivalent colors defined in the RGB color space. Both color spaces are device dependent.

If your application does not require that you preserve the source color list, you can pass the pointer to the same color list array as the src and dst parameters and allow the CMConvertHSVToRGB function to overwrite the source colors with the resulting converted color specifications.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertLabToXYZ

Converts colors specified in the L*a*b* color space to the XYZ color space. (Deprecated in OS X v10.6.)

CMError CMConvertLabToXYZ (
   const CMColor *src,
   const CMXYZColor *white,
   CMColor *dst,
   size_t count
);
Parameters
src

A pointer to a buffer containing the list of L*a*b* colors to convert to XYZ colors.

white

A pointer to a reference white point.

dst

A pointer to a buffer containing the list of colors as specified in the XYZ color space resulting from the conversion.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertLabToXYZ function converts one or more colors defined in the L*a*b color space to equivalent colors defined in the XYZ color space. Both color spaces are device independent.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertLuvToXYZ

Converts colors specified in the L*u*v* color space to the XYZ color space. (Deprecated in OS X v10.6.)

CMError CMConvertLuvToXYZ (
   const CMColor *src,
   const CMXYZColor *white,
   CMColor *dst,
   size_t count
);
Parameters
src

A pointer to an array containing the list of L*u*v* colors to convert.

white

A pointer to a reference white point.

dst

A pointer to an array containing the list of colors, resulting from the conversion, as specified in the XYZ color space.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertLuvToXYZ function converts one or more colors defined in the L*u*v color space to equivalent colors defined in the XYZ color space. Both color spaces are device independent.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertRGBToGray

Converts colors specified in the RGB color space to equivalent colors defined in the Gray color space. (Deprecated in OS X v10.6.)

CMError CMConvertRGBToGray (
   const CMColor *src,
   CMColor *dst,
   size_t count
);
Parameters
src

A pointer to an array containing the list of colors specified in RGB space to convert to colors specified in Gray space.

dst

A pointer to an array containing the list of colors, resulting from the conversion, as specified in the Gray color space.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertRGBToGray function converts one or more colors defined in the RGB color space to equivalent colors defined in the Gray color space. Both color spaces are device dependent.

If your application does not require that you preserve the source color list, you can pass the pointer to the same color list array as the src and dst parameters and allow the CMConvertRGBToGray function to overwrite the source colors with the resulting converted color specifications.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertRGBToHLS

Converts colors specified in the RGB color space to equivalent colors defined in the HLS color space. (Deprecated in OS X v10.6.)

CMError CMConvertRGBToHLS (
   const CMColor *src,
   CMColor *dst,
   size_t count
);
Parameters
src

A pointer to an array containing the list of RGB colors to convert to HLS colors.

dst

A pointer to an array containing the list of colors, resulting from the conversion, as specified in the HLS color space.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertRGBToHLS function converts one or more colors defined in the RGB color space to equivalent colors defined in the HLS color space. Both color spaces are device dependent.

If your application does not require that you preserve the source color list, you can pass the pointer to the same color list array as the src and dst parameters and allow the CMConvertRGBToHLS function to overwrite the source colors with the resulting converted color specifications.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertRGBToHSV

Converts colors specified in the RGB color space to equivalent colors defined in the HSV color space when the device types are the same. (Deprecated in OS X v10.6.)

CMError CMConvertRGBToHSV (
   const CMColor *src,
   CMColor *dst,
   size_t count
);
Parameters
src

A pointer to an array containing the list of RGB colors to convert to HSV colors.

dst

A pointer to an array containing the list of colors, resulting from the conversion, as specified in the HSV color space.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertRGBToHSV function converts one or more colors defined in the RGB color space to equivalent colors defined in the HSV color space. Both color spaces are device dependent.

If your application does not require that you preserve the source color list, you can pass the pointer to the same color list array as the src and dst parameters and allow the CMConvertRGBToHSV function to overwrite the source colors with the resulting converted color specifications.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertXYZToFixedXYZ

Converts colors specified in the XYZ color space whose components are expressed as XYZ 16-bit unsigned values of type CMXYZColor to equivalent colors expressed as 32-bit signed values of type CMFixedXYZColor. (Deprecated in OS X v10.6.)

CMError CMConvertXYZToFixedXYZ (
   const CMXYZColor *src,
   CMFixedXYZColor *dst,
   size_t count
);
Parameters
src

A pointer to an array containing the list of XYZ colors to convert to Fixed XYZ colors.

dst

A pointer to an array containing the list of colors resulting from the conversion in which the colors are specified as Fixed XYZ colors.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertXYZToFixedXYZ function converts one or more colors whose components are defined as XYZ colors to equivalent colors whose components are defined as Fixed XYZ colors. Fixed XYZ colors allow for 32-bit precision. The XYZ color space is device independent.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertXYZToLab

Converts colors specified in the XYZ color space to the L*a*b* color space. (Deprecated in OS X v10.6.)

CMError CMConvertXYZToLab (
   const CMColor *src,
   const CMXYZColor *white,
   CMColor *dst,
   size_t count
);
Parameters
src

A pointer to an array containing the list of XYZ colors to convert to L*a*b* colors.

white

A pointer to a reference white point.

dst

A pointer to an array containing the list of L*a*b* colors resulting from the conversion.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertXYZToLab function converts one or more colors defined in the XYZ color space to equivalent colors defined in the L*a*b* color space. Both color spaces are device independent.

If your application does not require that you preserve the source color list, you can pass the pointer to the same color list array as the src and dst parameters and allow the CMConvertXYZToLab function to overwrite the source colors with the resulting converted color specifications.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertXYZToLuv

Converts colors specified in the XYZ color space to the L*u*v* color space. (Deprecated in OS X v10.6.)

CMError CMConvertXYZToLuv (
   const CMColor *src,
   const CMXYZColor *white,
   CMColor *dst,
   size_t count
);
Parameters
src

A pointer to an array containing the list of XYZ colors to convert to L*u*v* colors.

white

A pointer to a reference white point.

dst

A pointer to an array containing the list of colors represented in L*u*v* color space resulting from the conversion.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertXYZToLuv function converts one or more colors defined in the XYZ color space to equivalent colors defined in the L*u*v* color space. Both color spaces are device independent.

If your application does not require that you preserve the source color list, you can pass the pointer to the same color list array as the src and dst parameters and allow the CMConvertXYZToLuv function to overwrite the source colors with the resulting converted color specifications.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertXYZToXYZ

Converts a source color to a destination color using the specified chromatic adaptation method. (Deprecated in OS X v10.6.)

CMError CMConvertXYZToXYZ (
   const CMColor *src,
   const CMXYZColor *srcIlluminant,
   CMColor *dst,
   const CMXYZColor *dstIlluminant,
   CMChromaticAdaptation method,
   size_t count
);
Parameters
src
srcIlluminant
dst
dstIlluminant
method
count
Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertXYZToYxy

Converts colors specified in the XYZ color space to the Yxy color space. (Deprecated in OS X v10.6.)

CMError CMConvertXYZToYxy (
   const CMColor *src,
   CMColor *dst,
   size_t count
);
Parameters
src

A pointer to an array containing the list of XYZ colors to convert to Yxy colors.

dst

A pointer to an array containing the list of colors resulting from the conversion represented in the Yxy color space.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertXYZToYxy function converts one or more colors defined in the XYZ color space to equivalent colors defined in the Yxy color space. Both color spaces are device independent.

If your application does not require that you preserve the source color list, you can pass the pointer to the same color list array as the src and dst parameters and allow the CMConvertXYZToYxy function to overwrite the source colors with the resulting converted color specifications.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMConvertYxyToXYZ

Converts colors specified in the Yxy color space to the XYZ color space. (Deprecated in OS X v10.6.)

CMError CMConvertYxyToXYZ (
   const CMColor *src,
   CMColor *dst,
   size_t count
);
Parameters
src

A pointer to an array containing the list of Yxy colors to convert.

dst

A pointer to an array containing the list of colors, resulting from the conversion, as specified in the XYZ color space.

count

The number of colors to convert.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMConvertYxyToXYZ function converts one or more colors defined in the Yxy color space to equivalent colors defined in the XYZ color space. Both color spaces are device independent.

If your application does not require that you preserve the source color list, you can pass the pointer to the same color list array as the src and dst parameters and allow the CMConvertYxyToXYZ function to overwrite the source colors with the resulting converted color specifications.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMCopyProfile

Duplicates the specified existing profile. (Deprecated in OS X v10.6.)

CMError CMCopyProfile (
   CMProfileRef *targetProf,
   const CMProfileLocation *targetLocation,
   CMProfileRef srcProf
);
Parameters
targetProf

A pointer to a profile reference of type CMProfileRef. On return, points to the profile copy that was created.

targetLocation

A pointer to a location specification that indicates the location, such as in memory or on disk, where the ColorSync Manager is to create the copy of the profile. A profile is commonly disk-file based. However, to accommodate special requirements, you can create a handle- or pointer-based profile, you can create a profile that is accessed through a procedure provided by your application, or you can create a temporary profile that is not saved after you call the CMCloseProfile function. To create a temporary profile, you either specify cmNoProfileBase as the kind of profile in the profile location structure or specify NULL for this parameter. To specify the location, you use the data type CMProfileLocation.

srcProf

A profile reference to the profile to duplicate.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMCopyProfile function duplicates an entire open profile whose reference you specify. If you have made temporary changes to the profile, which you have not saved by calling CMUpdateProfile, those changes are included in the duplicated profile. They are not saved to the original profile unless you call CMUpdateProfile for that profile.

The ColorSync Manager maintains a modified flag to track whether a profile has been modified. After copying a profile, the CMCopyProfile function sets the value of the modified flag for that profile to false.

Unless you are copying a profile that you created, you should not infringe on copyright protection specified by the profile creator. To obtain the copyright information, you call the function CMGetProfileElement, specifying the cmCopyrightTag tag signature for the copyright element (defined in the CMICCProfile.h header file).

You should also check the flags field of the profile header structure CM2Header for copyright information. You can test the cmEmbeddedUseMask bit of the flags field to determine whether the profile can be used independently. If the bit is set, you should use this profile as an embedded profile only and not copy the profile for your own purposes. The cmEmbeddedUseMask mask is described in “Flag Mask Definitions for Version 2.x Profiles.” The following code snippet shows how you might perform a test using the cmEmbeddedUseMask mask:

if (myCM2Header.flags & cmEmbeddedUseMask)
{
// profile should only be used as an embedded profile
}
else
{
// profile can be used independently
}

A calibration program, for example, might use the CMCopyProfile function to copy a device’s original profile, then modify the copy to reflect the current state of the device. Or an application might want to copy a profile after unflattening it.

To copy a profile, you must obtain a reference to that profile by either opening the profile or creating it. To open a profile, use the function CMOpenProfile. To create a new profile, use the function CMNewProfile. As an alternative to using the CMCopyProfile function to duplicate an entire profile, you can use the same profile reference more than once. To do so, you call the function CMCloneProfileRef to increment the reference count for the reference each time you reuse it. Calling the CMCloneProfileRef function increments the count; calling the function CMCloseProfile decrements it. The profile remains open as long as the reference count is greater than 0, indicating at least one routine retains a reference to the profile.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMCopyProfileDescriptionString

Returns the name of a profile as a CFString. (Deprecated in OS X v10.6.)

CMError CMCopyProfileDescriptionString (
   CMProfileRef prof,
   CFStringRef *str
);
Parameters
prof

The profile to query.

str

On output, the name of the profile as a CFString.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

If the profile is localized, ColorSync obtains the best localized name for the current process.

Availability
  • Available in OS X v. 10.3 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMCopyProfileLocalizedString

Gets one specific string out of a profile (Deprecated in OS X v10.6.)

CMError CMCopyProfileLocalizedString (
   CMProfileRef prof,
   OSType tag,
   CFStringRef reqLocale,
   CFStringRef *locale,
   CFStringRef *str
);
Parameters
prof

The profile to query.

tag

The tag type of profile to query.

reqLocale

The requested locale (optional).

locale

On output, points to the locale (optional).

str

On output, points to the dictionary string (optional).

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

For example, you pass in the optional tag 'dscm' plus "enUS" for the reqLocale parameter, to for a U.S. English string. If a U.S. English string is not found, ColorSync falls back to a reasonable default:

err = CMCopyProfileLocalizedString (prof, 'dscm',
                CFSTR("enUS"), nil, &theStr);
Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMCopyProfileLocalizedStringDictionary

Obtains a CFDictionary which contains the language locale and string for multiple localizations from a given tag. (Deprecated in OS X v10.6.)

CMError CMCopyProfileLocalizedStringDictionary (
   CMProfileRef prof,
   OSType tag,
   CFDictionaryRef *theDict
);
Parameters
prof

The profile to query

tag

The tag type of profile to query

theDict

On output, points to the dictionary .See the CFDictionary documentation for a description of the CFDictionaryRef data type.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

This function allows you to get a CFDictionary which contains the language locale and string for multiple localizations from a given tag.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMCountImageProfiles

Obtains a count of the number of embedded profiles for a given image. (Deprecated in OS X v10.6.)

CMError CMCountImageProfiles (
   const FSSpec *spec,
   UInt32 *count
);
Parameters
spec

A file specification for the image file. See the File Manager documentation for a description of the FSSpec data type.

count

On output, a count of the embedded profiles for the image

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMCountProfileElements

Counts the number of elements in the specified profile. (Deprecated in OS X v10.6.)

CMError CMCountProfileElements (
   CMProfileRef prof,
   UInt32 *elementCount
);
Parameters
prof

A profile reference of type CMProfileRef to the profile to examine.

elementCount

A pointer to an element count. On return, a one-based count of the number of elements.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Every element in the profile outside the header is counted. A profile may contain tags that are references to other elements. These tags are included in the count.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMCreateProfileIdentifier

Creates a profile identifier for a specified profile. (Deprecated in OS X v10.6.)

CMError CMCreateProfileIdentifier (
   CMProfileRef prof,
   CMProfileIdentifierPtr ident,
   UInt32 *size
);
Parameters
prof
ident
size
Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMDisposeProfileSearch

Frees the private memory allocated for a profile search after your application has completed the search. (Deprecated in OS X v10.6.)

void CMDisposeProfileSearch (
   CMProfileSearchRef search
);
Parameters
search

A reference to the profile search result list whose private memory is to be released. For a description of the CMProfileSearchRef private data type, see CMProfileSearchRef. See the QuickDraw Reference for a description of the PixMap data type.

Discussion

To set up a search, use the function CMNewProfileSearch. To obtain a reference to a profile corresponding to a specific index in the list, use the function CMSearchGetIndProfile. To obtain the file specification for a profile corresponding to a specific index in the list, use the function CMSearchGetIndProfileFileSpec. To update the search result list, use the function CMUpdateProfileSearch.

Version Notes

This function is not recommended for use in ColorSync 2.5.

Starting with version 2.5, you should use the function CMIterateColorSyncFolder for profile searching.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMEmbedImage

Embeds an image with an ICC profile. (Deprecated in OS X v10.6.)

CMError CMEmbedImage (
   const FSSpec *specFrom,
   const FSSpec *specInto,
   Boolean repl,
   CMProfileRef embProf
);
Parameters
specFrom

A file specification for the image file. See the File Manager documentation for a description of the FSSpec data type.

specInto

If this parameter is a file, it specifies the resulting image. If this parameter is a folder, it specifies the location of the resulting image which will have the same name as the original file. If this parameter is not provided, the original file is modified. See the File Manager documentation for a description of the FSSpec data type.

repl

A Boolean value. If a file with the same name already exists, it will be replaced if this parameter is set to true.

embProf

The profile to embed in the image.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMFlattenProfile

Transfers a profile stored in an independent disk file to an external profile format that can be embedded in a graphics document. (Deprecated in OS X v10.6.)

CMError CMFlattenProfile (
   CMProfileRef prof,
   UInt32 flags,
   CMFlattenUPP proc,
   void *refCon,
   Boolean *preferredCMMnotfound
);
Parameters
prof

A profile reference of type CMProfileRef to the profile to flatten.

flags

Reserved for future use.

proc

A pointer to a function that you provide to perform the low-level data transfer. For more information, see the function CMFlattenProcPtr.

refCon

A pointer to a reference constant for application data which the color management module (CMM) passes to the CMFlattenProcPtr function each time it calls the function. For example, the reference constant may point to a data structure that holds information required by the CMFlattenProcPtr function to perform the data transfer, such as the reference number to a disk file in which the flattened profile is to be stored.

Starting with ColorSync version 2.5, the ColorSync Manager calls your transfer function directly, without going through the preferred, or any, CMM.

preferredCMMnotfound

A pointer to a flag for whether the preferred CMM was found. On return, has the value true if the CMM specified by the profile was not available to perform flattening or does not support this function and the default CMM was used. Has the value false if the profile’s preferred CMM is able to perform flattening.

Starting with ColorSync 2.5, the ColorSync Manager calls your transfer function directly, without going through the preferred, or any, CMM. On return, the value of preferredCMMnotfound is guaranteed to be false.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The ColorSync Manager passes to the CMM the pointer to your profile-flattening function. The CMM calls your function CMFlattenProcPtr to perform the actual data transfer.

To unflatten a profile embedded in a graphics document to an independent disk file, use the function “Accessing Profile Elements”.

Version Notes

Prior to version 2.5, the ColorSync Manager dispatches the CMFlattenProfile function to the CMM specified by the profile whose reference you provide. If the preferred CMM is unavailable or it does not support this function, then the default CMM is used.

Starting with ColorSync version 2.5, the ColorSync Manager calls your transfer function directly, without going through the preferred, or any, CMM. As a result, the value returned in the preferredCMMnotfound parameter is guaranteed to be false.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMGetColorSyncFolderSpec

Obtains the volume reference number and the directory ID for a ColorSync Profiles folder. (Deprecated in OS X v10.6.)

CMError CMGetColorSyncFolderSpec (
   short vRefNum,
   Boolean createFolder,
   short *foundVRefNum,
   long *foundDirID
);
Parameters
vRefNum

The location of the ColorSync profiles folder. In OS X, pass a constant that specifies one of the four possible locations for ColorSync profiles. Pass kSystemDomain for profiles located in:

/System/Library/ColorSync/Profiles

Pass kLocalDomain for profiles located in:

/Library/ColorSync/Profiles

Pass kNetworkDomain for profiles located in:

/Network/Library/ColorSync/Profiles

Pass kUserDomain for profiles located in:

~/Library/ColorSync/Profiles

In Mac OS 9, pass the reference number of the volume to examine. The volume must be mounted. The constant kOnSystemDisk defined in the Folders header file (Folders.h) specifies the active system volume.

createFolder

A flag you set to true to direct the ColorSync Manager to create the ColorSync Profiles folder, if it does not exist. You can use the constants kCreateFolder and kDontCreateFolder, defined in the Folders.h header file, to assign a value to the flag.

foundVRefNum

A pointer to a volume reference number. On return, the volume reference number for the volume on which the ColorSync Profiles folder resides.

foundDirID

A pointer to a directory ID. On return, the directory ID for the volume on which the ColorSync Profiles folder resides.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

If the ColorSync Profiles folder does not already exist, you can use this function to create it.

Version Notes

Starting with version 2.5, the name and location of the profile folder changed.

Your application should use the function CMIterateColorSyncFolder, available starting in ColorSync version 2.5, or one of the search functions described in “Searching for Profiles Prior to ColorSync 2.5”, to search for a profile file, even if it is only looking for one file. Do not search for a profile file by obtaining the location of the profiles folder and searching for the file directly.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMGetColorSyncVersion

Gets ColorSync version information. (Deprecated in OS X v10.6.)

CMError CMGetColorSyncVersion (
   UInt32 *version
);
Parameters
version

On output, points to the version of ColorSync installed on the system.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

CMGetColorSyncVersion relieves you from having to call Gestalt to find out the version of ColorSync installed on the system.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetCWInfo

Obtains information about the color management modules (CMMs) used for a specific color world. (Deprecated in OS X v10.6.)

CMError CMGetCWInfo (
   CMWorldRef cw,
   CMCWInfoRecord *info
);
Parameters
cw

A reference to the color world of type CMWorldRef about which you want information.

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

info

A pointer to a color world information record of type CMCWInfoRecord that your application supplies. On return, 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.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

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.

Version Notes

Starting with ColorSync 2.5, a user can select a preferred CMM with the ColorSync control panel. 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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMGetDefaultDevice

Gets the default device. (Deprecated in OS X v10.6.)

CMError CMGetDefaultDevice (
   CMDeviceClass deviceClass,
   CMDeviceID *deviceID
);
Parameters
deviceClass

The device class whose default device you want to get. See “Device Classes” for a list of the constants you can supply.

deviceID

On return, points to the device ID for the default device.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

For each class of device, a device management layer may establish which of the registered devices is the default. This helps keep color management choices to a minimum and allows for some automatic features to be enabled, such as the "Default printer" as an output profile selection.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetDefaultProfileBySpace

Gets the default profile for the specified color space. (Deprecated in OS X v10.6.)

CMError CMGetDefaultProfileBySpace (
   OSType dataColorSpace,
   CMProfileRef *prof
);
Parameters
dataColorSpace

A four-character identifier of type OSType. You pass a color space signature that identifies the color space you wish to get the default profile for. The currently-supported values are cmRGBData, cmCMYKData, cmLabData, and cmXYZData. These constants are a subset of the constants described in “Color Space Signatures.” If you supply a value that is not supported, the CMGetDefaultProfileBySpace function returns an error value of paramErr.

prof

A pointer to a profile reference. On return, the reference specifies the current profile for the color space specified by dataColorSpace. CMGetDefaultProfileBySpace currently supports only file-based profiles.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMGetDefaultProfileBySpace function currently supports the RGB, CMYK, Lab, and XYZ color spaces. The signature constants for these color spaces (shown above with the dataColorSpace parameter description) are described in “Color Space Signatures.” Support for additional color spaces may be provided in the future. CMGetDefaultProfileBySpace returns an error value of paramErr if you pass a color space constant it does not currently support.

The CMGetDefaultProfileBySpace function always attempts to return a file-based profile for a supported color space. For example, if the user has not specified a default profile in the ColorSync control panel for the specified color space, or if the profile is not found (the user may have deleted the profiles in the ColorSync Profiles folder or even the folder itself), CMGetDefaultProfileBySpace creates a profile, stores it on disk, and returns a reference to that profile. However, you should always check for an error return—for example, a user may have booted from a CD, so that CMGetDefaultProfileBySpace cannot save a profile file to disk.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetDefaultProfileByUse

Obtains the users’ preferred device profile setting. (Deprecated in OS X v10.6.)

CMError CMGetDefaultProfileByUse (
   OSType use,
   CMProfileRef *prof
);
Parameters
use

A value that specifies the device type for which to obtain the profile.

prof
Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetDeviceDefaultProfileID

Gets the default profile ID for a given device. (Deprecated in OS X v10.6.)

CMError CMGetDeviceDefaultProfileID (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   CMDeviceProfileID *defaultProfID
);
Parameters
deviceClass

The device class to query. See “Device Classes” for a list of the constants you can supply.

deviceID

The device ID to query.

defaultID

On output, points to the id of the default profile for this device.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Device drivers and host software can set the default profile for a given device using the function CMSetDeviceDefaultProfileID.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetDeviceFactoryProfiles

Retrieves the original profiles for a given device. (Deprecated in OS X v10.6.)

CMError CMGetDeviceFactoryProfiles (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   CMDeviceProfileID *defaultProfID,
   UInt32 *arraySize,
   CMDeviceProfileArray *deviceProfiles
);
Parameters
deviceClass

The device class to query. See “Device Classes” for a list of the constants you can supply.

deviceID

The device ID to query.

defaultProfID

A pointer to the default profile for this device.

arraySize

A pointer to the size of the array to be returned. You can first call this routine to get the size returned, then call it again with the size of the buffer to receive the array.

deviceProfiles

On output, points to the profile array. You can first pass NULL in this parameter to receive the size of the array in the arraySize parameter. Then, once the appropriate amount of storage has been allocated, a pointer to it can be passed in this parameter to have the array copied to that storage.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

This function allows you to retrieve the original profiles for a given device. These may differ from the actual profiles in use for that device, in the case where any factory profiles have been replaced (updated). To get the actual profiles in use, call CMGetDeviceProfiles.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetDeviceInfo

Gets information about a specified device. (Deprecated in OS X v10.6.)

CMError CMGetDeviceInfo (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   CMDeviceInfo *deviceInfo
);
Parameters
deviceClass

A device class to query. See “Device Classes” for a list of the constants you can supply.

deviceID

A device ID to query. You can pass cmDefaultDeviceID.

deviceInfo

On input, points to a device information dictionary On output, the dictionary is filled with device information. If, on input, deviceInfo->deviceName is nil then the name is not returned. If you wants the device name dictionary returned, you should provide in deviceInfo->deviceName the address where this routine should store the CFDictionaryRef. The caller is responsible for disposing of the name dictionary.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetDeviceProfile

Gets a profile used by a given device. (Deprecated in OS X v10.6.)

CMError CMGetDeviceProfile (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   CMDeviceProfileID profileID,
   CMProfileLocation *profileLoc
);
Parameters
deviceClass

The device class for the device whose profile you want to get. See “Device Classes” for a list of the constants you can supply.

deviceID

The device ID for the device whose profile you want to get.

defaultID

The ID of the default profile for this device.

deviceProfLoc

On return, the location of the profile.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetDeviceProfiles

Gets the profiles used by a given device. (Deprecated in OS X v10.6.)

CMError CMGetDeviceProfiles (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   UInt32 *arraySize,
   CMDeviceProfileArray *deviceProfiles
);
Parameters
deviceClass

The device class for the device whose profiles you want to get. See “Device Classes” for a list of the constants you can supply.

deviceID

The device ID for the device whose profiles you want to get.

arraySize

A pointer to the size of the array to be returned. You can first call this routine to get the size returned, then call it again with the size of the buffer to receive the array.

deviceProfiles

On output, an array of profiles used by the device. You can first pass NULL in this parameter to receive the size of the array in the arraySize parameter. Then, once the appropriate amount of storage has been allocated, a pointer to it can be passed in this parameter to have the array copied to that storage.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMGetDeviceState

Gets the state of a device. (Deprecated in OS X v10.6.)

CMError CMGetDeviceState (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   CMDeviceState *deviceState
);
Parameters
deviceClass

A device class to query. See “Device Classes” for a list of the constants you can supply.

deviceID

A device ID to query. You can pass cmDefaultDeviceID.

deviceState

On output, points to the device state. See “Device States” for the values that can be returned.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetGammaByAVID

Obtains the gamma value for the specified display device. (Deprecated in OS X v10.6.)

CMError CMGetGammaByAVID (
   CMDisplayIDType theID,
   CMVideoCardGamma *gamma,
   UInt32 *size
);
Parameters
theID

A Display Manager ID value. You pass the ID value for the display device for which to set the gamma.

gamma
size
Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetImageSpace

Returns the signature of the data color space in which the color values of colors in an image are expressed. (Deprecated in OS X v10.6.)

CMError CMGetImageSpace (
   const FSSpec *spec,
   OSType *space
);
Parameters
spec

A file specification for the image file. See the File Manager documentation for a description of the FSSpec data type.

space

The signature of the data color space of the color values of colors for the image file is returned here.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMGetIndImageProfile

Obtains a specific embedded profile for a given image. (Deprecated in OS X v10.6.)

CMError CMGetIndImageProfile (
   const FSSpec *spec,
   UInt32 index,
   CMProfileRef *prof
);
Parameters
spec

A file specification for the image file. See the File Manager documentation for a description of the FSSpec data type.

index

The numeric index of the profile to return.

prof

On output, points to the profile.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMGetIndNamedColorValue

Obtains device and PCS color values for a specific named color index from a named color space profile. (Deprecated in OS X v10.6.)

CMError CMGetIndNamedColorValue (
   CMProfileRef prof,
   UInt32 index,
   CMColor *deviceColor,
   CMColor *PCSColor
);
Parameters
prof

A profile reference of type CMProfileRef to a named color space profile to obtain color values from.

index

A one-based index value for a named color.

deviceColor

A pointer to a device color. On return, a device color value in CMColor union format. If the profile does not contain device values, deviceColor is undefined.

PCSColor

A pointer to a profile connection space color. On return, an interchange color value in CMColor union format.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Based on the passed named color index, the CMGetIndNamedColorValue function does a lookup into the named color tag and returns device and PCS values. If the index is greater than the number of named colors, CMGetIndNamedColorValue returns an error code.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetIndProfileElement

Obtains the element data corresponding to a particular index from the specified profile. (Deprecated in OS X v10.6.)

CMError CMGetIndProfileElement (
   CMProfileRef prof,
   UInt32 index,
   UInt32 *elementSize,
   void *elementData
);
Parameters
prof

A profile reference of type CMProfileRef to the profile containing the element.

index

The index of the element whose data you want to obtain. This is a one-based element index within the range returned as the elementCount parameter of the CMCountProfileElements function.

elementSize

A pointer to an element data size. On input, specify the size of the element data to copy (except when elementData is set to NULL). Specify NULL to copy the entire element data. To obtain a portion of the element data, specify the number of bytes to be copy.

On return, the size of the element data actually copied.

elementData

A pointer to memory for element data. On input, you allocate memory. On return, this buffer holds the element data.

To obtain the element size in the elementSize parameter without copying the element data to this buffer, specify NULL for this parameter.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Before you call the CMGetIndProfileElement function to obtain the element data for an element at a specific index, you first determine the size in bytes of the element data. To determine the data size, you can

  • call the function CMGetIndProfileElementInfo, passing the element’s index

  • call the CMGetIndProfileElement function itself, specifying a pointer to an unsigned long data type in the elementSize field and a NULL value in the elementData field

Once you have determined the size of the element data, you allocate a buffer to hold as much of the data as you need. If you want all of the element data, you specify NULL in the elementSize parameter. If you want only a portion of the element data, you specify the number of bytes you want in the elementSize parameter. You supply a pointer to the data buffer in the elementData parameter. After calling CMGetIndProfileElement, the elementSize parameter contains the size in bytes of the element data actually copied.

Before calling this function, you should call the function CMCountProfileElements. It returns the profile’s total element count in the elementCount parameter.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetIndProfileElementInfo

Obtains the element tag and data size of an element by index from the specified profile. (Deprecated in OS X v10.6.)

CMError CMGetIndProfileElementInfo (
   CMProfileRef prof,
   UInt32 index,
   OSType *tag,
   UInt32 *elementSize,
   Boolean *refs
);
Parameters
prof

A profile reference of type CMProfileRef to the profile containing the element.

index

A one-based element index within the range returned by the elementCount parameter of the CMCountProfileElements function.

tag

A pointer to an element signature. On return, the tag signature of the element corresponding to the index.

elementSize

A pointer to an element size. On return, the size in bytes of the element data corresponding to the tag.

refs

A pointer to a reference count flag. On return, set to true if more than one tag in the profile refers to element data associated with the tag corresponding to the index.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The index order of elements is determined internally by the ColorSync Manager and is not publicly defined.

Before calling the CMGetIndProfileElementInfo function, you should call the function CMCountProfileElements, which returns the total number of elements in the profile in the elementCount parameter. The number you specify for the index parameter when calling CMGetIndProfileElementInfo should be in the range of 1 to elementCount; otherwise the function will return a result code of cmIndexRangeErr.

You might want to call this function, for example, to print out the contents of a profile.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetNamedColorIndex

Obtains a named color index for a specific color name from a named color space profile. (Deprecated in OS X v10.6.)

CMError CMGetNamedColorIndex (
   CMProfileRef prof,
   StringPtr name,
   UInt32 *index
);
Parameters
prof

A profile reference of type CMProfileRef to a named color space profile to obtain a named color index from.

name

A pointer to a Pascal string. You supply a color name string value for the color to obtain the color index for.

index

A pointer to an index value. On return, an index value for a named color.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Based on the passed color name, the CMGetNamedColorIndex function does a lookup into the named color tag and, if the name is found in the tag, returns the index. Otherwise, CMGetNamedColorIndex returns an error code.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetNamedColorInfo

Obtains information about a named color space from its profile reference. (Deprecated in OS X v10.6.)

CMError CMGetNamedColorInfo (
   CMProfileRef prof,
   UInt32 *deviceChannels,
   OSType *deviceColorSpace,
   OSType *PCSColorSpace,
   UInt32 *count,
   StringPtr prefix,
   StringPtr suffix
);
Parameters
prof

A profile reference of type CMProfileRef to a named color space profile to obtain named color information from.

deviceChannels

A pointer to a count value. On return, the number of device channels in the color space for the profile. It should agree with the “data color space” field in the profile header. For example, Pantone maps to CMYK, a four-channel color space. A value of 0 indicates no device channels were available.

deviceColorSpace

A pointer to a device color space. On return, a device color space, such as CMYK.

PCSColorSpace

A pointer to a profile connection space color space. On return, an interchange color space, such as Lab.

count

A pointer to a count value. On return, the number of named colors in the profile.

prefix

A pointer to a Pascal string. On return, the string contains a prefix, such as “Pantone”, for each color name. The prefix identifies the named color system described by the profile.

suffix

A pointer to a Pascal string. On return, the string contains a suffix for each color name, such as “CVC”.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMGetNamedColorInfo function returns information about the named color space referred to by the passed profile reference.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetNamedColorName

Obtains a named color name for a specific named color index from a named color space profile. (Deprecated in OS X v10.6.)

CMError CMGetNamedColorName (
   CMProfileRef prof,
   UInt32 index,
   StringPtr name
);
Parameters
prof

A profile reference of type CMProfileRef to a named color space profile to obtain a named color name from.

index

An index value for a named color to obtain the color name for.

name

A pointer to a Pascal string. On return, a color name string.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Based on the passed color name index, the CMGetNamedColorName function does a lookup into the named color tag and returns the name. If the index is greater than the number of named colors, CMGetNamedColorName returns an error code.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetNamedColorValue

Obtains device and PCS color values for a specific color name from a named color space profile. (Deprecated in OS X v10.6.)

CMError CMGetNamedColorValue (
   CMProfileRef prof,
   StringPtr name,
   CMColor *deviceColor,
   CMColor *PCSColor
);
Parameters
prof

A profile reference of type CMProfileRef to a named color space profile to obtain color values from.

name

A pointer to a Pascal string. You supply a color name string for the color to get information for.

deviceColor

A pointer to a device color. On return, a device color value in CMColor union format. If the profile does not contain device values, deviceColor is undefined.

PCSColor

A pointer to a profile connection space color. On return, an interchange color value in CMColor union format.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Based on the passed color name, the CMGetNamedColorValue function does a lookup into the named color tag and, if the name is found in the tag, returns device and color PCS values. Otherwise, CMGetNamedColorValue returns an error code.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetPartialProfileElement

Obtains a portion of the element data from the specified profile based on the specified element tag signature. (Deprecated in OS X v10.6.)

CMError CMGetPartialProfileElement (
   CMProfileRef prof,
   OSType tag,
   UInt32 offset,
   UInt32 *byteCount,
   void *elementData
);
Parameters
prof

A profile reference of type CMProfileRef to the profile containing the target element.

tag

The tag signature for the element in question. For a complete list of the tag signatures a profile may contain, including a description of each tag, refer to the International Color Consortium Profile Format Specification. The signatures for profile tags are defined in the CMICCProfile.h header file.

offset

Beginning from the first byte of the element data, the offset from which to begin copying the element data.

byteCount

A pointer to a data byte count. On input, the number of bytes of element data to copy, beginning from the offset specified by the offset parameter. On return, the number of bytes actually copied.

elementData

A pointer to memory for element data. On input, you pass a pointer to allocated memory. On return, this buffer holds the element data.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMGetPartialProfileElement function allows you to copy any portion of the element data beginning from any offset into the data. For the CMGetPartialProfileElement function to copy the element data and return it to you, your application must allocate a buffer in memory to hold the data.

You cannot use this function to obtain a portion of the CM2Header profile header. Instead, you must call the function CMGetProfileHeader to get the entire profile header and read its contents.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetPreferredCMM

Identifies the preferred CMM specified by the ColorSync control panel. (Deprecated in OS X v10.6.)

CMError CMGetPreferredCMM (
   OSType *cmmType,
   Boolean *prefCMMnotfound
);
Parameters
cmmType

A pointer to an OSType. On return, the component subtype for the preferred CMM. For example, the subtype for ColorSync’s default CMM is 'appl' and the subtype for the Kodak CMM is 'KCMS'. A return value of NULL indicates the preferred CMM in the ColorSync control panel is set to Automatic.

preferredCMMnotfound

A pointer to a Boolean flag for whether the preferred CMM was not found. On return, has the value true if the CMM was not found, false if it was found.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMGetPreferredCMM function returns in the cmmType parameter a value that identifies the preferred CMM the user last specified in the ColorSync control panel. CMGetPreferredCMM returns false in the preferredCMMnotfound parameter if the preferred CMM is currently available and true if it is not. The preferred CMM may not be available, for example, because a user specifies a preferred CMM in the ColorSync control panel, then reboots with extensions off. ColorSync does not change the preferred CMM setting when the preferred CMM is not available.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMGetProfileByAVID

Gets the current profile for a monitor. (Deprecated in OS X v10.6.)

CMError CMGetProfileByAVID (
   CMDisplayIDType theID,
   CMProfileRef *prof
);
Parameters
theAVID

A Display Manager ID value. You pass the ID value for the monitor for which to get the profile.

prof

A pointer to a profile reference. On return, a reference to the current profile for the monitor specified by theAVID.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

If the Display Manager supports ColorSync, the CMGetProfileByAVID function calls on the Display Manager to get the profile for the specified display. This is the case if the version of the Display Manager is 2.2.5 or higher (if gestaltDisplayMgrAttr has the gestaltDisplayMgrColorSyncAware bit set).

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
Declared In
ColorSyncDeprecated.h

CMGetProfileDescriptions

Obtains the description tag data for a specified profile. (Deprecated in OS X v10.6.)

CMError CMGetProfileDescriptions (
   CMProfileRef prof,
   char *aName,
   UInt32 *aCount,
   Str255 mName,
   ScriptCode *mCode,
   UniChar *uName,
   UniCharCount *uCount
);
Parameters
prof

A reference to the profile from which to obtain the description info.

aName

On output, a pointer to the profile name as a 7-bit Roman ASCII string.

aCount

On output, a pointer to a count of the number of characters returned in the aName field.

mName

On output, a pointer to the localized profile name string in Mac script-code format.

mCode

On output, a pointer the script code corresponding to the name string returned in the mName parameter.

uName

On output, a pointer to localizedUnicode profile name string.

uCount

On output, a pointer to a count of the number of Unicode (2-byte) characters returned in the uName parameter.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Use this function to get the description tag data for a given profile. The ICC Profile Format Specification (available at http://www.color.org ) includes a description tag ('desc' ), designed to provide more information about a profile than can be contained in a file name. This is especially critical on file systems with 8.3 names. The tag data can consist of up to three separate pieces (strings) of information for a profile. These different strings are designed to allow for display in different languages or on different computer systems. Applications typically use one of the strings to show profiles in a list or a pop-up menu.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetProfileElement

Obtains element data from the specified profile based on the specified element tag signature. (Deprecated in OS X v10.6.)

CMError CMGetProfileElement (
   CMProfileRef prof,
   OSType tag,
   UInt32 *elementSize,
   void *elementData
);
Parameters
prof

A profile reference of type CMProfileRef to the profile containing the target element.

tag

The tag signature (for example, ‘A2B0’, or constant cmAToB0Tag) for the element in question. The tag identifies the element. For a complete list of the public tag signatures a profile may contain, including a description of each tag, refer to the International Color Consortium Profile Format Specification. The signatures for profile tags are defined in the CMICCProfile.h header file.

elementSize

A pointer to a size value. On input, you specify the size of the element data to copy. Specify NULL to copy the entire element data. To obtain a portion of the element data, specify the number of bytes to copy.

On return, the size of the data returned.

elementData

A pointer to memory for element data. On input, you allocate memory. On return, this buffer holds the element data.

To obtain the element size in the elementSize parameter without copying the element data to this buffer, specify NULL for this parameter.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Before you call the CMGetProfileElement function to obtain the element data for a specific element, you must know the size in bytes of the element data so you can allocate a buffer to hold the returned data.

The CMGetProfileElement function serves two purposes: to get an element’s size and to obtain an element’s data. In both instances, you provide a reference to the profile containing the element in the prof parameter and the tag signature of the element in the tag parameter.

To obtain the element data size, call the CMGetProfileElement function specifying a pointer to an unsigned long data type in the elementSize field and a NULL value in the elementData field.

After you obtain the element size, you should allocate a buffer large enough to hold the returned element data, then call the CMGetProfileElement function again, specifying NULL in the elementSize parameter to copy the entire element data and a pointer to the data buffer in the elementData parameter.

To copy only a portion of the element data beginning from the first byte, allocate a buffer the size of the number of bytes of element data you want to obtain and specify the number of bytes to copy in the elementSize parameter. In this case, On return the elementSize parameter contains the size in bytes of the element data actually returned.

You cannot use the CMGetProfileElement function to copy a portion of element data beginning from an offset into the data. To copy a portion of the element data beginning from any offset, use the function CMGetPartialProfileElement.

You cannot use this function to obtain a portion of the CM2Header profile header. Instead, you must call the function CMGetProfileHeader to copy the entire profile header and read its contents.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetProfileHeader

Obtains the profile header for the specified profile. (Deprecated in OS X v10.6.)

CMError CMGetProfileHeader (
   CMProfileRef prof,
   CMAppleProfileHeader *header
);
Parameters
prof

A profile reference of type CMProfileRef to the profile whose header is to be copied.

header

A pointer to a profile header. On input, depending on the profile version, you may allocate a ColorSync 2.x or 1.0 header. On return, contains the profile data. For information about the ColorSync 2.x profile header structure, see CM2Header. For information about the ColorSync 1.0 header, see CMHeader.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMGetProfileHeader function returns the header for a ColorSync 2.x or ColorSync 1.0 profile. To return the header, the function uses a union of type CMAppleProfileHeader, with variants for version 1.0 and 2.x headers.

A 32-bit version value is located at the same offset in either header. For ColorSync 2.x profiles, this is the profileVersion field. For ColorSync 1.0 profiles, this is the applProfileVersion field. You can inspect the value at this offset to determine the profile version, and interpret the remaining header fields accordingly.

To copy a profile header to a profile after you modify the header’s contents, use the function CMSetProfileHeader.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetProfileLocation

Obtains the location of a profile based on the specified profile reference. (Deprecated in OS X v10.6.)

CMError CMGetProfileLocation (
   CMProfileRef prof,
   CMProfileLocation *location
);
Parameters
prof

A profile reference of type CMProfileRef. Before calling CMGetProfileLocation, you set the reference to specify the profile you wish to obtain the location for.

theProfile

A pointer to a profile location structure of type CMProfileLocation. On return, specifies the location of the profile. Commonly, a profile is disk-file based, but it may instead be temporary, handle-based, pointer-based, or accessed through a procedure supplied by your application.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

When your application calls the CMValidateProfile function, the ColorSync Manager dispatches the function to the CMM specified by the CMMType header field of the profile whose reference you specify. The preferred CMM can support this function or not.

To open a profile and obtain a reference to it, use the function CMOpenProfile.

Version Notes

This function is not recommended for use in ColorSync 2.5.

Starting with ColorSync version 2.5, you should use the function NCMGetProfileLocation instead of CMGetProfileLocation.

As of version 2.5, if you call CMGetProfileLocation, it will just call NCMGetProfileLocation in turn, passing the profile specified by prof, the profile location specified by theProfile, and a location size value of cmOriginalProfileLocationSize.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMGetProfileMD5

Gets the MD5 checksum from the profile header (message digest) (Deprecated in OS X v10.6.)

CMError CMGetProfileMD5 (
   CMProfileRef prof,
   CMProfileMD5 digest
);
Parameters
prof
digest
Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

You can call this function to determine if two profiles are identical, or if a profile has changed over time. You can access this new MD5 checksum directly in the profile header, or use the function CMGetProfileMD5. This function has the advantage that it works with both ICC 4 profiles and earlier profiles.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetProfileRefCount

Obtains the current reference count for the specified profile. (Deprecated in OS X v10.6.)

CMError CMGetProfileRefCount (
   CMProfileRef prof,
   long *count
);
Parameters
prof

A profile reference of type CMProfileRef to the profile whose reference count is obtained.

count

A pointer to a reference count. On return, the reference count for the specified profile reference.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The ColorSync Manager keeps an internal reference count for each profile reference returned from calls such as CMOpenProfile or CMNewProfile. Calling the function CMCloneProfileRef increments the count; calling the function CMCloseProfile decrements it. The profile remains open as long as the reference count is greater than 0, indicating at least one routine retains a reference to the profile. When the count reaches 0, the ColorSync Manager releases all memory, files, or resources allocated in association with that profile.

An application that manages profiles closely can call the CMGetProfileRefCount function to obtain the reference count for a profile reference, then perform special handling if necessary, based on the reference count.

To copy a profile with the function CMCopyProfile, you must obtain a reference to that profile by either opening the profile or creating it. To open a profile, use the function CMOpenProfile. To create a new profile, use the function CMNewProfile. As an alternative to using the CMCopyProfile function to duplicate an entire profile, you can use the same profile reference more than once. To do so, you call the function CMCloneProfileRef to increment the reference count for the reference each time you reuse it. Calling the CMCloneProfileRef function increments the count; calling the function CMCloseProfile decrements it. The profile remains open as long as the reference count is greater than 0, indicating at least one routine retains a reference to the profile.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetPS2ColorRendering

Obtains the color rendering dictionary (CRD) element data usable as the parameter to the PostScript setColorRendering operator, which specifies the PostScript color rendering dictionary to use for the following graphics data. (Deprecated in OS X v10.6.)

CMError CMGetPS2ColorRendering (
   CMProfileRef srcProf,
   CMProfileRef dstProf,
   UInt32 flags,
   CMFlattenUPP proc,
   void *refCon,
   Boolean *preferredCMMnotfound
);
Parameters
srcProf

A profile reference to a profile that supplies the rendering intent for the CRD.

dstProf

A profile reference to a profile from which to extract the CRD data.

flags

If the value of flags is equal to cmPS8bit, the generated PostScript will utilize 8-bit encoding whenever possible to achieve higher data compaction. If the value of flags is not equal to cmPS8bit, the generated data will be 7-bit safe, in either ASCII or ASCII base-85 encoding.

proc

A pointer to a callback flatten function to perform the data transfer. For information, see the function CMFlattenProcPtr.

refCon

An untyped pointer to arbitrary data supplied by your application. CMGetPS2ColorSpace passes this data in calls to your CMFlattenProcPtr function.

preferredCMMnotfound

A pointer to a flag for whether the preferred CMM was found. On return, has the value true if the CMM corresponding to profile was not available or if it was unable to perform the function and the default CMM was used. Otherwise, has the value false.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMGetPS2ColorRendering function obtains CRD data from the profile specified by the dstProf parameter. To be valid, the parameter must specify an output profile with at most four components. The CMM uses the rendering intent from the profile specified by the srcProf parameter to determine which of the PostScript tags (ps2CR0Tag, ps2CR1Tag, ps2CR2Tag, or ps2CR3Tag) to use in creating the CRD. If none of these tags exists in the profile, the CMM creates the CRD from one of the multidimensional table tags (cmAToB0, cmAToB1, or cmAToB2), again chosen according to the rendering intent of the profile specified by the srcProf parameter.

This function is dispatched to the CMM component specified by the destination profile. If the designated CMM is not available or the CMM does not implement this function, the ColorSync Manager dispatches this function to the default CMM.

The CMM obtains the PostScript data and passes it to your low-level data transfer procedure, specified by the proc parameter. The CMM converts the data into a PostScript stream and calls your procedure as many times as necessary to transfer the data to it. Typically, the low-level data transfer function returns this data to the calling application or device driver to pass to a PostScript printer.

Before your application or device driver sends the CRD to the printer, it can call the function CMGetPS2ColorRenderingVMSize to determine the virtual memory size of the CRD.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetPS2ColorRenderingIntent

Obtains the rendering intent element data in text format usable as the parameter to the PostScript findRenderingIntent operator, which specifies the color-matching option for subsequent graphics data. (Deprecated in OS X v10.6.)

CMError CMGetPS2ColorRenderingIntent (
   CMProfileRef srcProf,
   UInt32 flags,
   CMFlattenUPP proc,
   void *refCon,
   Boolean *preferredCMMnotfound
);
Parameters
srcProf

A profile reference to the source profile that defines the data color space and identifies the preferred CMM.

flags

If the value of flags is equal to cmPS8bit, the generated PostScript will utilize 8-bit encoding whenever possible to achieve higher data compaction. If the value of flags is not equal to cmPS8bit, the generated data will be 7-bit safe, in either ASCII or ASCII base-85 encoding.

proc

A low-level data transfer function supplied by the calling application to receive the PostScript data from the CMM. For more information, see the function CMFlattenProcPtr.

refCon

An untyped pointer to arbitrary data supplied by your application. CMGetPS2ColorSpace passes this data in calls to your CMFlattenProcPtr function.

preferredCMMnotfound

A pointer to a flag for whether the preferred CMM was found. On return, has the value true if the CMM corresponding to profile was not available or if it was unable to perform the function and the default CMM was used. Otherwise, has the value false.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMGetPS2ColorRenderingIntent function obtains PostScript rendering intent information from the header of the source profile. It returns data by calling your low-level data transfer procedure and passing the PostScript data to it. Typically, your low-level data transfer function returns this data to the calling application or device driver to pass to a PostScript printer.

The CMGetPS2ColorRenderingIntent function is dispatched to the CMM component specified by the source profile. If the designated CMM is not available or the CMM does not implement this function, then ColorSync dispatches the function to the default CMM.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetPS2ColorRenderingVMSize

Determines the virtual memory size of the color rendering dictionary (CRD) for a printer profile before your application or driver obtains the CRD and sends it to the printer. (Deprecated in OS X v10.6.)

CMError CMGetPS2ColorRenderingVMSize (
   CMProfileRef srcProf,
   CMProfileRef dstProf,
   UInt32 *vmSize,
   Boolean *preferredCMMnotfound
);
Parameters
srcProf

A profile reference to a profile that supplies the rendering intent for the CRD.

dstProf

A profile reference to the destination printer profile.

vmSize

A pointer to a memory size. On return, the virtual memory size of the CRD.

preferredCMMnotfound

A pointer to a flag for whether the preferred CMM was found. On return, has the value true if the CMM corresponding to profile was not available or if it was unable to perform the function and the default CMM was used. Otherwise, has the value false.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Your application or device driver can call this function to determine if the virtual memory size of the color rendering dictionary exceeds the printer’s capacity before sending the CRD to the printer. If the printer’s profile contains the Apple-defined optional tag 'psvm' described in CMConcatProfileSet, then the default CMM will return the data supplied by this tag specifying the CRD virtual memory size for the rendering intent’s CRD. If the printer’s profile does not contain this tag, then the CMM uses an algorithm to assess the VM size of the CRD, in which case the assessment can be larger than the actual maximum VM size.

The CMM uses the profile specified by the srcProf parameter to determine the rendering intent to use.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetPS2ColorSpace

Obtains color space element data in text format usable as the parameter to the PostScript setColorSpace operator, which characterizes the color space of subsequent graphics data. (Deprecated in OS X v10.6.)

CMError CMGetPS2ColorSpace (
   CMProfileRef srcProf,
   UInt32 flags,
   CMFlattenUPP proc,
   void *refCon,
   Boolean *preferredCMMnotfound
);
Parameters
srcProf

A profile reference to the source profile that defines the data color space and identifies the preferred CMM.

flags

If the value of flags is equal to cmPS8bit, the generated PostScript will utilize 8-bit encoding whenever possible to achieve higher data compaction. If the value of flags is not equal to cmPS8bit, the generated data will be 7-bit safe, in either ASCII or ASCII base-85 encoding.

proc

A pointer to a callback flatten function to receive the PostScript data from the CMM. For information, see the function CMFlattenProcPtr.

refCon

An untyped pointer to arbitrary data supplied by your application. CMGetPS2ColorSpace passes this data in calls to your CMFlattenProcPtr function.

preferredCMMnotfound

A pointer to a flag for whether the preferred CMM was found. On return, has the value true if the CMM corresponding to profile was not available or if it was unable to perform the function and the default CMM was used. Otherwise, has the value false.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMGetPS2ColorSpace function obtains PostScript color space data from the source profile. The valid profile classes for the CMGetPS2ColorSpace function are display, input, and output profiles with at most four components.

To determine which profile elements to use to generate the PostScript color space data, the CMM:

  • uses the PostScript cmPS2CSATag, if it exists

  • otherwise, uses the multidimensional table tag (cmAToB0, cmAToB1, or cmAToB2), if it exists, for the rendering intent currently specified by the profile

  • otherwise, uses the multidimensional table tag cmAToB0, if it exists

  • otherwise, for display profiles only, uses the tristimulus tags (cmRedColorantTag, cmGreenColorantTag, cmBlueColorantTag) and the tonal curve tags (cmRedTRCTag, cmGreenTRCTag, and cmBlueTRCTag)

The CMM obtains the PostScript data from the profile and calls your low-level data transfer procedure passing the PostScript data to it. The CMM converts the data into a PostScript stream and calls your procedure as many times as necessary to transfer the data to it.

Typically, the low-level data transfer function returns this data to the calling application or device driver to pass to a PostScript printer as an operand to the PostScript setcolorspace operator, which defines the color space of graphics data to follow.

The CMGetPS2ColorSpace function is dispatched to the CMM component specified by the source profile. If the designated CMM is not available or the CMM does not implement this function, then the ColorSync Manager dispatches the function to the default CMM.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMGetScriptProfileDescription

Obtains the internal name (or description) of a profile and the script code identifying the language in which the profile name is specified from the specified profile. (Deprecated in OS X v10.6.)

CMError CMGetScriptProfileDescription (
   CMProfileRef prof,
   Str255 name,
   ScriptCode *code
);
Parameters
prof

A profile reference of type CMProfileRef to the profile whose profile name and script code are obtained.

name

A pointer to a name string. On return, the profile name.

code

A pointer to a script code. On return, the script code.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The element data of the text description tag (which has the signature 'desc' or constant cmSigProfileDescriptionType, defined in the CMICCProfile.h header file) specifies the profile name and script code. The name parameter returns the profile name as a Pascal string. Use this function so that your application does not need to obtain and parse the element data, which contains other information.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMGetSystemProfile

Obtains a reference to the current system profile. (Deprecated in OS X v10.6.)

CMError CMGetSystemProfile (
   CMProfileRef *prof
);
Parameters
prof

A pointer to a profile reference of type CMProfileRef. On return, a reference to the current system profile.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The following functions allow you to pass NULL as a parameter value to specify the system profile as a source or destination profile:

Note that instead of passing NULL, you can pass a profile reference to a specific profile, including the system profile.

If you want to specify the system profile for any other function that requires a profile reference, such as CWConcatColorWorld and CWNewLinkProfile, you must use an explicit reference. You can obtain such a reference with the CMGetSystemProfile function.

There are other reasons you might need to obtain a reference to the current system profile. For example, your application might need to display the name of the current system profile to a user.

To identify the location of the physical file, call the function CMGetProfileLocation.

When your application has finished using the current system profile, it must close the reference to the profile by calling the function CMCloseProfile.

Version Notes

Starting with version 2.5, use of the system profile has changed. So rather than call CMGetSystemProfile to obtain a reference to the system profile, you may be able to obtain a profile that is more appropriate for the current operation by calling CMGetDefaultProfileBySpace to get the default profile for a color space or by calling CMGetProfileByAVID to get the profile for a specific display.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMIterateCMMInfo

Iterates through the color management modules installed on the system. (Deprecated in OS X v10.6.)

CMError CMIterateCMMInfo (
   CMMIterateUPP proc,
   UInt32 *count,
   void *refCon
);
Parameters
proc

A calling-program-supplied callback function that allows your application to monitor progress or abort the operation.

count

A pointer to the number of available CMMs.

refCon

A reference constant containing data specified by the calling application program.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMIterateCMMInfo function returns information for all CMMs installed on the system. The caller can pass nil for the CMMIterateUPP param to simply get a count of CMMs. If a CMMIterateUPP proc is provided, it is called once for each CMM installed - with the CMMInfo structure filled accordingly. The caller can pass a data reference to CMIterateCMMInfo which will then be passed to the CMMIterateUPP. This might be used to allow some of the information in the CMMInfo data structure to be put into a menu, for example, by passing a menu reference as the refcon. Either the proc or the count parameter must be provided. The caller will get a paramErr if both are nil.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMIterateColorDevices

Iterates through the color devices available on the system, returning device information to a callback you supply. (Deprecated in OS X v10.6.)

CMError CMIterateColorDevices (
   CMIterateDeviceInfoProcPtr proc,
   UInt32 *seed,
   UInt32 *count,
   void *refCon
);
Parameters
proc

A pointer to a function that iterates through device information available on the system. This is optional, but allows you to obtain device information. If provided, your callback is invoked once for each registered device.

seed

A pointer to a seed value. This is optional. If you pass a pointer to a seed value that is the same as the current seed value, then the callback function specified by the proc parameter is not invoked.

count

On output, the number of color devices available on the system.

refCon

An optional value that passed to your callback.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

This routine gets device information about all registered color devices. If provided, the supplied callback functions is called once for each registered device, passing in the device info and the supplied refcon.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMIterateColorSyncFolder

Iterates over the available profiles. (Deprecated in OS X v10.6.)

CMError CMIterateColorSyncFolder (
   CMProfileIterateUPP proc,
   UInt32 *seed,
   UInt32 *count,
   void *refCon
);
Parameters
proc

A universal procedure pointer of type CMProfileIterateUPP, which is described in CMProfileIterateData. If you do not wish to receive callbacks, pass NULL for this parameter. Otherwise, pass a pointer to your callback routine.

seed

A pointer to a value of type long. The first time you call CMIterateColorSyncFolder, you typically set the value to 0. In subsequent calls, you set the value to the seed value obtained from the previous call. ColorSync uses the value in determining whether to call your callback routine, as described in the discussion for this function.

On return, the value is the current seed for the profile cache (unless you pass NULL, as described in the discussion).

count

A pointer to a value of type long. On return, the value is the number of available profiles. CMIterateColorSyncFolder provides the number of profiles even when no iteration occurs (unless you pass NULL, as described in the discussion below). To determine the count alone, without iteration, call CMIterateColorSyncFolder and pass a value of NULL for all parameters except count.

refCon

An untyped pointer to arbitrary data supplied by your application. CMIterateColorSyncFolder passes this data to your callback routine. If you pass NULL for the refCon parameter, CMIterateColorSyncFolder passes NULL to your callback routine.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Starting with ColorSync version 2.5, when your application needs information about the profiles currently available in the ColorSync Profiles folder, it can call the CMIterateColorSyncFolder routine, which in turn calls your callback routine once for each profile.

Even though there may be many profiles available, CMIterateColorSyncFolder can take advantage of ColorSync’s profile cache to return profile information quickly, and (if the cache is valid) without having to open any profiles. For each profile, CMIterateColorSyncFolder supplies your routine with the profile header, script code, name, and location, in a structure of type CMProfileIterateData. As a result, your routine may be able to perform its function, such as building a list of profiles to display in a pop-up menu, without further effort (such as opening each file-based profile).

Only 2.x profiles are included in the profile search result.

Before calling CMIterateColorSyncFolder for the first time, you typically set seed to 0. ColorSync compares 0 to its current seed for the profile cache. It is not likely they will match—the odds are roughly one in two billion against it. If the values do not match, the routine iterates through all the profiles in the cache, calling your callback routine once for each profile. CMIterateColorSyncFolder then returns the actual seed value in seed (unless you passed NULL for that parameter).

If you pass the returned seed value in a subsequent call, and if there has been no change in the available profiles, the passed seed will match the stored cache seed and no iteration will take place.

Note that you can pass a NULL pointer for the seed parameter without harm. The result is the same as if you passed a pointer to 0, in that the function iterates through the available profiles, calling your callback routine once for each profile. However, the function does not return a seed value, since you have not passed a valid pointer.

You can force ColorSync to call your callback routine (if any profiles are available) by passing a NULL pointer or by passing 0 for the seed value. But suppose you have an operation, such as building a pop-up menu, that you only want to perform if the available profiles have changed. In that case, you pass the seed value from a previous call to CMIterateColorSyncFolder. If the profile folder has not changed, ColorSync will not call your callback routine.

Note that if there are no profiles available, ColorSync does not call your callback routine.

You can safely pass NULL for any or all of the parameters to the CMIterateColorSyncFolder function. If you pass NULL for all of the parameters, calling the function merely forces rebuilding of the profile cache, if necessary.

Version Notes

Starting with version 2.5, the name and location of the profile folder changed. In addition, the folder can now contain profiles within nested folders, as well as aliases to profiles or aliases to folders containing profiles. There are limits on the nesting of folders and aliases.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMIterateDeviceProfiles

Iterates through the device profiles available on the system and returns information about profiles of the devices to a callback you supply. (Deprecated in OS X v10.6.)

CMError CMIterateDeviceProfiles (
   CMIterateDeviceProfileProcPtr proc,
   UInt32 *seed,
   UInt32 *count,
   UInt32 flags,
   void *refCon
);
Parameters
proc

A pointer to a function that iterates through device information available on the system. This is optional, but allows you to obtain profile information for each device. If provided, your callback is invoked once for each registered device.

seed

A pointer to a seed value. This is optional. If you pass a pointer to a seed value that is the same as the current seed value, then the callback function specified by the proc parameter is not invoked.

count

On output, the number of color devices available on the system.

flags

A value that specifies which set of profiles you want to iterate through. It can have the following values: cmIterateFactoryDeviceProfiles, cmIterateCustomDeviceProfiles, cmIterateCurrentDeviceProfiles, cmIterateAllDeviceProfiles or 0. Supplying 0 is the same as supplying cmIterateCurrentDeviceProfiles.

refCon

An optional value that passed to your callback.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMLaunchControlPanel

Launches the ColorSync preferences pane. (Deprecated in OS X v10.6.)

CMError CMLaunchControlPanel (
   UInt32 flags
);
Parameters
flags

A value that specifies how the preferences pane is launched. You currently must pass a value of 0 for this parameter.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

When your application calls the function CMLaunchControlPanel, any changes made by the user will not be available (through calls such as CMGetDefaultProfileBySpace) until the user closes the ColorSync preferences pane. There is currently no ColorSync function that determines if the ColorSync preferences pane has been closed, but you can use the Process Manager API for this purpose.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMLinkImage

Matches an image file with a device link profile. (Deprecated in OS X v10.6.)

CMError CMLinkImage (
   const FSSpec *specFrom,
   const FSSpec *specInto,
   Boolean repl,
   UInt32 qual,
   CMProfileRef lnkProf,
   UInt32 lnkIntent
);
Parameters
specFrom

A file specification for the image file. See the File Manager documentation for a description of the FSSpec data type.

specInto

If this parameter is a file, it specifies the resulting image. If this parameter is a folder, it specifies the location of the resulting image which will have the same name as the original file. If this parameter is not provided, the original file is modified. See the File Manager documentation for a description of the FSSpec data type.

repl

If a file with the same name already exists, it will be replaced if this parameter is set to true.

qual

The optional quality for the match—normal, draft or best (cmNormalMode, cmDraftMode, or cmBestMode).

lnkProf

The device link profile for the match.

lnkIntent

The rendering intent for the match—perceptual intent, relative colorimetric intent, saturation intent , or absolute colorimetric intent (cmPerceptual, cmRelativecolorimetric, cmSaturation, or cmAbsoluteColorimetric ).

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMMakeProfile

Makes a display or abstract profile by modifying an existing one. (Deprecated in OS X v10.6.)

CMError CMMakeProfile (
   CMProfileRef prof,
   CFDictionaryRef spec
);
Parameters
prof

The profile to modify.

spec

A dictionary that specifies the modifications to make to the profile supplied in the prof parameter.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The function CMMakeProfile adds appropriate tags to a profile to make a display or abstract profile based on a specification dictionary you supply.

One key in the specification dictionary must be "profileType" with a CFString value of either "abstractLab", "displayRGB" or "displayID".

The dictionary can optionally contain these keys-value pairs:

  • "description", with an associated CFString value

  • "copyright", with an associated CFString value

For a profileType key whose value is "abstractLab", the dictionary can also contain the keys-value pairs listed in Table A-1.

Table A-1  Key-value pairs for “abstractLab”

Key

Value

Comment

"gridPoints"

A CFNumber (SInt32) that is an odd

Required

"proc"

A CFNumber (SInt64) coerced from a LabToLabProcPtr data type

Required

"refcon"

A CFNumber (SInt64) value coerced from a void* data type

Optional

For a profileType key whose value is "displayRGB", the dictionary can also contain the keys-value pairs listed in Table A-2.

Table A-2  Key-value pairs for “displayRGB”

Key

Value

Comment

"targetGamma"

A CFNumber (Float), for example, 1.8

Optional

"targetWhite"

A CFNumber (SInt32), for example, 6500

Optional

"gammaR

A CFNumber (Float), for example, 2.5

Required

"gammaG"

A CFNumber (Float), for example, 2.5

Required

"gammaB"

A CFNumber (Float), for example, 2.5

Required

"tableChans"

A CFNumber (SInt32), for example, 1 or 3

Optional

"tableEntries"

A CFNumber (SInt32), for example, 16 or 255

Optional

"tableEntrySize"

A CFNumber (SInt32), for example,1 or 2

Optional

"tableData"

A CFData (lut in RRRGGGBBB order)

Optional

"phosphorRx"

A CFNumber (Float)

Only if not supplying the phospherSet key.

phosphorRy"

A CFNumber (Float)

Only if not supplying the phospherSet key.

phosphorGx"

A CFNumber (Float)

Only if not supplying the phospherSet key.

"phosphorGy"

A CFNumber (Float)

Only if not supplying the phospherSet key.

"phosphorBx"

A CFNumber (Float)

Only if not supplying the phospherSet key.

"phosphorBy"

A CFNumber (Float)

Only if not supplying the phospherSet key.

"phosphorSet"

A CFString: "WideRGB", "700/525/450nm", "P22-EBU", "HDTV", "CCIR709", "sRGB", "AdobeRGB98" or "Trinitron"

Only if not supplying the phosphor R, G, B keys

"whitePointx"

A CFNumber (Float)

Only if not supplying a whiteTemp key

"whitePointy"

A CFNumber (Float)

Only if not supplying a whiteTemp key

"whiteTemp"

A CFNumber (SInt32), for example, 5000, 6500, or 9300

Only if not supplying whitePointx and whitePointy keys

For a profileType key whose value is "displayID", the dictionary can also contain the keys-value pairs in Table A-3

Table A-3  Key-value pairs for “displayID”

Key

Value

Comment

"targetGamma"

A CFNumber (Float), for example, 1.8

Optional

"targetWhite"

A CFNumber (SInt32), for example, 6500

Optional

"displayID"

A CFNumber (SInt32)

Required

Optionally, the keys-value pairs s for a profileType key whose value is "displayRGB" can be provided to override the values from the display.

Availability
  • Available in OS X v. 10.3 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMMatchImage

Color matches an image file. (Deprecated in OS X v10.6.)

CMError CMMatchImage (
   const FSSpec *specFrom,
   const FSSpec *specInto,
   Boolean repl,
   UInt32 qual,
   CMProfileRef srcProf,
   UInt32 srcIntent,
   CMProfileRef dstProf
);
Parameters
specFrom

A file specification for the image file. See the File Manager documentation for a description of the FSSpec data type.

specInto

If this parameter is a file, it specifies the resulting image. If this parameter is a folder, it specifies the location of the resulting image which will have the same name as the original file. If this parameter is not provided, the original file is modified. See the File Manager documentation for a description of the FSSpec data type.

repl

A Boolean value. If a file with the same name already exists, it will be replaced if this parameter is set to true.

qual

The optional quality for the match—normal, draft or best (cmNormalMode, cmDraftMode, or cmBestMode).

srcProf

The optional source profile for the match.

srcIntent

The rendering intent for the match—perceptual intent, relative colorimetric intent, saturation intent , or absolute colorimetric intent (cmPerceptual, cmRelativecolorimetric, cmSaturation, or cmAbsoluteColorimetric ).

dstProf

The destination profile for the match.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMNewProfile

Creates a new profile and associated backing copy. (Deprecated in OS X v10.6.)

CMError CMNewProfile (
   CMProfileRef *prof,
   const CMProfileLocation *theProfile
);
Parameters
prof

A pointer to a profile reference of type CMProfileRef. On return, a reference to the new profile.

theProfile

A pointer of type CMProfileLocation to the profile location where the new profile should be created. A profile is commonly disk-file based—the disk file type for a profile is 'prof'. However, to accommodate special requirements, you can create a handle- or pointer-based profile, you can create a temporary profile that is not saved after you call the CMCloseProfile function, or you can create a profile that is accessed through a procedure provided by your application. To create a temporary profile, you either specify cmNoProfileBase as the kind of profile in the profile location structure or specify NULL for this parameter.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMNewProfile function creates a new profile and backing copy in the location you specify. After you create the profile, you must fill in the profile header fields and populate the profile with tags and their element data, and then call the function CMUpdateProfile to save the element data to the profile file. The default ColorSync profile contents include a profile header of type CM2Header and an element table.

To set profile elements outside the header, you use the function CMSetProfileElement, the function CMSetProfileElementSize, and the function CMSetPartialProfileElement. You set these elements individually, identifying them by their tag names.

When you create a new profile, all fields of the CM2Header profile header are set to 0 except the size and profileVersion fields. To set the header elements, you call the function CMGetProfileHeader to get a copy of the header, assign values to the header fields, then call the function CMSetProfileHeader to write the new header to the profile.

For each profile class, such as a device profile, there is a specific set of elements and associated tags, defined by the ICC, that a profile must contain to meet the baseline requirements. The ICC also defines optional tags that a particular CMM might use to optimize or improve its processing. You can also define private tags, whose tag signatures you register with the ICC, to provide a CMM with greater capability to refine its processing.

After you fill in the profile with tags and their element data, you must call the CMUpdateProfile function to write the new profile elements to the profile file.

This function is most commonly used by profile developers who create profiles for device manufacturers and by calibration applications. In most cases, application developers use existing profiles.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMNewProfileSearch

Searches the ColorSync Profiles folder and returns a list of 2.x profiles that match the search specification. (Deprecated in OS X v10.6.)

CMError CMNewProfileSearch (
   CMSearchRecord *searchSpec,
   void *refCon,
   UInt32 *count,
   CMProfileSearchRef *searchResult
);
Parameters
searchSpec

A pointer to a search specification. For a description of the information you can provide in a search record of type CMSearchRecord to define the search, see CMSearchRecord. See the QuickDraw Reference for a description of the PixMap data type.

refCon

An untyped pointer to arbitrary data supplied by your application. CMNewProfileSearch passes this data to your filter routine. For a description of the filter routine, see the function CMProfileFilterProcPtr.

count

A pointer to a profile count. On return, a one-based count of profiles matching the search specification.

searchResult

A pointer to a search result reference. On return, a reference to the profile search result list. For a description of the CMProfileSearchRef private data type, see CMProfileSearchRef. See the QuickDraw Reference for a description of the PixMap data type.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMNewProfileSearch function sets up and defines a new search identifying through the search record the elements that a profile must contain to qualify for inclusion in the search result list. The function searches the ColorSync profiles folder for version 2.x profiles that meet the criteria and returns a list of these profiles in an internal private data structure whose reference is returned to you in the searchResult parameter.

You must provide a search record of type CMSearchRecord identifying the search criteria. You specify which fields of the search record to use for any given search through a search bit mask whose value you set in the search record’s searchMask field.

Among the information you can provide in the search record is a pointer to a filter function to use to eliminate profiles from the search based on additional criteria not defined by the search record. The search result reference is passed to the filter function after the search is performed. For a description of the filter function and its prototype, see the function CMProfileFilterProcPtr.

Your application cannot directly access the search result list. Instead, you pass the returned search result list reference to other search-related functions that allow you to use the result list.

When your application has completed its search, it should call the function CMDisposeProfileSearch to free the private memory allocated for the search.

To obtain a reference to a profile corresponding to a specific index in the list, use the function CMSearchGetIndProfile. To obtain the file specification for a profile corresponding to a specific index in the list, use the function CMSearchGetIndProfileFileSpec. To update the search result list, use the function CMUpdateProfileSearch. To free the private memory allocated for a profile search after your application has completed the search, use the function CMDisposeProfileSearch.

Version Notes

The CMNewProfileSearch function does not take full advantage of the optimized profile searching available starting with ColorSync version 2.5. Use CMIterateColorSyncFolder instead.

This function is not recommended for use in ColorSync 2.5.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMOpenProfile

Opens the specified profile and returns a reference to the profile. (Deprecated in OS X v10.6.)

CMError CMOpenProfile (
   CMProfileRef *prof,
   const CMProfileLocation *theProfile
);
Parameters
prof

A pointer to a profile reference of type CMProfileRef. On return, the reference refers to the opened profile.

theProfile

A pointer to a profile location of type CMProfileLocation for the profile to open. Commonly a profile is disk-file based, but it may instead be temporary, handle-based, pointer-based, or accessed through a procedure supplied by your application.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

If the CMOpenProfile function executes successfully, the profile reference refers to the opened profile. Your application uses this reference, for example, when it calls functions to color match, copy, and update a profile, and validate its contents.

The ColorSync Manager maintains private storage for each request to open a profile, allowing more than one application to use a profile concurrently.

When you create a new profile or modify the elements of an existing profile, the ColorSync Manager stores the new or modified elements in the private storage it maintains for your application. Any new or changed profile elements are not incorporated into the profile itself unless your application calls the function CMUpdateProfile to update the profile. If you call the function CMCopyProfile to create a copy of an existing profile under a new name, any changes you have made are incorporated in the profile duplicate but the original profile remains unchanged.

Before you call the CMOpenProfile function, you must set the CMProfileLocation data structure to identify the location of the profile to open. Most commonly, a profile is stored in a disk file. If the profile is in a disk file, use the profile location data type to provide its file specification. If the profile is in memory, use the profile location data type to specify a handle or pointer to the profile. If the profile is accessed through a procedure provided by your application, use the profile location data type to supply a universal procedure pointer to your procedure.

Your application must obtain a profile reference before you copy or validate a profile, and before you flatten the profile to embed it.

For example, your application can:

  • open a profile

  • call the CMGetProfileHeader function to obtain the profile’s header to modify its values

  • set new values

  • call the CMSetProfileHeader function to replace the modified header

  • pass the profile reference to a function such as NCWNewColorWorld as the source or destination profile in a color world for a color-matching session

  • When you close your reference to the profile by calling the function CMCloseProfile, your changes are discarded (unless you called the CMUpdateProfile function).

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMProfileElementExists

Tests whether the specified profile contains a specific element based on the element’s tag signature. (Deprecated in OS X v10.6.)

CMError CMProfileElementExists (
   CMProfileRef prof,
   OSType tag,
   Boolean *found
);
Parameters
prof

A profile reference of type CMProfileRef that specifies the profile to examine.

tag

The tag signature (for example, ‘A2B0’, or constant cmAToB0Tag) for the element in question. For a complete list of the tag signatures a profile may contain, including a description of each tag, refer to the International Color Consortium Profile Format Specification. The signatures for profile tags are defined in the CMICCProfile.h header file.

found

A pointer to a flag for whether the element was found. On return, the flag has the value true if the profile contains the element or false if it does not.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

You cannot use this function to test whether certain data in the CM2Header profile header exists. Instead, you must call the function CMGetProfileHeader to copy the entire profile header and read its contents.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMProfileIdentifierFolderSearch

Searches the ColorSync Profiles folder and returns a list of profile references, one for each profile that matches the specified profile identifier. (Deprecated in OS X v10.6.)

CMError CMProfileIdentifierFolderSearch (
   CMProfileIdentifierPtr ident,
   UInt32 *matchedCount,
   CMProfileSearchRef *searchResult
);
Parameters
ident

A pointer to a profile identifier structure specifying the profile to search for.

matchedCount

A pointer to a value of type unsigned long. On return, the one-based count of profiles that match the specified profile identifier. The count is typically 0 or 1, but can be higher.

searchResult

A pointer to a search result reference of type CMProfileSearchRef. On return, a reference to the profile search result list. Only version 2.x profiles are included in the profile search result.

Return Value

A CMError value. See “ColorSync Manager Result Codes.” It is not an error condition if this function finds no matching profiles. It returns an error only if a File Manager or other low-level system error occurs.

Discussion

When your application or device driver processes an image, it can keep a list of profile references for each profile it encounters in the image. Each time it encounters an embedded profile identifier, your application can call the function CMProfileIdentifierListSearch to see if there is already a matching profile reference in its list. If not, it can call the CMProfileIdentifierFolderSearch function to see if the profile is located in the ColorSync Profiles folder.

Although there should typically be at most one profile in the ColorSync Profiles folder that matches the profile identifier, two or more profiles with different filenames may qualify.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMProfileIdentifierListSearch

Searches a list of profile references and returns a list of all references that match a specified profile identifier. (Deprecated in OS X v10.6.)

CMError CMProfileIdentifierListSearch (
   CMProfileIdentifierPtr ident,
   CMProfileRef *profileList,
   UInt32 listSize,
   UInt32 *matchedCount,
   CMProfileRef *matchedList
);
Parameters
ident

A pointer to a profile identifier. The function looks for profile references in profileList that match the profile described by this identifier. For information on how a profile identifier match is determined, see CMProfileIdentifier.

profileList

A pointer to a list of profile references to search.

listSize

The number of profile references in profileList.

matchedCount

A pointer to a count of matching profile references. If you set matchedList to NULL, On return matchedCount specifies the number of references in profileList that match ident. The count is typically 0 or 1, but can be higher.

If you do not set matchedList to NULL, on input you set matchedCount to the maximum number of matching references to be returned in matchedList. On return, the value of matchedCount specifies the actual number of matching references returned, which is always equal to or less than the number passed in.

matchedList

A pointer to a list of profile references. If you set matchedList to NULL on input, On return nothing is returned in the parameter, and the actual number of matching references is returned in matchedCount.

If you do not set matchedList to NULL on input, it is treated as a pointer to allocated memory. On return, the allocated memory will contain a list, in no particular order, of profile references that match ident. Only version 2.x profiles are included in the profile search result. The number of references in the list is equal to or less than the value you pass in the matchedCount parameter. You must allocate enough memory for matchedList to store the requested number of profile references.

Return Value

A CMError value. See “ColorSync Manager Result Codes.” It is not an error condition if the CMProfileIdentifierListSearch function finds no matching profiles. The function returns an error only if a Memory Manager or other low-level system error occurs.

Discussion

When your application or device driver processes an image, it can keep a list of profile references for each unique profile or profile identifier it encounters in the image. Each time it encounters an embedded profile identifier, your application can call the CMProfileIdentifierListSearch function to see if there is already a matching profile reference in the list. Although your list of profile references would normally contain at most one reference that matches the profile identifier, it is possible to have two or more matches. For information on how a profile identifier match is determined, see CMProfileIdentifier.

If no matching profile is found in the list, your application can call the function CMProfileIdentifierFolderSearch to see if a matching profile can be found in the ColorSync Profiles folder.

To determine the amount of memory needed for the list of profile references that match a profile identifier, your application may want to call CMProfileIdentifierListSearch twice. The first time, on input you set matchedList to NULL and ignore matchedCount. On return, matchedCount specifies the number of matching profiles. You then allocate enough memory to hold that many profile references (or a smaller number if you do not want all the references) and call CMProfileIdentifierListSearch again. This time you set matchedList to a pointer to the allocated memory and set matchedCount to the number of references you wish to obtain. To allocate memory, you use code such as the following:

myProfileRefListPtr = NewPtr(sizeof(CMProfileRef) * matchedCount);

If your application is interested in obtaining only the first profile that matches the specified profile, you need call CMProfileIdentifierListSearch only once. To do so, you just allocate enough memory to store one profile reference, set matchedList to point to that memory (or just set matchedList to point to a local variable), and set matchedCount to 1. On return, if matchedCount still has the value 1, then CMProfileIdentifierListSearch found a matching profile.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMProfileModified

Indicates whether the specified profile has been modified since it was created or last updated. (Deprecated in OS X v10.6.)

CMError CMProfileModified (
   CMProfileRef prof,
   Boolean *modified
);
Parameters
prof

A profile reference of type CMProfileRef to the profile to examine.

modified

A pointer to a Boolean variable. On return, the value of modified is set to true if the profile has been modified, false if it has not.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

When a profile is first opened, its modified flag is set to false. On calls that add to, delete from, or set the profile header or tags, the modified flag is set to true. After calling the function CMUpdateProfile, the modified flag is reset to false.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMProofImage

Proofs an image. (Deprecated in OS X v10.6.)

CMError CMProofImage (
   const FSSpec *specFrom,
   const FSSpec *specInto,
   Boolean repl,
   UInt32 qual,
   CMProfileRef srcProf,
   UInt32 srcIntent,
   CMProfileRef dstProf,
   CMProfileRef prfProf
);
Parameters
specFrom

The destination profile for the match. See the File Manager documentation for a description of the FSSpec data type.

specInto

If this parameter is a file, it specifies the resulting image. If this parameter is a folder, it specifies the location of the resulting image which will have the same name as the original file. If this parameter is not provided, the original file is modified. See the File Manager documentation for a description of the FSSpec data type.

repl

A Boolean value. If a file with the same name already exists, it will be replaced if this parameter is set to true.

qual

The optional quality for the match—normal, draft or best (cmNormalMode, cmDraftMode, or cmBestMode).

srcProf

The optional source profile for the match.

srcIntent

The rendering intent for the match—perceptual intent, relative colorimetric intent, saturation intent , or absolute colorimetric intent (cmPerceptual, cmRelativecolorimetric, cmSaturation, or cmAbsoluteColorimetric ).

dstProf

The destination profile for the match.

prfProf

The proof profile for the match between the destination and proof profiles.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMRegisterColorDevice

Registers a device with ColorSync. (Deprecated in OS X v10.6.)

CMError CMRegisterColorDevice (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   CFDictionaryRef deviceName,
   const CMDeviceScope *deviceScope
);
Parameters
deviceSpec

The class of the device (e.g., 'scnr' ,'cmra' ,'prtr' ,'mntr' ).

deviceScope

The unique identifier of the class (Class + ID uniquely id's device).

deviceName

Name of the device. See the CFDictionary documentation for a description of the CFDictionaryRef data type.

deviceScope

Structure defining the user and host scope this device pertains to.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

For a device to be recognized by ColorSync (and possibly other parts of OS X) it needs to register itself using this function. If the device has ColorSync profiles associated with it, it should identify those u after registering with this function. Once a device is registered, it can appear as an input, output, or proofing device in ColorSync controls, as long as it has profiles associated with it. Registration need only happen once, when the device is installed. Device drivers need not register their device each time they are loaded.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMRemoveProfileElement

Removes an element corresponding to a specific tag from the specified profile. (Deprecated in OS X v10.6.)

CMError CMRemoveProfileElement (
   CMProfileRef prof,
   OSType tag
);
Parameters
prof

A profile reference of type CMProfileRef to the profile containing the tag remove.

tag

The tag signature for the element to remove.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMRemoveProfileElement function deletes the tag as well as the element data from the profile.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSearchGetIndProfile

Opens the profile corresponding to a specific index into a specific search result list and obtains a reference to that profile. (Deprecated in OS X v10.6.)

CMError CMSearchGetIndProfile (
   CMProfileSearchRef search,
   UInt32 index,
   CMProfileRef *prof
);
Parameters
search

A reference to the profile search result list containing the profile whose reference you want to obtain. For a description of the CMProfileSearchRef private data type, see CMProfileSearchRef. See the QuickDraw Reference for a description of the PixMap data type.

index

The position of the profile in the search result list. This value is specified as a one-based index into the set of profiles of the search result. The index must be less than or equal to the value returned as the count parameter of the CMNewProfileSearch function or the CMUpdateProfileSearch function; otherwise CMSearchGetIndProfile returns a result code of cmIndexRangeErr.

prof

A pointer to a profile reference of type CMProfileRef. On return, the reference refers to the profile associated with the specified index. See the QuickDraw Reference for a description of the PixMap data type.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Before your application can call the CMSearchGetIndProfile function, it must call the function CMNewProfileSearch to perform a profile search and produce a search result list. The search result list is a private data structure maintained by the ColorSync Manager. After your application has finished using the profile reference, it must close the reference by calling the function CMCloseProfile.

Version Notes

This function is not recommended for use in ColorSync 2.5.

Starting with version 2.5, you should use the function CMIterateColorSyncFolder for profile searching.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMSearchGetIndProfileFileSpec

Obtains the file specification for the profile at a specific index into a search result. (Deprecated in OS X v10.6.)

CMError CMSearchGetIndProfileFileSpec (
   CMProfileSearchRef search,
   UInt32 index,
   FSSpec *spec
);
Parameters
search

A reference to the profile search result containing the profile whose file specification you want to obtain. For a description of the CMProfileSearchRef private data type, see CMProfileSearchRef. See the QuickDraw Reference for a description of the PixMap data type.

index

The index of the profile whose file specification you want to obtain. This is a one-based index into a set of profiles in the search result list. The index must be less than or equal to the value returned as the count parameter of the CMNewProfileSearch function or the CMUpdateProfileSearch function; otherwise CMSearchGetIndProfile returns a result code of cmIndexRangeErr.

profileFile

A pointer to a file specification. On return, this parameter points to a file specification for the profile at the location specified by index. See the QuickDraw Reference for a description of the PixMap data type.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Before your application can call the CMSearchGetIndProfileFileSpec function, it must call the function CMNewProfileSearch to perform a profile search and produce a search result list. The search result list is a private data structure maintained by ColorSync.

The CMSearchGetIndProfileFileSpec function obtains the Macintosh file system file specification for a profile at a specific index in the search result list.

Version Notes

This function is not recommended for use in ColorSync 2.5.

Starting with version 2.5, you should use the function CMIterateColorSyncFolder for profile searching.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMSetDefaultDevice

Sets the default device. (Deprecated in OS X v10.6.)

CMError CMSetDefaultDevice (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID
);
Parameters
deviceClass

The class of the device (e.g., 'scnr' ,'cmra' ,'prtr' ,'mntr' ).

deviceID

The unique identifier of the class (Class + ID uniquely id's device).

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

For each class of device, a device management layer may establish which of the registered devices is the default. This helps keep color management choices to a minimum and allows for some "automatic" features to be enabled, such as, "Default printer" as an output profile selection. If no such device (as specified by deviceClass and deviceID ) has been registered, an error is returned.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetDefaultProfileBySpace

Sets the default profile for the specified color space. (Deprecated in OS X v10.6.)

CMError CMSetDefaultProfileBySpace (
   OSType dataColorSpace,
   CMProfileRef prof
);
Parameters
dataColorSpace

A four-character identifier of type OSType. You pass a color space signature that identifies the color space you wish to set the default profile for. The currently-supported values are cmRGBData, cmCMYKData, cmLabData, and cmXYZData. These constants are a subset of the constants described in “Color Space Signatures.” If you supply a value that is not supported, the CMGetDefaultProfileBySpace function returns an error value of paramErr.

prof

A profile reference. Before calling CMSetDefaultProfileBySpace, set the reference to specify the default profile for the color space. The profile must be file-based; otherwise, the function returns a CMInvalidProfileLocation error.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMSetDefaultProfileBySpace function currently supports the RGB, CMYK, Lab, and XYZ color spaces. The signature constants for these color spaces (shown above with the dataColorSpace parameter description) are described in “Color Space Signatures.” Support for additional color spaces may be provided in the future. CMSetDefaultProfileBySpace returns a value of paramErr if you pass a color space constant it does not currently support.

Note that a user can also use the ColorSync control panel to specify a default profile for the RGB and CMYK color spaces.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMSetDefaultProfileByUse

Sets values for device profile settings. (Deprecated in OS X v10.6.)

CMError CMSetDefaultProfileByUse (
   OSType use,
   CMProfileRef prof
);
Parameters
use

A value that specifies the device type for which to set the profile.

prof
Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMSetDeviceDefaultProfileID

Sets the default profile ID for a given device. (Deprecated in OS X v10.6.)

CMError CMSetDeviceDefaultProfileID (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   CMDeviceProfileID defaultProfID
);
Parameters
deviceClass

The device class for the device whose default profile you want to set. See “Device Classes” for a list of the constants you can supply.

deviceID

The device ID for the device whose default profile you want to set.

defaultID

The ID of profile you want to set as the default.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The default profile ID for a given device is an important piece of information because of the function CMGetProfileByUse. The function CMGetProfileByUse returns the default profile for devices depending on the user's selection in the ColorSync preferences pane. Device drivers and host software can set the default profile for a given device using the function CMSetDeviceDefaultProfileID.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetDeviceFactoryProfiles

Establishes the profiles used by a given device. (Deprecated in OS X v10.6.)

CMError CMSetDeviceFactoryProfiles (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   CMDeviceProfileID defaultProfID,
   const CMDeviceProfileArray *deviceProfiles
);
Parameters
deviceClass

The device class for the device whose factory profiles you want to establish. See “Device Classes” for a list of the constants you can supply.

deviceID

The device ID for the device whose factory profiles you want to establish.

defaultProfID

The ID of the default profile for this device.

deviceProfiles

On output, points to array that contains the factory device profiles.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

This function establishes the profiles used by a given device. It should be called after device registration to notify ColorSync of the device's profiles. Note that factory device profiles and the current device profiles might not be the same, since the latter may contain modifications to the factory set.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetDeviceProfile

Change the profile used by a given device. (Deprecated in OS X v10.6.)

CMError CMSetDeviceProfile (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   const CMDeviceProfileScope *profileScope,
   CMDeviceProfileID profileID,
   const CMProfileLocation *profileLoc
);
Parameters
deviceClass

The device class for the device whose profile you want to set. See “Device Classes” for a list of the constants you can supply.

deviceID

The device ID for the device whose profile you want to set.

profileScope

A pointer to the structure defining the scope this profile pertains to.

profileID

The ID of the default profile for this device.

deviceProfLoc

A pointer to the CMProfileLocation of the profile. Since this structure is a fixed length structure, you can simply pass a pointer to a stack-based structure or memory allocated for it.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

This function provides a way to change a profile used by a given device by ID. It can be called after device registration by calibration applications to reset a device's profile from factory defaults to calibrated profiles. In order for this call to be made successfully, you must pass the CMDeviceClass and CMDeviceID of the device being calibrated along with the CMDeviceProfileID of the profile to set. (Device selection and identification can be facilitated using the function CMIterateColorDevices). If an invalid CMDeviceClass or CMDeviceID is passed, an error (CMInvalidDeviceClass or CMInvalidDeviceID) is returned.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetDeviceProfiles

Changes the profiles used by a given device. (Deprecated in OS X v10.6.)

CMError CMSetDeviceProfiles (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   const CMDeviceProfileScope *profileScope,
   const CMDeviceProfileArray *deviceProfiles
);
Parameters
deviceClass

The device class for the device whose profiles you want to set. See “Device Classes” for a list of the constants you can supply.

deviceID

The device ID for the device whose profiles you want to set.

profileScope

A pointer to the structure defining the scope these profiles pertain to.

deviceProfiles

A pointer to the profile array that contains replacements for the factory profiles. You don’t have to replace all the original profiles with this call. The array can contain as few as one profile or as many profiles as there are in the original factory array. You supply only those profiles you want to replace. Profiles are replaced by ID.

Return Value

A CMError value. If you pass a n invalid CMDeviceClass or CMDeviceID, the function returns CMInvalidDeviceClass or CMInvalidDeviceID. See “ColorSync Manager Result Codes.”

Discussion

This function provides a way to change the profiles used by a given device. It can be called after device registration by calibration applications to reset a device's profiles from factory defaults to calibrated profiles. In order for this call to be made successfully, the caller must pass the CMDeviceClass and CMDeviceID device being calibrated. (You can call the function CMIterateColorDevices to find available device classes and IDs.).

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMSetDeviceState

Sets the state of a device. (Deprecated in OS X v10.6.)

CMError CMSetDeviceState (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   CMDeviceState deviceState
);
Parameters
deviceClass

The device class for the device whose state you want to set. See “Device Classes” for a list of the constants you can supply.

deviceID

The device ID for the device whose state you want to set.

deviceState

The device state to set. See “Device States” for the values you can supply.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

This routines provides access for the device management layer to update the state of a particular device. For example, a device can be offline, busy, or calibrated. The state data passed in replaces the old state data with the value you supply.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetGammaByAVID

Sets the gamma for the specified display device. (Deprecated in OS X v10.6.)

CMError CMSetGammaByAVID (
   CMDisplayIDType theID,
   CMVideoCardGamma *gamma
);
Parameters
theID

A Display Manager ID value. You pass the ID value for the display device for which to set the gamma.

gamma

A pointer to the gamma value to which you want to set the display device.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetIndImageProfile

Sets a specific embedded profile for a given image. (Deprecated in OS X v10.6.)

CMError CMSetIndImageProfile (
   const FSSpec *specFrom,
   const FSSpec *specInto,
   Boolean repl,
   UInt32 index,
   CMProfileRef prof
);
Parameters
specFrom

A file specification for the image file. See the File Manager documentation for a description of the FSSpec data type.

specInto

If this parameter is a file, it specifies the resulting image. If this parameter is a folder, it specifies the location of the resulting image which will have the same name as the original file. If this parameter is not provided, the original file is modified. See the File Manager documentation for a description of the FSSpec data type.

repl

A Boolean value. If a file with the same name already exists, it will be replaced if this parameter is set to true.

index

The numeric index of the profile to set.

prof

The profile to set at the index designated by the index parameter.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMSetPartialProfileElement

Sets part of the element data for a specific tag in the specified profile. (Deprecated in OS X v10.6.)

CMError CMSetPartialProfileElement (
   CMProfileRef prof,
   OSType tag,
   UInt32 offset,
   UInt32 byteCount,
   const void *elementData
);
Parameters
prof

A profile reference of type CMProfileRef to the profile containing the tag for which the element data is set.

tag

The tag signature for the element whose data is set. The tag identifies the element. For a complete list of the tag signatures a profile may contain, including a description of each tag, refer to the International Color Consortium Profile Format Specification. The signatures for profile tags are defined in the CMICCProfile.h header file.

offset

The offset in the existing element data where data transfer should begin.

byteCount

The number of bytes of element data to transfer.

elementData

A pointer to the buffer containing the element data to transfer to the profile.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

You can use the CMSetPartialProfileElement function to set the data for an element when the amount of data is large and you need to copy it to the profile in segments.

After you set the element size, you can call this function repeatedly, as many times as necessary, each time appending a segment of data to the end of the data already copied until all the element data is copied.

If you know the size of the element data, you should call the function CMSetProfileElementSize to reserve it before you call CMSetPartialProfileElement to set element data in segments. Setting the size first avoids the extensive overhead required to increase the size for the element data with each call to append another segment of data.

To copy the entire data for an element as a single operation, when the amount of data is small enough to allow this, call the function CMSetProfileElement.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetProfileByAVID

Sets the profile for the specified monitor, optionally setting video card gamma. (Deprecated in OS X v10.6.)

CMError CMSetProfileByAVID (
   CMDisplayIDType theID,
   CMProfileRef prof
);
Parameters
theAVID

A Display Manager ID value. You pass the ID value for the monitor for which to set the profile.

prof

A profile reference. Before calling CMSetProfileByAVID, set the reference to identify the profile for the monitor specified by theAVID.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

If you specify a profile that contains the optional profile tag for video card gamma, CMSetProfileByAVID extracts the tag and sets the video card based on the tag data. This is the only ColorSync function that sets video card gamma. The tag constant cmVideoCardGammaTag is described in “Video Card Gamma Tags.”

When a user sets a display profile using the Monitors & Sound control panel, the system profile is set to the same profile. When you call CMSetProfileByAVID to set a profile for a monitor, you may also wish to make that profile the system profile. If so, you must call CMSetSystemProfile explicitly—calling CMSetProfileByAVID alone has no affect on the system profile.

Note that if the Display Manager supports ColorSync, the CMSetProfileByAVID function calls on the Display Manager to set the profile for the specified display. This is the case if the version of the Display Manager is 2.2.5 or higher (if gestaltDisplayMgrAttr has the gestaltDisplayMgrColorSyncAware bit set).

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetProfileDescriptions

Sets the description tag data for a specified profile. (Deprecated in OS X v10.6.)

CMError CMSetProfileDescriptions (
   CMProfileRef prof,
   const char *aName,
   UInt32 aCount,
   ConstStr255Param mName,
   ScriptCode mCode,
   const UniChar *uName,
   UniCharCount uCount
);
Parameters
prof

A reference to the profile into which to set the description tag data.

aName

A pointer to a 7-bit Roman ASCII profile name string to be set for the profile. This string must be null-terminated.

aCount

A count of the number of characters in the string specified in the aName parameter

mName

A pointer to the localized profile name string in Mac script-code format which is to be set for the profile. This string must be null-terminated.

mCode

The script code corresponding to the string specified by the mName parameter.

uName

A pointer to the localized Unicode profile name string which is to be set for the profile. This string must be null-terminated

uCount

A count of the number of Unicode characters in string specified by the uName parameter. Do not confuse this with a byte count, because each Unicode character requires two bytes.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Use this function to set the description tag data for a given profile. The ICC Profile Format Specification (available at http://www.color.org) includes a description tag ( 'desc' ), designed to provide more information about a profile than can be contained in a file name. This is especially critical on file systems with 8.3 names. The tag data can consist of up to three separate pieces (strings) of information for a profile. These different strings are designed to allow for display in different languages or on different computer systems. Applications typically use one of the strings to show profiles in a list or a pop-up menu.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetProfileElement

Sets or replaces the element data for a specific tag in the specified profile. (Deprecated in OS X v10.6.)

CMError CMSetProfileElement (
   CMProfileRef prof,
   OSType tag,
   UInt32 elementSize,
   const void *elementData
);
Parameters
prof

A profile reference of type CMProfileRef to the profile containing the tag for which the element data is set.

tag

The tag signature for the element whose data is set. For a complete list of the tag signatures a profile may contain, including a description of each tag, refer to the International Color Consortium Profile Format Specification. The signatures for profile tags are defined in the CMICCProfile.h header file.

elementSize

The size in bytes of the element data set.

elementData

A pointer to the buffer containing the element data to transfer to the profile.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMSetProfileElement function replaces existing element data if an element with the specified tag is already present in the profile. Otherwise, it sets the element data for a new tag. Your application is responsible for allocating memory for the buffer to hold the data to transfer.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetProfileElementReference

Adds a tag to the specified profile to refer to data corresponding to a previously set element. (Deprecated in OS X v10.6.)

CMError CMSetProfileElementReference (
   CMProfileRef prof,
   OSType elementTag,
   OSType referenceTag
);
Parameters
prof

A profile reference of type CMProfileRef to the profile to add the tag to.

elementTag

The original element’s signature tag corresponding to the element data to which the new tag will refer.

referenceTag

The new tag signature to add to the profile to refer to the element data corresponding to elementTag.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

After the CMSetProfileElementReference function executes successfully, the specified profile will contain more than one tag corresponding to a single piece of data. All of these tags are of equal importance. Your application can set a reference to an element that was originally a reference itself without circularity.

If you call the function CMSetProfileElement subsequently for one of the tags acting as a reference to another tag’s data, then the element data you provide is set for the tag and the tag is no longer considered a reference. Instead, the tag corresponds to its own element data and not that of another tag.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetProfileElementSize

Reserves the element data size for a specific tag in the specified profile before setting the element data. (Deprecated in OS X v10.6.)

CMError CMSetProfileElementSize (
   CMProfileRef prof,
   OSType tag,
   UInt32 elementSize
);
Parameters
prof

A profile reference of type CMProfileRef to the profile in which the element data size is reserved.

tag

The tag signature for the element whose size is reserved. The tag identifies the element. For a complete list of the tag signatures a profile may contain, including a description of each tag, refer to the International Color Consortium Profile Format Specification. The signatures for profile tags are defined in the CMICCProfile.h header file.

elementSize

The total size in bytes to reserve for the element data.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Your application can use the CMSetProfileElementSize function to reserve the size of element data for a specific tag before you call the function CMGetPartialProfileElement to set the element data. The most efficient way to set a large amount of element data when you know the size of the data is to first set the size, then call the CMSetPartialProfileElement function to set each of the data segments. Calling the CMSetProfileElementSize function first eliminates the need for the ColorSync Manager to repeatedly increase the size for the data each time you call the CMSetPartialProfileElement function.

In addition to reserving the element data size, the CMSetProfileElementSize function sets the element tag, if it does not already exist.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetProfileHeader

Sets the header for the specified profile. (Deprecated in OS X v10.6.)

CMError CMSetProfileHeader (
   CMProfileRef prof,
   const CMAppleProfileHeader *header
);
Parameters
prof

A profile reference of type CMProfileRef to the profile whose header is set.

header

A pointer to the new header to set for the profile.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

You can use the CMSetProfileHeader function to set a header for a version 1.0 or a version 2.x profile. Before you call this function, you must set the values for the header, depending on the version of the profile. For a version 2.x profile, you use a data structure of type CM2Header. For a version 1.0 profile, you use a data structure of type CMHeader. You pass the header you supply in the CMAppleProfileHeader union, described in CMAppleProfileHeader.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetProfileLocalizedStringDictionary

Writes a dictionary of localized strings to a given tag in a profile. (Deprecated in OS X v10.6.)

CMError CMSetProfileLocalizedStringDictionary (
   CMProfileRef prof,
   OSType tag,
   CFDictionaryRef theDict
);
Parameters
prof

The profile to modify.

tag

The tag type of profile to modify.

theDict

The dictionary to modify. See the CFDictionary documentation for a description of the CFDictionaryRef data type.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMSetSystemProfile

Sets the current system profile. (Deprecated in OS X v10.6.)

CMError CMSetSystemProfile (
   const FSSpec *profileFileSpec
);
Parameters
profileFileSpec

A pointer to a file specification structure. Before calling CMSetSystemProfile, set the structure to specify the desired system profile.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

By default, a standard RGB profile is configured as the system profile. By calling the CMSetSystemProfile function, your application can specify a new system profile. You can configure only a display device profile as the system profile.

Version Notes

Starting with version 2.5, use of the system profile has changed.

The function CMSetSystemProfile does not retrieve video card gamma data (introduced in ColorSync version 2.5) to set the video card; use the function CMSetProfileByAVID instead.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMUnembedImage

Removes any ICC profiles embedded in an image. (Deprecated in OS X v10.6.)

CMError CMUnembedImage (
   const FSSpec *specFrom,
   const FSSpec *specInto,
   Boolean repl
);
Parameters
specFrom

A file specification for the image file. See the File Manager documentation for a description of the FSSpec data type.

specInto

If this parameter is a file, it specifies the resulting image. If this parameter is a folder, it specifies the location of the resulting image which will have the same name as the original file. If his parameter is not provided, the original file is modified. See the File Manager documentation for a description of the FSSpec data type.

repl

A Boolean value. If a file with the same name already exists, it will be replaced if this parameter is set to true.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMUnregisterColorDevice

Unregisters a device. (Deprecated in OS X v10.6.)

CMError CMUnregisterColorDevice (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID
);
Parameters
deviceClass

The device class of the device you want to unregister. See “Device Classes” for a list of the constants you can supply.

deviceID

The device ID of the device you want to unregister.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

When a device is no longer to be used on a system (as opposed to being offline), it should be unregistered. If a device is temporarily shut down or disconnected, it does not to be unregistered unless either of the following is true:

  • The device driver is being removed (uninstalled)

  • The device driver can’t access the device profiles without the device

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMUpdateProfile

Saves modifications to the specified profile. (Deprecated in OS X v10.6.)

CMError CMUpdateProfile (
   CMProfileRef prof
);
Parameters
prof

A profile reference of type CMProfileRef to the profile to update.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The CMUpdateProfile function makes permanent any changes or additions your application has made to the profile identified by the profile reference, if no other references to that profile exist.

The ColorSync Manager maintains a modified flag to track whether a profile has been modified. After updating a profile, the CMUpdateProfile function sets the value of the modified flag for that profile to false.

Each time an application calls the function CMOpenProfile, the function creates a unique reference to the profile. An application can also duplicate a profile reference by passing a copy to another task. You cannot use the CMUpdateProfile function to update a profile if more than one reference to the profile exists—attempting to do so will result in an error return. You can call the function CMGetProfileRefCount to determine the reference count for a profile reference.

You cannot use the CMUpdateProfile function to update a ColorSync 1.0 profile.

After you fill in tags and their data elements for a new profile created by calling the function CMNewProfile, you must call the CMUpdateProfile function to write the element data to the new profile.

If you modify an open profile, you must call CMUpdateProfile to save the changes to the profile file before you call the function CMCloseProfile. Otherwise, the changes are discarded.

To modify a profile header, you use the function CMGetProfileHeader and the function CMSetProfileHeader.

To set profile elements outside the header, you use the function CMSetProfileElement, the function CMSetProfileElementSize, and the function CMSetPartialProfileElement.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMUpdateProfileSearch

Searches the ColorSync Profiles folder and updates an existing search result obtained originally from the CMNewProfileSearch function. (Deprecated in OS X v10.6.)

CMError CMUpdateProfileSearch (
   CMProfileSearchRef search,
   void *refCon,
   UInt32 *count
);
Parameters
search

A reference to a search result list returned to your application when you called the CMNewProfileSearch function. For a description of the CMProfileSearchRef private data type, see CMProfileSearchRef. See the QuickDraw Reference for a description of the PixMap data type.

refCon

A pointer to a reference constant for application data passed as a parameter to calls to the filter function specified by the original search specification. For a description of the filter function, see the function CMProfileFilterProcPtr.

count

A pointer to a profile count. On return, if the function result is noErr, a one-based count of the number of profiles matching the original search specification passed to the CMNewProfileSearch function. Otherwise undefined.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

After a profile search has been set up and performed through a call to the CMNewProfileSearch function, the CMUpdateProfileSearch function updates the existing search result. You must use this function if the contents of the ColorSync Profiles folder have changed since the original search result was created.

The search update uses the original search specification, including the filter function indicated by the search record. Data given in the CMUpdateProfileSearch function’s refCon parameter is passed to the filter function each time it is called.

Sharing a disk over a network makes it possible for modification of the contents of the ColorSync Profiles folder to occur at any time.

For a description of the function you call to begin a new search, see the function CMNewProfileSearch. That function specifies the filter function referred to in the description of the refCon parameter.

Version Notes

Starting with version 2.5, you should use the function CMIterateColorSyncFolder for profile searching.

This function is not recommended for use in ColorSync 2.5.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CMValidateProfile

Indicates whether the specified profile contains the minimum set of elements required by the current color management module (CMM) for color matching or color checking. (Deprecated in OS X v10.6.)

CMError CMValidateProfile (
   CMProfileRef prof,
   Boolean *valid,
   Boolean *preferredCMMnotfound
);
Parameters
prof

A profile reference of type CMProfileRef to the profile to validate.

valid

A pointer to a valid profile flag. On return, has the value true if the profile contains the minimum set of elements to be valid and false if it does not.

preferredCMMnotfound

A pointer to a flag for whether the preferred CMM was found. On return, has the value true if the CMM specified by the profile was not available to perform validation or does not support this function and the default CMM was used. Has the value false if the profile’s preferred CMM is able to perform validation.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

When your application calls the CMValidateProfile function, the ColorSync Manager dispatches the function to the CMM specified by the CMMType header field of the profile whose reference you specify. The preferred CMM can support this function or not.

If the preferred CMM supports this function, it determines if the profile contains the baseline elements for the profile class, which the CMM requires to perform color matching or gamut checking. For each profile class, such as a device profile, there is a specific set of required tagged elements defined by the ICC that the profile must include. The ICC also defines optional tags, which may be included in a profile. A CMM might use these optional elements to optimize or improve its processing. Additionally, a profile might include private tags defined to provide a CMM with processing capability particular to the needs of that CMM. The profile developer can define these private tags, register the tag signatures with the ICC, and include the tags in a profile. The CMM checks only for the existence of profile elements it does not check the element’s content and size.

If the preferred CMM does not support the CMValidateProfile function request, the ColorSync Manager calls the default CMM to handle the validation request.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CMValidImage

Validates the specified image file. (Deprecated in OS X v10.6.)

CMError CMValidImage (
   const FSSpec *spec
);
Parameters
spec

A file specification for the image file you want to validate. See the File Manager documentation for a description of the FSSpec data type.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

This function validates the specified image file. ColorSync checks with any installed scripting plug-ins to see if they recognize the image's file format. If a scripting plug-in is found which recognizes the image's file format, CMValidateImage returns noErr . If the image's file format is not recognized, CMValidateImage returns the cmInvalidImageFile error.

Availability
  • Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CWCheckBitmap

Tests the colors of the pixel data of a bitmap to determine whether the colors map to the gamut of the destination device. (Deprecated in OS X v10.6.)

CMError CWCheckBitmap (
   CMWorldRef cw,
   const CMBitmap *bitmap,
   CMBitmapCallBackUPP progressProc,
   void *refCon,
   CMBitmap *resultBitmap
);
Parameters
cw

A reference to the color world of type CMWorldRef to use for the color check.

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

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

refCon

A pointer to a reference constant for application data passed as a parameter to calls to progressProc.

resultBitmap

A pointer to a bitmap. On return, 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.”

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

When your application calls the CWCheckBitMap function, the ColorSync Manager dispatches the 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 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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CWCheckColors

Tests a list of colors using a specified color world to see if they fall within the gamut of a destination device. (Deprecated in OS X v10.6.)

CMError CWCheckColors (
   CMWorldRef cw,
   CMColor *myColors,
   size_t count,
   UInt8 *result
);
Parameters
cw

A reference to the color world of type CMWorldRef describing how the test is to occur.

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

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 packed bits. On return, each 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.

To access the packed bit-array, use code similar to the following:

inline bool GetNthBit (UInt8* result, int n)
{
    return ( 0 != (result[n/8] & (128>>(n%8))) );
}

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.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The color test provides a preview of color matching using the specified color world.

All CMMs must support the CWCheckColors function.

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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CWConcatColorWorld

Sets up a color world that includes a set of profiles for various color transformations among devices in a sequence. (Deprecated in OS X v10.6.)

CMError CWConcatColorWorld (
   CMWorldRef *cw,
   CMConcatProfileSet *profileSet
);
Parameters
cw

A pointer to a color world. On return, 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. If that CMM is available, ColorSync will use that CMM for all color conversion and matching operations the CMM is capable of performing.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

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:

  • In the profile array, you can pass in one or more profiles, but you must specify at least one profile. If you specify only one profile, it must be a device link profile. If you specify a device link profile, you cannot specify any other profiles in the profiles array; a device link profile must be used alone.

  • In the profile array, you can specify an abstract profile anywhere in the sequence other than as the first or last profile.

  • For the first and last profiles, you can specify device profiles or color space conversion profiles. However, when you set up a color-matching session with a named color space profile and other profiles, the named color profile must be first or the last profile in the color world—it cannot be in the middle.

  • You cannot specify NULL to indicate the system profile. Note that starting with version 2.5, use of the system profile has changed.

  • If you specify a color space profile in the middle of the profile sequence, it is ignored by the default CMM.

  • If you specify a named color profile, it must be the first or the last profile. Otherwise, CWConcatColorWorld returns the value cmCantConcatenateError.

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

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.

Version Notes

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

Note also that starting with version 2.5, use of the system profile has changed.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

CWDisposeColorWorld

Releases the private storage associated with a color world when your application has finished using the color world. (Deprecated in OS X v10.6.)

void CWDisposeColorWorld (
   CMWorldRef cw
);
Parameters
cw

A color world reference of type CMWorldRef.

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

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CWFillLookupTexture

Fills a 3-D lookup texture from a color world. (Deprecated in OS X v10.6.)

CMError CWFillLookupTexture (
   CMWorldRef cw,
   UInt32 gridPoints,
   UInt32 format,
   UInt32 dataSize,
   void *data
);
Parameters
cw

The color world to use.

gridPoints

The number of grid points per channel in the texture.

format

The format of pixels in texture; for example, cmTextureRGBtoRGBX8.

dataSize

The size in bytes of texture data to fill.

data

On output, points to the texture data to fill.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

You can use the resulting table in OpenGL to accelerate color management in hardware.

Availability
  • Available in OS X v. 10.3 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CWMatchBitmap

Matches the colors of a bitmap to the gamut of a destination device using the profiles specified by a color world. (Deprecated in OS X v10.6.)

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 NCWNewColorWorld and 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 “ColorSync Manager Result Codes.”

Discussion

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 “Color Space Constants With Packing Formats.” Support for the following color space constants, was added with ColorSync version 2.5:

  • cmGray16Space

  • cmGrayA32Space

  • cmRGB48Space.

  • cmCMYK64Space

  • cmLAB48Space

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

CWMatchColors

Matches colors in a color list, using the specified color world. (Deprecated in OS X v10.6.)

CMError CWMatchColors (
   CMWorldRef cw,
   CMColor *myColors,
   size_t count
);
Parameters
cw

A reference to the color world of type CMWorldRef that describes how matching is to occur in the color-matching session.

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

myColors

A pointer to an array containing a list of colors of type CMColor. On input, contains the list of colors to match. On return, 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.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

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

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

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

NCMGetProfileLocation

Obtains either a profile location structure for a specified profile or the size of the location structure for the profile. (Deprecated in OS X v10.6.)

CMError NCMGetProfileLocation (
   CMProfileRef prof,
   CMProfileLocation *theProfile,
   UInt32 *locationSize
);
Parameters
prof

A profile reference of type CMProfileRef. Before calling NCMGetProfileLocation, you set the reference to specify the profile for which you wish to obtain the location or location structure size.

theProfile

A pointer to a profile location structure, as described in CMProfileLocation. If you pass NULL, NCMGetProfileLocation returns the size of the profile location structure for the profile specified by prof in the locationSize parameter. If you instead pass a pointer to memory you have allocated for the structure, on return, the structure specifies the location of the profile specified by prof.

locationSize

A pointer to a value of type long. If you pass NULL for the profLoc parameter, on return, locationSize contains the size in bytes of the profile location structure for the profile specified by prof. If you pass a pointer to a profile location structure in profLoc, set locationSize to the size of the structure before calling NCMGetProfileLocation, using the constant cmCurrentProfileLocationSize.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The NCMGetProfileLocation function is available starting with ColorSync version 2.5. It differs from its predecessor, CMGetProfileLocation, in that the newer version has a parameter for the size of the location structure for the specified profile.

You should use NCMGetProfileLocation rather than CMGetProfileLocation for the following reasons:

  • Code using the older version (CMGetProfileLocation) may not be as easily ported to other platforms.

  • Specifying the size of the profile location structure ensures that it can grow, if necessary, in the future.

The best way to use NCMGetProfileLocation is to call it twice:

  1. Pass a reference to the profile to locate in the prof parameter and NULL for the profLoc parameter. NCMGetProfileLocation returns the size of the location structure in the locationSize parameter.

  2. Allocate enough space for a structure of the returned size, then call the function again, passing a pointer in the profLoc parameter; on return, the structure specifies the location of the profile.

It is possible to call NCMGetProfileLocation just once, using the constant cmCurrentProfileLocationSize for the size of the allocated profile location structure and passing the same constant for the locationSize parameter. The constant cmCurrentProfileLocationSize may change in the future, but will be consistent within the set of headers you build your application with. However, if the size of the CMProfileLocation structure changes in a future version of ColorSync (and the value of cmCurrentProfileLocationSize as well) and you do not rebuild your application, NCMGetProfileLocation may return an error.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

NCMSetSystemProfile

Sets the location of a color profile. (Deprecated in OS X v10.6.)

CMError NCMSetSystemProfile (
   const CMProfileLocation *profLoc
);
Parameters
profLoc

The location of the profile. Commonly a profile is disk-file based. However, the profile may be a file-based profile, a handle-based profile, or a pointer-based profile.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

Prior to ColorSync 2.6, the function for setting the system profile supported only the FSSpec file specification type as a way of specifying a profile. This function allows for greater flexibility when specifying a system profile.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

NCMUnflattenProfile

Unflattens a previously flattened profile. (Deprecated in OS X v10.6.)

CMError NCMUnflattenProfile (
   CMProfileLocation *targetLocation,
   CMFlattenUPP proc,
   void *refCon,
   Boolean *preferredCMMnotfound
);
Parameters
targetLocation

The location of the profile you want to unflatten. Commonly a profile is disk-file based. However, the profile may be a file-based profile, a handle-based profile, or a pointer-based profile.

proc

A user-defined procedure which is called during the unflatten operation.

refCon

A reference constant containing data specified by the calling application program.

preferredCMMnotfound

A return value indicating whether or not the CMM specified in the profile was found.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
  • Not available to 64-bit applications.
Declared In
ColorSyncDeprecated.h

NCWConcatColorWorld

Defines a color world for color transformations among a series of concatenated profiles. (Deprecated in OS X v10.6.)

CMError NCWConcatColorWorld (
   CMWorldRef *cw,
   NCMConcatProfileSet *profileSet,
   CMConcatCallBackUPP proc,
   void *refCon
);
Parameters
cw

A reference to a color world that the ColorSync Manager returns if the function completes successfully. You pass this reference to other functions that use the color world for color-matching and color-checking sessions.

profileSet

An array of profiles describing the processing to be carried out. The array is in processing order source through destination.

proc

A calling-program-supplied callback function that allows your application to monitor progress or abort the operation.

refCon

A reference constant containing data specified by the calling application program.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The caller can override the color management module (CMM) that would normally be selected by ColorSync by providing a CMM identifier in the NCMConcatProfileSet structure, or pass 0 to accept ColorSync's CMM selection (note that this could either be the user's preferred CMM selection or the CMM called for in the profile). The flags and k parameters are provided to allow easy customization of such attributes as quality and gamut-checking, while preserving the other settings. Each profile in the set can be customized by overriding the intent, and the selection of the transform tag. Together with other profiles, a custom-rendering environment can be set up to transform to or from device-dependent spaces with a minimum of gamut compression and/or unnecessary transformations to and from connection spaces. This flexibility comes at the price of specific knowledge of the profile contents and how device gamuts overlap.

Note that for standard input and output device profiles, A2B and B2A tags represent transforms from data space to connection space and from connection space to data space, respectively. Under these circumstances, the caller would not normally be able to use the same transform tags (e.g., kUseAtoB ) consecutively, since a connection space would not be the same as the subsequent data space. If the spaces aren't the same, the caller will get a cmCantConcatenateError error returned. For profiles of type cmLinkClass, cmAbstractClass, cmColorSpaceClass , and cmNamedColorClass , these constants are not always meaningful, and the caller is encouraged to think in terms of the actual tags present in the profiles (e.g., A2B0 or B2A0 ). Under these conditions, it may well be appropriate to specify two transform tags of the same type consecutively, as long as the actual color spaces align in between tags. If this is not the case, a cmCantConcatenateError error is returned.

The callback proc is provided as protection against the appearance of a stalled machine during lengthy color world processing. If a CMM takes more than several seconds to process the information and create a color world, it will call the callback proc, if one is provided, and pass it the refCon provided. This is also true for NCWNewLinkProfile.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

NCWNewColorWorld

Creates a color world for color matching based on the specified source and destination profiles. (Deprecated in OS X v10.6.)

CMError NCWNewColorWorld (
   CMWorldRef *cw,
   CMProfileRef src,
   CMProfileRef dst
);
Parameters
cw

A pointer to a color world. On return, 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.

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.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

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 can specify a device profile or a color space conversion profile for the source and destination profiles.

  • You can not specify a device link profile or an abstract profile for either the source profile or the destination profile.

  • Only one profile can be a named color profile.

  • You can specify the system profile explicitly by reference or by giving NULL for either the source profile or the destination profile.

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

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.

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

Version Notes

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

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h

NCWNewLinkProfile

Obtains a profile reference for the specified by the profile location. (Deprecated in OS X v10.6.)

CMError NCWNewLinkProfile (
   CMProfileRef *prof,
   const CMProfileLocation *targetLocation,
   NCMConcatProfileSet *profileSet,
   CMConcatCallBackUPP proc,
   void *refCon
);
Parameters
prof

The returned profile reference.

targetLocation

The location of the profile. Commonly a profile is disk-file based. However, the profile may be a file-based profile, a handle-based profile, or a pointer-based profile.

profileSet

A pointer to the profile set structure.

proc

A calling-program-supplied callback function that allows your application to monitor progress or abort the operation.

refCon

A reference constant containing data specified by the calling application program.

Return Value

A CMError value. See “ColorSync Manager Result Codes.”

Discussion

The same new flexibility in creating color worlds is extended to link profiles, which are not assumed to go from input device color space to output device color space. The returned profile is open, and should be closed when you are finished with it.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
ColorSyncDeprecated.h