NCMDrawMatchedPicture

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

Declaration

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

Parameters

myPicture:
The QuickDraw picture whose colors are to be matched. See the QuickDraw Reference for a description of the PixMap data type.
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 1804955 Cmgetprofilebyavid to get the specific profile for the display, or you can call 1804940 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.
See the QuickDraw Reference for a description of the PixMap data type.
myRect:
A pointer to a destination rectangle for rendering the picture specified by myPicture.

Return Value

This function does not return an error value. Instead, after calling NCMDrawMatchedPicture you call the QDError routine to determine if an error has occurred.

Overview

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 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.