Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

Chapter 3 - ColorSync Manager Reference for Applications and Device Drivers / ColorSync Manager Functions

Matching Colors Using High-Level Functions With QuickDraw /

NCMBeginMatching

Sets up a high-level ColorSync matching session, using the specified source and destination profiles, that acknowledges QuickDraw operations.

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

src

A profile reference (page 3-63) for the source profile for the matching session. To indicate the ColorSync system profile, specify a NULL value.

dst

A profile reference for the destination profile for the matching session. To indicate the ColorSync system profile, specify a NULL value.

myRef

A pointer to a matching session. On output, it specifies the high-level matching session that was set up.

function result

A result code of type CMError. See "Result Codes" (page 3-174) for a list of ColorSync-specific result codes.

DISCUSSION

The NCMBeginMatching function sets up a high-level matching session using QuickDraw, 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 CMEndMatching function, described next, 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 first 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 would 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 low-level functions (which include the use of concatenated profiles well suited to print preview processing) offer an easier and faster way to do this.

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 and 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 NCMDrawMatchedPicture function for color matching using picture comments.

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

SEE ALSO

The high-level color-matching function NCMBeginMatching that uses QuickDraw 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 low-level matching functions described in "Matching Colors Using Low-Level Functions Without QuickDraw" (page 3-107).

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