PATHDocumentation > Mac OS 8 and 9 > Mutlimedia and Graphics > ColorSync Manager >

Managing Color With ColorSync


Matching Colors Using QuickDraw-Specific Functions

This section describes the functions you use to perform color-matching when working with QuickDraw. QuickDraw-Specific Color-Matching Functions provides an overview of these functions, while Matching to Displays Using QuickDraw-Specific Operations provides a code sample for working with them. Matching Colors Using General Purpose Functions describes color-matching functions that don't rely on QuickDraw.


NCMBeginMatching

Changed in ColorSync 2.5

Sets up a QuickDraw-specific ColorSync matching session, using the specified source and destination profiles.

pascal CMError NCMBeginMatching (
                     CMProfileRef src,
                     CMProfileRef dst,
                     CMMatchRef *myRef);
src
A profile reference of type CMProfileRef that specifies the source profile for the matching session. Starting with ColorSync version 2.5, you can call CMGetDefaultProfileBySpace to get the default profile for a specific color space or CMGetProfileByAVID to get a profile for a specific display. 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, as described in Setting Default Profiles .
dst
A profile reference of type CMProfileRef that specifies the destination profile for the matching session. Starting with ColorSync version 2.5, you can call CMGetDefaultProfileBySpace to get the default profile for a specific color space or CMGetProfileByAVID to get a profile for a specific display. 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, as described in Setting Default Profiles .
myRef
A pointer to a matching session. On output, it specifies the QuickDraw-specific matching session that was set up.
function result
A result code of type CMError . For possible values, see Result Codes for the ColorSync Manager .

DISCUSSION

The NCMBeginMatching function sets up a QuickDraw-specific matching session, telling the ColorSync Manager to match all colors drawn to the current graphics device using the specified source and destination profiles.

The NCMBeginMatching function returns a reference to the color-matching session. You must later pass this reference to the function CMEndMatching to conclude the session.

The source and destination profiles define how the match is to occur. Passing NULL for either the source or destination profile is equivalent to passing the system profile. If the current device is a screen device, matching to all screen devices occurs.

The NCMBeginMatching and CMEndMatching functions can be nested. In such cases, the ColorSync Manager matches to the most recently added profiles first. Therefore, if you want to use the NCMBeginMatching - CMEndMatching pair to perform a page preview--which typically entails color matching from a source device (scanner) to a destination device (printer) to a preview device (display)-- you first call NCMBeginMatching with the printer-to-display profiles, and then call NCMBeginMatching with the scanner-to-printer profiles. The ColorSync Manager then matches all drawing from the scanner to the printer and then back to the display. The print preview process entails multiprofile transformations. The ColorSync Manager general purpose functions (which include the use of concatenated profiles well suited to print-preview processing) offer an easier and faster way to do this. These functions are described in Matching Colors Using General Purpose Functions .

Note

If you call NCMBeginMatching before drawing to the screen's graphics device (as opposed to an offscreen device), you must call CMEndMatching to finish a matching session before calling WaitNextEvent or any other routine (such as Window Manager routines) that could draw to the screen. Failing to do so will cause unwanted matching to occur. Furthermore, if a device has color matching enabled, you cannot call the CopyBits procedure to copy from it to itself unless the source and destination rectangles are the same.

Even if you call the NCMBeginMatching function before calling the QuickDraw DrawPicture function, the ColorSync picture comments such as cmEnableMatching and cmDisableMatching are not acknowledged. For the ColorSync Manager to recognize these comments and allow their use, you must call the function NCMUseProfileComment for color matching using picture comments.

This function causes matching for the specified devices rather than for the current color graphics port.

VERSION NOTES

The parameter descriptions for src and dst describe changes in how this function is used starting with ColorSync version 2.5.

SEE ALSO

The NCMBeginMatching function uses QuickDraw and performs color matching in a manner acceptable to most applications. However, if your application needs a finer level of control over color matching, it can use the general purpose functions described in Matching Colors Using General Purpose Functions .

For background information on graphics devices, see Inside Macintosh: Imaging With QuickDraw.


CMEndMatching

Concludes a QuickDraw-specific ColorSync matching session initiated by a previous call to the NCMBeginMatching function.

pascal void CMEndMatching (CMMatchRef myRef);
myRef
A reference to the matching session to end. This reference was previously created and returned by a call to NCMBeginMatching function.
function result
This routine does not return an error value.

DISCUSSION

The CMEndMatching function releases private memory allocated for the QuickDraw-specific matching session.

After you call the NCMBeginMatching function and before you call CMEndMatching to end the matching session, embedded color-matching picture comments, such as cmEnableMatching and cmDisableMatching , are not acknowledged.


CMEnableMatchingComment

Inserts a comment into the currently open picture to turn matching on or off.

pascal void CMEnableMatchingComment (Boolean enableIt);
enableIt
A flag that directs the ColorSync Manager to generate a cmEnableMatching PicComment comment if true , or a cmDisbleMatching PicComment comment if false .

function result This routine does not return an error value.

If you call this function when no picture is open, it will have no effect.


NCMDrawMatchedPicture

Changed in ColorSync 2.5

Matches a picture's colors, using the system profile as the initial source profile but switching to any embedded profiles as they are encountered, to a destination device's color gamut, as the picture is drawn, using the specified destination profile.

pascal void NCMDrawMatchedPicture (
                     PicHandle myPicture,
                     CMProfileRef dst,
                     Rect *myRect);
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, as described in Setting Default Profiles .
myRect
A pointer to a destination rectangle for rendering the picture specified by myPicture .
function result
This routine does not return an error value. Instead, after calling NCMDrawMatchedPicture you call the QDError routine to determine if an error has occurred.

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


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

Previous | Back Up One Level | Next