PEXUtGetStandardColormapInfo(3G)

Name

PEXUtGetStandardColormapInfo − retrieve or generate PEX color information for a specified Visual

Syntax

#include <pexutcmap.h>

int PEXUtGetStandardColormapInfo(Display *display, XVisualInfo *vis_info, XStandardColormap *cmap_info_return, PEXColorApproxEntry *capx_info_return, Atom *std_prop_atom_return)

Parameters

display
A pointer to a display structure returned by a successful XOpenDisplay call, on which PEXlib has been initialized.

vis_info
A pointer to a valid structure that describes the Visual of interest.

cmap_info_return
A pointer to an structure in the caller’s domain. On successful return, this structure is written with a copy of the standard colormap property entry that was found for the Visual, if any. If no property was found, this structure is written with information derived from the attributes of the Visual.

capx_info_return
A pointer to a structure in the caller’s domain. On a successful return, this structure is written with a color approximation setup compatible with the contents of cmap_info_return and the Visual description, and can be used in a PEXSetTableEntries call.

std_prop_atom_return
A pointer to an Upon successful return, this location contains the Atom value for the property whose entry is described in *cmap_info_return, or if no property entry was used.

Returns

The function returns a value of if it is successful in finding or generating information about the specified Visual.

A negative return value indicates failure. The following are the meanings of the different failure values:

•A return value of means that an error was encountered during an Xlib call, and the return parameters are not valid.

•means that the utility ran out of memory.

Description

This procedure searches a set of standard colormap properties (the set and ordering to be determined by interoperability convention) for an entry for the visual described by vis_info. If an entry is found, it is copied into the cmap_info_return structure. If no appropriate entry is found, cmap_info_return is loaded with a description of a standard colormap RGB ramp "synthesized" from the information about the Visual, with a colormap ID of The capx_info_return structure is set up with a compatible color approximation entry. The std_prop_atom_return parameter returns a handle for the property name, or if no property entry was found.

A colormap initialization and color approximation setup that are likely to be supported by PEX in the Visual are described in cmap_info_return and capx_info_return. However, in the case where no interoperability property was used to obtain the colormap description, these return structures both describe what amounts to an "educated guess" about what color setup might be supported by PEX. In such a case, the utility return a color approximation entry for GrayScale and StaticGray Visuals, and a entry for other Visual classes. PEXUtVerifyColorApproximation may be used to verify that the PEX server does support the color approximation entry.

This utility is intended for use by applications that select a Visual by means other than PEXUtFindVisual (which returns an structure directly, and implements the same conventions regarding properties).