xorg-libx11/specs/libX11/CH06.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
                   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id='Color_Management_Functions'>
<title>Color Management Functions</title>
<!-- .sp 2 -->
<!-- .nr H1 6 -->
<!-- .nr H2 0 -->
<!-- .nr H3 0 -->
<!-- .nr H4 0 -->
<!-- .nr H5 0 -->
<!-- .na -->
<para>
<!-- .LP -->
<!-- .XS -->
<!-- Chapter 6: Color Management Functions  -->
<!-- .XE -->
Each X window always has an associated colormap that
provides a level of indirection between pixel values and colors displayed
on the screen.
Xlib provides functions that you can use to manipulate a colormap.
The X protocol defines colors using values in the <acronym>RGB</acronym> color space.
The <acronym>RGB</acronym> color space is device dependent;
rendering an <acronym>RGB</acronym> value on differing output devices typically results
in different colors.
Xlib also provides a means for clients to specify color using
device-independent color spaces for consistent results across devices.
Xlib supports device-independent color spaces derivable from the <acronym>CIE</acronym> XYZ
color space.
This includes the <acronym>CIE</acronym> XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as
the TekHVC color space.
</para>
<para>
<!-- .LP -->
This chapter discusses how to:
</para>
<itemizedlist>
  <listitem>
    <para>
Create, copy, and destroy a colormap
    </para>
  </listitem>
  <listitem>
    <para>
Specify colors by name or value
    </para>
  </listitem>
  <listitem>
    <para>
Allocate, modify, and free color cells
    </para>
  </listitem>
  <listitem>
    <para>
Read entries in a colormap
    </para>
  </listitem>
  <listitem>
    <para>
Convert between color spaces
    </para>
  </listitem>
  <listitem>
    <para>
Control aspects of color conversion
    </para>
  </listitem>
  <listitem>
    <para>
Query the color gamut of a screen
    </para>
  </listitem>
  <listitem>
    <para>
Add new color spaces
    </para>
  </listitem>
</itemizedlist>
<para>
<!-- .LP -->
All functions, types, and symbols in this chapter with the prefix ``Xcms''
are defined in
<filename class="headerfile">&lt;X11/Xcms.h&gt;</filename>.
<indexterm type="file"><primary><filename class="headerfile">X11/Xcms.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xcms.h&gt;</filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xcms.h&gt;</filename></secondary></indexterm>
The remaining functions and types are defined in
<filename class="headerfile">&lt;X11/Xlib.h&gt;</filename>.
<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>
</para>
<para>
<!-- .LP -->
Functions in this chapter manipulate the representation of color on the
screen.
For each possible value that a pixel can take in a window,
there is a color cell in the colormap.
For example,
if a window is 4 bits deep, pixel values 0 through 15 are defined.
A colormap is a collection of color cells.
A color cell consists of a triple of red, green, and blue (<acronym>RGB</acronym>) values.
The hardware imposes limits on the number of significant
bits in these values.
As each pixel is read out of display memory, the pixel
is looked up in a colormap.
The <acronym>RGB</acronym> value of the cell determines what color is displayed on the screen.
On a grayscale display with a black-and-white monitor,
the values are combined to determine the brightness on the screen.
</para>
<para>
<!-- .LP -->
Typically, an application allocates color cells or sets of color cells
to obtain the desired colors.
The client can allocate read-only cells.
In which case,
the pixel values for these colors can be shared among multiple applications,
and the <acronym>RGB</acronym> value of the cell cannot be changed.
If the client allocates read/write cells,
they are exclusively owned by the client,
and the color associated with the pixel value can be changed at will.
Cells must be allocated (and, if read/write, initialized with an <acronym>RGB</acronym> value)
by a client to obtain desired colors.
The use of pixel value for an
unallocated cell results in an undefined color.
</para>
<para>
<!-- .LP -->
Because colormaps are associated with windows, X supports displays
with multiple colormaps and, indeed, different types of colormaps.
If there are insufficient colormap resources in the display,
some windows will display in their true colors, and others
will display with incorrect colors.
A window manager usually controls which windows are displayed
in their true colors if more than one colormap is required for
the color resources the applications are using.
At any time, there is a set of installed colormaps for a screen.
Windows using one of the installed colormaps display with true colors, and
windows using other colormaps generally display with incorrect colors.
You can control the set of installed colormaps by using
<xref linkend='XInstallColormap' xrefstyle='select: title'/>
and
<xref linkend='XUninstallColormap' xrefstyle='select: title'/>.
</para>
<para>
<!-- .LP -->
Colormaps are local to a particular screen.
Screens always have a default colormap,
and programs typically allocate cells out of this colormap.
Generally, you should not write applications that monopolize
color resources.
Although some hardware supports multiple colormaps installed at one time,
many of the hardware displays
built today support only a single installed colormap, so the primitives
are written to encourage sharing of colormap entries between applications.
</para>
<para>
<!-- .LP -->
The
<function>DefaultColormap</function>
macro returns the default colormap.
The
<function>DefaultVisual</function>
macro
returns the default visual type for the specified screen.
<indexterm><primary>Color map</primary></indexterm>
Possible visual types are
<symbol>StaticGray</symbol>,
<symbol>GrayScale</symbol>,
<symbol>StaticColor</symbol>,
<symbol>PseudoColor</symbol>,
<symbol>TrueColor</symbol>,
or
<symbol>DirectColor</symbol>
(see <link linkend="Visual_Types">section 3.1</link>).
</para>
<sect1 id="Color_Structures">
<title>Color Structures</title>
<!-- .XS -->
<!-- (SN Color Structures -->
<!-- .XE -->
<para>
<!-- .LP -->
Functions that operate only on <acronym>RGB</acronym> color space values use an
<structname>XColor</structname>
structure, which contains:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XColor</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
	unsigned long pixel;	/* pixel value */
	unsigned short red, green, blue;	/* rgb values */
	char flags;	/* DoRed, DoGreen, DoBlue */
	char pad;
} XColor;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The red, green, and blue values are always in the range 0 to 65535
inclusive, independent of the number of bits actually used in the
display hardware.
The server scales these values down to the range used by the hardware.
Black is represented by (0,0,0),
and white is represented by (65535,65535,65535).
<indexterm><primary>Color</primary></indexterm>
In some functions,
the flags member controls which of the red, green, and blue members is used
and can be the inclusive OR of zero or more of
<symbol>DoRed</symbol>,
<symbol>DoGreen</symbol>,
and
<symbol>DoBlue</symbol>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
Functions that operate on all color space values use an
<structname>XcmsColor</structname>
structure.
This structure contains a union of substructures,
each supporting color specification encoding for a particular color space.
Like the
<structname>XColor</structname>
structure, the
<structname>XcmsColor</structname>
structure contains pixel
and color specification information (the spec member in the
<structname>XcmsColor</structname>
structure).
<indexterm significance="preferred"><primary>XcmsColor</primary></indexterm>
<!-- .sM -->
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 1i 2.5i -->
<!-- .ta .5i 1i 2.5i -->
typedef unsigned long XcmsColorFormat;			/* Color Specification Format */

typedef struct {
	union {
		XcmsRGB RGB;
		XcmsRGBi RGBi;
		XcmsCIEXYZ CIEXYZ;
		XcmsCIEuvY CIEuvY;
		XcmsCIExyY CIExyY;
		XcmsCIELab CIELab;
		XcmsCIELuv CIELuv;
		XcmsTekHVC TekHVC;
		XcmsPad Pad;
	} spec;
	unsigned long pixel;
	XcmsColorFormat format;
} XcmsColor;			/* Xcms Color Structure */
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
Because the color specification can be encoded for the various color spaces,
encoding for the spec member is identified by the format member,
which is of type
<type>XcmsColorFormat</type>.
The following macros define standard formats.
<!-- .sM -->
</para>

<literallayout class="monospaced">
#define          XcmsUndefinedFormat   0x00000000
#define          XcmsCIEXYZFormat      0x00000001  /* CIE XYZ */
#define          XcmsCIEuvYFormat      0x00000002  /* CIE u'v'Y */
#define          XcmsCIExyYFormat      0x00000003  /* CIE xyY */
#define          XcmsCIELabFormat      0x00000004  /* CIE L*a*b* */
#define          XcmsCIELuvFormat      0x00000005  /* CIE L*u*v* */
#define          XcmsTekHVCFormat      0x00000006  /* TekHVC */
#define          XcmsRGBFormat         0x80000000  /* RGB Device */
#define          XcmsRGBiFormat        0x80000001  /* RGB Intensity */
</literallayout>

<para>
<!-- .LP -->
<!-- .eM -->
Formats for device-independent color spaces are
distinguishable from those for device-dependent spaces by the 32nd bit.
If this bit is set,
it indicates that the color specification is in a device-dependent form;
otherwise, it is in a device-independent form.
If the 31st bit is set,
this indicates that the color space has been added to Xlib at run time
(see <link linkend="Creating_Additional_Color_Spaces">section 6.12.4</link>).
The format value for a color space added at run time may be different each
time the program is executed.
If references to such a color space must be made outside the client
(for example, storing a color specification in a file),
then reference should be made by color space string prefix
(see
<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>
and
<xref linkend='XcmsPrefixOfFormat' xrefstyle='select: title'/>).
</para>
<para>
<!-- .LP -->
Data types that describe the color specification encoding for the various
color spaces are defined as follows:
<!-- .sM -->
<indexterm significance="preferred"><primary>XcmsRGB</primary></indexterm>
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef double XcmsFloat;

typedef struct {
	unsigned short red;	/* 0x0000 to 0xffff */
	unsigned short green;	/* 0x0000 to 0xffff */
	unsigned short blue;	/* 0x0000 to 0xffff */
} XcmsRGB;		/* RGB Device */
</literallayout>
<indexterm significance="preferred"><primary>XcmsRGBi</primary></indexterm>
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
	XcmsFloat red;	/* 0.0 to 1.0 */
	XcmsFloat green;	/* 0.0 to 1.0 */
	XcmsFloat blue;	/* 0.0 to 1.0 */
} XcmsRGBi;		/* RGB Intensity */
</literallayout>
<indexterm significance="preferred"><primary>XcmsCIEXYZ</primary></indexterm>
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
	XcmsFloat X;
	XcmsFloat Y;	/* 0.0 to 1.0 */
	XcmsFloat Z;
} XcmsCIEXYZ;		/* CIE XYZ */
</literallayout>
<indexterm significance="preferred"><primary>XcmsCIEuvY</primary></indexterm>
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
	XcmsFloat u_prime;	/* 0.0 to ~0.6 */
	XcmsFloat v_prime;	/* 0.0 to ~0.6 */
	XcmsFloat Y; 	/* 0.0 to 1.0 */
} XcmsCIEuvY;		/* CIE u'v'Y */
</literallayout>
<indexterm significance="preferred"><primary>XcmsCIExyY</primary></indexterm>
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
	XcmsFloat x; 	/* 0.0 to ~.75 */
	XcmsFloat y; 	/* 0.0 to ~.85 */
	XcmsFloat Y; 	/* 0.0 to 1.0 */
} XcmsCIExyY;		/* CIE xyY */
</literallayout>
<indexterm significance="preferred"><primary>XcmsCIELab</primary></indexterm>
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
	XcmsFloat L_star; 	/* 0.0 to 100.0 */
	XcmsFloat a_star;
	XcmsFloat b_star;
} XcmsCIELab;		/* CIE L*a*b* */
</literallayout>
<indexterm significance="preferred"><primary>XcmsCIELuv</primary></indexterm>
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
	XcmsFloat L_star; 	/* 0.0 to 100.0 */
	XcmsFloat u_star;
	XcmsFloat v_star;
} XcmsCIELuv;		/* CIE L*u*v* */
</literallayout>
<indexterm significance="preferred"><primary>XcmsTekHVC</primary></indexterm>
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
	XcmsFloat H; 	/* 0.0 to 360.0 */
	XcmsFloat V; 	/* 0.0 to 100.0 */
	XcmsFloat C; 	/* 0.0 to 100.0 */
} XcmsTekHVC;		/* TekHVC */
</literallayout>
<indexterm significance="preferred"><primary>XcmsPad</primary></indexterm>
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
	XcmsFloat pad0;
	XcmsFloat pad1;
	XcmsFloat pad2;
	XcmsFloat pad3;
} XcmsPad;		/* four doubles */
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The device-dependent formats provided allow color specification in:
</para>
<itemizedlist>
  <listitem>
    <para>
<acronym>RGB</acronym> Intensity
(<structname>XcmsRGBi</structname>)
    </para>
  </listitem>
  <listitem>
    <para>
Red, green, and blue linear intensity values,
floating-point values from 0.0 to 1.0,
where 1.0 indicates full intensity, 0.5 half intensity, and so on.
    </para>
  </listitem>
  <listitem>
    <para>
<acronym>RGB</acronym> Device
(<structname>XcmsRGB</structname>)
    </para>
  </listitem>
  <listitem>
    <para>
Red, green, and blue values appropriate for the specified output device.
<structname>XcmsRGB</structname>
values are of type unsigned short,
scaled from 0 to 65535 inclusive,
and are interchangeable with the red, green, and blue values in an
<structname>XColor</structname>
structure.
    </para>
  </listitem>
</itemizedlist>
<para>
<!-- .LP -->
It is important to note that <acronym>RGB</acronym> Intensity values are not gamma corrected
values.
In contrast,
<acronym>RGB</acronym> Device values generated as a result of converting color specifications
are always gamma corrected, and
<acronym>RGB</acronym> Device values acquired as a result of querying a colormap
or passed in by the client are assumed by Xlib to be gamma corrected.
The term <emphasis remap='I'><acronym>RGB</acronym> value</emphasis> in this manual always refers to an <acronym>RGB</acronym> Device value.
</para>
</sect1>
<sect1 id="Color_Strings">
<title>Color Strings</title>
<!-- .XS -->
<!-- (SN Color Strings -->
<!-- .XE -->
<para>
<!-- .LP -->
Xlib provides a mechanism for using string names for colors.
A color string may either contain an abstract color name
or a numerical color specification.
Color strings are case-insensitive.
</para>
<para>
<!-- .LP -->
Color strings are used in the following functions:
</para>
<itemizedlist>
  <listitem>
    <para>
<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>
    </para>
  </listitem>
  <listitem>
    <para>
<xref linkend='XcmsAllocNamedColor' xrefstyle='select: title'/>
    </para>
  </listitem>
  <listitem>
    <para>
<xref linkend='XLookupColor' xrefstyle='select: title'/>
    </para>
  </listitem>
  <listitem>
    <para>
<xref linkend='XcmsLookupColor' xrefstyle='select: title'/>
    </para>
  </listitem>
  <listitem>
    <para>
<xref linkend='XParseColor' xrefstyle='select: title'/>
    </para>
  </listitem>
  <listitem>
    <para>
<xref linkend='XStoreNamedColor' xrefstyle='select: title'/>
    </para>
  </listitem>
</itemizedlist>
<para>
<!-- .LP -->
Xlib supports the use of abstract color names, for example, red or blue.
A value for this abstract name is obtained by searching one or more color
name databases.
Xlib first searches zero or more client-side databases;
the number, location, and content of these databases is
implementation-dependent and might depend on the current locale.
If the name is not found, Xlib then looks for the color in the
X server's database.
If the color name is not in the Host Portable Character Encoding,
the result is implementation-dependent.
</para>
<para>
<!-- .LP -->
A numerical color specification
consists of a color space name and a set of values in the following syntax:
</para>
<para>
<!-- .LP -->
<!-- .sM -->
<literallayout class="monospaced">
<emphasis remap='I'>&lt;color_space_name&gt;</emphasis>:<emphasis remap='I'>&lt;value&gt;/.../&lt;value&gt;</emphasis>
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The following are examples of valid color strings.
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
"CIEXYZ:0.3227/0.28133/0.2493"
"RGBi:1.0/0.0/0.0"
"rgb:00/ff/00"
"CIELuv:50.0/0.0/0.0"
</literallayout>
The syntax and semantics of numerical specifications are given
for each standard color space in the following sections.
</para>
<sect2 id="RGB_Device_String_Specification">
<title><acronym>RGB</acronym> Device String Specification</title>
<!-- .XS -->
<!-- (SN <acronym>RGB</acronym> Device String Specification -->
<!-- .XE -->
<para>
<!-- .LP -->
An <acronym>RGB</acronym> Device specification is identified by
the prefix ``rgb:'' and conforms to the following syntax:
</para>
<para>
<!-- .LP -->
<!-- .\" Start marker code here -->
<literallayout class="monospaced">
rgb:<emphasis remap='I'>&lt;red&gt;/&lt;green&gt;/&lt;blue&gt;</emphasis>

    <emphasis remap='I'>&lt;red&gt;</emphasis>, <emphasis remap='I'>&lt;green&gt;</emphasis>, <emphasis remap='I'>&lt;blue&gt;</emphasis> := <emphasis remap='I'>h</emphasis> | <emphasis remap='I'>hh</emphasis> | <emphasis remap='I'>hhh</emphasis> | <emphasis remap='I'>hhhh</emphasis>
    <emphasis remap='I'>h</emphasis> := single hexadecimal digits (case insignificant)
</literallayout>
<!-- .\" End marker code here -->
</para>
<para>
<!-- .LP -->
Note that <emphasis remap='I'>h</emphasis> indicates the value scaled in 4 bits,
<emphasis remap='I'>hh</emphasis> the value scaled in 8 bits,
<emphasis remap='I'>hhh</emphasis> the value scaled in 12 bits,
and <emphasis remap='I'>hhhh</emphasis> the value scaled in 16 bits, respectively.
</para>
<para>
<!-- .LP -->
Typical examples are the strings ``rgb:ea/75/52'' and ``rgb:ccc/320/320'',
but mixed numbers of hexadecimal digit strings
(``rgb:ff/a5/0'' and ``rgb:ccc/32/0'')
are also allowed.
</para>
<para>
<!-- .LP -->
For backward compatibility, an older syntax for <acronym>RGB</acronym> Device is
supported, but its continued use is not encouraged.
The syntax is an initial sharp sign character followed by
a numeric specification, in one of the following formats:
</para>
<para>
<!-- .LP -->
<!-- .\" Start marker code here -->
<literallayout class="monospaced">
<!-- .TA 2i -->
<!-- .ta 2i -->
#RGB	(4 bits each)
#RRGGBB	(8 bits each)
#RRRGGGBBB	(12 bits each)
#RRRRGGGGBBBB	(16 bits each)
</literallayout>
<!-- .\" End marker code here -->
</para>
<para>
<!-- .LP -->
The R, G, and B represent single hexadecimal digits.
When fewer than 16 bits each are specified,
they represent the most significant bits of the value
(unlike the ``rgb:'' syntax, in which values are scaled).
For example, the string ``#3a7'' is the same as ``#3000a0007000''.
</para>
</sect2>
<sect2 id="RGB_Intensity_String_Specification">
<title><acronym>RGB</acronym> Intensity String Specification</title>
<!-- .XS -->
<!-- (SN RGB Intensity String Specification -->
<!-- .XE -->
<para>
<!-- .LP -->
An <acronym>RGB</acronym> intensity specification is identified
by the prefix ``rgbi:'' and conforms to the following syntax:
</para>
<para>
<!-- .LP -->
<!-- .\" Start marker code here -->
<literallayout class="monospaced">
rgbi:<emphasis remap='I'>&lt;red&gt;/&lt;green&gt;/&lt;blue&gt;</emphasis>
</literallayout>
<!-- .\" End marker code here -->
</para>
<para>
<!-- .LP -->
Note that red, green, and blue are floating-point values
between 0.0 and 1.0, inclusive.
The input format for these values is an optional sign,
a string of numbers possibly containing a decimal point,
and an optional exponent field containing an E or e
followed by a possibly signed integer string.
</para>
</sect2>
<sect2 id="Device_Independent_String_Specifications">
<title>Device-Independent String Specifications</title>
<!-- .XS -->
<!-- (SN Device-Independent String Specifications -->
<!-- .XE -->
<para>
<!-- .LP -->
The standard device-independent string specifications have
the following syntax:
</para>
<para>
<!-- .LP -->
<!-- .\" Start marker code here -->
<literallayout class="monospaced">
CIEXYZ:<emphasis remap='I'>&lt;X&gt;/&lt;Y&gt;/&lt;Z&gt;</emphasis>
CIEuvY:<emphasis remap='I'>&lt;u&gt;/&lt;v&gt;/&lt;Y&gt;</emphasis>
CIExyY:<emphasis remap='I'>&lt;x&gt;/&lt;y&gt;/&lt;Y&gt;</emphasis>
CIELab:<emphasis remap='I'>&lt;L&gt;/&lt;a&gt;/&lt;b&gt;</emphasis>
CIELuv:<emphasis remap='I'>&lt;L&gt;/&lt;u&gt;/&lt;v&gt;</emphasis>
TekHVC:<emphasis remap='I'>&lt;H&gt;/&lt;V&gt;/&lt;C&gt;</emphasis>
</literallayout>
<!-- .\" End marker code here -->
</para>
<para>
<!-- .LP -->
All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are
floating-point values.
The syntax for these values is an optional plus or minus sign,
a string of digits possibly containing a decimal point,
and an optional exponent field consisting of an ``E'' or ``e''
followed by an optional plus or minus followed by a string of digits.
</para>
</sect2>
</sect1>
<sect1 id="Color_Conversion_Contexts_and_Gamut_Mapping">
<title>Color Conversion Contexts and Gamut Mapping</title>
<!-- .XS -->
<!-- (SN Color Conversion Contexts and Gamut Mapping -->
<!-- .XE -->
<para>
<!-- .LP -->
When Xlib converts device-independent color specifications
into device-dependent specifications and vice versa,
it uses knowledge about the color limitations of the screen hardware.
This information, typically called the device profile,
<indexterm><primary>Device profile</primary></indexterm>
is available in a Color Conversion Context (CCC).
<indexterm><primary>Color Conversion Context</primary></indexterm>
<indexterm><primary>CCC</primary></indexterm>
</para>
<para>
<!-- .LP -->
Because a specified color may be outside the color gamut of the target screen
and the white point associated with the color specification may differ
from the white point inherent to the screen,
Xlib applies gamut mapping when it encounters certain conditions:
<indexterm><primary>White point</primary></indexterm>
</para>
<itemizedlist>
  <listitem>
    <para>
Gamut compression occurs when conversion of device-independent
color specifications to device-dependent color specifications
results in a color out of the target screen's gamut.
    </para>
  </listitem>
  <listitem>
    <para>
White adjustment occurs when the inherent white point of the screen
differs from the white point assumed by the client.
    </para>
  </listitem>
</itemizedlist>
<para>
<!-- .LP -->
Gamut handling methods are stored as callbacks in the CCC,
which in turn are used by the color space conversion routines.
Client data is also stored in the CCC for each callback.
The CCC also contains the white point the client assumes to be
associated with color specifications (that is, the Client White Point).
<indexterm><primary>Client White Point</primary></indexterm>
<indexterm><primary>Gamut compression</primary></indexterm>
<indexterm><primary>Gamut handling</primary></indexterm>
<indexterm><primary>White point adjustment</primary></indexterm>
The client can specify the gamut handling callbacks and client data
as well as the Client White Point.
Xlib does not preclude the X client from performing other
forms of gamut handling (for example, gamut expansion);
however, Xlib does not provide direct support for gamut handling
other than white adjustment and gamut compression.
</para>
<para>
<!-- .LP -->
Associated with each colormap is an initial CCC transparently generated by
Xlib.
<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>
Therefore,
when you specify a colormap as an argument to an Xlib function,
you are indirectly specifying a CCC.
<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>
<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>
There is a default CCC associated with each screen.
Newly created CCCs inherit attributes from the default CCC,
so the default CCC attributes can be modified to affect new CCCs.
<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>
<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>
</para>
<para>
<!-- .LP -->
Xcms functions in which gamut mapping can occur return
<type>Status</type>
and have specific status values defined for them,
as follows:
</para>
<itemizedlist>
  <listitem>
    <para>
<symbol>XcmsFailure</symbol>
indicates that the function failed.
    </para>
  </listitem>
  <listitem>
    <para>
<symbol>XcmsSuccess</symbol>
indicates that the function succeeded.
In addition,
if the function performed any color conversion,
the colors did not need to be compressed.
    </para>
  </listitem>
  <listitem>
    <para>
<symbol>XcmsSuccessWithCompression</symbol>
indicates the function performed color conversion
and at least one of the colors needed to be compressed.
The gamut compression method is determined by the gamut compression
procedure in the CCC that is specified directly as a function argument
or in the CCC indirectly specified by means of the colormap argument.
    </para>
  </listitem>
</itemizedlist>
</sect1>
<sect1 id="Creating_Copying_and_Destroying_Colormaps">
<title>Creating, Copying, and Destroying Colormaps</title>
<!-- .XS -->
<!-- (SN Creating, Copying, and Destroying Colormaps -->
<!-- .XE -->
<para>
<!-- .LP -->
To create a colormap for a screen, use
<xref linkend='XCreateColormap' xrefstyle='select: title'/>.</para>
<indexterm significance="preferred"><primary>XCreateColormap</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XCreateColormap'>
<funcprototype>
  <funcdef>Colormap <function>XCreateColormap</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Window <parameter>w</parameter></paramdef>
  <paramdef>Visual *<parameter>visual</parameter></paramdef>
  <paramdef>int <parameter>alloc</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the window on whose screen you want to create a colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>visual</emphasis>
    </term>
    <listitem>
      <para>
Specifies a visual type supported on the screen.
If the visual type is not one supported by the screen,
a
<errorname>BadMatch</errorname>
error results.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>alloc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap entries to be allocated.
You can pass
<symbol>AllocNone</symbol>
or
<symbol>AllocAll</symbol>.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XCreateColormap' xrefstyle='select: title'/>
function creates a colormap of the specified visual type for the screen
on which the specified window resides and returns the colormap ID
associated with it.
Note that the specified window is only used to determine the screen.
</para>
<para>
<!-- .LP -->
The initial values of the colormap entries are undefined for the
visual classes
<symbol>GrayScale</symbol>,
<symbol>PseudoColor</symbol>,
and
<symbol>DirectColor</symbol>.
For
<symbol>StaticGray</symbol>,
<symbol>StaticColor</symbol>,
and
<symbol>TrueColor</symbol>,
the entries have defined values,
but those values are specific to the visual and are not defined by X.
For
<symbol>StaticGray</symbol>,
<symbol>StaticColor</symbol>,
and
<symbol>TrueColor</symbol>,
alloc must be
<symbol>AllocNone</symbol>,
or a
<errorname>BadMatch</errorname>
error results.
For the other visual classes,
if alloc is
<symbol>AllocNone</symbol>,
the colormap initially has no allocated entries,
and clients can allocate them.
For information about the visual types,
see <link linkend="Visual_Types">section 3.1</link>.
</para>
<para>
<!-- .LP -->
If alloc is
<symbol>AllocAll</symbol>,
the entire colormap is allocated writable.
The initial values of all allocated entries are undefined.
For
<symbol>GrayScale</symbol>
and
<symbol>PseudoColor</symbol>,
the effect is as if an
<xref linkend='XAllocColorCells' xrefstyle='select: title'/>
call returned all pixel values from zero to N - 1,
where N is the colormap entries value in the specified visual.
For
<symbol>DirectColor</symbol>,
the effect is as if an
<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
call returned a pixel value of zero and red_mask, green_mask,
and blue_mask values containing the same bits as the corresponding
masks in the specified visual.
However, in all cases,
none of these entries can be freed by using
<xref linkend='XFreeColors' xrefstyle='select: title'/>.
</para>
<para>
<!-- .LP -->
<xref linkend='XCreateColormap' xrefstyle='select: title'/>
can generate
<errorname>BadAlloc</errorname>,
<errorname>BadMatch</errorname>,
<errorname>BadValue</errorname>,
and
<errorname>BadWindow</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To create a new colormap when the allocation out of a previously
shared colormap has failed because of resource exhaustion, use
<xref linkend='XCopyColormapAndFree' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XCopyColormapAndFree</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XCopyColormapAndFree'>
<funcprototype>
  <funcdef>Colormap <function>XCopyColormapAndFree</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XCopyColormapAndFree' xrefstyle='select: title'/>
function creates a colormap of the same visual type and for the same screen
as the specified colormap and returns the new colormap ID.
It also moves all of the client's existing allocation from the specified
colormap to the new colormap with their color values intact
and their read-only or writable characteristics intact and frees those entries
in the specified colormap.
Color values in other entries in the new colormap are undefined.
If the specified colormap was created by the client with alloc set to
<symbol>AllocAll</symbol>,
the new colormap is also created with
<symbol>AllocAll</symbol>,
all color values for all entries are copied from the specified colormap,
and then all entries in the specified colormap are freed.
If the specified colormap was not created by the client with
<symbol>AllocAll</symbol>,
the allocations to be moved are all those pixels and planes
that have been allocated by the client using
<xref linkend='XAllocColor' xrefstyle='select: title'/>,
<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>,
<xref linkend='XAllocColorCells' xrefstyle='select: title'/>,
or
<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
and that have not been freed since they were allocated.
</para>
<para>
<!-- .LP -->
<xref linkend='XCopyColormapAndFree' xrefstyle='select: title'/>
can generate
<errorname>BadAlloc</errorname>
and
<errorname>BadColor</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To destroy a colormap, use
<xref linkend='XFreeColormap' xrefstyle='select: title'/>.
<indexterm significance="preferred"><primary>XFreeColormap</primary></indexterm>
</para>
<!-- .sM -->
<funcsynopsis id='XFreeColormap'>
<funcprototype>
  <funcdef><function>XFreeColormap</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap that you want to destroy.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XFreeColormap' xrefstyle='select: title'/>
function deletes the association between the colormap resource ID
and the colormap and frees the colormap storage.
However, this function has no effect on the default colormap for a screen.
If the specified colormap is an installed map for a screen,
it is uninstalled (see
<xref linkend='XUninstallColormap' xrefstyle='select: title'/>).
If the specified colormap is defined as the colormap for a window (by
<xref linkend='XCreateWindow' xrefstyle='select: title'/>,
<xref linkend='XSetWindowColormap' xrefstyle='select: title'/>,
or
<xref linkend='XChangeWindowAttributes' xrefstyle='select: title'/>),
<xref linkend='XFreeColormap' xrefstyle='select: title'/>
changes the colormap associated with the window to
<symbol>None</symbol>
and generates a
<symbol>ColormapNotify</symbol>
event.
X does not define the colors displayed for a window with a colormap of
<symbol>None</symbol>.
</para>
<para>
<!-- .LP -->
<xref linkend='XFreeColormap' xrefstyle='select: title'/>
can generate a
<errorname>BadColor</errorname>
error.
</para>
</sect1>
<sect1 id="Mapping_Color_Names_to_Values">
<title>Mapping Color Names to Values</title>
<!-- .XS -->
<!-- (SN Mapping Color Names to Values -->
<!-- .XE -->
<para>
<!-- .LP -->
<!-- .sp -->
To map a color name to an <acronym>RGB</acronym> value, use
<xref linkend='XLookupColor' xrefstyle='select: title'/>.
<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
<indexterm significance="preferred"><primary>XLookupColor</primary></indexterm>
<!-- .sM -->
</para>
<funcsynopsis id='XLookupColor'>
<funcprototype>
  <funcdef>Status <function>XLookupColor</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>char *<parameter>color_name</parameter></paramdef>
  <paramdef>XColor *<parameter>exact_def_return</parameter></paramdef>
  <paramdef>XColor *<parameter>screen_def_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color name string (for example, red) whose color
definition structure you want returned.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>exact_def_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the exact <acronym>RGB</acronym> values.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>screen_def_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the closest <acronym>RGB</acronym> values provided by the hardware.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XLookupColor' xrefstyle='select: title'/>
function looks up the string name of a color with respect to the screen
associated with the specified colormap.
It returns both the exact color values and
the closest values provided by the screen
with respect to the visual type of the specified colormap.
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.
<xref linkend='XLookupColor' xrefstyle='select: title'/>
returns nonzero if the name is resolved;
otherwise, it returns zero.
</para>
<para>
<!-- .LP -->
<xref linkend='XLookupColor' xrefstyle='select: title'/>
can generate a
<errorname>BadColor</errorname>
error.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To map a color name to the exact <acronym>RGB</acronym> value, use
<xref linkend='XParseColor' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
<indexterm significance="preferred"><primary>XParseColor</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XParseColor'>
<funcprototype>
  <funcdef>Status <function>XParseColor</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>char *<parameter>spec</parameter></paramdef>
  <paramdef>XColor *<parameter>exact_def_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>spec</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color name string;
case is ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>exact_def_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the exact color value for later use and sets the
<symbol>DoRed</symbol>,
<symbol>DoGreen</symbol>,
and
<symbol>DoBlue</symbol>
flags.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XParseColor' xrefstyle='select: title'/>
function looks up the string name of a color with respect to the screen
associated with the specified colormap.
It returns the exact color value.
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.
<xref linkend='XParseColor' xrefstyle='select: title'/>
returns nonzero if the name is resolved;
otherwise, it returns zero.
</para>
<para>
<!-- .LP -->
<xref linkend='XParseColor' xrefstyle='select: title'/>
can generate a
<errorname>BadColor</errorname>
error.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To map a color name to a value in an arbitrary color space, use
<xref linkend='XcmsLookupColor' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsLookupColor</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsLookupColor'>
<funcprototype>
  <funcdef>Status <function>XcmsLookupColor</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>char *<parameter>color_string</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_exact_return</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_screen_return</parameter></paramdef>
  <paramdef>XcmsColorFormat <parameter>result_format</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
<!-- .ds St -->
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_string</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color string(St.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_exact_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the color specification parsed from the color string
or parsed from the corresponding string found in a color-name database.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_screen_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the color that can be reproduced on the screen.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>result_format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color format for the returned color
specifications (color_screen_return and color_exact_return arguments).
If the format is
<symbol>XcmsUndefinedFormat</symbol>
and the color string contains a
numerical color specification,
the specification is returned in the format used in that numerical
color specification.
If the format is
<symbol>XcmsUndefinedFormat</symbol>
and the color string contains a color name,
the specification is returned in the format used
to store the color in the database.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsLookupColor' xrefstyle='select: title'/>
function looks up the string name of a color with respect to the screen
associated with the specified colormap.
It returns both the exact color values and
the closest values provided by the screen
with respect to the visual type of the specified colormap.
The values are returned in the format specified by result_format.
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.
<xref linkend='XcmsLookupColor' xrefstyle='select: title'/>
returns
<symbol>XcmsSuccess</symbol>
or
<symbol>XcmsSuccessWithCompression</symbol>
if the name is resolved; otherwise, it returns
<symbol>XcmsFailure</symbol>.
If
<symbol>XcmsSuccessWithCompression</symbol>
is returned, the color specification returned in
color_screen_return is the result of gamut compression.
</para>
</sect1>

<sect1 id="Allocating_and_Freeing_Color_Cells">
<title>Allocating and Freeing Color Cells</title>
<!-- .XS -->
<!-- (SN Allocating and Freeing Color Cells -->
<!-- .XE -->
<para>
<!-- .LP -->
There are two ways of allocating color cells:
explicitly as read-only entries, one pixel value at a time,
or read/write,
where you can allocate a number of color cells and planes simultaneously.
<indexterm><primary>Read-only colormap cells</primary></indexterm>
A read-only cell has its <acronym>RGB</acronym> value set by the server.
<indexterm><primary>Read/write colormap cells</primary></indexterm>
Read/write cells do not have defined colors initially;
functions described in the next section must be used to store values into them.
Although it is possible for any client to store values into a read/write
cell allocated by another client,
read/write cells normally should be considered private to the client
that allocated them.
</para>
<para>
<!-- .LP -->
Read-only colormap cells are shared among clients.
The server counts each allocation and freeing of the cell by clients.
When the last client frees a shared cell, the cell is finally deallocated.
If a single client allocates the same read-only cell multiple
times, the server counts each such allocation, not just the first one.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To allocate a read-only color cell with an <acronym>RGB</acronym> value, use
<xref linkend='XAllocColor' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>
<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>
<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
<indexterm significance="preferred"><primary>XAllocColor</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XAllocColor'>
<funcprototype>
  <funcdef>Status <function>XAllocColor</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>XColor *<parameter>screen_in_out</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>screen_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies and returns the values actually used in the colormap.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XAllocColor' xrefstyle='select: title'/>
function allocates a read-only colormap entry corresponding to the closest
<acronym>RGB</acronym> value supported by the hardware.
<xref linkend='XAllocColor' xrefstyle='select: title'/>
returns the pixel value of the color closest to the specified
<acronym>RGB</acronym> elements supported by the hardware
and returns the <acronym>RGB</acronym> value actually used.
The corresponding colormap cell is read-only.
In addition,
<xref linkend='XAllocColor' xrefstyle='select: title'/>
returns nonzero if it succeeded or zero if it failed.
<indexterm><primary>Color map</primary></indexterm>
<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
<indexterm><primary>Allocation</primary><secondary>colormap</secondary></indexterm>
<indexterm><primary>read-only colormap cells</primary></indexterm>
Multiple clients that request the same effective <acronym>RGB</acronym> value can be assigned
the same read-only entry, thus allowing entries to be shared.
When the last client deallocates a shared cell, it is deallocated.
<xref linkend='XAllocColor' xrefstyle='select: title'/>
does not use or affect the flags in the
<structname>XColor</structname>
structure.
</para>
<para>
<!-- .LP -->
<xref linkend='XAllocColor' xrefstyle='select: title'/>
can generate a
<errorname>BadColor</errorname>
error.
<!-- .EQ -->
delim %%
<!-- .EN -->
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To allocate a read-only color cell with a color in arbitrary format, use
<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>
<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>
<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsAllocColor</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsAllocColor'>
<funcprototype>
  <funcdef>Status <function>XcmsAllocColor</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_in_out</parameter></paramdef>
  <paramdef>XcmsColorFormat <parameter>result_format</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color to allocate and returns the pixel and color
that is actually used in the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>result_format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color format for the returned color specification.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
function is similar to
<xref linkend='XAllocColor' xrefstyle='select: title'/>
except the color can be specified in any format.
The
<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
function ultimately calls
<xref linkend='XAllocColor' xrefstyle='select: title'/>
to allocate a read-only color cell (colormap entry) with the specified color.
<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
first converts the color specified
to an <acronym>RGB</acronym> value and then passes this to
<xref linkend='XAllocColor' xrefstyle='select: title'/>.
<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
returns the pixel value of the color cell and the color specification
actually allocated.
This returned color specification is the result of converting the <acronym>RGB</acronym> value
returned by
<xref linkend='XAllocColor' xrefstyle='select: title'/>
into the format specified with the result_format argument.
If there is no interest in a returned color specification,
unnecessary computation can be bypassed if result_format is set to
<symbol>XcmsRGBFormat</symbol>.
The corresponding colormap cell is read-only.
If this routine returns
<symbol>XcmsFailure</symbol>,
the color_in_out color specification is left unchanged.
</para>
<para>
<!-- .LP -->
<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
can generate a
<errorname>BadColor</errorname>
error.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To allocate a read-only color cell using a color name and return the closest
color supported by the hardware in <acronym>RGB</acronym> format, use
<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>
<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>
<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
<indexterm significance="preferred"><primary>XAllocNamedColor</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XAllocNamedColor'>
<funcprototype>
  <funcdef>Status <function>XAllocNamedColor</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>char *<parameter>color_name</parameter></paramdef>
  <paramdef>XColor *<parameter>screen_def_return</parameter></paramdef>
  <paramdef>XColor *<parameter>exact_def_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color name string (for example, red) whose color
definition structure you want returned.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>screen_def_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the closest <acronym>RGB</acronym> values provided by the hardware.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>exact_def_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the exact <acronym>RGB</acronym> values.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>
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.
If screen_def_return and exact_def_return
point to the same structure, the pixel field will be set correctly,
but the color values are undefined.
<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>
returns nonzero if a cell is allocated;
otherwise, it returns zero.
</para>
<para>
<!-- .LP -->
<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>
can generate a
<errorname>BadColor</errorname>
error.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To allocate a read-only color cell using a color name and return the closest
color supported by the hardware in an arbitrary format, use
<xref linkend='XcmsAllocNamedColor' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Allocation</primary><secondary>read-only colormap cells</secondary></indexterm>
<indexterm><primary>Read-only colormap cells</primary><secondary>allocating</secondary></indexterm>
<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsAllocNamedColor</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsAllocNamedColor'>
<funcprototype>
  <funcdef>Status <function>XcmsAllocNamedColor</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>char *<parameter>color_string</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_screen_return</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_exact_return</parameter></paramdef>
  <paramdef>XcmsColorFormat <parameter>result_format</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_string</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color string whose color definition structure is to be
returned.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_screen_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the pixel value of the color cell and color specification
that actually is stored for that cell.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_exact_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the color specification parsed from the color string
or parsed from the corresponding string found in a color-name database.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>result_format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color format for the returned color
specifications (color_screen_return and color_exact_return arguments).
If the format is
<symbol>XcmsUndefinedFormat</symbol>
and the color string contains a
numerical color specification,
the specification is returned in the format used in that numerical
color specification.
If the format is
<symbol>XcmsUndefinedFormat</symbol>
and the color string contains a color name,
the specification is returned in the format used
to store the color in the database.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsAllocNamedColor' xrefstyle='select: title'/>
function is similar to
<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>
except that the color returned can be in any format specified.
This function
ultimately calls
<xref linkend='XAllocColor' xrefstyle='select: title'/>
to allocate a read-only color cell with
the color specified by a color string.
The color string is parsed into an
<structname>XcmsColor</structname>
structure (see
<xref linkend='XcmsLookupColor' xrefstyle='select: title'/>),
converted
to an <acronym>RGB</acronym> value, and finally passed to
<xref linkend='XAllocColor' xrefstyle='select: title'/>.
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.
</para>
<para>
<!-- .LP -->
This function returns both the color specification as a result
of parsing (exact specification) and the actual color specification
stored (screen specification).
This screen specification is the result of converting the <acronym>RGB</acronym> value
returned by
<xref linkend='XAllocColor' xrefstyle='select: title'/>
into the format specified in result_format.
If there is no interest in a returned color specification,
unnecessary computation can be bypassed if result_format is set to
<symbol>XcmsRGBFormat</symbol>.
If color_screen_return and color_exact_return
point to the same structure, the pixel field will be set correctly,
but the color values are undefined.
</para>
<para>
<!-- .LP -->
<xref linkend='XcmsAllocNamedColor' xrefstyle='select: title'/>
can generate a
<errorname>BadColor</errorname>
error.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To allocate read/write color cell and color plane combinations for a
<symbol>PseudoColor</symbol>
model, use
<xref linkend='XAllocColorCells' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Read/write colormap cells</primary><secondary>allocating</secondary></indexterm>
<indexterm><primary>Allocation</primary><secondary>read/write colormap cells</secondary></indexterm>
<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
<indexterm significance="preferred"><primary>XAllocColorCells</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XAllocColorCells'>
<funcprototype>
  <funcdef>Status <function>XAllocColorCells</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>Bool <parameter>contig</parameter></paramdef>
  <paramdef>unsigned long <parameter>plane_masks_return[]</parameter></paramdef>
  <paramdef>unsigned int <parameter>nplanes</parameter></paramdef>
  <paramdef>unsigned long <parameter>pixels_return[]</parameter></paramdef>
  <paramdef>unsigned int <parameter>npixels</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>contig</emphasis>
    </term>
    <listitem>
      <para>
Specifies a Boolean value that indicates whether the planes must be contiguous.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>plane_mask_return</emphasis>
    </term>
    <listitem>
      <para>
Returns an array of plane masks.
<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>nplanes</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of plane masks that are to be returned in the plane masks
array.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>pixels_return</emphasis>
    </term>
    <listitem>
      <para>
Returns an array of pixel values.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>npixels</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of pixel values that are to be returned in the
pixels_return array.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XAllocColorCells' xrefstyle='select: title'/>
function allocates read/write color cells.
The number of colors must be positive and the number of planes nonnegative,
or a
<errorname>BadValue</errorname>
error results.
If ncolors and nplanes are requested,
then ncolors 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,
ncolors &times; 2<superscript><emphasis>nplanes</emphasis></superscript>
distinct pixels can be produced.
All of these are
allocated writable by the request.
For
<symbol>GrayScale</symbol>
or
<symbol>PseudoColor</symbol>,
each mask has exactly one bit set to 1.
For
<symbol>DirectColor</symbol>,
each has exactly three bits set to 1.
If contig is
<symbol>True</symbol>
and if all masks are ORed
together, a single contiguous set of bits set to 1 will be formed for
<symbol>GrayScale</symbol>
or
<symbol>PseudoColor</symbol>
and three contiguous sets of bits set to 1 (one within each
pixel subfield) for
<symbol>DirectColor</symbol>.
The <acronym>RGB</acronym> values of the allocated
entries are undefined.
<xref linkend='XAllocColorCells' xrefstyle='select: title'/>
returns nonzero if it succeeded or zero if it failed.
</para>
<para>
<!-- .LP -->
<xref linkend='XAllocColorCells' xrefstyle='select: title'/>
can generate
<errorname>BadColor</errorname>
and
<errorname>BadValue</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To allocate read/write color resources for a
<symbol>DirectColor</symbol>
model, use
<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Read/write colormap planes</primary><secondary>allocating</secondary></indexterm>
<indexterm><primary>Allocation</primary><secondary>read/write colormap planes</secondary></indexterm>
<indexterm><primary>Color</primary><secondary>allocation</secondary></indexterm>
<indexterm significance="preferred"><primary>XAllocColorPlanes</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XAllocColorPlanes'>
<funcprototype>
  <funcdef>Status <function>XAllocColorPlanes</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>Bool <parameter>contig</parameter></paramdef>
  <paramdef>unsigned long <parameter>pixels_return[]</parameter></paramdef>
  <paramdef>int <parameter>ncolors</parameter></paramdef>
  <paramdef>int <parameter>nreds</parameter></paramdef>
  <paramdef>int <parameter>ngreens</parameter></paramdef>
  <paramdef>int <parameter>nblues</parameter></paramdef>
  <paramdef>unsigned long *<parameter>rmask_return</parameter></paramdef>
  <paramdef>unsigned long *<parameter>gmask_return</parameter></paramdef>
  <paramdef>unsigned long *<parameter>bmask_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>contig</emphasis>
    </term>
    <listitem>
      <para>
Specifies a Boolean value that indicates whether the planes must be contiguous.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>pixels_return</emphasis>
    </term>
    <listitem>
      <para>
Returns an array of pixel values.
<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
returns the pixel values in this array.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ncolors</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of pixel values that are to be returned in the
pixels_return array.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>nreds</emphasis>
    </term>
    <listitem>
      <para>
<!-- .br -->
<!-- .ns -->
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ngreens</emphasis>
    </term>
    <listitem>
      <para>
<!-- .br -->
<!-- .ns -->
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>nblues</emphasis>
    </term>
    <listitem>
      <para>
<!-- .br -->
<!-- .ns -->
Specify the number of red, green, and blue planes.
The value you pass must be nonnegative.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>rmask_return</emphasis>
    </term>
    <listitem>
      <para>
<!-- .br -->
<!-- .ns -->
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>gmask_return</emphasis>
    </term>
    <listitem>
      <para>
<!-- .br -->
<!-- .ns -->
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>bmask_return</emphasis>
    </term>
    <listitem>
      <para>
Return bit masks for the red, green, and blue planes.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The specified ncolors must be positive;
and nreds, ngreens, and nblues must be nonnegative,
or a
<errorname>BadValue</errorname>
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
<symbol>True</symbol>,
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
<symbol>DirectColor</symbol>,
each mask
will lie within the corresponding pixel subfield.
By ORing together
subsets of masks with each pixel value,
ncolors &times; 2<superscript><emphasis>(nreds+ngreens+nblues)</emphasis></superscript>
distinct pixel values can be produced.
All of these are allocated by the request.
However, in the
colormap, there are only
ncolors &times; 2<superscript><emphasis>nreds</emphasis></superscript>
independent red entries,
ncolors &times; 2<superscript><emphasis>ngreens</emphasis></superscript>
independent green entries, and
ncolors &times; 2<superscript><emphasis>nblues</emphasis></superscript>
independent blue entries.
This is true even for
<symbol>PseudoColor</symbol>.
When the colormap entry of a pixel
value is changed (using
<xref linkend='XStoreColors' xrefstyle='select: title'/>,
<xref linkend='XStoreColor' xrefstyle='select: title'/>,
or
<xref linkend='XStoreNamedColor' xrefstyle='select: title'/>),
the pixel is decomposed according to the masks,
and the corresponding independent entries are updated.
<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
returns nonzero if it succeeded or zero if it failed.
</para>
<para>
<!-- .LP -->
<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
can generate
<errorname>BadColor</errorname>
and
<errorname>BadValue</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<indexterm><primary>Freeing</primary><secondary>colors</secondary></indexterm>
To free colormap cells, use
<xref linkend='XFreeColors' xrefstyle='select: title'/>.
<indexterm significance="preferred"><primary>XFreeColors</primary></indexterm>
<indexterm><primary>Color</primary><secondary>deallocation</secondary></indexterm>
<!-- .sM -->
</para>
<funcsynopsis id='XFreeColors'>
<funcprototype>
  <funcdef><function>XFreeColors</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>unsigned long <parameter>pixels[]</parameter></paramdef>
  <paramdef>int <parameter>npixels</parameter></paramdef>
  <paramdef>unsigned long <parameter>planes</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>pixels</emphasis>
    </term>
    <listitem>
      <para>
Specifies an array of pixel values that map to the cells in the specified
colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>npixels</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of pixels.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>planes</emphasis>
    </term>
    <listitem>
      <para>
Specifies the planes you want to free.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XFreeColors' xrefstyle='select: title'/>
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
<indexterm><primary>XAllocColor</primary></indexterm>
<indexterm><primary>XAllocNamedColor</primary></indexterm>
<indexterm><primary>XAllocColorCells</primary></indexterm>
<indexterm><primary>XAllocColorPlanes</primary></indexterm>
<xref linkend='XAllocColor' xrefstyle='select: title'/>,
<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>,
<xref linkend='XAllocColorCells' xrefstyle='select: title'/>,
and
<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>).
Note that freeing an
individual pixel obtained from
<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
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.
</para>
<para>
<!-- .LP -->
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
<errorname>BadValue</errorname>
error results.
If a specified 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
<symbol>AllocAll</symbol>
to
<xref linkend='XCreateColormap' xrefstyle='select: title'/>),
a
<errorname>BadAccess</errorname>
error results.
If more than one pixel is in error,
the one that gets reported is arbitrary.
</para>
<para>
<!-- .LP -->
<xref linkend='XFreeColors' xrefstyle='select: title'/>
can generate
<errorname>BadAccess</errorname>,
<errorname>BadColor</errorname>,
and
<errorname>BadValue</errorname>
errors.
</para>
</sect1>
<sect1 id="Modifying_and_Querying_Colormap_Cells">
<title>Modifying and Querying Colormap Cells</title>
<!-- .XS -->
<!-- (SN Modifying and Querying Colormap Cells  -->
<!-- .XE -->
<para>
<!-- .LP -->
<!-- .sp -->
To store an <acronym>RGB</acronym> value in a single colormap cell, use
<xref linkend='XStoreColor' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
<indexterm significance="preferred"><primary>XStoreColor</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XStoreColor'>
<funcprototype>
  <funcdef><function>XStoreColor</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>XColor *<parameter>color</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color</emphasis>
    </term>
    <listitem>
      <para>
Specifies the pixel and <acronym>RGB</acronym> values.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XStoreColor' xrefstyle='select: title'/>
function changes the colormap entry of the pixel value specified in the
pixel member of the
<structname>XColor</structname>
structure.
You specified this value in the
pixel member of the
<structname>XColor</structname>
structure.
This pixel value must be a read/write cell and a valid index into the colormap.
If a specified pixel is not a valid index into the colormap,
a
<errorname>BadValue</errorname>
error results.
<xref linkend='XStoreColor' xrefstyle='select: title'/>
also changes the red, green, and/or blue color components.
You specify which color components are to be changed by setting
<symbol>DoRed</symbol>,
<symbol>DoGreen</symbol>,
and/or
<symbol>DoBlue</symbol>
in the flags member of the
<structname>XColor</structname>
structure.
If the colormap is an installed map for its screen,
the changes are visible immediately.
</para>
<para>
<!-- .LP -->
<xref linkend='XStoreColor' xrefstyle='select: title'/>
can generate
<errorname>BadAccess</errorname>,
<errorname>BadColor</errorname>,
and
<errorname>BadValue</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To store multiple <acronym>RGB</acronym> values in multiple colormap cells, use
<xref linkend='XStoreColors' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
<indexterm significance="preferred"><primary>XStoreColors</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XStoreColors'>
<funcprototype>
  <funcdef><function>XStoreColors</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>XColor <parameter>color[]</parameter></paramdef>
  <paramdef>int <parameter>ncolors</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color</emphasis>
    </term>
    <listitem>
      <para>
Specifies an array of color definition structures to be stored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ncolors</emphasis>
    </term>
    <listitem>
      <para>
<!-- .\"Specifies the number of color definition structures.  -->
Specifies the number of
<structname>XColor</structname>
structures in the color definition array.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XStoreColors' xrefstyle='select: title'/>
function changes the colormap entries of the pixel values
specified in the pixel members of the
<structname>XColor</structname>
structures.
You specify which color components are to be changed by setting
<symbol>DoRed</symbol>,
<symbol>DoGreen</symbol>,
and/or
<symbol>DoBlue</symbol>
in the flags member of the
<structname>XColor</structname>
structures.
If the colormap is an installed map for its screen, the
changes are visible immediately.
<xref linkend='XStoreColors' xrefstyle='select: title'/>
changes the specified pixels if they are allocated writable in the colormap
by any client, even if one or more pixels generates an error.
If a specified pixel is not a valid index into the colormap, a
<errorname>BadValue</errorname>
error results.
If a specified pixel either is unallocated or is allocated read-only, a
<errorname>BadAccess</errorname>
error results.
If more than one pixel is in error,
the one that gets reported is arbitrary.
</para>
<para>
<!-- .LP -->
<xref linkend='XStoreColors' xrefstyle='select: title'/>
can generate
<errorname>BadAccess</errorname>,
<errorname>BadColor</errorname>,
and
<errorname>BadValue</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To store a color of arbitrary format in a single colormap cell, use
<xref linkend='XcmsStoreColor' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsStoreColor</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsStoreColor'>
<funcprototype>
  <funcdef>Status <function>XcmsStoreColor</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color cell and the color to store.
Values specified in this
<structname>XcmsColor</structname>
structure remain unchanged on return.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsStoreColor' xrefstyle='select: title'/>
function converts the color specified in the
<structname>XcmsColor</structname>
structure into <acronym>RGB</acronym> values.
It then uses this <acronym>RGB</acronym> specification in an
<structname>XColor</structname>
structure, whose three flags
(<symbol>DoRed</symbol>,
<symbol>DoGreen</symbol>,
and
<symbol>DoBlue</symbol>)
are set, in a call to
<xref linkend='XStoreColor' xrefstyle='select: title'/>
to change the color cell specified by the pixel member of the
<structname>XcmsColor</structname>
structure.
This pixel value must be a valid index for the specified colormap,
and the color cell specified by the pixel value must be a read/write cell.
If the pixel value is not a valid index, a
<errorname>BadValue</errorname>
error results.
If the color cell is unallocated or is allocated read-only, a
<errorname>BadAccess</errorname>
error results.
If the colormap is an installed map for its screen,
the changes are visible immediately.
</para>
<para>
<!-- .LP -->
Note that
<xref linkend='XStoreColor' xrefstyle='select: title'/>
has no return value; therefore, an
<symbol>XcmsSuccess</symbol>
return value from this function indicates that the conversion
to <acronym>RGB</acronym> succeeded and the call to
<xref linkend='XStoreColor' xrefstyle='select: title'/>
was made.
To obtain the actual color stored, use
<xref linkend='XcmsQueryColor' xrefstyle='select: title'/>.
Because of the screen's hardware limitations or gamut compression,
the color stored in the colormap may not be identical
to the color specified.
</para>
<para>
<!-- .LP -->
<xref linkend='XcmsStoreColor' xrefstyle='select: title'/>
can generate
<errorname>BadAccess</errorname>,
<errorname>BadColor</errorname>,
and
<errorname>BadValue</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To store multiple colors of arbitrary format in multiple colormap cells, use
<xref linkend='XcmsStoreColors' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsStoreColors</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsStoreColors'>
<funcprototype>
  <funcdef>Status <function>XcmsStoreColors</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>XcmsColor <parameter>colors[]</parameter></paramdef>
  <paramdef>int <parameter>ncolors</parameter></paramdef>
  <paramdef>Bool <parameter>compression_flags_return[]</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colors</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color specification array of
<structname>XcmsColor</structname>
structures, each specifying a color cell and the color to store in that
cell.
Values specified in the array remain unchanged upon return.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ncolors</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of
<structname>XcmsColor</structname>
structures in the color-specification array.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>compression_flags_return</emphasis>
    </term>
    <listitem>
      <para>
Returns an array of Boolean values indicating compression status.
If a non-NULL pointer is supplied,
each element of the array is set to
<symbol>True</symbol>
if the corresponding color was compressed and
<symbol>False</symbol>
otherwise.
Pass NULL if the compression status is not useful.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsStoreColors' xrefstyle='select: title'/>
function converts the colors specified in the array of
<structname>XcmsColor</structname>
structures into <acronym>RGB</acronym> values and then uses these <acronym>RGB</acronym> specifications in
<structname>XColor</structname>
structures, whose three flags
(<symbol>DoRed</symbol>,
<symbol>DoGreen</symbol>,
and
<symbol>DoBlue</symbol>)
are set, in a call to
<xref linkend='XStoreColors' xrefstyle='select: title'/>
to change the color cells specified by the pixel member of the corresponding
<structname>XcmsColor</structname>
structure.
Each pixel value must be a valid index for the specified colormap,
and the color cell specified by each pixel value must be a read/write cell.
If a pixel value is not a valid index, a
<errorname>BadValue</errorname>
error results.
If a color cell is unallocated or is allocated read-only, a
<errorname>BadAccess</errorname>
error results.
If more than one pixel is in error,
the one that gets reported is arbitrary.
If the colormap is an installed map for its screen,
the changes are visible immediately.
</para>
<para>
<!-- .LP -->
Note that
<xref linkend='XStoreColors' xrefstyle='select: title'/>
has no return value; therefore, an
<symbol>XcmsSuccess</symbol>
return value from this function indicates that conversions
to <acronym>RGB</acronym> succeeded and the call to
<xref linkend='XStoreColors' xrefstyle='select: title'/>
was made.
To obtain the actual colors stored, use
<xref linkend='XcmsQueryColors' xrefstyle='select: title'/>.
Because of the screen's hardware limitations or gamut compression,
the colors stored in the colormap may not be identical
to the colors specified.
</para>
<para>
<!-- .LP -->
<xref linkend='XcmsStoreColors' xrefstyle='select: title'/>
can generate
<errorname>BadAccess</errorname>,
<errorname>BadColor</errorname>,
and
<errorname>BadValue</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To store a color specified by name in a single colormap cell, use
<xref linkend='XStoreNamedColor' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
<indexterm significance="preferred"><primary>XStoreNamedColor</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XStoreNamedColor'>
<funcprototype>
  <funcdef><function>XStoreNamedColor</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>char *<parameter>color</parameter></paramdef>
  <paramdef>unsigned long <parameter>pixel</parameter></paramdef>
  <paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color name string (for example, red).
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>pixel</emphasis>
    </term>
    <listitem>
      <para>
Specifies the entry in the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>flags</emphasis>
    </term>
    <listitem>
      <para>
Specifies which red, green, and blue components are set.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XStoreNamedColor' xrefstyle='select: title'/>
function looks up the named color with respect to the screen associated with
the colormap and stores the result in the specified colormap.
The pixel argument determines the entry in the colormap.
The flags argument determines which of the red, green, and blue components
are set.
You can set this member to the
bitwise inclusive OR of the bits
<symbol>DoRed</symbol>,
<symbol>DoGreen</symbol>,
and
<symbol>DoBlue</symbol>.
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.
If the specified pixel is not a valid index into the colormap, a
<errorname>BadValue</errorname>
error results.
If the specified pixel either is unallocated or is allocated read-only, a
<errorname>BadAccess</errorname>
error results.
</para>
<para>
<!-- .LP -->
<xref linkend='XStoreNamedColor' xrefstyle='select: title'/>
can generate
<errorname>BadAccess</errorname>,
<errorname>BadColor</errorname>,
<errorname>BadName</errorname>,
and
<errorname>BadValue</errorname>
errors.
</para>
<para>
<!-- .LP -->
The
<xref linkend='XQueryColor' xrefstyle='select: title'/>
and
<xref linkend='XQueryColors' xrefstyle='select: title'/>
functions take pixel values in the pixel member of
<structname>XColor</structname>
structures and store in the structures the <acronym>RGB</acronym> values for those
pixels from the specified colormap.
The values returned for an unallocated entry are undefined.
These functions also set the flags member in the
<structname>XColor</structname>
structure to all three colors.
If a pixel is not a valid index into the specified colormap, a
<errorname>BadValue</errorname>
error results.
If more than one pixel is in error,
the one that gets reported is arbitrary.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To query the <acronym>RGB</acronym> value of a single colormap cell, use
<xref linkend='XQueryColor' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
<indexterm significance="preferred"><primary>XQueryColor</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XQueryColor'>
<funcprototype>
  <funcdef><function>XQueryColor</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>XColor *<parameter>def_in_out</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>def_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies and returns the <acronym>RGB</acronym> values for the pixel specified in the structure.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XQueryColor' xrefstyle='select: title'/>
function returns the current <acronym>RGB</acronym> value for the pixel in the
<structname>XColor</structname>
structure and sets the
<symbol>DoRed</symbol>,
<symbol>DoGreen</symbol>,
and
<symbol>DoBlue</symbol>
flags.
</para>
<para>
<!-- .LP -->
<xref linkend='XQueryColor' xrefstyle='select: title'/>
can generate
<errorname>BadColor</errorname>
and
<errorname>BadValue</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To query the <acronym>RGB</acronym> values of multiple colormap cells, use
<xref linkend='XQueryColors' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
<indexterm significance="preferred"><primary>XQueryColors</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XQueryColors'>
<funcprototype>
  <funcdef><function>XQueryColors</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>XColor <parameter>defs_in_out[]</parameter></paramdef>
  <paramdef>int <parameter>ncolors</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>defs_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies and returns an array of color definition structures for the pixel
specified in the structure.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ncolors</emphasis>
    </term>
    <listitem>
      <para>
<!-- .\"Specifies the number of color definition structures.  -->
Specifies the number of
<structname>XColor</structname>
structures in the color definition array.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XQueryColors' xrefstyle='select: title'/>
function returns the <acronym>RGB</acronym> value for each pixel in each
<structname>XColor</structname>
structure and sets the
<symbol>DoRed</symbol>,
<symbol>DoGreen</symbol>,
and
<symbol>DoBlue</symbol>
flags in each structure.

</para>
<para>
<!-- .LP -->
<xref linkend='XQueryColors' xrefstyle='select: title'/>
can generate
<errorname>BadColor</errorname>
and
<errorname>BadValue</errorname>
errors.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To query the color of a single colormap cell in an arbitrary format, use
<xref linkend='XcmsQueryColor' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsQueryColor</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsQueryColor'>
<funcprototype>
  <funcdef>Status <function>XcmsQueryColor</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_in_out</parameter></paramdef>
  <paramdef>XcmsColorFormat <parameter>result_format</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies the pixel member that indicates the color cell to query.
The color specification stored for the color cell is returned in this
<structname>XcmsColor</structname>
structure.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>result_format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color format for the returned color specification.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsQueryColor' xrefstyle='select: title'/>
function obtains the <acronym>RGB</acronym> value
for the pixel value in the pixel member of the specified
<structname>XcmsColor</structname>
structure and then
converts the value to the target format as
specified by the result_format argument.
If the pixel is not a valid index in the specified colormap, a
<errorname>BadValue</errorname>
error results.
</para>
<para>
<!-- .LP -->
<xref linkend='XcmsQueryColor' xrefstyle='select: title'/>
can generate
<errorname>BadColor</errorname>
and
<errorname>BadValue</errorname>
errors.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To query the color of multiple colormap cells in an arbitrary format, use
<xref linkend='XcmsQueryColors' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsQueryColors</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsQueryColors'>
<funcprototype>
  <funcdef>Status <function>XcmsQueryColors</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>XcmsColor <parameter>colors_in_out[]</parameter></paramdef>
  <paramdef>unsigned int <parameter>ncolors</parameter></paramdef>
  <paramdef>XcmsColorFormat <parameter>result_format</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colors_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies an array of
<structname>XcmsColor</structname>
structures, each pixel member indicating the color cell to query.
The color specifications for the color cells are returned in these structures.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ncolors</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of
<structname>XcmsColor</structname>
structures in the color-specification array.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>result_format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color format for the returned color specification.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsQueryColors' xrefstyle='select: title'/>
function obtains the <acronym>RGB</acronym> values
for pixel values in the pixel members of
<structname>XcmsColor</structname>
structures and then
converts the values to the target format as
specified by the result_format argument.
If a pixel is not a valid index into the specified colormap, a
<errorname>BadValue</errorname>
error results.
If more than one pixel is in error,
the one that gets reported is arbitrary.
</para>
<para>
<!-- .LP -->
<xref linkend='XcmsQueryColors' xrefstyle='select: title'/>
can generate
<errorname>BadColor</errorname>
and
<errorname>BadValue</errorname>
errors.
</para>
</sect1>
<sect1 id="Color_Conversion_Context_Functions">
<title>Color Conversion Context Functions</title>
<!-- .XS -->
<!-- (SN Color Conversion Context Functions -->
<!-- .XE -->
<para>
<!-- .LP -->
This section describes functions to create, modify,
and query Color Conversion Contexts (CCCs).
</para>
<para>
<!-- .LP -->
Associated with each colormap is an initial CCC transparently generated by
Xlib.
<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>
Therefore, when you specify a colormap as an argument to a function,
you are indirectly specifying a CCC.
<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>
<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>
The CCC attributes that can be modified by the X client are:
</para>
<itemizedlist>
  <listitem>
    <para>
Client White Point
    </para>
  </listitem>
  <listitem>
    <para>
Gamut compression procedure and client data
    </para>
  </listitem>
  <listitem>
    <para>
White point adjustment procedure and client data
    </para>
  </listitem>
</itemizedlist>
<para>
<!-- .LP -->
The initial values for these attributes are implementation specific.
The CCC attributes for subsequently created CCCs can be defined
by changing the CCC attributes of the default CCC.
<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>
<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>
There is a default CCC associated with each screen.
</para>
<sect2 id="Getting_and_Setting_the_Color_Conversion_Context_of_a_Colormap">
<title>Getting and Setting the Color Conversion Context of a Colormap</title>
<!-- .XS -->
<!-- (SN Getting and Setting the Color Conversion Context of a Colormap -->
<!-- .XE -->
<para>
<!-- .LP -->
<!-- .sp -->
To obtain the CCC associated with a colormap, use
<xref linkend='XcmsCCCOfColormap' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsCCCOfColormap</primary></indexterm>
<indexterm><primary>Colormap</primary><secondary>CCC of</secondary></indexterm>
<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>
<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsCCCOfColormap'>
<funcprototype>
  <funcdef>XcmsCCC <function>XcmsCCCOfColormap</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsCCCOfColormap' xrefstyle='select: title'/>
function returns the CCC associated with the specified colormap.
Once obtained,
the CCC attributes can be queried or modified.
Unless the CCC associated with the specified colormap is changed with
<xref linkend='XcmsSetCCCOfColormap' xrefstyle='select: title'/>,
this CCC is used when the specified colormap is used as an argument
to color functions.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To change the CCC associated with a colormap, use
<xref linkend='XcmsSetCCCOfColormap' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsSetCCCOfColormap</primary></indexterm>
<indexterm><primary>Colormap</primary><secondary>CCC of</secondary></indexterm>
<indexterm><primary>CCC</primary><secondary>of colormap</secondary></indexterm>
<indexterm><primary>Color Conversion Context</primary><secondary>of colormap</secondary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsSetCCCOfColormap'>
<funcprototype>
  <funcdef>XcmsCCC <function>XcmsSetCCCOfColormap</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>Colormap <parameter>colormap</parameter></paramdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colormap</emphasis>
    </term>
    <listitem>
      <para>
Specifies the colormap.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsSetCCCOfColormap' xrefstyle='select: title'/>
function changes the CCC associated with the specified colormap.
It returns the CCC previously associated with the colormap.
If they are not used again in the application,
CCCs should be freed by calling
<xref linkend='XcmsFreeCCC' xrefstyle='select: title'/>.
Several colormaps may share the same CCC without restriction; this
includes the CCCs generated by Xlib with each colormap.  Xlib, however,
creates a new CCC with each new colormap.
</para>
</sect2>
<sect2 id="Obtaining_the_Default_Color_Conversion_Context">
<title>Obtaining the Default Color Conversion Context</title>
<!-- .XS -->
<!-- (SN Obtaining the Default Color Conversion Context -->
<!-- .XE -->
<para>
<!-- .LP -->
You can change the default CCC attributes for subsequently created CCCs
by changing the CCC attributes of the default CCC.
<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>
<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>
A default CCC is associated with each screen.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the default CCC for a screen, use
<xref linkend='XcmsDefaultCCC' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsDefaultCCC</primary></indexterm>
<indexterm><primary>Color Conversion Context</primary><secondary>default</secondary></indexterm>
<indexterm><primary>CCC</primary><secondary>default</secondary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsDefaultCCC'>
<funcprototype>
  <funcdef>XcmsCCC <function>XcmsDefaultCCC</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>int <parameter>screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>screen_number</emphasis>
    </term>
    <listitem>
      <para>
Specifies the appropriate screen number on the host server.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsDefaultCCC' xrefstyle='select: title'/>
function returns the default CCC for the specified screen.
Its visual is the default visual of the screen.
Its initial gamut compression and white point
adjustment procedures as well as the associated client data are implementation
specific.
</para>
</sect2>
<sect2 id="Color_Conversion_Context_Macros">
<title>Color Conversion Context Macros</title>
<!-- .XS -->
<!-- (SN Color Conversion Context Macros -->
<!-- .XE -->
<para>
<!-- .LP -->
Applications should not directly modify any part of the
<structname>XcmsCCC</structname>.
The following lists the C language macros, their corresponding function
equivalents for other language bindings, and what data they both
can return.
<!-- .sp -->
</para>
<!-- .LP -->
<indexterm significance="preferred"><primary>DisplayOfCCC</primary></indexterm>
<indexterm significance="preferred"><primary>XcmsDisplayOfCCC</primary></indexterm>
<!-- .sM -->

<funcsynopsis id='DisplayOfCCC'>
<funcprototype>
  <funcdef><function>DisplayOfCCC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<funcsynopsis id='XcmsDisplayOfCCC'>
<funcprototype>
  <funcdef>Display *<function>XcmsDisplayOfCCC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
Both return the display associated with the specified CCC.
</para>
<!-- .LP -->
<!-- .sp -->
<indexterm significance="preferred"><primary>VisualOfCCC</primary></indexterm>
<indexterm significance="preferred"><primary>XcmsVisualOfCCC</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='VisualOfCCC'>
<funcprototype>
  <funcdef><function>VisualOfCCC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<funcsynopsis id='XcmsVisualOfCCC'>
<funcprototype>
  <funcdef>Visual *<function>XcmsVisualOfCCC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
Both return the visual associated with the specified CCC.
<!-- .sp -->
</para>
<!-- .LP -->
<indexterm significance="preferred"><primary>ScreenNumberOfCCC</primary></indexterm>
<indexterm significance="preferred"><primary>XcmsScreenNumberOfCCC</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='ScreenNumberOfCCC'>
<funcprototype>
  <funcdef><function>ScreenNumberOfCCC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<funcsynopsis id='XcmsScreenNumberOfCCC'>
<funcprototype>
  <funcdef>int <function>XcmsScreenNumberOfCCC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
Both return the number of the screen associated with the specified CCC.
<!-- .sp -->
</para>
<!-- .LP -->
<indexterm significance="preferred"><primary>ScreenWhitePointOfCCC</primary></indexterm>
<indexterm significance="preferred"><primary>XcmsScreenWhitePointOfCCC</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='ScreenWhitePointOfCCC'>
<funcprototype>
  <funcdef><function>ScreenWhitePointOfCCC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis id='XcmsScreenWhitePointOfCCC'>
<funcprototype>
  <funcdef>XcmsColor <function>XcmsScreenWhitePointOfCCC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
Both return the white point of the screen associated with the specified CCC.
<!-- .sp -->
</para>
<!-- .LP -->
<indexterm significance="preferred"><primary>ClientWhitePointOfCCC</primary></indexterm>
<indexterm significance="preferred"><primary>XcmsClientWhitePointOfCCC</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='ClientWhitePointOfCCC'>
<funcprototype>
  <funcdef> <function>ClientWhitePointOfCCC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<funcsynopsis id='XcmsClientWhitePointOfCCC'>
<funcprototype>
  <funcdef>XcmsColor *<function>XcmsClientWhitePointOfCCC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
Both return the Client White Point of the specified CCC.
</para>
</sect2>

<sect2 id="Modifying_Attributes_of_a_Color_Conversion_Context">
<title>Modifying Attributes of a Color Conversion Context</title>
<!-- .XS -->
<!-- (SN Modifying Attributes of a Color Conversion Context -->
<!-- .XE -->
<para>
<!-- .LP -->
To set the Client White Point in the CCC, use
<xref linkend='XcmsSetWhitePoint' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsSetWhitePoint</primary></indexterm>
<indexterm><primary>Client White Point</primary><secondary>of Color Conversion Context</secondary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsSetWhitePoint'>
<funcprototype>
  <funcdef>Status <function>XcmsSetWhitePoint</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color</emphasis>
    </term>
    <listitem>
      <para>
Specifies the new Client White Point.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsSetWhitePoint' xrefstyle='select: title'/>
function changes the Client White Point in the specified CCC.
Note that the pixel member is ignored
and that the color specification is left unchanged upon return.
The format for the new white point must be
<symbol>XcmsCIEXYZFormat</symbol>,
<symbol>XcmsCIEuvYFormat</symbol>,
<symbol>XcmsCIExyYFormat</symbol>,
or
<symbol>XcmsUndefinedFormat</symbol>.
If the color argument is NULL, this function sets the format component of the
Client White Point specification to
<symbol>XcmsUndefinedFormat</symbol>,
indicating that the Client White Point is assumed to be the same as the
Screen White Point.
</para>
<para>
<!-- .LP -->
This function returns nonzero status
if the format for the new white point is valid;
otherwise, it returns zero.

<!-- .sp -->
</para>
<para>
<!-- .LP -->
To set the gamut compression procedure and corresponding client data
in a specified CCC, use
<xref linkend='XcmsSetCompressionProc' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsSetCompressionProc</primary></indexterm>
<indexterm><primary>Gamut compression</primary><secondary>setting in Color Conversion Context</secondary></indexterm>
<indexterm><primary>Gamut compression</primary><secondary>procedure</secondary></indexterm>
<indexterm><primary>Gamut compression</primary><secondary>client data</secondary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsSetCompressionProc'>
<funcprototype>
  <funcdef>XcmsCompressionProc <function>XcmsSetCompressionProc</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsCompressionProc <parameter>compression_proc</parameter></paramdef>
  <paramdef>XPointer <parameter>client_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>compression_proc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the gamut compression procedure that is to be applied
when a color lies outside the screen's color gamut.
If NULL is specified and a function using this CCC must convert
a color specification to a device-dependent format and encounters a color
that lies outside the screen's color gamut,
that function will return
<symbol>XcmsFailure</symbol>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>client_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies client data for gamut compression procedure or NULL.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsSetCompressionProc' xrefstyle='select: title'/>
function first sets the gamut compression procedure and client data
in the specified CCC with the newly specified procedure and client data
and then returns the old procedure.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To set the white point adjustment procedure and corresponding client data
in a specified CCC, use
<xref linkend='XcmsSetWhiteAdjustProc' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsSetWhiteAdjustProc</primary></indexterm>
<indexterm><primary>White point adjustment</primary><secondary>setting in Color Conversion Context</secondary></indexterm>
<indexterm><primary>White point adjustment</primary><secondary>procedure</secondary></indexterm>
<indexterm><primary>White point adjustment</primary><secondary>client data</secondary></indexterm>
<funcsynopsis id='XcmsSetWhiteAdjustProc'>
<funcprototype>
  <funcdef>XcmsWhiteAdjustProc <function>XcmsSetWhiteAdjustProc</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsWhiteAdjustProc <parameter>white_adjust_proc</parameter></paramdef>
  <paramdef>XPointer <parameter>client_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>white_adjust_proc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the white point adjustment procedure.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>client_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies client data for white point adjustment procedure or NULL.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsSetWhiteAdjustProc' xrefstyle='select: title'/>
function first sets the white point adjustment procedure and client data
in the specified CCC with the newly specified procedure and client data
and then returns the old procedure.
</para>
</sect2>
<sect2 id="Creating_and_Freeing_a_Color_Conversion_Context">
<title>Creating and Freeing a Color Conversion Context</title>
<!-- .XS -->
<!-- (SN Creating and Freeing a Color Conversion Context -->
<!-- .XE -->
<para>
<!-- .LP -->
You can explicitly create a CCC within your application by calling
<xref linkend='XcmsCreateCCC' xrefstyle='select: title'/>.
These created CCCs can then be used by those functions that explicitly
call for a CCC argument.
Old CCCs that will not be used by the application should be freed using
<xref linkend='XcmsFreeCCC' xrefstyle='select: title'/>.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To create a CCC, use
<xref linkend='XcmsCreateCCC' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsCreateCCC</primary></indexterm>
<indexterm><primary>Color Conversion Context</primary><secondary>creation</secondary></indexterm>
<indexterm><primary>CCC</primary><secondary>creation</secondary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsCreateCCC'>
<funcprototype>
  <funcdef>XcmsCCC <function>XcmsCreateCCC</function></funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>int <parameter>screen_number</parameter></paramdef>
  <paramdef>Visual *<parameter>visual</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>client_white_point</parameter></paramdef>
  <paramdef>XcmsCompressionProc <parameter>compression_proc</parameter></paramdef>
  <paramdef>XPointer <parameter>compression_client_data</parameter></paramdef>
  <paramdef>XcmsWhiteAdjustProc <parameter>white_adjust_proc</parameter></paramdef>
  <paramdef>XPointer <parameter>white_adjust_client_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>screen_number</emphasis>
    </term>
    <listitem>
      <para>
Specifies the appropriate screen number on the host server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>visual</emphasis>
    </term>
    <listitem>
      <para>
Specifies the visual type.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>client_white_point</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Client White Point.
If NULL is specified,
the Client White Point is to be assumed to be the same as the
Screen White Point.
Note that the pixel member is ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>compression_proc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the gamut compression procedure that is to be applied
when a color lies outside the screen's color gamut.
If NULL is specified and a function using this CCC must convert
a color specification to a device-dependent format and encounters a color
that lies outside the screen's color gamut,
that function will return
<symbol>XcmsFailure</symbol>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>compression_client_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies client data for use by the gamut compression procedure or NULL.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>white_adjust_proc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the white adjustment procedure that is to be applied
when the Client White Point differs from the Screen White Point.
NULL indicates that no white point adjustment is desired.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>white_adjust_client_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies client data for use with the white point adjustment procedure or NULL.
    </para>
  </listitem>
  </varlistentry>
</variablelist>


<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsCreateCCC' xrefstyle='select: title'/>
function creates a CCC for the specified display, screen, and visual.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To free a CCC, use
<xref linkend='XcmsFreeCCC' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsFreeCCC</primary></indexterm>
<indexterm><primary>Color Conversion Context</primary><secondary>freeing</secondary></indexterm>
<indexterm><primary>CCC</primary><secondary>freeing</secondary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsFreeCCC'>
<funcprototype>
  <funcdef>void <function>XcmsFreeCCC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsFreeCCC' xrefstyle='select: title'/>
function frees the memory used for the specified CCC.
Note that default CCCs and those currently associated with colormaps
are ignored.
</para>
</sect2>
</sect1>
<sect1 id="Converting_between_Color_Spaces">
<title>Converting between Color Spaces</title>
<!-- .XS -->
<!-- (SN Converting between Color Spaces -->
<!-- .XE -->
<para>
<!-- .LP -->
<!-- .sp -->
To convert an array of color specifications in arbitrary color formats
to a single destination format, use
<xref linkend='XcmsConvertColors' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Color conversion</primary></indexterm>
<indexterm><primary>Color</primary><secondary>conversion</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsConvertColors</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsConvertColors'>
<funcprototype>
  <funcdef>Status <function>XcmsConvertColors</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsColor <parameter>colors_in_out[]</parameter></paramdef>
  <paramdef>unsigned int <parameter>ncolors</parameter></paramdef>
  <paramdef>XcmsColorFormat <parameter>target_format</parameter></paramdef>
  <paramdef>Bool <parameter>compression_flags_return[]</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
If conversion is between device-independent color spaces only
(for example, TekHVC to CIELuv),
the CCC is necessary only to specify the Client White Point.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colors_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies an array of color specifications.
Pixel members are ignored and remain unchanged upon return.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ncolors</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of
<structname>XcmsColor</structname>
structures in the color-specification array.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>target_format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the target color specification format.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>compression_flags_return</emphasis>
    </term>
    <listitem>
      <para>
Returns an array of Boolean values indicating compression status.
If a non-NULL pointer is supplied,
each element of the array is set to
<symbol>True</symbol>
if the corresponding color was compressed and
<symbol>False</symbol>
otherwise.
Pass NULL if the compression status is not useful.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsConvertColors' xrefstyle='select: title'/>
function converts the color specifications in the specified array of
<structname>XcmsColor</structname>
structures from their current format to a single target format,
using the specified CCC.
When the return value is
<symbol>XcmsFailure</symbol>,
the contents of the color specification array are left unchanged.
</para>
<para>
<!-- .LP -->
The array may contain a mixture of color specification formats
(for example, 3 <acronym>CIE</acronym> XYZ, 2 <acronym>CIE</acronym> Luv, and so on).
When the array contains both device-independent and
device-dependent color specifications and the target_format argument specifies
a device-dependent format (for example,
<symbol>XcmsRGBiFormat</symbol>,
<symbol>XcmsRGBFormat</symbol>),
all specifications are converted to <acronym>CIE</acronym> XYZ format and then to the target
device-dependent format.
</para>
</sect1>
<sect1 id="Callback_Functions">
<title>Callback Functions</title>
<!-- .XS -->
<!-- (SN Callback Functions -->
<!-- .XE -->
<para>
<!-- .LP -->
This section describes the gamut compression and white point
adjustment callbacks.
</para>
<para>
<!-- .LP -->
The gamut compression procedure specified in the CCC
is called when an attempt to convert a color specification from
<structname>XcmsCIEXYZ</structname>
to a device-dependent format (typically
<structname>XcmsRGBi</structname>)
results in a color that lies outside the screen's color gamut.
If the gamut compression procedure requires client data, this data is passed
via the gamut compression client data in the CCC.
</para>
<para>
<!-- .LP -->
During color specification conversion between device-independent
and device-dependent color spaces,
if a white point adjustment procedure is specified in the CCC,
it is triggered when the Client White Point and Screen White Point differ.
If required, the client data is obtained from the CCC.
</para>
<sect2 id="Prototype_Gamut_Compression_Procedure">
<title>Prototype Gamut Compression Procedure</title>
<!-- .XS -->
<!-- (SN Prototype Gamut Compression Procedure -->
<!-- .XE -->
<para>
<!-- .LP -->
The gamut compression callback interface must adhere to the
following:
</para>
<indexterm significance="preferred"><primary>XcmsCompressionProc</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsCompressionProc'>
<funcprototype>
  <funcdef>typedef Status<function>(*XcmsCompressionProc</function>)</funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsColor <parameter>colors_in_out[]</parameter></paramdef>
  <paramdef>unsigned int <parameter>ncolors</parameter></paramdef>
  <paramdef>unsigned int <parameter>index</parameter></paramdef>
  <paramdef>Bool <parameter>compression_flags_return[]</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colors_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies an array of color specifications.
Pixel members should be ignored and must remain unchanged upon return.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ncolors</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of
<structname>XcmsColor</structname>
structures in the color-specification array.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>index</emphasis>
    </term>
    <listitem>
      <para>
Specifies the index into the array of
<structname>XcmsColor</structname>
structures for the encountered color specification that lies outside the
screen's color gamut.
Valid values are 0 (for the first element) to ncolors - 1.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>compression_flags_return</emphasis>
    </term>
    <listitem>
      <para>
Returns an array of Boolean values for indicating compression status.
If a non-NULL pointer is supplied
and a color at a given index is compressed, then
<symbol>True</symbol>
should be stored at the corresponding index in this array;
otherwise, the array should not be modified.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
When implementing a gamut compression procedure, consider the following
rules and assumptions:
</para>
<itemizedlist>
  <listitem>
    <para>
The gamut compression procedure can attempt to compress one or multiple
specifications at a time.
    </para>
  </listitem>
  <listitem>
    <para>
When called, elements 0 to index - 1 in the color specification
array can be assumed to fall within the screen's color gamut.
In addition, these color specifications are already in some device-dependent
format (typically
<structname>XcmsRGBi</structname>).
If any modifications are made to these color specifications,
they must be in their initial device-dependent format upon return.
    </para>
  </listitem>
  <listitem>
    <para>
When called, the element in the color specification array specified
by the index argument contains the color specification outside the
screen's color gamut encountered by the calling routine.
In addition, this color specification can be assumed to be in
<structname>XcmsCIEXYZ</structname>.
Upon return, this color specification must be in
<structname>XcmsCIEXYZ</structname>.
    </para>
  </listitem>
  <listitem>
    <para>
When called, elements from index to ncolors - 1
in the color specification array may or may not fall within the
screen's color gamut.
In addition, these color specifications can be assumed to be in
<structname>XcmsCIEXYZ</structname>.
If any modifications are made to these color specifications,
they must be in
<structname>XcmsCIEXYZ</structname>
upon return.
    </para>
  </listitem>
  <listitem>
    <para>
The color specifications passed to the gamut compression procedure
have already been adjusted to the Screen White Point.
This means that at this point the color specification's white point
is the Screen White Point.
    </para>
  </listitem>
  <listitem>
    <para>
If the gamut compression procedure uses a device-independent color space not
initially accessible for use in the color management system, use
<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>
to ensure that it is added.
    </para>
  </listitem>
</itemizedlist>
</sect2>
<sect2 id="Supplied_Gamut_Compression_Procedures">
<title>Supplied Gamut Compression Procedures</title>
<!-- .XS -->
<!-- (SN Supplied Gamut Compression Procedures -->
<!-- .XE -->
<para>
<!-- .LP -->
The following equations are useful in describing gamut compression
functions:
<!-- .EQ -->
delim %%
<!-- .EN -->
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%

%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%

%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%

%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
</literallayout>
</para>
<para>
<!-- .LP -->
The gamut compression callback procedures provided by Xlib are as follows:
</para>
<itemizedlist>
  <listitem>
    <para>
<function>XcmsCIELabClipL</function>
    </para>
  </listitem>
  <listitem>
    <para>
This brings the encountered out-of-gamut color specification into the
screen's color gamut by reducing or increasing <acronym>CIE</acronym> metric lightness (L*)
in the <acronym>CIE</acronym> L*a*b* color space until the color is within the gamut.
If the Psychometric Chroma of the color specification
is beyond maximum for the Psychometric Hue Angle,
then while maintaining the same Psychometric Hue Angle,
the color will be clipped to the <acronym>CIE</acronym> L*a*b* coordinates of maximum
Psychometric Chroma.
See
<xref linkend='XcmsCIELabQueryMaxC' xrefstyle='select: title'/>.
No client data is necessary.
    </para>
  </listitem>
  <listitem>
    <para>
<function>XcmsCIELabClipab</function>
    </para>
  </listitem>
  <listitem>
    <para>
This brings the encountered out-of-gamut color specification into the
screen's color gamut by reducing Psychometric Chroma,
while maintaining Psychometric Hue Angle,
until the color is within the gamut.
No client data is necessary.
    </para>
  </listitem>
  <listitem>
    <para>
<function>XcmsCIELabClipLab</function>
    </para>
  </listitem>
  <listitem>
    <para>
This brings the encountered out-of-gamut color specification into the
screen's color gamut by replacing it with <acronym>CIE</acronym> L*a*b* coordinates
that fall within the color gamut while maintaining the original
Psychometric Hue
Angle and whose vector to the original coordinates is the shortest attainable.
No client data is necessary.
    </para>
  </listitem>
  <listitem>
    <para>
<function>XcmsCIELuvClipL</function>
    </para>
  </listitem>
  <listitem>
    <para>
This brings the encountered out-of-gamut color specification into the
screen's color gamut by reducing or increasing <acronym>CIE</acronym> metric lightness (L*)
in the <acronym>CIE</acronym> L*u*v* color space until the color is within the gamut.
If the Psychometric Chroma of the color specification
is beyond maximum for the Psychometric Hue Angle,
then, while maintaining the same Psychometric Hue Angle,
the color will be clipped to the <acronym>CIE</acronym> L*u*v* coordinates of maximum
Psychometric Chroma.
See
<xref linkend='XcmsCIELuvQueryMaxC' xrefstyle='select: title'/>.
No client data is necessary.
    </para>
  </listitem>
  <listitem>
    <para>
<function>XcmsCIELuvClipuv</function>
    </para>
  </listitem>
  <listitem>
    <para>
This brings the encountered out-of-gamut color specification into the
screen's color gamut by reducing
Psychometric Chroma, while maintaining Psychometric Hue Angle,
until the color is within the gamut.
No client data is necessary.
    </para>
  </listitem>
  <listitem>
    <para>
<function>XcmsCIELuvClipLuv</function>
    </para>
  </listitem>
  <listitem>
    <para>
This brings the encountered out-of-gamut color specification into the
screen's color gamut by replacing it with <acronym>CIE</acronym> L*u*v* coordinates
that fall within the color gamut while maintaining the original
Psychometric Hue
Angle and whose vector to the original coordinates is the shortest attainable.
No client data is necessary.
    </para>
  </listitem>
  <listitem>
    <para>
<function>XcmsTekHVCClipV</function>
    </para>
  </listitem>
  <listitem>
    <para>
This brings the encountered out-of-gamut color specification into the
screen's color gamut by reducing or increasing the Value dimension
in the TekHVC color space until the color is within the gamut.
If Chroma of the color specification is beyond maximum for the particular Hue,
then, while maintaining the same Hue,
the color will be clipped to the Value and Chroma coordinates
that represent maximum Chroma for that particular Hue.
No client data is necessary.
    </para>
  </listitem>
  <listitem>
    <para>
<function>XcmsTekHVCClipC</function>
    </para>
  </listitem>
  <listitem>
    <para>
This brings the encountered out-of-gamut color specification into the
screen's color gamut by reducing the Chroma dimension
in the TekHVC color space until the color is within the gamut.
No client data is necessary.
    </para>
  </listitem>
  <listitem>
    <para>
<function>XcmsTekHVCClipVC</function>
    </para>
  </listitem>
  <listitem>
    <para>
This brings the encountered out-of-gamut color specification into the
screen's color gamut by replacing it with TekHVC coordinates
that fall within the color gamut while maintaining the original Hue
and whose vector to the original coordinates is the shortest attainable.
No client data is necessary.
    </para>
  </listitem>
</itemizedlist>
</sect2>
<sect2 id="Prototype_White_Point_Adjustment_Procedure">
<title>Prototype White Point Adjustment Procedure</title>
<!-- .XS -->
<!-- (SN Prototype White Point Adjustment Procedure -->
<!-- .XE -->
<para>
<!-- .LP -->
The white point adjustment procedure interface must adhere to the following:
</para>
<indexterm significance="preferred"><primary>XcmsWhiteAdjustProc</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsWhiteAdjustProc'>
<funcprototype>
  <funcdef>typedef Status <function>(*XcmsWhiteAdjustProc</function>)</funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>initial_white_point</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>target_white_point</parameter></paramdef>
  <paramdef>XcmsColorFormat <parameter>target_format</parameter></paramdef>
  <paramdef>XcmsColor <parameter>colors_in_out[]</parameter></paramdef>
  <paramdef>unsigned int <parameter>ncolors</parameter></paramdef>
  <paramdef>Bool <parameter>compression_flags_return[]</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>initial_white_point</emphasis>
    </term>
    <listitem>
      <para>
Specifies the initial white point.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>target_white_point</emphasis>
    </term>
    <listitem>
      <para>
Specifies the target white point.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>target_format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the target color specification format.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colors_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies an array of color specifications.
Pixel members should be ignored and must remain unchanged upon return.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ncolors</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of
<structname>XcmsColor</structname>
structures in the color-specification array.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>compression_flags_return</emphasis>
    </term>
    <listitem>
      <para>
Returns an array of Boolean values for indicating compression status.
If a non-NULL pointer is supplied
and a color at a given index is compressed, then
<symbol>True</symbol>
should be stored at the corresponding index in this array;
otherwise, the array should not be modified.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
</para>
</sect2>
<sect2 id="Supplied_White_Point_Adjustment_Procedures">
<title>Supplied White Point Adjustment Procedures</title>
<!-- .XS -->
<!-- (SN Supplied White Point Adjustment Procedures -->
<!-- .XE -->
<para>
<!-- .LP -->
White point adjustment procedures provided by Xlib are as follows:
</para>
<itemizedlist>
  <listitem>
    <para>
<function>XcmsCIELabWhiteShiftColors</function>
    </para>
  </listitem>
  <listitem>
    <para>
This uses the <acronym>CIE</acronym> L*a*b* color space for adjusting the chromatic character
of colors to compensate for the chromatic differences between the source
and destination white points.
This procedure simply converts the color specifications to
<structname>XcmsCIELab</structname>
using the source white point and then converts to the target specification
format using the destination's white point.
No client data is necessary.
    </para>
  </listitem>
  <listitem>
    <para>
<function>XcmsCIELuvWhiteShiftColors</function>
    </para>
  </listitem>
  <listitem>
    <para>
This uses the <acronym>CIE</acronym> L*u*v* color space for adjusting the chromatic character
of colors to compensate for the chromatic differences between the source
and destination white points.
This procedure simply converts the color specifications to
<structname>XcmsCIELuv</structname>
using the source white point and then converts to the target specification
format using the destination's white point.
No client data is necessary.
    </para>
  </listitem>
  <listitem>
    <para>
<function>XcmsTekHVCWhiteShiftColors</function>
    </para>
  </listitem>
  <listitem>
    <para>
This uses the TekHVC color space for adjusting the chromatic character
of colors to compensate for the chromatic differences between the source
and destination white points.
This procedure simply converts the color specifications to
<structname>XcmsTekHVC</structname>
using the source white point and then converts to the target specification
format using the destination's white point.
An advantage of this procedure over those previously described
is an attempt to minimize hue shift.
No client data is necessary.
    </para>
  </listitem>
</itemizedlist>
<para>
<!-- .LP -->
From an implementation point of view,
these white point adjustment procedures convert the color specifications
to a device-independent but white-point-dependent color space
(for example, <acronym>CIE</acronym> L*u*v*, <acronym>CIE</acronym> L*a*b*, TekHVC) using one white point
and then converting those specifications to the target color space
using another white point.
In other words,
the specification goes in the color space with one white point
but comes out with another white point,
resulting in a chromatic shift based on the chromatic displacement
between the initial white point and target white point.
The <acronym>CIE</acronym> color spaces that are assumed to be white-point-independent
are <acronym>CIE</acronym> u'v'Y, <acronym>CIE</acronym> XYZ, and <acronym>CIE</acronym> xyY.
When developing a custom white point adjustment procedure that uses a
device-independent color space not initially accessible for use in the
color management system, use
<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>
to ensure that it is added.
</para>
<para>
<!-- .LP -->
As an example,
if the CCC specifies a white point adjustment procedure
and if the Client White Point and Screen White Point differ, the
<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
function will use the white point adjustment
procedure twice:
</para>
<itemizedlist>
  <listitem>
    <para>
Once to convert to
<structname>XcmsRGB</structname>
    </para>
  </listitem>
  <listitem>
    <para>
A second time to convert from
<structname>XcmsRGB</structname>
    </para>
  </listitem>
</itemizedlist>
<para>
<!-- .LP -->
For example, assume the specification is in
<structname>XcmsCIEuvY</structname>
and the adjustment procedure is
<function>XcmsCIELuvWhiteShiftColors</function>.
During conversion to
<structname>XcmsRGB</structname>,
the call to
<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
results in the following series of color specification conversions:
<!-- .\" Do these need to be font coded? -->
</para>
<itemizedlist>
  <listitem>
    <para>
From
<structname>XcmsCIEuvY</structname>
to
<structname>XcmsCIELuv</structname>
using the Client White Point
    </para>
  </listitem>
  <listitem>
    <para>
From
<structname>XcmsCIELuv</structname>
to
<structname>XcmsCIEuvY</structname>
using the Screen White Point
    </para>
  </listitem>
  <listitem>
    <para>
From
<structname>XcmsCIEuvY</structname>
to
<structname>XcmsCIEXYZ</structname>
(<acronym>CIE</acronym> u'v'Y and XYZ are white-point-independent color spaces)
    </para>
  </listitem>
  <listitem>
    <para>
From
<structname>XcmsCIEXYZ</structname>
to
<structname>XcmsRGBi</structname>
    </para>
  </listitem>
  <listitem>
    <para>
From
<structname>XcmsRGBi</structname>
to
<structname>XcmsRGB</structname>
    </para>
  </listitem>
</itemizedlist>
<para>
<!-- .LP -->
The resulting <acronym>RGB</acronym> specification is passed to
<xref linkend='XAllocColor' xrefstyle='select: title'/>,
and the <acronym>RGB</acronym>
specification returned by
<xref linkend='XAllocColor' xrefstyle='select: title'/>
is converted back to
<structname>XcmsCIEuvY</structname>
by reversing the color conversion sequence.
</para>
</sect2>
</sect1>
<sect1 id="Gamut_Querying_Functions">
<title>Gamut Querying Functions</title>
<!-- .XS -->
<!-- (SN Gamut Querying Functions -->
<!-- .XE -->
<para>
<!-- .LP -->
This section describes the gamut querying functions that Xlib provides.
These functions allow the client to query the boundary
of the screen's color gamut in terms of the <acronym>CIE</acronym> L*a*b*, <acronym>CIE</acronym> L*u*v*,
and TekHVC color spaces.
<indexterm><primary>Gamut querying</primary></indexterm>
Functions are also provided that allow you to query
the color specification of:
</para>
<itemizedlist>
  <listitem>
    <para>
White (full-intensity red, green, and blue)
    </para>
  </listitem>
  <listitem>
    <para>
Red (full-intensity red while green and blue are zero)
    </para>
  </listitem>
  <listitem>
    <para>
Green (full-intensity green while red and blue are zero)
    </para>
  </listitem>
  <listitem>
    <para>
Blue (full-intensity blue while red and green are zero)
    </para>
  </listitem>
  <listitem>
    <para>
Black (zero-intensity red, green, and blue)
    </para>
  </listitem>
</itemizedlist>
<para>
<!-- .LP -->
The white point associated with color specifications passed to
and returned from these gamut querying
functions is assumed to be the Screen White Point.
<indexterm><primary>Screen White Point</primary></indexterm>
This is a reasonable assumption,
because the client is trying to query the screen's color gamut.
</para>
<para>
<!-- .LP -->
The following naming convention is used for the Max and Min functions:
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
Xcms<emphasis remap='I'>&lt;color_space&gt;</emphasis>QueryMax<emphasis remap='I'>&lt;dimensions&gt;</emphasis>

Xcms<emphasis remap='I'>&lt;color_space&gt;</emphasis>QueryMin<emphasis remap='I'>&lt;dimensions&gt;</emphasis>
</literallayout>
</para>
<para>
<!-- .LP -->
The &lt;dimensions&gt; consists of a letter or letters
that identify the dimensions of the color space
that are not fixed.
For example,
<xref linkend='XcmsTekHVCQueryMaxC' xrefstyle='select: title'/>
is given a fixed Hue and Value for which maximum Chroma is found.
</para>
<sect2 id="Red_Green_and_Blue_Queries">
<title>Red, Green, and Blue Queries</title>
<!-- .XS -->
<!-- (SN Red, Green, and Blue Queries -->
<!-- .XE -->
<para>
<!-- .LP -->
To obtain the color specification for black
(zero-intensity red, green, and blue), use
<xref linkend='XcmsQueryBlack' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsQueryBlack</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsQueryBlack'>
<funcprototype>
  <funcdef>Status <function>XcmsQueryBlack</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsColorFormat <parameter>target_format</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>target_format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the target color specification format.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the color specification in the specified target format
for zero-intensity red, green, and blue.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsQueryBlack' xrefstyle='select: title'/>
function returns the color specification in the specified target format
for zero-intensity red, green, and blue.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the color specification for blue
(full-intensity blue while red and green are zero), use
<xref linkend='XcmsQueryBlue' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsQueryBlue</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsQueryBlue'>
<funcprototype>
  <funcdef>Status <function>XcmsQueryBlue</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsColorFormat <parameter>target_format</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>target_format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the target color specification format.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the color specification in the specified target format
for full-intensity blue while red and green are zero.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsQueryBlue' xrefstyle='select: title'/>
function returns the color specification in the specified target format
for full-intensity blue while red and green are zero.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the color specification for green
(full-intensity green while red and blue are zero), use
<xref linkend='XcmsQueryGreen' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsQueryGreen</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsQueryGreen'>
<funcprototype>
  <funcdef>Status <function>XcmsQueryGreen</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsColorFormat <parameter>target_format</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>target_format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the target color specification format.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the color specification in the specified target format
for full-intensity green while red and blue are zero.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsQueryGreen' xrefstyle='select: title'/>
function returns the color specification in the specified target format
for full-intensity green while red and blue are zero.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the color specification for red
(full-intensity red while green and blue are zero), use
<xref linkend='XcmsQueryRed' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsQueryRed</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsQueryRed'>
<funcprototype>
  <funcdef>Status <function>XcmsQueryRed</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsColorFormat <parameter>target_format</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>target_format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the target color specification format.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the color specification in the specified target format
for full-intensity red while green and blue are zero.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsQueryRed' xrefstyle='select: title'/>
function returns the color specification in the specified target format
for full-intensity red while green and blue are zero.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain the color specification for white
(full-intensity red, green, and blue), use
<xref linkend='XcmsQueryWhite' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsQueryWhite</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsQueryWhite'>
<funcprototype>
  <funcdef>Status <function>XcmsQueryWhite</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsColorFormat <parameter>target_format</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>target_format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the target color specification format.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the color specification in the specified target format
for full-intensity red, green, and blue.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsQueryWhite' xrefstyle='select: title'/>
function returns the color specification in the specified target format
for full-intensity red, green, and blue.
</para>
</sect2>
<sect2 id="CIELab_Queries">
<title>CIELab Queries</title>
<!-- .XS -->
<!-- (SN CIELab Queries -->
<!-- .XE -->
<para>
<!-- .LP -->
The following equations are useful in describing the CIELab query functions:
<!-- .EQ -->
delim %%
<!-- .EN -->
</para>
<para>
<!-- .LP -->
<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
<indexterm><primary>Psychometric Chroma</primary></indexterm>
<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>
<literallayout class="monospaced">
%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%

%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%
</literallayout>
<!-- .sp -->
To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum Psychometric Chroma
for a given Psychometric Hue Angle and <acronym>CIE</acronym> metric lightness (L*), use
<xref linkend='XcmsCIELabQueryMaxC' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxC</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsCIELabQueryMaxC'>
<funcprototype>
  <funcdef>Status <function>XcmsCIELabQueryMaxC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue_angle</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>L_star</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue_angle</emphasis>
    </term>
    <listitem>
      <para>
Specifies the hue angle (in degrees) at which to find maximum chroma.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>L_star</emphasis>
    </term>
    <listitem>
      <para>
Specifies the lightness (L*) at which to find maximum chroma.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the <acronym>CIE</acronym> L*a*b* coordinates of maximum chroma
displayable by the screen for the given hue angle and lightness.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsCIELabQueryMaxC' xrefstyle='select: title'/>
function, given a hue angle and lightness,
finds the point of maximum chroma displayable by the screen.
It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum <acronym>CIE</acronym> metric lightness (L*)
for a given Psychometric Hue Angle and Psychometric Chroma, use
<xref linkend='XcmsCIELabQueryMaxL' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxL</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsCIELabQueryMaxL'>
<funcprototype>
  <funcdef>Status <function>XcmsCIELabQueryMaxL</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue_angle</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>chroma</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue_angle</emphasis>
    </term>
    <listitem>
      <para>
Specifies the hue angle (in degrees) at which to find maximum lightness.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>chroma</emphasis>
    </term>
    <listitem>
      <para>
Specifies the chroma at which to find maximum lightness.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the <acronym>CIE</acronym> L*a*b* coordinates of maximum lightness
displayable by the screen for the given hue angle and chroma.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsCIELabQueryMaxL' xrefstyle='select: title'/>
function, given a hue angle and chroma,
finds the point in <acronym>CIE</acronym> L*a*b* color space of maximum
lightness (L*) displayable by the screen.
It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.
An
<symbol>XcmsFailure</symbol>
return value usually indicates that the given chroma
is beyond maximum for the given hue angle.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the <acronym>CIE</acronym> L*a*b* coordinates of maximum Psychometric Chroma
for a given Psychometric Hue Angle, use
<xref linkend='XcmsCIELabQueryMaxLC' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
<indexterm><primary>Psychometric Chroma</primary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxLC</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsCIELabQueryMaxLC'>
<funcprototype>
  <funcdef>Status <function>XcmsCIELabQueryMaxLC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue_angle</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue_angle</emphasis>
    </term>
    <listitem>
      <para>
Specifies the hue angle (in degrees) at which to find maximum chroma.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the <acronym>CIE</acronym> L*a*b* coordinates of maximum chroma
displayable by the screen for the given hue angle.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsCIELabQueryMaxLC' xrefstyle='select: title'/>
function, given a hue angle,
finds the point of maximum chroma displayable by the screen.
It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the <acronym>CIE</acronym> L*a*b* coordinates of minimum <acronym>CIE</acronym> metric lightness (L*)
for a given Psychometric Hue Angle and Psychometric Chroma, use
<xref linkend='XcmsCIELabQueryMinL' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>minimum</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsCIELabQueryMinL</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsCIELabQueryMinL'>
<funcprototype>
  <funcdef>Status <function>XcmsCIELabQueryMinL</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue_angle</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>chroma</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue_angle</emphasis>
    </term>
    <listitem>
      <para>
Specifies the hue angle (in degrees) at which to find minimum lightness.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>chroma</emphasis>
    </term>
    <listitem>
      <para>
Specifies the chroma at which to find minimum lightness.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the <acronym>CIE</acronym> L*a*b* coordinates of minimum lightness
displayable by the screen for the given hue angle and chroma.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsCIELabQueryMinL' xrefstyle='select: title'/>
function, given a hue angle and chroma,
finds the point of minimum lightness (L*) displayable by the screen.
It returns this point in <acronym>CIE</acronym> L*a*b* coordinates.
An
<symbol>XcmsFailure</symbol>
return value usually indicates that the given chroma
is beyond maximum for the given hue angle.
</para>
</sect2>
<sect2 id="CIELuv_Queries">
<title>CIELuv Queries</title>
<!-- .XS -->
<!-- (SN CIELuv Queries -->
<!-- .XE -->
<para>
<!-- .LP -->
The following equations are useful in describing the CIELuv query functions:
<!-- .EQ -->
delim %%
<!-- .EN -->
</para>
<para>
<!-- .LP -->
<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
<indexterm><primary>Psychometric Chroma</primary></indexterm>
<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>
<literallayout class="monospaced">
%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%

%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
</literallayout>
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum Psychometric Chroma
for a given Psychometric Hue Angle and <acronym>CIE</acronym> metric lightness (L*), use
<xref linkend='XcmsCIELuvQueryMaxC' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxC</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsCIELuvQueryMaxC'>
<funcprototype>
  <funcdef>Status <function>XcmsCIELuvQueryMaxC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue_angle</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>L_star</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue_angle</emphasis>
    </term>
    <listitem>
      <para>
Specifies the hue angle (in degrees) at which to find maximum chroma.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>L_star</emphasis>
    </term>
    <listitem>
      <para>
Specifies the lightness (L*) at which to find maximum chroma.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the <acronym>CIE</acronym> L*u*v* coordinates of maximum chroma
displayable by the screen for the given hue angle and lightness.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsCIELuvQueryMaxC' xrefstyle='select: title'/>
function, given a hue angle and lightness,
finds the point of maximum chroma displayable by the screen.
It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum <acronym>CIE</acronym> metric lightness (L*)
for a given Psychometric Hue Angle and Psychometric Chroma, use
<xref linkend='XcmsCIELuvQueryMaxL' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxL</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsCIELuvQueryMaxL'>
<funcprototype>
  <funcdef>Status <function>XcmsCIELuvQueryMaxL</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue_angle</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>chroma</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue_angle</emphasis>
    </term>
    <listitem>
      <para>
Specifies the hue angle (in degrees) at which to find maximum lightness.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>L_star</emphasis>
    </term>
    <listitem>
      <para>
Specifies the lightness (L*) at which to find maximum lightness.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the <acronym>CIE</acronym> L*u*v* coordinates of maximum lightness
displayable by the screen for the given hue angle and chroma.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsCIELuvQueryMaxL' xrefstyle='select: title'/>
function, given a hue angle and chroma,
finds the point in <acronym>CIE</acronym> L*u*v* color space of maximum
lightness (L*) displayable by the screen.
It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.
An
<symbol>XcmsFailure</symbol>
return value usually indicates that the given chroma
is beyond maximum for the given hue angle.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the <acronym>CIE</acronym> L*u*v* coordinates of maximum Psychometric Chroma
for a given Psychometric Hue Angle, use
<xref linkend='XcmsCIELuvQueryMaxLC' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
<indexterm><primary>Psychometric Chroma</primary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
<indexterm><primary>Psychometric Chroma</primary><secondary>maximum</secondary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>maximum</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxLC</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsCIELuvQueryMaxLC'>
<funcprototype>
  <funcdef>Status <function>XcmsCIELuvQueryMaxLC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue_angle</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue_angle</emphasis>
    </term>
    <listitem>
      <para>
Specifies the hue angle (in degrees) at which to find maximum chroma.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the <acronym>CIE</acronym> L*u*v* coordinates of maximum chroma
displayable by the screen for the given hue angle.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsCIELuvQueryMaxLC' xrefstyle='select: title'/>
function, given a hue angle,
finds the point of maximum chroma displayable by the screen.
It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the <acronym>CIE</acronym> L*u*v* coordinates of minimum <acronym>CIE</acronym> metric lightness (L*)
for a given Psychometric Hue Angle and Psychometric Chroma, use
<xref linkend='XcmsCIELuvQueryMinL' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Psychometric Hue Angle</primary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary></indexterm>
<indexterm><primary><acronym>CIE</acronym> metric lightness</primary><secondary>minimum</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsCIELuvQueryMinL</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsCIELuvQueryMinL'>
<funcprototype>
  <funcdef>Status <function>XcmsCIELuvQueryMinL</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue_angle</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>chroma</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue_angle</emphasis>
    </term>
    <listitem>
      <para>
Specifies the hue angle (in degrees) at which to find minimum lightness.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>chroma</emphasis>
    </term>
    <listitem>
      <para>
Specifies the chroma at which to find minimum lightness.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the <acronym>CIE</acronym> L*u*v* coordinates of minimum lightness
displayable by the screen for the given hue angle and chroma.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsCIELuvQueryMinL' xrefstyle='select: title'/>
function, given a hue angle and chroma,
finds the point of minimum lightness (L*) displayable by the screen.
It returns this point in <acronym>CIE</acronym> L*u*v* coordinates.
An
<symbol>XcmsFailure</symbol>
return value usually indicates that the given chroma
is beyond maximum for the given hue angle.
</para>
</sect2>
<sect2 id="TekHVC_Queries">
<title>TekHVC Queries</title>
<!-- .XS -->
<!-- (SN TekHVC Queries -->
<!-- .XE -->
<para>
<!-- .LP -->
To obtain the maximum Chroma for a given Hue and Value, use
<xref linkend='XcmsTekHVCQueryMaxC' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Chroma</primary></indexterm>
<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxC</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsTekHVCQueryMaxC'>
<funcprototype>
  <funcdef>Status <function>XcmsTekHVCQueryMaxC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>value</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Hue in which to find the maximum Chroma.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>value</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Value in which to find the maximum Chroma.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the maximum Chroma along with the actual Hue and Value	at which
the maximum Chroma was found.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsTekHVCQueryMaxC' xrefstyle='select: title'/>
function, given a Hue and Value,
determines the maximum Chroma in TekHVC color space
displayable by the screen.
It returns the maximum Chroma along with the actual Hue
and Value at which the maximum Chroma was found.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the maximum Value for a given Hue and Chroma, use
<xref linkend='XcmsTekHVCQueryMaxV' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Value</primary></indexterm>
<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxV</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsTekHVCQueryMaxV'>
<funcprototype>
  <funcdef>Status <function>XcmsTekHVCQueryMaxV</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>chroma</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Hue in which to find the maximum Value.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>chroma</emphasis>
    </term>
    <listitem>
      <para>
Specifies the chroma at which to find maximum Value.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the maximum Value along with the Hue and Chroma at which the
maximum Value
was found.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsTekHVCQueryMaxV' xrefstyle='select: title'/>
function, given a Hue and Chroma,
determines the maximum Value in TekHVC color space
displayable by the screen.
It returns the maximum Value and the actual Hue and Chroma
at which the maximum Value was found.
<!-- .sp -->
</para>

<para>
<!-- .LP -->
To obtain the maximum Chroma and Value at which it is reached
for a specified Hue, use
<xref linkend='XcmsTekHVCQueryMaxVC' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Chroma</primary></indexterm>
<indexterm><primary>Value</primary></indexterm>
<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>
<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxVC</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsTekHVCQueryMaxVC'>
<funcprototype>
  <funcdef>Status <function>XcmsTekHVCQueryMaxVC</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Hue in which to find the maximum Chroma.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the color specification in XcmsTekHVC for the maximum Chroma, the
Value at which that maximum Chroma is reached, and the actual Hue at which
the maximum Chroma was found.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsTekHVCQueryMaxVC' xrefstyle='select: title'/>
function, given a Hue,
determines the maximum Chroma in TekHVC color space displayable by the screen
and the Value at which that maximum Chroma is reached.
It returns the maximum Chroma,
the Value at which that maximum Chroma is reached,
and the actual Hue for which the maximum Chroma was found.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain a specified number of TekHVC specifications such that they
contain maximum Values for a specified Hue and the
Chroma at which the maximum Values are reached, use
<xref linkend='XcmsTekHVCQueryMaxVSamples' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Chroma</primary></indexterm>
<indexterm><primary>Value</primary></indexterm>
<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>
<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxVSamples</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsTekHVCQueryMaxVSamples'>
<funcprototype>
  <funcdef>Status <function>XcmsTekHVCQueryMaxVSamples</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue</parameter></paramdef>
  <paramdef>XcmsColor <parameter>colors_return[]</parameter></paramdef>
  <paramdef>unsigned int <parameter>nsamples</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Hue for maximum Chroma/Value samples.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>nsamples</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of samples.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colors_return</emphasis>
    </term>
    <listitem>
      <para>
Returns nsamples of color specifications in XcmsTekHVC
such that the Chroma is the maximum attainable for the Value and Hue.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsTekHVCQueryMaxVSamples' xrefstyle='select: title'/>
returns nsamples of maximum Value, the Chroma at which that maximum Value
is reached, and the actual Hue for which the maximum Chroma was found.
These sample points may then be used to plot the maximum Value/Chroma
boundary of the screen's color gamut for the specified Hue in TekHVC color
space.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the minimum Value for a given Hue and Chroma, use
<xref linkend='XcmsTekHVCQueryMinV' xrefstyle='select: title'/>.
</para>
<indexterm><primary>Value</primary></indexterm>
<indexterm><primary>Value</primary><secondary>minimum</secondary></indexterm>
<indexterm significance="preferred"><primary>XcmsTekHVCQueryMinV</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsTekHVCQueryMinV'>
<funcprototype>
  <funcdef>Status <function>XcmsTekHVCQueryMinV</function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>hue</parameter></paramdef>
  <paramdef>XcmsFloat <parameter>chroma</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>hue</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Hue in which to find the minimum Value.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>value</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Value in which to find the minimum Value.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the minimum Value and the actual Hue and Chroma at which the
minimum Value
was found.
The white point associated with the returned
color specification is the Screen White Point.
The value returned in the pixel member is undefined.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM  -->
The
<xref linkend='XcmsTekHVCQueryMinV' xrefstyle='select: title'/>
function, given a Hue and Chroma,
determines the minimum Value in TekHVC color space displayable by the screen.
It returns the minimum Value and the actual Hue and Chroma at which
the minimum Value was found.
</para>

</sect2>
</sect1>
<sect1 id="Color_Management_Extensions">
<title>Color Management Extensions</title>
<!-- .XS -->
<!-- (SN Color Management Extensions -->
<!-- .XE -->
<para>
<!-- .LP -->
The Xlib color management facilities can be extended in two ways:
</para>
<itemizedlist>
  <listitem>
    <para>
Device-Independent Color Spaces
    </para>
  </listitem>
  <listitem>
    <para>
Device-independent color spaces that are derivable to <acronym>CIE</acronym> XYZ
space can be added using the
<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>
function.
    </para>
  </listitem>
  <listitem>
    <para>
Color Characterization Function Set
    </para>
  </listitem>
  <listitem>
    <para>
A Color Characterization Function Set consists of
device-dependent color spaces and their functions that
convert between these color spaces and the <acronym>CIE</acronym> XYZ
color space, bundled together for a specific class of output devices.
A function set can be added using the
<xref linkend='XcmsAddFunctionSet' xrefstyle='select: title'/>
function.
    </para>
  </listitem>
</itemizedlist>
<sect2 id="Color_Spaces">
<title>Color Spaces</title>
<!-- .XS -->
<!-- (SN Color Spaces -->
<!-- .XE -->
<para>
<!-- .LP -->
The <acronym>CIE</acronym> XYZ color space serves as the hub for all
conversions between device-independent and device-dependent color spaces.
Therefore, the knowledge to convert an
<structname>XcmsColor</structname>
structure to and from <acronym>CIE</acronym> XYZ format is associated with each color space.
For example, conversion from <acronym>CIE</acronym> L*u*v* to <acronym>RGB</acronym> requires the knowledge
to convert from <acronym>CIE</acronym> L*u*v* to <acronym>CIE</acronym> XYZ and from <acronym>CIE</acronym> XYZ to <acronym>RGB</acronym>.
This knowledge is stored as an array of functions that,
when applied in series, will convert the
<structname>XcmsColor</structname>
structure to or from <acronym>CIE</acronym> XYZ format.
This color specification conversion mechanism facilitates
the addition of color spaces.
</para>
<para>
<!-- .LP -->
Of course, when converting between only device-independent color spaces
or only device-dependent color spaces,
shortcuts are taken whenever possible.
For example, conversion from TekHVC to <acronym>CIE</acronym> L*u*v* is performed
by intermediate conversion to <acronym>CIE</acronym> u*v*Y and then to <acronym>CIE</acronym> L*u*v*,
thus bypassing conversion between <acronym>CIE</acronym> u*v*Y and <acronym>CIE</acronym> XYZ.
</para>
</sect2>
<sect2 id="Adding_Device_Independent_Color_Spaces">
<title>Adding Device-Independent Color Spaces</title>
<!-- .XS -->
<!-- (SN Adding Device-Independent Color Spaces -->
<!-- .XE -->
<para>
<!-- .LP -->
To add a device-independent color space, use
<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsAddColorSpace</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsAddColorSpace'>
<funcprototype>
  <funcdef>Status <function>XcmsAddColorSpace</function></funcdef>
  <paramdef>XcmsColorSpace *<parameter>color_space</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_space</emphasis>
    </term>
    <listitem>
      <para>
Specifies the device-independent color space to add.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>
function makes a device-independent color space (actually an
<structname>XcmsColorSpace</structname>
structure) accessible by the color management system.
Because format values for unregistered color spaces are assigned at run time,
they should be treated as private to the client.
If references to an unregistered color space must be made
outside the client (for example, storing color specifications
in a file using the unregistered color space),
then reference should be made by color space prefix
(see
<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>
and
<xref linkend='XcmsPrefixOfFormat' xrefstyle='select: title'/>).
</para>
<para>
<!-- .LP -->
If the
<structname>XcmsColorSpace</structname>
structure is already accessible in the color management system,
<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>
returns
<symbol>XcmsSuccess</symbol>.
</para>
<para>
<!-- .LP -->
Note that added
<structname>XcmsColorSpace</structname>s
must be retained for reference by Xlib.
</para>
</sect2>
<sect2 id="Querying_Color_Space_Format_and_Prefix">
<title>Querying Color Space Format and Prefix</title>
<!-- .XS -->
<!-- (SN Querying Color Space Format and Prefix -->
<!-- .XE -->
<para>
<!-- .LP -->
To obtain the format associated with the color space
associated with a specified color string prefix, use
<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsFormatOfPrefix</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsFormatOfPrefix'>
<funcprototype>
  <funcdef>XcmsColorFormat <function>XcmsFormatOfPrefix</function></funcdef>
  <paramdef>char *<parameter>prefix</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>prefix</emphasis>
    </term>
    <listitem>
      <para>
Specifies the string that contains the color space prefix.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>
function returns the format for the specified color space prefix
(for example, the string ``CIEXYZ'').
The prefix is case-insensitive.
If the color space is not accessible in the color management system,
<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>
returns
<symbol>XcmsUndefinedFormat</symbol>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain the color string prefix associated with the color space
specified by a color format, use
<xref linkend='XcmsPrefixOfFormat' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsPrefixOfFormat</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsPrefixOfFormat'>
<funcprototype>
  <funcdef>char *<function>XcmsPrefixOfFormat</function></funcdef>
  <paramdef>XcmsColorFormat <parameter>format</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>format</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color specification format.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsPrefixOfFormat' xrefstyle='select: title'/>
function returns the string prefix associated with the color specification
encoding specified by the format argument.
Otherwise, if no encoding is found, it returns NULL.
The returned string must be treated as read-only.
</para>
</sect2>
<sect2 id="Creating_Additional_Color_Spaces">
<title>Creating Additional Color Spaces</title>
<!-- .XS -->
<!-- (SN Creating Additional Color Spaces -->
<!-- .XE -->
<para>
<!-- .LP -->
Color space specific information necessary
for color space conversion and color string parsing is stored in an
<structname>XcmsColorSpace</structname>
structure.
Therefore, a new structure containing this information is required
for each additional color space.
In the case of device-independent color spaces,
a handle to this new structure (that is, by means of a global variable)
is usually made accessible to the client program for use with the
<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>
function.
</para>
<para>
<!-- .LP -->
If a new
<structname>XcmsColorSpace</structname>
structure specifies a color space not registered with the X Consortium,
they should be treated as private to the client
because format values for unregistered color spaces are assigned at run time.
If references to an unregistered color space must be made outside the
client (for example, storing color specifications in a file using the
unregistered color space), then reference should be made by color space prefix
(see
<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>
and
<xref linkend='XcmsPrefixOfFormat' xrefstyle='select: title'/>).
<!-- .sM -->
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef (*XcmsConversionProc)();
typedef XcmsConversionProc *XcmsFuncListPtr;
		/* A NULL terminated list of function pointers*/

typedef struct _XcmsColorSpace {
	char *prefix;
	XcmsColorFormat format;
	XcmsParseStringProc parseString;
	XcmsFuncListPtr to_CIEXYZ;
	XcmsFuncListPtr from_CIEXYZ;
	int inverse_flag;
} XcmsColorSpace;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The prefix member specifies the prefix that indicates a color string
is in this color space's string format.
For example, the strings ``ciexyz'' or ``CIEXYZ'' for <acronym>CIE</acronym> XYZ,
and ``rgb'' or ``<acronym>RGB</acronym>'' for <acronym>RGB</acronym>.
The prefix is case insensitive.
The format member specifies the color specification format.
Formats for unregistered color spaces are assigned at run time.
The parseString member contains a pointer to the function
that can parse a color string into an
<structname>XcmsColor</structname>
structure.
This function returns an integer (int): nonzero if it succeeded
and zero otherwise.
The to_CIEXYZ and from_CIEXYZ members contain pointers,
each to a NULL terminated list of function pointers.
When the list of functions is executed in series,
it will convert the color specified in an
<structname>XcmsColor</structname>
structure from/to the current color space format to/from the <acronym>CIE</acronym> XYZ format.
Each function returns an integer (int): nonzero if it succeeded
and zero otherwise.
The white point to be associated with the colors is specified
explicitly, even though white points can be found in the CCC.
The inverse_flag member, if nonzero, specifies that for each function listed
in to_CIEXYZ,
its inverse function can be found in from_CIEXYZ such that:
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
Given:  n = number of functions in each list

for each i, such that 0 &lt;= i &lt; n
    from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i].
</literallayout>
</para>
<para>
<!-- .LP -->
This allows Xlib to use the shortest conversion path,
thus bypassing <acronym>CIE</acronym> XYZ if possible (for example, TekHVC to <acronym>CIE</acronym> L*u*v*).
</para>
</sect2>
<sect2 id="Parse_String_Callback">
<title>Parse String Callback</title>
<!-- .XS -->
<!-- (SN Parse String Callback -->
<!-- .XE -->
<para>
<!-- .LP -->
The callback in the
<structname>XcmsColorSpace</structname>
structure for parsing a color string for the particular color space must
adhere to the following software interface specification:
</para>
<indexterm significance="preferred"><primary>XcmsParseStringProc</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsParseStringProc'>
<funcprototype>
  <funcdef>Status <function>XcmsParseStringProc</function></funcdef>
  <paramdef>char *<parameter>color_string</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>color_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_string</emphasis>
    </term>
    <listitem>
      <para>
Specifies the color string to parse.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>color_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the color specification in the color space's format.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
</para>
</sect2>
<sect2 id="Color_Specification_Conversion_Callback">
<title>Color Specification Conversion Callback</title>
<!-- .XS -->
<!-- (SN Color Specification Conversion Callback -->
<!-- .XE -->
<para>
<!-- .LP -->
Callback functions in the
<structname>XcmsColorSpace</structname>
structure for converting a color specification between device-independent
spaces must adhere to the
following software interface specification:
</para>
<!-- .sM -->
<funcsynopsis id='ConversionProc'>
<funcprototype>
  <funcdef>Status <function><replaceable>ConversionProc</replaceable></function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>white_point</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>colors_in_out</parameter></paramdef>
  <paramdef>unsigned int <parameter>ncolors</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>white_point</emphasis>
    </term>
    <listitem>
      <para>
Specifies the white point associated with color specifications.
The pixel member should be ignored,
and the entire structure remain unchanged upon return.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colors_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies an array of color specifications.
Pixel members should be ignored and must remain unchanged upon return.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ncolors</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of
<structname>XcmsColor</structname>
structures in the color-specification array.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
<!-- .sp -->
Callback functions in the
<structname>XcmsColorSpace</structname>
structure for converting a color specification to or from a device-dependent
space must adhere to the
following software interface specification:
</para>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
  <funcdef>Status <function><replaceable>ConversionProc</replaceable></function></funcdef>
  <paramdef>XcmsCCC <parameter>ccc</parameter></paramdef>
  <paramdef>XcmsColor *<parameter>colors_in_out</parameter></paramdef>
  <paramdef>unsigned int <parameter>ncolors</parameter></paramdef>
  <paramdef>Bool <parameter>compression_flags_return[]</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>ccc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the CCC.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>colors_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies an array of color specifications.
Pixel members should be ignored and must remain unchanged upon return.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ncolors</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of
<structname>XcmsColor</structname>
structures in the color-specification array.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>compression_flags_return</emphasis>
    </term>
    <listitem>
      <para>
Returns an array of Boolean values for indicating compression status.
If a non-NULL pointer is supplied
and a color at a given index is compressed, then
<symbol>True</symbol>
should be stored at the corresponding index in this array;
otherwise, the array should not be modified.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
Conversion functions are available globally for use by other color
spaces.
The conversion functions provided by Xlib are:
</para>
<informaltable frame='topbot'>
  <?dbfo keep-together="auto" ?>
  <tgroup cols='3' align='left' colsep='0' rowsep='0'>
  <colspec colname='c1' colwidth='1.0*'/>
  <colspec colname='c2' colwidth='1.0*'/>
  <colspec colname='c3' colwidth='1.0*'/>
  <thead>
    <row rowsep='1'>
      <entry>Function</entry>
      <entry>Converts from</entry>
      <entry>Converts to</entry>
    </row>
  </thead>
  <tbody>
    <row>
      <entry><function>XcmsCIELabToCIEXYZ</function></entry>
      <entry><symbol>XcmsCIELabFormat</symbol></entry>
      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsCIELuvToCIEuvY</function></entry>
      <entry><symbol>XcmsCIELuvFormat</symbol></entry>
      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsCIEXYZToCIELab</function></entry>
      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
      <entry><symbol>XcmsCIELabFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsCIEXYZToCIEuvY</function></entry>
      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsCIEXYZToCIExyY</function></entry>
      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
      <entry><symbol>XcmsCIExyYFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsCIEXYZToRGBi</function></entry>
      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
      <entry><symbol>XcmsRGBiFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsCIEuvYToCIELuv</function></entry>
      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>
      <entry><symbol>XcmsCIELabFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsCIEuvYToCIEXYZ</function></entry>
      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>
      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsCIEuvYToTekHVC</function></entry>
      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>
      <entry><symbol>XcmsTekHVCFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsCIExyYToCIEXYZ</function></entry>
      <entry><symbol>XcmsCIExyYFormat</symbol></entry>
      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsRGBToRGBi</function></entry>
      <entry><symbol>XcmsRGBFormat</symbol></entry>
      <entry><symbol>XcmsRGBiFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsRGBiToCIEXYZ</function></entry>
      <entry><symbol>XcmsRGBiFormat</symbol></entry>
      <entry><symbol>XcmsCIEXYZFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsRGBiToRGB</function></entry>
      <entry><symbol>XcmsRGBiFormat</symbol></entry>
      <entry><symbol>XcmsRGBFormat</symbol></entry>
    </row>
    <row>
      <entry><function>XcmsTekHVCToCIEuvY</function></entry>
      <entry><symbol>XcmsTekHVCFormat</symbol></entry>
      <entry><symbol>XcmsCIEuvYFormat</symbol></entry>
    </row>
  </tbody>
  </tgroup>
</informaltable>

</sect2>
<sect2 id="Function_Sets">
<title>Function Sets</title>
<!-- .XS -->
<!-- (SN Function Sets -->
<!-- .XE -->
<indexterm><primary>Function set</primary></indexterm>
<indexterm><primary>Function set</primary><secondary>LINEAR_RGB</secondary></indexterm>
<para>
<!-- .LP -->
Functions to convert between device-dependent color spaces
and <acronym>CIE</acronym> XYZ may differ for different classes of output devices
(for example, color versus gray monitors).
Therefore, the notion of a Color Characterization Function Set
has been developed.
A function set consists of device-dependent color spaces
and the functions that convert color specifications
between these device-dependent color spaces and the <acronym>CIE</acronym> XYZ color space
appropriate for a particular class of output devices.
The function set also contains a function that reads
color characterization data off root window properties.
It is this characterization data that will differ between devices within
a class of output devices.
<indexterm><primary>Device Color Characterization</primary></indexterm>
For details about how color characterization data is
stored in root window properties,
see <olink targetdoc='icccm' targetptr='Device_Color_Characterization'>the
section on Device Color Characterization in the
<citetitle>Inter-Client Communication Conventions Manual</citetitle></olink>.
The LINEAR_RGB function set is provided by Xlib
and will support most color monitors.
Function sets may require data that differs
from those needed for the LINEAR_RGB function set.
In that case,
its corresponding data may be stored on different root window properties.
</para>
</sect2>
<sect2 id="Adding_Function_Sets">
<title>Adding Function Sets</title>
<!-- .XS -->
<!-- (SN Adding Function Sets -->
<!-- .XE -->
<para>
<!-- .LP -->
To add a function set, use
<xref linkend='XcmsAddFunctionSet' xrefstyle='select: title'/>.
</para>
<indexterm significance="preferred"><primary>XcmsAddFunctionSet</primary></indexterm>
<!-- .sM -->
<funcsynopsis id='XcmsAddFunctionSet'>
<funcprototype>
  <funcdef>Status <function>XcmsAddFunctionSet</function></funcdef>
  <paramdef>XcmsFunctionSet *<parameter>function_set</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>function_set</emphasis>
    </term>
    <listitem>
      <para>
Specifies the function set to add.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The
<xref linkend='XcmsAddFunctionSet' xrefstyle='select: title'/>
function adds a function set to the color management system.
If the function set uses device-dependent
<structname>XcmsColorSpace</structname>
structures not accessible in the color management system,
<xref linkend='XcmsAddFunctionSet' xrefstyle='select: title'/>
adds them.
If an added
<structname>XcmsColorSpace</structname>
structure is for a device-dependent color space not registered
with the X Consortium,
they should be treated as private to the client
because format values for unregistered color spaces are assigned at run time.
If references to an unregistered color space must be made outside the
client (for example, storing color specifications in a file
using the unregistered color space),
then reference should be made by color space prefix
(see
<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>
and
<xref linkend='XcmsPrefixOfFormat' xrefstyle='select: title'/>).
</para>
<para>
<!-- .LP -->
Additional function sets should be added before any calls to other
Xlib routines are made.
If not, the
<structname>XcmsPerScrnInfo</structname>
member of a previously created
<structname>XcmsCCC</structname>
does not have the opportunity to initialize
with the added function set.
</para>
</sect2>
<sect2 id="Creating_Additional_Function_Sets">
<title>Creating Additional Function Sets</title>
<!-- .XS -->
<!-- (SN Creating Additional Function Sets -->
<!-- .XE -->
<para>
<!-- .LP -->
The creation of additional function sets should be
required only when an output device does not conform to existing
function sets or when additional device-dependent color spaces are necessary.
A function set consists primarily of a collection of device-dependent
<structname>XcmsColorSpace</structname>
structures and a means to read and store a
screen's color characterization data.
This data is stored in an
<structname>XcmsFunctionSet</structname>
structure.
A handle to this structure (that is, by means of global variable)
is usually made accessible to the client program for use with
<xref linkend='XcmsAddFunctionSet' xrefstyle='select: title'/>.
</para>
<para>
<!-- .LP -->
If a function set uses new device-dependent
<structname>XcmsColorSpace</structname>
structures,
they will be transparently processed into the color management system.
Function sets can share an
<structname>XcmsColorSpace</structname>
structure for a device-dependent color space.
In addition, multiple
<structname>XcmsColorSpace</structname>
structures are allowed for a device-dependent color space;
however, a function set can reference only one of them.
These
<structname>XcmsColorSpace</structname>
structures will differ in the functions to convert to and from <acronym>CIE</acronym> XYZ,
thus tailored for the specific function set.
<!-- .sM -->
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct _XcmsFunctionSet {
	XcmsColorSpace **DDColorSpaces;
	XcmsScreenInitProc screenInitProc;
	XcmsScreenFreeProc screenFreeProc;
} XcmsFunctionSet;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The DDColorSpaces member is a pointer to a NULL terminated list
of pointers to
<structname>XcmsColorSpace</structname>
structures for the device-dependent color spaces that are supported
by the function set.
The screenInitProc member is set to the callback procedure (see the following
interface specification) that initializes the
<structname>XcmsPerScrnInfo</structname>
structure for a particular screen.
</para>
<para>
<!-- .LP -->
The screen initialization callback must adhere to the following software
interface specification:
<indexterm significance="preferred"><primary>XcmsScreenInitProc</primary></indexterm>
<!-- .sM -->
</para>
<funcsynopsis>
<funcprototype>
  <funcdef>typedef Status <function>(*XcmsScreenInitProc</function>)</funcdef>
  <paramdef>Display *<parameter>display</parameter></paramdef>
  <paramdef>int <parameter>screen_number</parameter></paramdef>
  <paramdef>ScmsPerScrnInfo *<parameter>screen_info</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>screen_number</emphasis>
    </term>
    <listitem>
      <para>
Specifies the appropriate screen number on the host server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>screen_info</emphasis>
    </term>
    <listitem>
      <para>
Specifies the
<structname>XcmsPerScrnInfo</structname>
structure, which contains the per screen information.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
The screen initialization callback in the
<structname>XcmsFunctionSet</structname>
structure fetches the color characterization data (device profile) for
the specified screen,
typically off properties on the
screen's root window.
It then initializes the specified
<structname>XcmsPerScrnInfo</structname>
structure.
<indexterm><primary>Device profile</primary></indexterm>
<indexterm><primary>Color Characterization Data</primary></indexterm>
If successful, the procedure fills in the
<structname>XcmsPerScrnInfo</structname>
structure as follows:
</para>
<itemizedlist>
  <listitem>
    <para>
It sets the screenData member to the address
of the created device profile data structure
(contents known only by the function set).
    </para>
  </listitem>
  <listitem>
    <para>
It next sets the screenWhitePoint member.
    </para>
  </listitem>
  <listitem>
    <para>
It next sets the functionSet member to the address of the
<structname>XcmsFunctionSet</structname>
structure.
    </para>
  </listitem>
  <listitem>
    <para>
It then sets the state member to
<symbol>XcmsInitSuccess</symbol>
and finally returns
<symbol>XcmsSuccess</symbol>.
    </para>
  </listitem>
</itemizedlist>
<para>
<!-- .LP -->
If unsuccessful, the procedure sets the state member to
<symbol>XcmsInitFailure</symbol>
and returns
<symbol>XcmsFailure</symbol>.
</para>
<para>
<!-- .LP -->
The
<structname>XcmsPerScrnInfo</structname>
structure contains:
<!-- .sM -->
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct _XcmsPerScrnInfo {
	XcmsColor screenWhitePoint;
	XPointer functionSet;
	XPointer screenData;
	unsigned char state;
	char pad[3];
} XcmsPerScrnInfo;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The screenWhitePoint member specifies the white point inherent to
the screen.
The functionSet member specifies the appropriate function set.
The screenData member specifies the device profile.
The state member is set to one of the following:
</para>
<itemizedlist>
  <listitem>
    <para>
<symbol>XcmsInitNone</symbol>
indicates initialization has not been previously attempted.
    </para>
  </listitem>
  <listitem>
    <para>
<symbol>XcmsInitFailure</symbol>
indicates initialization has been previously attempted but failed.
    </para>
  </listitem>
  <listitem>
    <para>
<symbol>XcmsInitSuccess</symbol>
indicates initialization has been previously attempted and succeeded.
    </para>
  </listitem>
</itemizedlist>
<para>
<!-- .LP -->
The screen free callback must adhere to the following software
interface specification:
</para>
<funcsynopsis>
<funcprototype>
  <funcdef>typedef void (*XcmsScreenFreeProc)</funcdef>
  <paramdef>XPointer <parameter>screenData</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>screenData</emphasis>
    </term>
    <listitem>
      <para>
Specifies the data to be freed.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<!-- .LP -->
<!-- .eM -->
This function is called to free the screenData stored in an
<structname>XcmsPerScrnInfo</structname>
structure.
<!-- .bp -->

</para>
</sect2>
</sect1>
</chapter>