KCMS Application Developer's Guide

Typical Profile Operations Using the KCMS API

Your application can make function calls to the KCMS API to perform various tasks. Typically, applications want to use profiles to convert color data from one device type to another. This involves functions such as loading the profiles, getting and setting attributes, and saving the results. This section describes some of the typical API functions.

Getting and Setting Profile Attributes

The KCMS API provides a way to get profile information by examining the profile's attribute set. Each attribute has a value, which is data associated with the attribute. The API provides the following attribute calls:

KcsGetAttribute()--gets a specific attribute value associated with a profile. See "KcsGetAttribute()" for detailed information.

KcsSetAttribute()--modifies an attribute. (This is not always possible because some attributes are read-only.) See "KcsSetAttribute()" for detailed information.

For more information on profile attributes, see Chapter 5, KCMS Profile Attributes.

Loading and Saving Profiles

Profiles are typically stored as files on disks, although they can be imbedded in an image located across a network or in read-only memory in a printer.

Profiles are loaded with the KcsLoadProfile() function (see "KcsLoadProfile() ") and are saved with the KcsSaveProfile() function (see "KcsSaveProfile() "). KcsLoadProfile() takes the three arguments listed below. KcsSaveProfile() takes the first two arguments listed.

A profile identifier (Id)
A profile description
Hints about loading the profile

The profile Id is returned to the calling program from KcsLoadProfile() for use with other API functions. In the case of KcsSaveProfile(), the profile identifier is passed back into the KCMS framework library to indicate the profile to be saved.

The profile description is a union of many different types, each of which represents a way to supply a location where the profile data should be stored. The type and the associated fields in the union are required to complete a profile description. The type field indicates which of the union's fields to use.

A calling application can request that the KCMS framework load only specific parts of a profile, (for example, just its attributes). The caller uses the KcsModifyLoadHints() function to provide these load hints, which change the load status of the profile. Hints are described by the KcsLoadHints data type discussed on "KcsLoadHints ". Load hints that request specific operations and specific content be loaded for a profile are described in "Operation Hints".

Example: Using Profiles to Convert Color Data

Figure 2-1 shows how color data is converted between a scanner device and a monitor device.

Figure 2-1 Converting Color Data From a Scanner to a Monitor

In the figure, the devices do not perform their own color correction. Rather, the color data is converted from the form provided by the scanner (Scanner DCP) to a form appropriate for display on the monitor (Monitor DCP). To convert the color data, your application would follow the steps below:

Load the scanner and monitor profiles.

See "Loading Scanner and Monitor Profiles".
Connect the scanner profile to the monitor profile to get a complete profile.

See "Connecting Scanner to Monitor Profiles".
Evaluate color data through the complete profile.

See "Evaluating Color Data Through the Complete Profile".

Example 2-1 shows the sequence of calls that perform this conversion. For more information on the KcsConnectProfiles() function, see "Using Color Space Profiles" and the detailed function description on "KcsConnectProfiles() ".

Example 2-1 Simple Color Data Conversion

/* Load the scanner's DCP.*/
 KcsLoadProfile(&inProfile, &scannerDescription, KcsLoadAllNow);

 /* Load the monitor's DCP. */
 KcsLoadProfile(&outProfile, &monitorDescription, KcsLoadAllNow);

 /* Connect two DCPs to form a CCP */
 profileSequence[0] = inProfile;
 profileSequence[1] = outProfile;
 KcsConnectProfiles(&completeProfile, 2, profileSequence,
 		KcsLoadAllNow, &failedProfileIndex);

 /* Apply the CCP to input color data. */
 KcsEvaluate(completeProfile, KcsOperationForward, &inbufLayout,
 		&outbufLayout);

Loading Scanner and Monitor Profiles

As shown in Example 2-1, the first color-conversion step is to use the KcsLoadProfile()function. KcsLoadProfile() loads the profile associated with a specific device, effect, partial, or complete profile, and it allocates any system resources the profile requires. For a detailed description of KcsLoadProfile() , see "KcsConnectProfiles() ".

Connecting Scanner to Monitor Profiles

As shown in Example 2-1 and Figure 2-2, the next color-conversion step is to connect a pair of DCPs to form a CCP. KcsConnectProfiles() provides this functionality. Continuing with the example illustrated in Figure 2-1, a CCP is built by connecting the scanner's DCP to the monitor's DCP. The resulting CCP converts scanner data to monitor data.

Figure 2-2 Building a CCP From Two DCPs

Evaluating Color Data Through the Complete Profile

The final color-conversion step is to use the KcsEvaluate() function. KcsEvaluate() applies a color transformation based on the supplied CCP. One of the following operations is associated with the evaluation. These operations are illustrated in Figure 2-3.

OpForward
OpReverse
OpSimulate
OpGamutTest

Figure 2-3 Profile Load Hint Operations

`OpForward`

The forward operation is used to transform color from the scanner form to the monitor form.

`OpReverse`

The reverse operation is used to transform color from the monitor form to the scanner form. This is useful if your application modifies some colors in monitor space, to keep the greatest number of colors that can be converted back and stored in the scanner's color space.

A more familiar use of the reverse operation is to transform the color from printer to monitor form to see what the data looks like from the printer.

`OpSimulate`

The simulate operation is used to simulate the effect of running color data through a CCP, but retaining it in the form of the last device profile. For example, the simulate operation can produce monitor data that simulates the result of printed data.

`OpGamutTest`

The gamut-test operation is used to determine if each color in the source data is within the gamut of the destination device. Physical devices have a range of colors they can produce. This range of colors is known as the gamut of the device.

Using A Callback Function When Evaluating

KcsEvaluate() can take a long time to execute, especially if the input image or graphic contains millions of pixels. Therefore, your application can provide a callback function using KcsSetCallback(), which KcsEvaluate() calls when necessary. The callback function can, for example, provide feedback to request that processing be cancelled. If the callback returns a non-KCS_SUCCESS status, the processing stops.

Associating Profiles with Devices

The KcsSaveProfile() function, when supplied a KcsProfileDesc structure, associates that color profile with the supplied structure. Typically, a configuration or calibration program calls the KcsSaveProfile()function. The profile associated with the KcsDescription structure represents the last calibrated condition of the device. For more information on KcsSaveProfile(), see "KcsSaveProfile() ".

Many events can change the condition of a device. For example, as room lighting changes, so does the viewer's perception of a monitor's colors. Or, consider a color printer. When different kinds of paper are used in the printer, the printer's color condition changes. As conditions change, a user may associate a different profile with the device.

Using Color Space Profiles

Another possible use of KcsConnectProfiles() is to connect a DCP and a CSP, creating a new CCP. Refer to Figure 2-1. If the scanner DCP in that figure is connected to the CSP (instead of the Monitor DCP shown that converts for the CIEXYZ color space), the resulting CCP will convert color data produced by the scanner into CIEXYZ format.

Example 2-2 shows the sequence of calls that creates and applies the CCP. Note that this example is very similar to Example 2-1. The difference is the second call to KcsLoadProfile(). In Code Example 2-2, KcsLoadProfile() loads the CIEXYZ profile description instead of the monitor description.

Example 2-2 Connecting a DCP and CSP

/*Load scanner's DCP. */
 KcsLoadProfile(&inProfile, &scannerDescription, KcsLoadAllNow);
 if(status != KCS_SUCCESS) {
 	status = KcsGetLastError(&errDesc);
 	KcsFreeProfile(profileid);
 	exit(1);
 }

 /*Load CSP for CIEXYZ color space. */
 KcsLoadProfile(&outProfile,&CIEXYZdescription, KcsLoadAllNow);
 if(status != KCS_SUCCESS) {
 	status = KcsGetLastError(&errDesc);
 	KcsFreeProfile(profileid);
 	exit(1);
 }

 /*Connect two profiles to form a CCP.*/
 profileSequence[0] = inProfile;
 profileSequence[1] = outProfile;
 KcsConnectProfiles(&completeProfile,2, profileSequence,
 		KcsLoadAllNow, &failedProfileIndex);
 if(status != KCS_SUCCESS) {
 	status = KcsGetLastError(&errDesc);
 	KcsFreeProfile(profileid);
 	exit(1);
 }

 /*Apply the CCP to input color data.*/
 KcsEvaluate(completeProfile, KcsOperationForward,
 		&inbufLayout, &outbufLayout);