Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

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

Working With Profiles and Profile Identifiers in Pictures /

NCMUseProfileComment

Automatically embeds a profile or a profile identifier into an open picture.

pascal CMError NCMUseProfileComment (
CMProfileRef prof, 
unsigned long flags);

prof

A profile reference (page 3-63) to the profile to embed.

flags

A flag value in which individual bits determine settings. You set the low bit to 0 to embed a profile or to 1 to embed a profile identifier. Other bits are reserved for future use. ColorSync provides constant values for setting and testing the flags parameter, described in "Constants for Embedding Profiles and Profile Identifiers" (page 3-19).

function result

A result code of type CMError. See "Result Codes" (page 3-174) for a list of ColorSync-specific result codes.

DISCUSSION

The NCMUseProfileComment function automatically generates the picture comments required to embed the specified profile or profile identifier into the open picture.

To embed a profile, you call NCMUseProfileComment with the low bit of the flags parameter set to 0. The NCMUseProfileComment function calls the QuickDraw PicComment function with a picture comment kind value of cmComment and a 4-byte selector that describes the type of data in the picture comment: 0 to begin the profile, 1 to continue, and 2 to end the profile. If the size in bytes of the profile and the 4-byte selector together exceed 32 KB, this function segments the profile data and embeds the multiple segments in consecutive order using selector 1 to embed each segment. Figure 4-7 (page 4-33) in Advanced Color Imaging on the Mac OS shows how profile data is embedded in a PICT file picture.

To embed a profile identifier (page 3-64), you call NCMUseProfileComment with the low bit of the flags parameter set to 1. The function extracts the necessary information from the profile reference (prof) to embed a profile identifier for the profile. The profile reference can refer to a previously embedded profile or to a profile on disk in the ColorSyncTM Profiles folder.

IMPORTANT

You can use this function to embed all types of ColorSync 2.x profiles in an image, including device-linked profiles, but not abstract profiles. You cannot use this function to embed ColorSync 1.0 profiles in an image.

The NCMUseProfileComment function precedes the profile it embeds with a picture comment of kind cmBeginProfile. For embedding to work correctly, the currently effective profile must be terminated by a picture comment of kind cmEndProfile after drawing operations using that profile are performed. You are responsible for adding the picture comment of kind cmEndProfile. If a picture comment was not specified to end the profile following the drawing operations to which the profile applies, the profile will remain in effect until the next embedded profile is introduced with a picture comment of kind cmBeginProfile. However, use of the next profile might not be the intended action. Always pair use of the cmBeginProfile and cmEndProfile picture comments. When the ColorSync Manager encounters a cmEndProfile picture comment, it restores use of the system profile for matching until it encounters another cmBeginProfile picture comment.

For more information on the PicComment selector values used by NCMUseProfileComment, see "Picture Comment Selectors for Embedding Profile Information" (page 3-18).