![]() |
PATH![]() |
![]() ![]() |
To provide images and pictures showing consistent colors across displays, your application can use ColorSync to match the colors in a user's pictures and documents with the colors available on the user's current display. If a color cannot be reproduced on the system's current display, ColorSync maps the color to the color gamut of the display according to the specifications defined by the profiles. When Color Matching Occurs describes both QuickDraw-specific and general purpose ColorSync functions for color matching.
The ColorSync Manager provides two QuickDraw-specific functions that your application can call to draw a color picture to the current display. The function
NCMDrawMatchedPicture
matches the picture's colors to the display's gamut defined by the specified display profile. It uses the system profile as the initial source profile but switches to any embedded profiles as they are encountered. The 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.
The current display device's profile is typically configured as the system profile. A user can do this with the ColorSync control panel. However, starting with ColorSync 2.5, a user can use the Monitors & Sound control panel to set a separate profile for each display, as described in Setting a Profile for Each Monitor . When a user sets a profile for a display, ColorSync makes that profile the current default system profile.
Because the ColorSync Manager assumes the system profile is that of the current display, you can pass a value of
NULL
to the QuickDraw-specific functions instead of supplying an explicit profile reference. Passing
NULL
for a profile reference directs the ColorSync Manager to use the system profile. Note however, that starting with ColorSync 2.5, if you know the primary display for the image, and you know the AVID for that display, you can call
CMGetProfileByAVID
to get the profile for the specific display. For example,
Listing 3-5
shows how to get the profile for the main display (the one with the menu bar).
The following sections describe how to use ColorSync's QuickDraw-specific matching functions, which automatically perform color matching in a manner acceptable to most applications. However, if your application needs a finer level of control over color matching than is supplied by the QuickDraw-specific functions, you can use the general purpose functions described in Matching Colors Using the General Purpose Functions to match the colors of a bitmap, a pixel map, or a list of colors.
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 QuickDraw-specific 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 need to supply only the profile for the destination 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--typically set to 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. Or, starting in ColorSync version 2.5, if you know the AVID for the display on which drawing takes place, you can call
CMGetProfileByAVID
to get the profile for the display.
Listing 3-6 shows sample code that uses the QuickDraw-specific function NCMDrawMatchedPicture to perform color matching to a display. The code gets a profile for the destination display using an AVID if it is available; otherwise, it passes NULL to the NCMDrawMatchedPicture function to specify the system profile.
Listing 3-6 Matching a picture to a display
// Matching a picture to a display
CMError MyDrawPictureToADisplay (PicHandle thePict, AVIDType theAVID, Rect *destRect)
{
CMError theErr;
CMProfileRef destProf;
// Init for error handling.
theErr = noErr;
destProf = NULL;
// If caller supplied an AVID and CS 2.5 is running...
if (theAVID && ColorSync25Available() ) // See Listing 3-1 on page -xcii.
{
theErr = GetProfileByAVID(theAVID, &destProf);
require(theErr == noErr, cleanup);
}
else
{
// Use the System profile as the destination.
destProf = NULL;
}
// Draw the picture, with color matching.
NCMDrawMatchedPicture(thePict, destProf, destRect);
theErr = QDError();
require(theErr == noErr, cleanup);
// Do any necessary cleanup. If necessary, close the profile.
cleanup:
if (destProf)
CMCloseProfile(destProf);
return theErr;
}
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 encountered 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 and Searching for a Profile That Matches a Profile Identifier .
If your application allows a user to modify and save an image that you color matched using the function
NCMUseProfileComment
, your application should either embed the destination profile in the picture file or convert and match the colors of the modified image to the colors of the source profile. By doing this your application ensures the integrity of the image during future operations and display. The method you choose is specific to your application.
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, then conclude its drawing with the
CMEndMatching
function. For example, you might want to do this to customize settings in the profile that affect the matching operation. For more information on Color QuickDraw drawing functions, see
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. Code for performing this operation is not shown here.