Legacy Document

Inside Macintosh: Advanced Color Imaging on the Mac OS /

Chapter 7 - Color Manager / Using the Color Manager

Customizing Search Functions

Specialized color applications may need to modify the way in which the Color Manager determines the best-mapping color in a CLUT. A custom search function you provide can implement its own mapping rules. For instance, a color-selection application might want to map all levels of green to a single green on a monitor.

To do this, you write your own color search function and use the AddSearch function to install it in the list of search functions that the Color Manager maintains. Then when your application or Color QuickDraw calls the Color2Index function, the Color Manager calls on your search function to find and return the index for the best-mapping color. Your function should be defined as:

Boolean MySearchProc (RGBColor *rgb, long *position);

If your search function decides to act on the color, it returns the index of the desired color in the position parameter, and returns true for the function value. Otherwise, it should return false as the function value, and pass the input color back to the Color Manager in the rgb parameter. The Color Manager then looks to the next search function in the list, and if there are no other custom functions it uses the normal inverse table mechanism.

The functions are chain elements in a linked list beginning in the gdSearchProc field of the current GDevice data structure. Each link is an SProcRec data structure, which has the format shown below.

struct SProcRec {
   Handle         nxtSrch; /* handle to next sProcRec */
   ColorSearchProcPtrsrchProc;/* pointer to search function */
};
typedef struct SProcRec SProcRec;

The Color Manager provides functions to add and delete custom functions from the linked list. You can install any number of search functions in the list. The Color Manager gives each function the chance to act or pass on the color until one returns true. Since each device is a shared resource, you can use the SetClientID function to set the gdID field of the GDevice data structure to identify your application as the caller to your search functions. When your application is finished mapping colors, it should remove your custom search function, by calling the DelSearch function.

For example, Listing 7-1 shows a function that adds a custom search function before drawing with a user-supplied color.

Listing 7-1 Adding and using a custom search function

void MyDrawUserColor(void)
{     
   ColorSearchProcPtrMyColorSearch;
   RGBColor       *UserColor;
   Rect           *sampleRect;

   AddSearch(MyColorSearch);
   RGBForeColor(UserColor);
   FrameRect(sampleRect);
   DelSearch(MyColorSearch);
}

The MyColorSearch function could entirely replace the Color Manager's search algorithm by accepting the RGBColor data structure, doing a search, and then returning the index value and true. It could also merely modify the color and then let the Color Manager perform its inverse table lookup. For example, the MyColorSearch function could accept the RGBColor, do an arithmetic add with a gray color to lighten all three components, and then return the RGBColor data structure in the rgb VAR parameter and return false as the function value. The Color Manager then uses the returned color as the input for its default search.