10.3 Colormap Functions

A colormap is represented in CLX by a colormap object. A CLX program can create and manipulate several colormap objects. However, the colors contained in a colormap are made visible only when the colormap is installed. Each window is associated with a colormap that is used to translate window pixels into colors (see window-colormap). However, a window will appear in its true colors only if its associated colormap is installed.

The total number of colormaps that can be installed depends on the screen hardware. Most hardware devices allow exactly one colormap to be installed at any time. That is, screen-min-installed-maps and screen-max-installed-maps are both equal to 1. Installing a new colormap can cause a previously installed colormap to be uninstalled. It is important to remember that the set of installed colormaps is a hardware resource shared cooperatively among all client programs connected to an X server.

A CLX program can control the contents of colormaps by allocating color cells in one of two ways: read-only or read-write. Allocating a read-only color cell establishes a color value for a specified pixel value that cannot be changed. However, read-only color cells can be shared among all client programs. Read-only allocation is the best strategy for making use of limited colormap hardware in a multi-client environment.

Alternatively, allocating a read-write color cell allows a client the exclusive right to set the color value stored in the cell. A cell allocated read-write by one client cannot be allocated by another client, not even as a read-only cell. Note that read-write allocation is not allowed for screens whose visual type belongs to one of the :static-gray, :static-color, or :true-color classes. For screens of these classes, colormap cells cannot be modified.

Two entries of the default colormap, typically containing the colors black and white, are automatically allocated read-only. The pixel values for these entries can be returned by the functions screen-black-pixel and screen-white-pixel. Applications that need only two colors and also need to operate on both monochrome and color screens should always use these pixel values. The names black and white are intended to reflect relative intensity levels and need not reflect the actual colors displayed for these pixel values.

Each screen has a default colormap, which is initially installed. By conventions, clients should allocate only read-only cells from the default colormap.