XAllocColorPlanes

Syntax

Status XAllocColorPlanes(display, colormap, contig, pixels_return, ncolors, nreds, ngreens,
                           nblues, rmask_return, gmask_return, bmask_return)
      Display *display;
      Colormap colormap;
      Bool contig;
      unsigned long pixels_return[];
      int ncolors;
      int nreds, ngreens, nblues;
      unsigned long *rmask_return, *gmask_return, *bmask_return;

Arguments

display	Specifies the connection to the X server.
colormap	Specifies the colormap.
contig	Specifies a Boolean value that indicates whether the planes must be contiguous.
pixels_return	Returns an array of pixel values. XAllocColorPlanes() returns the pixel values in this array.
ncolors	Specifies the number of pixel values that are to be returned in the pixels_return array.
nreds ngreens nblues	Specify the number of red, green, and blue planes. The value you pass must be nonnegative.
rmask_return gmask_return bmask_return	Return bit masks for the red, green, and blue planes.

Description

The specified ncolors must be positive; and nreds, ngreens, and nblues must be nonnegative, or a BadValue error results. 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 contig is True, 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. For DirectColor, 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. This is true even for PseudoColor. When the colormap entry of a pixel value is changed (using XStoreColors(), XStoreColor(), or XStoreNamedColor()), the pixel is decomposed according to the masks, and the corresponding independent entries are updated. XAllocColorPlanes() returns nonzero if it succeeded or zero if it failed.

XAllocColorPlanes() can generate BadColor and BadValue errors.

Diagnostics

BadColor	A value for a Colormap argument does not name a defined Colormap.
BadValue	Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

See also

XAllocColor(), XAllocColorCells(), XAllocNamedColor(), XCreateColormap(), XFreeColors(), XQueryColor(), XStoreColors(), "Allocating and Freeing Color Cells".

---

Christophe Tronche, [email protected]