colormap.xplot.lib

su 的源代码库

COLORMAP - Functions to manipulate X colormaps:

xCreateRGBDefaultMap	create XA_RGB_DEFAULT_MAP property of root window if
			it does not already exist
xGetFirstPixel		return first pixel in range of contiguous pixels in
			XA_RGB_DEFAULT_MAP
xGetLastPixel		return last pixel in range of contiguous pixels in
			XA_RGB_DEFAULT_MAP
xCreateHSVColormap	create a 2 ramp colormap (HSV - Model)
xCreateRGBColormap	create a 2 ramp colormap (RGB - Model)

Function Prototypes:
Status xCreateRGBDefaultMap (Display *dpy, XStandardColormap *scmap);
unsigned long xGetFirstPixel (Display *dpy);
unsigned long xGetLastPixel (Display *dpy);
Colormap xCreateRGBColormap (Display *dpy, Window win,
	char *str_cmap, int verbose)
Colormap xCreateHSVColormap (Display *dpy, Window win,
	char *str_cmap, int verbose)

xCreateRGBDefaultMap:
Input:
dpy		display

Output:
scmap		the standard colormap structure

xGetFirstPixel, xGetLastPixel:
Input:
dpy		display

Notes:
PROBLEM
-------

Most mid-range display devices today support what X calls
the "PseudoColor visual".  Typically, only 256 colors (or gray
levels) may be displayed simultaneously.  Although these 256 colors
may be chosen from a much larger (4096 or more) set of available
colors, only 256 colors can appear on a display at one time.

These 256 colors are indexed by pixel values in a table called
the colormap.  Each window can have its own colormap, but only
one colormap can be installed in the display hardware at a time.
(Again, only 256 colors may be displayed at one time.)  The window 
manager is responsible for installing a window's colormap when that 
window becomes the key window.

Many of the applications we are likely to write require a large,
contiguous range of pixels (entries in the colormap).  In this
range, we must be able to:
(1) given a color (or gray), determine the corresponding pixel.
(2) given a pixel, determine the corresponding color (or gray).
An example would be an imaging application that uses a gray scale
to display images in shades of gray between black and white.
Such applications are also likely to require a few additional colors
for drawing axes, text, etc.

The problem is to coordinate the use of the limited number of
256 simultaneous colors so that windows for different applications 
appear reasonable, even when their particular colormaps are not
installed in the display hardware.  For example, we might expect 
an analog xclock's hands to be visible even when xclock's window
is not the key window, when its colormap is not installed.

We should ensure that the range of contiguous pixels used by one
application (perhaps for imaging) does not conflict with the pixels
used by other applications to draw text, clock hands, etc.


SOLUTION
--------

Applications that do not require special colormaps should simply
use the default colormap inherited from the root window when new
top-level windows are created.

Applications that do require a special colormap MUST create their
own colormap.  They must not assume that space will be available
in the default colormap for a contiguous range of read/write pixels,
because the server or window manager may have already allocated
these pixels as read-only.  Even if sufficient pixels are available
in the default colormap, they should not be allocated by a single
application.  The default colormap should be used only for windows
requiring a limited number of typical colors, such as red, yellow, etc.

Applications that require a contiguous range of read/write pixels
should allocate these pixels in their window's private colormaps.
They should determine which contiguous pixels to allocate from 
parameters in the standard colormap XA_RGB_DEFAULT_MAP.  In particular,
the first pixel in the range of contiguous pixels should be 
	base_pixel
and the last pixel in the range should be 
	base_pixel+red_max*red_mult+green_max*green_mult+blue_max*blue_mult,
where base_pixel, red_max, etc. are members in the XStandardColormap
structure.  On an 8-bit display, this range will typically provide 216
contiguous pixels, which may be set to a gray scale, color scale, or
whatever.  This leaves 40 colors for drawing text, axes, etc.

If the XA_RGB_DEFAULT_MAP does not exist, it should be created to 
consist of various colors composed of an equal number of reds, 
greens, and blues.  For example, if 216 colors are to be allocated,
then red_max=green_max=blue_max=5, red_mult=36, green_mult=6, and
blue_mult=1.  Because of the difficulty in forcing a particular 
pixel to correspond to a particular color in read-only color cells,
these 216 colors will likely be read/write color cells unless
created by the X server.  In any case, these 216 colors should not
be modified by any application.  In creating custom colormaps, the
only use of XA_RGB_DEFAULT_MAP should be in determining which 216
pixels to allocate for contiguous pixels.

In creating a custom colormap for a window, the application should
initialize this colormap to the colors already contained in the
window's colormap, which was inherited initially from its parent.
This will ensure that typical colors already allocated by other
applications will be consistent with pixels used by the application
requiring the custom colormap.  Ideally, windows might have
different colormaps, but the only differences would be in the
range of contiguous colors used for imaging, rendering, etc.
Ideally, the pixels corresponding to colors used to draw text, 
axes, etc. would be consistent for all windows.

Unfortunately, it is impractical to maintain complete consistency 
among various private colormaps.  For example, suppose a custom
colormap is created for a window before other applications have
had the opportunity to allocate their colors from the default
colormap.  Then, when the window with the custom colormap becomes
the key window, the windows of the other applications may be 
displayed with false colors, since the colormap of the key window
may not contain the true colors.  The colors used by the other 
applications did not exist when the custom colormap was created.
One solution to this problem might be to initially allocate a
set of "common" colors in the default colormap before launching
any applications.  This will increase the likelihood that typical
colors will be consistent among various colormaps.

Functions are provided below to
(1) create the standard colormap XA_RGB_DEFAULT_MAP, if it does not exist,
(2) determine the first and last pixels in the contiguous range of pixels,
(3) create some common private colormaps 

xCreateRGBDefaultMap:
This function returns 0 if the XA_RGB_DEFAULT_MAP property does not exist
and cannot be created.  At least 8 contiguous color cells must be free
in the default colormap to create the XA_RGB_DEFAULT_MAP.  If created, the
red_max, green_max, and blue_max values returned in scmap will be equal.

xGetFirstPixel, xGetLastPixel:
If it does not already exist, XA_RGB_DEFAULT_MAP will be created.
If XA_RGB_DEFAULT_MAP does not exist and cannot be created, then
this function returns 0.

xCreateRGBColormap, xCreateHSVColormap:
The returned colormap is only created; the window's colormap attribute
is not changed, and the colormap is not installed by this function.
The returned colormap is a copy of the window's current colormap, but 
with an RGB color scale allocated in the range of contiguous cells
determined by XA_RGB_DEFAULT_MAP.  If it does not already exist,
XA_RGB_DEFAULT_MAP will be created.

Author:  Dave Hale, Colorado School of Mines, 09/30/90