


XAllocStandardColormap(3X11)			 XAllocStandardColormap(3X11)
X11R5									X11R5



NAME
  XAllocStandardColormap, XSetRGBColormaps, XGetRGBColormaps, XStandardColor-
  map -	allocate, set, or read a standard colormap structure

SYNTAX
  XStandardColormap *XAllocStandardColormap()

  void XSetRGBColormaps(_d_i_s_p_l_a_y, _w, _s_t_d__c_o_l_o_r_m_a_p, _c_o_u_n_t, _p_r_o_p_e_r_t_y)
	Display	*_d_i_s_p_l_a_y;
	Window _w;
	XStandardColormap *_s_t_d__c_o_l_o_r_m_a_p;
	int _c_o_u_n_t;
	Atom _p_r_o_p_e_r_t_y;

  Status XGetRGBColormaps(_d_i_s_p_l_a_y, _w, _s_t_d__c_o_l_o_r_m_a_p__r_e_t_u_r_n, _c_o_u_n_t__r_e_t_u_r_n, _p_r_o_-
  _p_e_r_t_y)
	Display	*_d_i_s_p_l_a_y;
	Window _w;
	XStandardColormap **_s_t_d__c_o_l_o_r_m_a_p__r_e_t_u_r_n;
	int *_c_o_u_n_t__r_e_t_u_r_n;
	Atom _p_r_o_p_e_r_t_y;

ARGUMENTS

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

  _c_o_u_n_t	    Specifies the number of colormaps.

  _c_o_u_n_t__r_e_t_u_r_n
	    Returns the	number of colormaps.

  _p_r_o_p_e_r_t_y  Specifies the property name.

  _s_t_d__c_o_l_o_r_m_a_p
	    Specifies the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure to be used.

  _s_t_d__c_o_l_o_r_m_a_p__r_e_t_u_r_n
	    Returns the	_X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure.

DESCRIPTION
  The _X_A_l_l_o_c_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p function allocates	and returns a pointer to a
  _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure.	Note that all fields in	the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p
  structure are	initially set to zero.	If insufficient	memory is available,
  _X_A_l_l_o_c_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p returns NULL.	To free	the memory allocated to	this
  structure, use _X_F_r_e_e.

  The _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s function	replaces the RGB colormap definition in	the
  specified property on	the named window.  If the property does	not already
  exist, _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s sets the RGB colormap	definition in the specified
  property on the named	window.	 The property is stored	with a type of
  RGB_COLOR_MAP	and a format of	32.  Note that it is the caller's responsi-
  bility to honor the ICCCM restriction	that only RGB_DEFAULT_MAP contain
  more than one	definition.

  The _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s function	usually	is only	used by	window or session
  managers.  To	create a standard colormap, follow this	procedure:

  11..   Open a new connection to	the same server.

  22..   Grab the	server.

  33..   See if the property is on the property list of the root window for the
       screen.

  44..   If the desired property is not present:

       oo++    Create a colormap (unless using the	default	colormap of the
	    screen).

       oo++    Determine the color	characteristics	of the visual.

       oo++    Call _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s or _X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s to allocate cells in
	    the	colormap.

       oo++    Call _X_S_t_o_r_e_C_o_l_o_r_s to store appropriate color values	in the color-
	    map.

       oo++    Fill in the	descriptive members in the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p struc-
	    ture.

       oo++    Attach the property	to the root window.

       oo++    Use	_X_S_e_t_C_l_o_s_e_D_o_w_n_M_o_d_e to make the resource permanent.

  55..   Ungrab the server.

  _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s can generate	_B_a_d_A_l_l_o_c, _B_a_d_A_t_o_m, and _B_a_d_W_i_n_d_o_w errors.

  The _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s function	returns	the RGB	colormap definitions stored
  in the specified property on the named window.  If the property exists, is
  of type RGB_COLOR_MAP, is of format 32, and is long enough to	contain	a
  colormap definition, _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s	allocates and fills in space for the
  returned colormaps and returns a nonzero status.  If the visualid is not
  present, _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s assumes the	default	visual for the screen on
  which	the window is located; if the killid is	not present, _N_o_n_e is assumed,
  which	indicates that the resources cannot be released.  Otherwise, none of
  the fields are set, and _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s returns a zero status.  Note	that
  it is	the caller's responsibility to honor the ICCCM restriction that	only
  RGB_DEFAULT_MAP contain more than one	definition.

  _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s can generate	_B_a_d_A_t_o_m	and _B_a_d_W_i_n_d_o_w errors.

STRUCTURES
  The _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p	structure contains:

  /* Hints */ tab(); l l l.  T{	#define	T}T{ _R_e_l_e_a_s_e_B_y_F_r_e_e_i_n_g_C_o_l_o_r_m_a_p T}T{ (
  (XID)	1L) T} /* Values */

  typedef struct {
	  Colormap colormap;
	  unsigned long	red_max;
	  unsigned long	red_mult;
	  unsigned long	green_max;
	  unsigned long	green_mult;
	  unsigned long	blue_max;
	  unsigned long	blue_mult;
	  unsigned long	base_pixel;
	  VisualID visualid;
	  XID killid;
  } XStandardColormap;

  The colormap member is the colormap created by the _X_C_r_e_a_t_e_C_o_l_o_r_m_a_p func-
  tion.	 The red_max, green_max, and blue_max members give the maximum red,
  green, and blue values, respectively.	Each color coefficient ranges from
  zero to its max, inclusive. For example, a common colormap allocation	is
  3/3/2	(3 planes for red, 3 planes for	green, and 2 planes for	blue). This
  colormap would have red_max =	7, green_max = 7, and blue_max = 3. An alter-
  nate allocation that uses only 216 colors is red_max = 5, green_max =	5,
  and blue_max = 5.

  The red_mult,	green_mult, and	blue_mult members give the scale factors used
  to compose a full pixel value. (See the discussion of	the base_pixel
  members for further information.) For	a 3/3/2	allocation, red_mult might be
  32, green_mult might be 4, and blue_mult might be 1. For a 6-colors-each
  allocation, red_mult might be	36, green_mult might be	6, and blue_mult
  might	be 1.

  The base_pixel member	gives the base pixel value used	to compose a full
  pixel	value. Usually,	the base_pixel is obtained from	a call to the _X_A_l_l_o_c_-
  _C_o_l_o_r_P_l_a_n_e_s function.	Given integer red, green, and blue coefficients	in
  their	appropriate ranges, one	then can compute a corresponding pixel value
  by using the following expression:

  (r * red_mult	+ g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFFF

  For _G_r_a_y_S_c_a_l_e	colormaps, only	the colormap, red_max, red_mult, and
  base_pixel members are defined. The other members are	ignored. To compute a
  _G_r_a_y_S_c_a_l_e pixel value, use the following expression:

  (gray	* red_mult + base_pixel) & 0xFFFFFFFF

  Negative multipliers can be represented by converting	the 2's	complement
  representation of the	multiplier into	an unsigned long and storing the
  result in the	appropriate _mult field.  The step of masking by 0xFFFFFFFF
  effectively converts the resulting positive multiplier into a	negative one.
  The masking step will	take place automatically on many machine architec-
  tures, depending on the size of the integer type used	to do the computa-
  tion.

  The visualid member gives the	ID number of the visual	from which the color-
  map was created.  The	killid member gives a resource ID that indicates
  whether the cells held by this standard colormap are to be released by
  freeing the colormap ID or by	calling	the _X_K_i_l_l_C_l_i_e_n_t	function on the	indi-
  cated	resource.  (Note that this method is necessary for allocating out of
  an existing colormap.)

  The properties containing the	_X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p information have the type
  RGB_COLOR_MAP.

DIAGNOSTICS

  _B_a_d_A_l_l_o_c  The	server failed to allocate the requested	resource or server
	    memory.

  _B_a_d_A_t_o_m   A value for	an Atom	argument does not name a defined Atom.

  _B_a_d_W_i_n_d_o_w A value for	a Window argument does not name	a defined Window.

SEE ALSO
  XAllocColor(3X11), XCreateColormap(3X11), XFree(3X11),
  XSetCloseDownMode(3X11)
  _X_l_i_b - _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e	delim off








