


XAllocColor(3X11)					    XAllocColor(3X11)
X11R5									X11R5



NAME
  XAllocColor, XAllocNamedColor, XAllocColorCells, XAllocColorPlanes,
  XFreeColors -	allocate and free colors

SYNTAX

  Status XAllocColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p,	_s_c_r_e_e_n__i_n__o_u_t)
	Display	*_d_i_s_p_l_a_y;
	Colormap _c_o_l_o_r_m_a_p;
	XColor *_s_c_r_e_e_n__i_n__o_u_t;

  Status XAllocNamedColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r__n_a_m_e, _s_c_r_e_e_n__d_e_f__r_e_t_u_r_n,
  _e_x_a_c_t__d_e_f__r_e_t_u_r_n)
	Display	*_d_i_s_p_l_a_y;
	Colormap _c_o_l_o_r_m_a_p;
	char *_c_o_l_o_r__n_a_m_e;
	XColor *_s_c_r_e_e_n__d_e_f__r_e_t_u_r_n, *_e_x_a_c_t__d_e_f__r_e_t_u_r_n;

  Status XAllocColorCells(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_n_t_i_g, _p_l_a_n_e__m_a_s_k_s__r_e_t_u_r_n,
  _n_p_l_a_n_e_s,
			    _p_i_x_e_l_s__r_e_t_u_r_n, _n_p_i_x_e_l_s)
	Display	*_d_i_s_p_l_a_y;
	Colormap _c_o_l_o_r_m_a_p;
	Bool _c_o_n_t_i_g;
	unsigned long _p_l_a_n_e__m_a_s_k_s__r_e_t_u_r_n[];
	unsigned int _n_p_l_a_n_e_s;
	unsigned long _p_i_x_e_l_s__r_e_t_u_r_n[];
	unsigned int _n_p_i_x_e_l_s;

  Status XAllocColorPlanes(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_n_t_i_g, _p_i_x_e_l_s__r_e_t_u_r_n, _n_c_o_l_o_r_s,
	   _n_r_e_d_s, _n_g_r_e_e_n_s, _n_b_l_u_e_s, _r_m_a_s_k__r_e_t_u_r_n, _g_m_a_s_k__r_e_t_u_r_n, _b_m_a_s_k__r_e_t_u_r_n)
	Display	*_d_i_s_p_l_a_y;
	Colormap _c_o_l_o_r_m_a_p;
	Bool _c_o_n_t_i_g;
	unsigned long _p_i_x_e_l_s__r_e_t_u_r_n[];
	int _n_c_o_l_o_r_s;
	int _n_r_e_d_s, _n_g_r_e_e_n_s, _n_b_l_u_e_s;
	unsigned long *_r_m_a_s_k__r_e_t_u_r_n, *_g_m_a_s_k__r_e_t_u_r_n, *_b_m_a_s_k__r_e_t_u_r_n;

  XFreeColors(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _p_i_x_e_l_s, _n_p_i_x_e_l_s, _p_l_a_n_e_s)
	Display	*_d_i_s_p_l_a_y;
	Colormap _c_o_l_o_r_m_a_p;
	unsigned long _p_i_x_e_l_s[];
	int _n_p_i_x_e_l_s;
	unsigned long _p_l_a_n_e_s;

ARGUMENTS

  _c_o_l_o_r__n_a_m_e
	    Specifies the color	name string (for example, red) whose color
	    definition structure you want returned.

  _c_o_l_o_r_m_a_p  Specifies the colormap.

  _c_o_n_t_i_g    Specifies a	Boolean	value that indicates whether the planes	must
	    be contiguous.

  _d_i_s_p_l_a_y   Specifies the connection to	the X server.

  _e_x_a_c_t__d_e_f__r_e_t_u_r_n
	    Returns the	exact RGB values.

  _n_c_o_l_o_r_s   Specifies the number of pixel values that are to be	returned in
	    the	pixels_return array.

  _n_p_i_x_e_l_s   Specifies the number of pixels.

  _n_p_l_a_n_e_s   Specifies the number of plane masks	that are to be returned	in
	    the	plane masks array.

  _n_r_e_d_s
  _n_g_r_e_e_n_s
  _n_b_l_u_e_s
	    Specify the	number of red, green, and blue planes.	The value you
	    pass must be nonnegative.

  _p_i_x_e_l_s    Specifies an array of pixel	values.

  _p_i_x_e_l_s__r_e_t_u_r_n
	    Returns an array of	pixel values.

  _p_l_a_n_e__m_a_s_k__r_e_t_u_r_n
	    Returns an array of	plane masks.

  _p_l_a_n_e_s    Specifies the planes you want to free.

  _r_m_a_s_k__r_e_t_u_r_n
  _g_m_a_s_k__r_e_t_u_r_n
  _b_m_a_s_k__r_e_t_u_r_n
	    Return bit masks for the red, green, and blue planes.

  _s_c_r_e_e_n__d_e_f__r_e_t_u_r_n
	    Returns the	closest	RGB values provided by the hardware.

  _s_c_r_e_e_n__i_n__o_u_t
	    Specifies and returns the values actually used in the colormap.

DESCRIPTION

  The _X_A_l_l_o_c_C_o_l_o_r function allocates a read-only colormap entry	corresponding
  to the closest RGB value supported by	the hardware.  _X_A_l_l_o_c_C_o_l_o_r returns
  the pixel value of the color closest to the specified	RGB elements sup-
  ported by the	hardware and returns the RGB value actually used.  The
  corresponding	colormap cell is read-only.  In	addition, _X_A_l_l_o_c_C_o_l_o_r returns
  nonzero if it	succeeded or zero if it	failed.	 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 deallo-
  cates	a shared cell, it is deallocated.  _X_A_l_l_o_c_C_o_l_o_r does not	use or affect
  the flags in the _X_C_o_l_o_r structure.

  _X_A_l_l_o_c_C_o_l_o_r can generate a _B_a_d_C_o_l_o_r error.

  The _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r function	looks up the named color with respect to the
  screen that is associated with the specified colormap.  It returns both the
  exact	database definition and	the closest color supported by the screen.
  The allocated	color cell is read-only.  The pixel value is returned in
  screen_def_return.  If the color name	is not in the Host Portable Character
  Encoding the result is implementation	dependent.  Use	of uppercase or
  lowercase does not matter.  _X_L_o_o_k_u_p_C_o_l_o_r returns nonzero if a	cell is	allo-
  cated, otherwise it returns zero.

  _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r can generate	a _B_a_d_C_o_l_o_r error.


  The _X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s function	allocates read/write color cells.  The number
  of colors must be positive and the number of planes nonnegative, or a	_B_a_d_-
  _V_a_l_u_e	error results.	If _n_c_o_l_o_r_s and _n_p_l_a_n_e_s are requested, then _n_c_o_l_o_r_s
  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, (_n_c_o_l_o_r_s	* 2**_n_p_l_a_n_e_s) dis-
  tinct	pixels can be produced.	 All of	these are allocated writable by	the
  request.  For	_G_r_a_y_S_c_a_l_e or _P_s_e_u_d_o_C_o_l_o_r, each mask has	exactly	one bit	set
  to 1.	For _D_i_r_e_c_t_C_o_l_o_r, each has exactly three	bits set to 1.	If contig is
  _T_r_u_e and if all masks	are ORed together, a single contiguous set of bits
  set to 1 will	be formed for _G_r_a_y_S_c_a_l_e	or _P_s_e_u_d_o_C_o_l_o_r and three contiguous
  sets of bits set to 1	(one within each pixel subfield) for _D_i_r_e_c_t_C_o_l_o_r.
  The RGB values of the	allocated entries are undefined.  _X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s
  returns nonzero if it	succeeded or zero if it	failed.

  _X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s can generate	_B_a_d_C_o_l_o_r and _B_a_d_V_a_l_u_e errors.

  The specified	_n_c_o_l_o_r_s	must be	positive; and _n_r_e_d_s, _n_g_r_e_e_n_s, and _n_b_l_u_e_s must
  be nonnegative, or a _B_a_d_V_a_l_u_e	error results.	If _n_c_o_l_o_r_s colors, _n_r_e_d_s
  reds,	_n_g_r_e_e_n_s	greens,	and _n_b_l_u_e_s blues are requested,	_n_c_o_l_o_r_s	pixels are
  returned; and	the masks have _n_r_e_d_s, _n_g_r_e_e_n_s, and _n_b_l_u_e_s bits set to 1,
  respectively.	 If contig is _T_r_u_e, 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 _D_i_r_e_c_t_C_o_l_o_r, each mask will lie
  within the corresponding pixel subfield.  By ORing together subsets of
  masks	with each pixel	value, (_n_c_o_l_o_r_s	* 2**(_n_r_e_d_s+_n_g_r_e_e_n_s+_n_b_l_u_e_s) ) dis-
  tinct	pixel values can be produced.

  All of these are allocated by	the request.  However, in the colormap,	there
  are only (_n_c_o_l_o_r_s * 2**_n_r_e_d_s)	independent red	entries, (_n_c_o_l_o_r_s *
  2**_n_g_r_e_e_n_s) independent green	entries, and (_n_c_o_l_o_r_s *	2**_n_b_l_u_e_s) indepen-
  dent blue entries. This is true even for _P_s_e_u_d_o_C_o_l_o_r.	 When the colormap
  entry	of a pixel value is changed (using _X_S_t_o_r_e_C_o_l_o_r_s, _X_S_t_o_r_e_C_o_l_o_r, or
  _X_S_t_o_r_e_N_a_m_e_d_C_o_l_o_r), the pixel is decomposed according to the masks, and the
  corresponding	independent entries are	updated.  _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s returns
  nonzero if it	succeeded or zero if it	failed.

  _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s can	generate _B_a_d_C_o_l_o_r and _B_a_d_V_a_l_u_e errors.

  The _X_F_r_e_e_C_o_l_o_r_s function frees the cells represented by pixels whose values
  are in the pixels array.  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 (using _X_A_l_l_o_c_-
  _C_o_l_o_r, _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r, _X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s, and _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s).  Note
  that freeing an individual pixel obtained from _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s 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. If a specified pixel is
  not a	valid index into the colormap, a _B_a_d_V_a_l_u_e error	results.  If a speci-
  fied 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 _A_l_l_o_c_A_l_l	to _X_C_r_e_a_t_e_C_o_l_o_r_m_a_p), a _B_a_d_A_c_c_e_s_s
  error	results. If more than one pixel	is in error, the one that gets
  reported is arbitrary.

  _X_F_r_e_e_C_o_l_o_r_s can generate _B_a_d_A_c_c_e_s_s, _B_a_d_C_o_l_o_r,	and _B_a_d_V_a_l_u_e errors.




DIAGNOSTICS

  _B_a_d_A_c_c_e_s_s A client attempted to free a colormap entry	that it	did not
	    already allocate.

  _B_a_d_A_c_c_e_s_s A client attempted to store	into a read-only colormap entry.

  _B_a_d_C_o_l_o_r  A value for	a Colormap argument does not name a defined Colormap.

  _B_a_d_V_a_l_u_e  Some numeric value falls outside the range of values accepted by
	    the	request.  Unless a specific range is specified for an argu-
	    ment, 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
  XCreateColormap(3X11), XQueryColor(3X11), XStoreColors(3X11)
  _X_l_i_b - _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e
















































