Related Info: Color Manager Palette Manager Color Quickdraw
Device Manager

Colorizing the Mac

By Hugh Fisher, Page, Australia

Colorizing the Macintosh

In August I began converting a black and white Macintosh game, Fire-Brigade, to run in color on the Mac II. One of the requirements for the new version was for a map to be displayed in a specific set of colors, even on 16 color cards; and for the colors on this map to change to show the different seasons. “No problem,” I said to El Presidente, “Apple set up the Palette Manager for that kind of thing - I read it in Inside Mac Five. I’ll design the code over the weekend and put it on the machine Monday.”

After a statement like that it went as you would expect: six weeks of struggle, panic, and despair before finally getting the thing to work. Along the way I learned many interesting things about the Color and Palette Managers.

CLUTs and CopyBits

A quick recap on color graphics: the average color graphics card stores 2, 4, or 8 bit pixel values in memory rather than a 24 or 48 bit RGB color. When the screen is drawn, these pixel values are used as indexes into a color lookup table (CLUT) which stores actual RGB entries. Usually you change the color of something by keeping the table the same and redrawing with a new pixel value. Color cycling, or color table animation, instead stores a new RGB color into an entry in the table, immediately changing the color of every pixel with that value. This is often thought of as just an arcade game technique, but is also essential for manipulating digitized images of all sorts. Sorry if this is all elementary stuff to you.

Each monitor attached to a Mac II has a device CLUT, of type CTabHandle. This is a handle to a table of ColorSpecs, each of which is an RGB color and a 16 bit pixel value. The device CLUT is stored as the pmTable field for the PixMap representing the device video RAM. The pixel values in a device table are used by the Color Manager for various purposes, and it is most likely just a shadow copy of the real hardware table anyway, so it should not be altered directly.

Offscreen pixmaps also have a pixmap CLUT, usually copied from a device. These pixmaps never change depth and have no hardware to worry about, so every pixel value in the table is equal to its index and every entry is valid. New RGB colors can be assigned directly to table entries - a pixel value means whatever you want it to.

Color Quickdraw often needs to check if two color tables correspond. Instead of comparing the two entry by entry it just compares the ctSeed fields and assumes that if the seeds match, so does everything else. Device seeds are maintained and updated by the Color Manager. Pixmap tables copied from a device start with the same seed value. If you are going to change the RGB colors in an offscreen table it needs a unique seed of its own, so call GetCTSeed when it is first created. The seed does not need to change every time the RGB colors change, just be unique.

When CopyBits is called with PixMap parameters, it checks the seed values of the source and destination. If they are the same, the pixel values can be just blitted across directly. If the seeds are different, CopyBits translates each source pixel value into the best RGB match available in the destination table. The translation overhead is not detectable, but despite this I saw a letter in MacTutor recommending setting the source and destination seeds equal before a CopyBits. Don’t do it! If the seeds are already the same, you gain nothing. If they are different, your source image will be randomly recolored in the destination.

Down and Dirty Color Cycling

Color cycling an offscreen image is easy - you just store the new RGB color in the table. Onscreen color cycling can be done through the Color Manager routines Color2Index and SetEntries (code example below.) This method of color cycling is frowned upon by the User Interface Thought Police because it is device dependent.

{1}

procedure colorCycle (oldRGB, newRGB : RGBColor);
 var
 newColor : ColorSpec;
 colorPtr : ^CSpecArray;
 devIndex : Integer;
 begin
 devIndex := Color2Index (oldRGB);
 newColor.rgb := newRGB;
 colorPtr := @newColor;
 SetEntries (devIndex, 0, colorPtr^);
 end;

The Palette Manager

The primary function of the Palette Manager is arbitrating between competing demands when the number of colors is limited. It does this well, and every color application should use it. The second function is device independent color table animation, which has problems and is described in the next section.

The types of Palette Manager color reflect this division. Courteous and Tolerant colors are for applications working in RGB space, where you specify a color and let the hardware handle the details. Animated and Explicit colors are for applications that work with pixel values and CLUTs.

A palette is a set of colors assigned to a window. When there are not enough colors in the device CLUT to satisfy all the visible windows, the Palette Manager gives priority to the frontmost window and then works back. Every time a new window, including dialogs and alerts, is brought forward the Palette Manager reshuffles the priorities and if necessary alters the device CLUT, causing those distracting changes in the background.

Even a window without a palette can cause a change in the device CLUT on a 16 color system, which is quite irritating to watch. As per Tech Note #211 you can avoid this by setting up an application default palette regardless of whether you use color or not.

 data ‘pltt’ (-1) {
 $”0002 0000 0000 0000 0000 0000 0000 0000"
 $”FFFF FFFF FFFF 0002 0000 0000 0000 0000"
 $”0000 0000 0000 0002 0000 0000 0000 0000"
 };

The Palette Manager doesn’t know about ‘floating’ windows such as tearoff menus, so you have to do some palette managing of your own. When a document is brought to the ‘front’, make its palette the application default or share it with the true front window.

{2}

procedure mySelectWindow (w : WindowPtr);
 var
 p : PaletteHandle;
 begin
 p := GetPalette (w);
 ...
 SetPalette (WindowPtr(-1), p, true);

OR

{3}

 SetPalette ( the top floater, p, true);
 ActivatePalette (the top floater );

For some bizarre reason the Palette Manager is present on all Macs, not just the Mac II, so you don’t have to worry about compatibility.

The Palette Manager chapter says that PmForeColor and PmBackColor should be used in place of the regular RGBForeColor and RGBBackColor. For applications working in RGB space (Courteous and Tolerant) this is not necessary. The Palette Manager will not set up duplicate entries for a single color, so the final pixel value will always be the same no matter which you call. My opinion is that it is better to be consistent and always use the RGB calls.

Palettes are assigned to windows but not GrafPorts, which is awkward if you want to draw offscreen using a different set of colors. One solution is to temporarily reassign the front window palette, but this can cause the screen to change for no apparent reason. You could set up your own GDevice, but this is excessive. The best way is to use a custom search proc which returns the pixel values you want. More on this later.

The Dark Side of the Palette Manager

The Palette Manager can, according to Inside Macintosh V, be used for device independent color table animation. True, but it turns out that the Palette Manager has two serious limitations:

• You cannot animate a PICT

• You cannot maintain an offscreen copy

When you activate a palette of animated colors, the Palette Manager reserves entries in the device CLUT for your exclusive use. Reserved entry indexes are never returned by Color2Index, RGBForeColor, etc; so the color cannot be used by another application (or even another window unless it shares the palette.) This would be fine, except that you cannot use those routines either! The only way to draw with those pixel values is through PmForeColor and PmBackColor, period.

PICTs and Animated Colors

This is why you cannot animate a PICT. The PICT works in RGB space and therefore calls RGBForeColor. Your animated colors are protected against this, so are ignored. If there are free colors elsewhere in the device table, these will be used instead. The PICT will be drawn in color, but the colors do not correspond to the entries in your palette so animating the palette has no effect. If there are not any free colors, quite likely on a 4 or 16 color card, the PICT comes out in black and white. Either way, you are up the creek.

Can you draw the PICT with Tolerant colors and then change them to Animated? Sorry, no. The Palette Manager does some kind of least recently used analysis to select device CLUT entries for animation, so tries as hard as possible not to reserve the already existing entry. On a 4 or 16 color card, it will probably have to reserve one of your Tolerant colors, but not necessarily the right one.

Can you force Quickdraw to draw with your Animated colors? Yes, with a custom search proc, but it is messy. More on this later.

Pixmaps and Animated Colors

Now for offscreen pixmaps. Here the Palette Manager works fine in isolation, but can’t cope with the real world. Suppose you activate a palette of animated colors, draw your image using PmForeColor and PmBackColor, then create an offscreen pixmap and CopyBits the image to it. What happens when you CopyBits back?

It works for a while. The offscreen pixmap has a copy of the device CLUT with the same seed, so CopyBits just transfers the pixel values directly. AnimateEntry and AnimatePalette have been especially written by Apple to leave the device seed unchanged, because it is the pixel values that should match between the source and destination, not the RGB colors. Even if the onscreen image has been animated since the offscreen copy was created, it will be drawn correctly with the current palette RGB colors.

Unfortunately you can upset this happy state of affairs in many ways: changing the screen depth, moving the window to another screen, switching to another application under MultiFinder, choosing a new highlight color from the Control Panel. All of these may change the device CLUT and seed. (To be fair to Apple, I understand that the Control Panel has been fixed, and there is nothing they could do about the window moving to another monitor anyway.)

As soon as the device CLUT changes, the whole scheme is kaput. As described earlier, if the seeds of the source and destination pixmap CLUTs don’t match, CopyBits translates the pixel values from the source to the destination. The translation uses the same color matching algorithm as RGBForeColor, and likewise it ignores animated colors. Once again, your image is either translated to a different set of colors or becomes black and white.

Can you avoid this by setting the seeds equal? The animating colors are reserved for your application, so in theory those pixel values are unchanged. Again, no. The offscreen pixmap was built using pixel values from one particular device, so if the window has been moved to another they almost certainly will not match. Even on the same device it doesn’t always work. When the device CLUT changes, the Palette Manager may reassign the pixel values for colors in the palette. The pixel values in the offscreen pixmap are no longer valid.

In short, you can only maintain an offscreen copy of Animated colors as long as the device and device CLUT are held constant, and in today’s world of multiscreen, MultiFinder equipped Macintoshes this is hardly practical.

Solutions

Since it is equally impractical to write a bitmapped color graphics application such as Fire-Brigade without using offscreen pixmaps or PICTs, what can a programmer do? For Fire-Brigade, I tried three solutions which did work, as well as countless ones that didn’t.

First, I wrote a custom search proc which forced Quickdraw and CopyBits to recognize animating colors. Unfortunately this ruins the performance of CopyBits for small images, so had to be abandoned.

Next I tried redrawing the offscreen pixmaps whenever the device CLUT changed to keep them up to date. Since there were 200K of PICTs to draw, it took about 20 seconds to resume from a MultiFinder switch and had to be abandoned.

The final solution was to forget about the Palette Manager for animation. Instead Fire-Brigade uses the Palette Manager for what it is good at: making sure that our palette of Tolerant colors is available when we need it. Onscreen color cycling is done directly through the Color Manager as described above.

Locating Devices

To animate colors directly you need to know which device the window is on. Calling GetGDevice doesn’t work, because as far as I can tell it always returns the first device in the list regardless of the current port. The easiest way is to convert the windows portRect into global coordinates and call GetMaxDevice for that rect, on the assumption that very few windows spread over more than one monitor. If you want to be absolutely safe, convert the portRect into global coordinates and then calculate the intersection of this rect with each device^^.gdRect in turn.

(I also found that although GrafPorts are opened on the current device, windows are not. When I changed the device with SetGDevice before creating a window, the title bar and frame appeared on one monitor and the contents on the other! The correct way to put a window on a particular device is to calculate the window bounds rect as usual and then offset it by device^^.gdRect.topLeft.)

Custom Search Procs

Several times I have mentioned custom search procs. A search proc in Color Quickdraw translates an RGB color into an actual CLUT index value for a particular device. Custom search procs, described in the Color Manager chapter of Inside Mac, allow you to override the standard behavior when necessary.

A simple and useful proc is one that matches colors for offscreen drawing. If you want to save a large offscreen image which you know uses only a few colors, setting the offscreen pixmap depth to 2 or 4 saves a considerable amount of memory. Because you want to draw with the pixel values in the offscreen CLUT, not the device CLUT, install this search proc or something similar:

{4}

varoffscreenColors : CTabHandle; { Shared with pixmap }
...
function offscreenPixel (target : RGBColor; var pixel : LongInt):Boolean;
 var index : Integer;
 begin
 offscreenPixel := false; { In case we can’t match }
 with offscreenColors^^ do
 begin
 for index := 0 to ctSize do
 begin
 if (ctTable[index].red = target.red)
 and (ctTable[index].green = target.green)
 and (ctTable[index].blue = target.blue) then
 begin
 pixel := index;
 offscreenPixel := true;
 leave;
 end; { if }
 end; { for }
 end; { with }
 end; { offscreenPixel }

You only need to install this search proc when the image is first drawn, not when copying from it to the screen.

You can also write a custom search proc that recognizes animated colors. The easy way is just to search every entry in the device CLUT and return the index of the best match, regardless of whether it is reserved or not. This can give the wrong result under certain circumstances, because Animated colors, unlike Tolerant or Courteous, may have duplicates elsewhere in the device CLUT.

To be safe you should check if the target color is one in your palette, and if so return the pixel value for that entry. To do this you have to build your own lookup table. The pixel value is encoded in some way in the ciPrivate field of a palette entry record, but since the reason for using the Palette Manager is to avoid compatibility problems you shouldn’t touch it. Instead, open a CGrafPort and call PmForeColor for each palette entry in turn. Calling PmForeColor will set the rgbFgColor field of the port to the RGB color and the fgColor field to the actual pixel value. Store fgColor in your private lookup table and go on to the next.

Custom Quirks

The two things you have to remember with custom search procs are firstly that they are a shared resource, and secondly that they add an overhead to CopyBits.

Custom search procs are assigned to devices, not applications. Under MultiFinder this means that a background application may try to call RGBForeColor, which in turn calls your custom search proc, which bombs because it can’t find your global variables. Even if your search proc is self contained you shouldn’t risk other applications calling it. Make sure the code that calls AddSearch doesn’t call GetNextEvent until after a corresponding DelSearch. Horrible things happen if your application finishes but leaves a custom search proc installed.

The Color Manager chapter in Inside Macintosh V mentions ‘client ids’ , but these are only useful for search procs which are installed on more than one device. The client id can distinguish which device is calling the search proc, but because the id is also a shared resource you can’t arrange for it to be unique to your application.

Installing a custom search proc will add a certain constant overhead to CopyBits which depends on the depth of the source. If CopyBits needs to build a translation table to remap pixel values from the source to a device with a search proc, it has to call that search proc once for each entry in the source CLUT. Copying from a 4 bit pixmap means 16 calls, which is noticeably slower but not too bad; 8 bits means 256 calls which is just awful. A tightly coded search proc is no real improvement over a sloppy one - it is the number of calls that drags performance down, not the individual searches.

Color Diagnosis

A CLUT viewer of some sort is essential for working in color. The March 1988 issue of MacTutor describes a DA called Chroma which displays all the useful device and device color table values. I use a cut down version which just shows the colors in the CLUT and the seed value. Inside Mac V, Palette Manager chapter, Explicit Color section gives an outline of how to write it.

You should test your application with different screen depths. With 256 colors there is lots of room and the Color/Palette Managers are not worked very hard. Sixteen colors is much more stressful and reveals the problems faster. Of course, you still need to test at least briefly under 256 colors to avoid nasty surprises like the increased CopyBits overhead with search procs, and ideally you want to try it under 32 bit Quickdraw as well. (Ack! This is getting as bad as the IBM PC.)

Conclusion

During the weeks I spent trying to get the animation in Fire-Brigade to work, anyone fool enough to ask “How’s it going?” got 30 minutes of me calling down fire and brimstone upon the entire population of Cupertino, California. Since then I’ve mellowed a bit. I’m still irritated that the animation features of the Palette manager are useless for real applications, but I also think it doesn’t matter. By the end of 1990 onscreen color cycling should be obsolete and those parts of the Palette Manager dead, kept only for upward compatibility.

Color cycling is and will remain an important technique for image manipulation, and offscreen color cycling works beautifully on the Mac II. Onscreen color cycling, though, is something of an anachronism. It is only worthwhile when the CPU cannot redraw the screen quickly, and only possible when RAM costs too much for direct color to be used. Neither of these is true for the Mac II, so the successor to Fire-Brigade will do all its color cycling offscreen.

• Work in RGB color space, not with pixel values. It is the only way to survive multiple screens and 32 bit Quickdraw.

• Color Quickdraw tries to give you the best results it can under all circumstances. Resist the temptation to interfere for ‘efficiency’ - you usually make things worse.

• Test with 4 or 16 colors, and do lots of MultiFinder switching with other color applications active.

• The Palette Manager is your friend.

• Every application should have a default palette.

• Use palettes of Courteous/Tolerant colors if you want a particular set of colors onscreen.

• Use a custom search proc if you want a particular set of colors offscreen.

• Don’t use PmForeColor and PmBackColor for normal drawing.

• Avoid Animated colors like the plague!

• If you use a custom search proc, don’t leave it lying around.

• Make sure you test the performance of custom search procs under 256 colors.

• Offscreen CLUTs need a unique ctSeed if they are to be color cycled.

• Don’t force ctSeeds to be equal for CopyBits.

• If you want to cycle colors, do so offscreen in your own pixmaps and let CopyBits translate it to the screen.

Acknowledgements

A great many people helped me with information about Color Quickdraw and the Palette Manager, in particular Brett Adams and the Canberra office of Apple Computer. Thank you all very much.