![]() |
PATH![]() |
![]() ![]() |
This section describes the functions you use to perform operations on profiles:
CMOpenProfile
opens the specified profile and returns a reference to the profile.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.CMProfileModified
indicates whether the specified profile has been modified since it was created or last updated.CMUpdateProfile
saves modifications to the specified profile.CMNewProfile
creates a new profile and associated backing copy.CMCopyProfile
duplicates the specified existing profile.CMCloneProfileRef
increments the reference count for the specified profile reference.CMGetProfileRefCount
obtains the current reference count for the specified profile.NCMGetProfileLocation
obtains the location of a profile based on the specified profile reference;
new in ColorSync 2.5
.CMGetProfileLocation
obtains the location of a profile based on the specified profile reference (not recommended in ColorSync version 2.5).CMValidateProfile
indicates whether the specified profile contains the minimum set of elements required by the current color management module for color matching or color checking.CMFlattenProfile
transfers a profile stored in an independent disk file to an external profile format that can be embedded in a graphics document;
changed in ColorSync 2.5
.CMUnflattenProfile
transfers a profile embedded in a graphics document to an independent disk file;
changed in ColorSync 2.5
.Opens the specified profile and returns a reference to the profile.
pascal CMError CMOpenProfile (
CMProfileRef *prof
const CMProfileLocation *theProfile);
CMProfileRef
. On return, the reference refers to the opened profile.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.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:
NCWNewColorWorld
as the source or destination profile in a color world for a color-matching sessionCMCloseProfile
, your changes are discarded (unless you called the
CMUpdateProfile
function).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);
CMProfileRef
that identifies the profile that may need to be closed.
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.
To save changes to a profile before closing it, use the function
CMUpdateProfile
.
Indicates whether the specified profile has been modified since it was created or last updated.
pascal CMError CMProfileModified (
CMProfileRef prof,
Boolean *modified);
CMProfileRef
to the profile to examine.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
.
Saves modifications to the specified profile.
pascal CMError CMUpdateProfile (CMProfileRef prof);
CMProfileRef
to the profile to update.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
.
Creates a new profile and associated backing copy.
pascal CMError CMNewProfile (
CMProfileRef *prof,
CMProfileLocation *theProfile);
CMProfileRef
. On output, a reference to the new profile.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.
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.
NoteThis 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.
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.
Duplicates the specified existing profile.
pascal CMError CMCopyProfile (
CMProfileRef *targetProf,
const CMProfileLocation *targetLocation,
CMProfileRef srcProf);
CMProfileRef
. On output, points to the profile copy that was created.CMProfileLocation
.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.
Increments the reference count for the specified profile reference.
pascal CMError CMCloneProfileRef (CMProfileRef prof);
CMProfileRef
to the profile whose reference count is incremented.
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.
Obtains the current reference count for the specified profile.
pascal CMError CMGetProfileRefCount (
CMProfileRef prof,
long *count);
CMProfileRef
to the profile whose reference count is obtained.
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.
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);
CMProfileRef
. Before calling
NCMGetProfileLocation
, you set the reference to specify the profile for which you wish to obtain the location or location structure size.
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:
The best way to use NCMGetProfileLocation is to call it twice:
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.
Obtains the location of a profile based on the specified profile reference.
pascal CMError CMGetProfileLocation (
CMProfileRef prof,
CMProfileLocation *theProfile);
CMProfileRef
. Before calling
CMGetProfileLocation
, you set the reference to specify the profile you wish to obtain the location for.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.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.
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 .
To open a profile and obtain a reference to it, use the function
CMOpenProfile
.
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);
CMProfileRef
to the profile to validate.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.