PATHDocumentation > Mac OS 8 and 9 > Mutlimedia and Graphics > ColorSync Manager >

Managing Color With ColorSync


Accessing Profiles

This section describes the functions you use to perform operations on profiles:


CMOpenProfile

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

pascal CMError CMOpenProfile (
                        CMProfileRef *prof                  
                        const CMProfileLocation *theProfile);
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.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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:


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.

pascal CMError CMCloseProfile (CMProfileRef prof);
prof
A profile reference of type CMProfileRef that identifies the profile that may need to be closed.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.

Note

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.

IMPORTANT

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.

SEE ALSO

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


CMProfileModified

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

pascal CMError CMProfileModified (
                     CMProfileRef prof,
                     Boolean *modified);
prof
A profile reference of type CMProfileRef to the profile to examine.
modified
A pointer to a Boolean variable. On output, the value of modified is set to true if the profile has been modified, false if it has not.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

The CMProfileModified function returns, through the modified parameter, the current state of the modified flag for the specified profile.

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 .


CMUpdateProfile

Saves modifications to the specified profile.

pascal CMError CMUpdateProfile (CMProfileRef prof);
prof
A profile reference of type CMProfileRef to the profile to update.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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. For information on updating a ColorSync 1.0 profile, see Using ColorSync 1.0 Profiles With Newer Versions of the ColorSync Manager .

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 .


CMNewProfile

Creates a new profile and associated backing copy.

pascal CMError CMNewProfile (
                      CMProfileRef *prof,
                      CMProfileLocation *theProfile);
prof
A pointer to a profile reference of type CMProfileRef . On output, 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 isn't 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.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.

Note

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.

SEE ALSO

For information on how to fill in a profile with tags and element data including a description of the profile tags, refer to the International Color Consortium Profile Format Specification . For information on how to obtain the ICC format specification, see the section The International Color Consortium Profile Format in this document.


CMCopyProfile

Duplicates the specified existing profile.

pascal CMError CMCopyProfile (
                     CMProfileRef *targetProf,
                     const CMProfileLocation *targetLocation,
                     CMProfileRef srcProf);
targetProf
A pointer to a profile reference of type CMProfileRef . On output, 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 isn't 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.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.

SEE ALSO

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.


CMCloneProfileRef

Increments the reference count for the specified profile reference.

pascal CMError CMCloneProfileRef (CMProfileRef prof);
prof
A profile reference of type CMProfileRef to the profile whose reference count is incremented.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.

IMPORTANT

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.


CMGetProfileRefCount

Obtains the current reference count for the specified profile.

pascal CMError CMGetProfileRefCount (
                     CMProfileRef prof,
                     long *count);
prof
A profile reference of type CMProfileRef to the profile whose reference count is obtained.
count
A pointer to a reference count. On output, the reference count for the specified profile reference.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.

SEE ALSO

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.


NCMGetProfileLocation

New in ColorSync 2.5

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

pascal CMError NCMGetProfileLocation (
                     CMProfileRef prof,
                     CMProfileLocation * profLoc,
                     unsigned long * locationSize);
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.
profLoc
A pointer to a profile location structure, as described in Profile Location . 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 .
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

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

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

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

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

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

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


CMGetProfileLocation

Not Recommended in ColorSync 2.5

Obtains the location of a profile based on the specified profile reference.

pascal CMError CMGetProfileLocation (
                     CMProfileRef prof,
                     CMProfileLocation *theProfile);
prof
A profile reference of type CMProfileRef . Before calling CMGetProfileLocation , you set the reference to specify the profile you wish to obtain the location for.
theProfile
A pointer to a profile location structure of type CMProfileLocation . On output, specifies the location of the profile. Commonly, a profile is disk-file based, but it may instead be temporary, handle-based, pointer-based, or accessed through a procedure supplied by your application.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.

VERSION NOTES

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

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

SEE ALSO

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


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.

pascal CMError CMValidateProfile (
                     CMProfileRef prof,
                     Boolean *valid,
                     Boolean *preferredCMMnotfound);
prof
A profile reference of type CMProfileRef to the profile to validate.
valid
A pointer to a valid profile flag. On output, has the value true if the profile contains the minimum set of elements to be valid and false if it doesn't.
preferredCMMnotfound
A pointer to a flag for whether the preferred CMM was found. On output, 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.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.


CMFlattenProfile

Changed in ColorSync 2.5

Transfers a profile stored in an independent disk file to an external profile format that can be embedded in a graphics document.

pascal CMError CMFlattenProfile (
                     CMProfileRef prof,
                     unsigned long flags,
                 &nbsbsp;p;CMFlattenUPP proc,
                     void *refCon,
                     Boolean *preferredCMMnotfound);
prof
A profile reference of type CMProfileRef to the profile to flatten.
flags
Reserved for future use.
proc
A pointer to a function that you provide to perform the low-level data transfer. For more information, see the function MyColorSyncDataTransfer .
refCon
A reference constant for application data which the color management module (CMM) passes to the MyColorSyncDataTransfer function each time it calls the function. For example, the refce constant may point to a data structure that holds information required by the MyColorSyncDataTransfer function to perform the data transfer, such as the reference number to a disk file in which the flattened profile is to be stored. Starting with ColorSync version 2.5, the ColorSync Manager calls your transfer function directly, without going through the preferred, or any, CMM.
preferredCMMnotfound
A pointer to a flag for whether the preferred CMM was found. On output, has the value true if the CMM specified by the profile was not available to perform flattening or does not support this function and the default CMM was used. Has the value false if the profile's preferred CMM is able to perform flattening. Starting with ColorSync 2.5, the ColorSync Manager calls your transfer function directly, without going through the preferred, or any, CMM. On return, the value of preferredCMMnotfound is guaranteed to be false .
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

The version notes that follow this section describe changes to how the CMFlattenProfile function works starting in ColorSync version 2.5.

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

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

VERSION NOTES

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

SEE ALSO

To unflatten a profile embedded in a graphics document to an independent disk file, use the function CMUnflattenProfile .


CMUnflattenProfile

Changed in ColorSync 2.5

Transfers a profile embedded in a graphics document to an independent disk file.

pascal CMError CMUnflattenProfile (
                     FSSpec *resultFileSpec,
                     CMFlattenUPP proc,
                     void *refCon,
                     Boolean *preferredCMMnotfound);
resultFileSpec
A pointer to a file specification. On return, the file specification identifies an independent disk file containing the extracted profile.
proc
A pointer to a function provided by your application to receive the profile data from the CMM and store it in a file.
refCon
A reference constant for application data which the CMM passes to the MyColorSyncDataTransfer function each time it calls the function. Starting with ColorSync 2.5, the ColorSync Manager calls your transfer function directly, without going through the preferred, or any, CMM.
preferredCMMnotfound
A pointer to a flag for whether the preferred CMM was found. On output, has the value true if the CMM specified by the profile was not available to perform unflattening 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 unflattening. Starting with ColorSync 2.5, the ColorSync Manager calls your transfer function directly, without going through the preferred, or any, CMM. On return, the value of preferredCMMnotfound is guaranteed to be false .
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

The version notes that follow this section describe changes to how the CMUnflattenProfile function works starting in ColorSync version 2.5.

Prior to version 2.5, the ColorSync Manager dispatches the CMUnflattenProfile function (passed by your application in the proc parameter) to the CMM specified by the profile that is to be transferred to a disk file. If the preferred CMM is unavailable or it doesn't support this function, then the default CMM is used.

The ColorSync Manager calls your unflattening function to identify the CMM to which it dispatches the CMUnflattenProfile function. For this reason, your function must be able to buffer at least 8 bytes of data. For a description of an unflattening function prototype, see MyColorSyncDataTransfer . For a sample of an actual unflattening function, see Part B: Unflattening the Profile .

The CMM calls your version of the MyColorSyncDataTransfer function to transfer the profile data from the graphics document to an independent disk file.

Before you can obtain a profile reference to a profile that was embedded in a graphics document, you must use this function to unflatten the profile. Then you can call CMOpenProfile to open the profile and obtain a reference to it.

When you have finished using the profile, you must call the CMCloseProfile function to close the profile and call the File Manager's FSpDelete function to delete the file.

VERSION NOTES

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


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

Previous | Back Up One Level | Next