Legacy Document

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

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

Creating and Using Device-Linked Profiles
To accommodate users who use a specific configuration requiring a combination of device profiles and possibly nondevice profiles repeatedly over time, your application can create device-linked profiles. A device-linked profile offers your user a means of saving and storing a series of profiles corresponding to a specific configuration in a concatenated format. This feature provides an economy of effort for both your application and its user.
There are many uses for device-linked profiles. For example, a user might want to store multiple profiles, such as various device profiles and color space profiles associated with the creation and editing of an image.
Most users use the same device configuration to scan, view, and print graphics over a period of time, often soft proofing images before they print them. To enhance your application's soft-proofing feature, you can allow your users to store the contents of the profiles involved in the soft-proofing process in a device-linked profile. Your application can use the appropriate device-linked profile each time a user enacts the soft-proofing feature, instead of opening a profile reference to each of the profiles to create a color world to pass to the color-matching functions. For additional information about soft proofing, see "Providing Soft Proofs" (page 4-55).
A device-linked profile is especially useful when a scanner application does not embed the source profile in the document containing the image it creates. By storing the scanner's profile, your application eliminates the need to query the user for the appropriate source profile each time the user wants to soft proof using the configuration involving that scanner.
A user may want to see how a scanned image will look when printed using a specific printer. The user may want to look at many images captured on the same scanner at different times before printing the image. Because the same devices are involved in the process, if your application has offered the user the opportunity to create device-linked profiles, your application could display a list of device-linked profiles that the user had previously created for various configurations and allow the user to select the appropriate one for the current soft proofing.
Here are the steps your application should take in creating a device-linked profile:
Open the profiles corresponding to the devices and transformations involved in the configuration and obtain references to them.
To create a device-linked profile, your application must first obtain references to the profiles involved in the configuration. If the profile for an input device, such as a scanner, is embedded in the document containing the image, you must first extract the profile. For a description of how to obtain a profile reference, see "Obtaining Profile References" (page 4-16). For information describing how to extract a profile from a document, see "Extracting Profiles Embedded in Pictures" (page 4-37).
Create an array containing references to the profiles, specifying the profile references in processing order.
You supply the profile references as an array of type CMProfileRef within a data structure of type CMConcatProfileSet. The order of the profiles must correspond to the order in which you want the colors of the image to be processed. For example, for soft proofing an image, you should specify the scanner profile reference first, followed by the printer profile reference, and then the display profile reference because the goal is to match the colors of the scanned image to the color gamut of the printer for which the image is destined and then display the results to the user.
In the count field, specify a one-based number identifying how many profiles the array holds. A device-linked profile represents a one-way link between devices.
Here is the CMConcatProfileSet data type:
struct CMConcatProfileSet {
 unsigned short     keyIndex;     /* zero-based */
 unsigned short     count;     /* one-based */
 CMProfileRef     profileSet[1];
};
You must adhere to the rules that govern the type of profiles you can specify in the array. For example, the first and last profiles must be device profiles. For a list of these rules, see "Concatenated Profile Set Structure" in Advanced Color Imaging Reference.
Specify the index corresponding to the profile whose preferred CMM is used to perform the processing.
The header of each profile specifies the preferred CMM for that profile. Only one CMM is used for all transformations across the profiles of a device-linked profile. You identify the profile whose CMM is used by supplying the zero-based index of that profile in the keyIndex field of the CMConcatProfileSet data type.
Using the CMProfileLocation data type, provide a file specification for the new device-linked profile.
If the CWNewLinkProfile function is successful, the ColorSync Manager creates a device-linked profile in the location that you specify, opens a reference to the profile, and returns the profile reference to your application. To tell the ColorSync Manager where to create the new profile, your application must provide a file specification. The ColorSync Manager defines a data structure of type CMProfileLocation containing a CMProfLoc union that you use to give a file specification. See Listing 4-2 (page 4-19), which assigns values to a CMProfileLocation data structure.
Call the CWNewLinkProfile function to create the device-linked profile.
After you set up CMConcatProfileSet and CMProfileLocation, your application can call the CWNewLinkProfile function, passing these values to it. If the function completes successfully, it returns a reference to the newly created device-linked profile.
Note that you cannot embed a device-linked profile into a document along with an image that uses it.
Using the CWConcatColorWorld function, create a color world based on the device-linked profile.
You can use a device-linked profile with the low-level ColorSync Manager functions only. To use a device-linked profile for a color-matching or color gamut-checking function, you must first create a color world using the CWConcatColorWorld function, passing to it a data structure of type CMConcatProfileSet. The CMConcatProfileSet data structure is the same data type that you used to specify the array of profiles when you created the new device-linked profile. To create the color world, however, you specify the device-linked profile as the only member of the CMConcatProfileSet array. If the CWConcatColorWorld function is successful, it returns a reference to a color world that your application can pass to other low-level functions for color-matching and color gamut-checking sessions. A device-linked profile remains intact and available for use again after your application calls the CWDisposeColorWorld function to dispose of the concatenated color world.
Considerations
Here are some points to consider about how the ColorSync Manager uses information contained in the profiles comprising a device-linked profile:

When you use a device-linked profile, the quality flag setting--indicating normal mode, draft mode, or best mode--specified by the first profile prevails for the entire session; the quality flags of following profiles in the sequence are ignored. The quality flag setting is stored in the flags field of the profile header.
The ColorSync Manager uses the rendering intent specified by the first profile to color match to the second profile, the rendering intent specified by the second profile to color match to the third profile, and so on through the series of concatenated profiles.

When your application is finished with the device-linked profile, it must close the profile with the CMCloseProfile function.