PEXUtCopyColormapAsReadOnly(3G)

Name

PEXUtCopyColormapAsReadOnly − create a Colormap for use with XAllocColor by copying an existing Colormap

Syntax

#include <pexutcmap.h>

int PEXUtCopyColormapAsReadOnly(Display *display, Colormap source_cmap_id, 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.

source_cmap_id
A valid identifier for a resource that has been initialized in accordance with the color approximation entry (capx_info).

vis_info
A pointer to a valid structure that describes the Visual in which the source Colormap has been allocated, and in which the new Colormap will be created.

capx_info
A pointer to a valid structure, that describes the color approximation setup for which the source Colormap has been 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 new 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 a new Colormap that is a copy of the source_cmap_id colormap, but using read-only or unallocated cells whereever possible, while protecting the integrity of the color approximation region ("ramp") described in capx_info. 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).

The new Colormap ID is returned in colormap_id_return. The source Colormap is not freed; that is left for the caller to do if desired.