ColorSync Manager Reference

Framework	ApplicationServices/ApplicationServices.h, Carbon/Carbon.h
Declared in	CMApplication.h CMCalibrator.h CMDeviceIntegration.h CMICCProfile.h CMMComponent.h CMScriptingPlugin.h ColorSyncDeprecated.h QuickdrawAPI.h

Overview

The ColorSync Manager is the API for ColorSync, a platform-independent color management system from Apple. ColorSync provides essential services for fast, consistent, and accurate color calibration, proofing, and reproduction using input, output, and display devices. ColorSync also provides an interface to system-wide color management settings that allows users to save color settings for specific jobs and switch between settings.

You need this reference if your software product performs color drawing, printing, or calculation, or if your peripheral device supports color. You also need this reference if you are creating a color management module (CMM)—a component that implements color-matching, color-conversion, and gamut-checking services.

The Color Picker Manager, documented separately, provides a standard user interface for soliciting color choices.

Carbon supports the majority of the ColorSync Manager programming interface. However, ColorSync 1.0 compatibility calls such as CWNewColorWorld, GetProfile, and SetProfile are not supported.

Nor does Carbon support ColorSync functions used for color management modules (CMMs). These functions aren't supported because Mac OS X uses Bundle Services to implement CMMs.

Some applications use the Component Manager to determine what CMMs are available. You cannot use the Component Manager for this purpose in Mac OS X. Apple has, however, provided a the function CMIterateCMMInfo to query for available CMMs.

Functions by Task

Accessing Profiles

Iterating Installed Profiles

Creating Profiles

Accessing Special Profiles

Accessing Profile Elements

Accessing Profile Descriptions

Accessing Name-Class Profiles

Working With ColorWorlds

Converting Colors

Working With CMMs

Working With PostScript

Working With QuickDraw

Registering Devices

Accessing Default Devices

Accessing Devices Profiles

Accessing Device State and Information

Iterating Over Devices and Device Profiles

Working With Image Files

Working With Video Card Lookup Tables

Miscellaneous

Working With Universal Procedure Pointers

Not Recommended

Functions

CMCalibrateDisplay

Calibrates a display.

OSErr CMCalibrateDisplay (
   CalibratorInfo *theInfo
);

Parameters

theInfo: A pointer to a calibrator info data structure that contains the necessary data for calibrating a display.

Return Value

An OSErr value.

Availability

Not available in CarbonLib.
Available in Mac OS X 10.0 and later.

Declared In

CMCalibrator.h

CMCloneProfileRef

Increments the reference count for the specified profile reference.

CMError CMCloneProfileRef (
   CMProfileRef prof
);

Parameters

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

Return Value

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

Discussion

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

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

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.1 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

ColorMatching

Declared In

ColorSyncDeprecated.h

CMCloseProfile

Decrements the reference count for the specified profile reference and, if the reference count reaches 0, frees all private memory and other resources associated with the profile.

CMError CMCloseProfile (
   CMProfileRef prof
);

Parameters

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

Return Value

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

Discussion

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

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

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

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

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

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

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

Declared In

ColorSyncDeprecated.h

CMCopyProfile

Duplicates the specified existing profile.

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

Parameters

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

Return Value

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

Discussion

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

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

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

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

if (myCM2Header.flags & cmEmbeddedUseMask)

// profile should only be used as an embedded profile

else

// profile can be used independently

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMCopyProfileDescriptionString

Returns the name of a profile as a CFString.

CMError CMCopyProfileDescriptionString (
   CMProfileRef prof,
   CFStringRef *str
);

Parameters

prof: The profile to query.
str: On ouput, the name of the profile as a CFString.

Return Value

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

Discussion

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

Availability

Available in Mac OS X v. 10.3 and later.

Related Sample Code

ImageApp

Declared In

ColorSyncDeprecated.h

CMCopyProfileLocalizedString

Gets one specific string out of a profile

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

Parameters

prof: The profile to query.
tag: The tag type of profile to query.
reqLocale: The requested locale (optional).
locale: On ouput, points to the locale (optional).
str: On output, points to the dictionary string (optional).

Return Value

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

Discussion

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

err = CMCopyProfileLocalizedString (prof, 'dscm',

                CFSTR("enUS"), nil, &theStr);

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Related Sample Code

ColorMatching

Declared In

ColorSyncDeprecated.h

CMCopyProfileLocalizedStringDictionary

Obtains a CFDictionary which contains the language locale and string for multiple localizations from a given tag.

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

Parameters

prof: The profile to query
tag: The tag type of profile to query
theDict: On output, points to the dictionary .See the CFDictionary documentation for a description of the CFDictionaryRef data type.

Return Value

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

Discussion

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

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMCountProfileElements

Counts the number of elements in the specified profile.

CMError CMCountProfileElements (
   CMProfileRef prof,
   UInt32 *elementCount
);

Parameters

prof: A profile reference of type CMProfileRef to the profile to examine.
elementCount: A pointer to an element count. On return, a one-based count of the number of elements.

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetColorSyncVersion

Gets ColorSync version information.

CMError CMGetColorSyncVersion (
   UInt32 *version
);

Parameters

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

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetDefaultDevice

Gets the default device.

CMError CMGetDefaultDevice (
   CMDeviceClass deviceClass,
   CMDeviceID *deviceID
);

Parameters

deviceClass: The device class whose default device you want to get. See “Device Classes” for a list of the constants you can supply.
deviceID: On return, points to the device ID for the default device.

Return Value

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

Discussion

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

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Related Sample Code

ColorSyncDevices

Declared In

ColorSyncDeprecated.h

CMGetDefaultProfileBySpace

Gets the default profile for the specified color space.

CMError CMGetDefaultProfileBySpace (
   OSType dataColorSpace,
   CMProfileRef *prof
);

Parameters

dataColorSpace: A four-character identifier of type OSType. You pass a color space signature that identifies the color space you wish to get the default profile for. The currently-supported values are cmRGBData, cmCMYKData, cmLabData, and cmXYZData. These constants are a subset of the constants described in “Color Space Signatures.” If you supply a value that is not supported, the CMGetDefaultProfileBySpace function returns an error value of paramErr.
prof: A pointer to a profile reference. On return, the reference specifies the current profile for the color space specified by dataColorSpace. CMGetDefaultProfileBySpace currently supports only file-based profiles.

Return Value

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

Discussion

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.5 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

Declared In

ColorSyncDeprecated.h

CMGetDefaultProfileByUse

Obtains the users’ preferred device profile setting.

CMError CMGetDefaultProfileByUse (
   OSType use,
   CMProfileRef *prof
);

Parameters

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

Return Value

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 3.0 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

ColorMatching

Declared In

ColorSyncDeprecated.h

CMGetDeviceDefaultProfileID

Gets the default profile ID for a given device.

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

Parameters

deviceClass: The device class to query. See “Device Classes” for a list of the constants you can supply.
deviceID: The device ID to query.
defaultID: On output, points to the id of the default profile for this device.

Return Value

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

Discussion

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

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMGetDeviceFactoryProfiles

Retrieves the original profiles for a given device.

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

Parameters

deviceClass: The device class to query. See “Device Classes” for a list of the constants you can supply.
deviceID: The device ID to query.
defaultProfID: A pointer to the default profile for this device.
arraySize: A pointer to the size of the array to be returned. You can first call this routine to get the size returned, then call it again with the size of the buffer to receive the array.
deviceProfiles: On output, points to the profile array. You can first pass NULL in this parameter to receive the size of the array in the arraySize parameter. Then, once the appropriate amount of storage has been allocated, a pointer to it can be passed in this parameter to have the array copied to that storage.

Return Value

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

Discussion

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

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMGetDeviceInfo

Gets information about a specified device.

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

Parameters

deviceClass: A device class to query. See “Device Classes” for a list of the constants you can supply.
deviceID: A device ID to query. You can pass cmDefaultDeviceID.
deviceInfo: On input, points to a device information dictionary On output, the dictionary is filled with device information. If, on input, deviceInfo->deviceName is nil then the name is not returned. If you wants the device name dictionary returned, you should provide in deviceInfo->deviceName the address where this routine should store the CFDictionaryRef. The caller is responsible for disposing of the name dictionary.

Return Value

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

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMGetDeviceProfile

Gets a profile used by a given device.

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

Parameters

deviceClass: The device class for the device whose profile you want to get. See “Device Classes” for a list of the constants you can supply.
deviceID: The device ID for the device whose profile you want to get.
defaultID: The ID of the default profile for this device.
deviceProfLoc: On return, the location of the profile.

Return Value

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

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Related Sample Code

ColorSyncDevices

Declared In

ColorSyncDeprecated.h

CMGetDeviceState

Gets the state of a device.

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

Parameters

deviceClass: A device class to query. See “Device Classes” for a list of the constants you can supply.
deviceID: A device ID to query. You can pass cmDefaultDeviceID.
deviceState: On output, points to the device state. See “Device States” for the values that can be returned.

Return Value

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

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMGetGammaByAVID

Obtains the gamma value for the specified display device.

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

Parameters

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

Return Value

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 3.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetIndNamedColorValue

Obtains device and PCS color values for a specific named color index from a named color space profile.

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

Parameters

prof: A profile reference of type CMProfileRef to a named color space profile to obtain color values from.
index: A one-based index value for a named color.
deviceColor: A pointer to a device color. On return, a device color value in CMColor union format. If the profile does not contain device values, deviceColor is undefined.
PCSColor: A pointer to a profile connection space color. On return, an interchange color value in CMColor union format.

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.1 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetIndProfileElement

Obtains the element data corresponding to a particular index from the specified profile.

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

Parameters

prof

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

index

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

elementSize

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

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

elementData

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

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

Return Value

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

Discussion

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

call the function CMGetIndProfileElementInfo, passing the element’s index
call the CMGetIndProfileElement function itself, specifying a pointer to an unsigned long data type in the elementSize field and a NULL value in the elementData field

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetIndProfileElementInfo

Obtains the element tag and data size of an element by index from the specified profile.

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

Parameters

prof: A profile reference of type CMProfileRef to the profile containing the element.
index: A one-based element index within the range returned by the elementCount parameter of the CMCountProfileElements function.
tag: A pointer to an element signature. On return, the tag signature of the element corresponding to the index.
elementSize: A pointer to an element size. On return, the size in bytes of the element data corresponding to the tag.
refs: A pointer to a reference count flag. On return, set to true if more than one tag in the profile refers to element data associated with the tag corresponding to the index.

Return Value

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

Discussion

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

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetNamedColorIndex

Obtains a named color index for a specific color name from a named color space profile.

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

Parameters

prof: A profile reference of type CMProfileRef to a named color space profile to obtain a named color index from.
name: A pointer to a Pascal string. You supply a color name string value for the color to obtain the color index for.
index: A pointer to an index value. On return, an index value for a named color.

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.1 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetNamedColorInfo

Obtains information about a named color space from its profile reference.

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

Parameters

prof: A profile reference of type CMProfileRef to a named color space profile to obtain named color information from.
deviceChannels: A pointer to a count value. On return, the number of device channels in the color space for the profile. It should agree with the “data color space” field in the profile header. For example, Pantone maps to CMYK, a four-channel color space. A value of 0 indicates no device channels were available.
deviceColorSpace: A pointer to a device color space. On return, a device color space, such as CMYK.
PCSColorSpace: A pointer to a profile connection space color space. On return, an interchange color space, such as Lab.
count: A pointer to a count value. On return, the number of named colors in the profile.
prefix: A pointer to a Pascal string. On return, the string contains a prefix, such as “Pantone”, for each color name. The prefix identifies the named color system described by the profile.
suffix: A pointer to a Pascal string. On return, the string contains a suffix for each color name, such as “CVC”.

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.1 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetNamedColorName

Obtains a named color name for a specific named color index from a named color space profile.

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

Parameters

prof: A profile reference of type CMProfileRef to a named color space profile to obtain a named color name from.
index: An index value for a named color to obtain the color name for.
name: A pointer to a Pascal string. On return, a color name string.

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.1 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetNamedColorValue

Obtains device and PCS color values for a specific color name from a named color space profile.

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

Parameters

prof: A profile reference of type CMProfileRef to a named color space profile to obtain color values from.
name: A pointer to a Pascal string. You supply a color name string for the color to get information for.
deviceColor: A pointer to a device color. On return, a device color value in CMColor union format. If the profile does not contain device values, deviceColor is undefined.
PCSColor: A pointer to a profile connection space color. On return, an interchange color value in CMColor union format.

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.1 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetPartialProfileElement

Obtains a portion of the element data from the specified profile based on the specified element tag signature.

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

Parameters

prof: A profile reference of type CMProfileRef to the profile containing the target element.
tag: The tag signature for the element in question. For a complete list of the tag signatures a profile may contain, including a description of each tag, refer to the International Color Consortium Profile Format Specification. The signatures for profile tags are defined in the CMICCProfile.h header file.
offset: Beginning from the first byte of the element data, the offset from which to begin copying the element data.
byteCount: A pointer to a data byte count. On input, the number of bytes of element data to copy, beginning from the offset specified by the offset parameter. On return, the number of bytes actually copied.
elementData: A pointer to memory for element data. On input, you pass a pointer to allocated memory. On return, this buffer holds the element data.

Return Value

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

Discussion

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetProfileByAVID

Gets the current profile for a monitor.

CMError CMGetProfileByAVID (
   CMDisplayIDType theID,
   CMProfileRef *prof
);

Parameters

theAVID: A Display Manager ID value. You pass the ID value for the monitor for which to get the profile.
prof: A pointer to a profile reference. On return, a reference to the current profile for the monitor specified by theAVID.

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.5 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

Declared In

ColorSyncDeprecated.h

CMGetProfileDescriptions

Obtains the description tag data for a specified profile.

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

Parameters

prof: A reference to the profile from which to obtain the description info.
aName: On output, a pointer to the profile name as a 7-bit Roman ASCII string.
aCount: On output, a pointer to a count of the number of characters returned in the aName field.
mName: On output, a pointer to the localized profile name string in Mac script-code format.
mCode: On output, a pointer the script code corresponding to the name string returned in the mName parameter.
uName: On output, a pointer to localizedUnicode profile name string.
uCount: On output, a pointer to a count of the number of Unicode (2-byte) characters returned in the uName parameter.

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetProfileElement

Obtains element data from the specified profile based on the specified element tag signature.

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

Parameters

prof

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

tag

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

elementSize

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

On return, the size of the data returned.

elementData

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

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

Return Value

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

Discussion

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

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

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

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

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

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetProfileHeader

Obtains the profile header for the specified profile.

CMError CMGetProfileHeader (
   CMProfileRef prof,
   CMAppleProfileHeader *header
);

Parameters

prof: A profile reference of type CMProfileRef to the profile whose header is to be copied.
header: A pointer to a profile header. On input, depending on the profile version, you may allocate a ColorSync 2.x or 1.0 header. On return, contains the profile data. For information about the ColorSync 2.x profile header structure, see CM2Header. For information about the ColorSync 1.0 header, see CMHeader.

Return Value

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

Discussion

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

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

ImageApp

Declared In

ColorSyncDeprecated.h

CMGetProfileMD5

Gets the MD5 checksum from the profile header (message digest)

CMError CMGetProfileMD5 (
   CMProfileRef prof,
   CMProfileMD5 digest
);

Parameters

prof
digest

Return Value

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

Discussion

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

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMGetProfileRefCount

Obtains the current reference count for the specified profile.

CMError CMGetProfileRefCount (
   CMProfileRef prof,
   long *count
);

Parameters

prof: A profile reference of type CMProfileRef to the profile whose reference count is obtained.
count: A pointer to a reference count. On return, the reference count for the specified profile reference.

Return Value

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

Discussion

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

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.1 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetPS2ColorRendering

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

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

Parameters

srcProf: A profile reference to a profile that supplies the rendering intent for the CRD.
dstProf: A profile reference to a profile from which to extract the CRD data.
flags: If the value of flags is equal to cmPS8bit, the generated PostScript will utilize 8-bit encoding whenever possible to achieve higher data compaction. If the value of flags is not equal to cmPS8bit, the generated data will be 7-bit safe, in either ASCII or ASCII base-85 encoding.
proc: A pointer to a callback flatten function to perform the data transfer. For information, see the function CMFlattenProcPtr.
refCon: An untyped pointer to arbitrary data supplied by your application. CMGetPS2ColorSpace passes this data in calls to your CMFlattenProcPtr function.
preferredCMMnotfound: A pointer to a flag for whether the preferred CMM was found. On return, has the value true if the CMM corresponding to profile was not available or if it was unable to perform the function and the default CMM was used. Otherwise, has the value false.

Return Value

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

Discussion

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

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

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetPS2ColorRenderingIntent

Obtains the rendering intent element data in text format usable as the parameter to the PostScript findRenderingIntent operator, which specifies the color-matching option for subsequent graphics data.

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

Parameters

srcProf: A profile reference to the source profile that defines the data color space and identifies the preferred CMM.
flags: If the value of flags is equal to cmPS8bit, the generated PostScript will utilize 8-bit encoding whenever possible to achieve higher data compaction. If the value of flags is not equal to cmPS8bit, the generated data will be 7-bit safe, in either ASCII or ASCII base-85 encoding.
proc: A low-level data transfer function supplied by the calling application to receive the PostScript data from the CMM. For more information, see the function CMFlattenProcPtr.
refCon: An untyped pointer to arbitrary data supplied by your application. CMGetPS2ColorSpace passes this data in calls to your CMFlattenProcPtr function.
preferredCMMnotfound: A pointer to a flag for whether the preferred CMM was found. On return, has the value true if the CMM corresponding to profile was not available or if it was unable to perform the function and the default CMM was used. Otherwise, has the value false.

Return Value

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

Discussion

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetPS2ColorRenderingVMSize

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

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

Parameters

srcProf: A profile reference to a profile that supplies the rendering intent for the CRD.
dstProf: A profile reference to the destination printer profile.
vmSize: A pointer to a memory size. On return, the virtual memory size of the CRD.
preferredCMMnotfound: A pointer to a flag for whether the preferred CMM was found. On return, has the value true if the CMM corresponding to profile was not available or if it was unable to perform the function and the default CMM was used. Otherwise, has the value false.

Return Value

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

Discussion

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetPS2ColorSpace

Obtains color space element data in text format usable as the parameter to the PostScript setColorSpace operator, which characterizes the color space of subsequent graphics data.

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

Parameters

srcProf: A profile reference to the source profile that defines the data color space and identifies the preferred CMM.
flags: If the value of flags is equal to cmPS8bit, the generated PostScript will utilize 8-bit encoding whenever possible to achieve higher data compaction. If the value of flags is not equal to cmPS8bit, the generated data will be 7-bit safe, in either ASCII or ASCII base-85 encoding.
proc: A pointer to a callback flatten function to receive the PostScript data from the CMM. For information, see the function CMFlattenProcPtr.
refCon: An untyped pointer to arbitrary data supplied by your application. CMGetPS2ColorSpace passes this data in calls to your CMFlattenProcPtr function.
preferredCMMnotfound: A pointer to a flag for whether the preferred CMM was found. On return, has the value true if the CMM corresponding to profile was not available or if it was unable to perform the function and the default CMM was used. Otherwise, has the value false.

Return Value

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

Discussion

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

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

uses the PostScript cmPS2CSATag, if it exists
otherwise, uses the multidimensional table tag (cmAToB0, cmAToB1, or cmAToB2), if it exists, for the rendering intent currently specified by the profile
otherwise, uses the multidimensional table tag cmAToB0, if it exists
otherwise, for display profiles only, uses the tristimulus tags (cmRedColorantTag, cmGreenColorantTag, cmBlueColorantTag) and the tonal curve tags (cmRedTRCTag, cmGreenTRCTag, and cmBlueTRCTag)

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

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetSystemProfile

Obtains a reference to the current system profile.

CMError CMGetSystemProfile (
   CMProfileRef *prof
);

Parameters

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

Return Value

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

Discussion

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

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

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

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

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

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

Version Notes

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

QuartzCache

Declared In

ColorSyncDeprecated.h

CMIterateCMMInfo

Iterates through the color management modules installed on the system.

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

Parameters

proc: A calling-program-supplied callback function that allows your application to monitor progress or abort the operation.
count: A pointer to the number of available CMMs.
refCon: A reference constant containing data specified by the calling application program.

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMIterateColorDevices

Iterates through the color devices available on the system, returning device information to a callback you supply.

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

Parameters

proc: A pointer to a function that iterates through device information available on the system. This is optional, but allows you to obtain device information. If provided, your callback is invoked once for each registered device.
seed: A pointer to a seed value. This is optional. If you pass a pointer to a seed value that is the same as the current seed value, then the callback function specified by the proc parameter is not invoked.
count: On output, the number of color devices available on the system.
refCon: An optional value that passed to your callback.

Return Value

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

Discussion

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

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Related Sample Code

Declared In

ColorSyncDeprecated.h

CMIterateColorSyncFolder

Iterates over the available profiles.

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

Parameters

proc

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

seed

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

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

count

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

refCon

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

Return Value

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

Discussion

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

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

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

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

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

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

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

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

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

Version Notes

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.5 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

ImageApp

Declared In

ColorSyncDeprecated.h

CMIterateDeviceProfiles

Iterates through the device profiles available on the system and returns information about profiles of the devices to a callback you supply.

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

Parameters

proc: A pointer to a function that iterates through device information available on the system. This is optional, but allows you to obtain profile information for each device. If provided, your callback is invoked once for each registered device.
seed: A pointer to a seed value. This is optional. If you pass a pointer to a seed value that is the same as the current seed value, then the callback function specified by the proc parameter is not invoked.
count: On output, the number of color devices available on the system.
flags: A value that specifies which set of profiles you want to iterate through. It can have the following values: cmIterateFactoryDeviceProfiles, cmIterateCustomDeviceProfiles, cmIterateCurrentDeviceProfiles, cmIterateAllDeviceProfiles or 0. Supplying 0 is the same as supplying cmIterateCurrentDeviceProfiles.
refCon: An optional value that passed to your callback.

Return Value

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

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Related Sample Code

Declared In

ColorSyncDeprecated.h

CMLaunchControlPanel

Launches the ColorSync preferences pane.

CMError CMLaunchControlPanel (
   UInt32 flags
);

Parameters

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

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 3.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMMakeProfile

Makes a display or abstract profile by modifying an existing one.

CMError CMMakeProfile (
   CMProfileRef prof,
   CFDictionaryRef spec
);

Parameters

prof: The profile to modify.
spec: A dictionary that specifies the modifications to make to the profile supplied in the prof parameter.

Return Value

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

Discussion

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

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

The dictionary can optionally contain these keys-value pairs:

"description", with an associated CFString value
"copyright", with an associated CFString value

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

**Table 1** Key-value pairs for “abstractLab”
Key	Value	Comment
`"gridPoints"`	A CFNumber (`SInt32`) that is an odd	Required
`"proc"`	A CFNumber (`SInt64`) coerced from a `LabToLabProcPtr` data type	Required
`"refcon"`	A CFNumber (`SInt64`) value coerced from a `void*` data type	Optional

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

**Table 2** Key-value pairs for “displayRGB”
Key	Value	Comment
`"targetGamma"`	A CFNumber (`Float`), for example, 1.8	Optional
`"targetWhite"`	A CFNumber (`SInt32`), for example, 6500	Optional
`"gammaR`	A CFNumber (`Float`), for example, 2.5	Required
`"gammaG"`	A CFNumber (`Float`), for example, 2.5	Required
`"gammaB"`	A CFNumber (`Float`), for example, 2.5	Required
`"tableChans"`	A CFNumber (`SInt32`), for example, 1 or 3	Optional
`"tableEntries"`	A CFNumber (`SInt32`), for example, 16 or 255	Optional
`"tableEntrySize"`	A CFNumber (`SInt32`), for example,1 or 2	Optional
`"tableData"`	A CFData (lut in RRRGGGBBB order)	Optional
`"phosphorRx"`	A CFNumber (`Float`)	Only if not supplying the `phospherSet` key.
`phosphorRy"`	A CFNumber (`Float`)	Only if not supplying the `phospherSet` key.
`phosphorGx"`	A CFNumber (`Float`)	Only if not supplying the `phospherSet` key.
`"phosphorGy"`	A CFNumber (`Float`)	Only if not supplying the `phospherSet` key.
`"phosphorBx"`	A CFNumber (`Float`)	Only if not supplying the `phospherSet` key.
`"phosphorBy"`	A CFNumber (`Float`)	Only if not supplying the `phospherSet` key.
`"phosphorSet"`	A CFString: "WideRGB", "700/525/450nm", "P22-EBU", "HDTV", "CCIR709", "sRGB", "AdobeRGB98" or "Trinitron"	Only if not supplying the phospher R, G, B keys
`"whitePointx"`	A CFNumber (`Float`)	Only if not supplying a `whiteTemp` key
`"whitePointy"`	A CFNumber (`Float`)	Only if not supplying a `whiteTemp` key
`"whiteTemp"`	A CFNumber (`SInt32`), for example, 5000, 6500, or 9300	Only if not supplying `whitePointx` and `whitePointy` keys

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

**Table 3** Key-value pairs for “displayID”
Key	Value	Comment
`"targetGamma"`	A CFNumber (`Float`), for example, 1.8	Optional
`"targetWhite"`	A CFNumber (`SInt32`), for example, 6500	Optional
`"displayID"`	A CFNumber (`SInt32`)	Required

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

Availability

Available in Mac OS X v. 10.3 and later.

Related Sample Code

VideoViewer

Declared In

ColorSyncDeprecated.h

CMNewProfile

Creates a new profile and associated backing copy.

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

Parameters

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

Return Value

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

Discussion

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

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

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

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

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

VideoViewer

Declared In

ColorSyncDeprecated.h

CMOpenProfile

Opens the specified profile and returns a reference to the profile.

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

Parameters

prof: A pointer to a profile reference of type CMProfileRef. On return, the reference refers to the opened profile.
theProfile: A pointer to a profile location of type CMProfileLocation for the profile to open. Commonly a profile is disk-file based, but it may instead be temporary, handle-based, pointer-based, or accessed through a procedure supplied by your application.

Return Value

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

Discussion

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

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

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

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

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

For example, your application can:

open a profile
call the CMGetProfileHeader function to obtain the profile’s header to modify its values
set new values
call the CMSetProfileHeader function to replace the modified header
pass the profile reference to a function such as NCWNewColorWorld as the source or destination profile in a color world for a color-matching session
When you close your reference to the profile by calling the function CMCloseProfile, your changes are discarded (unless you called the CMUpdateProfile function).

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

Declared In

ColorSyncDeprecated.h

CMProfileElementExists

Tests whether the specified profile contains a specific element based on the element’s tag signature.

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

Parameters

prof: A profile reference of type CMProfileRef that specifies the profile to examine.
tag: The tag signature (for example, ‘A2B0’, or constant cmAToB0Tag) for the element in question. For a complete list of the tag signatures a profile may contain, including a description of each tag, refer to the International Color Consortium Profile Format Specification. The signatures for profile tags are defined in the CMICCProfile.h header file.
found: A pointer to a flag for whether the element was found. On return, the flag has the value true if the profile contains the element or false if it does not.

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMProfileModified

Indicates whether the specified profile has been modified since it was created or last updated.

CMError CMProfileModified (
   CMProfileRef prof,
   Boolean *modified
);

Parameters

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

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.1 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMRegisterColorDevice

Registers a device with ColorSync.

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

Parameters

deviceSpec: The class of the device (e.g., 'scnr' ,'cmra' ,'prtr' ,'mntr' ).
deviceScope: The unique identifier of the class (Class + ID uniquely id's device).
deviceName: Name of the device. See the CFDictionary documentation for a description of the CFDictionaryRef data type.
deviceScope: Structure defining the user and host scope this device pertains to.

Return Value

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

Discussion

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

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMRemoveProfileElement

Removes an element corresponding to a specific tag from the specified profile.

CMError CMRemoveProfileElement (
   CMProfileRef prof,
   OSType tag
);

Parameters

prof: A profile reference of type CMProfileRef to the profile containing the tag remove.
tag: The tag signature for the element to remove.

Return Value

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

Discussion

The CMRemoveProfileElement function deletes the tag as well as the element data from the profile.

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMSetDefaultDevice

Sets the default device.

CMError CMSetDefaultDevice (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID
);

Parameters

deviceClass: The class of the device (e.g., 'scnr' ,'cmra' ,'prtr' ,'mntr' ).
deviceID: The unique identifier of the class (Class + ID uniquely id's device).

Return Value

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

Discussion

For each class of device, a device management layer may establish which of the registered devices is the default. This helps keep color management choices to a minimum and allows for some "automatic" features to be enabled, such as, "Default printer" as an output profile selection. If no such device (as specified by deviceClass and deviceID ) has been registered, an error is returned.

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMSetDeviceDefaultProfileID

Sets the default profile ID for a given device.

CMError CMSetDeviceDefaultProfileID (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   CMDeviceProfileID defaultProfID
);

Parameters

deviceClass: The device class for the device whose default profile you want to set. See “Device Classes” for a list of the constants you can supply.
deviceID: The device ID for the device whose default profile you want to set.
defaultID: The ID of profile you want to set as the default.

Return Value

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

Discussion

The default profile ID for a given device is an important piece of information because of the function CMGetProfileByUse. The function CMGetProfileByUse returns the default profile for devices depending on the user's selection in the ColorSync preferences pane. Device drivers and host software can set the default profile for a given device using the function CMSetDeviceDefaultProfileID.

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMSetDeviceFactoryProfiles

Establishes the profiles used by a given device.

CMError CMSetDeviceFactoryProfiles (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   CMDeviceProfileID defaultProfID,
   const CMDeviceProfileArray *deviceProfiles
);

Parameters

deviceClass: The device class for the device whose factory profiles you want to establish. See “Device Classes” for a list of the constants you can supply.
deviceID: The device ID for the device whose factory profiles you want to establish.
defaultProfID: The ID of the default profile for this device.
deviceProfiles: On output, points to array that contains the factory device profiles.

Return Value

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

Discussion

This function establishes the profiles used by a given device. It should be called after device registration to notify ColorSync of the device's profiles. Note that factory device profiles and the current device profiles might not be the same, since the latter may contain modifications to the factory set.

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMSetDeviceProfile

Change the profile used by a given device.

CMError CMSetDeviceProfile (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   const CMDeviceProfileScope *profileScope,
   CMDeviceProfileID profileID,
   const CMProfileLocation *profileLoc
);

Parameters

deviceClass: The device class for the device whose profile you want to set. See “Device Classes” for a list of the constants you can supply.
deviceID: The device ID for the device whose profile you want to set.
profileScope: A pointer to the structure defining the scope this profile pertains to.
profileID: The ID of the default profile for this device.
deviceProfLoc: A pointer to the CMProfileLocation of the profile. Since this structure is a fixed length structure, you can simply pass a pointer to a stack-based structure or memory allocated for it.

Return Value

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

Discussion

This function provides a way to change a profile used by a given device by ID. It can be called after device registration by calibration applications to reset a device's profile from factory defaults to calibrated profiles. In order for this call to be made successfully, you must pass the CMDeviceClass and CMDeviceID of the device being calibrated along with the CMDeviceProfileID of the profile to set. (Device selection and identification can be facilitated using the function CMIterateColorDevices). If an invalid CMDeviceClass or CMDeviceID is passed, an error (CMInvalidDeviceClass or CMInvalidDeviceID) is returned.

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMSetDeviceState

Sets the state of a device.

CMError CMSetDeviceState (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID,
   CMDeviceState deviceState
);

Parameters

deviceClass: The device class for the device whose state you want to set. See “Device Classes” for a list of the constants you can supply.
deviceID: The device ID for the device whose state you want to set.
deviceState: The device state to set. See “Device States” for the values you can supply.

Return Value

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

Discussion

This routines provides access for the device management layer to update the state of a particular device. For example, a device can be offline, busy, or calibrated. The state data passed in replaces the old state data with the value you supply.

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMSetGammaByAVID

Sets the gamma for the specified display device.

CMError CMSetGammaByAVID (
   CMDisplayIDType theID,
   CMVideoCardGamma *gamma
);

Parameters

theID: A Display Manager ID value. You pass the ID value for the display device for which to set the gamma.
gamma: A pointer to the gamma value to which you want to set the display device.

Return Value

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 3.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMSetPartialProfileElement

Sets part of the element data for a specific tag in the specified profile.

CMError CMSetPartialProfileElement (
   CMProfileRef prof,
   OSType tag,
   UInt32 offset,
   UInt32 byteCount,
   const void *elementData
);

Parameters

prof: A profile reference of type CMProfileRef to the profile containing the tag for which the element data is set.
tag: The tag signature for the element whose data is set. The tag identifies the element. For a complete list of the tag signatures a profile may contain, including a description of each tag, refer to the International Color Consortium Profile Format Specification. The signatures for profile tags are defined in the CMICCProfile.h header file.
offset: The offset in the existing element data where data transfer should begin.
byteCount: The number of bytes of element data to transfer.
elementData: A pointer to the buffer containing the element data to transfer to the profile.

Return Value

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

Discussion

You can use the CMSetPartialProfileElement function to set the data for an element when the amount of data is large and you need to copy it to the profile in segments.

After you set the element size, you can call this function repeatedly, as many times as necessary, each time appending a segment of data to the end of the data already copied until all the element data is copied.

If you know the size of the element data, you should call the function CMSetProfileElementSize to reserve it before you call CMSetPartialProfileElement to set element data in segments. Setting the size first avoids the extensive overhead required to increase the size for the element data with each call to append another segment of data.

To copy the entire data for an element as a single operation, when the amount of data is small enough to allow this, call the function CMSetProfileElement.

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMSetProfileByAVID

Sets the profile for the specified monitor, optionally setting video card gamma.

CMError CMSetProfileByAVID (
   CMDisplayIDType theID,
   CMProfileRef prof
);

Parameters

theAVID: A Display Manager ID value. You pass the ID value for the monitor for which to set the profile.
prof: A profile reference. Before calling CMSetProfileByAVID, set the reference to identify the profile for the monitor specified by theAVID.

Return Value

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

Discussion

If you specify a profile that contains the optional profile tag for video card gamma, CMSetProfileByAVID extracts the tag and sets the video card based on the tag data. This is the only ColorSync function that sets video card gamma. The tag constant cmVideoCardGammaTag is described in “Video Card Gamma Tags.”

When a user sets a display profile using the Monitors & Sound control panel, the system profile is set to the same profile. When you call CMSetProfileByAVID to set a profile for a monitor, you may also wish to make that profile the system profile. If so, you must call CMSetSystemProfile explicitly—calling CMSetProfileByAVID alone has no affect on the system profile.

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.5 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMSetProfileDescriptions

Sets the description tag data for a specified profile.

CMError CMSetProfileDescriptions (
   CMProfileRef prof,
   const char *aName,
   UInt32 aCount,
   ConstStr255Param mName,
   ScriptCode mCode,
   const UniChar *uName,
   UniCharCount uCount
);

Parameters

prof: A reference to the profile into which to set the description tag data.
aName: A pointer to a 7-bit Roman ASCII profile name string to be set for the profile. This string must be null-terminated.
aCount: A count of the number of characters in the string specified in the aName parameter
mName: A pointer to the localized profile name string in Mac script-code format which is to be set for the profile. This string must be null-terminated.
mCode: The script code corresponding to the string specified by the mName parameter.
uName: A pointer to the localized Unicode profile name string which is to be set for the profile. This string must be null-terminated
uCount: A count of the number of Unicode characters in string specified by the uName parameter. Do not confuse this with a byte count, because each Unicode character requires two bytes.

Return Value

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMSetProfileElement

Sets or replaces the element data for a specific tag in the specified profile.

CMError CMSetProfileElement (
   CMProfileRef prof,
   OSType tag,
   UInt32 elementSize,
   const void *elementData
);

Parameters

prof: A profile reference of type CMProfileRef to the profile containing the tag for which the element data is set.
tag: The tag signature for the element whose data is set. For a complete list of the tag signatures a profile may contain, including a description of each tag, refer to the International Color Consortium Profile Format Specification. The signatures for profile tags are defined in the CMICCProfile.h header file.
elementSize: The size in bytes of the element data set.
elementData: A pointer to the buffer containing the element data to transfer to the profile.

Return Value

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

Discussion

The CMSetProfileElement function replaces existing element data if an element with the specified tag is already present in the profile. Otherwise, it sets the element data for a new tag. Your application is responsible for allocating memory for the buffer to hold the data to transfer.

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMSetProfileElementReference

Adds a tag to the specified profile to refer to data corresponding to a previously set element.

CMError CMSetProfileElementReference (
   CMProfileRef prof,
   OSType elementTag,
   OSType referenceTag
);

Parameters

prof: A profile reference of type CMProfileRef to the profile to add the tag to.
elementTag: The original element’s signature tag corresponding to the element data to which the new tag will refer.
referenceTag: The new tag signature to add to the profile to refer to the element data corresponding to elementTag.

Return Value

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

Discussion

After the CMSetProfileElementReference function executes successfully, the specified profile will contain more than one tag corresponding to a single piece of data. All of these tags are of equal importance. Your application can set a reference to an element that was originally a reference itself without circularity.

If you call the function CMSetProfileElement subsequently for one of the tags acting as a reference to another tag’s data, then the element data you provide is set for the tag and the tag is no longer considered a reference. Instead, the tag corresponds to its own element data and not that of another tag.

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMSetProfileElementSize

Reserves the element data size for a specific tag in the specified profile before setting the element data.

CMError CMSetProfileElementSize (
   CMProfileRef prof,
   OSType tag,
   UInt32 elementSize
);

Parameters

prof: A profile reference of type CMProfileRef to the profile in which the element data size is reserved.
tag: The tag signature for the element whose size is reserved. The tag identifies the element. For a complete list of the tag signatures a profile may contain, including a description of each tag, refer to the International Color Consortium Profile Format Specification. The signatures for profile tags are defined in the CMICCProfile.h header file.
elementSize: The total size in bytes to reserve for the element data.

Return Value

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

Discussion

Your application can use the CMSetProfileElementSize function to reserve the size of element data for a specific tag before you call the function CMGetPartialProfileElement to set the element data. The most efficient way to set a large amount of element data when you know the size of the data is to first set the size, then call the CMSetPartialProfileElement function to set each of the data segments. Calling the CMSetProfileElementSize function first eliminates the need for the ColorSync Manager to repeatedly increase the size for the data each time you call the CMSetPartialProfileElement function.

In addition to reserving the element data size, the CMSetProfileElementSize function sets the element tag, if it does not already exist.

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMSetProfileHeader

Sets the header for the specified profile.

CMError CMSetProfileHeader (
   CMProfileRef prof,
   const CMAppleProfileHeader *header
);

Parameters

prof: A profile reference of type CMProfileRef to the profile whose header is set.
header: A pointer to the new header to set for the profile.

Return Value

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

Discussion

You can use the CMSetProfileHeader function to set a header for a version 1.0 or a version 2.x profile. Before you call this function, you must set the values for the header, depending on the version of the profile. For a version 2.x profile, you use a data structure of type CM2Header. For a version 1.0 profile, you use a data structure of type CMHeader. You pass the header you supply in the CMAppleProfileHeader union, described in CMAppleProfileHeader.

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMSetProfileLocalizedStringDictionary

Writes a dictionary of localized strings to a given tag in a profile.

CMError CMSetProfileLocalizedStringDictionary (
   CMProfileRef prof,
   OSType tag,
   CFDictionaryRef theDict
);

Parameters

prof: The profile to modify.
tag: The tag type of profile to modify.
theDict: The dictionary to modify. See the CFDictionary documentation for a description of the CFDictionaryRef data type.

Return Value

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

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMUnregisterColorDevice

Unregisters a device.

CMError CMUnregisterColorDevice (
   CMDeviceClass deviceClass,
   CMDeviceID deviceID
);

Parameters

deviceClass: The device class of the device you want to unregister. See “Device Classes” for a list of the constants you can supply.
deviceID: The device ID of the device you want to unregister.

Return Value

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

Discussion

When a device is no longer to be used on a system (as opposed to being offline), it should be unregistered. If a device is temporarily shut down or disconnected, it does not to be unregistered unless either of the following is true:

The device driver is being removed (uninstalled)
The device driver can’t access the device profiles without the device

Availability

Not available in CarbonLib.
Available in Mac OS X 10.1 and later.

Declared In

ColorSyncDeprecated.h

CMUpdateProfile

Saves modifications to the specified profile.

CMError CMUpdateProfile (
   CMProfileRef prof
);

Parameters

prof: A profile reference of type CMProfileRef to the profile to update.

Return Value

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

Discussion

The CMUpdateProfile function makes permanent any changes or additions your application has made to the profile identified by the profile reference, if no other references to that profile exist.

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

Each time an application calls the function CMOpenProfile, the function creates a unique reference to the profile. An application can also duplicate a profile reference by passing a copy to another task. You cannot use the CMUpdateProfile function to update a profile if more than one reference to the profile exists—attempting to do so will result in an error return. You can call the function CMGetProfileRefCount to determine the reference count for a profile reference.

You cannot use the CMUpdateProfile function to update a ColorSync 1.0 profile.

After you fill in tags and their data elements for a new profile created by calling the function CMNewProfile, you must call the CMUpdateProfile function to write the element data to the new profile.

If you modify an open profile, you must call CMUpdateProfile to save the changes to the profile file before you call the function CMCloseProfile. Otherwise, the changes are discarded.

To modify a profile header, you use the function CMGetProfileHeader and the function CMSetProfileHeader.

To set profile elements outside the header, you use the function CMSetProfileElement, the function CMSetProfileElementSize, and the function CMSetPartialProfileElement.

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CMValidateProfile

Indicates whether the specified profile contains the minimum set of elements required by the current color management module (CMM) for color matching or color checking.

CMError CMValidateProfile (
   CMProfileRef prof,
   Boolean *valid,
   Boolean *preferredCMMnotfound
);

Parameters

prof: A profile reference of type CMProfileRef to the profile to validate.
valid: A pointer to a valid profile flag. On return, has the value true if the profile contains the minimum set of elements to be valid and false if it does not.
preferredCMMnotfound: A pointer to a flag for whether the preferred CMM was found. On return, has the value true if the CMM specified by the profile was not available to perform validation or does not support this function and the default CMM was used. Has the value false if the profile’s preferred CMM is able to perform validation.

Return Value

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

Discussion

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

If the preferred CMM supports this function, it determines if the profile contains the baseline elements for the profile class, which the CMM requires to perform color matching or gamut checking. For each profile class, such as a device profile, there is a specific set of required tagged elements defined by the ICC that the profile must include. The ICC also defines optional tags, which may be included in a profile. A CMM might use these optional elements to optimize or improve its processing. Additionally, a profile might include private tags defined to provide a CMM with processing capability particular to the needs of that CMM. The profile developer can define these private tags, register the tag signatures with the ICC, and include the tags in a profile. The CMM checks only for the existence of profile elements it does not check the element’s content and size.

If the preferred CMM does not support the CMValidateProfile function request, the ColorSync Manager calls the default CMM to handle the validation request.

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CWCheckBitmap

Tests the colors of the pixel data of a bitmap to determine whether the colors map to the gamut of the destination device.

CMError CWCheckBitmap (
   CMWorldRef cw,
   const CMBitmap *bitmap,
   CMBitmapCallBackUPP progressProc,
   void *refCon,
   CMBitmap *resultBitmap
);

Parameters

cw

A reference to the color world of type CMWorldRef to use for the color check.

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

bitmap

A pointer to a bitmap of type CMBitmap whose colors are to be checked.

progressProc

A calling program–supplied callback function that allows your application to monitor progress or abort the operation as the bitmap’s colors are checked against the gamut of the destination device. The default CMM calls your function approximately every half-second unless color checking occurs in less time this happens when there is a small amount of data to be checked. If the function returns a result of true, the operation is aborted. Specify NULL for this parameter if your application will not monitor the bitmap color checking. For information on the callback function and its type definition, see the function CMBitmapCallBackProcPtr.

refCon

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

resultBitmap

A pointer to a bitmap. On return, contains the results of the color check. The bitmap must have bounds equal to the parameter of the source bitmap pointed to by bitMap. You must allocate the pixel buffer pointed to by the image field of the structure CMBitmap and initialize the buffer to zeroes. Pixels are set to 1 if the corresponding pixel of the source bitmap indicated by bitMap is out of gamut. You must set the space field of the CMBitMap structure to cmGamutResult1Space color space storage format, as described in “Abstract Color Space Constants.”

Return Value

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

Discussion

When your application calls the CWCheckBitMap function, the ColorSync Manager dispatches the function to the preferred CMM. The ColorSync Manager determines the preferred CMM based on the color world configuration. If the color world you pass in was created by the CWConcatColorWorld function, then the keyIndex field of the CMConcatProfileSet data structure identifies the preferred CMM. If the preferred CMM is not available, the default CMM is used to perform the color matching.

For the CWCheckBitMap function to execute successfully, the source profile’s dataColorSpace field value and the space field value of the source bitmap pointed to by the bitMap parameter must specify the same data color space. CWCheckBitMap is not supported if the color world was initialized with a named color space profile.

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CWCheckColors

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

CMError CWCheckColors (
   CMWorldRef cw,
   CMColor *myColors,
   size_t count,
   UInt8 *result
);

Parameters

cw

A reference to the color world of type CMWorldRef describing how the test is to occur.

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

myColors

A pointer to an array containing a list of colors of type CMColor to be checked.This function assumes the color values are specified in the data color space of the source profile.

count

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

result

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

To access the packed bit-array, use code similar to the following:

inline bool GetNthBit (UInt8* result, int n)

    return ( 0 != (result[n/8] & (128>>(n%8))) );

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

Return Value

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

Discussion

The color test provides a preview of color matching using the specified color world.

All CMMs must support the CWCheckColors function.

If you have set a profile’s gamut-checking mask so that no gamut information is included—see “Flag Mask Definitions for Version 2.x Profiles” — CWCheckColors returns the cmCantGamutCheckError error.

The CWCheckColors function supports matching sessions set up with one of the multichannel color data types. CWCheckColors is not supported if the color world was initialized with a named color space profile.

Availability

Available in CarbonLib 1.0 and later when ColorSync 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

CWConcatColorWorld

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

CMError CWConcatColorWorld (
   CMWorldRef *cw,
   CMConcatProfileSet *profileSet
);

Parameters

cw

A pointer to a color world. On return, a reference to a color world of type CMWorldRef. You pass the returned reference to other functions that use the color world for color-matching and color-checking sessions.

profileSet

A pointer of type CMConcatProfileSet to an array of profiles describing the processing to carry out. You create the array and initialize it in processing order—source through destination.

You set the keyIndex field of the CMConcatProfileSet data structure to specify the zero-based index of the profile within the profile array whose specified CMM should be used for the entire color-matching or color-checking session. The profile header’s CMMType field specifies the CMM. This CMM will fetch the profile elements necessary for the session.

Note that starting with ColorSync 2.5, the user can set a preferred CMM with the ColorSync control panel. If that CMM is available, ColorSync will use that CMM for all color conversion and matching operations the CMM is capable of performing.

Return Value

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

Discussion

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

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

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

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

In the profile array, you can pass in one or more profiles, but you must specify at least one profile. If you specify only one profile, it must be a device link profile. If you specify a device link profile, you cannot specify any other profiles in the profiles array; a device link profile must be used alone.
In the profile array, you can specify an abstract profile anywhere in the sequence other than as the first or last profile.
For the first and last profiles, you can specify device profiles or color space conversion profiles. However, when you set up a color-matching session with a named color space profile and other profiles, the named color profile must be first or the last profile in the color world—it cannot be in the middle.
You cannot specify NULL to indicate the system profile. Note that starting with version 2.5, use of the system profile has changed.
If you specify a color space profile in the middle of the profile sequence, it is ignored by the default CMM.
If you specify a named color profile, it must be the first or the last profile. Otherwise, CWConcatColorWorld returns the value cmCantConcatenateError.

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

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

Version Notes

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

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

ColorSyncDeprecated.h

CWDisposeColorWorld

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

void CWDisposeColorWorld (
   CMWorldRef cw
);

Parameters

cw

A color world reference of type CMWorldRef.

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

Discussion

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

Declared In

ColorSyncDeprecated.h

CWFillLookupTexture

Fills a 3-D lookup texture from a color world.

CMError CWFillLookupTexture (
   CMWorldRef cw,
   UInt32 gridPoints,
   UInt32 format,
   UInt32 dataSize,
   void *data
);

Parameters

cw: The color world to use.
gridPoints: The number of grid points per channel in the texture.
format: The format of pixels in texture; for example, cmTextureRGBtoRGBX8.
dataSize: The size in bytes of texture data to fill.
data: On output, points to the texture data to fill.

Return Value

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

Discussion

You can use the resulting table in OpenGL to accelerate color management in hardware.

Availability

Available in Mac OS X v. 10.3 and later.

Related Sample Code

ImageApp

Declared In

ColorSyncDeprecated.h

CWMatchBitmap

Matches the colors of a bitmap to the gamut of a destination device using the profiles specified by a color world.

CMError CWMatchBitmap (
   CMWorldRef cw,
   CMBitmap *bitmap,
   CMBitmapCallBackUPP progressProc,
   void *refCon,
   CMBitmap *matchedBitmap
);

Parameters

cw

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

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

bitmap

A pointer to a bitmap of type CMBitmap whose colors are to be matched.

progressProc

A calling program–supplied universal procedure pointer to a callback function that allows your application to monitor progress or abort the operation as the bitmap colors are matched. The default CMM calls your function approximately every half-second unless color matching occurs in less time this happens when there is a small amount of data to be matched. If the function returns a result of true, the operation is aborted. To match colors without monitoring the process, specify NULL for this parameter. For a description of the function your application supplies, see the function CMBitmapCallBackProcPtr.

refCon

A pointer to a reference constant for application data passed through as a parameter to calls to the progressProc function.

matchedBitmap

A pointer to a bitmap. On return, contains the color-matched image. You must allocate the pixel buffer pointed to by the image field of the structure CMBitmap. If you specify NULL for matchedBitMap, then the source bitmap is matched in place.

Return Value

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

Discussion

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

You should ensure that the buffer pointed to by the image field of the bitmap passed in the bitMap parameter is zeroed out before you call this function.

The ColorSync Manager does not explicitly support a CMY color space. However, for printers that have a CMY color space, you can use either of the following circumventions to make the adjustment:

You can use a CMY profile, which the ColorSync Manager does support, with a CMYK color space. If you specify a CMYK color space in this case, the ColorSync Manager zeroes out the K channel to simulate a CMY color space.
You can use an RGB color space and pass in the bitmap along with an RGB profile, then perform the conversion from RGB to CMY yourself.

For this function to execute successfully, the source profile’s dataColorSpace field value and the space field value of the source bitmap pointed to by the bitMap parameter must specify the same data color space. Additionally, the destination profile’s dataColorSpace field value and the space field value of the resulting bitmap pointed to by the matchedBitMap parameter must specify the same data color space, unless the destination profile is a named color space profile.

If you set matchedBitMap to NULL to specify in-place matching, you must be sure the space required by the destination bitmap is less than or equal to the size of the source bitmap.

Version Notes

The color spaces currently supported for the CWMatchBitmap function are defined in “Color Space Constants With Packing Formats.” Support for the following color space constants, was added with ColorSync version 2.5:

cmGray16Space
cmGrayA32Space
cmRGB48Space.
cmCMYK64Space
cmLAB48Space

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

ColorMatching

Declared In

ColorSyncDeprecated.h

CWMatchColors

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

CMError CWMatchColors (
   CMWorldRef cw,
   CMColor *myColors,
   size_t count
);

Parameters

cw

A reference to the color world of type CMWorldRef that describes how matching is to occur in the color-matching session.

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

myColors

A pointer to an array containing a list of colors of type CMColor. On input, contains the list of colors to match. On return, contains the list of matched colors specified in the color data space of the color world’s destination profile.

count

A one-based count of the number of colors in the color list of the myColors array.

Return Value

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

Discussion

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

All color management modules (CMM)s must support this function.

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 1.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

NCMGetProfileLocation

Obtains either a profile location structure for a specified profile or the size of the location structure for the profile.

CMError NCMGetProfileLocation (
   CMProfileRef prof,
   CMProfileLocation *theProfile,
   UInt32 *locationSize
);

Parameters

prof: A profile reference of type CMProfileRef. Before calling NCMGetProfileLocation, you set the reference to specify the profile for which you wish to obtain the location or location structure size.
theProfile: A pointer to a profile location structure, as described in CMProfileLocation. If you pass NULL, NCMGetProfileLocation returns the size of the profile location structure for the profile specified by prof in the locationSize parameter. If you instead pass a pointer to memory you have allocated for the structure, on return, the structure specifies the location of the profile specified by prof.
locationSize: A pointer to a value of type long. If you pass NULL for the profLoc parameter, on return, locationSize contains the size in bytes of the profile location structure for the profile specified by prof. If you pass a pointer to a profile location structure in profLoc, set locationSize to the size of the structure before calling NCMGetProfileLocation, using the constant cmCurrentProfileLocationSize.

Return Value

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

Discussion

The NCMGetProfileLocation function is available starting with ColorSync version 2.5. It differs from its predecessor, CMGetProfileLocation, in that the newer version has a parameter for the size of the location structure for the specified profile.

You should use NCMGetProfileLocation rather than CMGetProfileLocation for the following reasons:

Code using the older version (CMGetProfileLocation) may not be as easily ported to other platforms.
Specifying the size of the profile location structure ensures that it can grow, if necessary, in the future.

The best way to use NCMGetProfileLocation is to call it twice:

Pass a reference to the profile to locate in the prof parameter and NULL for the profLoc parameter. NCMGetProfileLocation returns the size of the location structure in the locationSize parameter.
Allocate enough space for a structure of the returned size, then call the function again, passing a pointer in the profLoc parameter; on return, the structure specifies the location of the profile.

It is possible to call NCMGetProfileLocation just once, using the constant cmCurrentProfileLocationSize for the size of the allocated profile location structure and passing the same constant for the locationSize parameter. The constant cmCurrentProfileLocationSize may change in the future, but will be consistent within the set of headers you build your application with. However, if the size of the CMProfileLocation structure changes in a future version of ColorSync (and the value of cmCurrentProfileLocationSize as well) and you do not rebuild your application, NCMGetProfileLocation may return an error.

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.5 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

NCWConcatColorWorld

Defines a color world for color transformations among a series of concatenated profiles.

CMError NCWConcatColorWorld (
   CMWorldRef *cw,
   NCMConcatProfileSet *profileSet,
   CMConcatCallBackUPP proc,
   void *refCon
);

Parameters

cw: A reference to a color world that the ColorSync Manager returns if the function completes successfully. You pass this reference to other functions that use the color world for color-matching and color-checking sessions.
profileSet: An array of profiles describing the processing to be carried out. The array is in processing order source through destination.
proc: A calling-program-supplied callback function that allows your application to monitor progress or abort the operation.
refCon: A reference constant containing data specified by the calling application program.

Return Value

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

Discussion

The caller can override the color management module (CMM) that would normally be selected by ColorSync by providing a CMM identifier in the NCMConcatProfileSet structure, or pass 0 to accept ColorSync's CMM selection (note that this could either be the user's preferred CMM selection or the CMM called for in the profile). The flags and k parameters are provided to allow easy customization of such attributes as quality and gamut-checking, while preserving the other settings. Each profile in the set can be customized by overriding the intent, and the selection of the transform tag. Together with other profiles, a custom-rendering environment can be set up to transform to or from device-dependent spaces with a minimum of gamut compression and/or unnecessary transformations to and from connection spaces. This flexibility comes at the price of specific knowledge of the profile contents and how device gamuts overlap.

Note that for standard input and output device profiles, A2B and B2A tags represent transforms from data space to connection space and from connection space to data space, respectively. Under these circumstances, the caller would not normally be able to use the same transform tags (e.g., kUseAtoB ) consecutively, since a connection space would not be the same as the subsequent data space. If the spaces aren't the same, the caller will get a cmCantConcatenateError error returned. For profiles of type cmLinkClass, cmAbstractClass, cmColorSpaceClass , and cmNamedColorClass , these constants are not always meaningful, and the caller is encouraged to think in terms of the actual tags present in the profiles (e.g., A2B0 or B2A0 ). Under these conditions, it may well be appropriate to specify two transform tags of the same type consecutively, as long as the actual color spaces align in between tags. If this is not the case, a cmCantConcatenateError error is returned.

The callback proc is provided as protection against the appearance of a stalled machine during lengthy color world processing. If a CMM takes more than several seconds to process the information and create a color world, it will call the callback proc, if one is provided, and pass it the refCon provided. This is also true for NCWNewLinkProfile.

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
Available in Mac OS X 10.0 and later.

Related Sample Code

Declared In

ColorSyncDeprecated.h

NCWNewColorWorld

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

CMError NCWNewColorWorld (
   CMWorldRef *cw,
   CMProfileRef src,
   CMProfileRef dst
);

Parameters

cw

A pointer to a color world. On return, a reference to a matching session color world of type CMWorldRef. You pass this reference to other functions that use the color world.

src

A profile reference of type CMProfileRef that specifies the source profile for the color-matching world. This profile’s dataColorSpace element corresponds to the source data type for subsequent calls to functions that use this color world.

Starting with ColorSync version 2.5, you can call CMGetDefaultProfileBySpace to get the default profile for a specific color space or CMGetProfileByAVID to get a profile for a specific display.

With any version of ColorSync, you can specify a NULL value to indicate the ColorSync system profile. Note, however, that starting with version 2.5, use of the system profile has changed.

dst

A profile reference of type CMProfileRef that specifies the destination profile for the color-matching world. This profile’s dataColorSpace element corresponds to the destination data type for subsequent calls to functions using this color world.

Starting with ColorSync version 2.5, you can call CMGetDefaultProfileBySpace to get the default profile for a specific color space or CMGetProfileByAVID to get a profile for a specific display.

With any version of ColorSync, you can specify a NULL value to indicate the ColorSync system profile. Note, however, that starting with version 2.5, use of the system profile has changed.

Return Value

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

Discussion

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

You can specify a device profile or a color space conversion profile for the source and destination profiles.
You can not specify a device link profile or an abstract profile for either the source profile or the destination profile.
Only one profile can be a named color profile.
You can specify the system profile explicitly by reference or by giving NULL for either the source profile or the destination profile.

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

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

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

Version Notes

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

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.0 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

NCWNewLinkProfile

Obtains a profile reference for the specified by the profile location.

CMError NCWNewLinkProfile (
   CMProfileRef *prof,
   const CMProfileLocation *targetLocation,
   NCMConcatProfileSet *profileSet,
   CMConcatCallBackUPP proc,
   void *refCon
);

Parameters

prof: The returned profile reference.
targetLocation: The location of the profile. Commonly a profile is disk-file based. However, the profile may be a file-based profile, a handle-based profile, or a pointer-based profile.
profileSet: A pointer to the profile set structure.
proc: A calling-program-supplied callback function that allows your application to monitor progress or abort the operation.
refCon: A reference constant containing data specified by the calling application program.

Return Value

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

Discussion

The same new flexibility in creating color worlds is extended to link profiles, which are not assumed to go from input device color space to output device color space. The returned profile is open, and should be closed when you are finished with it.

Availability

Available in CarbonLib 1.0 and later when ColorSync 2.6 or later is present.
Available in Mac OS X 10.0 and later.

Declared In

ColorSyncDeprecated.h

Callbacks

CMBitmapCallBackProcPtr

Defines a pointer to a bitmap callback function that function reports on the progress of a color-matching or color-checking session being performed for a bitmap or a pixel map.

typedef Boolean (*MyCMBitmapCallBackProc)
(
   SInt16 progress,
   void * refCon
);
);

If you name your function MyCMBitmapCallBackProc, you would declare it like this:

Boolean MyCMBitmapCallBackProc (
   SInt16 progress,
   void * refCon
);

Parameters

progress: A byte count that begins at an arbitrary value when the function is first called. On each subsequent call, the value is decremented by an amount that can vary from call to call, but that reflects how much of the matching process has completed since the previous call. If the function is called at all, it will be called a final time with a byte count of 0 when the matching is complete.
refCon: The pointer to a reference constant passed to your MyCMBitmapCallBack function each time the color management module (CMM) calls your function.

Return Value

False indicates the color-matching or color-checking session should continue. True indicates the session should be aborted—for example, the user may be holding down the Command–period keys.

Discussion

Your MyCMBitmapCallBack function allows your application to monitor the progress of a color-matching or color-checking session for a bitmap or a pixel map. Your function can also terminate the matching or checking operation.

Your callback function is called by the CMM performing the matching or checking process if your application passes a pointer to your callback function in the progressProc parameter when it calls one of the following functions: CWCheckBitmap , CWMatchBitmap , CWCheckPixMap , and CWMatchPixMap. Note that your callback function may not be called at all if the operation completes in a very short period.

The CMM used for the color-matching session calls your function at regular intervals. For example, the default CMM calls your function approximately every half-second unless the color matching or checking occurs in less time; this happens when there is a small amount of data to match or check.

Each time the ColorSync Manager calls your function, it passes to the function any data stored in the reference constant. This is the data that your application specified in the refCon parameter when it called one of the color-matching or checking functions.

For large bitmaps and pixel maps, your application can display a progress bar or other indicator to show how much of the operation has been completed. You might, for example, use the reference constant to pass to the callback function a window reference to a dialog box. You obtain information on how much of the operation has completed from the progress parameter. The first time your callback is called, this parameter contains an arbitrary byte count. On each subsequent call, the value is decremented by an amount that can vary from call to call, but that reflects how much of the matching process has completed since the previous call. Using the current value and the original value, you can determine the percentage that has completed. If the callback function is called at all, it will be called a final time with a byte count of 0 when the matching is complete.

To terminate the matching or checking operation, your function should return a value of true. Because pixel-map matching is done in place, an application that allows the user to terminate the process should revert to the prematched image to avoid partial mapping.

For bitmap matching, if the matchedBitMap parameter of the CWMatchBitmap function specifies NULL, to indicate that the source bitmap is to be matched in place, and the application allows the user to abort the process, you should also revert to the prematched bitmap if the user terminates the operation.

Each time the ColorSync Manager calls your progress function, it passes a byte count in the progress parameter. The last time the ColorSync Manager calls your progress function, it passes a byte count of 0 to indicate the completion of the matching or checking process. You should use the 0 byte count as a signal to perform any cleanup operations your function requires, such as filling the progress bar to completion to indicate to the user the end of the checking or matching session, and then removing the dialog box used for the display.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMConcatCallBackProcPtr

Defines a pointer to a progress-monitoring function that the ColorSync Manager calls during lengthy color world processing.

typedef Boolean (*CMConcatCallBackProcPtr)
(
   SInt32 progress,
   void *refCon
);

If you name your function MyCMConcatCallBackProc, you would declare it like this:

Boolean MyCMConcatCallBackProc (
   SInt32 progress,
   void *refCon
);

Parameters

progress
refCon

Discussion

If a CMM takes more than several seconds to process the information and create a color world, it will call the Callback proc, if one is provided, and pass it the refCon provided

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMCountImageProfilesProcPtr

Defines a pointer to a function that obtains a count of the number of embeded profiles for a given image..

typedef CMError (*CMCountImageProfilesProcPtr)
(
   const FSSpec * spec,
   UInt32 * count
);

If you name your function MyCMCountImageProfilesProc, you would declare it like this:

CMError MyCMCountImageProfilesProc (
   const FSSpec * spec,
   UInt32 * count
);

Parameters

spec: See the File Manager documentation for a description of the FSSpec data type.
count

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

CMEmbedImageProcPtr

Defines a pointer to a function that embeds an image with an ICC profile..

typedef CMError (*CMEmbedImageProcPtr)
(
   const FSSpec * specFrom,
   const FSSpec * specInto,
   Boolean repl,
   CMProfileRef embProf
);

If you name your function MyCMEmbedImageProc, you would declare it like this:

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

Parameters

specFrom: See the File Manager documentation for a description of the FSSpec data type.
specInto: See the File Manager documentation for a description of the FSSpec data type.
repl
embProf

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

CMFlattenProcPtr

Defines a pointer to a data transfer callback function that transfers profile data from the format for embedded profiles to disk file format or vice versa.

typedef OSErr (*CMFlattenProcPtr) (
   SInt32 command,
   SInt32 *size,
   void *data,
   void *refCon
);

If you name your function MyCMFlattenProc, you would declare it like this:

OSErr MyCMFlattenProc (
   SInt32 command,
   SInt32 *size,
   void *data,
   void *refCon
);

Parameters

command

The command with which the MyCMFlattenCallback function is called. This command specifies the operation the function is to perform.

size

A pointer to a size value. On input, the size in bytes of the data to transfer. On return, the size of the data actually transferred.

data

A pointer to the buffer supplied by the ColorSync Manager to use for the data transfer.

refCon

A pointer to a reference constant that holds the application data passed in from the functions CMFlattenProfile, NCMUnflattenProfile, CMGetPS2ColorRenderingVMSize, CMGetPS2ColorRenderingIntent, or CMFlattenProfile. Each time the CMM calls your MyCMFlattenCallback function, it passes this data to the function.

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

Return Value

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

Discussion

IThis callback can be used, for example, by PostScript functions to transfer data from a profile to text format usable by a PostScript driver. Starting in ColorSync version 2.5, the ColorSync Manager calls your data transfer function directly, without going through the preferred, or any, CMM. So any references to the CMM in the discussion that follows are applicable only to versions of ColorSync prior to version 2.5. Where the discussion does not involve CMMs, it is applicable to all versions of ColorSync.

Your MyCMFlattenCallback function is called to flatten and unflatten profiles or to transfer PostScript-related data from a profile to the PostScript format to send to an application or device driver.

The ColorSync Manager and the CMM communicate with the MyCMFlattenCallback function using the command parameter to identify the operation to perform. To read and write profile data, your function must support the following commands: cmOpenReadSpool, cmOpenWriteSpool, cmReadSpool, cmWriteSpool, and cmCloseSpool.

You determine the behavior of your MyCMFlattenCallback function. The following sections describe how your function might handle the flattening and unflattening processes.

Flattening a Profile:

The ColorSync Manager calls the specified profile’s preferred CMM when an application calls the CMFlattenProfile function to transfer profile data embedded in a graphics document.

The ColorSync Manager determines if the CMM supports the CMFlattenProfile function. If so, the ColorSync Manager dispatches the CMFlattenProfile function to the CMM. If not, ColorSync calls the default CMM, dispatching the CMFlattenProfile function to it.

The CMM communicates with the MyCMFlattenCallback function using a command parameter to identify the operation to perform. The CMM calls your function as often as necessary, passing to it on each call any data transferred to the CMM from the CMFlattenProfile function’s refCon parameter.

The ColorSync Manager calls your function with the following sequence of commands: cmOpenWriteSpool, cmWriteSpool, and cmCloseSpool. Here is how you should handle these commands:

When the CMM calls your function with the cmOpenWriteSpool command, you should perform any initialization required to write profile data you receive from the CMM to a buffer or file.
The CMM will call your function with the cmWriteSpool command as many times as necessary to transfer all the profile data to you. Each time you are called, you should receive the data and write it to your buffer or file, returning in the size parameter the number of bytes of data you actually accepted.
When the CMM calls your function with the cmCloseSpool command, you should perform any required cleanup processes.

As part of this process, your function can embed the profile data in a graphics document, for example, a PICT file or a TIFF file. For example, your MyCMFlattenCallback function can call the QuickDraw PicComment function to embed the flattened profile in a picture.

Unflattening a Profile:

When an application calls the CMUnflattenProfile function to transfer a profile that is embedded in a graphics document to an independent disk file, the ColorSync Manager calls your MyCMFlattenCallback function with the following sequence of commands: cmOpenReadSpool, cmReadSpool, cmCloseSpool. Here is how you should handle these commands:

When the ColorSync Manager calls your function with the cmOpenReadSpool command, you should perform any initialization required to read from the embedded profile format.
The ColorSync Manager calls your function with the cmReadSpool command as many times as necessary, directing your function to extract the profile data from the embedded format in the image file and return it to the ColorSync Manager in the data buffer. For each call, the ColorSync Manager specifies in the size parameter the number of bytes of data you should return. Each time your function is called it should read and return the requested data; it should also specify in the size parameter the actual number of bytes of data it returns.
When the ColorSync Manager calls your function with the cmCloseSpool command, you should perform any required cleanup processes.

Version Notes

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGetImageSpaceProcPtr

Defines a pointer to a function that obtains the signature of the data color space in which the color values of colors in an image are expressed.

typedef CMError (*CMGetImageSpaceProcPtr)
(
   const FSSpec * spec,
   OSType * space
);

If you name your function MyCMGetImageSpaceProc, you would declare it like this:

CMError MyCMGetImageSpaceProc (
   const FSSpec * spec,
   OSType * space
);

Parameters

spec: See the File Manager documentation for a description of the FSSpec data type.
space

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

CMGetIndImageProfileProcPtr

Defines a pointer to a function that obtains a specific embeded profile for a given image.

typedef CMError (*CMGetIndImageProfileProcPtr)
(
   const FSSpec * spec,
   UInt32 index,
   CMProfileRef * prof
);

If you name your function MyCMGetIndImageProfileProc, you would declare it like this:

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

Parameters

spec: See the File Manager documentation for a description of the FSSpec data type.
index
prof

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

CMIterateDeviceInfoProcPtr

Defines a pointer to a function that iterates through device information available on the system.

typedef OSErr (*CMIterateDeviceInfoProcPtr)
(
   const CMDeviceInfo * deviceInfo,
   void * refCon
);

If you name your function MyCMIterateDeviceInfoProc, you would declare it like this:

OSErr MyCMIterateDeviceInfoProc (
   const CMDeviceInfo * deviceInfo,
   void * refCon
);

Parameters

deviceData
refCon

Return Value

An OSErr value.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMIterateDeviceProfileProcPtr

Defines a pointer to a function that iterates through the device profiles available on the system.

typedef OSErr (*CMIterateDeviceProfileProcPtr)
(
   const CMDeviceInfo * deviceInfo,
   const NCMDeviceProfileInfo * profileInfo,
   void * refCon
);

If you name your function MyCMIterateDeviceProfileProc, you would declare it like this:

OSErr MyCMIterateDeviceProfileProc (
   const CMDeviceInfo * deviceInfo,
   const NCMDeviceProfileInfo * profileInfo,
   void * refCon
);

Parameters

deviceData
profileData
refCon

Return Value

An OSErr value.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMLinkImageProcPtr

Defines a pointer to a function that matches an image file with a device link profile.

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

If you name your function MyCMLinkImageProc, you would declare it like this:

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

Parameters

specFrom: See the File Manager documentation for a description of the FSSpec data type.
specInto: See the File Manager documentation for a description of the FSSpec data type.
repl
qual
lnkProf
lnkIntent

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

CMMatchImageProcPtr

Defines a pointer to a function that color matches an image file.

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

If you name your function MyCMMatchImageProc, you would declare it like this:

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

Parameters

specFrom: See the File Manager documentation for a description of the FSSpec data type.
specInto: See the File Manager documentation for a description of the FSSpec data type.
repl
qual
srcProf
srcIntent
dstProf

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

CMMIterateProcPtr

Defines a pointer to a function that iterates through color management modules installed on the system.

typedef OSErr (*CMMIterateProcPtr) (
   CMMInfo * iterateData,
   void * refCon
);

If you name your function MyCMMIterateProc, you would declare it like this:

OSErr MyCMMIterateProc (
   CMMInfo * iterateData,
   void * refCon
);

Parameters

iterateData
refCon

Return Value

An OSErr value.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMProfileAccessProcPtr

Defines a pointer to a profile access callback function that provides procedure-based access to a profile.

typedef OSErr (*CMProfileAccessProcPtr)
(
   SInt32 command,
   SInt32 offset,
   SInt32 *size,
   void *data,
   void *refCon
);

If you name your function MyCMProfileAccessProc, you would declare it like this:

OSErr MyCMProfileAccessProc (
   SInt32 command,
   SInt32 offset,
   SInt32 *size,
   void *data,
   void *refCon
);

Parameters

command: A command value indicating the operation to perform. Operation constants are described in “Profile Access Procedures.”
offset: For read and write operations, the offset from the beginning of the profile at which to read or write data.
size: A pointer to a size value. On input, for the cmReadAccess and cmWriteAccess command constants, a pointer to a value indicating the number of bytes to read or write; for the cmOpenWriteAccess command, the total size of the profile. On return, after reading or writing, the actual number of bytes read or written.
data: A pointer to a buffer containing data to read or write. On return, for a read operation, contains the data that was read.
refCon: A reference constant pointer that can store private data for the CMProfileAccessCallback function.

Return Value

An OSErr value.

Discussion

When your application calls the CMOpenProfile, CMNewProfile, CMCopyProfile, or CMNewLinkProfile functions, it may supply the ColorSync Manager with a profile location structure of type CMProfileLocation that specifies a procedure that provides access to a profile. In the structure, you provide a universal procedure pointer to a profile access procedure supplied by you and, optionally, a pointer to data your procedure can use. The ColorSync Manager calls your procedure when the profile is created, initialized, opened, read, updated, or closed.

When the ColorSync Manager calls your profile access procedure, it passes a constant indicating the operation to perform. The operations include creating a new profile, reading from the profile, writing the profile, and so on. Operation constants are described in “Profile Access Procedures.” Your procedure must be able to respond to each of these constants.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ColorSyncDeprecated.h

CMProfileFilterProcPtr

Defines a pointer to a profile filter callback function that examines the profile whose reference you specify and determines whether to include it in the profile search result list.

typedef Boolean (*CMProfileFilterProcPtr)
(
   CMProfileRef prof,
   void * refCon
);

If you name your function MyCMProfileFilterProc, you would declare it like this:

Boolean MyCMProfileFilterProc (
   CMProfileRef prof,
   void * refCon
);

Parameters

prof: A profile reference of type CMProfileRef to the profile to test.
refCon: A pointer to a reference constant that holds data passed through from the CMNewProfileSearch function or the CMUpdateProfileSearch function.

Return Value

A value of false indicates that the profile should be included; true indicates that the profile should be filtered out.

Discussion

Your MyCMProfileFilterCallback function is called after the CMNewProfileSearch function searches for profiles based on the search record’s contents as specified by the search bitmask.

When your application calls CMNewProfileSearch, it passes a reference to a search specification record of type CMSearchRecord of type CMSearchRecord that contains a filter field. If the filter field contains a pointer to your MyCMProfileFilterCallback function, then your function is called to determine whether to exclude a profile from the search result list. Your function should return true for a given profile to exclude that profile from the search result list. If you do not want to filter profiles beyond the criteria in the search record, specify a NULL value for the search record’s filter field.

After a profile has been included in the profile search result based on criteria specified in the search record, your MyCMProfileFilterCallback function can further examine the profile. For example, you may wish to include or exclude the profile based on criteria such as an element or elements not included in the CMSearchRecord search record. Your MyCMProfileFilterCallback function can also perform searching using AND or OR logic.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ColorSyncDeprecated.h

CMProfileIterateProcPtr

Defines a pointer to a profile iteration callback function that the ColorSync Manager calls for each found profile file as it iterates over the available profiles.

typedef OSErr (*CMProfileIterateProcPtr)
(
   CMProfileIterateData * iterateData,
   void * refCon
);

If you name your function MyCMProfileIterateProc, you would declare it like this:

OSErr MyCMProfileIterateProc (
   CMProfileIterateData * iterateData,
   void * refCon
);

Parameters

iterateData: A pointer to a structure of type CMProfileIterateData. When the function CMIterateColorSyncFolder calls MyProfileIterateCallback, as it does once for each found profile, the structure contains key information about the profile.
refCon: An untyped pointer to arbitrary data your application previously passed to the function CMIterateColorSyncFolder.

Return Value

An OSErr value. If MyCMProfileIterateCallback returns an error, CMIterateColorSyncFolder stops iterating and returns the error value to its caller (presumably your code).

Discussion

When your application needs information about the profiles currently available in the profiles folder, it calls the function CMIterateColorSyncFolder , which, depending on certain conditions, calls your callback routine once for each profile. See the description of CMIterateColorSyncFolder for information on when it calls the MyCMProfileIterateCallback function.

Your MyCMProfileIterateCallback function examines the structure pointed to by the iterateData parameter to obtain information about the profile it describes. The function determines whether to do anything with that profile, such as list its name in a pop-up menu of available profiles.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMProofImageProcPtr

Defines a pointer to a function that proofs an image.

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

If you name your function MyCMProofImageProc, you would declare it like this:

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

Parameters

specFrom: See the File Manager documentation for a description of the FSSpec data type.
specInto: See the File Manager documentation for a description of the FSSpec data type.
repl
qual
srcProf
srcIntent
dstProf
prfProf

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

CMSetIndImageProfileProcPtr

Defines a pointer to a function that sets a specific embeded profile for a given image.

typedef CMError (*CMSetIndImageProfileProcPtr)
(
   const FSSpec * specFrom,
   const FSSpec * specInto,
   Boolean repl,
   UInt32 index,
   CMProfileRef prof
);

If you name your function MyCMSetIndImageProfileProc, you would declare it like this:

CMError MyCMSetIndImageProfileProc (
   const FSSpec * specFrom,
   const FSSpec * specInto,
   Boolean repl,
   UInt32 index,
   CMProfileRef prof
);

Parameters

specFrom: See the File Manager documentation for a description of the FSSpec data type.
specInto: See the File Manager documentation for a description of the FSSpec data type.
repl
index
prof

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

CMUnembedImageProcPtr

Defines a pointer to a function that umembeds an ICC profile from an image.

typedef CMError (*CMUnembedImageProcPtr)
(
   const FSSpec * specFrom,
   const FSSpec * specInto,
   Boolean repl
);

If you name your function MyCMUnembedImageProc, you would declare it like this:

CMError MyCMUnembedImageProc (
   const FSSpec * specFrom,
   const FSSpec * specInto,
   Boolean repl
);

Parameters

specFrom: See the File Manager documentation for a description of the FSSpec data type.
specInto: See the File Manager documentation for a description of the FSSpec data type.
repl

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

CMValidImageProcPtr

Defines a pointer to a function that validates a specified image file.

typedef CMError (*CMValidImageProcPtr)
(
   const FSSpec * spec
);

If you name your function MyCMValidImageProc, you would declare it like this:

CMError MyCMValidImageProc (
   const FSSpec * spec
);

Parameters

spec: See the File Manager documentation for a description of the FSSpec data type.

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

CountImageProfilesProcPtr

Defines a pointer to a function that counts the number of embeded profiles for a given image.

typedef CMError (*CountImageProfilesProcPtr)
(
   const FSSpec * spec,
   UInt32 * count
);

If you name your function MyCountImageProfilesProc, you would declare it like this:

CMError MyCountImageProfilesProc (
   const FSSpec * spec,
   UInt32 * count
);

Parameters

spec: See the File Manager documentation for a description of the FSSpec data type.
count

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

EmbedImageProcPtr

Defines a pointer to an embed-image function.

typedef CMError (*EmbedImageProcPtr)
(
   const FSSpec * specFrom,
   const FSSpec * specInto,
   CMProfileRef embedProf,
   UInt32 embedFlags
);

If you name your function MyEmbedImageProc, you would declare it like this:

CMError MyEmbedImageProc (
   const FSSpec * specFrom,
   const FSSpec * specInto,
   CMProfileRef embedProf,
   UInt32 embedFlags
);

Parameters

specFrom: See the File Manager documentation for a description of the FSSpec data type.
specInto: See the File Manager documentation for a description of the FSSpec data type.
embedProf
embedFlags

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

GetImageSpaceProcPtr

Defines a pointer to a get-image-space function.

typedef CMError (*GetImageSpaceProcPtr)
(
   const FSSpec * spec,
   OSType * space
);

If you name your function MyGetImageSpaceProc, you would declare it like this:

CMError MyGetImageSpaceProc (
   const FSSpec * spec,
   OSType * space
);

Parameters

spec: See the File Manager documentation for a description of the FSSpec data type.
space

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

GetIndImageProfileProcPtr

Defines a pointer to a function that obtains a color profile for an individual image..

typedef CMError (*GetIndImageProfileProcPtr)
(
   const FSSpec * spec,
   UInt32 index,
   CMProfileRef * prof
);

If you name your function MyGetIndImageProfileProc, you would declare it like this:

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

Parameters

spec: See the File Manager documentation for a description of the FSSpec data type.
index
prof

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

MatchImageProcPtr

Defines a pointer to a match-image function.

typedef CMError (*MatchImageProcPtr)
(
   const FSSpec * specFrom,
   const FSSpec * specInto,
   UInt32 qual,
   UInt32 srcIntent,
   CMProfileRef srcProf,
   CMProfileRef dstProf,
   CMProfileRef prfProf,
   UInt32 matchFlags
);

If you name your function MyMatchImageProc, you would declare it like this:

CMError MyMatchImageProc (
   const FSSpec * specFrom,
   const FSSpec * specInto,
   UInt32 qual,
   UInt32 srcIntent,
   CMProfileRef srcProf,
   CMProfileRef dstProf,
   CMProfileRef prfProf,
   UInt32 matchFlags
);

Parameters

specFrom: See the File Manager documentation for a description of the FSSpec data type.
specInto: See the File Manager documentation for a description of the FSSpec data type.
qual
srcIntent
srcProf
dstProf
prfProf
matchFlags

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

SetIndImageProfileProcPtr

Defines a pointer to a function that sets a color profile for an individual image.

typedef CMError (*SetIndImageProfileProcPtr)
(
   const FSSpec * specFrom,
   const FSSpec * specInto,
   UInt32 index,
   CMProfileRef prof,
   UInt32 embedFlags
);

If you name your function MySetIndImageProfileProc, you would declare it like this:

CMError MySetIndImageProfileProc (
   const FSSpec * specFrom,
   const FSSpec * specInto,
   UInt32 index,
   CMProfileRef prof,
   UInt32 embedFlags
);

Parameters

specFrom: See the File Manager documentation for a description of the FSSpec data type.
specInto: See the File Manager documentation for a description of the FSSpec data type.
index
prof
embedFlags

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

UnembedImageProcPtr

Defines a pointer to an umembed-image function.

typedef CMError (*UnembedImageProcPtr)
(
   const FSSpec * specFrom,
   const FSSpec * specInto
);

If you name your function MyUnembedImageProc, you would declare it like this:

CMError MyUnembedImageProc (
   const FSSpec * specFrom,
   const FSSpec * specInto
);

Parameters

specFrom: See the File Manager documentation for a description of the FSSpec data type.
specInto: See the File Manager documentation for a description of the FSSpec data type.

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

ValidateImageProcPtr

Defines a pointer to a validate-image function.

typedef CMError (*ValidateImageProcPtr)
(
   const FSSpec * spec
);

If you name your function MyValidateImageProc, you would declare it like this:

CMError MyValidateImageProc (
   const FSSpec * spec
);

Parameters

spec: See the File Manager documentation for a description of the FSSpec data type.

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

ValidateSpaceProcPtr

Defines a pointer to a validate-space function.

typedef CMError (*ValidateSpaceProcPtr)
(
   const FSSpec * spec,
   OSType * space
);

If you name your function MyValidateSpaceProc, you would declare it like this:

CMError MyValidateSpaceProc (
   const FSSpec * spec,
   OSType * space
);

Parameters

spec: See the File Manager documentation for a description of the FSSpec data type.
space

Return Value

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

Availability

Available in Mac OS X v10.0 through Mac OS X v10.3.

Declared In

CMScriptingPlugin.h

Data Types

CalibratorInfo

Contains data used to calibrate a display.

struct CalibratorInfo {
   UInt32 dataSize;
   CMDisplayIDType displayID;
   UInt32 profileLocationSize;
   CMProfileLocation * profileLocationPtr;
   CalibrateEventUPP eventProc;
   Boolean isGood;
};
typedef struct CalibratorInfo CalibratorInfo;

Fields

dataSize
displayID
profileLocationSize
profileLocationPtr
eventProc
isGood

Availability

Available in Mac OS X v10.0 and later.

Declared In

CMCalibrator.h

CM2Header

Contains information that supports the header format specified by the ICC format specification for version 2.x profiles.

struct CM2Header {
   UInt32 size;
   OSType CMMType;
   UInt32 profileVersion;
   OSType profileClass;
   OSType dataColorSpace;
   OSType profileConnectionSpace;
   CMDateTime dateTime;
   OSType CS2profileSignature;
   OSType platform;
   UInt32 flags;
   OSType deviceManufacturer;
   UInt32 deviceModel;
   UInt32 deviceAttributes[2];
   UInt32 renderingIntent;
   CMFixedXYZColor white;
   OSType creator;
   char reserved[44];
};
typedef struct CM2Header CM2Header;

Fields

size

The total size in bytes of the profile.

CMMType

The signature of the preferred CMM for color-matching and color-checking sessions for this profile. To avoid conflicts with other CMMs, this signature must be registered with the ICC. For the signature of the default CMM, see “Default CMM Signature.”

profileVersion

The version of the profile format. The first 8 bits indicate the major version number, followed by 8 bits indicating the minor version number. The following 2 bytes are reserved.

The profile version number is not tied to the version of the ColorSync Manager. Profile formats and their versions are defined by the ICC. For example, a major version change may indicate the addition of new required tags to the profile format; a minor version change may indicate the addition of new optional tags.

profileClass

One of the seven profile classes supported by the ICC: input, display, output, named color space, device link, color space conversion, or abstract. For the signatures representing profile classes, see “Profile Classes.”

dataColorSpace

The color space of the profile. Color values used to express colors of images using this profile are specified in this color space. For a list of the color space signatures, see “Color Space Signatures.”

profileConnectionSpace

The profile connection space, or PCS. The signatures for the two profile connection spaces supported by ColorSync, cmXYZData and cmLabData, are described in “Color Space Signatures.”

dateTime

The date and time when the profile was created. You can use this value to keep track of your own versions of this profile. For information on the date and time format, see CMDateTime.

CS2profileSignature

The 'acsp' constant as required by the ICC format.

platform

The signature of the primary platform on which this profile runs. For Apple Computer, this is 'APPL'. For other platforms, refer to the International Color Consortium Profile Format Specification.

flags

Flags that provide hints, such as preferred quality and speed options, to the preferred CMM. The flags field consists of an unsigned long data type. The 16 bits in the low word, 0-15, are reserved for use by the ICC. The 16 bits in the high word, 16-31, are available for use by color management systems. For information on how these bits are defined and how your application can set and test them, see “Flag Mask Definitions for Version 2.x Profiles.”

deviceManufacturer

The signature of the manufacturer of the device to which this profile applies. This value is registered with the ICC.

deviceModel

The model of this device, as registered with the ICC.

deviceAttributes

Attributes that are unique to this particular device setup, such as media, paper, and ink types. The data type for this field is an array of two unsigned longs. The low word of deviceAttributes[0] is reserved by the ICC. The high word of deviceAttributes[0] and the entire word of deviceAttributes[1] are available for vendor use. For information on how the bits in deviceAttributes are defined and how your application can set and test them, see “Device Attribute Values for Version 2.x Profiles.”

renderingIntent

The preferred rendering intent for the object or file tagged with this profile. Four types of rendering intent are defined: perceptual, relative colorimetric, saturation, and absolute colorimetric. The renderingIntent field consists of an unsigned long data type. The low word is reserved by the ICC and is used to set the rendering intent. The high word is available for use. For information on how the bits in renderingIntent are defined and how your application can set and test them, see “Rendering Intent Values for Version 2.x Profiles.”

white

The profile illuminant white reference point, expressed in the XYZ color space.

creator

Signature identifying the profile creator.

reserved

This field is reserved for future use.

Discussion

The ColorSync Manager defines the CM2header profile structure to support the header format specified by the ICC format specification for version 2.x profiles. For a description of CMHeader, the ColorSync 1.0 profile header, see CMHeader. To obtain a copy of the International Color Consortium Profile Format Specification, or to get other information about the ICC, visit the ICC Web site at http://www.color.org/.

Your application cannot obtain a discrete profile header value using the element tag scheme available for use with elements outside the header. Instead, to set or modify values of a profile header, your application must obtain the entire profile header using the function CMGetProfileHeader and replace the header using the function CMSetProfileHeader.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CM2Profile

struct CM2Profile {
   CM2Header header;
   CMTagElemTable tagTable;
   char elemData[1];
};
typedef struct CM2Profile CM2Profile;
typedef CM2Profile * CM2ProfilePtr;

Fields

header
tagTable
elemData

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CM4Header

struct CM4Header {
   UInt32 size;
   OSType CMMType;
   UInt32 profileVersion;
   OSType profileClass;
   OSType dataColorSpace;
   OSType profileConnectionSpace;
   CMDateTime dateTime;
   OSType CS2profileSignature;
   OSType platform;
   UInt32 flags;
   OSType deviceManufacturer;
   UInt32 deviceModel;
   UInt32 deviceAttributes[2];
   UInt32 renderingIntent;
   CMFixedXYZColor white;
   OSType creator;
   CMProfileMD5 digest;
   char reserved[28];
};
typedef struct CM4Header CM4Header;

Fields

size
CMMType
profileVersion
profileClass
dataColorSpace
profileConnectionSpace
dateTime
CS2profileSignature
platform
flags
deviceManufacturer
deviceModel
deviceAttributes
renderingIntent
white
creator
digest
reserved

Availability

Available in Mac OS X v10.1 and later.

Declared In

ColorSyncDeprecated.h

CMAccelerationCalcData

struct CMAccelerationCalcData {
   SInt32 pixelCount;
   Ptr inputData;
   Ptr outputData;
   UInt32 reserved1;
   UInt32 reserved2;
};
typedef struct CMAccelerationCalcData CMAccelerationCalcData;

Fields

CMAccelerationCalcDataPtr

typedef CMAccelerationCalcData* CMAccelerationCalcDataPtr;

CMAccelerationCalcDataHdl

typedef CMAccelerationCalcDataPtr* CMAccelerationCalcDataHdl;

CMAccelerationTableData

struct CMAccelerationTableData {
   SInt32 inputLutEntryCount;
   SInt32 inputLutWordSize;
   Handle inputLut;
   SInt32 outputLutEntryCount;
   SInt32 outputLutWordSize;
   Handle outputLut;
   SInt32 colorLutInDim;
   SInt32 colorLutOutDim;
   SInt32 colorLutGridPoints;
   SInt32 colorLutWordSize;
   Handle colorLut;
   CMBitmapColorSpace inputColorSpace;
   CMBitmapColorSpace outputColorSpace;
   void *userData;
   UInt32 reserved1;
   UInt32 reserved2;
   UInt32 reserved3;
   UInt32 reserved4;
   UInt32 reserved5;
};
typedef struct CMAccelerationTableData CMAccelerationTableData;

Fields

CMAccelerationTableDataPtr

typedef CMAccelerationTableData* CMAccelerationTableDataPtr;

CMAccelerationTableDataHdl

typedef CMAccelerationTableDataPtr* CMAccelerationTableDataHdl;

CMAdaptationMatrixType

struct CMAdaptationMatrixType {
   OSType typeDescriptor;
   unsigned long reserved;
   Fixed adaptationMatrix[9];
};
typedef struct CMAdaptationMatrixType CMAdaptationMatrixType;

Fields

typeDescriptor
reserved
adaptationMatrix

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMAppleProfileHeader

Defines a data structure to provide access to both version 2.x and version 1.0 profiles, as specified by the International Color Consortium.

union CMAppleProfileHeader {
   CMHeader cm1;
   CM2Header cm2;
   CM4Header cm4;
};
typedef union CMAppleProfileHeader CMAppleProfileHeader;

Fields

cm1: A version 1.0 profile header. For a description of the ColorSync version 1.0 profile header, see CMHeader.
cm2: A current profile header. For a description of the ColorSync profile header, see CM2Header.
cm4

Discussion

The ColorSync Manager defines the CMAppleProfileHeader structure to provide access to both version 2.x and version 1.0 profiles, as specified by the International Color Consortium. To obtain a copy of the International Color Consortium Profile Format Specification, or to get other information about the ICC, visit the ICC Web site at http://www.color.org/.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMBitmap

Contains information that describes color bitmap images.

struct CMBitmap {
   char * image;
   long width;
   long height;
   long rowBytes;
   long pixelSize;
   CMBitmapColorSpace space;
   long user1;
   long user2;
};
typedef struct CMBitmap CMBitmap;

Fields

image: A pointer to a bit image.
width: The width of the bit image, that is, the number of pixels in a row.
height: The height of the bit image, that is, the number of rows in the image.
rowBytes: The offset in bytes from one row of the image to the next.
pixelSize: The number of bits per pixel. The pixel size should correspond to the packing size specified in the space field. This requirement is not enforced as of ColorSync version 2.5, but it may be enforced in future versions.
space: The color space in which the colors of the bitmap image are specified. For a description of the possible color spaces for color bitmaps, see “Color Space Constants With Packing Formats.”
user1: Not used by ColorSync. It is recommended that you set this field to 0.
user2: Not used by ColorSync. It is recommended that you set this field to 0.

Discussion

The ColorSync Manager defines a bitmap structure of type CMBitmap to describe color bitmap images. When your application calls the function CWMatchColors , you pass a pointer to a source bitmap of type CMBitmap containing the image whose colors are to be matched to the color gamut of the device specified by the destination profile of the given color world. If you do not want the image color matched in place, you can also pass a pointer to a resulting bitmap of type CMBitmap to define and hold the color-matched image.

For QuickDraw GX, an image can have an indexed bitmap to a list of colors. The ColorSync Manager does not support indexed bitmaps in the same way QuickDraw GX does. ColorSync supports indexed bitmaps only when the cmNamedIndexed32Space color space constant is used in conjunction with a named color space profile.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMBitmapCallBackProc

typedef CMBitmapCallBackProcPtr CMBitmapCallBackProc;

CMBitmapCallBackUPP

Defines a universal procedure pointer to a bitmap callback.

typedef CMBitmapCallBackProcPtr CMBitmapCallBackUPP;

Discussion

For more information, see the description of the CMBitmapCallBackProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMBufferLocation

struct CMBufferLocation {
   void * buffer;
   UInt32 size;
};
typedef struct CMBufferLocation CMBufferLocation;

Fields

buffer
size

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMCMYColor

Contains color values expressed in the CMY color space.

struct CMCMYColor {
   UInt16 cyan;
   UInt16 magenta;
   UInt16 yellow;
};
typedef struct CMCMYColor CMCMYColor;

Fields

cyan
magenta
yellow

Discussion

A color value expressed in the CMY color space is composed of cyan, magenta, and yellow component values. Each color component is expressed as a numeric value within the range of 0 to 65535 inclusive.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMCMYKColor

Contains color values expressed in the CMYK color space.

struct CMCMYKColor {
   UInt16 cyan;
   UInt16 magenta;
   UInt16 yellow;
   UInt16 black;
};
typedef struct CMCMYKColor CMCMYKColor;

Fields

cyan
magenta
yellow
black

Discussion

A color value expressed in the CMYK color space is composed of cyan, magenta, yellow, and black component values. Each color component is expressed as a numeric value within the range of 0 to 65535 inclusive.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMColor

Defines a union that can be used to specify a color value defined by one of the 15 data types supported by the union.

union CMColor {
   CMRGBColor rgb;
   CMHSVColor hsv;
   CMHLSColor hls;
   CMXYZColor XYZ;
   CMLabColor Lab;
   CMLuvColor Luv;
   CMYxyColor Yxy;
   CMCMYKColor cmyk;
   CMCMYColor cmy;
   CMGrayColor gray;
   CMMultichannel5Color mc5;
   CMMultichannel6Color mc6;
   CMMultichannel7Color mc7;
   CMMultichannel8Color mc8;
   CMNamedColor namedColor;
};
typedef union CMColor CMColor;

Fields

rgb: A color value expressed in the RGB color space as data of type CMRGBColor.
hsv: A color value expressed in the HSV color space as data of type CMHSVColor.
hls: A color value expressed in the HLS color space as data of type CMHLSColor.
XYZ: A color value expressed in the XYZ color space as data of type CMXYZColor.
Lab: A color value expressed in the L*a*b* color space as data of type CMLabColor.
Luv: A color value expressed in the L*u*v* color space as data of type CMLuvColor.
Yxy: A color value expressed in the Yxy color space as data of type CMYxyColor.
cmyk: A color value expressed in the CMYK color space as data of type CMCMYKColor.
cmy: A color value expressed in the CMY color space as data of type CMCMYColor.
gray: A color value expressed in the Gray color space as data of type CMGrayColor.
mc5: A color value expressed in the five-channel multichannel color space as data of type CMMultichannel5Color. See CMMultichannel5Color for a description of the CMMultichannel5Color data type.
mc6: A color value expressed in the six-channel multichannel color space as data of type CMMultichannel6Color. See CMMultichannel6Color for a description of the CMMultichannel6Color data type.
mc7: A color value expressed in the seven-channel multichannel color space as data of type CMMultichannel7Color. See CMMultichannel7Color for a description of the CMMultichannel7Color data type.
mc8: A color value expressed in the eight-channel multichannel color space as data of type CMMultichannel8Color. See CMMultichannel8Color for a description of the CMMultichannel8Color data type.
namedColor: A color value expressed as an index into a named color space. See CMNamedColor for a description of the CMNamedColor data type.

Discussion

A color union can contain one of the above fields.

Your application can use a union of type CMColor to specify a color value defined by one of the 15 data types supported by the union. Your application uses an array of color unions to specify a list of colors to match, check, or convert. The array is passed as a parameter to the general purpose color matching, color checking, or color conversion functions. The following functions use a color union:

The function CWMatchColors matches the colors in the color list array to the data color space of the destination profile specified by the color world.
The function CWCheckColors checks the colors in the color list array against the color gamut specified by the color world’s destination profile.
The color conversion functions, described in “Converting Between Color Spaces”, take source and destination array parameters of type CMColor specifying lists of colors to convert from one color space to another.

You do not use a union of type CMColor to convert colors expressed in the XYZ color space as values of type CMFixedXYZ because the CMColor union does not support the CMFixedXYZ data type.

Availability

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared In

CMApplication.h

CMConcatCallBackUPP

Defines a universal procedure pointer to a progress-monitoring function that the ColorSync Manager calls during lengthy color world processing.

typedef CMConcatCallBackProcPtr CMConcatCallBackUPP;

Discussion

For more information, see the description of the CMConcatCallBackProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMConcatProfileSet

Contains profile and other information needed to set up a color world.

struct CMConcatProfileSet {
   UInt16 keyIndex;
   UInt16 count;
   CMProfileRef profileSet[1];
};
typedef struct CMConcatProfileSet CMConcatProfileSet;

Fields

keyIndex: A zero-based index into the array of profile references identifying the profile whose CMM is used for the entire session. The profile’s CMMType field identifies the CMM.
count: The one-based count of profiles in the profile array. A minimum of one profile is required.
profileSet: A variable-length array of profile references. The references must be in processing order from source to destination. The rules governing the types of profiles you can specify in a profile array differ depending on whether you are creating a profile set for the function CWConcatColorWorld or for the function CWNewLinkProfile. See the function descriptions for details.

Discussion

You can call the function NCWNewColorWorld to create a color world for operations such as color matching and color conversion. A color world is normally based on two profiles—source and destination. But it can include a series of profiles that describe the processing for a work-flow sequence, such as scanning, printing, and previewing an image. To create a color world that includes a series of profiles, you use the function CWConcatColorWorld.

The array specified in the profileSet field identifies a concatenated profile set your application can use to establish a color world in which the sequential relationship among the profiles exists until your application disposes of the color world. Alternatively, you can create a device link profile composed of a series of linked profiles that remains intact and available for use again after your application disposes of the concatenated color world. In either case, you use a data structure of type CMConcatProfileSet to define the profile set.

A device link profile accommodates users who use a specific configuration requiring a combination of device profiles and possibly non-device profiles repeatedly over time.

To set up a color world that includes a concatenated set of profiles, your application uses the function CWConcatColorWorld , passing it a structure of type CMConcatProfileSet. The array you pass may contain a set of profile references or it may contain only the profile reference of a device link profile. To create a device link profile, your application calls the function CWNewLinkProfile, passing a structure of type CMConcatProfileSet.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMCurveType

struct CMCurveType {
   OSType typeDescriptor;
   UInt32 reserved;
   UInt32 countValue;
   UInt16 data[1];
};
typedef struct CMCurveType CMCurveType;

Fields

typeDescriptor
reserved
countValue
data

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMCWInfoRecord

Contains information about a given color world.

struct CMCWInfoRecord {
   UInt32 cmmCount;
   CMMInfoRecord cmmInfo[2];
};
typedef struct CMCWInfoRecord CMCWInfoRecord;

Fields

cmmCount

The number of CMMs involved in the color-matching session, either 1 or 2.

cmmInfo

An array containing two elements. Depending on the value that cmmCount returns, the cmmInfo array contains one or two records of type CMMInfoRecord reporting the CMM type and version number.

If cmmCount is 1, the first element of the array (cmmInfo[0]) describes the CMM and the contents of the second element of the array (cmmInfo[1]) is undefined.

If cmmCount is 2, the first element of the array (cmmInfo[0]) describes the source CMM and the second element of the array (cmmInfo[1]) describes the destination CMM.

Discussion

Your application supplies a color world information record structure of type CMCWInfoRecord as a parameter to the CMGetCWInfo function to obtain information about a given color world. The ColorSync Manager uses this data structure to return information about the color world.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ColorSyncDeprecated.h

CMDataType

struct CMDataType {
   OSType typeDescriptor;
   UInt32 reserved;
   UInt32 dataFlag;
   char data[1];
};
typedef struct CMDataType CMDataType;

Fields

typeDescriptor
reserved
dataFlag
data

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMDateTime

Contains data that specifies a date and time in year, month, day of the month, hours, minutes, and seconds

struct CMDateTime {
   UInt16 year;
   UInt16 month;
   UInt16 dayOfTheMonth;
   UInt16 hours;
   UInt16 minutes;
   UInt16 seconds;
};
typedef struct CMDateTime CMDateTime;

Fields

year: The year. Note that to indicate the year 1984, this field would store the integer 1984, not just 84.
month: The month of the year, where 1 represents January, and 12 represents December.
dayOfTheMonth: The day of the month, ranging from 1 to 31.
hours: The hour of the day, ranging from 0 to 23, where 0 represents midnight and 23 represents 11:00 P.M.
minutes: The minutes of the hour, ranging from 0 to 59.
seconds: The seconds of the minute, ranging from 0 to 59.

Discussion

The ColorSync Manager defines the CMDateTime data structure to specify a date and time in year, month, day of the month, hours, minutes, and seconds. Other ColorSync structures use the CMDateTime structure to specify information such as the creation date or calibration date for a color space profile.

The CMDateTime structure is similar to the Macintosh Toolbox structure DateTimeRec, and like it, is intended to hold date and time values only for a Gregorian calendar.

The CMDateTime structure is platform independent. However, when used with Macintosh Toolbox routines such as SecondsToDate and DateToSeconds, which use seconds to designate years, the range of years that can be represented is limited.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMDateTimeType

struct CMDateTimeType {
   OSType typeDescriptor;
   UInt32 reserved;
   CMDateTime dateTime;
};
typedef struct CMDateTimeType CMDateTimeType;

Fields

typeDescriptor
reserved
dateTime

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMDeviceData

struct CMDeviceData {
   UInt32 dataVersion;
   CMDeviceSpec deviceSpec;
   CMDeviceScope deviceScope;
   CMDeviceState deviceState;
   CMDeviceProfileID defaultProfileID;
   UInt32 profileCount;
   UInt32 reserved;
};
typedef struct CMDeviceData CMDeviceData;

CMDeviceDataPtr

typedef CMDeviceData* CMDeviceDataPtr;

CMDeviceID

Defines a data type for a CM device ID.

typedef UInt32 CMDeviceID;

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMDeviceInfo

struct CMDeviceInfo {
   UInt32 dataVersion;
   CMDeviceClass deviceClass;
   CMDeviceID deviceID;
   CMDeviceScope deviceScope;
   CMDeviceState deviceState;
   CMDeviceProfileID defaultProfileID;
   CFDictionaryRef * deviceName;
   UInt32 profileCount;
   UInt32 reserved;
};
typedef struct CMDeviceInfo CMDeviceInfo;
typedef CMDeviceInfo * CMDeviceInfoPtr;

Fields

dataVersion
deviceClass
deviceID
deviceScope
deviceState
defaultProfileID
deviceName: See the CFDictionary documentation for a description of the CFDictionaryRef data type.
profileCount
reserved

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMDeviceName

struct CMDeviceName {
   UniCharCount deviceNameLength;
   UniChar deviceName[256];
};
typedef struct CMDeviceName CMDeviceName;

Fields

CMDeviceNamePtr

typedef CMDeviceName* CMDeviceNamePtr;

CMDeviceProfileArray

struct CMDeviceProfileArray {
   UInt32 profileCount;
   CMDeviceProfileInfo profiles[1];
};
typedef struct CMDeviceProfileArray CMDeviceProfileArray;
typedef CMDeviceProfileArray * CMDeviceProfileArrayPtr;

Fields

profileCount
profiles

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMDeviceProfileID

typedef UInt32 CMDeviceProfileID;

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMDeviceProfileInfo

struct CMDeviceProfileInfo {
   UInt32 dataVersion;
   CMDeviceProfileID profileID;
   CMProfileLocation profileLoc;
   CFDictionaryRef profileName;
   UInt32 reserved;
};
typedef struct CMDeviceProfileInfo CMDeviceProfileInfo;

Fields

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMDeviceProfileScope

typedef CMDeviceScope CMDeviceProfileScope;

Availability

Available in Mac OS X v10.1 and later.

Declared In

ColorSyncDeprecated.h

CMDeviceScope

struct CMDeviceScope {
   CFStringRef deviceUser;
   CFStringRef deviceHost;
};
typedef struct CMDeviceScope CMDeviceScope;
typedef CMDeviceScope CMDeviceProfileScope;

Fields

deviceUser
deviceHost

Availability

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared In

CMDeviceIntegration.h

CMDeviceSpec

struct CMDeviceSpec {
   UInt32 specVersion;
   CMDeviceClass deviceClass;
   CMDeviceID deviceID;
   CMDeviceName deviceName;
   UInt32 reserved;
};
typedef struct CMDeviceSpec CMDeviceSpec;

Fields

CMDeviceSpecPtr

typedef CMDeviceSpec* CMDeviceSpecPtr;

CMDeviceState

typedef UInt32 CMDeviceState;

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMDisplayIDType

Defines a data type for a display ID type.

typedef UInt32 CMDisplayIDType;

Discussion

This data type is passed as a parameter to the functions CMGetProfileByAVID and CMSetProfileByAVID.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMError

Defines a data type for a ColorSync Manager result code.

typedef  CMError;

Discussion

For a list of possible resutlt codes, see “ColorSync Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMFileLocation

Contains a file specification for a profile stored in a disk file.

struct CMFileLocation {
   FSSpec spec;
};
typedef struct CMFileLocation CMFileLocation;

Fields

spec: A file system specification structure giving the location of the profile file. A file specification structure includes the volume reference number, the directory ID of the parent directory, and the filename or directory name. See the File Manager documentation for a description of the FSSpec data type.

Discussion

Your application uses the CMFileLocation structure to provide a file specification for a profile stored in a disk file. You provide a file specification structure in the CMProfileLocation structure’s u field to specify the location of an existing profile or a profile to be created.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ColorSyncDeprecated.h

CMFixedXYColor

struct CMFixedXYColor {
   Fixed x;
   Fixed y;
};
typedef struct CMFixedXYColor CMFixedXYColor;

Fields

x
y

Availability

Available in Mac OS X v10.1 and later.

Declared In

ColorSyncDeprecated.h

CMFixedXYZColor

Contains data that specifies the profile illuminant in the profile header’s white field and other profile element values.

struct CMFixedXYZColor {
   Fixed X;
   Fixed Y;
   Fixed Z;
};
typedef struct CMFixedXYZColor CMFixedXYZColor;

Fields

X
Y
Z

Discussion

ColorSync uses the CMFixedXYZColor data type to specify the profile illuminant in the profile header’s white field and to specify other profile element values. Color component values defined by the Fixed type definition can be used to specify a color value in the XYZ color space with greater precision than a color whose components are expressed as CMXYZComponent data types. The Fixed data type is a signed 32-bit value. A color value expressed in the XYZ color space whose color components are of type Fixed is defined by the CMFixedXYZColor type definition.

Your application can convert colors defined in the XYZ color space between CMXYZColor data types (in which the color components are expressed as 16-bit unsigned values) and CMFixedXYZColor data types (in which the colors are expressed as 32-bit signed values). To convert color values, you use the functions CMConvertFixedXYZToXYZ and CMConvertXYZToFixedXYZ.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMFlattenUPP

Defines a universal procedure pointer to a data-flattening callback.

typedef CMFlattenProcPtr CMFlattenUPP;

Discussion

For more information, see the description of the CMFlattenProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMGrayColor

Contains a color value expressed in the gray color space.

struct CMGrayColor {
   UInt16 gray;
};
typedef struct CMGrayColor CMGrayColor;

Fields

gray

Discussion

A color value expressed in the Gray color space is composed of a single component, gray, represented as a numeric value within the range of 0 to 65535 inclusive.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMHandleLocation

Contains a handle specification for a profile stored in relocatable memory.

struct CMHandleLocation {
   Handle h;
};
typedef struct CMHandleLocation CMHandleLocation;

Fields

h: A data structure of type Handle containing a handle that indicates the location of a profile in memory.

Discussion

Your application uses the CMHandleLocation structure to provide a handle specification for a profile stored in relocatable memory. You provide the handle specification structure in the CMProfileLocation structure’s u field to specify an existing profile or a profile to be created.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMHeader

Contains version 1.0 profile header data.

struct CMHeader {
   UInt32 size;
   OSType CMMType;
   UInt32 applProfileVersion;
   OSType dataType;
   OSType deviceType;
   OSType deviceManufacturer;
   UInt32 deviceModel;
   UInt32 deviceAttributes[2];
   UInt32 profileNameOffset;
   UInt32 customDataOffset;
   CMMatchFlag flags;
   CMMatchOption options;
   CMXYZColor white;
   CMXYZColor black;
};
typedef struct CMHeader CMHeader;

Fields

size

The total size in bytes of the profile, including any custom data.

CMMType

applProfileVersion

The Apple profile version. Set this field to $0100 (defined as the constant kCMApplProfileVersion).

dataType

The kind of color data.

deviceType

The kind of device.

deviceManufacturer

A name supplied by the device manufacturer.

deviceModel

The device model specified by the manufacturer.

deviceAttributes

Private information such as paper surface and ink temperature.

profileNameOffset

The offset to the profile name from the top of data.

customDataOffset

The offset to any custom data from the top of data.

flags

A field used by drivers; it can hold one of the following flags:

CMNativeMatchingPreferredCMTurnOffCache

The CMNativeMatchingPreferred flag is available for developers of intelligent peripherals that can off-load color matching into the peripheral. Most drivers will not use this flag. (Its default setting is 0, meaning that the profile creator does not care whether matching occurs on the host or the device.)

Use the CMTurnOffCache flag for CMMs that will not benefit from a cache, such as those that can look up data from a table with less overhead, or that do not want to take the memory hit a cache entails, or that do their own caching and do not want the CMM to do it. (The default is 0, meaning turn on cache.

options

The options field specifies the preferred matching for this profile; the default is CMPerceptualMatch; other values are CMColorimetricMatch or CMSaturationMatch. The options are set by the image creator.

white

The profile illuminant white reference point, expressed in the XYZ color space.

black

The black reference point for this profile, expressed in the XYZ color space.

Discussion

ColorSync 1.0 defined a version 1.0 profile whose structure and format are different from that of the ICC version 2.x profile. The CMHeader data type represents the version 1.0 profile header. For more information on profile version numbers, see “ColorSync and ICC Profile Format Version Numbers”. To obtain a copy of the International Color Consortium Profile Format Specification, or to get other information about the ICC, visit the ICC Web site at http://www.color.org/

Your application cannot use ColorSync Manager functions to update a version 1.0 profile or to search for version 1.0 profiles. However, your application can use other ColorSync Manager functions that operate on version 1.0 profiles. For example, your application can open a version 1.0 profile using the function CMOpenProfile, obtain the version 1.0 profile header using the function CMGetProfileHeader, and access version 1.0 profile elements using the function CMGetProfileElement.

To make it possible to operate on both version 1.0 profiles and version 2.x profiles, the ColorSync Manager defines the union CMAppleProfileHeader, which supports either profile -*header version. The CMHeader data type defines the version 1.0 profile header, while the CM2Header data type defines the version 2.x profile header.

Version Notes

Use of the CMHeader type is not recommended for ColorSync versions starting with 2.0. Use CM2Header instead.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ColorSyncDeprecated.h

CMHLSColor

Contains a color value expressed in the HLS color space.

struct CMHLSColor {
   UInt16 hue;
   UInt16 lightness;
   UInt16 saturation;
};
typedef struct CMHLSColor CMHLSColor;

Fields

hue: A hue value that represents a fraction of a circle in which red is positioned at 0. .
lightness: A lightness value.
saturation: A saturation value.

Discussion

A color value expressed in the HLS color space is composed of hue, lightness, and saturation component values. Each color component is expressed as a numeric value within the range of 0 to 65535 inclusive.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMHSVColor

Contains a color value expressed in the HSV color space.

struct CMHSVColor {
   UInt16 hue;
   UInt16 saturation;
   UInt16 value;
};
typedef struct CMHSVColor CMHSVColor;

Fields

hue
saturation
value

Discussion

A color value expressed in the HSV color space is composed of hue, saturation, and value component values. Each color component is expressed as a numeric value within the range of 0 to 65535 inclusive. The hue value represents a fraction of a circle in which red is positioned at 0.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMIntentCRDVMSize

Defines the rendering intent and its maximum VM size.

struct CMIntentCRDVMSize {
   long renderingIntent;
   UInt32 VMSize;
};
typedef struct CMIntentCRDVMSize CMIntentCRDVMSize;

Fields

renderingIntent: The rendering intent whose CRD virtual memory size you want to obtain. The rendering intent values are described in “Rendering Intent Values for Version 2.x Profiles.”
VMSize: The virtual memory size of the CRD for the rendering intent specified for the renderingIntent field.

Discussion

To specify the maximum virtual memory (VM) size of the color rendering dictionary (CRD) for a specific rendering intent for a particular PostScript(TM) Level 2 printer type, a printer profile can include the optional Apple-defined 'psvm' tag. The PostScript CRD virtual memory size tag structure’s element data includes an array containing one entry for each rendering intent and its virtual memory size.

If a PostScript printer profile includes this tag, the default CMM uses the tag and returns the values specified by the tag when your application or device driver calls the function CMGetPS2ColorRenderingVMSize.

If a PostScript printer profile does not include this tag, the CMM uses an algorithm to determine the VM size of the CRD. This may result in a size that is greater than the actual VM size.

The CMPS2CRDVMSizeType data type for the tag includes an array containing one or more members of type CMIntentCRDVMSize.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMIString

Defines a profile name.

struct CMIString {
   ScriptCode theScript;
   Str63 theString;
};
typedef struct CMIString CMIString;
typedef CMIString IString;

Fields

theScript: The script code for the theString parameter.
theString: The profile name.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ColorSyncDeprecated.h

CMLabColor

Contains a color value expressed in the L*a*b* color space.

struct CMLabColor {
   UInt16 L;
   UInt16 a;
   UInt16 b;
};
typedef struct CMLabColor CMLabColor;

Fields

L: A numeric value within the range of 0 to 65535, which maps to 0 to 100 inclusive. Note that this encoding is slightly different from the 0 to 65280 encoding of the L channel defined in the ICC specification for PCS L*a*b values.
a: A value that ranges from 0 to 65535, and maps to –128 to 127.996 inclusive.
b: A value that ranges from 0 to 65535, and maps to –128 to 127.996 inclusive.

Discussion

A color expressed in the L*a*b* color space is composed of L, a, and b component values.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMLut16Type

struct CMLut16Type {
   OSType typeDescriptor;
   UInt32 reserved;
   UInt8 inputChannels;
   UInt8 outputChannels;
   UInt8 gridPoints;
   UInt8 reserved2;
   Fixed matrix[3][3];
   UInt16 inputTableEntries;
   UInt16 outputTableEntries;
   UInt16 inputTable[1];
};
typedef struct CMLut16Type CMLut16Type;

Fields

typeDescriptor
reserved
inputChannels
outputChannels
gridPoints
reserved2
matrix
inputTableEntries
outputTableEntries
inputTable
CLUT
outputTable

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMLut8Type

struct CMLut8Type {
   OSType typeDescriptor;
   UInt32 reserved;
   UInt8 inputChannels;
   UInt8 outputChannels;
   UInt8 gridPoints;
   UInt8 reserved2;
   Fixed matrix[3][3];
   UInt8 inputTable[1];
};
typedef struct CMLut8Type CMLut8Type;

Fields

typeDescriptor
reserved
inputChannels
outputChannels
gridPoints
reserved2
matrix
inputTable
CLUT
outputTable
aNet
aNode
aSocket

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMLuvColor

Contains a color value expressed in the L*u*v* color space.

struct CMLuvColor {
   UInt16 L;
   UInt16 u;
   UInt16 v;
};
typedef struct CMLuvColor CMLuvColor;

Fields

L: A numeric value within the range of 0 to 65535 that maps to 0 to 100 inclusive.
u: A numeric value within the range of 0 to 65535 that maps to –128 to 127.996 inclusive.
v: A numeric value within the range of 0 to 65535 that maps to –128 to 127.996 inclusive.

Discussion

A color value expressed in the L*u*v* color space is composed of L, u, and v component values.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMMakeAndModel

Contains make and model information fro a device.

struct CMMakeAndModel {
   OSType manufacturer;
   UInt32 model;
   UInt32 serialNumber;
   UInt32 manufactureDate;
   UInt32 reserved1;
   UInt32 reserved2;
   UInt32 reserved3;
   UInt32 reserved4;
};
typedef struct CMMakeAndModel CMMakeAndModel;

Fields

manufacturer
model
serialNumber
manufactureDate
reserved1
reserved2
reserved3
reserved4

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMMakeAndModelType

Contains make and model information along with a type descriptor.

struct CMMakeAndModelType {
   OSType typeDescriptor;
   UInt32 reserved;
   CMMakeAndModel makeAndModel;
};
typedef struct CMMakeAndModelType CMMakeAndModelType;

Fields

typeDescriptor
reserved
makeAndModel

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMMatchFlag

Defines a data type for match flags.

typedef  long CMMatchFlag;

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ColorSyncDeprecated.h

CMMatchOption

Defines a data type for match options.

typedef long CMMatchOption;

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ColorSyncDeprecated.h

CMMatchRef

Defines an abstract private data structure for the color-matching-session reference.

typedef struct OpaqueCMMatchRef * CMMatchRef;

Discussion

The ColorSync Manager defines an abstract private data structure of type OpaqueCMMatchRef for the color-matching-session reference. When your application calls the function NCMBeginMatching to begin a QuickDraw-specific color-matching session, the ColorSync Manager returns a reference pointer to the color-matching session which you must later pass to the CMEndMatching function to conclude the session.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ColorSyncDeprecated.h

CMMeasurementType

Contains measurement type information.

struct CMMeasurementType {
   OSType typeDescriptor;
   UInt32 reserved;
   UInt32 standardObserver;
   CMFixedXYZColor backingXYZ;
   UInt32 geometry;
   UInt32 flare;
   UInt32 illuminant;
};
typedef struct CMMeasurementType CMMeasurementType;

Fields

typeDescriptor
reserved
standardObserver
backingXYZ
geometry
flare
illuminant

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMMInfo

Contains information pertainting to a color management module.

struct CMMInfo {
   UInt32 dataSize;
   OSType CMMType;
   OSType CMMMfr;
   UInt32 CMMVersion;
   unsigned char ASCIIName[32];
   unsigned char ASCIIDesc[256];
   UniCharCount UniCodeNameCount;
   UniChar UniCodeName[32];
   UniCharCount UniCodeDescCount;
   UniChar UniCodeDesc[256];
};
typedef struct CMMInfo CMMInfo;

Fields

dataSize
CMMType
CMMMfr
CMMVersion
ASCIIName
ASCIIDesc
UniCodeNameCount
UniCodeName
UniCodeDescCount
UniCodeDesc
TPLFMT_BKSZ
TPLFMT_NBLOCKS
TPLFMT_EDCLOC

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMMInfoRecord

Contains CMM type and version information.

struct CMMInfoRecord {
   OSType CMMType;
   long CMMVersion;
};
typedef struct CMMInfoRecord CMMInfoRecord;

Fields

CMMType: The signature of the CMM as specified in the profile header’s CMMType field. The CMGetCWInfo function returns this value.
CMMVersion: The version of the CMM. The CMGetCWInfo function returns this value.

Discussion

Your application supplies an array containing two CMM information record structures of type CMMInfoRecord as a field of the CMCWInfoRecord structure. These structures allow the CMGetCWInfo function to return information about the one or two CMMs used in a given color world. Your application must allocate memory for the array. When your application calls the CMGetCWInfo function, it passes a pointer to the CMCWInfoRecord structure containing the array.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

ColorSyncDeprecated.h

CMMIterateUPP

Defines a universal procedure pointer to a CMM interation callback.

typedef CMMIterateProcPtr CMMIterateUPP;

Discussion

For more information, see the description of the CMMIterateProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMMultichannel5Color

Contains a color value expressed in the multichannel color space with 5 channels.

struct CMMultichannel5Color {
   UInt8 components[5];
};
typedef struct CMMultichannel5Color CMMultichannel5Color;

Fields

components

Discussion

A color expressed in the multichannel color space with 5 channels. The color value for each channel component is expressed as an unsigned byte of type char.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMMultichannel6Color

Contains a color expressed in the multichannel color space with 6 channels.

struct CMMultichannel6Color {
   UInt8 components[6];
};
typedef struct CMMultichannel6Color CMMultichannel6Color;

Fields

components

Discussion

A color expressed in the multichannel color space with 6 channels. The color value for each channel component is expressed as an unsigned byte of type char.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMMultichannel7Color

Contains a color value expressed in the multichannel color space with 7 channels.

struct CMMultichannel7Color {
   UInt8 components[7];
};
typedef struct CMMultichannel7Color CMMultichannel7Color;

Fields

components

Discussion

A color expressed in the multichannel color space with 7 channels. The color value for each channel component is expressed as an unsigned byte of type char.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMMultichannel8Color

Contains a color value expressed in the multichannel color space with 8 channels

struct CMMultichannel8Color {
   UInt8 components[8];
};
typedef struct CMMultichannel8Color CMMultichannel8Color;

Fields

components

Discussion

A color expressed in the multichannel color space with 8 channels. The color value for each channel component is expressed as an unsigned byte of type char.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ColorSyncDeprecated.h

CMMultiFunctCLUTType

struct CMMultiFunctCLUTType {
   UInt8 gridPoints[16];
   UInt8 entrySize;
   UInt8 reserved[3];
   UInt8 data[1];
};
typedef struct CMMultiFunctCLUTType CMMultiFunctCLUTType;

Fields

gridPoints
entrySize
reserved
data

Availability

Available in Mac OS X v10.1 and later.

Declared In

ColorSyncDeprecated.h

CMMultiFunctLutA2BType

typedef CMMultiFunctLutType CMMultiFunctLutA2BType;

Availability

Available in Mac OS X v10.1 through Mac OS X v10.4.

Declared In

C