PATHDocumentation > Mac OS 8 and 9 > Mutlimedia and Graphics > ColorSync Manager >

Managing Color With ColorSync


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.

Opening a Profile and Obtaining a Reference to It

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 the CMGetProfileLocation 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;
}

Reference Counts for Profile References

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.


© 1988-1999 Apple Computer, Inc. — (Last Updated 20 Jan 99)