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

Managing Color With ColorSync


Accessing Profile Elements

This section describes the functions you use to examine, set, and change individual elements of a profile.


CMProfileElementExists

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

pascal CMError CMProfileElementExists (
                     CMProfileRef prof,
                     OSType tag,
                     Boolean *found);
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 . For information on how to obtain the ICC format specification, see the section The International Color Consortium Profile Format in this document. 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 output, the flag has the value true if the profile contains the element or false if it doesn't.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.


CMCountProfileElements

Counts the number of elements in the specified profile.

pascal CMError CMCountProfileElements (
                      CMProfileRef prof,
                      unsigned long *elementCount);
prof
A profile reference of type CMProfileRef to the profile to examine.
elementCount
A pointer to an element count. On output, a one-based count of the number of elements.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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. For information about profiles and their tags, see Profile Properties .


CMGetProfileElement

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

pascal CMError CMGetProfileElement (
                     CMProfileRef prof,
                     OSType tag,
                     unsigned long *elementSize,
                     void *elementData);
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 . For information on how to obtain the ICC format specification, see the section The International Color Consortium Profile Format in this document. 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 output, the size of the data returned.
elementData
A pointer to memory for element data. On input, you allocate memory. On output, 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.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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 output the elementSize parameter contains the size in bytes of the element data actually returned.

SEE ALSO

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.


CMGetProfileHeader

Obtains the profile header for the specified profile.

pascal CMError CMGetProfileHeader (
                     CMProfileRef prof,
                     CMAppleProfileHeader *header);
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 output, 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 and How ColorSync 1.0 Profiles and Version 2.x Profiles Differ .
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.

SEE ALSO

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


CMGetPartialProfileElement

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

pascal CMError CMGetPartialProfileElement (
                     CMProfileRef prof,
                     OSType tag,
                     unsigned long offset,
                     unsigned long *byteCount,
                     void *elementData);
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 . For information on how to obtain the ICC format specification, see the section The International Color Consortium Profile Format in this document. 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 output, the number of bytes actually copied.
elementData
A pointer to memory for element data. On input, you pass a pointer to allocated memory. On output, this buffer holds the element data.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.


CMGetIndProfileElementInfo

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

pascal CMError CMGetIndProfileElementInfo (
                     CMProfileRef prof,
                     unsigned long index,
                     OSType *tag,
                     unsigned long *elementSize,
                     Boolean *refs);
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 output, the tag signature of the element corresponding to the index.
elementSize
A pointer to an element size. On output, the size in bytes of the element data corresponding to the tag.
refs
A pointer to a reference count flag. On output, set to true if more than one tag in the profile refers to element data associated with the tag corresponding to the index.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager . See the discussion for this function for one possible error return value.

DISCUSSION

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 . The index order of elements is determined internally by the ColorSync Manager and is not publicly defined.

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


CMGetIndProfileElement

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

pascal CMError CMGetIndProfileElement (
                     CMProfileRef prof,
                     unsigned long index,
                     unsigned long *elementSize,
                     void *elementData);
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 output, the size of the element data actually copied.
elementData
A pointer to memory for element data. On input, you allocate memory. On output, 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.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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

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.

SEE ALSO

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


CMSetProfileElementSize

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

pascal CMError CMSetProfileElementSize (
                     CMProfileRef prof,
                     OSType tag,
                     unsigned long elementSize);
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 . For information on how to obtain the ICC format specification, see the section The International Color Consortium Profile Format in this document. 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.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

Your application can use the CMSetProfileElementSize function to reserve the size of element data for a specific tag before you call the function CMSetPartialProfileElement 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.


CMSetPartialProfileElement

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

pascal CMError CMSetPartialProfileElement (
                     CMProfileRef prof,
                     OSType tag,
                     unsigned long offset,
                     unsigned long byteCount,
                     void *elementData);
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 . For information on how to obtain the ICC format specification, see the section The International Color Consortium Profile Format in this document. 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.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.

SEE ALSO

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 .


CMSetProfileElement

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

pascal CMError CMSetProfileElement (
                     CMProfileRef prof, OSType tag,
                     unsigned long elementSize,
                     void *elementData);
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 . For information on how to obtain the ICC format specification, see the section The International Color Consortium Profile Format in this document. 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.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.


CMSetProfileHeader

Sets the header for the specified profile.

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

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 .


CMSetProfileElementReference

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

pascal CMError CMSetProfileElementReference (
                     CMProfileRef prof,
                     OSType elementTag,
                     OSType referenceTag);
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 .
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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.


CMRemoveProfileElement

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

pascal CMError CMRemoveProfileElement (
                     CMProfileRef prof,
                     OSType tag);
prof
A profile reference of type CMProfileRef to the profile containing the tag remove.
tag
The tag signature for the element to remove.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

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


CMGetScriptProfileDescription

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

pascal CMError CMGetScriptProfileDescription (
                     CMProfileRef prof,
                     Str255 name,
                     ScriptCode *code);
prof
A profile reference of type CMProfileRef to the profile whose profile name and script code are obtained.
name
A pointer to a name string. On output, the profile name.
code
A pointer to a script code. On output, the script code.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

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


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