TweetFollow Us on Twitter

All About The Palette Manager

ALL ABOUT THE PALETTE MANAGER

DAVID VAN BRINK

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.

UNDERSTANDING THE PALETTE MANAGER

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.

SELECTING THE RIGHT COLOR SET

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;

MORE WAYS OF REQUESTING COLOR

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.

DRAWING WITH PALETTE COLORS

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.

ACCESSING NEW COLOR LOOK-UP TABLES

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. *
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Latest Forum Discussions

See All

Six fantastic ways to spend National Vid...
As if anyone needed an excuse to play games today, I am about to give you one: it is National Video Games Day. A day for us to play games, like we no doubt do every day. Let’s not look a gift horse in the mouth. Instead, feast your eyes on this... | Read more »
Old School RuneScape players turn out in...
The sheer leap in technological advancements in our lifetime has been mind-blowing. We went from Commodore 64s to VR glasses in what feels like a heartbeat, but more importantly, the internet. It can be a dark mess, but it also brought hundreds of... | Read more »
Today's Best Mobile Game Discounts...
Every day, we pick out a curated list of the best mobile discounts on the App Store and post them here. This list won't be comprehensive, but it every game on it is recommended. Feel free to check out the coverage we did on them in the links below... | Read more »
Nintendo and The Pokémon Company's...
Unless you have been living under a rock, you know that Nintendo has been locked in an epic battle with Pocketpair, creator of the obvious Pokémon rip-off Palworld. Nintendo often resorts to legal retaliation at the drop of a hat, but it seems this... | Read more »
Apple exclusive mobile games don’t make...
If you are a gamer on phones, no doubt you have been as distressed as I am on one huge sticking point: exclusivity. For years, Xbox and PlayStation have done battle, and before this was the Sega Genesis and the Nintendo NES. On console, it makes... | Read more »
Regionally exclusive events make no sens...
Last week, over on our sister site AppSpy, I babbled excitedly about the Pokémon GO Safari Days event. You can get nine Eevees with an explorer hat per day. Or, can you? Specifically, you, reader. Do you have the time or funds to possibly fly for... | Read more »
As Jon Bellamy defends his choice to can...
Back in March, Jagex announced the appointment of a new CEO, Jon Bellamy. Mr Bellamy then decided to almost immediately paint a huge target on his back by cancelling the Runescapes Pride event. This led to widespread condemnation about his perceived... | Read more »
Marvel Contest of Champions adds two mor...
When I saw the latest two Marvel Contest of Champions characters, I scoffed. Mr Knight and Silver Samurai, thought I, they are running out of good choices. Then I realised no, I was being far too cynical. This is one of the things that games do best... | Read more »
Grass is green, and water is wet: Pokémo...
It must be a day that ends in Y, because Pokémon Trading Card Game Pocket has kicked off its Zoroark Drop Event. Here you can get a promo version of another card, and look forward to the next Wonder Pick Event and the next Mass Outbreak that will be... | Read more »
Enter the Gungeon review
It took me a minute to get around to reviewing this game for a couple of very good reasons. The first is that Enter the Gungeon's style of roguelike bullet-hell action is teetering on the edge of being straight-up malicious, which made getting... | Read more »

Price Scanner via MacPrices.net

Take $150 off every Apple 11-inch M3 iPad Air
Amazon is offering a $150 discount on 11-inch M3 WiFi iPad Airs right now. Shipping is free: – 11″ 128GB M3 WiFi iPad Air: $449, $150 off – 11″ 256GB M3 WiFi iPad Air: $549, $150 off – 11″ 512GB M3... Read more
Apple iPad minis back on sale for $100 off MS...
Amazon is offering $100 discounts (up to 20% off) on Apple’s newest 2024 WiFi iPad minis, each with free shipping. These are the lowest prices available for new minis among the Apple retailers we... Read more
Apple’s 16-inch M4 Max MacBook Pros are on sa...
Amazon has 16-inch M4 Max MacBook Pros (Silver and Black colors) on sale for up to $410 off Apple’s MSRP right now. Shipping is free. Be sure to select Amazon as the seller, rather than a third-party... Read more
Red Pocket Mobile is offering a $150 rebate o...
Red Pocket Mobile has new Apple iPhone 17’s on sale for $150 off MSRP when you switch and open up a new line of service. Red Pocket Mobile is a nationwide MVNO using all the major wireless carrier... Read more
Switch to Verizon, and get any iPhone 16 for...
With yesterday’s introduction of the new iPhone 17 models, Verizon responded by running “on us” promos across much of the iPhone 16 lineup: iPhone 16 and 16 Plus show as $0/mo for 36 months with bill... Read more
Here is a summary of the new features in Appl...
Apple’s September 2025 event introduced major updates across its most popular product lines, focusing on health, performance, and design breakthroughs. The AirPods Pro 3 now feature best-in-class... Read more
Apple’s Smartphone Lineup Could Use A Touch o...
COMMENTARY – Whatever happened to the old adage, “less is more”? Apple’s smartphone lineup. — which is due for its annual refresh either this month or next (possibly at an Apple Event on September 9... Read more
Take $50 off every 11th-generation A16 WiFi i...
Amazon has Apple’s 11th-generation A16 WiFi iPads in stock on sale for $50 off MSRP right now. Shipping is free: – 11″ 11th-generation 128GB WiFi iPads: $299 $50 off MSRP – 11″ 11th-generation 256GB... Read more
Sunday Sale: 14-inch M4 MacBook Pros for up t...
Don’t pay full price! Amazon has Apple’s 14-inch M4 MacBook Pros (Silver and Black colors) on sale for up to $220 off MSRP right now. Shipping is free. Be sure to select Amazon as the seller, rather... Read more
Mac mini with M4 Pro CPU back on sale for $12...
B&H Photo has Apple’s Mac mini with the M4 Pro CPU back on sale for $1259, $140 off MSRP. B&H offers free 1-2 day shipping to most US addresses: – Mac mini M4 Pro CPU (24GB/512GB): $1259, $... Read more

Jobs Board

All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.