PRINT HINTS

SYNCING UP WITH COLORSYNC

JOHN WANG

Apple's recently introduced ColorSync, a color matching software technology, provides a common platform for applications and device drivers to match colors by communicating color information between graphics devices with differing color characteristics. This column starts off with an overview and then delves deeper into the inner workings of ColorSync so that you'll have a better understanding of how to use this new technology. We'll also take a look at how applications and device drivers can take advantage of ColorSync.

WHAT IS COLORSYNC?
ColorSync is an extension to the Macintosh system that's distributed with the Apple Color Printer and the Color OneScanner. It provides a platform for maintaining quality and similarity of images that are moved between different devices. Because different devices typically reproduce different gamuts -- ranges of colors -- ColorSync can be used by applications and device drivers to perform color correction. For example, monitors from different manufacturers have dissimilar gamuts because they use different hardware that drives different cathode ray tubes. In fact, there are minute color differences among the same models due to the video card, internal settings, user adjustments, and even age. ColorSync uses color matching algorithms to visually equate the images produced by different devices. Applications that are ColorSync aware attempt to display a document faithfully on any monitor.

Besides supporting RGB, ColorSync supports color matching with other color spaces, such as CMYK. Printers normally work in the CMYK color space because CMYK colors are subtractive -- when added they move the image toward black or dark gray. This is entirely different from RGB monitors, which use additive colors -- colors that when added move the image toward white. Consequently, ColorSync is especially useful when it's necessary to match on-screen and printed colors -- colors with two very different gamuts.

PROFILES AND COLOR MATCHING METHODS
ColorSync uses two major elements to implement color matching between devices: profiles and color matching methods (CMMs). The profiles contain the device characterization while the CMMs contain the color matching code to perform the matching. A CMM performs matching between a source profile and a destination profile. A system will have at least one profile for each device to be matched and at least one CMM to perform the matching. Apple ships ColorSync with one Apple CMM and with ColorSync profiles for all Apple monitors currently being manufactured. The open architecture of ColorSync allows third-party developers to create their own profiles and CMMs.

A ColorSync profile is simply a file whose data fork contains a CMProfile record, usually stored in the ColorSync^TM Profiles folder. (This folder is in the Preferences folder in your System Folder; your code can get it by calling GetColorSyncFolderSpec.) Profiles may also be stored in a 'prof' resource,as discussed later. A device may have more than one profile; however, only one is selected for use at any given time. For example, printers have profiles for various paper types since the output onto different types of paper can vary. The Apple Color Printer has default profiles for coated paper, transparency film, and plain paper. A monitor may also have several profiles for various special gamma settings. ColorSync neither affects nor is affected by the gamma setting. For best results, the user must select a ColorSync profile that matches the gamma.

Here's the data structure for a CMProfile record:

typedef struct CMHeader {
    unsigned long   size;
    OSType          CMMType;
    unsigned long   applProfileVersion;
    OSType          dataType;
    OSType          deviceType;
    OSType          deviceManufacturer;
    unsigned long   deviceModel;
    unsigned long   deviceAttributes[2];
    unsigned long   profileNameOffset;
    unsigned long   customDataOffset;
    CMMatchFlag     flags;
    CMMatchOption   options;
    XYZColor        white;
    XYZColor        black;
} CMHeader;

typedef struct CMProfileChromaticities {
    XYZColor    red;
    XYZColor    green;
    XYZColor    blue;
    XYZColor    cyan;
    XYZColor    magenta;
    XYZColor    yellow;
} CMProfileChromaticities;

typedef struct CMProfileResponse {
    unsigned short  counts[onePlusLastResponse];
    CMResponseData  data[1];
} CMProfileResponse;

typedef struct CMProfile {
    CMHeader                header;
    CMProfileChromaticities profile;
    CMProfileResponse       response;
    IString                 profileName;
    char                    customData[1];
} CMProfile, *CMProfilePtr, **CMProfileHandle;

CMMs are components of type 'cmm ' that contain code to perform matching. The component subtype distinguishes between different CMMs. ColorSync ships with the default Apple CMM, which has the subtype 'appl'. Developers who want to provide custom CMMs to perform matching beyond the capabilities of Apple's basic color matching method need to register their CMM subtype with the Apple Registry (AppleLink REGISTRY) to avoid conflict with other CMM manufacturers. The only requirement for subtype naming is that all-lowercase types are not used, because they're reserved by Apple.

A CMM can have six routines, three of which are required:

• CMInit: Given the source and destination profile, prepare to perform color matching.
• CMMatchColors: Match a list of colors using profiles specified by a call to CMInit.
• CMCheckColors: Check a list of colors and determine whether they fall within the gamut of the destination device's color space.

The optional CMM routines are as follows:

• CMMatchPixMap: Match the colors of a pixel map using profiles specified by a call to CMInit.
• CMCheckPixMap: Check a pixel map to determine which pixels fall outside the destination profile's gamut.
• CMConcatenateProfiles: Concatenate two profiles to create one new profile.

WHICH CMM TO USE?
ColorSync profiles that refer to the custom CMMs can be created by setting the CMMType field in the CMHeader to the subtype of the CMM. ColorSync will attempt to use the corresponding CMM when using that profile. However, the custom profiles must still contain the data necessary for compatibility with Apple's default color matching method so that the Apple CMM can be used if the custom CMM is unavailable. The rules for deciding which CMM to use depend on the source and destination profile:

1. If the source and destination profiles use the same CMM and the corresponding CMM is available, the matching is performed entirely by that CMM. If the CMM is not available, the Apple CMM is used.
2. If the source and destination profiles use different CMMs, then: a) If the CMM for the destination profile is available, try using that CMM. If the CMM returns an error because it can't perform the color matching, try step b. Since the Apple CMM will never return an error because it's always able to perform matching between two profiles, this is considered a special case, so skip to b. b) If the CMM for the source profile is available, try using that CMM. If the CMM returns an error because it can't perform the color matching, try step 3. Again, since the Apple CMM will never return an error, this is considered a special case, so skip to step 3.
3. If the CMMs for both the source and destination profiles are available but can't perform the matching as described in step 2, ColorSync matches using the source CMM from the source profile color space to the XYZ color space, and then using the destination CMM from the XYZ color space to the destination profile color space.
4. If step 3 doesn't work because a CMM is missing, the Apple CMM is substituted for the missing one.

COLORSYNC ROUTINES
ColorSync provides high-level and low-level routines that may be used by application and device driver developers. Except for BeginMatching, EndMatching, and DrawMatchedPicture -- which are available in System 7 only -- the routines are available in system software version 6.0.7 and later. On all systems, ColorSync must be installed. The gestalt selector 'cmtc' returns gestaltColorSync10 (0x0100) for the version of ColorSync that works with system software version 6.0.7, and gestaltColorSync11 (0x0110) for the version that works with System 7. (Note that 6.0.7 must also have version 1.2 of the 32-Bit QuickDraw INIT installed.)

// Use Gestalt to get version of ColorSync.
if (Gestalt(gestaltColorMatchingVersion, &CMversion) != noErr)
    CMversion = 0;

The high-level profile management routines are as follows:

• GetProfile: Get the profile currently selected for a device.
• SetProfile: Add a profile to the device's profile list.
• SetProfileDescription: Set profile description fields for a new profile (typically created by a calibrator).
• GetColorSyncFolderSpec: Get the folder in which ColorSync profiles should be stored.
• GetProfileName: Given a profile, return its name.
• GetProfileAdditionalDataOffset: Given a profile, return the custom data offset.
• ConcatenateProfiles: Concatenate two profiles into one.
• GetIndexedProfile: Return the number of profiles and the profiles from the device's profile list.
• DeleteDeviceProfile: Delete a profile from a device's profile list.

The following high-level matching routines provide a layer of code between application and device driver code and the CMM component code. They simplify color matching by performing matching of all QuickDraw drawing routines.

• BeginMatching: Tell Color QuickDraw to begin matching for the current graphics device using the specified source and destination profiles. (Not available in system software version 6.0.7.)
• EndMatching: Tell Color QuickDraw to stop matching. (Not available in 6.0.7.)
• EnableMatching: Insert picComments to turn matching on or off inside a picture.
• UseProfile: Insert a profile into an open picture.
• DrawMatchedPicture: Draw a picture using color matching. (Not available in 6.0.7.)

These low-level routines perform color matching:

• CWNewColorWorld: Create a color matching world using the specified source and destination profiles.
• CWDisposeColorWorld: Dispose of a color matching world to end the session.
• CWMatchColors: Match a list of colors using the current color matching world.
• CWCheckColors: Check a list of colors to see if they fall within a device's gamut. Use the current color matching world.
• CWMatchPixMap: Match a pixel map using the current color matching world.
• CWCheckPixMap: Check the colors of a pixel map using the current color matching world to determine whether the colors are in the gamut of the destination device.

HOW DOES COLORSYNC WORK?
Now that you have an overview of the basic elements of ColorSync -- profiles, CMMs, and routines -- we can discuss how ColorSync works by putting all these pieces together.

As mentioned earlier, ColorSync profiles are normally stored in the ColorSync^TM Profiles folder in the Preferences folder. In this folder, you'll find a selection of monitor profiles for all Apple color monitor products. In some cases, there are duplicates to account for the color differences between different gamma settings for the monitor. For example, the Apple 16-inch monitor has two profiles: Apple 16" RGB Page-White and Apple 16" RGB Standard. The user selects the profile that corresponds to the Use Special Gamma setting made in the Monitors control panel. This profile -- also called the system profile -- is selected in the ColorSync control panel. The system profile is used as the default source profile whenever you're matching from a document that doesn't specify a profile or matching to a device that doesn't otherwise have an associated profile.

You may be wondering how to use the ColorSync control panel to select more than one system profile for multiple monitors. Unfortunately, the system profile is an abstraction that shouldn't be associated with any particular device. As described earlier in "Which CMM to Use?" it should be used whenever a profile isn't explicitly specified for a source or destination. ColorSync-awareapplications can support multiple monitors by matching to specific graphics devices, thereby overriding the system profile selection. But this isn't recommended except with high-end applications because of difficulties in implementation and complexities for the user.

Applications can determine the current system profile selection with GetProfile. In fact, GetProfile works with any device to get the current profile selection for that device. However, for the call to work, the devices must register their profile responder. Every device that uses ColorSync to perform matching must have a profile responder, which is a component that supports the following routines:

• CMGetProfile: Return the profile that the driver would use to perform a match.
• CMSetProfile: Add the profile to the driver's profile list.
• CMSetProfileDescription: Set the device-specific fields in a profile. This allows newly created profiles to be used with the device.
• CMGetIndexedProfile: Get the profile that matches the search criteria.
• CMDeleteDeviceProfile: Delete the profile from the driver's profile list.

The system profile responder is always registered globally in a system, so you can use the ColorSync high-level profile management routines on the system device. Printer driver profile responders are registered only if requested; you register one by calling PrGeneral with the driver opened. The PrGeneral opcode is registerProfileOp (13). By using a profile responder, an application can communicate with any device to request ColorSync profile information. This is especially useful for calibration applications. For example, an application can create a new profile for a printer, call SetProfileDescription to set the device-specific fields in the profile, and then call SetProfile to add the profile to the device driver's profile list.

The following code excerpt demonstrates how to register a device driver profile responder. The complete sample code (including error checking!) is provided on this issue's CD.

// Register printer profile responder.
PrOpen();
if ((prError = PrError()) == noErr) {
    printerOpened = true;
    prRecHdl = (THPrint)NewHandle(sizeof(TPrint));
    PrintDefault(prRecHdl);
    
    regProfileBlk.iOpCode = registerProfileOp;
    regProfileBlk.iError = 0; 
    regProfileBlk.lReserved = 0;
    regProfileBlk.hPrint = prRecHdl;
    regProfileBlk.fRegisterIt = true;
    PrGeneral((Ptr)&regProfileBlk);
    prError = regProfileBlk.iError;
}

You don't see the default profiles for device drivers such as the Apple Color Printer in the ColorSync^TM Profiles folder because they're stored as 'prof' resources in the device drivers themselves. However, applications can still create profiles for the printer driver to use by placing them in the ColorSync^TM Profiles folder. All printer drivers should search not only in their private profile storage location but in the ColorSync^TM Profiles folder as well. In the Apple Color Printer Print Options dialog box, users can choose custom profiles in a pop-up menu if Customized Color Matching is selected. The driver even filters the profiles, so only profiles that match the paper type appear in the menu. This is accomplished by reading in each profile in the folder and searching for the desired values in the CMHeader record. The Apple Color Printer driver stores the profile's paper type in the deviceAttributes field of the profile's CMHeader record. This field is used differently by various devices; for instance, monitor profiles use it to store the gamma setting. When you finally print to a color printer such as the Apple Color Printer, the printer driver performs matching from the system profile to the printer profile. The application must pass the ColorSync picComments through to the printer for matching to occur. If the application strips out picComments, the printer driver assumes the document uses the system profile. If the picComments contain a custom profile, the printer driver uses that profile as the source profile instead of the system profile. Even a matching method chosen in the Customized Color Matching pop-up menu is overridden by such custom profiles. For example, if a document contains scanned images, the images may have a custom profile that uses photographic matching while the rest of the document uses the solid color system profile.

WHAT DOES AN APPLICATION HAVE TO DO?
In a way, most applications are already ColorSync compatible because they can print to ColorSync- aware printers such as the Apple Color Printer. However, for an application to become ColorSync savvy, it should have three key features:

• It should allow users to tag color matching information to documents and to be able to display them using ColorSync. ColorSync calls such as UseProfile, DrawMatchedPicture, and BeginMatching/EndMatching can be used to do this.
• Applications should allow users to preview the output to a ColorSync-aware printer by matching from the document to the printer profile and back to the system profile. The user can thus view color differences that occur in the color matching transition between gamuts. The application can even visually outline colors that can't be displayed faithfully, using the CheckColors routine.
• Most important, the application must preserve picComments in its documents. The application can allow modification of the ColorSync picComments as appropriate, but it must save the information in the document and allow the information to be passed through to the printer.

WHAT DOES A PRINTER DRIVER HAVE TO DO?
A printer driver must first have a responder component that implements the responder routines mentioned earlier. The responder allows ColorSync to communicate with the printer driver. By watching for picComments in the printer port bottleneck procs, the driver is notified of source profile changes and other information as well. The printer driver can then adjust the color matching accordingly.

Matching can be performed with high-level calls such as BeginMatching or with low-level calls such as CWMatchColors. If the printer driver spools pages in the PICT format and uses DrawPicture with an off-screen graphics device for rendering, the high-level calls can be used. Otherwise, matching is best performed with the low-level calls from the QuickDraw bottleneck procs. The Apple Color Printer uses low-level calls and performs color matching in its custom bottleneck procs before rendering occurs. Applications that generate PostScript^TM code directly must perform color matching themselves using the low-level calls. They can determine what destination printer profile to use by calling GetProfile.

Apple doesn't ship an updated LaserWriter driver to support ColorSync because it would require a major rewrite of current code. However, applications can work around this by performing the color matching in the application. On the other hand, PostScript Level 2 has color matching support built into the PostScript language, so it would be possible to offload color matching to the PostScript imaging device.

YOUR COLORFUL FUTURE
ColorSync is an open architecture platform that enables third-party developers to create profiles, CMMs, and drivers that are mutually compatible. As shown in the past, open architecture promotes market acceptance and user adoption. By using ColorSync as your color matching platform, you're ensured of continued compatibility with future Apple technologies.

As a developer, you can influence the direction of ColorSync; send your feedback to AppleLink DEVSUPPORT. In fact, you can even send me your ColorSync-savvy application (AppleLink WANG.JY) and I'd be thrilled to evaluate it.

JOHN WANG (AppleLink WANG.JY) is standing in for Pete ("Luke") Alexander, who was busy working on his QuickDraw GX article for a future issue of develop. We expect various members of Developer Technical Support's Printing, Imaging, and Graphics group to take turns writing this column in the future. John also found the time to write his regular QuickTime column; look there (later in this issue) for the real John Wang bio. *

The ColorSync Utilities document on this issue's CD is the comprehensive document that developers should refer to for ColorSync development. However, having worked with many ColorSync developers, I've come across several issues that aren't covered in the ColorSync Utilities document. This column is a conglomeration of hours of discussion and mutual enlightenment.*You make gamma settings in the Monitors control panel by Option-clicking the Options button and, in the dialog box that appears, selecting Use Special Gamma and choosing the special gamma from the pop-up menu. *

Components are described in the Component Manager documentation in the QuickTime Developer's Kit v. 1.5. The information will soon be published in Inside Macintosh: More Macintosh Toolbox. *

XYZ is a device-independent color space defined by the Commission Internationale de l'Eclairage (CIE). It's an additive color space similar to RGB. Each of the XYZ components is a 1.15-bit unsigned fixed-point number.*

Color matching to multiple monitors is implemented by setting the destination profile for each graphics device with SetProfile and then performing matching with DrawMatchedPicture or BeginMatching/EndMatching. *

Applications that strip picComments from pictures before sending them to the printer driver are not ColorSync compatible because they remove the information that ColorSync uses to perform matching. For general information on picComments, see the Macintosh (Imaging) Technical Note "Picture Comments -- The Real Deal" (formerly #91). *

Thanks to Bill Guschwan, Tom Mohr, Konstantin Othmer, Steve Swen, and Forrest Tanaka for reviewing this column. *