Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Advanced Color Imaging on the Mac OS /: Chapter 4 - Developing ColorSync-Supportive Applications / Developing Your ColorSync-Supportive Application

Matching Colors to Displays Using ColorSync With QuickDraw Operations
To provide your user with images and pictures showing consistent colors across displays, your application can use the ColorSync Manager to match the colors in the user's pictures and documents with the colors available on the user's current display. If a color cannot be reproduced on the current system's display, the ColorSync Manager maps the color to the color gamut of the display according to the specifications defined by the profiles.
The ColorSync Manager provides two high-level functions that use QuickDraw that your application can call to draw a color picture to the current display. One function, NCMDrawMatchedPicture, uses the source profile embedded in the picture to match the picture's colors to the display's gamut defined by the system profile. The other function, NCMBeginMatching, uses the source and destination profiles you specify to match the colors of the source image to the colors of the device for which it is destined.
On all systems, the current display device's profile should be configured as the system profile. The ColorSync System Profile control panel allows the user to configure the current display's profile as the system profile. Because the ColorSync Manager recognizes the system profile as that of the current display, you can specify NULL to indicate the system profile instead of explicitly giving a profile reference. Passing NULL as a profile reference to the ColorSync Manager functions directs the ColorSync Manager to use the system profile.
The following sections describe how to use these high-level matching functions, which automatically perform color matching in a manner acceptable to most applications. Listing 4-4 shows sample code that performs color matching to a display in different ways using the high-level functions.
However, if your application needs a finer level of control over color matching, you can use the low-level ColorSync Manager color-matching functions, described in"Matching Colors Using the Low-Level Functions" (page 4-27) to match the colors of a bitmap, a pixel map, or a list of colors.

Matching Colors in a Picture Containing an Embedded Profile or Profile Identifier
If a user copies a picture that includes a profile or profile identifier into one of your application's documents, your application can use the ColorSync Manager's high-level function NCMDrawMatchedPicture to match the colors in that picture to the display on which you draw it.
As the picture is drawn, the NCMDrawMatchedPicture function automatically matches all colors to the color gamut of the display device, using the destination profile passed in the dst parameter. To use this function, you identify only the profile for the display device. The function acknowledges color-matching picture comments embedded in the picture and uses embedded profiles and profile identifiers. The source profile for the device on which the image was created should be embedded in the QuickDraw picture whose handle you pass to the function; the NCMDrawMatchedPicture function uses the embedded source profile, if it exists. If the source profile is not embedded, the function uses the current system profile as the source profile.
A picture may have more than one profile embedded, and may embed profile identifiers that refer to, and possibly modify, embedded profiles or profiles on disk. If the profiles and profile identifiers are embedded correctly, the NCMDrawMatchedPicture function will use them successively, as they are encountered.
By specifying NULL as the destination profile when you use this function, you are assured that the system profile--that is, the profile for the main screen--is used as the destination profile. Alternatively, your application can call the CMGetSystemProfile function to obtain a reference to the profile and specify the system profile explicitly; the portion of code that calls the NCMDrawMatchedPicture function in Listing 4-4 handles use of the system profile this way.

Considerations
For embedded profiles (and profile identifiers) to operate correctly, the currently effective profile must be terminated by a picture comment of kind cmEndProfile after drawing operations using that profile are performed. If a picture comment was not specified to end the profile, the profile will remain in effect until the next embedded profile is introduced with a picture comment of kind cmBeginProfile. However, use of the next profile might not be the intended action. It is good practice to always pair use of the cmBeginProfile and cmEndProfile picture comments. When the ColorSync Manager encounters an cmEndProfile picture comment, it restores use of the system profile for matching until it encounters another cmBeginProfile picture comment.

Note
Profile identifiers are also stored with picture comments. For more information on profile identifiers, see "Embedding Profiles and Profile Identifiers" (page 4-32) and "Searching for a Profile That Matches a Profile Identifier" (page 4-75).
If your application allows a user to modify an image that you color-matched using the NCMDrawMatchedPicture function, your application must either embed the system profile in the picture file or convert and match the colors of the modified image to the colors of the source profile. The method you choose is specific to your application.

Matching Colors as Your User Draws a Picture
To use Color QuickDraw functions to draw a document with colors matched to a display, your application can simply use the NCMBeginMatching function before calling Color QuickDraw functions, and then conclude its drawing with the CMEndMatching function. Color QuickDraw drawing functions are described in Inside Macintosh: Imaging With QuickDraw.
To use the NCMBeginMatching function, you must specify both the source and destination profiles. The NCMBeginMatching function returns a reference to the color-matching session in its myRef parameter. You then pass the reference to the CMEndMatching function to terminate color matching, as shown in Listing 4-4.
Listing 4-4 Two methods of color matching to a display
void MyMatchingToDisplays (void)
{
   CMError     cmErr;
   CMProfileRefsysProf;
   CMProfileReftargProf;
   PicHandle   hPICT;
   Rect        rcPICT;
   CMMatchRef  matchRef;
   /* use the system profile as the destination profile for the
      NCMDrawMatchedPicture function */
   cmErr = MyGetPict(&hPICT, &rcPICT);
   if (cmErr == noErr)
   {
      cmErr = CMGetSystemProfile(&sysProf);
   }
   if (cmErr == noErr)
   {
      NCMDrawMatchedPicture(hPICT, sysProf, &rcPICT);
      
      KillPicture(hPICT);
      (void) CMCloseProfile(sysProf);
   }
   /* use the system profile as the source profile and another profile as the
   destination profile for the NCMBeginMatching and CMEndMatching functions */
   cmErr = CMGetSystemProfile(&sysProf);

   if (cmErr == noErr)
   {
      cmErr = MyGetImageTargetProfile(&targProf);
   }

   if (cmErr == noErr)
   {
      cmErr = NCMBeginMatching(sysProf, targProf, &matchRef);
      (void) CMCloseProfile(sysProf);
      (void) CMCloseProfile(targProf);
   }

   if (cmErr == noErr)
   {
      MyDoDrawing();

      CMEndMatching(matchRef);
   }  
}