Legacy Document

Inside Macintosh: Advanced Color Imaging on the Mac OS /

Chapter 4 - Developing ColorSync-Supportive Applications / Developing Your ColorSync-Supportive Application

Searching for a Profile That Matches a Profile Identifier

Embedding a profile in an image guarantees that the image can be rendered correctly on a different system. However, profiles can be large--the largest can be several hundred kilobytes or even larger. The ColorSync Manager defines a profile identifier structure, CMProfileIdentifier, that can identify a profile but that takes up much less space than a large profile.

The profile identifier structure contains a profile header, an optional calibration date, a profile description string length, and a variable-length profile description string. Your application might use an embedded profile identifier, for example, to change just the rendering intent or flag values in an image without having to embed an entire copy of a profile. For more information on the CMProfileIdentifier structure, including a description of how a match is determined between a profile reference and a profile identifier, see "Profile Identifier Structure" in Advanced Color Imaging Reference.

IMPORTANT

A document containing an embedded profile identifier cannot necessarily be ported to different systems or platforms.

The ColorSync Manager provides the NCMUseProfileComment routine to embed profiles and profile identifiers in an open picture file. For information on embedding, see "Embedding Profiles and Profile Identifiers" (page 4-32). Your application can embed profile identifiers in place of entire profiles, or in addition to them. A profile identifier can refer to an embedded profile or to a profile on disk.

The ColorSync Manager provides the CMProfileIdentifierListSearch routine for finding a profile identifier in a list of profile identifiers and the CMProfileIdentifierFolderSearch routine for finding a profile identifier in the ColorSyncTM Profiles folder.

When your application or device driver processes an image, it typically keeps a list of profile references for each profile it encounters in the image. Each time it encounters an embedded profile identifier, your application first calls the CMProfileIdentifierListSearch function to see if there is already a matching profile reference in its list. That function returns a list of profile references that match the profile identifier. Although the returned list would normally contain at most one reference, it is possible to have two or more matches. If the CMProfileIdentifierListSearch routine does not find a matching profile reference, your application calls the CMProfileIdentifierFolderSearch routine to see if a matching profile can be found in the ColorSyncTM Profiles folder.

Listing 4-24 demonstrates how your application can use ColorSync's search routines to obtain a profile reference for an embedded profile identifier. It uses the following structure to store a list of profile identifiers, along with a count of the number of items in the list.

typedef struct {
   long count;
   CMProfileRefprofs[1];
} ProfileCacheList, **ProfileCacheHandle;

Listing 4-24 Searching for a profile that matches a profile identifier

CMError MyFindAndOpenProfileByIdentifier( ProfileCacheHandle profCache,
                              CMProfileIdentifierPtr unique,
                              Boolean *pFoundInCache,
                              CMProfileRef *pProf)
{
   CMError     err = noErr;
   CMProfileRefprof = nil;
   long        cacheCount = (**profCache).count;
   unsigned longfoundCount = 0;
   
   *pFoundInCache = false;
   
   /* if there are any profile references in the cache (the list of profile */
   /* references for profiles or profile identifiers we have already */
   /* encountered) look there for a match with the passed profile identifier */
   if (cacheCount)
   {
      CMProfileRef *cacheList;
      
      cacheList = (**profCache).profs;
      foundCount = 1;/* return no more than one match */
      err = CMProfileIdentifierListSearch(unique, cacheList, cacheCount,
                                 &foundCount, &prof);
      if (foundCount && !err)
         *pFoundInCache = true;
      else
         prof = nil;
   }
   
   /* if we didn't find a match for the passed profile identifier in the list of */
   /* previously encountered profiles, look for a match on disk, in the */
   /* ColorSync(TM) Profiles folder */
   if (!prof)
   {
      CMProfileSearchRef search = nil;
      foundCount = 0;
      
      err = CMProfileIdentifierFolderSearch(unique, &foundCount, &search);
      /* if we found one or more matches, obtain a profile reference for the */
      /* first matching profile; */
      /* if no error, dispose of the search result */
      if (!err)
      {
         if (foundCount)
            err = CMSearchGetIndProfile(search, 1, &prof);
         CMDisposeProfileSearch(search);
      }
   }
   
   /* if we still didn't find a match for the passed profile identifier, */
   /* use the system profile */
   if (!prof)
   {
      err = CMGetSystemProfile(&prof);
   }
   
   if (err)
      prof = nil;
   *pProf = prof;
   return err;
}

Although typically there is at most one profile reference in your application's list or one profile in the ColorSyncTM Profiles folder that matches the searched-for profile identifier, it is possible that two or more profiles may qualify. It is not an error condition if either the CMProfileIdentifierListSearch or the CMProfileIdentifierFolderSearch routine finds no matching profile.