Carbon


NCMDrawMatchedPicture

Header: CMApplication.h Carbon status: Supported

Matches a picture’s colors to a destination device’s color gamut, as the picture is drawn, using the specified destination profile.

void NCMDrawMatchedPicture (
    PicHandle myPicture, 
    CMProfileRef dst, 
    Rect *myRect
);
Parameter descriptions
myPicture

The QuickDraw picture whose colors are to be matched.

dst

A profile reference of type CMProfileRef to the profile of the destination device. Starting with ColorSync version 2.5, if you know the destination display device, you can call CMGetProfileByAVID to get the specific profile for the display, or you can call CMGetDefaultProfileBySpace to get the default profile for the RGB color space,.

With any version of ColorSync, you can specify a NULL value to indicate the ColorSync system profile. Note, however, that starting with version 2.5, use of the system profile has changed.

myRect

A pointer to a destination rectangle for rendering the picture specified by myPicture.

DISCUSSION

The NCMDrawMatchedPicture function operates in the context of the current color graphics port. This function sets up and takes down a color-matching session. It automatically matches all colors in a picture to the destination profile for a destination device as the picture is drawn. It uses the ColorSync system profile as the initial source profile and any embedded profiles as they are encountered thereafter. (Because color-matching picture comments embedded in the picture to be matched are recognized, embedded profiles are used.)

The ColorSync Manager defines five picture comment kinds, as described in “Picture Comment Kinds for Profiles and Color Matching”. For embedding to work correctly, each embedded profile that is used for matching must be terminated by a picture comment of kind cmEndProfile. If a picture comment is not specified to end the profile after drawing operations using that profile are performed, the profile will remain in effect until another embedded profile is introduced that has a picture comment kind of cmBeginProfile. To avoid unexpected matching effects, 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.

The picture is drawn with matched colors to all screen graphics devices. If the current graphics device is not a screen device, matching occurs for that graphics device only.

If the current port is not a color graphics port, then calling this function is equivalent to calling DrawPicture, in which case no color matching occurs.

VERSION NOTES

The parameter description for dst describes changes in how this function is used starting with ColorSync version 2.5.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when ColorSync 2.0 or later is present.


© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)