Standard Colormap Functions

To use the functions defined in this section, you should include the header file <X11/Xmu/StdCmap.h> and link against the libXmu library.

Status XmuAllStandardColormaps(Display *dpy);

Status XmuAllStandardColormaps(Display *dpy);

dpy	specifies the connection to the X server

To create all of the appropriate standard colormaps for every visual of every screen on a given display, use XmuAllStandardColormaps.

This function defines and retains as permanent resources all standard colormaps which are meaningful for the visuals of each screen of the display. It returns 0 on failure, non-zero on success. If the property of any standard colormap is already defined, this function will redefine it.

This function is intended to be used by window managers or a special client at the start of a session.

The standard colormaps of a screen are defined by properties associated with the screen's root window. The property names of standard colormaps are predefined, and each property name except RGB_DEFAULT_MAP may describe at most one colormap.

The standard colormaps are: RGB_BEST_MAP, RGB_RED_MAP, RGB_GREEN_MAP, RGB_BLUE_MAP, RGB_DEFAULT_MAP, and RGB_GRAY_MAP. Therefore a screen may have at most 6 standard colormap properties defined.

A standard colormap is associated with a particular visual of the screen. A screen may have multiple visuals defined, including visuals of the same class at different depths. Note that a visual id might be repeated for more than one depth, so the visual id and the depth of a visual identify the visual. The characteristics of the visual will determine which standard colormaps are meaningful under that visual, and will determine how the standard colormap is defined. Because a standard colormap is associated with a specific visual, there must be a method of determining which visuals take precedence in defining standard colormaps.

The method used here is: for the visual of greatest depth, define all standard colormaps meaningful to that visual class, according to this order of (descending) precedence: DirectColor; PseudoColor; TrueColor and GrayScale; and finally StaticColor and StaticGray.

This function allows success, on a per screen basis. For example, if a map on screen 1 fails, the maps on screen 0, created earlier, will remain. However, none on screen 1 will remain. If a map on screen 0 fails, none will remain.

See XmuVisualStandardColormaps for which standard colormaps are meaningful under these classes of visuals.

Status XmuVisualStandardColormaps(Display *dpy, int screen, VisualID visualid, unsigned int depth, Bool replace, Bool retain);

Status XmuVisualStandardColormaps(Display *dpy, int screen, VisualID visualid, unsigned int depth, Bool replace, Bool retain);

dpy	specifies the connection to the X server
screen	specifies the screen of the display
visualid	specifies the visual type
depth	specifies the visual depth
replace	specifies whether or not to replace
retain	specifies whether or not to retain

To create all of the appropriate standard colormaps for a given visual on a given screen, use XmuVisualStandardColormaps.

This function defines all appropriate standard colormap properties for the given visual. If replace is True, any previous definition will be removed. If retain is True, new properties will be retained for the duration of the server session. This function returns 0 on failure, non-zero on success. On failure, no new properties will be defined, but old ones may have been removed if replace was True.

Not all standard colormaps are meaningful to all visual classes. This routine will check and define the following properties for the following classes, provided that the size of the colormap is not too small. For DirectColor and PseudoColor: RGB_DEFAULT_MAP, RGB_BEST_MAP, RGB_RED_MAP, RGB_GREEN_MAP, RGB_BLUE_MAP, and RGB_GRAY_MAP. For TrueColor and StaticColor: RGB_BEST_MAP. For GrayScale and StaticGray: RGB_GRAY_MAP.

Status XmuLookupStandardColormap(Display *dpy, int screen, VisualID visualid, unsigned int depth, Atom property, Bool replace, Bool retain);

Status XmuLookupStandardColormap(Display *dpy, int screen, VisualID visualid, unsigned int depth, Atom property, Bool replace, Bool retain);

dpy	specifies the connection to the X server
screen	specifies the screen of the display
visualid	specifies the visual type
depth	specifies the visual depth
property	specifies the standard colormap property
replace	specifies whether or not to replace
retain	specifies whether or not to retain

To create a standard colormap if one does not currently exist, or replace the currently existing standard colormap, use XmuLookupStandardColormap.

Given a screen, a visual, and a property, this function will determine the best allocation for the property under the specified visual, and determine the whether to create a new colormap or to use the default colormap of the screen.

If replace is True, any previous definition of the property will be replaced. If retain is True, the property and the colormap will be made permanent for the duration of the server session. However, pre-existing property definitions which are not replaced cannot be made permanent by a call to this function; a request to retain resources pertains to newly created resources.

This function returns 0 on failure, non-zero on success. A request to create a standard colormap upon a visual which cannot support such a map is considered a failure. An example of this would be requesting any standard colormap property on a monochrome visual, or, requesting an RGB_BEST_MAP on a display whose colormap size is 16.

Status XmuGetColormapAllocation(XVisualInfo *vinfo, Atom property, unsigned long *red_max, unsigned long *green_max, unsigned long *blue_max);

Status XmuGetColormapAllocation(XVisualInfo *vinfo, Atom property, unsigned long *red_max, unsigned long *green_max, unsigned long *blue_max);

vinfo	specifies visual information for a chosen visual
property	specifies one of the standard colormap property names
red_max	returns maximum red value
green_max	returns maximum green value
blue_max	returns maximum blue value

To determine the best allocation of reds, greens, and blues in a standard colormap, use XmuGetColormapAllocation.

XmuGetColormapAllocation returns 0 on failure, non-zero on success. It is assumed that the visual is appropriate for the colormap property.

XStandardColormap *XmuStandardColormap(Display *dpy, int screen, VisualID visualid, unsigned int depth, Atom property, Colormap cmap, unsigned long red_max, unsigned long green_max, unsigned long blue_max);

XStandardColormap *XmuStandardColormap(Display *dpy, int screen, VisualID visualid, unsigned int depth, Atom property, Colormap cmap, unsigned long red_max, unsigned long green_max, unsigned long blue_max);

dpy	specifies the connection to the X server
screen	specifies the screen of the display
visualid	specifies the visual type
depth	specifies the visual depth
property	specifies the standard colormap property
cmap	specifies the colormap ID, or None
red_max	specifies the red allocation
green_max	specifies the green allocation
blue_max	specifies the blue allocation

To create any one standard colormap, use XmuStandardColormap.

This function creates a standard colormap for the given screen, visualid, and visual depth, with the given red, green, and blue maximum values, with the given standard property name. Upon success, it returns a pointer to an XStandardColormap structure which describes the newly created colormap. Upon failure, it returns NULL. If cmap is the default colormap of the screen, the standard colormap will be defined on the default colormap; otherwise a new colormap is created.

Resources created by this function are not made permanent; that is the caller's responsibility.

Status XmuCreateColormap(Display *dpy, XStandardColormap *colormap);

Status XmuCreateColormap(Display *dpy, XStandardColormap *colormap);

dpy	specifies the connection under which the map is created
colormap	specifies the map to be created

To create any one colormap which is described by an XStandardColormap structure, use XmuCreateColormap.

This function returns 0 on failure, and non-zero on success. The base_pixel of the colormap is set on success. Resources created by this function are not made permanent. No argument error checking is provided; use at your own risk.

All colormaps are created with read-only allocations, with the exception of read-only allocations of colors which fail to return the expected pixel value, and these are individually defined as read/write allocations. This is done so that all the cells defined in the colormap are contiguous, for use in image processing. This typically happens with White and Black in the default map.

Colormaps of static visuals are considered to be successfully created if the map of the static visual matches the definition given in the standard colormap structure.

void XmuDeleteStandardColormap(Display *dpy, Screen *screen, Atom property);

void XmuDeleteStandardColormap(Display *dpy, Screen *screen, Atom property);

dpy	specifies the connection to the X server
screen	specifies the screen of the display
property	specifies the standard colormap property

To remove any standard colormap property, use XmuDeleteStandardColormap. This function will remove the specified property from the specified screen, releasing any resources used by the colormap(s) of the property, if possible.