About color palettes in Common Graphics

A palette holds an arbitrary set of colors for drawing in one or more windows. An application needs to use a palette only if

1. The end user might be running the Windows operating system in 256-color mode or (perhaps) 65,536-color mode; and
2. Colors other than the 20 colors in the end user's Control Panel color scheme are needed.

The end user's Control Panel color scheme normally includes the 16 standard VGA colors black, white, gray, light-gray, red, green, blue, yellow, cyan, magenta, dark-red, dark-green, dark-blue, dark-yellow, dark-cyan, and dark-magenta, plus four special colors for button background and 3d edges and so on. The linked names are to constants whose values are the named colors.

By default, calling the function palette on a Common Graphics window returns the symbol :RGB, which indicates that the window has not been given a custom palette. To draw in color on a window that has no custom palette, you simply set the foreground-color or background-color to be an RGB color object (as created by make-rgb named by constants such as blue and red), and then call various drawing functions.

But if Windows is not in true color mode (that is, less than 24-bit color) and the requested RGB color is not one of the 20 system colors (either a VGA color or one of the other four colors in the current Control Panel color scheme), then this actual color will not be used. Instead, for a line-drawing operation, one of the 20 system colors that is nearest to the requested color will be substituted; and for a space-filling operation, each pixel that is drawn will be one of two system colors in such a proportion as to approximate the requested color (this approximation technique is called dithering, and does not look as nice as every pixel being the actual requested color).

The alternative to the above is to define and use a custom color palette. The basic procedure to set up a custom palette is to

1. Create a vector of RGB color objects.
2. Create a palette by calling open-palette on that RGB vector.
3. Assign the palette handle returned by open-palette to a window by calling setf of palette.

To then draw in the window,

1. setf the current foreground-color and/or background-color of the window to be the index of the desired color in the color vector that you defined earlier.
2. Call drawing functions on the window.

A palette should be no larger than the number of colors in which the end user is running the Windows operating system. If Windows is running in 256-color mode (8-bit color), for example, then no more than 256 different colors may appear on the screen at any time, and a palette may contain no more than 256 colors.

If multiple windows (including those in other applications) are using palettes, and Windows is running in 256-color mode, then any given window that is using a palette will typically not display the correct colors except when it is the most recently selected window that uses a palette, since the combined palettes will typically contain more colors than the whole system can display.

The set of colors currently being displayed system-wide is sometimes referred to as the system palette. Common Graphics knows to force a window's full palette into the system palette whenever it is selected.

When Windows is running in 256-color mode, it is recommended that a palette have somewhat less than 256 colors, so that when the window is selected, the basic colors used in other windows will still have room in the system palette and so other windows will not switch to odd colors borrowed from your custom palette. A palette of 236 colors or less would still leave room for the user's 20 colors from their Control Panel color scheme.

The Windows OS may be run in 1-bit (monochrome) mode, 4-bit (16-color / VGA) mode, 8-bit (256-color) mode, 16-bit (65,536-color) mode, or 24- or 32-bit (true color) mode, depending on the end user's settings in Control Panel. True color never uses a palette because the 24 bits or more for each pixel is large enough to contain an accurate RGB (red-green-blue) specification directly rather than serving as an index into a smaller table of color definitions. Though most any color computer that is sold nowadays is capable of true color, the end user may still elect to run in 256-color mode either to achieve a greater screen resolution (width by height) or to achieve greater speed of graphical output. So in general it should not be assumed that an end user will run your application in true color unless that is an explicit requirement of the application.

A special case is 16-bit color mode, where the OS appears to use a default palette with millions of colors that approximate true color. In this mode, arbitrary RGB colors may be used for foreground and background colors of Common Graphics windows without using custom palettes, but the colors actually used will still only be approximate (though a much better approximation than dithering). A custom palette may still be needed even in this mode for better color accuracy.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.