diff options
Diffstat (limited to 'libX11/specs/libX11/CH06.xml')
| -rw-r--r-- | libX11/specs/libX11/CH06.xml | 14896 |
1 files changed, 7448 insertions, 7448 deletions
diff --git a/libX11/specs/libX11/CH06.xml b/libX11/specs/libX11/CH06.xml index a8224d8fc..ab5cec031 100644 --- a/libX11/specs/libX11/CH06.xml +++ b/libX11/specs/libX11/CH06.xml @@ -1,7448 +1,7448 @@ -<?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"><X11/Xcms.h></filename>.
-<indexterm type="file"><primary><filename class="headerfile">X11/Xcms.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xcms.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xcms.h></filename></secondary></indexterm>
-The remaining functions and types are defined in
-<filename class="headerfile"><X11/Xlib.h></filename>.
-<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></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
-<function>XInstallColormap</function>
-and
-<function>XUninstallColormap</function>.
-</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 section 3.1).
-</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 section 6.12.4).
-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
-<function>XcmsFormatOfPrefix</function>
-and
-<function>XcmsPrefixOfFormat</function>).
-</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>
-<function>XAllocNamedColor</function>
- </para>
- </listitem>
- <listitem>
- <para>
-<function>XcmsAllocNamedColor</function>
- </para>
- </listitem>
- <listitem>
- <para>
-<function>XLookupColor</function>
- </para>
- </listitem>
- <listitem>
- <para>
-<function>XcmsLookupColor</function>
- </para>
- </listitem>
- <listitem>
- <para>
-<function>XParseColor</function>
- </para>
- </listitem>
- <listitem>
- <para>
-<function>XStoreNamedColor</function>
- </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'><color_space_name></emphasis>:<emphasis remap='I'><value>/.../<value></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'><red>/<green>/<blue></emphasis>
-
- <emphasis remap='I'><red></emphasis>, <emphasis remap='I'><green></emphasis>, <emphasis remap='I'><blue></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'><red>/<green>/<blue></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'><X>/<Y>/<Z></emphasis>
-CIEuvY:<emphasis remap='I'><u>/<v>/<Y></emphasis>
-CIExyY:<emphasis remap='I'><x>/<y>/<Y></emphasis>
-CIELab:<emphasis remap='I'><L>/<a>/<b></emphasis>
-CIELuv:<emphasis remap='I'><L>/<u>/<v></emphasis>
-TekHVC:<emphasis remap='I'><H>/<V>/<C></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
-<function>XCreateColormap</function>.</para>
-<indexterm significance="preferred"><primary>XCreateColormap</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Wi on whose screen you want to create a colormap -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window (Wi.
- </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
-<function>XCreateColormap</function>
-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 section 3.1.
-</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
-<function>XAllocColorCells</function>
-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
-<function>XAllocColorPlanes</function>
-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
-<function>XFreeColors</function>.
-</para>
-<para>
-<!-- .LP -->
-<function>XCreateColormap</function>
-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
-<function>XCopyColormapAndFree</function>.
-<indexterm significance="preferred"><primary>XCopyColormapAndFree</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XCopyColormapAndFree</function>
-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
-<function>XAllocColor</function>,
-<function>XAllocNamedColor</function>,
-<function>XAllocColorCells</function>,
-or
-<function>XAllocColorPlanes</function>
-and that have not been freed since they were allocated.
-</para>
-<para>
-<!-- .LP -->
-<function>XCopyColormapAndFree</function>
-can generate
-<errorname>BadAlloc</errorname>
-and
-<errorname>BadColor</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To destroy a colormap, use
-<function>XFreeColormap</function>.
-<indexterm significance="preferred"><primary>XFreeColormap</primary></indexterm>
-</para>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Cm that you want to destroy -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>colormap</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the colormap (Cm.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XFreeColormap</function>
-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
-<function>XUninstallColormap</function>).
-If the specified colormap is defined as the colormap for a window (by
-<function>XCreateWindow</function>,
-<function>XSetWindowColormap</function>,
-or
-<function>XChangeWindowAttributes</function>),
-<function>XFreeColormap</function>
-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 -->
-<function>XFreeColormap</function>
-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
-<function>XLookupColor</function>.
-<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
-<indexterm significance="preferred"><primary>XLookupColor</primary></indexterm>
-<!-- .sM -->
-</para>
-<funcsynopsis>
-<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*exact_def_return,<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
-<function>XLookupColor</function>
-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.
-<function>XLookupColor</function>
-returns nonzero if the name is resolved;
-otherwise, it returns zero.
-</para>
-<para>
-<!-- .LP -->
-<function>XLookupColor</function>
-can generate a
-<errorname>BadColor</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To map a color name to the exact <acronym>RGB</acronym> value, use
-<function>XParseColor</function>.
-</para>
-<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
-<indexterm significance="preferred"><primary>XParseColor</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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
-<function>XParseColor</function>
-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.
-<function>XParseColor</function>
-returns nonzero if the name is resolved;
-otherwise, it returns zero.
-</para>
-<para>
-<!-- .LP -->
-<function>XParseColor</function>
-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
-<function>XcmsLookupColor</function>.
-</para>
-<indexterm><primary>Color</primary><secondary>naming</secondary></indexterm>
-<indexterm significance="preferred"><primary>XcmsLookupColor</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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*color_exact_return,<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
-<function>XcmsLookupColor</function>
-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.
-<function>XcmsLookupColor</function>
-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
-<function>XAllocColor</function>.
-</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>
-<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
-<function>XAllocColor</function>
-function allocates a read-only colormap entry corresponding to the closest
-<acronym>RGB</acronym> value supported by the hardware.
-<function>XAllocColor</function>
-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,
-<function>XAllocColor</function>
-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.
-<function>XAllocColor</function>
-does not use or affect the flags in the
-<structname>XColor</structname>
-structure.
-</para>
-<para>
-<!-- .LP -->
-<function>XAllocColor</function>
-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
-<function>XcmsAllocColor</function>.
-</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>
-<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
-<function>XcmsAllocColor</function>
-function is similar to
-<function>XAllocColor</function>
-except the color can be specified in any format.
-The
-<function>XcmsAllocColor</function>
-function ultimately calls
-<function>XAllocColor</function>
-to allocate a read-only color cell (colormap entry) with the specified color.
-<function>XcmsAllocColor</function>
-first converts the color specified
-to an <acronym>RGB</acronym> value and then passes this to
-<function>XAllocColor</function>.
-<function>XcmsAllocColor</function>
-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
-<function>XAllocColor</function>
-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 -->
-<function>XcmsAllocColor</function>
-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
-<function>XAllocNamedColor</function>.
-</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>
-<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*screen_def_return,<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
-<function>XAllocNamedColor</function>
-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.
-<function>XAllocNamedColor</function>
-returns nonzero if a cell is allocated;
-otherwise, it returns zero.
-</para>
-<para>
-<!-- .LP -->
-<function>XAllocNamedColor</function>
-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
-<function>XcmsAllocNamedColor</function>.
-</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>
-<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.
-<!-- .ds St \ whose color definition structure is to be returned -->
- </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_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
-<function>XcmsAllocNamedColor</function>
-function is similar to
-<function>XAllocNamedColor</function>
-except that the color returned can be in any format specified.
-This function
-ultimately calls
-<function>XAllocColor</function>
-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
-<function>XcmsLookupColor</function>),
-converted
-to an <acronym>RGB</acronym> value, and finally passed to
-<function>XAllocColor</function>.
-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
-<function>XAllocColor</function>
-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 -->
-<function>XcmsAllocNamedColor</function>
-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
-<function>XAllocColorCells</function>.
-</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>
-<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>unsignedlong<parameter> plane_masks_return[]</parameter></paramdef>
- <paramdef>unsignedint<parameter> nplanes</parameter></paramdef>
- <paramdef>unsignedlong<parameter> pixels_return[]</parameter></paramdef>
- <paramdef>unsignedint<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
-<function>XAllocColorCells</function>
-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 × 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.
-<function>XAllocColorCells</function>
-returns nonzero if it succeeded or zero if it failed.
-</para>
-<para>
-<!-- .LP -->
-<function>XAllocColorCells</function>
-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
-<function>XAllocColorPlanes</function>.
-</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>
-<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>unsignedlong<parameter> pixels_return[]</parameter></paramdef>
- <paramdef>int<parameter> ncolors</parameter></paramdef>
- <paramdef>intnreds,ngreens,<parameter> nblues</parameter></paramdef>
- <paramdef>unsignedlong*rmask_return,*gmask_return,<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.
-<function>XAllocColorPlanes</function>
-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 × 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 × 2<superscript><emphasis>nreds</emphasis></superscript>
-independent red entries,
-ncolors × 2<superscript><emphasis>ngreens</emphasis></superscript>
-independent green entries, and
-ncolors × 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
-<function>XStoreColors</function>,
-<function>XStoreColor</function>,
-or
-<function>XStoreNamedColor</function>),
-the pixel is decomposed according to the masks,
-and the corresponding independent entries are updated.
-<function>XAllocColorPlanes</function>
-returns nonzero if it succeeded or zero if it failed.
-</para>
-<para>
-<!-- .LP -->
-<function>XAllocColorPlanes</function>
-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
-<function>XFreeColors</function>.
-<indexterm significance="preferred"><primary>XFreeColors</primary></indexterm>
-<indexterm><primary>Color</primary><secondary>deallocation</secondary></indexterm>
-<!-- .sM -->
-</para>
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XFreeColors</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Colormap<parameter> colormap</parameter></paramdef>
- <paramdef>unsignedlong<parameter> pixels[]</parameter></paramdef>
- <paramdef>int<parameter> npixels</parameter></paramdef>
- <paramdef>unsignedlong<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.
-<!-- .ds Pi that map to the cells in the specified colormap -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>pixels</emphasis>
- </term>
- <listitem>
- <para>
-Specifies an array of pixel values (Pi.
- </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
-<function>XFreeColors</function>
-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>
-<function>XAllocColor</function>,
-<function>XAllocNamedColor</function>,
-<function>XAllocColorCells</function>,
-and
-<function>XAllocColorPlanes</function>).
-Note that freeing an
-individual pixel obtained from
-<function>XAllocColorPlanes</function>
-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
-<function>XCreateColormap</function>),
-a
-<errorname>BadAccess</errorname>
-error results.
-If more than one pixel is in error,
-the one that gets reported is arbitrary.
-</para>
-<para>
-<!-- .LP -->
-<function>XFreeColors</function>
-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
-<function>XStoreColor</function>.
-</para>
-<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
-<indexterm significance="preferred"><primary>XStoreColor</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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
-<function>XStoreColor</function>
-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.
-<function>XStoreColor</function>
-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 -->
-<function>XStoreColor</function>
-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
-<function>XStoreColors</function>.
-</para>
-<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
-<indexterm significance="preferred"><primary>XStoreColors</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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
-<function>XStoreColors</function>
-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.
-<function>XStoreColors</function>
-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 -->
-<function>XStoreColors</function>
-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
-<function>XcmsStoreColor</function>.
-</para>
-<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
-<indexterm significance="preferred"><primary>XcmsStoreColor</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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
-<function>XcmsStoreColor</function>
-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
-<function>XStoreColor</function>
-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
-<function>XStoreColor</function>
-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
-<function>XStoreColor</function>
-was made.
-To obtain the actual color stored, use
-<function>XcmsQueryColor</function>.
-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 -->
-<function>XcmsStoreColor</function>
-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
-<function>XcmsStoreColors</function>.
-</para>
-<indexterm><primary>Color</primary><secondary>storing</secondary></indexterm>
-<indexterm significance="preferred"><primary>XcmsStoreColors</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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
-<function>XcmsStoreColors</function>
-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
-<function>XStoreColors</function>
-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
-<function>XStoreColors</function>
-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
-<function>XStoreColors</function>
-was made.
-To obtain the actual colors stored, use
-<function>XcmsQueryColors</function>.
-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 -->
-<function>XcmsStoreColors</function>
-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
-<function>XStoreNamedColor</function>.
-</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>
-<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>unsignedlong<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
-<function>XStoreNamedColor</function>
-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 -->
-<function>XStoreNamedColor</function>
-can generate
-<errorname>BadAccess</errorname>,
-<errorname>BadColor</errorname>,
-<errorname>BadName</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-The
-<function>XQueryColor</function>
-and
-<function>XQueryColors</function>
-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
-<function>XQueryColor</function>.
-</para>
-<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
-<indexterm significance="preferred"><primary>XQueryColor</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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
-<function>XQueryColor</function>
-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 -->
-<function>XQueryColor</function>
-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
-<function>XQueryColors</function>.
-</para>
-<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
-<indexterm significance="preferred"><primary>XQueryColors</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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
-<function>XQueryColors</function>
-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 -->
-<function>XQueryColors</function>
-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
-<function>XcmsQueryColor</function>.
-</para>
-<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
-<indexterm significance="preferred"><primary>XcmsQueryColor</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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
-<function>XcmsQueryColor</function>
-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 -->
-<function>XcmsQueryColor</function>
-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
-<function>XcmsQueryColors</function>.
-</para>
-<indexterm><primary>Color</primary><secondary>querying</secondary></indexterm>
-<indexterm significance="preferred"><primary>XcmsQueryColors</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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>unsignedint<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
-<function>XcmsQueryColors</function>
-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 -->
-<function>XcmsQueryColors</function>
-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
-<function>XcmsCCCOfColormap</function>.
-</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>
-<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
-<function>XcmsCCCOfColormap</function>
-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
-<function>XcmsSetCCCOfColormap</function>,
-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
-<function>XcmsSetCCCOfColormap</function>.
-</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>
-<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
-<function>XcmsSetCCCOfColormap</function>
-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
-<function>XcmsFreeCCC</function>.
-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
-<function>XcmsDefaultCCC</function>.
-</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>
-<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
-<function>XcmsDefaultCCC</function>
-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>
-<funcprototype>
- <funcdef><function>DisplayOfCCC</function></funcdef>
- <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<funcsynopsis>
-<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>
-<funcprototype>
- <funcdef><function>VisualOfCCC</function></funcdef>
- <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<funcsynopsis>
-<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>
-<funcprototype>
- <funcdef><function>ScreenNumberOfCCC</function></funcdef>
- <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<funcsynopsis>
-<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>
-<funcprototype>
- <funcdef><function>ScreenWhitePointOfCCC</function></funcdef>
- <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<funcsynopsis>
-<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>
-<funcprototype>
- <funcdef> <function>ClientWhitePointOfCCC</function></funcdef>
- <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<funcsynopsis>
-<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
-<function>XcmsSetWhitePoint</function>.
-</para>
-<indexterm significance="preferred"><primary>XcmsSetWhitePoint</primary></indexterm>
-<indexterm><primary>Client White Point</primary><secondary>of Color Conversion Context</secondary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Co new Client White Point -->
- </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
-<function>XcmsSetWhitePoint</function>
-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
-<function>XcmsSetCompressionProc</function>.
-</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>
-<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>.
-<!-- .ds Cd the gamut compression procedure -->
- </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
-<function>XcmsSetCompressionProc</function>
-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
-<function>XcmsSetWhiteAdjustProc</function>.
-</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>
-<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.
-<!-- .ds Cd 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
-<function>XcmsSetWhiteAdjustProc</function>
-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
-<function>XcmsCreateCCC</function>.
-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
-<function>XcmsFreeCCC</function>.
-<!-- .sp -->
-</para>
-<para>
-<!-- .LP -->
-To create a CCC, use
-<function>XcmsCreateCCC</function>.
-</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>
-<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
-<function>XcmsCreateCCC</function>
-function creates a CCC for the specified display, screen, and visual.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To free a CCC, use
-<function>XcmsFreeCCC</function>.
-</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>
-<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
-<function>XcmsFreeCCC</function>
-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
-<function>XcmsConvertColors</function>.
-</para>
-<indexterm><primary>Color conversion</primary></indexterm>
-<indexterm><primary>Color</primary><secondary>conversion</secondary></indexterm>
-<indexterm significance="preferred"><primary>XcmsConvertColors</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XcmsConvertColors</function></funcdef>
- <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
- <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>
- <paramdef>unsignedint<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
-<function>XcmsConvertColors</function>
-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>
-<funcprototype>
- <funcdef>typedef Status<function>(*XcmsCompressionProc</function>)</funcdef>
- <paramdef>XcmsCCC<parameter> ccc</parameter></paramdef>
- <paramdef>XcmsColor<parameter> colors_in_out[]</parameter></paramdef>
- <paramdef>unsignedint<parameter> ncolors</parameter></paramdef>
- <paramdef>unsignedint<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
-<function>XcmsAddColorSpace</function>
-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
-<function>XcmsCIELabQueryMaxC</function>.
-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
-<function>XcmsCIELuvQueryMaxC</function>.
-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>
-<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>unsignedint<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
-<function>XcmsAddColorSpace</function>
-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
-<function>XcmsAllocColor</function>
-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
-<function>XcmsAllocColor</function>
-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
-<function>XAllocColor</function>,
-and the <acronym>RGB</acronym>
-specification returned by
-<function>XAllocColor</function>
-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'><color_space></emphasis>QueryMax<emphasis remap='I'><dimensions></emphasis>
-
-Xcms<emphasis remap='I'><color_space></emphasis>QueryMin<emphasis remap='I'><dimensions></emphasis>
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-The <dimensions> consists of a letter or letters
-that identify the dimensions of the color space
-that are not fixed.
-For example,
-<function>XcmsTekHVCQueryMaxC</function>
-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
-<function>XcmsQueryBlack</function>.
-</para>
-<indexterm significance="preferred"><primary>XcmsQueryBlack</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Cs zero-intensity red, green, and blue -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>color_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the color specification in the specified target format
-for (Cs.
-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
-<function>XcmsQueryBlack</function>
-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
-<function>XcmsQueryBlue</function>.
-</para>
-<indexterm significance="preferred"><primary>XcmsQueryBlue</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Cs full-intensity blue while red and green are zero -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>color_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the color specification in the specified target format
-for (Cs.
-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
-<function>XcmsQueryBlue</function>
-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
-<function>XcmsQueryGreen</function>.
-</para>
-<indexterm significance="preferred"><primary>XcmsQueryGreen</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Cs full-intensity green while red and blue are zero -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>color_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the color specification in the specified target format
-for (Cs.
-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
-<function>XcmsQueryGreen</function>
-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
-<function>XcmsQueryRed</function>.
-</para>
-<indexterm significance="preferred"><primary>XcmsQueryRed</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Cs full-intensity red while green and blue are zero -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>color_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the color specification in the specified target format
-for (Cs.
-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
-<function>XcmsQueryRed</function>
-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
-<function>XcmsQueryWhite</function>.
-</para>
-<indexterm significance="preferred"><primary>XcmsQueryWhite</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Cs full-intensity red, green, and blue -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>color_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the color specification in the specified target format
-for (Cs.
-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
-<function>XcmsQueryWhite</function>
-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
-<function>XcmsCIELabQueryMaxC</function>.
-</para>
-<indexterm significance="preferred"><primary>XcmsCIELabQueryMaxC</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Ha maximum chroma -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue_angle</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the hue angle (in degrees) at which to find (Ha.
-<!-- .ds Ls maximum chroma -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>L_star</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the lightness (L*) at which to find (Ls.
-<!-- .ds Lc maximum chroma -->
-<!-- .ds lC hue angle and 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 (Lc
-displayable by the screen for the given (lC.
-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
-<function>XcmsCIELabQueryMaxC</function>
-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
-<function>XcmsCIELabQueryMaxL</function>.
-</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>
-<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.
-<!-- .ds Ha maximum lightness -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue_angle</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the hue angle (in degrees) at which to find (Ha.
-<!-- .ds Ch maximum lightness -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>chroma</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the chroma at which to find (Ch.
-<!-- .ds Lc maximum lightness -->
-<!-- .ds lC hue angle and 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 (Lc
-displayable by the screen for the given (lC.
-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
-<function>XcmsCIELabQueryMaxL</function>
-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
-<function>XcmsCIELabQueryMaxLC</function>.
-</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>
-<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.
-<!-- .ds Ha maximum chroma -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue_angle</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the hue angle (in degrees) at which to find (Ha.
-<!-- .ds Lc maximum chroma -->
-<!-- .ds lC hue angle -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>color_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc
-displayable by the screen for the given (lC.
-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
-<function>XcmsCIELabQueryMaxLC</function>
-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
-<function>XcmsCIELabQueryMinL</function>.
-</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>
-<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.
-<!-- .ds Ha minimum lightness -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue_angle</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the hue angle (in degrees) at which to find (Ha.
-<!-- .ds Ch minimum lightness -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>chroma</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the chroma at which to find (Ch.
-<!-- .ds Lc minimum lightness -->
-<!-- .ds lC hue angle and 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 (Lc
-displayable by the screen for the given (lC.
-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
-<function>XcmsCIELabQueryMinL</function>
-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
-<function>XcmsCIELuvQueryMaxC</function>.
-</para>
-<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxC</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Ha maximum chroma -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue_angle</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the hue angle (in degrees) at which to find (Ha.
-<!-- .ds Ls maximum chroma -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>L_star</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the lightness (L*) at which to find (Ls.
-<!-- .ds Lc maximum chroma -->
-<!-- .ds lC hue angle and 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 (Lc
-displayable by the screen for the given (lC.
-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
-<function>XcmsCIELuvQueryMaxC</function>
-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
-<function>XcmsCIELuvQueryMaxL</function>.
-</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>
-<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.
-<!-- .ds Ha maximum lightness -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue_angle</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the hue angle (in degrees) at which to find (Ha.
-<!-- .ds Ls maximum lightness -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>L_star</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the lightness (L*) at which to find (Ls.
-<!-- .ds Lc maximum lightness -->
-<!-- .ds lC hue angle and 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 (Lc
-displayable by the screen for the given (lC.
-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
-<function>XcmsCIELuvQueryMaxL</function>
-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
-<function>XcmsCIELuvQueryMaxLC</function>.
-</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>
-<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.
-<!-- .ds Ha maximum chroma -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue_angle</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the hue angle (in degrees) at which to find (Ha.
-<!-- .ds Lc maximum chroma -->
-<!-- .ds lC hue angle -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>color_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc
-displayable by the screen for the given (lC.
-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
-<function>XcmsCIELuvQueryMaxLC</function>
-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
-<function>XcmsCIELuvQueryMinL</function>.
-</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>
-<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.
-<!-- .ds Ha minimum lightness -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue_angle</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the hue angle (in degrees) at which to find (Ha.
-<!-- .ds Ch minimum lightness -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>chroma</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the chroma at which to find (Ch.
-<!-- .ds Lc minimum lightness -->
-<!-- .ds lC hue angle and 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 (Lc
-displayable by the screen for the given (lC.
-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
-<function>XcmsCIELuvQueryMinL</function>
-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
-<function>XcmsTekHVCQueryMaxC</function>.
-</para>
-<indexterm><primary>Chroma</primary></indexterm>
-<indexterm><primary>Chroma</primary><secondary>maximum</secondary></indexterm>
-<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxC</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Hu in which to find the maximum Chroma -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the Hue (Hu.
-<!-- .ds Va maximum Chroma -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>value</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the Value in which to find the (Va.
-<!-- .ds Lc maximum Chroma along with the actual Hue and Value -->
-<!-- .ds lC maximum Chroma -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>color_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the (Lc at which the (lC 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
-<function>XcmsTekHVCQueryMaxC</function>
-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
-<function>XcmsTekHVCQueryMaxV</function>.
-</para>
-<indexterm><primary>Value</primary></indexterm>
-<indexterm><primary>Value</primary><secondary>maximum</secondary></indexterm>
-<indexterm significance="preferred"><primary>XcmsTekHVCQueryMaxV</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Hu in which to find the maximum Value -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the Hue (Hu.
-<!-- .ds Ch maximum Value -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>chroma</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the chroma at which to find (Ch.
-<!-- .ds Lc maximum Value along with the Hue and Chroma -->
-<!-- .ds lC maximum Value -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>color_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the (Lc at which the (lC 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
-<function>XcmsTekHVCQueryMaxV</function>
-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
-<function>XcmsTekHVCQueryMaxVC</function>.
-</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>
-<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.
-<!-- .ds Hu in which to find the maximum Chroma -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the Hue (Hu.
-<!-- .ds Lc color specification in \ -->
-XcmsTekHVC for the maximum Chroma, the Value at which \
-that maximum Chroma is reached, and the actual Hue
-<!-- .ds lC maximum Chroma -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>color_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the (Lc at which the (lC 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
-<function>XcmsTekHVCQueryMaxVC</function>
-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
-<function>XcmsTekHVCQueryMaxVSamples</function>.
-</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>
-<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>unsignedint<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.
-<!-- .ds Hu for maximum Chroma/Value samples -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the Hue (Hu.
- </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
-<function>XcmsTekHVCQueryMaxVSamples</function>
-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
-<function>XcmsTekHVCQueryMinV</function>.
-</para>
-<indexterm><primary>Value</primary></indexterm>
-<indexterm><primary>Value</primary><secondary>minimum</secondary></indexterm>
-<indexterm significance="preferred"><primary>XcmsTekHVCQueryMinV</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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.
-<!-- .ds Hu in which to find the minimum Value -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hue</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the Hue (Hu.
-<!-- .ds Va minimum Value -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>value</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the Value in which to find the (Va.
-<!-- .ds Lc minimum Value and the actual Hue and Chroma -->
-<!-- .ds lC minimum Value -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>color_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the (Lc at which the (lC 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
-<function>XcmsTekHVCQueryMinV</function>
-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
-<function>XcmsAddColorSpace</function>
-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
-<function>XcmsAddFunctionSet</function>
-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
-<function>XcmsAddColorSpace</function>.
-</para>
-<indexterm significance="preferred"><primary>XcmsAddColorSpace</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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
-<function>XcmsAddColorSpace</function>
-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
-<function>XcmsFormatOfPrefix</function>
-and
-<function>XcmsPrefixOfFormat</function>).
-</para>
-<para>
-<!-- .LP -->
-If the
-<structname>XcmsColorSpace</structname>
-structure is already accessible in the color management system,
-<function>XcmsAddColorSpace</function>
-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
-<function>XcmsFormatOfPrefix</function>.
-</para>
-<indexterm significance="preferred"><primary>XcmsFormatOfPrefix</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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
-<function>XcmsFormatOfPrefix</function>
-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,
-<function>XcmsFormatOfPrefix</function>
-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
-<function>XcmsPrefixOfFormat</function>.
-</para>
-<indexterm significance="preferred"><primary>XcmsPrefixOfFormat</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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
-<function>XcmsPrefixOfFormat</function>
-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
-<function>XcmsAddColorSpace</function>
-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
-<function>XcmsFormatOfPrefix</function>
-and
-<function>XcmsPrefixOfFormat</function>).
-<!-- .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 <= i < 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>
-<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>
-<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>unsignedint<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>unsignedint<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>
- <tgroup cols='3' align='center'>
- <colspec colname='c1'/>
- <colspec colname='c2'/>
- <colspec colname='c3'/>
- <thead>
- <row>
- <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 the section on Device Color Characterization in the
-<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
-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
-<function>XcmsAddFunctionSet</function>.
-</para>
-<indexterm significance="preferred"><primary>XcmsAddFunctionSet</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<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
-<function>XcmsAddFunctionSet</function>
-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,
-<function>XcmsAddFunctionSet</function>
-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
-<function>XcmsFormatOfPrefix</function>
-and
-<function>XcmsPrefixOfFormat</function>).
-</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
-<function>XcmsAddFunctionSet</function>.
-</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>
+<?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"><X11/Xcms.h></filename>. +<indexterm type="file"><primary><filename class="headerfile">X11/Xcms.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xcms.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xcms.h></filename></secondary></indexterm> +The remaining functions and types are defined in +<filename class="headerfile"><X11/Xlib.h></filename>. +<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></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 +<function>XInstallColormap</function> +and +<function>XUninstallColormap</function>. +</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 section 3.1). +</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 section 6.12.4). +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 +<function>XcmsFormatOfPrefix</function> +and +<function>XcmsPrefixOfFormat</function>). +</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> +<function>XAllocNamedColor</function> + </para> + </listitem> + <listitem> + <para> +<function>XcmsAllocNamedColor</function> + </para> + </listitem> + <listitem> + <para> +<function>XLookupColor</function> + </para> + </listitem> + <listitem> + <para> +<function>XcmsLookupColor</function> + </para> + </listitem> + <listitem> + <para> +<function>XParseColor</function> + </para> + </listitem> + <listitem> + <para> +<function>XStoreNamedColor</function> + </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'><color_space_name></emphasis>:<emphasis remap='I'><value>/.../<value></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'><red>/<green>/<blue></emphasis> + + <emphasis remap='I'><red></emphasis>, <emphasis remap='I'><green></emphasis>, <emphasis remap='I'><blue></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'><red>/<green>/<blue></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'><X>/<Y>/<Z></emphasis> +CIEuvY:<emphasis remap='I'><u>/<v>/<Y></emphasis> +CIExyY:<emphasis remap='I'><x>/<y>/<Y></emphasis> +CIELab:<emphasis remap='I'><L>/<a>/<b></emphasis> +CIELuv:<emphasis remap='I'><L>/<u>/<v></emphasis> +TekHVC:<emphasis remap='I'><H>/<V>/<C></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 +<function>XCreateColormap</function>.</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. +<!-- .ds Wi on whose screen you want to create a colormap --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window (Wi. + </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 +<function>XCreateColormap</function> +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 section 3.1. +</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 +<function>XAllocColorCells</function> +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 +<function>XAllocColorPlanes</function> +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 +<function>XFreeColors</function>. +</para> +<para> +<!-- .LP --> +<function>XCreateColormap</function> +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 +<function>XCopyColormapAndFree</function>. +<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> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XCopyColormapAndFree</function> +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 +<function>XAllocColor</function>, +<function>XAllocNamedColor</function>, +<function>XAllocColorCells</function>, +or +<function>XAllocColorPlanes</function> +and that have not been freed since they were allocated. +</para> +<para> +<!-- .LP --> +<function>XCopyColormapAndFree</function> +can generate +<errorname>BadAlloc</errorname> +and +<errorname>BadColor</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To destroy a colormap, use +<function>XFreeColormap</function>. +<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. +<!-- .ds Cm that you want to destroy --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>colormap</emphasis> + </term> + <listitem> + <para> +Specifies the colormap (Cm. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XFreeColormap</function> +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 +<function>XUninstallColormap</function>). +If the specified colormap is defined as the colormap for a window (by +<function>XCreateWindow</function>, +<function>XSetWindowColormap</function>, +or +<function>XChangeWindowAttributes</function>), +<function>XFreeColormap</function> +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 --> +<function>XFreeColormap</function> +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 +<function>XLookupColor</function>. +<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*exact_def_return,<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 +<function>XLookupColor</function> +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. +<function>XLookupColor</function> +returns nonzero if the name is resolved; +otherwise, it returns zero. +</para> +<para> +<!-- .LP --> +<function>XLookupColor</function> +can generate a +<errorname>BadColor</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To map a color name to the exact <acronym>RGB</acronym> value, use +<function>XParseColor</function>. +</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 +<function>XParseColor</function> +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. +<function>XParseColor</function> +returns nonzero if the name is resolved; +otherwise, it returns zero. +</para> +<para> +<!-- .LP --> +<function>XParseColor</function> +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 +<function>XcmsLookupColor</function>. +</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*color_exact_return,<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 +<function>XcmsLookupColor</function> +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. +<function>XcmsLookupColor</function> +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 +<function>XAllocColor</function>. +</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 +<function>XAllocColor</function> +function allocates a read-only colormap entry corresponding to the closest +<acronym>RGB</acronym> value supported by the hardware. +<function>XAllocColor</function> +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, +<function>XAllocColor</function> +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. +<function>XAllocColor</function> +does not use or affect the flags in the +<structname>XColor</structname> +structure. +</para> +<para> +<!-- .LP --> +<function>XAllocColor</function> +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 +<function>XcmsAllocColor</function>. +</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 +<function>XcmsAllocColor</function> +function is similar to +<function>XAllocColor</function> +except the color can be specified in any format. +The +<function>XcmsAllocColor</function> +function ultimately calls +<function>XAllocColor</function> +to allocate a read-only color cell (colormap entry) with the specified color. +<function>XcmsAllocColor</function> +first converts the color specified +to an <acronym>RGB</acronym> value and then passes this to +<function>XAllocColor</function>. +<function>XcmsAllocColor</function> +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 +<function>XAllocColor</function> +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 --> +<function>XcmsAllocColor</function> +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 +<function>XAllocNamedColor</function>. +</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*screen_def_return,<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 +<function>XAllocNamedColor</function> +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. +<function>XAllocNamedColor</function> +returns nonzero if a cell is allocated; +otherwise, it returns zero. +</para> +<para> +<!-- .LP --> +<function>XAllocNamedColor</function> +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 +<function>XcmsAllocNamedColor</function>. +</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. +<!-- .ds St \ whose color definition structure is to be returned --> + </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_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 +<function>XcmsAllocNamedColor</function> +function is similar to +<function>XAllocNamedColor</function> +except that the color returned can be in any format specified. +This function +ultimately calls +<function>XAllocColor</function> +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 +<function>XcmsLookupColor</function>), +converted +to an <acronym>RGB</acronym> value, and finally passed to +<function>XAllocColor</function>. +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 +<function>XAllocColor</function> +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 --> +<function>XcmsAllocNamedColor</function> +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 +<function>XAllocColorCells</function>. +</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>unsignedlong<parameter> plane_masks_return[]</parameter></paramdef> + <paramdef>unsignedint<parameter> nplanes</parameter></paramdef> + <paramdef>unsignedlong<parameter> pixels_return[]</parameter></paramdef> + <paramdef>unsignedint<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 +<function>XAllocColorCells</function> +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 × 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. +<function>XAllocColorCells</function> +returns nonzero if it succeeded or zero if it failed. +</para> +<para> +<!-- .LP --> +<function>XAllocColorCells</function> +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 +<function>XAllocColorPlanes</function>. +</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>unsignedlong<parameter> pixels_return[]</parameter></paramdef> + <paramdef>int<parameter> ncolors</parameter></paramdef> + <paramdef>intnreds,ngreens,<parameter> nblues</parameter></paramdef> + <paramdef>unsignedlong*rmask_return,*gmask_return,<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. +<function>XAllocColorPlanes</function> +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 × 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 × 2<superscript><emphasis>nreds</emphasis></superscript> +independent red entries, +ncolors × 2<superscript><emphasis>ngreens</emphasis></superscript> +independent green entries, and +ncolors × 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 +<function>XStoreColors</function>, +<function>XStoreColor</function>, +or +<function>XStoreNamedColor</function>), +the pixel is decomposed according to the masks, +and the corresponding independent entries are updated. +<function>XAllocColorPlanes</function> +returns nonzero if it succeeded or zero if it failed. +</para> +<para> +<!-- .LP --> +<function>XAllocColorPlanes</function> +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 +<function>XFreeColors</function>. +<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>unsignedlong<parameter> pixels[]</parameter></paramdef> + <paramdef>int<parameter> npixels</parameter></paramdef> + <paramdef>unsignedlong<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. +<!-- .ds Pi that map to the cells in the specified colormap --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>pixels</emphasis> + </term> + <listitem> + <para> +Specifies an array of pixel values (Pi. + </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 +<function>XFreeColors</function> +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> +<function>XAllocColor</function>, +<function>XAllocNamedColor</function>, +<function>XAllocColorCells</function>, +and +<function>XAllocColorPlanes</function>). +Note that freeing an +individual pixel obtained from +<function>XAllocColorPlanes</function> +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 +<function>XCreateColormap</function>), +a +<errorname>BadAccess</errorname> +error results. +If more than one pixel is in error, +the one that gets reported is arbitrary. +</para> +<para> +<!-- .LP --> +<function>XFreeColors</function> +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 +<function>XStoreColor</function>. +</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 +<function>XStoreColor</function> +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. +<function>XStoreColor</function> +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 --> +<function>XStoreColor</function> +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 +<function>XStoreColors</function>. +</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 +<function>XStoreColors</function> +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. +<function>XStoreColors</function> +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 --> +<function>XStoreColors</function> +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 +<function>XcmsStoreColor</function>. +</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 +<function>XcmsStoreColor</function> +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 +<function>XStoreColor</function> +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 +<function>XStoreColor</function> +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 +<function>XStoreColor</function> +was made. +To obtain the actual color stored, use +<function>XcmsQueryColor</function>. +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 --> +<function>XcmsStoreColor</function> +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 +<function>XcmsStoreColors</function>. +</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 +<function>XcmsStoreColors</function> +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 +<function>XStoreColors</function> +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 +<function>XStoreColors</function> +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 +<function>XStoreColors</function> +was made. +To obtain the actual colors stored, use +<function>XcmsQueryColors</function>. +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 --> +<function>XcmsStoreColors</function> +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 +<function>XStoreNamedColor</function>. +</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>unsignedlong<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 +<function>XStoreNamedColor</function> +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 --> +<function>XStoreNamedColor</function> +can generate +<errorname>BadAccess</errorname>, +<errorname>BadColor</errorname>, +<errorname>BadName</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +The +<function>XQueryColor</function> +and +<function>XQueryColors</function> +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 +<function>XQueryColor</function>. +</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 +<function>XQueryColor</function> +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 --> +<function>XQueryColor</function> +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 +<function>XQueryColors</function>. +</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 +<function>XQueryColors</function> +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 --> +<function>XQueryColors</function> +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 +<function>XcmsQueryColor</function>. +</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 +<function>XcmsQueryColor</function> +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 --> +<function>XcmsQueryColor</function> +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 +<function>XcmsQueryColors</function>. +</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>unsignedint<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 +<function>XcmsQueryColors</function> +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 --> +<function>XcmsQueryColors</function> +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 +<function>XcmsCCCOfColormap</function>. +</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 +<function>XcmsCCCOfColormap</function> +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 +<function>XcmsSetCCCOfColormap</function>, +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 +<function>XcmsSetCCCOfColormap</function>. +</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 +<function>XcmsSetCCCOfColormap</function> +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 +<function>XcmsFreeCCC</function>. +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 +<function>XcmsDefaultCCC</function>. +</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 +<function>XcmsDefaultCCC</function> +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 +<function>XcmsSetWhitePoint</function>. +</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. +<!-- .ds Co new Client White Point --> + </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 +<function>XcmsSetWhitePoint</function> +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 +<function>XcmsSetCompressionProc</function>. +</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>. +<!-- .ds Cd the gamut compression procedure --> + </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 +<function>XcmsSetCompressionProc</function> +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 +<function>XcmsSetWhiteAdjustProc</function>. +</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. +<!-- .ds Cd 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 +<function>XcmsSetWhiteAdjustProc</function> +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 +<function>XcmsCreateCCC</function>. +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 +<function>XcmsFreeCCC</function>. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To create a CCC, use +<function>XcmsCreateCCC</function>. +</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 +<function>XcmsCreateCCC</function> +function creates a CCC for the specified display, screen, and visual. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To free a CCC, use +<function>XcmsFreeCCC</function>. +</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 +<function>XcmsFreeCCC</function> +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 +<function>XcmsConvertColors</function>. +</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>unsignedint<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 +<function>XcmsConvertColors</function> +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>unsignedint<parameter> ncolors</parameter></paramdef> + <paramdef>unsignedint<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 +<function>XcmsAddColorSpace</function> +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 +<function>XcmsCIELabQueryMaxC</function>. +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 +<function>XcmsCIELuvQueryMaxC</function>. +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>unsignedint<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 +<function>XcmsAddColorSpace</function> +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 +<function>XcmsAllocColor</function> +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 +<function>XcmsAllocColor</function> +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 +<function>XAllocColor</function>, +and the <acronym>RGB</acronym> +specification returned by +<function>XAllocColor</function> +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'><color_space></emphasis>QueryMax<emphasis remap='I'><dimensions></emphasis> + +Xcms<emphasis remap='I'><color_space></emphasis>QueryMin<emphasis remap='I'><dimensions></emphasis> +</literallayout> +</para> +<para> +<!-- .LP --> +The <dimensions> consists of a letter or letters +that identify the dimensions of the color space +that are not fixed. +For example, +<function>XcmsTekHVCQueryMaxC</function> +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 +<function>XcmsQueryBlack</function>. +</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. +<!-- .ds Cs zero-intensity red, green, and blue --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>color_return</emphasis> + </term> + <listitem> + <para> +Returns the color specification in the specified target format +for (Cs. +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 +<function>XcmsQueryBlack</function> +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 +<function>XcmsQueryBlue</function>. +</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. +<!-- .ds Cs full-intensity blue while red and green are zero --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>color_return</emphasis> + </term> + <listitem> + <para> +Returns the color specification in the specified target format +for (Cs. +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 +<function>XcmsQueryBlue</function> +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 +<function>XcmsQueryGreen</function>. +</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. +<!-- .ds Cs full-intensity green while red and blue are zero --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>color_return</emphasis> + </term> + <listitem> + <para> +Returns the color specification in the specified target format +for (Cs. +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 +<function>XcmsQueryGreen</function> +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 +<function>XcmsQueryRed</function>. +</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. +<!-- .ds Cs full-intensity red while green and blue are zero --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>color_return</emphasis> + </term> + <listitem> + <para> +Returns the color specification in the specified target format +for (Cs. +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 +<function>XcmsQueryRed</function> +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 +<function>XcmsQueryWhite</function>. +</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. +<!-- .ds Cs full-intensity red, green, and blue --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>color_return</emphasis> + </term> + <listitem> + <para> +Returns the color specification in the specified target format +for (Cs. +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 +<function>XcmsQueryWhite</function> +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 +<function>XcmsCIELabQueryMaxC</function>. +</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. +<!-- .ds Ha maximum chroma --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue_angle</emphasis> + </term> + <listitem> + <para> +Specifies the hue angle (in degrees) at which to find (Ha. +<!-- .ds Ls maximum chroma --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>L_star</emphasis> + </term> + <listitem> + <para> +Specifies the lightness (L*) at which to find (Ls. +<!-- .ds Lc maximum chroma --> +<!-- .ds lC hue angle and 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 (Lc +displayable by the screen for the given (lC. +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 +<function>XcmsCIELabQueryMaxC</function> +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 +<function>XcmsCIELabQueryMaxL</function>. +</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. +<!-- .ds Ha maximum lightness --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue_angle</emphasis> + </term> + <listitem> + <para> +Specifies the hue angle (in degrees) at which to find (Ha. +<!-- .ds Ch maximum lightness --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>chroma</emphasis> + </term> + <listitem> + <para> +Specifies the chroma at which to find (Ch. +<!-- .ds Lc maximum lightness --> +<!-- .ds lC hue angle and 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 (Lc +displayable by the screen for the given (lC. +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 +<function>XcmsCIELabQueryMaxL</function> +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 +<function>XcmsCIELabQueryMaxLC</function>. +</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. +<!-- .ds Ha maximum chroma --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue_angle</emphasis> + </term> + <listitem> + <para> +Specifies the hue angle (in degrees) at which to find (Ha. +<!-- .ds Lc maximum chroma --> +<!-- .ds lC hue angle --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>color_return</emphasis> + </term> + <listitem> + <para> +Returns the <acronym>CIE</acronym> L*a*b* coordinates of (Lc +displayable by the screen for the given (lC. +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 +<function>XcmsCIELabQueryMaxLC</function> +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 +<function>XcmsCIELabQueryMinL</function>. +</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='xcmscielabqueryminlc'> +<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. +<!-- .ds Ha minimum lightness --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue_angle</emphasis> + </term> + <listitem> + <para> +Specifies the hue angle (in degrees) at which to find (Ha. +<!-- .ds Ch minimum lightness --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>chroma</emphasis> + </term> + <listitem> + <para> +Specifies the chroma at which to find (Ch. +<!-- .ds Lc minimum lightness --> +<!-- .ds lC hue angle and 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 (Lc +displayable by the screen for the given (lC. +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 +<function>XcmsCIELabQueryMinL</function> +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 +<function>XcmsCIELuvQueryMaxC</function>. +</para> +<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxC</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xcmxcieluvquerymaxc'> +<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. +<!-- .ds Ha maximum chroma --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue_angle</emphasis> + </term> + <listitem> + <para> +Specifies the hue angle (in degrees) at which to find (Ha. +<!-- .ds Ls maximum chroma --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>L_star</emphasis> + </term> + <listitem> + <para> +Specifies the lightness (L*) at which to find (Ls. +<!-- .ds Lc maximum chroma --> +<!-- .ds lC hue angle and 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 (Lc +displayable by the screen for the given (lC. +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 +<function>XcmsCIELuvQueryMaxC</function> +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 +<function>XcmsCIELuvQueryMaxL</function>. +</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. +<!-- .ds Ha maximum lightness --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue_angle</emphasis> + </term> + <listitem> + <para> +Specifies the hue angle (in degrees) at which to find (Ha. +<!-- .ds Ls maximum lightness --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>L_star</emphasis> + </term> + <listitem> + <para> +Specifies the lightness (L*) at which to find (Ls. +<!-- .ds Lc maximum lightness --> +<!-- .ds lC hue angle and 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 (Lc +displayable by the screen for the given (lC. +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 +<function>XcmsCIELuvQueryMaxL</function> +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 +<function>XcmsCIELuvQueryMaxLC</function>. +</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. +<!-- .ds Ha maximum chroma --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue_angle</emphasis> + </term> + <listitem> + <para> +Specifies the hue angle (in degrees) at which to find (Ha. +<!-- .ds Lc maximum chroma --> +<!-- .ds lC hue angle --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>color_return</emphasis> + </term> + <listitem> + <para> +Returns the <acronym>CIE</acronym> L*u*v* coordinates of (Lc +displayable by the screen for the given (lC. +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 +<function>XcmsCIELuvQueryMaxLC</function> +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 +<function>XcmsCIELuvQueryMinL</function>. +</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. +<!-- .ds Ha minimum lightness --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue_angle</emphasis> + </term> + <listitem> + <para> +Specifies the hue angle (in degrees) at which to find (Ha. +<!-- .ds Ch minimum lightness --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>chroma</emphasis> + </term> + <listitem> + <para> +Specifies the chroma at which to find (Ch. +<!-- .ds Lc minimum lightness --> +<!-- .ds lC hue angle and 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 (Lc +displayable by the screen for the given (lC. +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 +<function>XcmsCIELuvQueryMinL</function> +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 +<function>XcmsTekHVCQueryMaxC</function>. +</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. +<!-- .ds Hu in which to find the maximum Chroma --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue</emphasis> + </term> + <listitem> + <para> +Specifies the Hue (Hu. +<!-- .ds Va maximum Chroma --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value</emphasis> + </term> + <listitem> + <para> +Specifies the Value in which to find the (Va. +<!-- .ds Lc maximum Chroma along with the actual Hue and Value --> +<!-- .ds lC maximum Chroma --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>color_return</emphasis> + </term> + <listitem> + <para> +Returns the (Lc at which the (lC 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 +<function>XcmsTekHVCQueryMaxC</function> +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 +<function>XcmsTekHVCQueryMaxV</function>. +</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. +<!-- .ds Hu in which to find the maximum Value --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue</emphasis> + </term> + <listitem> + <para> +Specifies the Hue (Hu. +<!-- .ds Ch maximum Value --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>chroma</emphasis> + </term> + <listitem> + <para> +Specifies the chroma at which to find (Ch. +<!-- .ds Lc maximum Value along with the Hue and Chroma --> +<!-- .ds lC maximum Value --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>color_return</emphasis> + </term> + <listitem> + <para> +Returns the (Lc at which the (lC 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 +<function>XcmsTekHVCQueryMaxV</function> +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 +<function>XcmsTekHVCQueryMaxVC</function>. +</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. +<!-- .ds Hu in which to find the maximum Chroma --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue</emphasis> + </term> + <listitem> + <para> +Specifies the Hue (Hu. +<!-- .ds Lc color specification in \ --> +XcmsTekHVC for the maximum Chroma, the Value at which \ +that maximum Chroma is reached, and the actual Hue +<!-- .ds lC maximum Chroma --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>color_return</emphasis> + </term> + <listitem> + <para> +Returns the (Lc at which the (lC 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 +<function>XcmsTekHVCQueryMaxVC</function> +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 +<function>XcmsTekHVCQueryMaxVSamples</function>. +</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>unsignedint<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. +<!-- .ds Hu for maximum Chroma/Value samples --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue</emphasis> + </term> + <listitem> + <para> +Specifies the Hue (Hu. + </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 +<function>XcmsTekHVCQueryMaxVSamples</function> +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 +<function>XcmsTekHVCQueryMinV</function>. +</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. +<!-- .ds Hu in which to find the minimum Value --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hue</emphasis> + </term> + <listitem> + <para> +Specifies the Hue (Hu. +<!-- .ds Va minimum Value --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value</emphasis> + </term> + <listitem> + <para> +Specifies the Value in which to find the (Va. +<!-- .ds Lc minimum Value and the actual Hue and Chroma --> +<!-- .ds lC minimum Value --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>color_return</emphasis> + </term> + <listitem> + <para> +Returns the (Lc at which the (lC 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 +<function>XcmsTekHVCQueryMinV</function> +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 +<function>XcmsAddColorSpace</function> +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 +<function>XcmsAddFunctionSet</function> +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 +<function>XcmsAddColorSpace</function>. +</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 +<function>XcmsAddColorSpace</function> +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 +<function>XcmsFormatOfPrefix</function> +and +<function>XcmsPrefixOfFormat</function>). +</para> +<para> +<!-- .LP --> +If the +<structname>XcmsColorSpace</structname> +structure is already accessible in the color management system, +<function>XcmsAddColorSpace</function> +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 +<function>XcmsFormatOfPrefix</function>. +</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 +<function>XcmsFormatOfPrefix</function> +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, +<function>XcmsFormatOfPrefix</function> +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 +<function>XcmsPrefixOfFormat</function>. +</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 +<function>XcmsPrefixOfFormat</function> +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 +<function>XcmsAddColorSpace</function> +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 +<function>XcmsFormatOfPrefix</function> +and +<function>XcmsPrefixOfFormat</function>). +<!-- .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 <= i < 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>unsignedint<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>unsignedint<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> + <tgroup cols='3' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <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 the section on Device Color Characterization in the +<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>. +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 +<function>XcmsAddFunctionSet</function>. +</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 +<function>XcmsAddFunctionSet</function> +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, +<function>XcmsAddFunctionSet</function> +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 +<function>XcmsFormatOfPrefix</function> +and +<function>XcmsPrefixOfFormat</function>). +</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 +<function>XcmsAddFunctionSet</function>. +</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> |