Next: Finding Colors, Previous: Installing Colormaps, Up: Colormap Functions [Contents][Index]
The following paragraphs describe the functions for allocating read-only and read-write color cells, allocating color planes, and freeing color cells.
A colormap.
A color object or a stringable containing a color name.
Returns a pixel for a read-only color cell in the colormap. The color in the allocated cell is the closest approximation to the requested color possible for the screen hardware. The other values returned give both the approximate color stored in the cell and the exact color requested.
The requested color can be either a color object or a stringable containing a color name. If a color name is given, a corresponding color value is looked up (see lookup-color) and used. Color name strings must contain only ISO Latin-1 characters; case is not significant.
Type pixel.
Type color.
A colormap.
A positive number defining the length of the pixels sequence returned.
A non-negative number defining the length of the masks sequence returned.
If true, the masks form contiguous sets of bits.
A subtype of sequence that indicates the type of sequences returned.
Returns a sequence of pixels for read-write color cells in the colormap. The allocated cells contain undefined color values. The visual type class of the colormap must be either :gray-scale, :pseudo-color, or :direct-color.
The colors argument and the :planes argument define the number of pixels and the number of masks returned, respectively. The number of colors must be positive, and the number of planes must be non-negative. A total of (* colors (expt 2 planes)) color cells are allocated. The pixel values for the allocated cells can be computed by combining the returned pixels and masks.
The length of the returned masks sequence is equal to :planes. Each mask of the returned masks sequence defines a single bitplane. None of the masks have any 1 bits in common. Thus, by selectively combining masks with logior, (expt 2 planes) distinct combined plane masks can be computed.
The length of the returned pixels sequence is equal to colors. None of the pixels have any 1 bits in common with each other or with any of the returned masks. By combining pixels and plane masks with logior, (* colors (expt 2 planes)) distinct pixel values can be produced.
If the colormap class is :gray-scale or :pseudo-color, each mask will have exactly one bit set. If the colormap class is :direct-color, each mask will have exactly three bits set. If :contiguous-p is true, combining all masks with logior produces a plane mask with either one set of contiguous bits (for :gray-scale and :pseudo-color) or three sets of contiguous bits (for :direct-color).
Type sequence of pixels.
A colormap.
A positive number defining the length of the pixels sequence returned.
A non-negative number defining the length of the masks sequence returned.
If true, then the masks form contiguous sets of bits.
A subtype of sequence that indicates the type of sequences returned.
Returns a sequence of pixels for read-write color cells in the colormap. The allocated cells contain undefined color values. The visual type class of the colormap must be either :gray-scale, :pseudo-color, or :direct-color.
The colors argument defines the number of pixels returned. The :reds, :greens, and :blues arguments define the number of bits set in the returned red, green, and blue masks, respectively. The number of colors must be positive, and the number of bits for each mask must be non-negative. A total of (* colors (expt 2 (+ reds greens blues))) color cells are allocated. The pixel values for the allocated cells can be computed by combining the returned pixels and masks.
Each mask of the returned masks defines a pixel subfield for the corresponding primary. None of the masks have any 1 bits in common. By selectively combining subsets of the red, green, and blue masks with logior, (expt 2 (+ reds greens blues) distinct combined plane masks can be computed.
The length of the returned pixels sequence is equal to colors. None of the pixels have any 1 bits in common with each other or with any of the returned masks. By combining pixels and plane masks with logior, (* colors (expt 2 (+ reds greens blues)) distinct pixel values can be produced.
If :contiguous-p is true, each of returned masks consists of a set of contiguous bits. If the colormap class is :direct-color, each returned mask lies within the pixel subfield for its primary.
Type sequence of pixel.
Type pixel.
A colormap.
A sequence of pixel values.
A pixel value with no bits in common with any of the pixels.
Frees a set of allocated color cells from the colormap. The pixel values for the freed cells are computed by combining the given pixels sequence and :plane-mask. The total number of cells freed is:
(* (length pixels) (expt 2 (logcount plane-mask)))
The :plane-mask must not have any bits in common with any of the given pixels. The pixel values for the freed cells are produced by using logior to combine each of the given pixels with all subsets of the :plane-mask.
Note that freeing an individual pixel allocated by alloc-color-planes may not allow it to be reused until all related pixels computed from the same plane mask are also freed.
A single error is generated if any computed pixel is invalid or if its color cell is not allocated by the client. Even if an error is generated, all valid pixel values are freed.
Next: Finding Colors, Previous: Installing Colormaps, Up: Colormap Functions [Contents][Index]