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

Managing Color With ColorSync


Embedding Profiles and Profile Identifiers

When the user creates and saves a document or picture containing a color image created or modified with your application, your application can provide for future color matching by saving--along with that document or picture--the profile for the device on which the image was created or modified. In addition to a profile--or instead of a profile--your application can save a profile identifier. A profile identifier is an abbreviated data structure that identifies, and possibly modifies, a profile in memory or on disk.

When embedding source profiles or profile identifiers in the documents created by your application, you can store them in any manner that you choose. For example, you may choose to have your application store, in the resource fork of the document file, one profile for an entire image, or a separate profile for every object in an image, or a separate profile identifier that points to a profile on disk for every device on which the user modified the image.

When embedding source profiles or profile identifiers in PICT file pictures, your application should use the cmComment picture comment, which has a kind value of 224 and is defined for embedded version 2.x profiles. This comment is followed by a 4-byte selector that describes the type of data in the comment. The following selectors are currently defined:

Selector

Value

Description

cmBeginProfileSel 0 Beginning of a version 2.x profile. Profile data to follow.
cmContinueProfileSel 1 Continuation of version 2.x profile data. Profile data to follow.
cmEndProfileSel 2 End of version 2.x profile data. No profile data follows.
cmProfileIdentifierSel 3 Profile identifier follows. A profile identifier identifies a profile that may reside in memory or on disk.

Because the dataSize parameter of the PicComment procedure is a signed 16-bit value, the maximum amount of profile data that can be embedded in a single picture comment is 32,763 bytes (32,767 - 4 bytes for the selector).

You can embed a larger profile by using multiple picture comments of selector type cmContinueProfileSel , as shown in Figure 3-7 . You must embed the profile data in consecutive order, and you must conclude the profile data by embedding a picture comment of selector type cmEndProfileSel . The ColorSync Manager provides the NCMUseProfileComment function to automate the process of embedding profile information.

Embedded Profile Format

Figure 3-7 shows how profile data is embedded in a PICT file picture as a series of picture comments. The illustration shows two embedded profiles. The first profile contains less than 20K of data, so its data can be stored in one picture comment with selector type cmBeginProfileSel . Note, however, that a second comment of selector type cmEndProfileSel , containing no data, concludes the embedded profile.

The second embedded profile shown in Figure 3-7 has more than 32K of data, so its data must be stored in two consecutive picture comments. The first comment has selector type cmBeginProfileSel , while the second has type cmContinueProfileSel . If the profile were larger and required additional picture comments, each additional comment would have selector type cmContinueProfileSel . As with all embedded profiles, the final picture comment has selector type cmEndProfileSel .

Embedding Different Profile Versions

For version 1.0 of the ColorSync Manager, you use picture comment types cmBeginProfile and cmEndProfile to begin and end a picture comment. The cmBeginProfile comment is not supported for ColorSync version 2.x profiles; however, the you can use the cmEndProfile comment to end the current profile for both ColorSync 1.0 and 2.x. Following a cmEndProfile comment, the ColorSync Manager reverts to the system profile. You use the cmEnableMatching and cmDisableMatching picture comments to begin and end color matching in both ColorSync 1.0 and 2.x. See Inside Macintosh: Imaging With QuickDraw for more information about picture comments.

Figure 3-7 Embedding profile data in a PICT file picture

The NCMUseProfileComment Function

The ColorSync Manager provides the function NCMUseProfileComment to automate the process of embedding a profile or profile identifier. This function generates the picture comments required to embed the specified profile or identifier into the open picture. It 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; or 3 for a profile identifier. For a 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.

For embedded profiles or profile identifiers 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. If you do not specify a picture comment to end the profile, the profile will remain in effect until the next embedded profile is introduced with a picture comment of kind cmBeginProfile . It is good practice to 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.

IMPORTANT

The NCMUseProfileComment function does not automatically terminate the embedded profile or profile identifier with a cmEndProfile picture comment. You must add a picture comment of kind cmEndProfile when the drawing operations to which the profile applies are complete. Otherwise, the profile remains in effect until the next embedded profile with a picture comment of kind cmBeginProfile is encountered.

In addition to embedded profiles, an image may contain embedded profile identifiers, which are stored with the selector cmProfileIdentifierSel. For more information on profile identifiers, see Searching for a Profile That Matches a Profile Identifier , and CMProfileIdentifier .

Listing 3-8 shows how to embed a profile in a picture file. The MyPreprendProfileToPicHandle function creates a new picture, embeds the profile for the device used to create the picture, then draws the picture. The caller passes a reference for the profile as the prof parameter. Note that after MyPreprendProfileToPicHandle calls the NCMUseProfileComment function to embed the profile, it calls its own MyEndProfileComment function to embed a comment of kind cmEndProfile , ensuring that the profile is properly terminated.

Listing 3-8 Embedding a profile by prepending it before its associated picture

CMError MyPrependProfileToPicHandle (
                PicHandle pict,
                PicHandle *pictNew,
                CMProfileRef prof,
                Boolean embedAsIdentifier)
{
    OSErr           theErr;
    CGrafPtr        savePort;
    GDHandle        saveGDev;
    GWorldPtr       tempWorld;
    Rect            pictRect;
    unsigned long   flags;
    
    // Init for error handling.
    theErr = noErr;
    tempWorld = nil;
    
    // Check parameters
    if (prof == nil) theErr = paramErr;
    require(theErr == noErr, cleanup);
    
    // Determine whether to embed as identifier or whole profile.
    if (embedAsIdentifier)
        flags = cmEmbedProfileIdentifier;
    else
        flags = cmEmbedWholeProfile;
    
    // Create a temporary graphics world.
    theErr = NewSmallGWorld(&tempWorld);
    require(theErr == noErr, cleanup);
    
    // Save current world and switch to temporary.
    GetGWorld(&savePort, &saveGDev);
    SetGWorld(tempWorld, nil);
    pictRect = (**pict).picFrame;
    ClipRect(&pictRect);                // Important: set clipRgn.
    
    // Create a new picture.
    *pictNew = OpenPicture(&pictRect);  // Start recording.
    theErr = NCMUseProfileComment(prof,flags);
    DrawPicture(pict, &pictRect);
    MyEndProfileComment();              // Routine shown below.
    ClosePicture();
    
    if (theErr)
        KillPicture(*pictNew);
    
    SetGWorld(savePort, saveGDev);
    
// Do any necessary cleanup:dispose of graphics world.
cleanup:
    
    if (tempWorld)
        DisposeGWorld(tempWorld);
    
    return theErr;
}

Here is the application-defined MyEndProfileComment function called by MyPrependProfileToPicHandle to add the cmEndProfile picture comment to terminate the profile:

void MyEndProfileComment (void)
{
    PicComment(cmEndProfile, 0, 0);
}

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