One of the goals of QuickDraw is to isolate the application from the specific graphic
display devices it is running on. The Palette Manager lets multiple applications share
screen space and color allocation in a fair and orderly fashion.
The Palette Manager has been enhanced in 32-Bit QuickDraw to support new color
usages. When applications use the Palette Manager to establish and maintain a specific
color environment, the Palette Manager juggles numerous factors in honoring a
request. It must consider, for example, the limits of the available display hardware
and the presence of other applications requesting color environments. On a
multiple-screen system, the Palette Manager will keep track of the colors for each
screen. Also, the Palette Manager provides an extra level of indirection in drawing
colors, which serves as a color naming or numbering system.
A palette is a data structure attached to a window using the SetPalette system call or
other means. The palette, which contains a list of colors, each with a usage value and a
tolerance value, lets the system know what colors that window needs. When colors are
changed, the Palette Manager makes sure that windows, the menu bar, and the desktop
are redrawn as needed with the new colors.
The Palette Manager calls should be used any time you might be tempted to call the
Color Manager routines SetEntries or RestoreEntries. These calls modify the color
environment directly, without letting the system decide which colors would be best to
change. Also, they operate on a single screen. SetEntries or RestoreEntries should only
be called by programs that have no intention of sharing the screen--programs like
lava-lamp screen-savers and programs that will never, ever run under MultiFinder.
Most commercial software does not fall in this category and absolutely should not call
SetEntries and RestoreEntries. Use the Palette Manager to modify the color
environment to get a better application with less work.
Suppose we are writing a program to display PICTs on a four or more bit-depth
screen. The built-in color table for four bits ('clut' ;ID 4, in ROM resources)
contains a smattering of different colors. If the PICT we wish to display contains only
shades of red, we'd want to have as many shades of red as possible (14 on a four-bit
screen) in the screen's 'clut'. There are actually 16 different colors available, but 2
of them, black and white, are never changed. This guarantees that menus, windows, and
other such things that are always black on the Macintosh will be visible in their
intended colors.
To get some shades of red on the screen, we create a palette with 14 entries, each with
a different shade of red in it. We set the usage of each entry to pmTolerant. When the
palette's window is activated, the Palette Manager will look for shades of red that are
within a certain range, or within tolerance, of each palette entry. If an index in the
screen's 'clut' is already within range of one of the entries, then the Palette Manager
will use that index. If not, the Palette Manager will steal an index in the order
specified by its color arbitration rules and change it to the requested color.
Here is how we generate the sample palette:
FUNCTION Make14RedPalette: PaletteHandle;
VAR
i: LONGINT;
ph: PaletteHandle;
c: RGBColor;
BEGIN
ph := NewPalette(14,NIL,pmTolerant,4000);
(* should check for NIL result *)
c.green := 0;
c.blue := 0;
FOR i:=0 TO 13
DO
BEGIN
(* range red component from 1/14 to 14/14 *)
(* i is a longint, and so can safely be multiplied by 65535 *)
c.red := (i+1)*65535 DIV 14;
SetEntryColor(ph,i,c);
END;
Make14RedPalette := ph;
END;
Next, we might attach it to our window:
myPalette := Make14RedPalette; SetPalette(myWindow,myPalette);
Whenever this window is brought to the front, the Palette Manager will attempt to
provide 14 shades of red, ranging from RGB(4681,0,0) to RGB(65535,0,0). We
might consider RGB(0,0,0), black, which is always available, to be a 15th shade of
red. To draw in these colors, we just make the normal Color QuickDraw calls (like
RGBForeColor), and we'll automatically get the closest shade of red available. If, after
setting up this palette, we try to draw in nonred colors, the results will not be pretty.
With black, white, and 14 shades of red, the available options for a good match to
green, for example, are severely limited.
In the preceding example, we assumed the PICT uses shades of red. This is generally
hard to determine, unless we generate the PICT in the first place. Since the PICT is in
reds, we might want to load the palette from a resource with GetNewPalette rather
than compute it in code. Or, we might happen to have a color table with the colors we
need. In that case, we could have passed it to NewPalette, instead of nil in the example,
or to CTab2Palette, if we already had a palette allocated.
We've just described how a program can ensure that a set of colors is available for a
specific graphic display. The well-mannered programmer may be thinking, "Gee,
that's swell, but how do I give those colors back when I'm done?" The answer is, don't
even try. Any other window that needs colors to look good will have its own palette
attached, and therefore get the colors it needs. Also, each time a program quits, the
Palette Manager restores the color environment to a well-balanced state in terms of
color distribution.
Different types of screens often require different color sets to best display the same
image. Grayscale screens default to having a range of gray tones from black to white,
which is an excellent range for drawing most images. A grayscale screen should
usually be left with its default color table. Here is the sample routine modified to
provide 14 shades of red on a four-bit color screen, 254 shades on an eight-bit color
screen, and no color requests at all on two-bit or grayscale screens:
FUNCTION MakeRedPalette: PaletteHandle;
VAR
i: LONGINT;
ph: PaletteHandle;
c: RGBColor;
BEGIN
ph := NewPalette(14+254,NIL,0,0);
(* should check for NIL result *)
c.green := 0;
c.blue := 0;
(* Make fourteen reds that are inhibited on all *)
(* screens except four-bit color *)
FOR i:=0 TO 13
DO
BEGIN
(* range red component from 1/14 to 14/14 *)
(* i is a longint, and so can safely be multiplied by 65535 *)
c.red := (i+1)*65535 DIV 14;
SetEntryColor(ph,i,c);
SetEntryUsage(ph,i,pmTolerant+pmInhibitC2+
pmInhibitG2+pmInhibitG4+
pmInhibitC8+pmInhibitG8,4000);
END;
(* Make 254 reds that are inhibited on all *)
(* screens except eight-bit color *)
FOR i:=0 TO 253
DO
BEGIN
(* range red component from 1/254 to 254/254 *)
(* i is a longint, and so can safely be multiplied by 65535 *)
c.red := (i+1)*65535 DIV 254;
SetEntryColor(ph,14+i,c);
SetEntryUsage(ph,14+i,pmTolerant+pmInhibitC2+
pmInhibitG2+pmInhibitG4+
pmInhibitC4+pmInhibitG8,0);
END;
MakeRedPalette := ph;
END;
So far, we've seen how to request a set of colors from the Palette Manager. The
examples use colors with usage combinations of pmTolerant, and various inhibit bits.
Other ways to request colors are explained in Inside Macintosh, volume V, page 154.
In addition, combinations of pmExplicit and pmTolerant or pmAnimated are now
supported. Here are some examples of different usages.
SetEntryUsage(ph,1,pmCourteous,0);
The color is courteous, activating the palette will never cause a change in a screen's
color table. This is useful only for "naming" the color, in this case to 1.
PmForeColor(1) and PmBackColor(1) are two ways to use this color.
SetEntryUsage(ph,2,pmTolerant,10000);
The color is tolerant, activating the palette will ensure that some index in the screen's
color table is within 10000 in each RGB component from palette entry 2.
SetEntryUsage(ph,3,pmAnimated,0);
The color is animated, activating the palette will reserve an index from the screen's
color table to be owned by this palette (if the screen is indexed). If the color is
changed with AnimateEntry then any previous drawing done with that entry will
change.
SetEntryUsage(ph,4,pmExplicit,0);
The color is explicit, any drawing done with this entry will draw in device index 4,
because this entry is the 4th color in the palette. This is mostly useful for monitoring
the color environment.
SetEntryUsage(ph,5,pmExplicit+pmTolerant,0);
The color is both explicit and tolerant. Activating the palette will ensure that device
index 5 exactly matches the palette's color 5 (because the tolerance here is 0).
SetEntryUsage(ph,6,pmExplicit+pmAnimated,0);
The color is both explicit and animated. Activating the palette will reserve screen
index 6 for this palette's use. The color may be modified with AnimateEntry and
AnimatePalette.
SetEntryUsage(ph,7,pmAnimated+pmInhibitC8+pmInhibitG8,0);
The color is animated on any screen other than an 8-bit color or an 8-bit gray- scale
device. On those devices, the color behaves as a courteous color.
After the palette has been set up, there are several ways to draw with the colors in the
palette. In addition to PmForeColor and PmBackColor, a pixMap or pixPat color table
may be specified to point to palette entries. To do this, set bit 14 in the ctFlags field of
the color table (ctFlags is called transindex in older equate files). Then set the desired
palette entry numbers in the value field of each colorSpec. The color table is then
assumed to be sequential, as device tables are (colorSpec 0 refers to pixel value 0 in
the pixMap or pixPat; color value 1 refers to pixel value 1, and so on).
This code retrieves a copy of the desktop pattern (system resource 'ppat' 16) and
modifies its fields to refer to sequential palette entries.
myPP: PixPatHandle;
myCT: CTabHandle;
myPP := GetPixPat(16);
(* Gets the system color desktop pattern *)
myCT := myPP^^.patMap^^.pmTable
FOR j := 0 TO myCT^^.ctSize
(* Set .value field equal to position for each element *)
DO
myCT^^.ctTable[j].value := j;
myCT^^.ctFlags := BitOr(myCT^^.ctFlags,$4000);
(* .ctFlags aka .transindex *)
Drawing the unmodified ppat 16 would produce it exactly as it appears on the desktop.
After the modification, drawing with myPP would produce the same pattern with the
colors replaced by palette colors.
One use for this might be to draw a pixMap with all animated colors, and then let the
user adjust color, brightness, and contrast with slider controls. The color changes
would be performed with AnimatePalette calls.
Several new 'clut's have been defined for 32-Bit QuickDraw and may be accessed with
the GetCTable routine. As before, 'clut' IDs 1, 2, 4, and 8 are the standard color tables
for those depths. A gray ramp for each depth can be requested using the depth plus 32.
'Clut' IDs for gray ramps with depths 1,2,4, and 8 are 33, 34, 36, and 40
respectively.
'clut's 2 and 4 are modified to include the highlight color and may be accessed as the
depth plus 64.
'clut's may not exist as actual resources; the GetCTable routine may synthesize them
when they are requested. If there is a 'clut' resource with the specified ID, however,
GetCTable will load that resource and return a detached handle to it. So to dispose of the
handle, you should call DisposCTable rather than release resource. *
David Van Brink, graphics software engineer, graduated from the University of
California-Irvine in 1986 with a BSICS (you figure it out!) degree. After working in
southern California for MegaGraphics, he moved north to work for Apple. Despite the
fact that sleeping on the job is his professed favorite part of working here, he does
seem to find time to write some awesome software. When he's not sleeping his days
away at Apple, he dabbles in computer-aided music and writes his own music
sequencing software. Other activities he enjoys: recreating Philip K. Dick scenarios
with friends; watching Star Trek while eating Kraft® Macaroni And Cheese; and
encouraging his parrot named "12" to teach his rat "X" to talk. And always
remember....*
Color Arbitration; Color look-up table ('clut') displays, like the Macintosh II
Video Card, have a certain number of colors available at each bit-depth. Different
applications, and different documents within an application, use the colors in different
ways. For example, a full-color digitized photograph isn't usually meant to be
displayed in various tones of brown. If there aren't enough colors to go around, the
Palette Manager arbitrates. When a window with a palette comes to the front, the
Palette Manager inspects the window's palette and tries to modify the screen's color
table to best satisfy the palette. (If a window without a palette comes to the front, no
change occurs.) When another window is activated and comes to the front, the Palette
Manager inspects its palette and modifies the colors, taking colors used by previous
windows last. *