![]() |
PATH![]() |
![]() ![]() |
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.
To open a
profile and obtain a reference to it, you call the function
CMOpenProfile
. You can also obtain a profile reference from the
CMCopyProfile
,
CWNewLinkProfile
, and
CMNewProfile
functions. To identify a profile that is file based, memory based, or accessed through a procedure, you must give its location.
The ColorSync Manager defines the
CMProfileLocation
data type to specify a profile's location:
struct CMProfileLocation {
short locType; /* specifies the location type */
CMProfLoc u; /* structure for specified type */
};
The
CMProfileLocation
structure contains the u field of type
CMProfLoc
. The
CMProfLoc
type is a union that can provide access to any of the structures
CMFileLocation
,
CMHandleLocation
,
CMPtrLocation
, or
CMProcedureLocation
.
The data you specify in the u field indicates the actual location of the profile. In most cases, a ColorSync profile is stored in a disk file and you use the union for a file specification. However, a profile can also be located in memory, or in an arbitrary location (such as a resource) that is accessed through a procedure provided by your application. For more information on profile access, see Accessing a Resource-Based Profile With a Procedure . In addition, you can specify that a profile is temporary, meaning that it will not persist in memory after your application uses it for a color session.
To identify the data type in the u field of the CMProfileLocation structure, you assign to the CMProfileLocation.locType field one of the constants or numeric equivalents defined by the following enumeration:
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 */
};
For example, for a file-based profile, the
u
field would hold a file specification and the
locType
field would hold the constant
cmFileBasedProfile
. Your application passes a
CMProfileLocation
structure when it calls the
CMOpenProfile
function and the function returns a reference to the specified profile.
Note
If you already have a profile reference for a profile, you can call the
NCMGetProfileLocation
function (available starting in ColorSync 2.5) or theCMGetProfileLocation
function (for previous versions of ColorSync) to obtain the location for the profile.
Listing 3-2 shows an application-defined function, MyOpenProfileFSSpec , that assigns the file specification for a profile file to the profLoc union and identifies the location type as file-based. It then calls the CMOpenProfile function, passing to it the profile's file specification and receiving in return a reference to the profile.
Listing 3-2 Opening a reference to a file-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;
}
The ColorSync Manager keeps an internal reference count for each profile reference returned from a call to the
CMOpenProfile
,
CMCopyProfile
,
CMNewProfile
, or
CWNewLinkProfile
functions. Calling the
CMCloneProfileRef
function increments the count; calling the
CMCloseProfile
function decrements it. When the count reaches 0, the ColorSync Manager releases all private memory, files, or resources allocated in association with that profile. The profile remains open as long as the reference count is greater than 0, indicating that at least one task retains a reference to the profile. You can determine the current reference count for a profile reference by calling the
CMGetProfileRefCount
function.
When your application passes a copy of a profile reference to an independent task, whether synchronous or asynchronous, the task should call CMCloneProfileRef to increment the reference count. Both the called task and the caller should call CMCloseProfile when finished with the profile reference. This ensures that the tasks can finish independently of each other.
IMPORTANT
You call CMCloneProfileRef after copying a profile reference but not after duplicating an entire profile (as with the CMCopyProfile function).
When your application passes a copy of a profile reference internally, it may not need to call CMCloneProfileRef, as long as the application calls CMCloseProfile once and only once for the profile.
IMPORTANT
In your application, make sure that CMCloseProfile is called once for each time a profile reference is created or cloned. Otherwise, the private memory and resources associated with the profile reference may not be properly freed, or a task may attempt to use a profile reference that is no longer valid.