Legacy Document

Inside Macintosh: Advanced Color Imaging on the Mac OS /

Chapter 7 - Color Manager / Using the Color Manager

Managing the Device CLUT

The Color Manager functions that directly modify a device CLUT should be used with care, because in a multitasking environment, changes to a device CLUT affect colors used by the system software and other application windows.

Note

The Color Manager functions described next are designed to operate on a single GDevice data structure. The Palette Manager can perform most of these operations across multiple GDevice data structures. Since the Palette Manager provides more general and portable functionality, applications should use Palette Manager functions whenever possible.

Use the SetEntries function to change any of the entries in a device's CLUT. SetEntries changes the CTSeed field value, so the Color Manager knows to rebuild the inverse table.

The SaveEntries and RestoreEntries functions can make temporary changes to the color table under very specialized circumstances (for example, from a color selection dialog box within an application). Applications don't need these functions under normal circumstances. For example, if you use the Palette Manager functions GetEntryColor and SetEntryColor on a palette, rather than directly changing a device's color table, the Palette Manager ensures that colors used by other applications and the system are not affected.

You can use the SaveEntries function to copy any combination of ColorSpec data structures into a color table. RestoreEntries replaces the table created by SaveEntries in the graphics device. Unlike SetEntries, these functions don't perform invalidations of the device's color table, so they avoid causing invalidations of cached data structures. If you use these functions, your application must take responsibility for rebuilding and restoring auxiliary structures as necessary.

By convention, when using SetEntries or RestoreEntries, you should store white at color table position 0, and black in the last color table position available, whether it is 1, 3, 15, or 255. The Palette Manager also enforces this convention. The most commonly found CLUT contains 256 entries, but a 4-entry CLUT can illustrate setting entry values more concisely. Here's a CSpecArray data structure called MyColors containing four RGB color values:

Table 7-2 A sample CSpecArray data structure

Value	Red	Green	Blue
0	FFFF	FFFF	FFFF
1	FFFF	0000	0000
2	8888	8888	8888
3	0000	0000	0000

Then you could use the SetEntries function to fill the four entries of the CLUT starting at 0 with white at the first entry, a bright red at the second, a gray at the third, and black at the last entry:

SetEntries(0, 4, MyColors);

Color Manager functions maintain special information in device color tables. Using the ProtectEntry and ReserveEntry functions, an entry may be protected, which prevents SetEntries from further changing the entry, or reserved, which makes the entry unavailable to be mapped by the RGBForeColor and RGBBackColor functions. Functions that change the device table (SetEntries, ProtectEntry, and ReserveEntry, but not RestoreEntries) perform the appropriate invalidations of QuickDraw data structures. Your application must then redraw where necessary.

Use the RealColor function to determine whether a particular color exists in a color table. RealColor determines whether any color in the CLUT for the current GDevice data structure matches the given color to the resolution of the device's inverse table. For example, if the device's inverse table is set to a resolution of 4 (the default), RealColor returns true if any color in the CLUT exactly matches the top four bits of each component. You could make RealColor match to the top 5 bits by rebuilding the inverse table: call MakeITable with a res parameter value of 5.

The Color2Index function returns the index in the current device's CLUT that is the best match to the requested color. The Index2Color function performs the opposite function--it returns the color of a particular index value. These functions can be useful when making copies of the screen frame buffer. Use the GetSubTable function to obtain a set of indexes for a CLUT; it calls the Color2Index function for each input color.