PEXUtCreateColormap(3G)

Name

PEXUtCreateColormap − create a Colormap and initialize it for PEX color approximation

Syntax

#include <pexutcmap.h>

int PEXUtCreateColormap(Display *display, XVisualInfo *vis_info, PEXColorApproxEntry *capx_info, Colormap *colormap_id_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 in which the Colormap will be created.

capx_info
A pointer to a valid structure, that describes the color approximation setup for which the Colormap is to be initialized.

colormap_id_return
A pointer to a identifier, into which will be written the resource ID of the created Colormap.

Returns

The function returns a value of if the Colormap is successfully created and initialized.

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, including X Colormap creation.

•means that the utility ran out of memory.

Description

This procedure creates an X Colormap in the Visual described by vis_info. It uses the provided PEX color approximation table entry (in capx_info) as a guide in initializing the Colormap contents. It then applies any additional adjustments due to vendor, platform, or configuration dependencies to the Colormap contents. Finally, it converts as many cells in the Colormap to be read-only or unallocated as possible (see the explanation below), so that XAllocColor can be used with the Colormap.

Only the cells in the region of the Colormap described by the color approximation entry have been modified from their default values. If the color approximation region consumes the entire Colormap, then all cells in the new map are read-only. If the region only consumes some of the map, then cells outside the region are read-only or unallocated, but the color approximation region is left read-write. This ensures that no unallocated cells exist within the region that could be modified during a later XAllocColor operation (resulting in a "corrupted" region).

If successful, the new Colormap ID is returned in colormap_id_return. The new Colormap ID is not entered into any standard colormap property.

Note that in the case where a color approximation entry is specified, the utility initializes the colormap to contain a gray ramp. If the application plans to load other colors into the color approximation region, it may encounter color cell permission errors since the cells in the region may be read-only. Instead of using this utility, the following sequence of calls should be used:

Call PEXUtCreateWriteableColormap(...,&writeable_cmap_id,...) to create and initialize a Colormap.

Call XStoreColors(...,writeable_cmap_id,...) to load the desired colors.

Call PEXUtModifyColormapForVendorDependencies(...,writeable_cmap_id,...) to adjust the Colormap contents according to any implementation or configuration idiosyncrasies.

Optionally, call PEXUtCopyColormapAsReadOnly(...,writeable_cmap_id,...,&readonly_cmap_id) and XFreeColormap(...,writeable_cmap_id) to create a read-only version of the Colormap.