ADC Home > Reference Library > Reference > Graphics & Imaging > ColorSync > ColorSync Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated ColorSync Manager Functions

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

Deprecated in Mac OS X v10.4

CMEnableMatchingComment

Inserts a comment into the currently open picture to turn matching on or off. (Deprecated in Mac 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
Declared In
QuickdrawAPI.h

CMEndMatching

Concludes a QuickDraw-specific ColorSync matching session initiated by a previous call to the NCMBeginMatching function. (Deprecated in Mac 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
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 Mac 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
Declared In
QuickdrawAPI.h

CWMatchPixMap

Matches a pixel map in place based on a specified color world. (Deprecated in Mac 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
Declared In
QuickdrawAPI.h

NCMBeginMatching

Sets up a QuickDraw-specific ColorSync matching session, using the specified source and destination profiles. (Deprecated in Mac 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 NCMBeginMatching– CMEndMatching 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
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 Mac 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
Declared In
QuickdrawAPI.h

NCMUseProfileComment

Automatically embeds a profile or a profile identifier into an open picture. (Deprecated in Mac 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
Declared In
QuickdrawAPI.h

Deprecated in Mac OS X v10.5

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 Mac OS X v10.5.)

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
Declared In
CMApplication.h

CMConvertHLSToRGB

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

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
Declared In
CMApplication.h

CMConvertHSVToRGB

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

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
Declared In
CMApplication.h

CMConvertLabToXYZ

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

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
Declared In
CMApplication.h

CMConvertLuvToXYZ

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

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
Declared In
CMApplication.h

CMConvertRGBToGray

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

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
Declared In
CMApplication.h

CMConvertRGBToHLS

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

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
Declared In
CMApplication.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 Mac OS X v10.5.)

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
Declared In
CMApplication.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 Mac OS X v10.5.)

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
Declared In
CMApplication.h

CMConvertXYZToLab

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

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
Declared In
CMApplication.h

CMConvertXYZToLuv

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

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
Declared In
CMApplication.h

CMConvertXYZToXYZ

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

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
Declared In
CMApplication.h

CMConvertXYZToYxy

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

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
Declared In
CMApplication.h

CMConvertYxyToXYZ

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

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
Declared In
CMApplication.h

CMCountImageProfiles

Obtains a count of the number of embeded profiles for a given image. (Deprecated in Mac OS X v10.5.)

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 embeded profiles for the image

Return Value

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

Availability
Declared In
CMScriptingPlugin.h

CMCreateProfileIdentifier

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

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

Parameters
prof
ident
size
Return Value

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

Availability
Declared In
CMApplication.h

CMDisposeProfileSearch

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

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
Declared In
CMApplication.h

CMEmbedImage

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

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
Declared In
CMScriptingPlugin.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 Mac OS X v10.5.)

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
Declared In
CMApplication.h

CMGetColorSyncFolderSpec

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

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

Parameters
vRefNum

The location of the ColorSync profiles folder. In Mac 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
Declared In
CMApplication.h

CMGetCWInfo

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

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
Declared In
CMApplication.h

CMGetDeviceProfiles

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

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
Declared In
CMDeviceIntegration.h

CMGetImageSpace

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

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
Declared In
CMScriptingPlugin.h

CMGetIndImageProfile

Obtains a specific embeded profile for a given image. (Deprecated in Mac OS X v10.5.)

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
Declared In
CMScriptingPlugin.h

CMGetPreferredCMM

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

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
Declared In
CMApplication.h

CMGetProfileLocation

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

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
Declared In
CMApplication.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 Mac OS X v10.5.)

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
Declared In
CMApplication.h

CMLinkImage

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

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 i ntent , or absolute colorimetric intent (cmPerceptual, cmRelativecolorimetric, cmSaturation, or cmAbsoluteColorimetric ).

Return Value

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

Availability
Declared In
CMScriptingPlugin.h

CMMatchImage

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

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 i ntent , 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
Declared In
CMScriptingPlugin.h

CMNewProfileSearch

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

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
Declared In
CMApplication.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 Mac OS X v10.5.)

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
Declared In
CMApplication.h

CMProfileIdentifierListSearch

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

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
Declared In
CMApplication.h

CMProofImage

Proofs an image. (Deprecated in Mac OS X v10.5.)

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 i ntent , 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
Declared In
CMScriptingPlugin.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 Mac OS X v10.5.)

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
Declared In
CMApplication.h

CMSearchGetIndProfileFileSpec

Obtains the file specification for the profile at a specific index into a search result. (Deprecated in Mac OS X v10.5.)

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
Declared In
CMApplication.h

CMSetDefaultProfileBySpace

Sets the default profile for the specified color space. (Deprecated in Mac OS X v10.5.)

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
Declared In
CMApplication.h

CMSetDefaultProfileByUse

Sets values for device profile settings. (Deprecated in Mac OS X v10.5.)

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
Declared In
CMApplication.h

CMSetDeviceProfiles

Changes the profiles used by a given device. (Deprecated in Mac OS X v10.5.)

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
Declared In
CMDeviceIntegration.h

CMSetIndImageProfile

Sets a specific embeded profile for a given image. (Deprecated in Mac OS X v10.5.)

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
Declared In
CMScriptingPlugin.h

CMSetSystemProfile

Sets the current system profile. (Deprecated in Mac OS X v10.5.)

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
Declared In
CMApplication.h

CMUnembedImage

Removes any ICC profiles embeded in an image. (Deprecated in Mac OS X v10.5.)

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
Declared In
CMScriptingPlugin.h

CMUpdateProfileSearch

Searches the ColorSync Profiles folder and updates an existing search result obtained originally from the CMNewProfileSearch function. (Deprecated in Mac OS X v10.5.)

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
Declared In
CMApplication.h

CMValidImage

Validates the specified image file. (Deprecated in Mac OS X v10.5.)

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
Declared In
CMScriptingPlugin.h

CWNewLinkProfile

Creates a device link profile based on the specified set of profiles. (Deprecated in Mac 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:

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
Declared In
CMApplication.h

DisposeCMBitmapCallBackUPP

Disposes of a universal procedure pointer (UPP) to a bitmap callback. (Deprecated in Mac OS X v10.5.)

void DisposeCMBitmapCallBackUPP (
   CMBitmapCallBackUPP userUPP
);

Parameters
userUPP

The universal procedure pointer to dispose of.

Availability
Declared In
CMTypes.h

DisposeCMConcatCallBackUPP

Disposes of a universal procedure pointer (UPP) to a progress-monitoring callback. (Deprecated in Mac OS X v10.5.)

void DisposeCMConcatCallBackUPP (
   CMConcatCallBackUPP userUPP
);

Parameters
userUPP

The universal procedure pointer to dispose of.

Availability
Declared In
CMTypes.h

DisposeCMFlattenUPP

Disposes of a universal procedure pointer (UPP) to a data-flattening callback. (Deprecated in Mac OS X v10.5.)

void DisposeCMFlattenUPP (
   CMFlattenUPP userUPP
);

Parameters
userUPP

The universal procedure pointer to dispose of.

Availability
Declared In
CMTypes.h

DisposeCMMIterateUPP

Disposes of a universal procedure pointer (UPP) to a progress-monitoring callback for the CMIterateCMMInfo function. (Deprecated in Mac OS X v10.5.)

void DisposeCMMIterateUPP (
   CMMIterateUPP userUPP
);

Parameters
userUPP

The universal procedure pointer to dispose of.

Availability
Declared In
CMApplication.h

DisposeCMProfileAccessUPP

Disposes of a universal procedure pointer (UPP) to a profile-access callback. (Deprecated in Mac OS X v10.5.)

void DisposeCMProfileAccessUPP (
   CMProfileAccessUPP userUPP
);

Parameters
userUPP

The universal procedure pointer to dispose of.

Availability
Declared In
CMTypes.h

DisposeCMProfileFilterUPP

Disposes of a universal procedure pointer (UPP) to a profile-filter callback. (Deprecated in Mac OS X v10.5.)

void DisposeCMProfileFilterUPP (
   CMProfileFilterUPP userUPP
);

Parameters
userUPP

The universal procedure pointer to dispose of.

Availability
Declared In
CMTypes.h

DisposeCMProfileIterateUPP

Disposes of a universal procedure pointer (UPP) to a profile-iteration callback. (Deprecated in Mac OS X v10.5.)

void DisposeCMProfileIterateUPP (
   CMProfileIterateUPP userUPP
);

Parameters
userUPP

The universal procedure pointer to dispose of.

Availability
Declared In
CMApplication.h

InvokeCMBitmapCallBackUPP

Invokes a universal procedure pointer (UPP) to a bitmap callback. (Deprecated in Mac OS X v10.5.)

Boolean InvokeCMBitmapCallBackUPP (
   SInt32 progress,
   void *refCon,
   CMBitmapCallBackUPP userUPP
);

Discussion

In most cases, you do not need to call this function as ColorSync Manager invokes your callback for you. See the “CMBitmapCallBackProcPtr” callback for more information and for a description of the parameters.

Availability
Declared In
CMTypes.h

InvokeCMConcatCallBackUPP

Invokes a universal procedure pointer (UPP) to a progress-monitoring callback. (Deprecated in Mac OS X v10.5.)

Boolean InvokeCMConcatCallBackUPP (
   SInt32 progress,
   void *refCon,
   CMConcatCallBackUPP userUPP
);

Discussion

In most cases, you do not need to call this function as ColorSync Manager invokes your callback for you. See the “CMConcatCallBackProcPtr” callback for more information and for a description of the parameters.

Availability
Declared In
CMTypes.h

InvokeCMFlattenUPP

Invokes a universal procedure pointer (UPP) to a data-flattening callback. (Deprecated in Mac OS X v10.5.)

OSErr InvokeCMFlattenUPP (
   SInt32 command,
   long *size,
   void *data,
   void *refCon,
   CMFlattenUPP userUPP
);

Discussion

In most cases, you do not need to call this function as ColorSync Manager invokes your callback for you. See the “CMFlattenProcPtr” callback for more information and for a description of the parameters.

Availability
Declared In
CMTypes.h

InvokeCMMIterateUPP

Invokes a universal procedure pointer (UPP) to a a progress-monitoring callback for the CMIterateCMMInfo function. (Deprecated in Mac OS X v10.5.)

OSErr InvokeCMMIterateUPP (
   CMMInfo *iterateData,
   void *refCon,
   CMMIterateUPP userUPP
);

Discussion

In most cases, you do not need to call this function as ColorSync Manager invokes your callback for you. See the “CMMIterateProcPtr” callback for more information and for a description of the parameters.

Availability
Declared In
CMApplication.h

InvokeCMProfileAccessUPP

Invokes a universal procedure pointer (UPP) to a profile-access callback. (Deprecated in Mac OS X v10.5.)

OSErr InvokeCMProfileAccessUPP (
   SInt32 command,
   SInt32 offset,
   SInt32 *size,
   void *data,
   void *refCon,
   CMProfileAccessUPP userUPP
);

Discussion

In most cases, you do not need to call this function as ColorSync Manager invokes your callback for you. See the “CMProfileAccessProcPtr” callback for more information and for a description of the parameters.

Availability
Declared In
CMTypes.h

InvokeCMProfileFilterUPP

Invokes a universal procedure pointer (UPP) to a profile-filter callback. (Deprecated in Mac OS X v10.5.)

Discussion

In most cases, you do not need to call this function as ColorSync Manager invokes your callback for you. See the “CMProfileFilterProcPtr” callback for more information and for a description of the parameters.

Availability
Declared In
CMTypes.h

InvokeCMProfileIterateUPP

Invokes a universal procedure pointer (UPP) to a profile-iteration callback. (Deprecated in Mac OS X v10.5.)

OSErr InvokeCMProfileIterateUPP (
   CMProfileIterateData *iterateData,
   void *refCon,
   CMProfileIterateUPP userUPP
);

Parameters
Return Value

A result code. See “ColorSync Manager Result Codes.”

Discussion

In most cases, you do not need to call this function as ColorSync Manager invokes your callback for you. See the “CMProfileIterateProcPtr” callback for more information and for a description of the parameters.

Availability
Declared In
CMApplication.h

NCMSetSystemProfile

Sets the location of a color profile. (Deprecated in Mac OS X v10.5.)

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
Declared In
CMApplication.h

NCMUnflattenProfile

Unflattens a previouslyflattened profile. (Deprecated in Mac OS X v10.5.)

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
Declared In
CMApplication.h

NewCMBitmapCallBackUPP

Creates a new universal procedure pointer (UPP) to a bitmap callback. (Deprecated in Mac OS X v10.5.)

CMBitmapCallBackUPP NewCMBitmapCallBackUPP (
   CMBitmapCallBackProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your bitmap callback function.

Return Value

The universal procedure pointer.

Availability
Declared In
CMTypes.h

NewCMConcatCallBackUPP

Creates a new universal procedure pointer (UPP) to a progress-monitoring callback. (Deprecated in Mac OS X v10.5.)

CMConcatCallBackUPP NewCMConcatCallBackUPP (
   CMConcatCallBackProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your progress-monitoring callback function.

Return Value

The universal procedure pointer.

Discussion

The callback protects 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, if one is provided, and pass it the refCon provided. Passed to the functions NCWNewLinkProfile or NCWConcatColorWorld function .

Availability
Declared In
CMTypes.h

NewCMFlattenUPP

Creates a new universal procedure pointer (UPP) to a data-flattening callback. (Deprecated in Mac OS X v10.5.)

CMFlattenUPP NewCMFlattenUPP (
   CMFlattenProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your data-flattening callback function.

Return Value

The universal procedure pointer.

Availability
Declared In
CMTypes.h

NewCMMIterateUPP

Creates a new universal procedure pointer (UPP) to a progress-monitoring callback for the CMIterateCMMInfo function. (Deprecated in Mac OS X v10.5.)

CMMIterateUPP NewCMMIterateUPP (
   CMMIterateProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your progress-monitoring callback function.

Return Value

The universal procedure pointer.

Availability
Declared In
CMApplication.h

NewCMProfileAccessUPP

Creates a new universal procedure pointer (UPP) to a profile-access callback. (Deprecated in Mac OS X v10.5.)

CMProfileAccessUPP NewCMProfileAccessUPP (
   CMProfileAccessProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your profile-access callback function.

Return Value

The universal procedure pointer.

Availability
Declared In
CMTypes.h

NewCMProfileFilterUPP

Creates a new universal procedure pointer (UPP) to a profile-filter callback. (Deprecated in Mac OS X v10.5.)

CMProfileFilterUPP NewCMProfileFilterUPP (
   CMProfileFilterProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your profile-filter callback function.

Return Value

The universal procedure pointer.

Availability
Declared In
CMTypes.h

NewCMProfileIterateUPP

Creates a new universal procedure pointer (UPP) to a profile-iteration callback. (Deprecated in Mac OS X v10.5.)

CMProfileIterateUPP NewCMProfileIterateUPP (
   CMProfileIterateProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your profile-iteration callback function.

Return Value

The universal procedure pointer.

Availability
Declared In
CMApplication.h

< Previous PageNext Page > Hide TOC

© 1999, 2005 Apple Computer, Inc. All Rights Reserved. (Last updated: 2005-06-04)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.