TweetFollow Us on Twitter

Graphical Truffles - The Palette Manager Way

Graphical Truffles

The Palette Manager Way

Edgar Lee And Forrest Tanaka

No part of the Macintosh graphics environment is more feared, hated, or misunderstood than the Palette Manager. The Developer Support Center gets many questions about it from people who don't have any idea how to get it to do what they want. We've seen many people just give up on the Palette Manager completely and instead use lower-level routines that are much more difficult to use but easier to understand quickly.

The Palette Manager is actually very simple. It has no complicated heuristics that only rocket scientists can understand. In this column, we'll show how the Palette Manager gets its job done, and we'll talk about a couple of issues that you'll have to deal with to make your palettes do what you want them to do. You'll see that the Palette Manager is both easy to understand and a very useful part of the Macintosh Toolbox.

Before you read this column, it would be a good idea to read the Palette Manager chapter (Chapter 20) ofInside MacintoshVolume VI, which lays down the terminology that we'll use here.

The critical job that the Palette Manager does is activate a palette. This happens whenever you call SetPalette or ActivatePalette for the frontmost window and whenever a window that has a palette is activated. When a palette is activated, the Palette Manager loads the palette colors into the screen's color table. How it goes about doing this is determined by the usage mode of each entry in the palette.

You indicate an entry's usage mode by setting a flag in its usage field. There are four usage modes: pmCourteous, pmTolerant, pmAnimated, and pmExplicit. You can choose a separate usage mode or combination of usage modes for each entry in a palette, or you can give all the entries the same usage mode. Let's take a look at what each usage mode is good for and what effect each one has when a palette is activated.

pmCourteous. The pmCourteous usage mode enables you to replace RGBColor records in your code with single integers. Thus, having a palette of courteous colors gives you an alternative way to specify foreground and background colors. This is great for localizers who might need to change the colors in your program to something more meaningful in other countries, and it's great for you if you feel like changing a color without recompiling.

Activating a palette of courteous colors simply tells the Palette Manager to use your window's palette as a sort of lookup table. When your window is the current port and you call PmForeColor or PmBackColor with a palette index, the Palette Manager simply retrieves the color in your window's palette at that index and uses it for any subsequent drawing to that window. Courteous colors never change the screen's color table -- they get mapped to the closest colors already available there.

Here's an example: Without the Palette Manager, you would draw a green oval in a window by setting up an RGBColor record with a red component of 0, a green component of 65,535, and a blue component of 0 and passing this record to RGBForeColor; then you would call FrameOval. To change the oval to blue, you would modify your RGBColor record in your source code and recompile your program. Now, suppose instead you brought in the Palette Manager by setting up a palette resource (resource type 'pltt') that contained one courteous entry -- green -- with an index of 0. In your code, you would call PmForeColor(0) instead of RGBForeColor with green. When you called FrameOval, the oval would be drawn in green. To change the color to blue, you would just use ResEdit to modify the green entry in your 'pltt' resource to blue. So calling PmForeColor for a courteous palette entry is just like calling RGBForeColor, but instead of supplying the RGB components, you simply pass an index into the palette, where the index points to the color's RGB components (see Figure 1).

pmTolerant. The pmTolerant usage mode is used when you want to be sure that a specific set of colors is available to the screens that your window is on. It's a bummer to draw a rainbow in a window on a screen that another application has removed all the greens and yellows from. You need a palette of tolerant colors to assert your application's right to the colors it needs to display its images optimally. With such a palette, you can change the colors in a screen's color table to ones that you want.

Before we look at how a palette of tolerant colors is activated, realize that Color QuickDraw always wants white in the first entry of a screen's color table and black in the last. To enforce this rule, Color QuickDraw protects these two entries from being changed to other colors. That means a palette of tolerant colors can change all the colors of a screen's color table except two.

When a palette of tolerant colors is activated, the Palette Manager checks each entry in the palette and associates it with an entry in the screen's color table. Let's say we have a palette with three entries -- bright green, black, and dark yellow -- attached to a window on a 16-color screen. All three palette entries are tolerant, with a tolerance of 0. The Palette Manager does the following: 1. It checks the first entry in the palette, bright green, and searches the screen's color table for the same bright green. It finds that color near the middle of the color table, and so associates palette entry 0 with this existing bright green entry in the color table. 2. It searches the screen's color table for the second entry in the palette, black. It finds it at the very end, so palette entry 1 corresponds to entry 15 of the color table. 3. It searches the screen's color table for dark yellow. There isn't one, so it chooses a color table entry to change to dark yellow. It can't choose the black or the white entry because they're protected and can't be changed, and it can't change the bright green entry because that entry is already associated with entry 0 of the palette. So it chooses one of the other color table entries and changes it to dark yellow.

[IMAGE Graphics_column_rev1.GIF]

Figure 1 Alternative Ways to Specify a Foreground Color

Because the color table has been changed, the Palette Manager makes sure that other windows are redrawn, just in case they were drawn using the color table entry that was changed to dark yellow. It does this by sending update events to all windows as soon as the palette is activated. If no color table changes were needed, the Palette Manager doesn't bother doing this.

Once our three-entry palette has been activated, we can call PmForeColor, passing it 0, 1, or 2 to draw objects in bright green, black, or dark yellow, respectively. In fact, we could call RGBForeColor, passing it bright green, black, or dark yellow RGBColor records, and they would use the same colors that our palette loaded into the screen's color table. Figure 1 applies to palettes of tolerant colors as well as palettes of courteous colors. If there are more palette entries than will fit in the screen's color table, the Palette Manager associates each palette entry with a color table entry until no more color table entries are available and then interprets the rest of the palette entries as courteous. For example, let's say a 20-entry palette is activated on a 16-color screen, where each palette entry is pmTolerant with a tolerance of 0 and neither black nor white is in the palette. Beginning with the first palette entry, the Palette Manager associates each entry with a color table entry. The 15th palette entry can't be associated with any color table entry because the black and white entries are protected from changes and all 14 other entries have already been associated with palette entries. So the 15th palette entry and all entries beyond it are simply treated as courteous colors.

pmAnimated. On indexed devices, the pmAnimated usage mode is used to do color table animation, which gives you smooth, fast visual effects simply by changing the colors in your screen's color table very quickly. You don't have to redraw anything to see this animation; you just use the Palette Manager to change the interpretation of the colors of your existing image. This is great for games and fast controls for image processing applications. On direct devices, animated entries are treated as courteous entries.

Like pmTolerant entries, each pmAnimated palette entry is associated with an entry in a screen's color table when the palette is activated, and the colors in the palette are put into the screen's color table. But changing color table entries for color animation changes everything on the screen that uses those same color table entries, like the desktop or window frames. That's usually not what we want, so the Palette Manager forces everything outside the window to be redrawn without the colors that are being used for color animation -- those colors are off limits. In fact, the only way to use those colors is to call PmForeColor or PmBackColor for an animated palette entry and then draw some QuickDraw object. Remember, the big difference between tolerant and animated colors is that color table entries that are used for tolerant colors can be used by anyone, but animated color table entries are used only by objects drawn in the palette's window after a call to PmForeColor or PmBackColor.

Let's use our three-entry palette as an example again, but this time assume that each entry is animated. The Palette Manager first takes the bright green entry, picks a color table entry on the screen, and changes it to bright green. It doesn't matter if there's already a bright green in the color table. As usual, the Palette Manager avoids the black and white entries at either end of the color table. It then picks another color table entry and puts black into it, and does the same for the dark yellow entry. If you call PmForeColor(0) and draw an object, it's drawn in bright green. But if you call RGBForeColor for bright green and draw an object, it doesn't use the bright green that's been defined as animated. Instead, it uses the closest color to bright green available, aside from any color table entries that have been defined as animated.

pmExplicit. The pmExplicit usage mode is rarely used alone, and there's not much to it beyond what's described in the Palette Manager chapter ofInside MacintoshVolume VI. We'll discuss in the next section the more interesting case of using pmExplicit along with the other usage modes.

When attaching a palette to a window, the Palette Manager works in a way that affects whether you should store black and white in the palette. We'll outline the way it works in two different categories. The first category applies to palettes containing the same number of entries as the screen's color table, and the second category applies to palettes containing fewer entries than the screen's color table.

Same number of entries in palette and color table. If the palette contains the same number of entries as the screen's color table, black and white should be stored in the palette. If these two entries aren't stored in the palette, the Palette Manager will ignore two entries in the palette when loading the palette colors into the screen's color table, to avoid overwriting the color table's black and white entries. The Palette Manager will decide which palette entries to ignore based on the usage field for each palette entry.

As an example, let's take the case of a palette all of whose entries are defined as pmTolerant + pmExplicit. Because the pmExplicit flag tells the Palette Manager to store each palette entry in its respective index in the screen's color table, the choice of which palette entry to ignore is fairly straightforward. The colors stored at the first and last entry of the palette correspond to the protected entries in the screen's color table, so these entries will be ignored.

In the case of a palette containing entries not defined with the pmExplicit flag set, the decision of which two palette colors to ignore can seem somewhat random. This is because the decision is based on the current distribution of the palette entries in the screen's color table, where the distribution is derived from the tolerance values of the palette entries and the existing colors in the screen's color table before the palette was activated.

For example, suppose we have a 16-entry palette and a 4-bit screen color table as shown in Figure 2 (we've used the default color table). Figure 3 shows how the screen's color table will look in two different cases when the palette of the frontmost window has been activated. In these figures, the explicit entries are distributed sequentially in the screen's color table, whereas the nonexplicit entries are scattered throughout the color table.

[IMAGE Graphics_column_rev2.GIF]

Figure 2 An Example Palette and Color Table

[IMAGE Graphics_column_rev3.GIF]

Figure 3 The Color Table With the Palette of the Frontmost Window Active

For the explicit entries, we see that the first and last entries of the palette are not loaded into the screen's color table, to protect the color table's white and black entries. However, for the nonexplicit entries, the two palette colors ignored aren't necessarily the first and last entries of the palette. When determining where the nonexplicit palette entries should be stored in the color table, the Palette Manager first checks to see which colors in the screen's color table already match those in the palette. If there's a match within the specified tolerance, that palette entry is stored at the index of the matching color in the screen's color table.

And one other thing: When multiple nonexplicit palette entries match (within the specified tolerance) the same color in the screen's color table, all those palette entries are stored at the same index in the color table. This means that only one slot in the color table is needed rather than as many slots as there are palette entries.

Fewer entries in the palette. Now, if the window's palette contains fewer entries than the screen's color table, the palette entries' usage field plays a large part in determining whether black and white should be included in the palette. The reason for this is similar to the previous case for nonexplicit entries.

[IMAGE Graphics_column_rev4.GIF] Figure 4 Another Example Palette and Color Table

[IMAGE Graphics_column_rev5.GIF]

Figure 5 The Color Table With the Palette of the Frontmost Window Active

If all the entries in a palette are defined without the pmExplicit flag set, the presence of black and white in the palette isn't as critical, since the palette entries will likely be scattered throughout the screen's color table while avoiding the protected white and black colors stored in the first and last slots of the screen's color table. Since there are fewer palette entries than color table entries, we needn't worry about palette entries getting ignored. So in this case, creating a palette without a black entry or a white entry is perfectly fine as long as there are enough slots in the screen's color table to hold all the palette entries and the two protected colors.

However, if the palette entries are all defined with the pmExplicit flag set, there's a good chance that one of the palette's entries will be ignored. And the palette entry that does get ignored will usually be the first entry in the palette, because this entry shares the same index as the protected white entry in the screen's color table.

For example, suppose we have a 192-entry palette and an 8-bit screen color table as shown in Figure 4 (again, we've used the default color table). Figure 5 shows how the screen's color table will look in two different cases when the palette of the frontmost window has been activated.

Again, the explicit entries are distributed sequentially in the screen's color table, starting with the first entry in the color table. Because the first entry in the screen's color table is protected from being overwritten, the first entry in the palette is ignored. But in the nonexplicit case, the entries are distributed somewhat differently. Depending on what colors are already in the screen's color table, the nonexplicit entries can be stored anywhere throughout the color table. And in this example, since there are clearly more slots in the screen's color table than needed by the palette entries, all the colors in the palette appear in the color table; none are ignored. So again in this case, including black and white in the palette really isn't necessary.

We've seen how the way the Palette Manager works can affect whether you decide to store black and white in your palette. In all the instances we mentioned, the positions of the black entry and white entry were always the same: white first and black last. However, in certain cases, you may not want to position white first and black last.

In the case where you'd like to create just one palette to handle devices at multiple bit depths, the black and white entries should be stored as the first two colors in the palette. This ensures that the two colors used on a 1-bit device are present. Likewise, to ensure that the optimal colors are used at depths 2, 4, and 8, we do the same thing for each additional depth. We store the preferred colors at the appropriate position in the palette. Figure 6 shows how a typical palette could be configured to handle multiple bit depths.

In our sample palette, the first 16 colors are defined as shades of gray, because we've decided our window would look best when displayed in grayscale on a 1-, 2-, or 4-bit device. For the 1-bit and 2- bit devices, we simply choose the appropriate shades for those depths and store them in the first four slots of our palette. But for an 8-bit device, we include as many colors as we can for the optimal display at that depth. For this example, we added the nongrayscale colors from the standard 8-bit color table to the remaining slots in our palette. Because the Palette Manager only uses the maximum number of colors it can (starting at the first index in the palette) for a specific bit depth, only the colors we want shown will be shown. Also, because the placement of the colors determines which colors are available at a certain depth, all the palette entries must be defined as explicit entries.

[IMAGE Graphics_column_rev6.GIF] Figure 6 A Palette Configured to Handle Multiple Bit Depths

Another way of ensuring that certain palette entries are available at certain depths is to apply the inhibit usage categories to the palette entries. These inhibit constants tell the Palette Manager which entries are available under the current color environment. Depending on which inhibit constant is used, the palette entries can be inhibited from a specific bit depth and from a color or grayscale device. So by combining various inhibit constants to our sample palette, we can inhibit the colors outside the current depth's range from being used. In our example, if entry number 16 were defined with

pmInhibitC2 + pmInhibitC4 + pmInhibitG2 + pmInhibitG4

this entry would be available only on an 8-bit or deeper color or grayscale device.

The Palette Manager works very simply, but it has so many options and effects that it can seem complicated. By understanding how the Palette Manager makes its decisions, you should find it easy to figure out how to make it do precisely what you want. We hope this column has made this clear, so that you can use the Palette Manager and avoid fussing with the alternatives.

EDGAR LEE (AppleLink EDGAR) Before Edgar's dog, Sunny, departed for the East Coast, we asked her if she could tell us a little about him. Here's what she had to say: "Edgar . . . is that his name? Oh yeah, nice human. A little hairless for my taste, but a good guy. He works over there in DTS or something. He used to come home late all the time. At first I thought he was seeing another dog, then I realized he's just a nerd. And how is he to me? Well, let's see, he takes care of me, entertains me. I bark once, he feeds me; I bark twice, we go out for a walk. Not bad for an owner; I've heard worse stories. Does he ever get upset with me? I suppose at times he does. I probably deserve it; carpet cleaning isn't cheap, you know. But hey, I see a clean spot, I go for it."*

FORREST TANAKA (AppleLink TANAKA) has spent the last couple of months learning how to be a domestic kind of guy. Once worried about paying the rent, he's now worried about paying the mortgage. Once worried about his downstairs neighbors, he's now worried about getting the best fertilizer. Now he's even the stepparent of an old dog and a cat with an attitude. As a final blow to his carefree days of youth, he has to mow the lawn! *

Indexed and direct devices are discussed in the Graphics Overview chapter (Chapter 16) of Inside Macintosh Volume VI.*

The inhibit constants are discussed in the Palette Manager chapter (Chapter 20) of Inside Macintosh Volume VI.*

Thanks to Bill Guschwan, Shannon Holland, Guillermo Ortiz, Konstantin Othmer, Brigham Stevens, and John Wang for reviewing this column. Special thanks to Joseph Maurer and Faith Pai. *


Community Search:
MacTech Search:

Software Updates via MacUpdate

jAlbum 19.2 - Create custom photo galler...
With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly, with pro results - Simply drag and drop photos into groups, choose a design... Read more
BlueStacks 4.140.13 - Run Android applic...
BlueStacks App Player lets you run your Android apps fast and fullscreen on your Mac. Feature comparison chart Version 4.140.13: Highlights/Bug Fixes: Feel free to use BlueStacks as your go to... Read more
Adobe Premiere Pro CC 2020 14.0.1 - Digi...
Premiere Pro CC 2020 is available as part of Adobe Creative Cloud for as little as $52.99/month. The price on display is a price for annual by-monthly plan for Adobe Premiere Pro only Adobe Premiere... Read more
VirtualBox 6.1.2 - x86 virtualization so...
VirtualBox is a family of powerful x86 virtualization products for enterprise as well as home use. Not only is VirtualBox an extremely feature rich, high performance product for enterprise customers... Read more
RoboForm 8.6.8 - Password manager; syncs...
RoboForm is a password manager that offers one-click login, mobile syncing, easy form filling, and reliable security. Password Manager. RoboForm remembers your passwords so you don't have to! Just... Read more
Postbox 7.0.11 - Powerful and flexible e...
Postbox is a new email application that helps you organize your work life and get stuff done. It has all the elegance and simplicity of Apple Mail, but with more power and flexibility to manage even... Read more
calibre 4.9.0 - Complete e-book library...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more
Notability 4.2 - Note-taking and annotat...
Notability is a powerful note-taker to annotate documents, sketch ideas, record lectures, take notes and more. It combines, typing, handwriting, audio recording, and photos so you can create notes... Read more
FoldersSynchronizer 5.0.1 - Synchronize...
FoldersSynchronizer is a popular and useful utility that synchronizes and backs-up files, folders, disks and boot disks. On each session you can apply special options like Timers, Multiple Folders,... Read more
Sketch 62 - Design app for UX/UI for iOS...
Sketch is an innovative and fresh look at vector drawing. Its intentionally minimalist design is based upon a drawing space of unlimited size and layers, free of palettes, panels, menus, windows, and... Read more

Latest Forum Discussions

See All

The Alliance update to Out There: Omega...
Out There is an old go-to recommendation for a lot of mobile stalwarts, but I could never really get into it. This sci-fi survival game that blended elements of interactive fiction and roguelike mechanics just felt a little off-balance and a little... | Read more »
Animal Fury Destination is an action-adv...
Animal Fury Destination is an action-adventure game from independent, Colombian developer Ignicion Games. It's a 3D action game where you'll play as various different characters as you embark on a quest to stop an evil crow sorcerer. [Read more] | Read more »
Shadowgun War Games Closed Beta Impressi...
Shadowgun: War Games is an upcoming free-to-play multiplayer shooter that’s essentially just an Overwatch knock-off. There are hero characters with special abilities, and you compete in 5-v-5 game modes where the goal is to use superior team... | Read more »
Slingsters is a physics-based puzzler fo...
Slingsters is a physics-based puzzle game where the aim is to collect various different monsters by flinging them from one side of a level to the other and into a box. It's also the first game from Nappy Cat and is available now for iOS and... | Read more »
Spiritwish's latest update sees the...
A sizeable update has hit Nexon's MMORPG Spiritwish today. It brings a new game mode, characters and there will also be a special event to celebrate the update with a firework display. [Read more] | Read more »
Maze Machina, a turn-based puzzler from...
The latest game from Arnold Rauers also known as Tiny Touch Tales is now available. You may be familiar with one of his many excellent titles such as Card Crawl, Enyo and Card Thief. His latest endeavour is called Maze Machina and you can grab it... | Read more »
Mario Kart Tour's Ice Tour races to...
Can you believe Mario Kart Tour is already on its 9th tour? The game only launched back in September, and since then it's become increasingly tricky to keep on top of the amount of new content Nintendo is pumping out. [Read more] | Read more »
Apple Arcade: Ranked - Top 50 [Updated 1...
In case you missed it, I am on a quest to rank every Apple Arcade game there is. [Read more] | Read more »
Marvel Future Fight's latest update...
Marvel Future Fight's latest update has added an all-new team of heroes to recruit and do battle with. The 'Warriors of the Sky' include Blue Dragon, War Tiger, Sun Bird, and Shadow Shell. As is the norm, each character comes with their own unique... | Read more »
Klee: Spacetime Cleaners is a fast-paced...
Klee: Spacetime Cleaners is a fast-paced auto-shooter that sports a cute retro aesthetic thathad racked up an impressive 100,000 pre-registers prior to its release. It's available now for both iOS and Android. [Read more] | Read more »

Price Scanner via

Just in! Apple iMacs on sale for $100-$150 of...
B&H Photo has new 2019 21″ and 27″ 5K iMacs on stock today and on sale for up to $150 off Apple’s MSRP, with prices starting at only $999. These are the same iMacs sold by Apple in their retail... Read more
Save $100 on the 13″ 1.4GHz MacBook Pro at th...
Apple resellers have 13″ 1.4GHz MacBook Pros on sale today for $100 off Apple’s MSRP, and some are including free overnight delivery: (1) Amazon has new 2019 13″ 1.4GHz MacBook Pros on sale for $100... Read more
AT&T offers free 64GB Apple iPhone XS wit...
Open a new line of service with AT&T, and they will include a free 64GB iPhone XS. Credit for the phone is applied monthly over a 30 month lease. The fine print: “Limited Time Requires new line... Read more
New Verizon deal: Apple iPhone XR for $300 of...
Switch to Verizon and sign up with one of their Unlimited plans, and Verizon will take $300 off the price of an Apple iPhone XR (regularly $749), plus get a free $200 prepaid Mastercard. This is an... Read more
Amazon’s popular AirPods sale is back with mo...
Amazon has new 2019 Apple AirPods on sale today ranging up to $40 off MSRP, starting at $129, as part of their popular Apple AirPods sale. Shipping is free: – AirPods Pro: $234.98 $15 off MSRP –... Read more
Apple’s top of the line 10.5″ 256GB WiFi + Ce...
B&H Photo has the top of the line 10.5″ 256GB WiFi + Cellular iPad Air on sale for $599 shipped. That’s $180 off Apple’s MSRP for this model and the cheapest price available. Overnight shipping... Read more
Apple’s refurbished iPad Pros are the cheapes...
Apple has Certified Refurbished 11″ iPad Pros available on their online store for up to $220 off the cost of new models. Prices start at $679. Each iPad comes with a standard Apple one-year warranty... Read more
Just in: Take $100 off the price of the 3.0GH...
Apple resellers are offering new 2018 6-Core Mac minis for $100 off Apple’s MSRP today, only $999. B&H Photo has 6-Core Mac minis on sale for $100 off Apple’s standard MSRP. Overnight shipping is... Read more
Apple has 4-core and 6-core 2018 Mac minis av...
Apple has Certified Refurbished 2018 Mac minis available on their online store for $120-$170 off the cost of new models. Each mini comes with a new outer case plus a standard Apple one-year warranty... Read more
Amazon offers $200 discount on 13″ MacBook Ai...
Amazon has new 2019 13″ MacBook Airs with 256GB SSDs on sale for $200 off Apple’s MSRP, now only $1099, each including free shipping. Be sure to select Amazon as the seller during checkout, rather... Read more

Jobs Board

Tableau Data Visualization Engineer - *Apple...
Job Summary Apple is looking for a seasoned Tableau Data Visualization Engineer to join the team on an initial 9 month contract at our Global HQ in Cupertino. The Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**744429BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000574-Garner-Store **Job Description:** At Best Read more
Geek Squad *Apple* Consultation Professiona...
**757963BR** **Job Title:** Geek Squad Apple Consultation Professional **Job Category:** Store Associates **Store NUmber or Department:** 000433-Henrietta-Store Read more
*Apple* Computing Professional - Best Buy (U...
**754611BR** **Job Title:** Apple Computing Professional **Job Category:** Store Associates **Store NUmber or Department:** 000142-Milpitas-Store **Job Read more
Best Buy *Apple* Computing Master - Best Bu...
**745058BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Store NUmber or Department:** 001080-Lake Charles-Store **Job Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.