XAllocColor(3X) — X Version 11

NAME

XAllocColor, XAllocNamedColor, XAllocColorCells, XAllocColorPlanes, XFreeColors − allocate and free colors

SYNTAX

Status XAllocColor(display, cmap, screen_in_out)
      Display ∗display;
      Colormap cmap;
      XColor ∗screen_in_out;

Status XAllocNamedColor(display, cmap, color_name, visual_def_return, exact_def_return)
      Display ∗display;
      Colormap cmap;
      char ∗color_name;
      XColor ∗visual_def_return, ∗exact_def_return;

Status XAllocColorCells(display, cmap, contig, plane_masks_return, nplanes,
                          pixels_return, ncolors)
      Display ∗display;
      Colormap cmap;
      Bool contig;
      unsigned long plane_masks_return[];
      unsigned int nplanes;
      unsigned long pixels_return[];
      unsigned int ncolors;

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

XFreeColors(display, cmap, pixels, npixels, planes)
      Display ∗display;
      Colormap cmap;
      unsigned long pixels[];
      int npixels;
      unsigned long planes;

ARGUMENTS

cmapSpecifies the color map ID.

color_nameSpecifies the color name string (for example, “red”) whose color definition structure you want returned.

contigSpecifies a boolean value. You pass the value 1 if the planes must be contiguous or the value 0 if the planes do not need to be contiguous.

displaySpecifies the connection to the X server.

exact_def_return
Returns the exact RGB values.

ncolorsSpecifies the number of pixel values that are to be returned in the pixels_return array.

npixelsSpecifies the number of pixels.

nplanesSpecifies the number of plane masks that are to be returned in the plane masks array.

nreds

ngreens

nblues
Specify the number of red, green, and blue colors (shades). The value you pass must be non-negative.

pixelsSpecifies an array of pixel values.

pixels_returnReturns an array of pixel values.

plane_mask_return
Returns an array of plane masks.

planesSpecifies the planes you want to free.

rmask_return

gmask_return

bmask_return
Return bit masks for the red, green, and blue planes.

screen_in_out
Specifies or returns the values actually used in the color map.

visual_def_return
Returns the closest RGB values provided by the hardware.

DESCRIPTION

The XAllocColor function allocates a read-only color map entry corresponding to the closest red, green, and blue values supported by the hardware. XAllocColor returns the pixel value of the color closest to the specified RGB elements supported by the hardware and returns the red, green, and blue values actually used. .PN XAllocColor can generate BadAlloc and BadColor errors.

The XAllocNamedColor function looks up the named color with respect to the screen that is associated with the specified color map. Both the exact data base definition and the closest color supported by the screen are returned. .PN XAllocNamedColor can generate BadAlloc and BadColor errors.

The XAllocColorCells function allocates read/write color cells. The number of colors must be positive and the number of planes nonnegative. .PN XAllocColorCells can generate BadAlloc, BadColor, and BadValue errors.

The XAllocColorPlanes function allocates read/write color resources in a way that is compatible with DirectColor displays. .PN XAllocColorPlanes can generate BadAlloc, BadColor, and BadValue errors.

The XFreeColors function frees the cells represented by pixels whose values are in the pixels array. .PN XFreeColors can generate BadAccess, BadColor, and BadValue errors.

DIAGNOSTICS

BadAccess A client attempted to free a color map entry that it did not already allocate.

BadAccess A client attempted to store into a read-only color map entry.

BadAlloc The server failed to allocate the requested resource or server memory.

BadColor A value for a Colormap argument does not name a defined Colormap.

BadName A font or color of the specified name does not exist.

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.

Museum