Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

Chapter 5 - Color Manager Reference /

Color Manager Functions / Managing Color Tables

SetEntries

Sets a group of color table entries for the current GDevice data structure.

pascal void SetEntries (
short start, 
short count, 
cSpecArray aTable);

start

The index of the first entry to be changed.

count

The number of entries to be changed.

aTable

An array of ColorSpec data structures containing the colors to be used.

DISCUSSION

The SetEntries function sets a group of color table entries for the current GDevice data structure, starting at a given position for the specified number of entries. Use the aTable parameter to directly specify a cSpecArray structure, not the beginning of a color table. The ColorSpec.value fields of the entries must be in the logical range for the target device's assigned pixel depth. Thus, with a 4-bit pixel size, the ColorSpec.value fields should be in the range 1 to 15. With an 8-bit pixel size, the range is 0 to 255. Note that all values are zero-based; for example, to set three entries, pass 2 in the count parameter.

WARNING

Instead of using SetEntries, you should use the Palette Manager function SetEntryColor to allow your application to run in a multiscreen or multitasking environment.<8batcolor>s

The SetEntries positional information works in logical space rather than in the actual memory space used by the hardware. Requesting a change at the fourth position in the color table may not modify the fourth color table entry in the hardware, but it does correctly change the color on the screen for any pixels with a value of 4 in the video card. The SetEntries mode characterized by a start position and a length is called sequence mode. In this case, SetEntries sequentially loads new colors into the hardware in the same order as they appear in the aTable parameter, copies the clientID fields for changed color table entries from the current GDevice data structure's gdID field, and ignores the ColorSpec.value fields.

The other SetEntries mode is called index mode. It allows the cSpecArray structure to specify where the data will be installed on an entry-by-entry basis. To use this mode, pass -1 for the start position, with a valid count and a pointer to the cSpecArray data structure. Each entry is installed into the color table at the position specified by the ColorSpec.value field of each entry in the cSpecArray data structure. In the current GDevice data structure's color table, the ColorSpec.value fields of all changed entries are assigned the GDevice data structure's gdID value.

When the Color Manager changes color table entries, it invalidates all cached fonts, and changes the color tables's seed number so that the next drawing operation triggers the Color Manager to rebuild the inverse table. If any of the requested entries are protected or out of range, the Color Manager returns a protection error, and nothing happens. The Color Manager changes a reserved entry only if the current gdID field of the current GDevice data structure matches the low byte of the intended ColorSpec.value field in the color table.