PATHMac OS 8 and 9 Developer Documentation > Mutlimedia and Graphics > ColorSync Manager >

Managing Color With ColorSync


Embedding Profile Information in Pictures

Applications use the QuickDraw PicComment function, described in Inside Macintosh: Imaging With QuickDraw , to add picture comments to a picture. The ColorSync Manager provides the NCMUseProfileComment function for automatically embedding profile information with the PicComment function.


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 of type CMProfileRef to the profile to embed.
flags
A flag value in which individual bits determine settings. Constants for Embedding Profiles and Profile Identifiers describes constants for use with this parameter. For example, you pass cmEmbedWholeProfile to embed a whole profile or cmEmbedProfileIdentifier to embed a profile identifier. No other values are currently defined; all other bits are reserved for future use.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

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 use the constant cmEmbedWholeProfile to set the flags parameter before calling NCMUseProfileComment . 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: cmBeginProfileSel to begin the profile, cmContinueProfileSel to continue, and cmEndProfileSel to end the profile. These constants are described in Picture Comment Selectors for Embedding Profile Information .

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 cmContinueProfileSel to embed each segment.

To embed a profile identifier of type CMProfileIdentifier , you use the constant cmEmbedProfileIdentifier to set the flags parameter before calling NCMUseProfileComment . 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 ColorSync Profiles folder.

IMPORTANT

You can use this function to embed most types of profiles in an image, including device link 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 .

VERSION NOTES

In ColorSync 2.0, the flags parameter was ignored and the routine always embedded the entire profile.

In ColorSync 2.0, if the prof parameter refers to a version 1.0 profile, the profile is not embedded into the picture correctly. In ColorSync versions starting with 2.1, this bug has been fixed. One possible workaround for this problem in ColorSync 2.0 is to call CMCopyProfile to copy the 1.0 profile reference into a handle. The handle can then be embedded into the picture using CMUseProfileComment .


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