Next: , Previous: Cursor, Up: Top


6 Colormap

A colormap maps pixel values to RGB color space values.

— Function: x:create-colormap window visual alloc-policy

window specifies the window on whose screen you want to create a colormap. visual specifies a visual type supported on the screen. alloc-policy Specifies the colormap entries to be allocated. You can pass X:Alloc-None or X:Alloc-All.

The X:Create-Colormap function creates and returns a colormap of the specified visual type for the screen on which window resides. Note that window is used only to determine the screen.

X:Gray-Scale
X:Pseudo-Color
X:Direct-Color
The initial values of the colormap entries are undefined.
X:Static-Gray
X:Static-Color
X:True-Color
The entries have defined values, but those values are specific to visual and are not defined by X. The alloc-policy must be ‘X:Alloc-None’.

For the other visual classes, if alloc-policy is ‘X:Alloc-None’, the colormap initially has no allocated entries, and clients can allocate them.

If alloc-policy is ‘X:Alloc-All’, the entire colormap is allocated writable. The initial values of all allocated entries are undefined.

X:Gray-Scale
X:Pseudo-Color
The effect is as if an XAllocColorCells call returned all pixel values from zero to N - 1, where N is the colormap entries value in visual.
X:Direct-Color
The effect is as if an XAllocColorPlanes call returned a pixel value of zero and red_mask, green_mask, and blue_mask values containing the same bits as the corresponding masks in the specified visual.

To create a new colormap when the allocation out of a previously shared colormap has failed because of resource exhaustion, use:

— Function: x:copy-colormap-and-free colormap

Creates and returns a colormap of the same visual type and for the same screen as the specified colormap. It also moves all of the client's existing allocation from the specified colormap to the new colormap with their color values intact and their read-only or writable characteristics intact and frees those entries in the specified colormap. Color values in other entries in the new colormap are undefined. If the specified colormap was created by the client with alloc set to ‘X:Alloc-All’, the new colormap is also created with ‘X:Alloc-All’, all color values for all entries are copied from the specified colormap, and then all entries in the specified colormap are freed. If the specified colormap was not created by the client with ‘X:Alloc-All’, the allocations to be moved are all those pixels and planes that have been allocated by the client and that have not been freed since they were allocated.

A colormap maps pixel values to elements of the RGB datatype. An RGB is a list or vector of 3 integers, describing the red, green, and blue intensities respectively. The integers are in the range 0 - 65535.

— Function: x:alloc-colormap-cells colormap ncolors nplanes
— Function: x:alloc-colormap-cells colormap ncolors nplanes contiguous?

The X:Alloc-Color-Cells function allocates read/write color cells. The number of colors, ncolors must be positive and the number of planes, nplanes nonnegative. If ncolors and nplanes are requested, then ncolors pixels and nplane plane masks are returned. No mask will have any bits set to 1 in common with any other mask or with any of the pixels. By ORing together each pixel with zero or more masks, ncolors * 2^nplanes distinct pixels can be produced. All of these are allocated writable by the request.

x:Gray-Scale
x:Pseudo-Color
Each mask has exactly one bit set to 1. If contiguous? is non-false and if all masks are ORed together, a single contiguous set of bits set to 1 is formed.
x:Direct-Color
Each mask has exactly three bits set to 1. If contiguous? is non-false and if all masks are ORed together, three contiguous sets of bits set to 1 (one within each pixel subfield) is formed.

The RGB values of the allocated entries are undefined. X:Alloc-Color-Cells returns a list of two uniform arrays if it succeeded or #f if it failed. The first array has the pixels allocated and the second has the plane-masks. — Function: x:alloc-colormap-cells colormap ncolors rgb
— Function: x:alloc-colormap-cells colormap ncolors rgb contiguous?

The specified ncolors must be positive; and rgb a list or vector of 3 nonnegative integers. If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested, ncolors pixels are returned; and the masks have nreds, ngreens, and nblues bits set to 1, respectively. If contiguous? is non-false, each mask will have a contiguous set of bits set to 1. No mask will have any bits set to 1 in common with any other mask or with any of the pixels.

Each mask will lie within the corresponding pixel subfield. By ORing together subsets of masks with each pixel value, ncolors * 2(nreds+ngreens+nblues) distinct pixel values can be produced. All of these are allocated by the request. However, in the colormap, there are only ncolors * 2^nreds independent red entries, ncolors * 2^ngreens independent green entries, and ncolors * 2^nblues independent blue entries.

X:Alloc-Color-Cells returns a list if it succeeded or #f if it failed. The first element of the list has an array of the pixels allocated. The second, third, and fourth elements are the red, green, and blue plane-masks.

— Function: x:free-colormap-cells colormap pixels planes
— Function: x:free-colormap-cells colormap pixels

Frees the cells represented by pixels whose values are in the pixels unsigned-integer uniform-vector. The planes argument should not have any bits set to 1 in common with any of the pixels. The set of all pixels is produced by ORing together subsets of the planes argument with the pixels. The request frees all of these pixels that were allocated by the client. Note that freeing an individual pixel obtained from X:Alloc-Colormap-Cells with a planes argument may not actually allow it to be reused until all of its related pixels are also freed. Similarly, a read-only entry is not actually freed until it has been freed by all clients, and if a client allocates the same read-only entry multiple times, it must free the entry that many times before the entry is actually freed.

All specified pixels that are allocated by the client in the colormap are freed, even if one or more pixels produce an error. It is an error if a specified pixel is not allocated by the client (that is, is unallocated or is only allocated by another client) or if the colormap was created with all entries writable (by passing ‘x:Alloc-All’ to X:Create-Colormap). If more than one pixel is in error, the one that gets reported is arbitrary.

— Function: x:colormap-find-color colormap rgb

rgb is a list or vector of 3 integers, describing the red, green, and blue intensities respectively; or an integer ‘#xrrggbb’, packing red, green and blue intensities in the range 0 - 255. — Function: x:colormap-find-color colormap color-name

The case-insensitive string color_name specifies the name of a color (for example, red)

X:Colormap-Find-Color allocates a read-only colormap entry corresponding to the closest RGB value supported by the hardware. X:Colormap-Find-Color returns the pixel value of the color closest to the specified RGB or color_name elements supported by the hardware, if successful; otherwise X:Colormap-Find-Color returns #f.

Multiple clients that request the same effective RGB value can be assigned the same read-only entry, thus allowing entries to be shared. When the last client deallocates a shared cell, it is deallocated.

— Function: x:color-ref colormap pixel

Returns a list of 3 integers, describing the red, green, and blue intensities respectively of the colormap entry of the cell indexed by pixel.

The integer pixel must be a valid index into colormap.

— Function: X:Color-Set! colormap pixel rgb

rgb is a list or vector of 3 integers, describing the red, green, and blue intensities respectively; or an integer ‘#xrrggbb’, packing red, green and blue intensities in the range 0 - 255. — Function: X:Color-Set! colormap pixel color-name

The case-insensitive string color_name specifies the name of a color (for example, red)

The integer pixel must be a valid index into colormap.

X:Color-Set! changes the colormap entry of the read/write cell indexed by pixel. If the colormap is an installed map for its screen, the changes are visible immediately.

— Function: x:install-colormap colormap

Installs the specified colormap for its associated screen. All windows associated with colormap immediately display with true colors. A colormap is associated with a window when the window is created or its attributes changed.

If the specified colormap is not already an installed colormap, the X server generates a ColormapNotify event on each window that has that colormap.

— Function: x:ccc colormap

Returns the Color-Conversion-Context of colormap.