About the ColorSync Manager Programming Interface

The ColorSync Manager programming interface allows your application to handle tasks such as color matching, color conversion, profile management, profile searching and accessing, reading individual tagged elements within a profile, embedding profiles in documents, and modifying profiles.

The ColorSync API is summarized in Summary of the ColorSync Manager. You can find detailed information about individual functions, data types, and constants in ColorSync Manager Reference. The ColorSync Manager includes a number of interface files you may need for your development efforts. These files are described in ColorSync Header Files.

What Should a ColorSync-Supportive Application Do?

Your ColorSync-supportive application can provide a rich set of color-matching features. Your application can color match images, pixel maps, bitmaps, and even individual colors. In addition to color matching, you can handle such tasks as color conversion, color gamut checking, soft proofing of images, profile management, profile searching and accessing, reading individual tagged elements within a profile, embedding profiles and profile identifiers in documents, extracting embedded profiles and profile identifiers, and modifying profiles and profile identifiers.

Your application can provide an interface that offers pop-up menus or other user interface items allowing a user to choose which profile to associate with an image and how an image is rendered. It can show the user the colors of an image that are in or out of gamut for a particular device on which the image is to be produced and how ColorSync adjusts for colors that are out of gamut. This allows the user to preview differences that occur in the color-matching transition between gamuts and make corrections if necessary.

Most of the terms and operations mentioned in this section are defined in Overview of Color and Color Management Systems and Overview of ColorSync.

How the ColorSync Manager Selects a CMM

When a ColorSync function performs a color matching or color checking operation, it must determine which CMM to use. You typically pass source and destination profiles to a function, either directly or as part of a color world—an abstract private data structure you create by calling either the NCWNewColorWorld, the CWConcatColorWorld, or the CWNewLinkProfile function. When you call one of the latter two functions to create a color world, you use the CMConcatProfileSet data structure to specify a series of one or more profiles for the color world.

A profile header contains a CMMType field that specifies a CMM for that profile. For example, Signature of ColorSync’s Default Color Manager describes a signature for the CMMType field that specifies ColorSync’s default CMM. When you set up a CMConcatProfileSet data structure to specify a series of profiles, you set the structure’s keyIndex field to specify the zero-based index of the profile within the array of profiles whose CMM (as indicated by its CMMType field) ColorSync should use. A CMM specified by this mechanism is called a key CMM.

As we have seen, an operation may use more than one profile and there are multiple factors that can affect the choice of a CMM. To deal with these factors, ColorSync uses the following algorithm to select a CMM:

1. Starting with version 2.5, a user can select a preferred CMM in the ColorSync control panel. If a user has chosen a preferred CMM, and if that CMM is available, ColorSync uses that CMM for all color checking and color matching operations the CMM can handle.

   If the preferred CMM is not available or cannot handle an operation, ColorSync uses the default CMM, as described in step 4.

2. Prior to ColorSync 2.5, or if the user has not selected a preferred CMM with the ColorSync control panel, or has selected Automatic, and if the ColorSync function takes a color world reference and the user has initialized the color world with CWConcatColorWorld or CWNewLinkProfile, ColorSync uses the key CMM.

   If the key CMM is not available or cannot handle an operation, ColorSync uses the default CMM, as described in step 4

3. Prior to ColorSync 2.5, or if the user has not selected a preferred CMM with the ColorSync control panel, or has selected Automatic, and if the ColorSync function takes a color world reference and the user has initialized the color world with NCWNewColorWorld (and therefore without a CMConcatProfileSet structure), ColorSync uses an arbitrated CMM or CMMs—a CMM or CMMs selected from the source and destination profiles as described in Selecting a CMM by the Arbitration Algorithm.

   If an arbitrated CMM is not available or cannot handle an operation, ColorSync uses the default CMM, as described in step 4.

4. If a CMM is not specified by one of the previous three steps, or if a specified CMM is not available or cannot handle an operation, ColorSync uses the default CMM—the robust CMM that is installed as part of the ColorSync extension. The default CMM supports all the required and optional functions defined by the ColorSync Manager, and is therefore a suitable CMM of last resort. The signature for the default CMM is specified by the constant kDefaultCMMSignature.

Selecting a CMM by the Arbitration Algorithm

This section describes the arbitration algorithm, introduced in How the ColorSync Manager Selects a CMM, ColorSync uses to select one or more arbitrated CMMs for a color matching or color checking operation:

• If the source and destination profiles specify the same CMM and that CMM component is available and able to perform the matching, then the specified CMM maps the colors directly from the color space of the source profile to the color space of the destination profile. This is the simplest scenario, and Figure 4-1 illustrates it.

• If the source and destination profiles specify different CMMs, then the ColorSync Manager follows these steps to choose the CMM:

  1. If the CMM specified by the destination profile is available, is able to perform the color matching using the two profiles, and is not the default CMM, then the ColorSync Manager uses this CMM. Figure 4-2 shows this scenario.

     

  1. If the destination profile’s specified CMM is unavailable or unable to perform the color-matching request using the two profiles, then the ColorSync Manager looks for the CMM specified by the source profile. If the CMM specified by the source profile is available, is able to perform the color matching using the two profiles, and is not the default CMM, the ColorSync Manager uses this CMM. Figure 4-3 shows this scenario.

  

  1. If both the source-specified CMM and the destination-specified CMM are available, but neither is able to perform the match alone, the ColorSync Manager uses the source profile’s CMM to convert the colors of the source image from the source profile’s color space to an interchange color space using the XYZ color space profile as the destination profile. Next, the ColorSync Manager uses the CMM specified by the destination profile to convert the colors now specified in the interchange color space to colors expressed in the color space of the destination profile using the XYZ color space profile as the source profile. The color conversion and matching work this way if both profiles specify the same interchange color space. Figure 4-4 shows this scenario.

  

  1. If both the source-specified CMM and the destination-specified CMM are available, but neither is able to perform the match alone and both profiles specify different interchange color spaces, the ColorSync Manager uses the source profile’s CMM to convert the colors of the source image from the source profile’s color space to its interchange color space using the appropriate color space profile as the destination profile. The example shown in Figure 4-5 uses the XYZ color space profile as the destination profile. Then the ColorSync Manager inserts a part into the process, itself converting colors from the source profile’s interchange color space to the destination profile’s interchange color space. Next, the ColorSync Manager uses the CMM specified by the destination profile to convert the colors now specified in the destination profile’s interchange color space to colors expressed in the destination profile’s color space using the appropriate color space profile as the source profile. The example shown in Figure 4-5 uses the Lab color space profile as the source profile.

  

• If neither the source nor the destination profile’s specified CMM is available or able to perform the color conversion and matching, then the ColorSync Manager uses the default CMM, which will always attempt to perform the match. Figure 4-6 shows this scenario.

  

Determining If the ColorSync Manager Is Available

To determine whether version 2.5 of the ColorSync Manager is available on a 68K-based or a PowerPC-based Macintosh system, you use the Gestalt function with the gestaltColorMatchingVersion selector. The function shown in Listing 4-1 returns a Boolean value of true if version 2.5 or later of the ColorSync Manager is installed and false if not.

Listing 4-1  Determining if ColorSync 2.5 is available

Boolean ColorSync25Available (void)

{

    Boolean haveColorSync25 = false;

    long    version;

    if (Gestalt(gestaltColorMatchingVersion, &version) == noErr)

    {

        if (version >= gestaltColorSync25)

        {

            haveColorSync25 = true;

        }

    }

    return haveColorSync25;

}

If your application does not depend on features added for version 2.5 of the ColorSync Manager, use the ColorSync Gestalt selector for the ColorSync version you require. For example, you might substitute gestaltColorSync20 for gestaltColorSync25 in the previous function (and rename the function appropriately). To identify other versions of ColorSync, use any of the ColorSync Gestalt selector constants described in ColorSync Manager Reference. For related version information, see ColorSync Version Information.

Providing Minimal ColorSync Support

ColorSync supports the profile format defined by the International Color Consortium (ICC). The ICC format provides a single cross-platform standard for translating color data across devices. The ICC’s common profile format allows one user to electronically transfer a document containing a color image to another user with the assurance that the original image will be rendered faithfully according to the source profile for the image.

To ensure this, the application or driver used to create the image stores the profile for the source device in the document containing the color image. The application can do this automatically or allow the user to tag the image. If the source profile is embedded within the document, a user can move the document from one system to another without concern for whether the profile used to create the image is available.

To support ColorSync, your application should, at a minimum, leave profile information intact in the documents and pictures it imports or copies. That is, your application should not strip out profile information from documents or pictures created with other applications. Even if your application does not use the profile information, users may be able to take advantage of it when using the documents or pictures with other applications.

For example, profiles and profile identifiers may be embedded in pictures that a user pastes into documents created by your application. A profile identifier is an abbreviated data structure that identifies, and possibly modifies, a profile in memory or on disk. For more information on profile identifiers, see Searching for a Profile That Matches a Profile Identifier. Profiles and profile identifiers can be embedded in formats such as PICT or TIFF files. For files of type 'PICT', the ColorSync Manager defines the following picture comments for embedding profiles and profile identifiers, and for performing color matching:

/* PicComment IDs */

enum {

    cmBeginProfile          = 220,  /* begin ColorSync 1.0 profile */

    cmEndProfile            = 221,  /* end a ColorSync 2.x or 1.0

                                        profile */

    cmEnableMatching        = 222,  /* begin color matching for either

                                        ColorSync 2.x or 1.0 */

    cmDisableMatching       = 223,  /* end color matching for either

                                        ColorSync 2.x or 1.0 */

    cmComment               = 224   /* embedded ColorSync 2.x profile

                                        information */

};

The picture comment kind value of cmComment is defined for embedded ColorSync Manager version 2.x profiles and profile identifiers. This picture comment is followed by a 4-byte selector that describes the type of data in the picture comment.

/* PicComment selectors for cmComment */

enum {

    cmBeginProfileSel       = 0,    /* begining of a ColorSync 2.x

                                        profile; profile data to

                                        follow */

    cmContinueProfileSel    = 1,    /* continuation of a ColorSync

                                        2.x profile; profile data to

                                        follow */

    cmEndProfileSel         = 2     /* end of ColorSync 2.x profile

                                        data; no profile data follows */

    cmProfileIdentifierSel  = 3     /* profile identifier information

                                        follows; the matching profile

                                        may be stored in the image or

                                        on disk */

};

Your application should leave these comments and the embedded profile information they define intact. Similarly, if your application imports or converts file types defined by other applications, your application should maintain the profile information embedded in those files, too.

Your application can also embed picture comments and profiles in documents and pictures it creates or modifies. For information describing how to do this, see Embedding Profiles and Profile Identifiers. Inside Macintosh: Imaging With QuickDraw describes picture comments in detail.

Obtaining Profile References

Most of the ColorSync Manager functions require that your application identify the profile or profiles to use in carrying out the work of the function. For example, when your application calls functions to perform color matching or color gamut checking, you must identify the profiles to use for the session. For functions that use QuickDraw, you specify a source profile and a destination profile. For general purpose functions, you specify a color world containing source and destination profiles or a set of concatenated profiles. You can also create a device link profile, which is described in Creating and Using Device Link Profiles, but to do so your application must first obtain references to all the profiles that will comprise the device link profile.

The ColorSync Manager provides for multiple concurrent accesses to a single profile through use of a private data structure called a profile reference. A profile reference is a unique reference to a profile; it is the means by which your application identifies a profile and gains access to the contents of that profile. Many applications can use the same profile at the same time, each with its own reference to the profile. However, an application can only change a profile if it has the only reference to the profile.

struct CMProfileLocation {

    short        locType;   /* specifies the location type */

    CMProfLoc    u;         /* structure for specified type */

};

enum {

    cmNoProfileBase         = 0,    /* the profile is temporary */

    cmFileBasedProfile      = 1,    /* file-based profile */

    cmHandleBasedProfile    = 2,    /* handle-based profile */

    cmPtrBasedProfile       = 3     /* pointer-based profile */

    cmProcedureBasedProfile = 4     /* procedure-based profile */

};

CMError MyOpenProfileFSSpec (FSSpec spec, CMProfileRef *prof)

{

    CMError                 theErr;

    CMProfileLocation       profLoc;

    profLoc.u.fileLoc.spec = spec;

    profLoc.locType = cmFileBasedProfile;

    theErr = CMOpenProfile(prof, &profLoc);

    return theErr;

}

Poor Man’s Exception Handling

Listing 4-3 shows a macro definition that is used in several subsequent code listings. In this macro, if assertion evaluates to false, execution continues at the location exception. Otherwise, execution continues at the next statement following the macro.

Listing 4-3  Poor man’s exception handling macro

// Equivalent to  if ((assertion) == false) goto exception;

#define require(assertion, exception)   \

    do {                                \

        if (assertion) ;                \

        else { goto exception; }        \

    } while (false)

You can find examples of how to use this macro in Listing 4-4, Listing 4-5 and others. While this style of poor man’s exception handling may not appeal to all developers, it does offer these advantages:

• It improves readability because it avoids pushing code off the page with multiple nested if then else clauses and by limiting the number of return statements in the code.

• You can enhance the macro to provide debug messages that supply useful runtime information about the error or where it occurred.

Identifying the Current System Profile

For the functions NCMBeginMatching, NCMUseProfileComment, and NCWNewColorWorld, your application can specify NULL to signify the system profile. For all other functions—for example, the CMGetProfileElement function, the CMValidateProfile function, and the CMCopyProfile function—for which you want to specify the system profile, you must give an explicit reference to the profile. You can use the CMGetSystemProfile function to obtain a reference to the system profile.

Each profile, including the profile configured as the system profile, has a name associated with it. If your application needs to display the name of the system profile to the user, it can call CMGetSystemProfile, as shown in Figure 4-4, to get the system profile, then call the CMGetScriptProfileDescription function to get the profile name and script code.

Listing 4-4  Identifying the current system profile

CMError MyPrintSystemProfileName (void)

{

    CMError         theErr;

    CMProfileRef    sysProf;

    Str255          profName;

    ScriptCode      profScript;

    theErr = CMGetSystemProfile(&sysProf);

    require(theErr == noErr, cleanup);

    theErr = CMGetScriptProfileDescription(sysProf, profName,

                                                &profScript);

    require(theErr == noErr, cleanup);

    // … call Script Mgr to get correct font for script …

    DrawString(profname);

// Do any necessary cleanup. In this case, just return.

cleanup:

    return theErr;

}

Getting the Profile for the Main Display

Starting with ColorSync version 2.5, a user can select a separate profile for each display, as described in Setting a Profile for Each Monitor. In your code, you can determine the profile for any display for which you know the AVID by calling the function CMGetProfileByAVID, which is also new in version 2.5. You can get more information about AVID values from the Display Manager SDK.

Listing 4-5 shows how to get the profile for the main display (the one that contains the menu bar).

Listing 4-5  Getting the profile for the main display

CMError GetProfileForMainDisplay (CMProfileRef *prof)

{

    CMError     theErr;

    AVIDType    theAVID;

    GDHandle    theDevice;

    // Get the main GDevice.

    theDevice = GetMainDevice();

    // Get the AVID for that device.

    theErr = DMGetDisplayIDByGDevice(theDevice, &theAVID, true);

    require(theErr == noErr, cleanup);

    // Get the profile for that AVID.

    theErr = GetProfileByAVID(theAVID, prof);

    require(theErr == noErr, cleanup);

// Do any necessary cleanup. In this case, just return.

cleanup:

    return theErr;

}

This code first gets a graphic device handle for the main display, then calls the Display Manager routine DMGetDisplayIDByGDevice to get an AVID for the device. It then passes the AVID to the ColorSync Manager routine CMGetProfileByAVID to get a profile reference to the profile for the display.

Matching to Displays Using QuickDraw-Specific Operations

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 4-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 inMatching Colors Using the General Purpose Functions to match the colors of a bitmap, a pixel map, or a list of colors.

// 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() )

    {

        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;

}

Creating a Color World to Use With the General Purpose Functions

A color world is a reference to a private ColorSync structure that represents a unique color-matching session. Although profiles can be large, a color world is a compact representation of the mapping needed to match between profiles. Conceptually, you can think of a color world as a sort of matrix multiplication of two or more profiles that distills all the information contained in the profiles into a fast, multidimensional lookup table.

For the ColorSync Manager general purpose functions, a color world characterizes how the color-matching session will occur based on information contained in the profiles that you supply when your application sets up the color world. When Color Matching Occurs describes both general purpose and QuickDraw-specific ColorSync functions for color matching. Your application can define a color world for color transformations between a source profile and a destination profile, or it can define a color world for color transformations between a series of concatenated profiles.

For the general purpose ColorSync Manager functions, a color world is the equivalent of the ColorSync Manager QuickDraw-based functions’ source and destination profiles. From your application’s perspective, the difference in specifying profiles for the general purpose functions is that instead of calling a function and passing it references to the profiles for the session, first you must create a color world using those profile references and pass the color world to the function. This general purpose interface provides better performance during color-matching.

Your application calls the NCWNewColorWorld function to set up a simple color world for color transformations involving two profiles—a source profile and a destination profile—and the function returns a reference to the color world it creates. Setting up a color world for color processing involving a series of concatenated profiles or a single device link profile, which contains a series of profiles, is slightly more complex. Here are the steps you take:

1. Obtain references to the profiles to use for the concatenated color world.

   For information describing how to obtain references to the profiles for the color world, see Obtaining Profile References.

2. Set up an array containing references to the profiles comprising the set.

   Before your application calls the function CWConcatColorWorld to create the color world, you must establish the profile set. The ColorSync Manager defines the following data structure of type CMConcatProfileSet that you use to specify the profile set:

   struct CMConcatProfileSet { unsigned shortkeyIndex; unsigned shortcount; CMProfileRefprofileSet[1]; };

   Your application also uses the CMConcatProfileSet data structure to define a profile set for a device link profile. See Creating and Using Device Link Profiles for more information.

   Your application creates an array that contains references to the profiles for the color world, specifying these references in processing order. You specify the one-based number of profile references in the array by setting the value of the CMConcatProfileSet.count field. You assign the profile array to the CMConcatProfileSet.profileSet field.

   The ColorSync Manager defines rules governing the types of profiles you can specify in a profile array. These rules differ depending on whether you are creating a profile set to create a device link profile or to create a concatenated color world. For a list of the rules defining the types of profiles you can use for these purposes, see CWNewLinkProfile and CWConcatColorWorld.

3. Identify the CMM for color processing.

   Each of the profiles whose references you give identifies a CMM for color processing involving that profile. To perform color transformation using a series of profiles, the ColorSync Manager uses only one CMM. You use the CMConcatProfileSet.keyIndex field to identify the index into the array corresponding to the profile whose specified CMM is to be used. The array is zero based, so you must specify the CMConcatProfileSet.keyIndex value as a number in the range of 0 to count – 1, where count is the number of elements in the array.

4. Call the CWConcatColorWorld function to set up the color world.

   You pass the CWConcatColorWorld function a parameter of type CMConcatProfileSet to specify the profile array, and the function returns a color world reference. To perform color matching or gamut checking using the profiles comprising a color world, you call the general purpose function passing it the reference to the color world.

   Using a device link profile for the general purpose functions entails additional steps, described in Creating and Using Device Link Profiles.

Matching the Colors of a Pixel Map to the Display’s Color Gamut

Your application can call the function CWMatchPixMap to match the colors of a pixel image to the display’s color gamut. To use CWMatchPixMap, you first create a color world, as described in Creating a Color World to Use With the General Purpose Functions. The color world is based on the source profile for the device used to create the pixel image and the destination profile for the display on which the image is shown.

To match the colors of a pixel image to the display’s color gamut, the source profile for the color world must specify a data color space of RGB as its dataColorSpace element value to correspond to the pixel map data type, which is implicitly RGB. If the source profile you specify for the color world is the original source profile used to create the pixel image, most likely these values match. However, if you want to verify that the source profile’s dataColorSpace element specifies RGB, you can use the CMGetProfileHeader function to obtain the profile header. The profile header contains the dataColorSpace element field. For a pixel image, the display profile’s dataColorSpace element must also be set to RGB; this is the color space commonly used for displays.

If the source profile is embedded in the document containing the pixel map, your application can extract the profile and open a reference to it before you create the color world. For information on how to extract an embedded profile, see Extracting Profiles Embedded in Pictures. If the source profile is installed in the ColorSync Profiles folder, your application can display a list of profiles to the user to allow the user to select the appropriate one.

Matching the Colors of a Bitmap Image to the Display’s Color Gamut

Matching the colors of a bitmap image to the current system’s display is similar to the process of matching a pixel map’s colors, except that the data type of a bitmap image is explicitly stated in the space field of the bitmap. You can specify a bitmap image using any of the following data types: cmGraySpace, cmGrayASpace, cmRGB16Space, cmRGB24Space, cmRGB32Space, cmARGB32Space, cmRGB48Space, cmCMYK32Space, cmCMYK64Space, cmHSV32Space, cmHLS32Space, cmYXY32Space, cmXYZ32Space, cmLUV32Space, cmLAB24Space, cmLab32Space, cmLAB48Space, cmNamedIndexed32Space, cmMCFive8Space, cmMCSix8Space, cmMCSeven8Space, or cmMCEight8Space. The data type of the source bitmap image must correspond to the data color space specified by the color world’s source profile.

When you call the CWMatchBitmap function, you can pass it a pointer to a bitmap to hold the resulting image. In this case, you must allocate the pixel buffer pointed to by the image field of the CMBitmap structure. Because the CWMatchBitmap function allows you to specify a separate bitmap to hold the resulting color-matched image, you must ensure that the data type you specify in the space field of the resulting bitmap matches the destination’s color data space. On input, the color space of the source profile must match the color space of the bitmap. If you specify NULL for the destination bitmap, on successful output, ColorSync will change the space field of the source bitmap to reflect the bitmap space to which the source image was mapped.

Rather than create a bitmap for the color-matched image, you can match the bitmap in place. To do so, you specify NULL instead of passing a pointer to a resulting bitmap.

The code in Listing 4-7 shows how to set up a bitmap for the resulting color-matched image before calling the CWMatchBitmap function to perform the color matching. The MyMatchImage function calls the MyGetImageProfile function (not shown) to obtain an embedded profile from the image. If none is found, it calls the MyGetImageSpace function (also not shown) to determine the color space for the profile, then calls the ColorSync routine CMGetDefaultProfileBySpace to obtain the default profile for that space.

The MyMatchImage function then calls GetProfileForMainDisplay, shown in Listing 4-5, to get the destination profile. It uses the source and destination profiles to set up a color world by calling NCWNewColorWorld, then uses the resulting color world when it calls CWMatchBitmap to match the colors to the display.

Listing 4-7  Matching the colors of a bitmap using a color world

void MyMatchImage (FSSpec theImage)

{

    CMError         theErr;

    CMProfileRef    sourceProf;

    CMProfileRef    destProf;

    CMWorldRef      cw;

    CMBitmap        bitmap;

    OSType          theSpace;

    /* Init for error handling. If any error during process,

        jump to cleanup area and quit trying. */

    theErr = noErr;

    sourceProf = nil;

    destProf = nil;

    cw = nil;

    bitmap.image = nil;

    // Determine source profile.

    // 1st - try to find an embedded profile

    theErr = MyGetImageProfile(theImage, &sourceProf);

    if (theErr == noErr)

    {

        // 2nd - use default profile for the image space

        theErr = MyGetImageSpace(theSpace, &sourceProf);

        require(theErr == noErr, cleanup);

        theErr = CMGetDefaultProfileBySpace(theSpace, &sourceProf);

        require(theErr == noErr, cleanup);

    }

    require(theErr == noErr, cleanup);

    // Determine dest profile.

    theErr = GetProfileForMainDisplay(&destProf);

    require(theErr == noErr, cleanup);

    // Set up a color world.

    theErr = NCWNewColorWorld(&cw, sourceProf, destProf);

    require(theErr == noErr, cleanup);

    // close profiles after setting up color world.

    if (sourceProf)

        CMCloseProfile(sourceProf);

    if (destProf)

        CMCloseProfile(destProf);

    sourceProf = destProf = nil;

    // Read the image into the CMBitmap structure

    theErr = MyGetImageBitmap(theImage, &bitmap);

    require(theErr == noErr, cleanup);

    // Match bitmap in place.

    theErr = CWMatchBitmap(cw, &bitmap, nil, nil, nil);

    require(theErr == noErr, cleanup);

    // Render results here ... (code not shown)

/* Do any necessary cleanup:close profiles and dispose of

    color world and bitmap. */

cleanup:

    if (sourceProf)

        CMCloseProfile(sourceProf);

    if (destProf)

        CMCloseProfile(destProf);

    if (cw)

        CWDisposeColorWorld(cw);

    if (bitmap.image)

        DisposePtr(bitmap.image);

    return theErr;

}

Embedded Profile Format

Listing 4-7 shows how profile data is embedded in a PICT file picture as a series of picture comments. The illustration shows two embedded profiles. The first profile contains less than 20K of data, so its data can be stored in one picture comment with selector type cmBeginProfileSel. Note, however, that a second comment of selector type cmEndProfileSel, containing no data, concludes the embedded profile.

The second embedded profile shown in Listing 4-7 has more than 32K of data, so its data must be stored in two consecutive picture comments. The first comment has selector type cmBeginProfileSel, while the second has type cmContinueProfileSel. If the profile were larger and required additional picture comments, each additional comment would have selector type cmContinueProfileSel. As with all embedded profiles, the final picture comment has selector type cmEndProfileSel.

Embedding Different Profile Versions

For version 1.0 of the ColorSync Manager, you use picture comment types cmBeginProfile and cmEndProfile to begin and end a picture comment. The cmBeginProfile comment is not supported for ColorSync version 2.x profiles; however, the you can use the cmEndProfile comment to end the current profile for both ColorSync 1.0 and 2.x. Following a cmEndProfile comment, the ColorSync Manager reverts to the system profile. You use the cmEnableMatching and cmDisableMatching picture comments to begin and end color matching in both ColorSync 1.0 and 2.x. See Inside Macintosh: Imaging With QuickDraw for more information about picture comments.

The NCMUseProfileComment Function

The ColorSync Manager provides the function NCMUseProfileComment to automate the process of embedding a profile or profile identifier. This function generates the picture comments required to embed the specified profile or identifier into the open picture. It calls the QuickDraw PicComment function with a picture comment kind value of cmComment and a 4-byte selector that describes the type of data in the picture comment: 0 to begin the profile, 1 to continue, and 2 to end the profile; or 3 for a profile identifier. For a profile, if the size in bytes of the profile and the 4-byte selector together exceed 32 KB, this function segments the profile data and embeds the multiple segments in consecutive order using selector 1 to embed each segment.

For embedded profiles or profile identifiers to work correctly, the currently effective profile must be terminated by a picture comment of kindcmEndProfile after drawing operations using that profile are performed. If you do not specify a picture comment to end the profile, the profile will remain in effect until the next embedded profile is introduced with a picture comment of kindcmBeginProfile. It is good practice to always pair use of the cmBeginProfile and cmEndProfile picture comments. When the ColorSync Manager encounters a cmEndProfile picture comment, it restores use of the system profile for matching until it encounters another cmBeginProfile picture comment.

In addition to embedded profiles, an image may contain embedded profile identifiers, which are stored with the selector cmProfileIdentifierSel. For more information on profile identifiers, see Searching for a Profile That Matches a Profile Identifier, and CMProfileIdentifier.

Listing 4-8 shows how to embed a profile in a picture file. The MyPreprendProfileToPicHandle function creates a new picture, embeds the profile for the device used to create the picture, then draws the picture. The caller passes a reference for the profile as the prof parameter. Note that after MyPreprendProfileToPicHandle calls the NCMUseProfileComment function to embed the profile, it calls its own MyEndProfileComment function to embed a comment of kindcmEndProfile, ensuring that the profile is properly terminated.

Listing 4-8  Embedding a profile by prepending it before its associated picture

CMError MyPrependProfileToPicHandle (

                PicHandle pict,

                PicHandle *pictNew,

                CMProfileRef prof,

                Boolean embedAsIdentifier)

{

    OSErr           theErr;

    CGrafPtr        savePort;

    GDHandle        saveGDev;

    GWorldPtr       tempWorld;

    Rect            pictRect;

    unsigned long   flags;

    // Init for error handling.

    theErr = noErr;

    tempWorld = nil;

    // Check parameters

    if (prof == nil) theErr = paramErr;

    require(theErr == noErr, cleanup);

    // Determine whether to embed as identifier or whole profile.

    if (embedAsIdentifier)

        flags = cmEmbedProfileIdentifier;

    else

        flags = cmEmbedWholeProfile;

    // Create a temporary graphics world.

    theErr = NewSmallGWorld(&tempWorld);

    require(theErr == noErr, cleanup);

    // Save current world and switch to temporary.

    GetGWorld(&savePort, &saveGDev);

    SetGWorld(tempWorld, nil);

    pictRect = (**pict).picFrame;

    ClipRect(&pictRect);                // Important: set clipRgn.

    // Create a new picture.

    *pictNew = OpenPicture(&pictRect);  // Start recording.

    theErr = NCMUseProfileComment(prof,flags);

    DrawPicture(pict, &pictRect);

    MyEndProfileComment();              // Routine shown below.

    ClosePicture();

    if (theErr)

        KillPicture(*pictNew);

    SetGWorld(savePort, saveGDev);

// Do any necessary cleanup:dispose of graphics world.

cleanup:

    if (tempWorld)

        DisposeGWorld(tempWorld);

    return theErr;

}

Here is the application-defined MyEndProfileComment function called by MyPrependProfileToPicHandle to add the cmEndProfile picture comment to terminate the profile:

void MyEndProfileComment (void)

{

    PicComment(cmEndProfile, 0, 0);

}

Counting the Profiles in the PICT File

Given a picHandle value to a picture containing an embedded profile, the sample code shown in Listing 4-10 counts the number of profiles in the picture.

The MyCountProfilesInPicHandle function calls the Toolbox function SetStdCProcs to get the current QuickDraw drawing bottleneck procedures, then sets the bottlenecks to its own routines. It initializes its global counter, gCount, which holds a single count summing both ColorSync 1.0 profiles and version 2.x profiles, to zero. The MyCountProfilesInPicHandle function calls its own drawing function, MyDrawPicHandleUsingBottleneck, not shown here, to draw the picture. The drawing function sets up a port that uses the private bottleneck routines.

As the picture is drawn, the MyCountProfilesCommentProc bottleneck procedure counts the number of profiles encountered. MyCountProfilesCommentProc checks for both version 1.0 profiles and version 2.x profiles and increments the global count when it finds either type. You can easily modify this code to keep separate counts if necessary.

MyCountProfilesInPicHandle doesn’t use any other QuickDraw bottlenecks, so it uses nonoperational routines (routines that do nothing but return) for all other bottlenecks. The prototype for a function to handle the TextProc bottleneck, for example, can be defined as follows:

static pascal void MyNoOpTextProc ( short byteCount,

                                    Ptr textAddr,

                                    Point numer,

                                    Point denom);

For a general discussion of customizing QuickDraw’s bottleneck routines, see Customizing QuickDraw’s Text Handling in Inside Macintosh: Text.

Listing 4-9  Counting the number of profiles in a picture

CMError MyCountProfilesInPicHandle (PicHandle pict, unsigned long *count)

{

    OSErr       theErr = noErr;

    CQDProcs    procs;

    /* Set up bottleneck for picComments so we can count the profiles. */

    SetStdCProcs(&procs);

    procs.textProc    = NewQDTextProc (MyNoOpTextProc);

    procs.lineProc    = NewQDLineProc (MyNoOpLineProc);

    procs.rectProc    = NewQDRectProc (MyNoOpRectProc);

    procs.rRectProc   = NewQDRRectProc (MyNoOpRRectProc);

    procs.ovalProc    = NewQDOvalProc (MyNoOpOvalProc);

    procs.arcProc     = NewQDArcProc (MyNoOpArcProc);

    procs.polyProc    = NewQDPolyProc (MyNoOpPolyProc);

    procs.rgnProc     = NewQDRgnProc (MyNoOpRgnProc);

    procs.bitsProc    = NewQDBitsProc (MyNoOpBitsProc);

    procs.commentProc = NewQDCommentProc(MyCountProfilesCommentProc);

    procs.txMeasProc  = NewQDTxMeasProc (MyNoOpTxMeasProc);

/* Initialize the global counter to be incremented by the commentProc. */

    gCount = 0;

/* Draw the picture and count the profiles while drawing. */

    theErr = MyDrawPicHandleUsingBottlenecks (pict, procs, nil);

/* Obtain the result from the count global variable. */

    *count = gCount;

/* Clean up and return. */

    DisposeRoutineDescriptor(procs.textProc);

    DisposeRoutineDescriptor(proc.lineProc);

    DisposeRoutineDescriptor(procs.rectProc);

    DisposeRoutineDescriptor(procs.rRectProc);

    DisposeRoutineDescriptor(procs.ovalProc);

    DisposeRoutineDescriptor(procs.arcProc);

    DisposeRoutineDescriptor(procs.polyProc);

    DisposeRoutineDescriptor(procs.rgnProc);

    DisposeRoutineDescriptor(procs.bitsProc);

    DisposeRoutineDescriptor(procs.commentProc);

    DisposeRoutineDescriptor(procs.txMeasProc);

}

pascal void MyCountProfilesCommentProc (short kind,

                                        short dataSize,

                                        Handle dataHandle)

{

    long    selector;

    switch (kind)

    {

        case cmBeginProfile

            gCount ++;  // We found a ColorSync 1.0 profile; increment the count.

            break;

        case cmComment;

            // Break if dataSize is too small to be a selector.

            if (dataSize <= 4) break;

            // Since dataSize is >= 4, we can get a selector from the first long.

            selector = *((long *)(*dataHandle));

            if (selector == cmBeginProfileSel)

                gCount ++;  // We found a ColorSync 2.xprofile; increment the count.

            break;

    }

}

Extracting a Profile

Flattening refers to transferring a profile stored in an independent disk file to an external profile format that can be embedded in a graphics document. Unflattening refers to transferring from the embedded format to an independent disk file.

This part of the sample application identifies the profile to unflatten, unflattens the profile, creates a temporary profile, and disposes of the original. To perform these tasks, the code must again draw the picture using the bottleneck routines.

CMError MyGetIndexedProfileFromPicHandle (PicHandle pict,

                                            unsigned long index,

                                            CMProfileRef *prof,

                                            CMProfileLocation *profLoc)

{

    CMError             theErr;

    unsigned long       refCon;

    CMFlattenUPP        myFlattenUPP;

    Boolean             preferredCMMNotFound;

    Boolean             tempCreated;

    FSSpec              tempSpec;

    CMProfileRef        tempProf;

    CMProfileLocation   tempProfLoc;

    // Init for error handling.

    theErr = noErr;

    tempCreated = false;

    tempProf = nil;

    // Create a universal procedure pointer for the

    // unflatten procedure shown in Listing 3-11.

    myFlattenUPP = NewCMFlattenProc(MyUnflattenProc);

    // Pass the pict as the refcon.

    refCon = (unsigned long) pict;

    // Set the global index variable to the index of the profile we’re looking for.

    gIndex = index;

    // The next call invokes the MyUnflattenProc shown in Listing 3-11.

    //On return, tempSpec identifies the newly created profile on disk.

    theErr = CMUnflattenProfile(&tempSpec, myFlattenUPP,(void*)&refCon,

                            &preferredCMMNotFound);

    DisposeRoutineDescriptor(myFlattenUPP);// Dispose of the procedure pointer.

    require(theErr == noErr, cleanup);

    tempCreated = true;

    // Open the newly created profile, create a temporary profile reference for it,

    // copy the temporary reference, then close it and delete the profile file.

    tempProfLoc.locType = cmFileBasedProfile;

    tempProfLoc.u.fileLoc.spec = tempSpec;

    theErr = CMOpenProfile(&tempProf, &tempProfLoc);

    require(theErr == noErr, cleanup);

    theErr = CMCopyProfile(prof, profLoc, tempProf);

    require(theErr == noErr, cleanup);

// Do any necessary cleanup:close profile and delete file spec.

cleanup:

    if (tempProf)

        theErr = CMCloseProfile(tempProf);

    if (tempCreated)

        theErr = FSpDelete(&tempSpec);

    return theErr;

}

pascal OSErr MyUnflattenProc (long command,

                                long *sizePtr,

                                void *dataPtr,

                                void *refConPtr)

{

    OSErr                   theErr = noErr;

    static CQDProcs         procs;

    static GWorldPtr        offscreen;

    PicHandle               pict;

    switch (command)

    {

        case cmOpenReadSpool:

            theErr = NewSmallGWorld(&offscreen);

            if (theErr)

                return theErr;

            /* Replace the QuickDraw bottleneck routines, mostly with routines

                that do nothing, but also with our unflatten comments routine,

                so that we can intercept the comments we are interested in and

                ignore everything else. */

            SetStdCProcs(&procs);

            procs.textProc    = NewQDTextProc (MyNoOpTextProc);

            procs.lineProc    = NewQDLineProc (MyNoOpLineProc);

            procs.rectProc    = NewQDRectProc (MyNoOpRectProc);

            procs.rRectProc   = NewQDRRectPro (MyNoOpRRectProc);

            procs.ovalProc    = NewQDOvalProc (MyNoOpOvalProc);

            procs.arcProc     = NewQDArcProc (MyNoOpArcProc);

            procs.polyProc    = NewQDPolyProc (MyNoOpPolyProc);

            procs.rgnProc     = NewQDRgnProc (MyNoOpRgnProc);

            procs.bitsProc    = NewQDBitsProc(MyNoOpBitsProc);

            procs.commentProc = NewQDCommentProc (MyUnflattenProfilesCommentProc);

            procs.txMeasProc  = NewQDTxMeasProc (MyNoOpTxMeasProc);

            gChunkBaseHndl = nil;

            gChunkIndex = 0;

            gChunkOffset = 0;

            gChunkSize = 0;

            break;

    case cmReadSpool:

        if (gChunkOffset > gChunkSize)      /* If we overread the last chunk, */

        {

            return ioErr;                   /* use system I/O error value. */

        }

        if (gChunkOffset == gChunkSize)     /* If we used up the last chunk, */

        {

            if (gChunkBaseHndl !=nil)

            {

                HUnlock(gChunkBaseHndl);    /* dispose of the previous chunk. */

                DisposeHandle(gChunkBaseHndl);

                gChunkBaseHndl = nil;

            }

            gChunkIndex++;              /* Read in a new chunk. */

            gChunkOffset = 0;

            gCount = 0;

            gChunkCount = 0;

            pict = *((PicHandle *)refConPtr);

            theErr = MyDrawPicHandleUsingBottlenecks (pict, procs, offscreen);

            /* This invokes MyUnflattenProfilesCommentProc shown in Listing 3-12. */

            if (gChunkBaseHndl==nil)    /* Check to see if we're overread. */

                return ioErr;           /* If so, return system I/O error value. */

            HLock(gChunkBaseHndl);

        }

        if (gChunkOffset < gChunkSize)

        {

            *sizePtr = MIN(gChunkSize-gChunkOffset, *sizePtr);

            BlockMove((Ptr)(&((*gChunkBaseHndl)[gChunkOffset])),

                (Ptr)dataPtr, *sizePtr);

            gChunkOffset += (*sizePtr);

        }

        break;

        case cmCloseSpool:

            if (gChunkBaseHndl != nil)

            {

                HUnlock(gChunkBaseHndl);        /* Dispose of the previous chunk. */

                DisposeHandle(gChunkBaseHndl);

                gChunkBaseHndl = nil;

            }

            /* Dispose of our offscreen world and the routine descriptors

                for our bottlenect routines. */

            DisposeGWorld(offscreen);

            DisposeRoutineDescriptor(procs.MyNoOpTextPrc);

            DisposeRoutineDescriptor(procs.MyNoOpLinePrc);

            DisposeRoutineDescriptor(procs.MyNoOpRectProc);

            DisposeRoutineDescriptor(procs.MyNoOpRRectPrc);

            DisposeRoutineDescriptor(procs.MyNoOpOvalProc);

            DisposeRoutineDescriptor(procs.MyNoOpArcProc);

            DisposeRoutineDescriptor(procs.MyNoOpPolyPrc);

            DisposeRoutineDescriptor(procs.MyNoOpRgnProc);

            DisposeRoutineDescriptor(procs.MyNoOpBitsProc);

            DisposeRoutineDescriptor(procs.MyUnflattenProfilesCommentPrc);

            DisposeRoutineDescriptor(procs.MyNoOpTxMeasPrc);

            break;

        default:

            break;

    }

    return theErr;

}

pascal void MyUnflattenProfilesCommentProc (short kind,

                                            short dataSize,

                                            Handle dataHandle)

{

    long    selector;

    OSErr   theErr;

    if (gChunkBaseHndl != nil) return;

                /* The handle is in use; this shouldn’t happen. */

    if (gCount > gIndex) return;

                /* We have already found the profile. */

    switch (kind)

    {

    case cmBeginProfile:

        gCount ++;          /* We found a version 1 profile. */

        gChunkCount = 1;    /* v1 profiles should only have 1 chunk. */

        if (gCount != gIndex) break;

                            /* This is not the profile we're looking for. */

        if (gChunkCount != gChunkIndex) break;

                            /* This is not the chunk we're looking for. */

        gChunkBaseHndl = dataHandle;

        theErr = HandToHand(&gChunkBaseHndl);

        gChunkSize = dataSize;

        gChunkOffset = 0;

        break;

    case cmComment:

        if (dataSize <= 4) break;

                            /* The dataSize too small for selector, so break. */

        selector = *((long *)(*dataHandle));

                            /* Get the selector from the first long in data. */

        switch (selector)

        {

            case cmBeginProfileSel:

                gCount ++;              /* We found a version 2 profile. */

                gChunkCount = 1;

                if (gCount != gIndex) break;

                                    /* This is not the profile we're looking for. */

                if (gChunkCount!=gChunkIndex) break;

                                    /* This is not the chunk we're looking for. */

                gChunkBaseHndl = dataHandle;

                theErr = HandToHand(&gChunkBaseHndl);

                gChunkSize = dataSize;

                gChunkOffset = 4;

                break;

            case cmContinueProfileSel:

                gChunkCount ++;

                if (gCount != gIndex) break;

                                    /* This is not the profile we're looking for. */

                if (gChunkCount!=gChunkIndex) break;

                                    /* This is not the chunk we're looking for. */

                gChunkBaseHndl = dataHandle;

                theErr = HandToHand(&gChunkBaseHndl);

                gChunkSize = dataSize;

                gChunkOffset = 4;

                break;

            case cmEndProfileSel:

                                    /* Check to see if we're overreading. */

                gChunkCount = 0;

                break;

        }

        break;

    }

}

An Iteration Function for Profile Searching With ColorSync 2.5

The CMIterateColorSyncFolderCompat function, shown in Listing 4-15, performs an optimized search using the CMIterateColorSyncFolder function if ColorSync version 2.5 is available. Otherwise, it calls theCMNewProfileSearch function, which is available in earlier versions of ColorSync.

When you call the CMIterateColorSyncFolderCompat function, you pass a universal procedure pointer to a filter procedure in the proc parameter. CMIterateColorSyncFolderCompat uses that filter procedure when it performs an optimized search with CMIterateColorSyncFolder. Listing 4-13 provides a sample filter procedure called MyIterateProc.

The MyIterateProc function is called once for each available profile and merely stores the names of all non-display profiles (such as printer and scanner profiles) at an arbitrary position in a list. You would do something similar, for example, to display a list of profiles in a dialog.

Note that the CMIterateColorSyncFolderCompat function works in a similar way for ColorSync 2.5 and for earlier versions, although the search is much more efficient with version 2.5. CMIterateColorSyncFolderCompat either calls the CMIterateColorSyncFolder function, which calls the MyIterateProc function once for each available profile, or it calls the CMNewProfileSearch function, which calls the ProfileSearchFilter function (Listing 4-14) once for each available profile. The ProfileSearchFilter function in turn calls MyIterateProc, so similar processing occurs.

Listing 4-13  An iteration function for profile searching with ColorSync 2.5

Pascal OSErr MyIterateProc(CMProfileIterateData* data, void* refcon)

{

    Cell theCell;

    // Assume we can cast refCon to a ListHandle.

    ListHandle list = (ListHandle)refcon;

    /* Assume we’re interested only in non-display profiles, such as printer

        and scanner profiles. */

    if (data->header.profileClass != cmDisplayClass)

    {

        /* This code adds the profile name at an arbitrary position

            in a list. You could do something similar to display a

            list of all available profiles. */

        cell.v = LAddRow(1,999,list);

        cell.h = 0;

        // The name data in the iterate data structure is in Pascal format,

            so we use the length byte to determine how many bytes to copy. */

        LSetCell((Ptr)data->name+1, name[0], cell, list);

        cell.h = 1;

        // Store the profile's location information with the cell.

        LSetCell((Ptr)data->location, sizeof(cmProfileLocation), cell, list);

    }

    // A more complicated function might need to return an error here.

    return noErr;

};

A Filter Function for Profile Searching Prior to ColorSync 2.5

To search for profiles prior to version 2.5 of the ColorSync Manager, you use the CMNewProfileSearch function. You supply CMNewProfileSearch with a search record of type CMSearchRecord that identifies the search criteria. If you also provide a pointer to a filter function, CMNewProfileSearch uses the function to eliminate profiles from the search based on additional criteria not defined by the search record. The ProfileSearchFilter function shown in Listing 4-14 provides an example of a filter routine for searching with the CMNewProfileSearch function.

Listing 4-14 defines the IterateCompatPtr data type, a pointer to a structure that stores search information. When you call the CMIterateColorSyncFolderCompat function shown in Listing 4-15, you pass a reference to the MyIterateProc function (Listing 4-13) in the proc parameter. If ColorSync 2.5 is not available, the CMIterateColorSyncFolderCompat function calls the CMNewProfileSearch function. It passes the ProfileSearchFilter function (Listing 4-13) as the search filter and it passes an IterateCompatPtr pointer as the refCon parameter. It sets the proc field of the IterateCompatPtr pointer to the MyIterateProc function that you passed in the proc parameter.

The CMNewProfileSearch function calls the ProfileSearchFilter function (Listing 4-13) once for each profile. The ProfileSearchFilter function simply casts the passed refCon pointer to an IterateCompatPtr, then calls the function specified by the pointer’s proc field. As a result, the MyIterateProc function is called once for each profile, just as it is when CMIterateColorSyncFolderCompat calls CMIterateColorSyncFolder under ColorSync 2.5.

Note that ProfileSearchFilter always returns true, indicating the profile should be filtered out of the search result returned by CMNewProfileSearch, because we’ve already gotten all the information we need from it. Note also that ProfileSearchFilter uses the require macro, which is defined in Poor Man’s Exception Handling.

Listing 4-14  A filter function for profile searching prior to ColorSync 2.5

// Declare a structure to use for searching with ColorSync versions prior to 2.5.

typedef struct IterateCompat

{

    CMProfileIterateUPP     proc;

    OSErr                   osErr;

    void*                   refCon;

} IterateCompatRec, *IterateCompatPtr;

static pascal Boolean ProfileSearchFilter (CMProfileRef prof, void *refCon)

{

    OSErr                   theErr = noErr;

    IterateCompatPtr        refConCompatPtr;

    CMProfileIterateData    iterData;

    // Cast refcon to our type.

    refConCompatPtr = (IterateCompatPtr)refCon;

    // If we had an error from an earlier profile, give up

    //  by branching to cleanup location.

    theErr = refConCompatPtr->osErr;

    require(theErr == noErr, cleanup);

    // Try to get the profile's location.

    theErr = CMGetProfileLocation(prof, &iterData.location);

    require(theErr == noErr, cleanup);

    // Try to get the profile's header.

    theErr = CMGetProfileHeader(prof, (CMAppleProfileHeader*)&iterData.header);

    require(theErr == noErr, cleanup);

    // Try to get the profile's name.

    theErr = CMGetScriptProfileDescription(prof, iterData.name, &iterData.code);

    require(theErr == noErr, cleanup);

    iterData.dataVersion = cmProfileIterateDataVersion1;

    // Call the iterate callback routine.

    theErr = CallCMProfileIterateProc(refConCompatPtr->proc,

                                    &iterData, refConCompatPtr->refCon);

    require(theErr == noErr, cleanup);

cleanup:

    if (theErr)

        refConCompatPtr->osErr = theErr;

    return true;   // exclude the profile;

}

A Compatible Function for Optimized Profile Searching

Listing 4-15 provides sample code that performs an optimized profile search if ColorSync 2.5 is available, but provides a search that is compatible with previous versions if ColorSync 2.5 is not available.

When ColorSync 2.5 is available, CMIterateColorSyncFolderCompat simply calls the function CMIterateColorSyncFolder, passing on the information it received through its parameters. As a result, CMIterateColorSyncFolder calls the MyIterateProc function, shown in Listing 4-13, once for each available profile. Your version of MyIterateProc can examine the passed information for each profile and perform any required operation on the profiles it is interested in.

When ColorSync 2.5 is not available, CMIterateColorSyncFolderCompat sets up a search with the function CMNewProfileSearch. As part of this setup, it initializes a structure of type IterateCompatRec, defined in Listing 4-14, which it passes to CMNewProfileSearch for the refCon parameter. The CMNewProfileSearch function in turn passes a pointer to the IterateCompatRec structure as the refCon parameter to ProfileSearchFilter, which it calls once for each available profile.

ProfileSearchFilter calls the MyIterateProc function, which gets a chance to handle each profile, just as it does in the case where ColorSync 2.5 is available. The main drawback is that without the availability of the profile cache and the CMIterateColorSyncFolder function, searching through the profiles is likely to be a much more time-consuming task.

Note that CMIterateColorSyncFolderCompat uses the require macro, which is defined in Poor Man’s Exception Handling.

Listing 4-15  Optimized profile searching compatible with previous versions of ColorSync

CMError CMIterateColorSyncFolderCompat (CMProfileIterateUPP proc,

                                         unsigned long *seed,

                                         unsigned long *count,

                                         void *refCon)

{

    CMError theErr = noErr ;

    /* Presume the caller passed a pointer to MyIterateProc to this

            function in the proc parameter. */

    if ( ColorSync25Available() )

        return CMIterateColorSyncFolder(proc, seed, count, refCon);

    else

    {

        CMProfileSearchRef  searchResult;

        CMSearchRecord      searchSpec;

        unsigned long       count;

        IterateCompatRec    refConCompat;

        searchSpec.filter = NewCMProfileFilterProc(ProfileSearchFilter);

        searchSpec.searchMask = cmMatchAnyProfile;

        /* Set up our private data structure for compatible (pre-ColorSync 2.5)

            profile searching.

            Pass the pointer to the MyIterateProc function, which was

                presumably passed to this function in the proc parameter,

                on to our filter routine, ProfileSearchFilter,

                in the refCon parameter, using an IterateCompatRec structure. */

        refConCompat.proc = proc;

        refConCompat.osErr = noErr;

        refConCompat.refCon = refCon;

        //  Start traditional search.

        theErr = CMNewProfileSearch(&searchSpec,

                            (void*)&refConCompat, &count, &searchResult);

        if (theErr == noErr)

        {

            // We don’t use the result, but still must dispose of it.

            CMDisposeProfileSearch(searchResult);

            theErr = refConCompat.osErr;

        }

        DisposeRoutineDescriptor(searchSpec.filter);

    }

    return theErr;

}

Defining a Data Structure for a Resource-Based Profile

The sample code listings that follow use the application-defined MyResourceLocRec data structure. It stores information to describe a resource-based profile, including

• the resource file specification

• the resource type

• the resource ID

• the resource file reference

• the resource handle

• the profile access procedure pointer

• the resource name

  struct MyResourceLocRec {

  FSSpec resFileSpec;

  ResType resType;

  short resID;

  short resFileRef;

  Handle resHandle;

  CMProfileAccessUPP proc;

  Str255 resName;

  };

  typedef struct MyResourceLocRec MyResourceLocRec, *MyResourceLocPtr;

The ColorSync Manager defines the CMProfileAccessUPP type as follows:

typedef UniversalProcPtr CMProfileAccessUPP;

Setting Up a Location Structure for Procedure Access to a Resource-Based Profile

The MyCreateProcedureProfileAccess routine shown in Listing 4-18 sets up a CMProfileLocation structure for procedure access to a resource-based profile. The MyDisposeProcedureProfileAccess routine, shown in Listing 4-19, disposes of memory allocated by MyCreateProcedureProfileAccess. Your application uses these routines (or similar ones that you write) in the following way:

1. Before calling a ColorSync Manager routine such as CMCopyProfile, you call the MyCreateProcedureProfileAccess routine to set up a CMProfileLocation structure that you can pass to the ColorSync Manager routine. The location structure specifies your profile-access procedure and may provide other information as well. A sample profile-access procedure is shown in Listing 4-20.

2. During the course of its operations, the ColorSync Manager may call your profile-access procedure many times.

3. After the ColorSync Manager routine has completed its operation, and if your application does not need to use the CMProfileLocation structure for another operation, you call the MyDisposeProcedureProfileAccess routine to dispose of memory allocated by MyCreateProcedureProfileAccess.

For the sample MyCreateProcedureProfileAccess routine shown in Listing 4-18, you pass a pointer to a CMProfileLocation structure to fill in, a pointer to a file specification for the resource file containing the profile resource, the type of the resource, the ID for the resource, and optionally the name of the resource (stored as a Pascal string, where the first byte is a length byte for the string).

Listing 4-18  Setting up a location structure for procedure access to a resource-based profile

OSErr MyCreateProcedureProfileAccess (

                                    CMProfileLocation *profileLocation,

                                    FSSpec *resourceSpec,

                                    Str255 resourceName,

                                    OSType resourceType,

                                    short resourceID)

{

    OSErr               theErr = noErr;

    MyResourceLocPtr    resourceInfo;

    /* Allocate memory for our private resource info structure. */

    resourceInfo = (MyResourceLocPtr) NewPtrClear(sizeof(MyResourceLocRec));

    if (!resourceInfo)

        theErr = MemError();

    if (!theErr)

    {

        /* Set up our private resource info structure. */

        resourceInfo->resFileSpec = *resourceSpec;

        resourceInfo->resType = resourceType;

        resourceInfo->resID = resourceID;

        resourceInfo->resFileRef = 0;

        resourceInfo->resHandle = 0;

        resourceInfo->proc = NewCMProfileAccessProc(MyCMProfileAccessProc);

        /* If a resource name was passed in, copy it to the structure;

            since it’s a Pascal string, first byte is length;

            note that BlockMoveData is faster than BlockMove for a

            move that involves data only. */

        if (resourceName)

            BlockMoveData(resourceName, resourceInfo->resName,

                            resourceName[0]+1);

        /* set up the profile location structure */

        profileLocation->locType = cmProcedureBasedProfile;

        profileLocation->u.procLoc.refCon = (void*) resourceInfo;

        profileLocation->u.procLoc.proc = resourceInfo->proc;

    }

    return theErr;

}

If the MyCreateProcedureProfileAccess routine is able to set up the profile location pointer for procedure access to a resource-based profile, it returns a value of noErr.

Disposing of a Resource-Based Profile Access Structure

Your application calls the MyDisposeProcedureProfileAccess routine (Listing 4-19) to dispose of any memory allocated by the MyCreateProcedureProfileAccess routine (Listing 4-18).

Listing 4-19  Disposing of a resource-based profile access structure

void MyDisposeProcedureProfileAccess (CMProfileLocation *profileLocation)

{

    DisposeRoutineDescriptor(profileLocation->u.procLoc.proc);

    /* Dispose of our private resource info structure. */

    DisposePtr((Ptr)profileLocation->u.procLoc.refCon);

}

This routine first disposes of the universal procedure pointer to your profile access procedure, then disposes of the pointer used to store resource data in a MyResourceLocRec structure.

Responding to a Procedure-Based Profile Command

For information on the procedure declaration for a profile access procedure, see MyCMProfileAccessProc. The ColorSync Manager calls your procedure when the profile is created, initialized, opened, read, updated, or closed, passing a command constant that specifies the current command. Your profile access procedure must be able to respond to each of the following command constants, which are described in ColorSync Manager Reference:

enum {

    cmOpenReadAccess    = 1,

    cmOpenWriteAccess   = 2,

    cmReadAccess        = 3,

    cmWriteAccess       = 4,

    cmCloseAccess       = 5,

    cmCreateNewAccess   = 6,

    cmAbortWriteAccess  = 7,

    cmBeginAccess       = 8,

    cmEndAccess         = 9

};

The profile access procedure shown in Listing 4-20, MyCMProfileAccessProc, consists of a single switch statement, which calls the appropriate routine based on the value of the command parameter. Each of the nine routines called by MyCMProfileAccessProc is described and listed in the sections that follow Listing 4-20, and each refers back to Listing 4-20.

Listing 4-20  Responding to a procedure-based profile command

pascal OSErr MyCMProfileAccessProc (long command,

                                    long offset,

                                    long *sizePtr,

                                    void *dataPtr,

                                    void *refConPtr)

{

    OSErr   theErr = noErr;

    switch (command)

    {

        case cmBeginAccess:

            theErr = DoBeginAccess(refConPtr);

            break;

        case cmCreateNewAccess:

            theErr = DoCreateNewAccess(refConPtr);

            break;

        case cmOpenReadAccess:

            theErr = DoOpenReadAccess(refConPtr);

            break;

        case cmOpenWriteAccess:

            theErr = DoOpenWriteAccess(sizePtr, refConPtr);

            break;

        case cmReadAccess:

            theErr = DoReadAccess(offset, sizePtr, dataPtr, refConPtr);

            break;

        case cmWriteAccess:

            theErr = DoWriteAccess(offset, sizePtr, dataPtr, refConPtr);

            break;

        case cmCloseAccess:

            theErr = DoCloseAccess(refConPtr);

            break;

        case cmAbortWriteAccess:

            theErr = DoAbortWriteAccess(refConPtr);

            break;

        case cmEndAccess:

            theErr = DoEndAccess(refConPtr);

            break;

        default:

            theErr = paramErr;

            break;

    }

    return theErr;

}

Note that the MyCMProfileAccessProc routine passes its parameter data as necessary to the routines it calls. The parameters have the following values:

command

A command value indicating the operation to perform. The possible values for command constants are shown elsewhere in this section.

offset

For read and write operations, the offset from the beginning of the profile at which to read or write data.

size

For the cmReadAccess and cmWriteAccess command constants, a pointer to a value indicating the number of bytes to read or write; for the cmOpenWriteAccess command, the total size of the profile. On output after reading or writing, the actual number of bytes read or written.

data

A pointer to a buffer containing data to read or write. On output, for a read operation, contains the data that was read.

refConPtr

A reference constant pointer that can store private data for the MyCMProfileAccessProc procedure. For example, Listing 4-18 shows how to set up a location structure for procedure access to a resource-based profile. That routine sets the location structure’s refCon field to a pointer to a MyResourceLocRec structure, which is described in Defining a Data Structure for a Resource-Based Profile. That same structure pointer is passed to the MyCMProfileAccessProc routine in the refConPtr parameter, and provides access to all the stored information about the resource location.