NCMBeginMatching

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

Declaration

CMError NCMBeginMatching (
   CMProfileRef src,
   CMProfileRef dst,
   CMMatchRef *myRef
);

Parameters

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 1804940 Cmgetdefaultprofilebyspace to get the default profile for a specific color space or 1804955 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.
See the QuickDraw Reference for a description of the PixMap data type.
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 1804940 Cmgetdefaultprofilebyspace to get the default profile for a specific color space or 1804955 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.See the QuickDraw Reference for a description of the PixMap data type.
myRef:
A pointer to a matching session. On return, it specifies the QuickDraw-specific matching session that was set up. See the QuickDraw Reference for a description of the PixMap data type.

Return Value

A CMError value. See Result Codes.

Overview

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

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.

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

Version-Notes

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