Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

Chapter 3 - ColorSync Manager Reference for Applications and Device Drivers / ColorSync Manager Functions

Accessing Profile Elements /

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 (page 3-63) to the profile containing the target element.

tag

The tag signature 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 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. See "Result Codes" (page 3-174) for a list of ColorSync-specific 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 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 CMGetPartialProfileElement function (page 3-90).

You cannot use this function to obtain a portion of a profile element in the CM2Header profile header. Instead, you must call the CMGetProfileHeader function (page 3-88) to copy the profile header and read its contents.