diff options
Diffstat (limited to 'libX11/specs/libX11/CH06')
| -rw-r--r-- | libX11/specs/libX11/CH06 | 4773 |
1 files changed, 0 insertions, 4773 deletions
diff --git a/libX11/specs/libX11/CH06 b/libX11/specs/libX11/CH06 deleted file mode 100644 index 44824d324..000000000 --- a/libX11/specs/libX11/CH06 +++ /dev/null @@ -1,4773 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -.\" Digital Equipment Corporation -.\" -.\" Portions Copyright \(co 1990, 1991 by -.\" Tektronix, Inc. -.\" -.\" Permission to use, copy, modify and distribute this documentation for -.\" any purpose and without fee is hereby granted, provided that the above -.\" copyright notice appears in all copies and that both that copyright notice -.\" and this permission notice appear in all copies, and that the names of -.\" Digital and Tektronix not be used in in advertising or publicity pertaining -.\" to this documentation without specific, written prior permission. -.\" Digital and Tektronix makes no representations about the suitability -.\" of this documentation for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 6\fP\s-1 - -\s+1\fBColor Management Functions\fP\s-1 -.sp 2 -.nr H1 6 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.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 RGB color space. -The RGB color space is device dependent; -rendering an RGB 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 CIE XYZ -color space. -This includes the CIE XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as -the TekHVC color space. -.LP -This chapter discusses how to: -.IP \(bu 5 -Create, copy, and destroy a colormap -.IP \(bu 5 -Specify colors by name or value -.IP \(bu 5 -Allocate, modify, and free color cells -.IP \(bu 5 -Read entries in a colormap -.IP \(bu 5 -Convert between color spaces -.IP \(bu 5 -Control aspects of color conversion -.IP \(bu 5 -Query the color gamut of a screen -.IP \(bu 5 -Add new color spaces -.LP -All functions, types, and symbols in this chapter with the prefix ``Xcms'' -are defined in -.hN X11/Xcms.h . -The remaining functions and types are defined in -.hN X11/Xlib.h . -.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 (RGB) 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 RGB 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. -.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 RGB 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 RGB value) -by a client to obtain desired colors. -The use of pixel value for an -unallocated cell results in an undefined color. -.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 -.PN XInstallColormap -and -.PN XUninstallColormap . -.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. -.LP -The -.PN DefaultColormap -macro returns the default colormap. -The -.PN DefaultVisual -macro -returns the default visual type for the specified screen. -.IN "Color map" -Possible visual types are -.PN StaticGray , -.PN GrayScale , -.PN StaticColor , -.PN PseudoColor , -.PN TrueColor , -or -.PN DirectColor -(see section 3.1). -.NH 2 -Color Structures -.XS -\*(SN Color Structures -.XE -.LP -Functions that operate only on RGB color space values use an -.PN XColor -structure, which contains: -.LP -.IN "XColor" "" "@DEF@" -.sM -.Ds 0 -.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; -.De -.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). -.IN "Color" -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 -.PN DoRed , -.PN DoGreen , -and -.PN DoBlue . -.LP -.sp -Functions that operate on all color space values use an -.PN XcmsColor -structure. -This structure contains a union of substructures, -each supporting color specification encoding for a particular color space. -Like the -.PN XColor -structure, the -.PN XcmsColor -structure contains pixel -and color specification information (the spec member in the -.PN XcmsColor -structure). -.IN "XcmsColor" "" "@DEF@" -.sM -.LP -.Ds 0 -.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 */ -.De -.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 -.PN XcmsColorFormat . -The following macros define standard formats. -.sM -.TS -lw(.5i) lw(1.6i) lw(1.4i) lw(1.5i). -T{ -#define -T} T{ -.PN XcmsUndefinedFormat -T} T{ -0x00000000 -T} -T{ -#define -T} T{ -.PN XcmsCIEXYZFormat -T} T{ -0x00000001 -T} T{ -/* CIE XYZ */ -T} -T{ -#define -T} T{ -.PN XcmsCIEuvYFormat -T} T{ -0x00000002 -T} T{ -/* CIE u'v'Y */ -T} -T{ -#define -T} T{ -.PN XcmsCIExyYFormat -T} T{ -0x00000003 -T} T{ -/* CIE xyY */ -T} -T{ -#define -T} T{ -.PN XcmsCIELabFormat -T} T{ -0x00000004 -T} T{ -/* CIE L*a*b* */ -T} -T{ -#define -T} T{ -.PN XcmsCIELuvFormat -T} T{ -0x00000005 -T} T{ -/* CIE L*u*v* */ -T} -T{ -#define -T} T{ -.PN XcmsTekHVCFormat -T} T{ -0x00000006 -T} T{ -/* TekHVC */ -T} -T{ -#define -T} T{ -.PN XcmsRGBFormat -T} T{ -0x80000000 -T} T{ -/* RGB Device */ -T} -T{ -#define -T} T{ -.PN XcmsRGBiFormat -T} T{ -0x80000001 -T} T{ -/* RGB Intensity */ -T} -.TE -.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 -.PN XcmsFormatOfPrefix -and -.PN XcmsPrefixOfFormat ). -.LP -Data types that describe the color specification encoding for the various -color spaces are defined as follows: -.sM -.IN "XcmsRGB" "" "@DEF@" -.LP -.Ds 0 -.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 */ -.De -.IN "XcmsRGBi" "" "@DEF@" -.LP -.Ds 0 -.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 */ -.De -.IN "XcmsCIEXYZ" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - XcmsFloat X; - XcmsFloat Y; /* 0.0 to 1.0 */ - XcmsFloat Z; -} XcmsCIEXYZ; /* CIE XYZ */ -.De -.IN "XcmsCIEuvY" "" "@DEF@" -.LP -.Ds 0 -.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 */ -.De -.IN "XcmsCIExyY" "" "@DEF@" -.LP -.Ds 0 -.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 */ -.De -.IN "XcmsCIELab" "" "@DEF@" -.LP -.Ds 0 -.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* */ -.De -.IN "XcmsCIELuv" "" "@DEF@" -.LP -.Ds 0 -.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* */ -.De -.IN "XcmsTekHVC" "" "@DEF@" -.LP -.Ds 0 -.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 */ -.De -.IN "XcmsPad" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { - XcmsFloat pad0; - XcmsFloat pad1; - XcmsFloat pad2; - XcmsFloat pad3; -} XcmsPad; /* four doubles */ -.De -.LP -.eM -The device-dependent formats provided allow color specification in: -.IP \(bu 5 -RGB Intensity -.Pn ( XcmsRGBi ) -.IP -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. -.IP \(bu 5 -RGB Device -.Pn ( XcmsRGB ) -.IP -Red, green, and blue values appropriate for the specified output device. -.PN XcmsRGB -values are of type unsigned short, -scaled from 0 to 65535 inclusive, -and are interchangeable with the red, green, and blue values in an -.PN XColor -structure. -.LP -It is important to note that RGB Intensity values are not gamma corrected -values. -In contrast, -RGB Device values generated as a result of converting color specifications -are always gamma corrected, and -RGB 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 \fIRGB value\fP in this manual always refers to an RGB Device value. -.NH 2 -Color Strings -.XS -\*(SN Color Strings -.XE -.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. -.LP -Color strings are used in the following functions: -.IP \(bu 5 -.PN XAllocNamedColor -.IP \(bu 5 -.PN XcmsAllocNamedColor -.IP \(bu 5 -.PN XLookupColor -.IP \(bu 5 -.PN XcmsLookupColor -.IP \(bu 5 -.PN XParseColor -.IP \(bu 5 -.PN XStoreNamedColor -.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. -.LP -A numerical color specification -consists of a color space name and a set of values in the following syntax: -.LP -.sM -.Ds 0 -\fI<color_space_name>\fP:\fI<value>/.../<value>\fP -.De -.LP -.eM -The following are examples of valid color strings. -.LP -.Ds 0 -"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" -.De -The syntax and semantics of numerical specifications are given -for each standard color space in the following sections. -.NH 3 -RGB Device String Specification -.XS -\*(SN RGB Device String Specification -.XE -.LP -An RGB Device specification is identified by -the prefix ``rgb:'' and conforms to the following syntax: -.LP -.\" Start marker code here -.Ds 0 -rgb:\fI<red>/<green>/<blue>\fP - - \fI<red>\fP, \fI<green>\fP, \fI<blue>\fP := \fIh\fP | \fIhh\fP | \fIhhh\fP | \fIhhhh\fP - \fIh\fP := single hexadecimal digits (case insignificant) -.De -.\" End marker code here -.LP -Note that \fIh\fP indicates the value scaled in 4 bits, -\fIhh\fP the value scaled in 8 bits, -\fIhhh\fP the value scaled in 12 bits, -and \fIhhhh\fP the value scaled in 16 bits, respectively. -.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. -.LP -For backward compatibility, an older syntax for RGB 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: -.LP -.\" Start marker code here -.Ds 0 -.TA 2i -.ta 2i -#RGB (4 bits each) -#RRGGBB (8 bits each) -#RRRGGGBBB (12 bits each) -#RRRRGGGGBBBB (16 bits each) -.De -.\" End marker code here -.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''. -.NH 3 -RGB Intensity String Specification -.XS -\*(SN RGB Intensity String Specification -.XE -.LP -An RGB intensity specification is identified -by the prefix ``rgbi:'' and conforms to the following syntax: -.LP -.\" Start marker code here -.Ds 0 -rgbi:\fI<red>/<green>/<blue>\fP -.De -.\" End marker code here -.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. -.NH 3 -Device-Independent String Specifications -.XS -\*(SN Device-Independent String Specifications -.XE -.LP -The standard device-independent string specifications have -the following syntax: -.LP -.\" Start marker code here -.Ds 0 -CIEXYZ:\fI<X>/<Y>/<Z>\fP -CIEuvY:\fI<u>/<v>/<Y>\fP -CIExyY:\fI<x>/<y>/<Y>\fP -CIELab:\fI<L>/<a>/<b>\fP -CIELuv:\fI<L>/<u>/<v>\fP -TekHVC:\fI<H>/<V>/<C>\fP -.De -.\" End marker code here -.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. -.NH 2 -Color Conversion Contexts and Gamut Mapping -.XS -\*(SN Color Conversion Contexts and Gamut Mapping -.XE -.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, -.IN "Device profile" -is available in a Color Conversion Context (CCC). -.IN "Color Conversion Context" -.IN "CCC" -.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: -.IN "White point" -.IP \(bu 5 -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. -.IP \(bu 5 -White adjustment occurs when the inherent white point of the screen -differs from the white point assumed by the client. -.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). -.IN "Client White Point" -.IN "Gamut compression" -.IN "Gamut handling" -.IN "White point adjustment" -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. -.LP -Associated with each colormap is an initial CCC transparently generated by -Xlib. -.IN "Color Conversion Context" "creation" -Therefore, -when you specify a colormap as an argument to an Xlib function, -you are indirectly specifying a CCC. -.IN "CCC" "of colormap" -.IN "Color Conversion Context" "of colormap" -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. -.IN "CCC" "default" -.IN "Color Conversion Context" "default" -.LP -Xcms functions in which gamut mapping can occur return -.PN Status -and have specific status values defined for them, -as follows: -.IP \(bu 5 -.PN XcmsFailure -indicates that the function failed. -.IP \(bu 5 -.PN XcmsSuccess -indicates that the function succeeded. -In addition, -if the function performed any color conversion, -the colors did not need to be compressed. -.IP \(bu 5 -.PN XcmsSuccessWithCompression -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. -.NH 2 -Creating, Copying, and Destroying Colormaps -.XS -\*(SN Creating, Copying, and Destroying Colormaps -.XE -.LP -To create a colormap for a screen, use -.PN XCreateColormap . -.IN "XCreateColormap" "" "@DEF@" -.sM -.FD 0 -Colormap XCreateColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvisual\fP\^, \fIalloc\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Visual *\fIvisual\fP\^; -.br - int \fIalloc\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi on whose screen you want to create a colormap -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIvisual\fP 1i -Specifies a visual type supported on the screen. -If the visual type is not one supported by the screen, -a -.PN BadMatch -error results. -.IP \fIalloc\fP 1i -Specifies the colormap entries to be allocated. -You can pass -.PN AllocNone -or -.PN AllocAll . -.LP -.eM -The -.PN XCreateColormap -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. -.LP -The initial values of the colormap entries are undefined for the -visual classes -.PN GrayScale , -.PN PseudoColor , -and -.PN DirectColor . -For -.PN StaticGray , -.PN StaticColor , -and -.PN TrueColor , -the entries have defined values, -but those values are specific to the visual and are not defined by X. -For -.PN StaticGray , -.PN StaticColor , -and -.PN TrueColor , -alloc must be -.PN AllocNone , -or a -.PN BadMatch -error results. -For the other visual classes, -if alloc is -.PN AllocNone , -the colormap initially has no allocated entries, -and clients can allocate them. -For information about the visual types, -see section 3.1. -.LP -If alloc is -.PN AllocAll , -the entire colormap is allocated writable. -The initial values of all allocated entries are undefined. -For -.PN GrayScale -and -.PN PseudoColor , -the effect is as if an -.PN XAllocColorCells -call returned all pixel values from zero to N \- 1, -where N is the colormap entries value in the specified visual. -For -.PN DirectColor , -the effect is as if an -.PN XAllocColorPlanes -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 -.PN XFreeColors . -.LP -.PN XCreateColormap -can generate -.PN BadAlloc , -.PN BadMatch , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To create a new colormap when the allocation out of a previously -shared colormap has failed because of resource exhaustion, use -.PN XCopyColormapAndFree . -.IN "XCopyColormapAndFree" "" "@DEF@" -.sM -.FD 0 -Colormap XCopyColormapAndFree\^(\^\fIdisplay\fP, \fIcolormap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.LP -.eM -The -.PN XCopyColormapAndFree -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 -.PN AllocAll , -the new colormap is also created with -.PN AllocAll , -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 -.PN AllocAll , -the allocations to be moved are all those pixels and planes -that have been allocated by the client using -.PN XAllocColor , -.PN XAllocNamedColor , -.PN XAllocColorCells , -or -.PN XAllocColorPlanes -and that have not been freed since they were allocated. -.LP -.PN XCopyColormapAndFree -can generate -.PN BadAlloc -and -.PN BadColor -errors. -.LP -.sp -To destroy a colormap, use -.PN XFreeColormap . -.IN "XFreeColormap" "" "@DEF@" -.sM -.FD 0 -XFreeColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Cm that you want to destroy -.IP \fIcolormap\fP 1i -Specifies the colormap \*(Cm. -.LP -.eM -The -.PN XFreeColormap -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 -.PN XUninstallColormap ). -If the specified colormap is defined as the colormap for a window (by -.PN XCreateWindow , -.PN XSetWindowColormap , -or -.PN XChangeWindowAttributes ), -.PN XFreeColormap -changes the colormap associated with the window to -.PN None -and generates a -.PN ColormapNotify -event. -X does not define the colors displayed for a window with a colormap of -.PN None . -.LP -.PN XFreeColormap -can generate a -.PN BadColor -error. -.NH 2 -Mapping Color Names to Values -.XS -\*(SN Mapping Color Names to Values -.XE -.LP -.sp -To map a color name to an RGB value, use -.PN XLookupColor . -.IN "Color" "naming" -.IN "XLookupColor" "" "@DEF@" -.sM -.FD 0 -Status XLookupColor\^(\^\fIdisplay\fP, \fIcolormap\fP, \fIcolor_name\fP, \ -\fIexact_def_return\fP\^, \fIscreen_def_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - char *\fIcolor_name\fP\^; -.br - XColor *\fIexact_def_return\fP\^, *\fIscreen_def_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor_name\fP 1i -Specifies the color name string (for example, red) whose color -definition structure you want returned. -.IP \fIexact_def_return\fP 1i -Returns the exact RGB values. -.IP \fIscreen_def_return\fP 1i -Returns the closest RGB values provided by the hardware. -.LP -.eM -The -.PN XLookupColor -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. -.PN XLookupColor -returns nonzero if the name is resolved; -otherwise, it returns zero. -.LP -.PN XLookupColor -can generate a -.PN BadColor -error. -.LP -.sp -To map a color name to the exact RGB value, use -.PN XParseColor . -.IN "Color" "naming" -.IN "XParseColor" "" "@DEF@" -.sM -.FD 0 -Status XParseColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \^\fIspec\fP\^, \fIexact_def_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - char *\fIspec\fP\^; -.br - XColor *\fIexact_def_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIspec\fP 1i -Specifies the color name string; -case is ignored. -.IP \fIexact_def_return\fP 1i -Returns the exact color value for later use and sets the -.PN DoRed , -.PN DoGreen , -and -.PN DoBlue -flags. -.LP -.eM -The -.PN XParseColor -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. -.PN XParseColor -returns nonzero if the name is resolved; -otherwise, it returns zero. -.LP -.PN XParseColor -can generate a -.PN BadColor -error. -.LP -.sp -To map a color name to a value in an arbitrary color space, use -.PN XcmsLookupColor . -.IN "Color" "naming" -.IN "XcmsLookupColor" "" "@DEF@" -.sM -.FD 0 -Status XcmsLookupColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor_string\fP\^, \fIcolor_exact_return\fP\^, \fIcolor_screen_return\fP\^, -.br - \fIresult_format\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - char *\fIcolor_string\fP\^; -.br - XcmsColor *\fIcolor_exact_return\fP\^, *\fIcolor_screen_return\fP\^; -.br - XcmsColorFormat \fIresult_format\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.ds St -.IP \fIcolor_string\fP 1i -Specifies the color string\*(St. -.IP \fIcolor_exact_return\fP 1i -Returns the color specification parsed from the color string -or parsed from the corresponding string found in a color-name database. -.IP \fIcolor_screen_return\fP 1i -Returns the color that can be reproduced on the screen. -.IP \fIresult_format\fP 1i -Specifies the color format for the returned color -specifications (color_screen_return and color_exact_return arguments). -If the format is -.PN XcmsUndefinedFormat -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 -.PN XcmsUndefinedFormat -and the color string contains a color name, -the specification is returned in the format used -to store the color in the database. -.LP -.eM -The -.PN XcmsLookupColor -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. -.PN XcmsLookupColor -returns -.PN XcmsSuccess -or -.PN XcmsSuccessWithCompression -if the name is resolved; otherwise, it returns -.PN XcmsFailure . -If -.PN XcmsSuccessWithCompression -is returned, the color specification returned in -color_screen_return is the result of gamut compression. -.NH 2 -Allocating and Freeing Color Cells -.XS -\*(SN Allocating and Freeing Color Cells -.XE -.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. -.IN "Read-only colormap cells" -A read-only cell has its RGB value set by the server. -.IN "Read/write colormap cells" -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. -.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. -.LP -.sp -To allocate a read-only color cell with an RGB value, use -.PN XAllocColor . -.IN "Allocation" "read-only colormap cells" -.IN "Read-only colormap cells" "allocating" -.IN "Color" "allocation" -.IN "XAllocColor" "" "@DEF@" -.sM -.FD 0 -Status XAllocColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIscreen_in_out\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XColor *\fIscreen_in_out\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIscreen_in_out\fP 1i -Specifies and returns the values actually used in the colormap. -.LP -.eM -The -.PN XAllocColor -function allocates a read-only colormap entry corresponding to the closest -RGB value supported by the hardware. -.PN XAllocColor -returns the pixel value of the color closest to the specified -RGB elements supported by the hardware -and returns the RGB value actually used. -The corresponding colormap cell is read-only. -In addition, -.PN XAllocColor -returns nonzero if it succeeded or zero if it failed. -.IN "Color map" -.IN "Color" "allocation" -.IN "Allocation" "colormap" -.IN "read-only colormap cells" -Multiple clients that request the same effective RGB value can be assigned -the same read-only entry, thus allowing entries to be shared. -When the last client deallocates a shared cell, it is deallocated. -.PN XAllocColor -does not use or affect the flags in the -.PN XColor -structure. -.LP -.PN XAllocColor -can generate a -.PN BadColor -error. -.EQ -delim %% -.EN -.LP -.sp -To allocate a read-only color cell with a color in arbitrary format, use -.PN XcmsAllocColor . -.IN "Allocation" "read-only colormap cells" -.IN "Read-only colormap cells" "allocating" -.IN "Color" "allocation" -.IN "XcmsAllocColor" "" "@DEF@" -.sM -.FD 0 -Status XcmsAllocColor\^(\^\fIdisplay\fP\^, \fIcolormap\fP\^, \fIcolor_in_out\fP\^, \fIresult_format\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XcmsColor *\fIcolor_in_out\fP\^; -.br - XcmsColorFormat \fIresult_format\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor_in_out\fP 1i -Specifies the color to allocate and returns the pixel and color -that is actually used in the colormap. -.IP \fIresult_format\fP 1i -Specifies the color format for the returned color specification. -.LP -.eM -The -.PN XcmsAllocColor -function is similar to -.PN XAllocColor -except the color can be specified in any format. -The -.PN XcmsAllocColor -function ultimately calls -.PN XAllocColor -to allocate a read-only color cell (colormap entry) with the specified color. -.PN XcmsAllocColor -first converts the color specified -to an RGB value and then passes this to -.PN XAllocColor . -.PN XcmsAllocColor -returns the pixel value of the color cell and the color specification -actually allocated. -This returned color specification is the result of converting the RGB value -returned by -.PN XAllocColor -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 -.PN XcmsRGBFormat . -The corresponding colormap cell is read-only. -If this routine returns -.PN XcmsFailure , -the color_in_out color specification is left unchanged. -.LP -.PN XcmsAllocColor -can generate a -.PN BadColor -error. -.LP -.sp -To allocate a read-only color cell using a color name and return the closest -color supported by the hardware in RGB format, use -.PN XAllocNamedColor . -.IN "Allocation" "read-only colormap cells" -.IN "Read-only colormap cells" "allocating" -.IN "Color" "naming" -.IN "Color" "allocation" -.IN "XAllocNamedColor" "" "@DEF@" -.sM -.FD 0 -Status XAllocNamedColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \ -\fIcolor_name\fP\^, \fIscreen_def_return\fP\^, \fIexact_def_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - char *\fIcolor_name\fP\^; -.br - XColor *\fIscreen_def_return\fP\^, *\fIexact_def_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor_name\fP 1i -Specifies the color name string (for example, red) whose color -definition structure you want returned. -.IP \fIscreen_def_return\fP 1i -Returns the closest RGB values provided by the hardware. -.IP \fIexact_def_return\fP 1i -Returns the exact RGB values. -.LP -.eM -The -.PN XAllocNamedColor -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. -.PN XAllocNamedColor -returns nonzero if a cell is allocated; -otherwise, it returns zero. -.LP -.PN XAllocNamedColor -can generate a -.PN BadColor -error. -.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 -.PN XcmsAllocNamedColor . -.IN "Allocation" "read-only colormap cells" -.IN "Read-only colormap cells" "allocating" -.IN "Color" "naming" -.IN "Color" "allocation" -.IN "XcmsAllocNamedColor" "" "@DEF@" -.sM -.FD 0 -Status XcmsAllocNamedColor\^(\^\fIdisplay\fP\^, \fIcolormap\fP\^, \fIcolor_string\fP\^, \fIcolor_screen_return\fP\^, \fIcolor_exact_return\fP\^, -.br - \fIresult_format\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - char *\fIcolor_string\fP\^; -.br - XcmsColor *\fIcolor_screen_return\fP\^; -.br - XcmsColor *\fIcolor_exact_return\fP\^; -.br - XcmsColorFormat \fIresult_format\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.ds St \ whose color definition structure is to be returned -.IP \fIcolor_string\fP 1i -Specifies the color string\*(St. -.IP \fIcolor_screen_return\fP 1i -Returns the pixel value of the color cell and color specification -that actually is stored for that cell. -.IP \fIcolor_exact_return\fP 1i -Returns the color specification parsed from the color string -or parsed from the corresponding string found in a color-name database. -.IP \fIresult_format\fP 1i -Specifies the color format for the returned color -specifications (color_screen_return and color_exact_return arguments). -If the format is -.PN XcmsUndefinedFormat -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 -.PN XcmsUndefinedFormat -and the color string contains a color name, -the specification is returned in the format used -to store the color in the database. -.LP -.eM -The -.PN XcmsAllocNamedColor -function is similar to -.PN XAllocNamedColor -except that the color returned can be in any format specified. -This function -ultimately calls -.PN XAllocColor -to allocate a read-only color cell with -the color specified by a color string. -The color string is parsed into an -.PN XcmsColor -structure (see -.PN XcmsLookupColor ), -converted -to an RGB value, and finally passed to -.PN XAllocColor . -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. -.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 RGB value -returned by -.PN XAllocColor -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 -.PN XcmsRGBFormat . -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. -.LP -.PN XcmsAllocNamedColor -can generate a -.PN BadColor -error. -.LP -.sp -To allocate read/write color cell and color plane combinations for a -.PN PseudoColor -model, use -.PN XAllocColorCells . -.IN "Read/write colormap cells" "allocating" -.IN "Allocation" "read/write colormap cells" -.IN "Color" "allocation" -.IN "XAllocColorCells" "" "@DEF@" -.sM -.FD 0 -Status XAllocColorCells\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcontig\fP\^, \ -\fIplane_masks_return\fP\^, \fInplanes\fP\^, -.br - \fIpixels_return\fP\^, \fInpixels\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - Bool \fIcontig\fP\^; -.br - unsigned long \fIplane_masks_return\fP[\^]\^; -.br - unsigned int \fInplanes\fP\^; -.br - unsigned long \fIpixels_return\fP[\^]\^; -.br - unsigned int \fInpixels\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcontig\fP 1i -Specifies a Boolean value that indicates whether the planes must be contiguous. -.IP \fIplane_mask_return\fP 1i -Returns an array of plane masks. -.\" *** JIM: NEED MORE INFO FOR THIS. *** -.IP \fInplanes\fP 1i -Specifies the number of plane masks that are to be returned in the plane masks -array. -.IP \fIpixels_return\fP 1i -Returns an array of pixel values. -.IP \fInpixels\fP 1i -Specifies the number of pixel values that are to be returned in the -pixels_return array. -.LP -.eM -.EQ -delim %% -.EN -The -.PN XAllocColorCells -function allocates read/write color cells. -The number of colors must be positive and the number of planes nonnegative, -or a -.PN BadValue -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 sup nplanes% distinct pixels can be produced. -All of these are -allocated writable by the request. -For -.PN GrayScale -or -.PN PseudoColor , -each mask has exactly one bit set to 1. -For -.PN DirectColor , -each has exactly three bits set to 1. -If contig is -.PN True -and if all masks are ORed -together, a single contiguous set of bits set to 1 will be formed for -.PN GrayScale -or -.PN PseudoColor -and three contiguous sets of bits set to 1 (one within each -pixel subfield) for -.PN DirectColor . -The RGB values of the allocated -entries are undefined. -.PN XAllocColorCells -returns nonzero if it succeeded or zero if it failed. -.LP -.PN XAllocColorCells -can generate -.PN BadColor -and -.PN BadValue -errors. -.LP -.sp -To allocate read/write color resources for a -.PN DirectColor -model, use -.PN XAllocColorPlanes . -.IN "Read/write colormap planes" "allocating" -.IN "Allocation" "read/write colormap planes" -.IN "Color" "allocation" -.IN "XAllocColorPlanes" "" "@DEF@" -.sM -.FD 0 -Status XAllocColorPlanes\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcontig\fP\^, \fIpixels_return\fP\^, \fIncolors\fP\^, \fInreds\fP\^, \fIngreens\fP\^, -.br - \fInblues\fP\^, \fIrmask_return\fP\^, \fIgmask_return\fP\^, \fIbmask_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - Bool \fIcontig\fP\^; -.br - unsigned long \fIpixels_return\fP[\^]\^; -.br - int \fIncolors\fP\^; -.br - int \fInreds\fP\^, \fIngreens\fP\^, \fInblues\fP\^; -.br - unsigned long *\fIrmask_return\fP\^, *\fIgmask_return\fP\^, *\fIbmask_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcontig\fP 1i -Specifies a Boolean value that indicates whether the planes must be contiguous. -.IP \fIpixels_return\fP 1i -Returns an array of pixel values. -.PN XAllocColorPlanes -returns the pixel values in this array. -.IP \fIncolors\fP 1i -Specifies the number of pixel values that are to be returned in the -pixels_return array. -.IP \fInreds\fP 1i -.br -.ns -.IP \fIngreens\fP 1i -.br -.ns -.IP \fInblues\fP 1i -.br -.ns -Specify the number of red, green, and blue planes. -The value you pass must be nonnegative. -.IP \fIrmask_return\fP 1i -.br -.ns -.IP \fIgmask_return\fP 1i -.br -.ns -.IP \fIbmask_return\fP 1i -Return bit masks for the red, green, and blue planes. -.LP -.eM -.EQ -delim %% -.EN -The specified ncolors must be positive; -and nreds, ngreens, and nblues must be nonnegative, -or a -.PN BadValue -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 -.PN True , -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 -.PN DirectColor , -each mask -will lie within the corresponding pixel subfield. -By ORing together -subsets of masks with each pixel value, -ncolors * %2 sup (nreds+ngreens+nblues)% distinct pixel values can be produced. -All of these are allocated by the request. -However, in the -colormap, there are only ncolors * %2 sup nreds% independent red entries, -ncolors * %2 sup ngreens% independent green entries, -and ncolors * %2 sup nblues% independent blue entries. -This is true even for -.PN PseudoColor . -When the colormap entry of a pixel -value is changed (using -.PN XStoreColors , -.PN XStoreColor , -or -.PN XStoreNamedColor ), -the pixel is decomposed according to the masks, -and the corresponding independent entries are updated. -.PN XAllocColorPlanes -returns nonzero if it succeeded or zero if it failed. -.LP -.PN XAllocColorPlanes -can generate -.PN BadColor -and -.PN BadValue -errors. -.LP -.sp -.IN "Freeing" "colors" -To free colormap cells, use -.PN XFreeColors . -.IN "XFreeColors" "" "@DEF@" -.IN "Color" "deallocation" -.sM -.FD 0 -XFreeColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIpixels\fP\^, \fInpixels\fP\^, \fIplanes\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - unsigned long \fIpixels\fP\^[\^]; -.br - int \fInpixels\fP\^; -.br - unsigned long \fIplanes\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.ds Pi that map to the cells in the specified colormap -.IP \fIpixels\fP 1i -Specifies an array of pixel values \*(Pi. -.IP \fInpixels\fP 1i -Specifies the number of pixels. -.IP \fIplanes\fP 1i -Specifies the planes you want to free. -.LP -.eM -The -.PN XFreeColors -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 -.IN XAllocColor -.IN XAllocNamedColor -.IN XAllocColorCells -.IN XAllocColorPlanes -.PN XAllocColor , -.PN XAllocNamedColor , -.PN XAllocColorCells , -and -.PN XAllocColorPlanes ). -Note that freeing an -individual pixel obtained from -.PN XAllocColorPlanes -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. -.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 -.PN BadValue -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 -.PN AllocAll -to -.PN XCreateColormap ), -a -.PN BadAccess -error results. -If more than one pixel is in error, -the one that gets reported is arbitrary. -.LP -.PN XFreeColors -can generate -.PN BadAccess , -.PN BadColor , -and -.PN BadValue -errors. -.NH 2 -Modifying and Querying Colormap Cells -.XS -\*(SN Modifying and Querying Colormap Cells -.XE -.LP -.sp -To store an RGB value in a single colormap cell, use -.PN XStoreColor . -.IN "Color" "storing" -.IN "XStoreColor" "" "@DEF@" -.sM -.FD 0 -XStoreColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XColor *\fIcolor\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor\fP 1i -Specifies the pixel and RGB values. -.LP -.eM -The -.PN XStoreColor -function changes the colormap entry of the pixel value specified in the -pixel member of the -.PN XColor -structure. -You specified this value in the -pixel member of the -.PN XColor -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 -.PN BadValue -error results. -.PN XStoreColor -also changes the red, green, and/or blue color components. -You specify which color components are to be changed by setting -.PN DoRed , -.PN DoGreen , -and/or -.PN DoBlue -in the flags member of the -.PN XColor -structure. -If the colormap is an installed map for its screen, -the changes are visible immediately. -.LP -.PN XStoreColor -can generate -.PN BadAccess , -.PN BadColor , -and -.PN BadValue -errors. -.LP -.sp -To store multiple RGB values in multiple colormap cells, use -.PN XStoreColors . -.IN "Color" "storing" -.IN "XStoreColors" "" "@DEF@" -.sM -.FD 0 -XStoreColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^, \fIncolors\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XColor \fIcolor\fP\^[\^]\^; -.br - int \fIncolors\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor\fP 1i -Specifies an array of color definition structures to be stored. -.IP \fIncolors\fP 1i -.\"Specifies the number of color definition structures. -Specifies the number of -.PN XColor -structures in the color definition array. -.LP -.eM -The -.PN XStoreColors -function changes the colormap entries of the pixel values -specified in the pixel members of the -.PN XColor -structures. -You specify which color components are to be changed by setting -.PN DoRed , -.PN DoGreen , -and/or -.PN DoBlue -in the flags member of the -.PN XColor -structures. -If the colormap is an installed map for its screen, the -changes are visible immediately. -.PN XStoreColors -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 -.PN BadValue -error results. -If a specified pixel either is unallocated or is allocated read-only, a -.PN BadAccess -error results. -If more than one pixel is in error, -the one that gets reported is arbitrary. -.LP -.PN XStoreColors -can generate -.PN BadAccess , -.PN BadColor , -and -.PN BadValue -errors. -.LP -.sp -To store a color of arbitrary format in a single colormap cell, use -.PN XcmsStoreColor . -.IN "Color" "storing" -.IN "XcmsStoreColor" "" "@DEF@" -.sM -.FD 0 -Status XcmsStoreColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XcmsColor *\fIcolor\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor\fP 1i -Specifies the color cell and the color to store. -Values specified in this -.PN XcmsColor -structure remain unchanged on return. -.LP -.eM -The -.PN XcmsStoreColor -function converts the color specified in the -.PN XcmsColor -structure into RGB values. -It then uses this RGB specification in an -.PN XColor -structure, whose three flags -.Pn ( DoRed , -.PN DoGreen , -and -.PN DoBlue ) -are set, in a call to -.PN XStoreColor -to change the color cell specified by the pixel member of the -.PN XcmsColor -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 -.PN BadValue -error results. -If the color cell is unallocated or is allocated read-only, a -.PN BadAccess -error results. -If the colormap is an installed map for its screen, -the changes are visible immediately. -.LP -Note that -.PN XStoreColor -has no return value; therefore, an -.PN XcmsSuccess -return value from this function indicates that the conversion -to RGB succeeded and the call to -.PN XStoreColor -was made. -To obtain the actual color stored, use -.PN XcmsQueryColor . -Because of the screen's hardware limitations or gamut compression, -the color stored in the colormap may not be identical -to the color specified. -.LP -.PN XcmsStoreColor -can generate -.PN BadAccess , -.PN BadColor , -and -.PN BadValue -errors. -.LP -.sp -To store multiple colors of arbitrary format in multiple colormap cells, use -.PN XcmsStoreColors . -.IN "Color" "storing" -.IN "XcmsStoreColors" "" "@DEF@" -.sM -.FD 0 -Status XcmsStoreColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolors\fP\^, \fIncolors\fP\^, \fIcompression_flags_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XcmsColor \fIcolors\fP\^[\^]\^; -.br - int \fIncolors\fP\^; -.br - Bool \fIcompression_flags_return\fP\^[\^]\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolors\fP 1i -Specifies the color specification array of -.PN XcmsColor -structures, each specifying a color cell and the color to store in that -cell. -Values specified in the array remain unchanged upon return. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.IP \fIcompression_flags_return\fP 1i -Returns an array of Boolean values indicating compression status. -If a non-NULL pointer is supplied, -each element of the array is set to -.PN True -if the corresponding color was compressed and -.PN False -otherwise. -Pass NULL if the compression status is not useful. -.LP -.eM -The -.PN XcmsStoreColors -function converts the colors specified in the array of -.PN XcmsColor -structures into RGB values and then uses these RGB specifications in -.PN XColor -structures, whose three flags -.Pn ( DoRed , -.PN DoGreen , -and -.PN DoBlue ) -are set, in a call to -.PN XStoreColors -to change the color cells specified by the pixel member of the corresponding -.PN XcmsColor -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 -.PN BadValue -error results. -If a color cell is unallocated or is allocated read-only, a -.PN BadAccess -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. -.LP -Note that -.PN XStoreColors -has no return value; therefore, an -.PN XcmsSuccess -return value from this function indicates that conversions -to RGB succeeded and the call to -.PN XStoreColors -was made. -To obtain the actual colors stored, use -.PN XcmsQueryColors . -Because of the screen's hardware limitations or gamut compression, -the colors stored in the colormap may not be identical -to the colors specified. -.LP -.PN XcmsStoreColors -can generate -.PN BadAccess , -.PN BadColor , -and -.PN BadValue -errors. -.LP -.sp -To store a color specified by name in a single colormap cell, use -.PN XStoreNamedColor . -.IN "Color" "storing" -.IN "Color" "naming" -.IN "XStoreNamedColor" "" "@DEF@" -.sM -.FD 0 -XStoreNamedColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^, \fIpixel\fP\^, \fIflags\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - char *\^\fIcolor\fP\^; -.br - unsigned long \fIpixel\fP\^; -.br - int \fIflags\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor\fP 1i -Specifies the color name string (for example, red). -.IP \fIpixel\fP 1i -Specifies the entry in the colormap. -.IP \fIflags\fP 1i -Specifies which red, green, and blue components are set. -.LP -.eM -The -.PN XStoreNamedColor -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 -.PN DoRed , -.PN DoGreen , -and -.PN DoBlue . -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 -.PN BadValue -error results. -If the specified pixel either is unallocated or is allocated read-only, a -.PN BadAccess -error results. -.LP -.PN XStoreNamedColor -can generate -.PN BadAccess , -.PN BadColor , -.PN BadName , -and -.PN BadValue -errors. -.LP -The -.PN XQueryColor -and -.PN XQueryColors -functions take pixel values in the pixel member of -.PN XColor -structures and store in the structures the RGB 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 -.PN XColor -structure to all three colors. -If a pixel is not a valid index into the specified colormap, a -.PN BadValue -error results. -If more than one pixel is in error, -the one that gets reported is arbitrary. -.LP -.sp -To query the RGB value of a single colormap cell, use -.PN XQueryColor . -.IN "Color" "querying" -.IN "XQueryColor" "" "@DEF@" -.sM -.FD 0 -XQueryColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIdef_in_out\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XColor *\fIdef_in_out\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIdef_in_out\fP 1i -Specifies and returns the RGB values for the pixel specified in the structure. -.LP -.eM -The -.PN XQueryColor -function returns the current RGB value for the pixel in the -.PN XColor -structure and sets the -.PN DoRed , -.PN DoGreen , -and -.PN DoBlue -flags. -.LP -.PN XQueryColor -can generate -.PN BadColor -and -.PN BadValue -errors. -.LP -.sp -To query the RGB values of multiple colormap cells, use -.PN XQueryColors . -.IN "Color" "querying" -.IN "XQueryColors" "" "@DEF@" -.sM -.FD 0 -XQueryColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIdefs_in_out\fP\^, \fIncolors\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XColor \fIdefs_in_out\fP[\^]\^; -.br - int \fIncolors\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIdefs_in_out\fP 1i -Specifies and returns an array of color definition structures for the pixel -specified in the structure. -.IP \fIncolors\fP 1i -.\"Specifies the number of color definition structures. -Specifies the number of -.PN XColor -structures in the color definition array. -.LP -.eM -The -.PN XQueryColors -function returns the RGB value for each pixel in each -.PN XColor -structure and sets the -.PN DoRed , -.PN DoGreen , -and -.PN DoBlue -flags in each structure. - -.LP -.PN XQueryColors -can generate -.PN BadColor -and -.PN BadValue -errors. -.sp -.LP -To query the color of a single colormap cell in an arbitrary format, use -.PN XcmsQueryColor . -.IN "Color" "querying" -.IN "XcmsQueryColor" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor_in_out\fP\^, \fIresult_format\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XcmsColor *\fIcolor_in_out\fP\^; -.br - XcmsColorFormat \fIresult_format\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolor_in_out\fP 1i -Specifies the pixel member that indicates the color cell to query. -The color specification stored for the color cell is returned in this -.PN XcmsColor -structure. -.IP \fIresult_format\fP 1i -Specifies the color format for the returned color specification. -.LP -.eM -The -.PN XcmsQueryColor -function obtains the RGB value -for the pixel value in the pixel member of the specified -.PN XcmsColor -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 -.PN BadValue -error results. -.LP -.PN XcmsQueryColor -can generate -.PN BadColor -and -.PN BadValue -errors. -.sp -.LP -To query the color of multiple colormap cells in an arbitrary format, use -.PN XcmsQueryColors . -.IN "Color" "querying" -.IN "XcmsQueryColors" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIresult_format\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XcmsColor \fIcolors_in_out\fP\^[\^]\^; -.br - unsigned int \fIncolors\fP\^; -.br - XcmsColorFormat \fIresult_format\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIcolors_in_out\fP 1i -Specifies an array of -.PN XcmsColor -structures, each pixel member indicating the color cell to query. -The color specifications for the color cells are returned in these structures. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.IP \fIresult_format\fP 1i -Specifies the color format for the returned color specification. -.LP -.eM -The -.PN XcmsQueryColors -function obtains the RGB values -for pixel values in the pixel members of -.PN XcmsColor -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 -.PN BadValue -error results. -If more than one pixel is in error, -the one that gets reported is arbitrary. -.LP -.PN XcmsQueryColors -can generate -.PN BadColor -and -.PN BadValue -errors. -.NH 2 -Color Conversion Context Functions -.XS -\*(SN Color Conversion Context Functions -.XE -.LP -This section describes functions to create, modify, -and query Color Conversion Contexts (CCCs). -.LP -Associated with each colormap is an initial CCC transparently generated by -Xlib. -.IN "Color Conversion Context" "creation" -Therefore, when you specify a colormap as an argument to a function, -you are indirectly specifying a CCC. -.IN "CCC" "of colormap" -.IN "Color Conversion Context" "of colormap" -The CCC attributes that can be modified by the X client are: -.IP \(bu 5 -Client White Point -.IP \(bu 5 -Gamut compression procedure and client data -.IP \(bu 5 -White point adjustment procedure and client data -.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. -.IN "CCC" "default" -.IN "Color Conversion Context" "default" -There is a default CCC associated with each screen. -.NH 3 -Getting and Setting the Color Conversion Context of a Colormap -.XS -\*(SN Getting and Setting the Color Conversion Context of a Colormap -.XE -.LP -.sp -To obtain the CCC associated with a colormap, use -.PN XcmsCCCOfColormap . -.IN "XcmsCCCOfColormap" "" "@DEF@" -.IN "Colormap" "CCC of" -.IN "CCC" "of colormap" -.IN "Color Conversion Context" "of colormap" -.sM -.FD 0 -XcmsCCC XcmsCCCOfColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.LP -.eM -The -.PN XcmsCCCOfColormap -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 -.PN XcmsSetCCCOfColormap , -this CCC is used when the specified colormap is used as an argument -to color functions. -.sp -.LP -To change the CCC associated with a colormap, use -.PN XcmsSetCCCOfColormap . -.IN "XcmsSetCCCOfColormap" "" "@DEF@" -.IN "Colormap" "CCC of" -.IN "CCC" "of colormap" -.IN "Color Conversion Context" "of colormap" -.sM -.FD 0 -XcmsCCC XcmsSetCCCOfColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIccc\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -The -.PN XcmsSetCCCOfColormap -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 -.PN XcmsFreeCCC . -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. -.NH 3 -Obtaining the Default Color Conversion Context -.XS -\*(SN Obtaining the Default Color Conversion Context -.XE -.LP -You can change the default CCC attributes for subsequently created CCCs -by changing the CCC attributes of the default CCC. -.IN "CCC" "default" -.IN "Color Conversion Context" "default" -A default CCC is associated with each screen. -.sp -.LP -To obtain the default CCC for a screen, use -.PN XcmsDefaultCCC . -.IN "XcmsDefaultCCC" "" "@DEF@" -.IN "Color Conversion Context" "default" -.IN "CCC" "default" -.sM -.FD 0 -XcmsCCC XcmsDefaultCCC\^(\^\fIdisplay\fP, \fIscreen_number\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.LP -.eM -The -.PN XcmsDefaultCCC -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. -.NH 3 -Color Conversion Context Macros -.XS -\*(SN Color Conversion Context Macros -.XE -.LP -Applications should not directly modify any part of the -.PN XcmsCCC . -The following lists the C language macros, their corresponding function -equivalents for other language bindings, and what data they both -can return. -.sp -.LP -.IN "DisplayOfCCC" "" "@DEF@" -.IN "XcmsDisplayOfCCC" "" "@DEF@" -.sM -.FD 0 -DisplayOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.sp -Display *XcmsDisplayOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -Both return the display associated with the specified CCC. -.LP -.sp -.IN "VisualOfCCC" "" "@DEF@" -.IN "XcmsVisualOfCCC" "" "@DEF@" -.sM -.FD 0 -VisualOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.sp -Visual *XcmsVisualOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -Both return the visual associated with the specified CCC. -.sp -.LP -.IN "ScreenNumberOfCCC" "" "@DEF@" -.IN "XcmsScreenNumberOfCCC" "" "@DEF@" -.sM -.FD 0 -ScreenNumberOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.sp -int XcmsScreenNumberOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -Both return the number of the screen associated with the specified CCC. -.sp -.LP -.IN "ScreenWhitePointOfCCC" "" "@DEF@" -.IN "XcmsScreenWhitePointOfCCC" "" "@DEF@" -.sM -.FD 0 -ScreenWhitePointOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.sp -XcmsColor *XcmsScreenWhitePointOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -Both return the white point of the screen associated with the specified CCC. -.sp -.LP -.IN "ClientWhitePointOfCCC" "" "@DEF@" -.IN "XcmsClientWhitePointOfCCC" "" "@DEF@" -.sM -.FD 0 -ClientWhitePointOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.sp -XcmsColor *XcmsClientWhitePointOfCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -Both return the Client White Point of the specified CCC. -.NH 3 -Modifying Attributes of a Color Conversion Context -.XS -\*(SN Modifying Attributes of a Color Conversion Context -.XE -.LP -To set the Client White Point in the CCC, use -.PN XcmsSetWhitePoint . -.IN "XcmsSetWhitePoint" "" "@DEF@" -.IN "Client White Point" "of Color Conversion Context" -.sM -.FD 0 -Status XcmsSetWhitePoint\^(\^\fIccc\fP\^, \fIcolor\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColor *\fIcolor\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.ds Co new Client White Point -.IP \fIcolor\fP 1i -Specifies the \*(Co. -.LP -.eM -The -.PN XcmsSetWhitePoint -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 -.PN XcmsCIEXYZFormat , -.PN XcmsCIEuvYFormat , -.PN XcmsCIExyYFormat , -or -.PN XcmsUndefinedFormat . -If the color argument is NULL, this function sets the format component of the -Client White Point specification to -.PN XcmsUndefinedFormat , -indicating that the Client White Point is assumed to be the same as the -Screen White Point. -.LP -This function returns nonzero status -if the format for the new white point is valid; -otherwise, it returns zero. - -.sp -.LP -To set the gamut compression procedure and corresponding client data -in a specified CCC, use -.PN XcmsSetCompressionProc . -.IN "XcmsSetCompressionProc" "" "@DEF@" -.IN "Gamut compression" "setting in Color Conversion Context" -.IN "Gamut compression" "procedure" -.IN "Gamut compression" "client data" -.sM -.FD 0 -XcmsCompressionProc XcmsSetCompressionProc\^(\^\fIccc\fP\^, \fIcompression_proc\fP\^, \fIclient_data\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsCompressionProc \fIcompression_proc\fP\^; -.br - XPointer \fIclient_data\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.IP \fIcompression_proc\fP 1i -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 -.PN XcmsFailure . -.ds Cd the gamut compression procedure -.IP \fIclient_data\fP 1i -Specifies client data for \*(Cd or NULL. -.LP -.eM -The -.PN XcmsSetCompressionProc -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 -.LP -To set the white point adjustment procedure and corresponding client data -in a specified CCC, use -.PN XcmsSetWhiteAdjustProc . -.IN "XcmsSetWhiteAdjustProc" "" "@DEF@" -.IN "White point adjustment" "setting in Color Conversion Context" -.IN "White point adjustment" "procedure" -.IN "White point adjustment" "client data" -.FD 0 -.sM -XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc\^(\^\fIccc\fP\^, \fIwhite_adjust_proc\fP\^, \fIclient_data\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsWhiteAdjustProc \fIwhite_adjust_proc\fP\^; -.br - XPointer \fIclient_data\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.IP \fIwhite_adjust_proc\fP 1i -Specifies the white point adjustment procedure. -.ds Cd the white point adjustment procedure -.IP \fIclient_data\fP 1i -Specifies client data for \*(Cd or NULL. -.LP -.eM -The -.PN XcmsSetWhiteAdjustProc -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. -.NH 3 -Creating and Freeing a Color Conversion Context -.XS -\*(SN Creating and Freeing a Color Conversion Context -.XE -.LP -You can explicitly create a CCC within your application by calling -.PN XcmsCreateCCC . -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 -.PN XcmsFreeCCC . -.sp -.LP -To create a CCC, use -.PN XcmsCreateCCC . -.IN "XcmsCreateCCC" "" "@DEF@" -.IN "Color Conversion Context" "creation" -.IN "CCC" "creation" -.sM -.FD 0 -XcmsCCC XcmsCreateCCC\^(\^\fIdisplay\fP, \fIscreen_number\fP\^, \fIvisual\fP\^, \fIclient_white_point\fP\^, \fIcompression_proc\fP\^, -.br - \fIcompression_client_data\fP\^, \fIwhite_adjust_proc\fP\^, \fIwhite_adjust_client_data\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.br - Visual *\fIvisual\fP\^; -.br - XcmsColor *\fIclient_white_point\fP\^; -.br - XcmsCompressionProc \fIcompression_proc\fP\^; -.br - XPointer \fIcompression_client_data\fP\^; -.br - XcmsWhiteAdjustProc \fIwhite_adjust_proc\fP\^; -.br - XPointer \fIwhite_adjust_client_data\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.IP \fIvisual\fP 1i -Specifies the visual type. -.IP \fIclient_white_point\fP 1i -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. -.IP \fIcompression_proc\fP 1i -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 -.PN XcmsFailure . -.IP \fIcompression_client_data\fP 1i -Specifies client data for use by the gamut compression procedure or NULL. -.IP \fIwhite_adjust_proc\fP 1i -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. -.IP \fIwhite_adjust_client_data\fP 1i -Specifies client data for use with the white point adjustment procedure or NULL. -.LP -.eM -The -.PN XcmsCreateCCC -function creates a CCC for the specified display, screen, and visual. -.LP -.sp -To free a CCC, use -.PN XcmsFreeCCC . -.IN "XcmsFreeCCC" "" "@DEF@" -.IN "Color Conversion Context" "freeing" -.IN "CCC" "freeing" -.sM -.FD 0 -void XcmsFreeCCC\^(\^\fIccc\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.LP -.eM -The -.PN XcmsFreeCCC -function frees the memory used for the specified CCC. -Note that default CCCs and those currently associated with colormaps -are ignored. -.NH 2 -Converting between Color Spaces -.XS -\*(SN Converting between Color Spaces -.XE -.LP -.sp -To convert an array of color specifications in arbitrary color formats -to a single destination format, use -.PN XcmsConvertColors . -.IN "Color conversion" -.IN "Color" "conversion" -.IN "XcmsConvertColors" "" "@DEF@" -.sM -.FD 0 -Status XcmsConvertColors\^(\^\fIccc\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fItarget_format\fP\^, \fIcompression_flags_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColor \fIcolors_in_out\fP\^[\^]\^; -.br - unsigned int \fIncolors\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - Bool \fIcompression_flags_return\fP\^[\^]\^; -.FN -.IP \fIccc\fP 1i -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. -.IP \fIcolors_in_out\fP 1i -Specifies an array of color specifications. -Pixel members are ignored and remain unchanged upon return. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.IP \fIcompression_flags_return\fP 1i -Returns an array of Boolean values indicating compression status. -If a non-NULL pointer is supplied, -each element of the array is set to -.PN True -if the corresponding color was compressed and -.PN False -otherwise. -Pass NULL if the compression status is not useful. -.LP -.eM -The -.PN XcmsConvertColors -function converts the color specifications in the specified array of -.PN XcmsColor -structures from their current format to a single target format, -using the specified CCC. -When the return value is -.PN XcmsFailure , -the contents of the color specification array are left unchanged. -.LP -The array may contain a mixture of color specification formats -(for example, 3 CIE XYZ, 2 CIE 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, -.PN XcmsRGBiFormat , -.PN XcmsRGBFormat ), -all specifications are converted to CIE XYZ format and then to the target -device-dependent format. -.NH 2 -Callback Functions -.XS -\*(SN Callback Functions -.XE -.LP -This section describes the gamut compression and white point -adjustment callbacks. -.LP -The gamut compression procedure specified in the CCC -is called when an attempt to convert a color specification from -.PN XcmsCIEXYZ -to a device-dependent format (typically -.PN XcmsRGBi ) -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. -.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. -.NH 3 -Prototype Gamut Compression Procedure -.XS -\*(SN Prototype Gamut Compression Procedure -.XE -.LP -The gamut compression callback interface must adhere to the -following: -.IN "XcmsCompressionProc" "" "@DEF@" -.sM -.FD 0 -typedef Status (*\^XcmsCompressionProc\^)\^(\^\fIccc\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIindex\fP\^, \fIcompression_flags_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColor \fIcolors_in_out[]\fP\^; -.br - unsigned int \fIncolors\fP\^; -.br - unsigned int \fIindex\fP\^; -.br - Bool \fIcompression_flags_return[]\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.IP \fIcolors_in_out\fP 1i -Specifies an array of color specifications. -Pixel members should be ignored and must remain unchanged upon return. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.IP \fIindex\fP 1i -Specifies the index into the array of -.PN XcmsColor -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. -.IP \fIcompression_flags_return\fP 1i -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 -.PN True -should be stored at the corresponding index in this array; -otherwise, the array should not be modified. -.LP -.eM -When implementing a gamut compression procedure, consider the following -rules and assumptions: -.IP \(bu 5 -The gamut compression procedure can attempt to compress one or multiple -specifications at a time. -.IP \(bu 5 -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 -.PN XcmsRGBi ). -If any modifications are made to these color specifications, -they must be in their initial device-dependent format upon return. -.IP \(bu 5 -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 -.PN XcmsCIEXYZ . -Upon return, this color specification must be in -.PN XcmsCIEXYZ . -.IP \(bu 5 -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 -.PN XcmsCIEXYZ . -If any modifications are made to these color specifications, -they must be in -.PN XcmsCIEXYZ -upon return. -.IP \(bu 5 -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. -.IP \(bu 5 -If the gamut compression procedure uses a device-independent color space not -initially accessible for use in the color management system, use -.PN XcmsAddColorSpace -to ensure that it is added. -.NH 3 -Supplied Gamut Compression Procedures -.XS -\*(SN Supplied Gamut Compression Procedures -.XE -.LP -The following equations are useful in describing gamut compression -functions: -.EQ -delim %% -.EN -.LP -.Ds 0 -%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 ]% -.De -.LP -The gamut compression callback procedures provided by Xlib are as follows: -.IP \(bu 5 -.PN XcmsCIELabClipL -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by reducing or increasing CIE metric lightness (L*) -in the CIE 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 CIE L*a*b* coordinates of maximum -Psychometric Chroma. -See -.PN XcmsCIELabQueryMaxC . -No client data is necessary. -.IP \(bu 5 -.PN XcmsCIELabClipab -.IP -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. -.IP \(bu 5 -.PN XcmsCIELabClipLab -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by replacing it with CIE 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. -.IP \(bu 5 -.PN XcmsCIELuvClipL -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by reducing or increasing CIE metric lightness (L*) -in the CIE 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 CIE L*u*v* coordinates of maximum -Psychometric Chroma. -See -.PN XcmsCIELuvQueryMaxC . -No client data is necessary. -.IP \(bu 5 -.PN XcmsCIELuvClipuv -.IP -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. -.IP \(bu 5 -.PN XcmsCIELuvClipLuv -.IP -This brings the encountered out-of-gamut color specification into the -screen's color gamut by replacing it with CIE 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. -.IP \(bu 5 -.PN XcmsTekHVCClipV -.IP -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. -.IP \(bu 5 -.PN XcmsTekHVCClipC -.IP -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. -.IP \(bu 5 -.PN XcmsTekHVCClipVC -.IP -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. -.NH 3 -Prototype White Point Adjustment Procedure -.XS -\*(SN Prototype White Point Adjustment Procedure -.XE -.LP -The white point adjustment procedure interface must adhere to the following: -.IN "XcmsWhiteAdjustProc" "" "@DEF@" -.sM -.FD 0 -typedef Status (*\^XcmsWhiteAdjustProc\^)\^(\^\fIccc\fP\^, \fIinitial_white_point\fP\^, \fItarget_white_point\fP\^, \fItarget_format\fP\^, -.br - \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIcompression_flags_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColor *\fIinitial_white_point\fP\^; -.br - XcmsColor *\fItarget_white_point\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - XcmsColor \fIcolors_in_out[]\fP\^; -.br - unsigned int \fIncolors\fP\^; -.br - Bool \fIcompression_flags_return[]\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.IP \fIinitial_white_point\fP 1i -Specifies the initial white point. -.IP \fItarget_white_point\fP 1i -Specifies the target white point. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.IP \fIcolors_in_out\fP 1i -Specifies an array of color specifications. -Pixel members should be ignored and must remain unchanged upon return. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.IP \fIcompression_flags_return\fP 1i -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 -.PN True -should be stored at the corresponding index in this array; -otherwise, the array should not be modified. -.LP -.eM -.NH 3 -Supplied White Point Adjustment Procedures -.XS -\*(SN Supplied White Point Adjustment Procedures -.XE -.LP -White point adjustment procedures provided by Xlib are as follows: -.IP \(bu 5 -.PN XcmsCIELabWhiteShiftColors -.IP -This uses the CIE 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 -.PN XcmsCIELab -using the source white point and then converts to the target specification -format using the destination's white point. -No client data is necessary. -.IP \(bu 5 -.PN XcmsCIELuvWhiteShiftColors -.IP -This uses the CIE 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 -.PN XcmsCIELuv -using the source white point and then converts to the target specification -format using the destination's white point. -No client data is necessary. -.IP \(bu 5 -.PN XcmsTekHVCWhiteShiftColors -.IP -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 -.PN XcmsTekHVC -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. -.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, CIE L*u*v*, CIE 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 CIE color spaces that are assumed to be white-point-independent -are CIE u'v'Y, CIE XYZ, and CIE 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 -.PN XcmsAddColorSpace -to ensure that it is added. -.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 -.PN XcmsAllocColor -function will use the white point adjustment -procedure twice: -.IP \(bu 5 -Once to convert to -.PN XcmsRGB -.IP \(bu 5 -A second time to convert from -.PN XcmsRGB -.LP -For example, assume the specification is in -.PN XcmsCIEuvY -and the adjustment procedure is -.PN XcmsCIELuvWhiteShiftColors . -During conversion to -.PN XcmsRGB , -the call to -.PN XcmsAllocColor -results in the following series of color specification conversions: -.\" Do these need to be font coded? -.IP \(bu 5 -From -.PN XcmsCIEuvY -to -.PN XcmsCIELuv -using the Client White Point -.IP \(bu 5 -From -.PN XcmsCIELuv -to -.PN XcmsCIEuvY -using the Screen White Point -.IP \(bu 5 -From -.PN XcmsCIEuvY -to -.PN XcmsCIEXYZ -(CIE u'v'Y and XYZ are white-point-independent color spaces) -.IP \(bu 5 -From -.PN XcmsCIEXYZ -to -.PN XcmsRGBi -.IP \(bu 5 -From -.PN XcmsRGBi -to -.PN XcmsRGB -.LP -The resulting RGB specification is passed to -.PN XAllocColor , -and the RGB -specification returned by -.PN XAllocColor -is converted back to -.PN XcmsCIEuvY -by reversing the color conversion sequence. -.NH 2 -Gamut Querying Functions -.XS -\*(SN Gamut Querying Functions -.XE -.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 CIE L*a*b*, CIE L*u*v*, -and TekHVC color spaces. -.IN "Gamut querying" -Functions are also provided that allow you to query -the color specification of: -.IP \(bu 5 -White (full-intensity red, green, and blue) -.IP \(bu 5 -Red (full-intensity red while green and blue are zero) -.IP \(bu 5 -Green (full-intensity green while red and blue are zero) -.IP \(bu 5 -Blue (full-intensity blue while red and green are zero) -.IP \(bu 5 -Black (zero-intensity red, green, and blue) -.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. -.IN "Screen White Point" -This is a reasonable assumption, -because the client is trying to query the screen's color gamut. -.LP -The following naming convention is used for the Max and Min functions: -.LP -.Ds 0 -Xcms\fI<color_space>\fPQueryMax\fI<dimensions>\fP - -Xcms\fI<color_space>\fPQueryMin\fI<dimensions>\fP -.De -.LP -The <dimensions> consists of a letter or letters -that identify the dimensions of the color space -that are not fixed. -For example, -.PN XcmsTekHVCQueryMaxC -is given a fixed Hue and Value for which maximum Chroma is found. -.NH 3 -Red, Green, and Blue Queries -.XS -\*(SN Red, Green, and Blue Queries -.XE -.LP -To obtain the color specification for black -(zero-intensity red, green, and blue), use -.PN XcmsQueryBlack . -.IN "XcmsQueryBlack" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryBlack\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.ds Cs zero-intensity red, green, and blue -.IP \fIcolor_return\fP 1i -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. -.LP -.eM -The -.PN XcmsQueryBlack -function returns the color specification in the specified target format -for zero-intensity red, green, and blue. -.sp -.LP -To obtain the color specification for blue -(full-intensity blue while red and green are zero), use -.PN XcmsQueryBlue . -.IN "XcmsQueryBlue" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryBlue\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.ds Cs full-intensity blue while red and green are zero -.IP \fIcolor_return\fP 1i -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. -.LP -.eM -The -.PN XcmsQueryBlue -function returns the color specification in the specified target format -for full-intensity blue while red and green are zero. -.sp -.LP -To obtain the color specification for green -(full-intensity green while red and blue are zero), use -.PN XcmsQueryGreen . -.IN "XcmsQueryGreen" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryGreen\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.ds Cs full-intensity green while red and blue are zero -.IP \fIcolor_return\fP 1i -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. -.LP -.eM -The -.PN XcmsQueryGreen -function returns the color specification in the specified target format -for full-intensity green while red and blue are zero. -.sp -.LP -To obtain the color specification for red -(full-intensity red while green and blue are zero), use -.PN XcmsQueryRed . -.IN "XcmsQueryRed" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryRed\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.ds Cs full-intensity red while green and blue are zero -.IP \fIcolor_return\fP 1i -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. -.LP -.eM -The -.PN XcmsQueryRed -function returns the color specification in the specified target format -for full-intensity red while green and blue are zero. -.LP -.sp -To obtain the color specification for white -(full-intensity red, green, and blue), use -.PN XcmsQueryWhite . -.IN "XcmsQueryWhite" "" "@DEF@" -.sM -.FD 0 -Status XcmsQueryWhite\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColorFormat \fItarget_format\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.IP \fItarget_format\fP 1i -Specifies the target color specification format. -.ds Cs full-intensity red, green, and blue -.IP \fIcolor_return\fP 1i -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. -.LP -.eM -The -.PN XcmsQueryWhite -function returns the color specification in the specified target format -for full-intensity red, green, and blue. -.NH 3 -CIELab Queries -.XS -\*(SN CIELab Queries -.XE -.LP -The following equations are useful in describing the CIELab query functions: -.EQ -delim %% -.EN -.LP -.IN "Psychometric Hue Angle" -.IN "CIE metric lightness" -.IN "Psychometric Chroma" -.IN "Psychometric Chroma" "maximum" -.Ds 0 -%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 ]% -.De -.sp -To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma -for a given Psychometric Hue Angle and CIE metric lightness (L*), use -.PN XcmsCIELabQueryMaxC . -.IN "XcmsCIELabQueryMaxC" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELabQueryMaxC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIL_star\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsFloat \fIL_star\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha maximum chroma -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Ls maximum chroma -.IP \fIL_star\fP 1i -Specifies the lightness (L*) at which to find \*(Ls. -.ds Lc maximum chroma -.ds lC hue angle and lightness -.IP \fIcolor_return\fP 1i -Returns the CIE 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. -.LP -.eM -The -.PN XcmsCIELabQueryMaxC -function, given a hue angle and lightness, -finds the point of maximum chroma displayable by the screen. -It returns this point in CIE L*a*b* coordinates. -.LP -.sp -To obtain the CIE L*a*b* coordinates of maximum CIE metric lightness (L*) -for a given Psychometric Hue Angle and Psychometric Chroma, use -.PN XcmsCIELabQueryMaxL . -.IN "Psychometric Hue Angle" -.IN "CIE metric lightness" -.IN "CIE metric lightness" "maximum" -.IN "XcmsCIELabQueryMaxL" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELabQueryMaxL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsFloat \fIchroma\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha maximum lightness -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Ch maximum lightness -.IP \fIchroma\fP 1i -Specifies the chroma at which to find \*(Ch. -.ds Lc maximum lightness -.ds lC hue angle and chroma -.IP \fIcolor_return\fP 1i -Returns the CIE 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. -.LP -.eM -The -.PN XcmsCIELabQueryMaxL -function, given a hue angle and chroma, -finds the point in CIE L*a*b* color space of maximum -lightness (L*) displayable by the screen. -It returns this point in CIE L*a*b* coordinates. -An -.PN XcmsFailure -return value usually indicates that the given chroma -is beyond maximum for the given hue angle. -.sp -.LP -To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma -for a given Psychometric Hue Angle, use -.PN XcmsCIELabQueryMaxLC . -.IN "Psychometric Hue Angle" -.IN "Psychometric Chroma" -.IN "CIE metric lightness" -.IN "Psychometric Chroma" "maximum" -.IN "CIE metric lightness" "maximum" -.IN "XcmsCIELabQueryMaxLC" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELabQueryMaxLC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha maximum chroma -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Lc maximum chroma -.ds lC hue angle -.IP \fIcolor_return\fP 1i -Returns the CIE 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. -.LP -.eM -The -.PN XcmsCIELabQueryMaxLC -function, given a hue angle, -finds the point of maximum chroma displayable by the screen. -It returns this point in CIE L*a*b* coordinates. -.sp -.LP -To obtain the CIE L*a*b* coordinates of minimum CIE metric lightness (L*) -for a given Psychometric Hue Angle and Psychometric Chroma, use -.PN XcmsCIELabQueryMinL . -.IN "Psychometric Hue Angle" -.IN "CIE metric lightness" -.IN "CIE metric lightness" "minimum" -.IN "XcmsCIELabQueryMinL" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELabQueryMinL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsFloat \fIchroma\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha minimum lightness -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Ch minimum lightness -.IP \fIchroma\fP 1i -Specifies the chroma at which to find \*(Ch. -.ds Lc minimum lightness -.ds lC hue angle and chroma -.IP \fIcolor_return\fP 1i -Returns the CIE 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. -.LP -.eM -The -.PN XcmsCIELabQueryMinL -function, given a hue angle and chroma, -finds the point of minimum lightness (L*) displayable by the screen. -It returns this point in CIE L*a*b* coordinates. -An -.PN XcmsFailure -return value usually indicates that the given chroma -is beyond maximum for the given hue angle. -.NH 3 -CIELuv Queries -.XS -\*(SN CIELuv Queries -.XE -.LP -The following equations are useful in describing the CIELuv query functions: -.EQ -delim %% -.EN -.LP -.IN "Psychometric Hue Angle" -.IN "CIE metric lightness" -.IN "Psychometric Chroma" -.IN "Psychometric Chroma" "maximum" -.Ds 0 -%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 ]% -.De -.sp -.LP -To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma -for a given Psychometric Hue Angle and CIE metric lightness (L*), use -.PN XcmsCIELuvQueryMaxC . -.IN "XcmsCIELuvQueryMaxC" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELuvQueryMaxC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIL_star\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsFloat \fIL_star\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha maximum chroma -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Ls maximum chroma -.IP \fIL_star\fP 1i -Specifies the lightness (L*) at which to find \*(Ls. -.ds Lc maximum chroma -.ds lC hue angle and lightness -.IP \fIcolor_return\fP 1i -Returns the CIE 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. -.LP -.eM -The -.PN XcmsCIELuvQueryMaxC -function, given a hue angle and lightness, -finds the point of maximum chroma displayable by the screen. -It returns this point in CIE L*u*v* coordinates. -.sp -.LP -To obtain the CIE L*u*v* coordinates of maximum CIE metric lightness (L*) -for a given Psychometric Hue Angle and Psychometric Chroma, use -.PN XcmsCIELuvQueryMaxL . -.IN "Psychometric Hue Angle" -.IN "CIE metric lightness" -.IN "CIE metric lightness" "maximum" -.IN "XcmsCIELuvQueryMaxL" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELuvQueryMaxL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsFloat \fIchroma\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha maximum lightness -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Ls maximum lightness -.IP \fIL_star\fP 1i -Specifies the lightness (L*) at which to find \*(Ls. -.ds Lc maximum lightness -.ds lC hue angle and chroma -.IP \fIcolor_return\fP 1i -Returns the CIE 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. -.LP -.eM -The -.PN XcmsCIELuvQueryMaxL -function, given a hue angle and chroma, -finds the point in CIE L*u*v* color space of maximum -lightness (L*) displayable by the screen. -It returns this point in CIE L*u*v* coordinates. -An -.PN XcmsFailure -return value usually indicates that the given chroma -is beyond maximum for the given hue angle. -.sp -.LP -To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma -for a given Psychometric Hue Angle, use -.PN XcmsCIELuvQueryMaxLC . -.IN "Psychometric Hue Angle" -.IN "Psychometric Chroma" -.IN "CIE metric lightness" -.IN "Psychometric Chroma" "maximum" -.IN "CIE metric lightness" "maximum" -.IN "XcmsCIELuvQueryMaxLC" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELuvQueryMaxLC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha maximum chroma -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Lc maximum chroma -.ds lC hue angle -.IP \fIcolor_return\fP 1i -Returns the CIE 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. -.LP -.eM -The -.PN XcmsCIELuvQueryMaxLC -function, given a hue angle, -finds the point of maximum chroma displayable by the screen. -It returns this point in CIE L*u*v* coordinates. -.sp -.LP -To obtain the CIE L*u*v* coordinates of minimum CIE metric lightness (L*) -for a given Psychometric Hue Angle and Psychometric Chroma, use -.PN XcmsCIELuvQueryMinL . -.IN "Psychometric Hue Angle" -.IN "CIE metric lightness" -.IN "CIE metric lightness" "minimum" -.IN "XcmsCIELuvQueryMinL" "" "@DEF@" -.sM -.FD 0 -Status XcmsCIELuvQueryMinL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue_angle\fP\^; -.br - XcmsFloat \fIchroma\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Ha minimum lightness -.IP \fIhue_angle\fP 1i -Specifies the hue angle (in degrees) at which to find \*(Ha. -.ds Ch minimum lightness -.IP \fIchroma\fP 1i -Specifies the chroma at which to find \*(Ch. -.ds Lc minimum lightness -.ds lC hue angle and chroma -.IP \fIcolor_return\fP 1i -Returns the CIE 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. -.LP -.eM -The -.PN XcmsCIELuvQueryMinL -function, given a hue angle and chroma, -finds the point of minimum lightness (L*) displayable by the screen. -It returns this point in CIE L*u*v* coordinates. -An -.PN XcmsFailure -return value usually indicates that the given chroma -is beyond maximum for the given hue angle. -.NH 3 -TekHVC Queries -.XS -\*(SN TekHVC Queries -.XE -.LP -To obtain the maximum Chroma for a given Hue and Value, use -.PN XcmsTekHVCQueryMaxC . -.IN "Chroma" -.IN "Chroma" "maximum" -.IN "XcmsTekHVCQueryMaxC" "" "@DEF@" -.sM -.FD 0 -Status XcmsTekHVCQueryMaxC\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIvalue\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue\fP\^; -.br - XcmsFloat \fIvalue\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -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 -.IP \fIhue\fP 1i -Specifies the Hue \*(Hu. -.ds Va maximum Chroma -.IP \fIvalue\fP 1i -Specifies the Value in which to find the \*(Va. -.ds Lc maximum Chroma along with the actual Hue and Value -.ds lC maximum Chroma -.IP \fIcolor_return\fP 1i -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. -.LP -.eM -The -.PN XcmsTekHVCQueryMaxC -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 -.LP -To obtain the maximum Value for a given Hue and Chroma, use -.PN XcmsTekHVCQueryMaxV . -.IN "Value" -.IN "Value" "maximum" -.IN "XcmsTekHVCQueryMaxV" "" "@DEF@" -.sM -.FD 0 -Status XcmsTekHVCQueryMaxV\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue\fP\^; -.br - XcmsFloat \fIchroma\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -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 -.IP \fIhue\fP 1i -Specifies the Hue \*(Hu. -.ds Ch maximum Value -.IP \fIchroma\fP 1i -Specifies the chroma at which to find \*(Ch. -.ds Lc maximum Value along with the Hue and Chroma -.ds lC maximum Value -.IP \fIcolor_return\fP 1i -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. -.LP -.eM -The -.PN XcmsTekHVCQueryMaxV -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 -.LP -To obtain the maximum Chroma and Value at which it is reached -for a specified Hue, use -.PN XcmsTekHVCQueryMaxVC . -.IN "Chroma" -.IN "Value" -.IN "Chroma" "maximum" -.IN "Value" "maximum" -.IN "XcmsTekHVCQueryMaxVC" "" "@DEF@" -.sM -.FD 0 -Status XcmsTekHVCQueryMaxVC\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -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 -.IP \fIhue\fP 1i -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 -.IP \fIcolor_return\fP 1i -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. -.LP -.eM -The -.PN XcmsTekHVCQueryMaxVC -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 -.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 -.PN XcmsTekHVCQueryMaxVSamples . -.IN "Chroma" -.IN "Value" -.IN "Chroma" "maximum" -.IN "Value" "maximum" -.IN "XcmsTekHVCQueryMaxVSamples" "" "@DEF@" -.sM -.FD 0 -Status XcmsTekHVCQueryMaxVSamples\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIcolors_return\fP\^, \fInsamples\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue\fP\^; -.br - XcmsColor \fIcolors_return[]\fP\^; -.br - unsigned int \fInsamples\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -The CCC's Client White Point and white point adjustment procedures -are ignored. -.ds Hu for maximum Chroma/Value samples -.IP \fIhue\fP 1i -Specifies the Hue \*(Hu. -.IP \fInsamples\fP 1i -Specifies the number of samples. -.IP \fIcolors_return\fP 1i -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. -.LP -.eM -The -.PN XcmsTekHVCQueryMaxVSamples -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 -.LP -To obtain the minimum Value for a given Hue and Chroma, use -.PN XcmsTekHVCQueryMinV . -.IN "Value" -.IN "Value" "minimum" -.IN "XcmsTekHVCQueryMinV" "" "@DEF@" -.sM -.FD 0 -Status XcmsTekHVCQueryMinV\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsFloat \fIhue\fP\^; -.br - XcmsFloat \fIchroma\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIccc\fP 1i -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 -.IP \fIhue\fP 1i -Specifies the Hue \*(Hu. -.ds Va minimum Value -.IP \fIvalue\fP 1i -Specifies the Value in which to find the \*(Va. -.ds Lc minimum Value and the actual Hue and Chroma -.ds lC minimum Value -.IP \fIcolor_return\fP 1i -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. -.LP -.eM -The -.PN XcmsTekHVCQueryMinV -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. -.NH 2 -Color Management Extensions -.XS -\*(SN Color Management Extensions -.XE -.LP -The Xlib color management facilities can be extended in two ways: -.IP \(bu 5 -Device-Independent Color Spaces -.IP -Device-independent color spaces that are derivable to CIE XYZ -space can be added using the -.PN XcmsAddColorSpace -function. -.IP \(bu 5 -Color Characterization Function Set -.IP -A Color Characterization Function Set consists of -device-dependent color spaces and their functions that -convert between these color spaces and the CIE XYZ -color space, bundled together for a specific class of output devices. -A function set can be added using the -.PN XcmsAddFunctionSet -function. -.NH 3 -Color Spaces -.XS -\*(SN Color Spaces -.XE -.LP -The CIE XYZ color space serves as the hub for all -conversions between device-independent and device-dependent color spaces. -Therefore, the knowledge to convert an -.PN XcmsColor -structure to and from CIE XYZ format is associated with each color space. -For example, conversion from CIE L*u*v* to RGB requires the knowledge -to convert from CIE L*u*v* to CIE XYZ and from CIE XYZ to RGB. -This knowledge is stored as an array of functions that, -when applied in series, will convert the -.PN XcmsColor -structure to or from CIE XYZ format. -This color specification conversion mechanism facilitates -the addition of color spaces. -.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 CIE L*u*v* is performed -by intermediate conversion to CIE u*v*Y and then to CIE L*u*v*, -thus bypassing conversion between CIE u*v*Y and CIE XYZ. -.NH 3 -Adding Device-Independent Color Spaces -.XS -\*(SN Adding Device-Independent Color Spaces -.XE -.LP -To add a device-independent color space, use -.PN XcmsAddColorSpace . -.IN "XcmsAddColorSpace" "" "@DEF@" -.sM -.FD 0 -Status XcmsAddColorSpace\^(\^\fIcolor_space\fP\^) -.br - XcmsColorSpace *\fIcolor_space\fP\^; -.FN -.IP \fIcolor_space\fP 1i -Specifies the device-independent color space to add. -.LP -.eM -The -.PN XcmsAddColorSpace -function makes a device-independent color space (actually an -.PN XcmsColorSpace -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 -.PN XcmsFormatOfPrefix -and -.PN XcmsPrefixOfFormat ). -.LP -If the -.PN XcmsColorSpace -structure is already accessible in the color management system, -.PN XcmsAddColorSpace -returns -.PN XcmsSuccess . -.LP -Note that added -.PN XcmsColorSpaces -must be retained for reference by Xlib. -.NH 3 -Querying Color Space Format and Prefix -.XS -\*(SN Querying Color Space Format and Prefix -.XE -.LP -To obtain the format associated with the color space -associated with a specified color string prefix, use -.PN XcmsFormatOfPrefix . -.IN "XcmsFormatOfPrefix" "" "@DEF@" -.sM -.FD 0 -XcmsColorFormat XcmsFormatOfPrefix\^(\^\fIprefix\fP\^) -.br - char *\fIprefix\fP\^; -.FN -.IP \fIprefix\fP 1i -Specifies the string that contains the color space prefix. -.LP -.eM -The -.PN XcmsFormatOfPrefix -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, -.PN XcmsFormatOfPrefix -returns -.PN XcmsUndefinedFormat . -.LP -.sp -To obtain the color string prefix associated with the color space -specified by a color format, use -.PN XcmsPrefixOfFormat . -.IN "XcmsPrefixOfFormat" "" "@DEF@" -.sM -.FD 0 -char *XcmsPrefixOfFormat\^(\^\fIformat\fP\^) -.br - XcmsColorFormat \fIformat\fP\^; -.FN -.IP \fIformat\fP 1i -Specifies the color specification format. -.LP -.eM -The -.PN XcmsPrefixOfFormat -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. -.NH 3 -Creating Additional Color Spaces -.XS -\*(SN Creating Additional Color Spaces -.XE -.LP -Color space specific information necessary -for color space conversion and color string parsing is stored in an -.PN XcmsColorSpace -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 -.PN XcmsAddColorSpace -function. -.LP -If a new -.PN XcmsColorSpace -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 -.PN XcmsFormatOfPrefix -and -.PN XcmsPrefixOfFormat ). -.sM -.LP -.Ds 0 -.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; -.De -.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 CIE XYZ, -and ``rgb'' or ``RGB'' for RGB. -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 -.PN XcmsColor -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 -.PN XcmsColor -structure from/to the current color space format to/from the CIE 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: -.LP -.Ds 0 -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]. -.De -.LP -This allows Xlib to use the shortest conversion path, -thus bypassing CIE XYZ if possible (for example, TekHVC to CIE L*u*v*). -.NH 3 -Parse String Callback -.XS -\*(SN Parse String Callback -.XE -.LP -The callback in the -.PN XcmsColorSpace -structure for parsing a color string for the particular color space must -adhere to the following software interface specification: -.IN "XcmsParseStringProc" "" "@DEF@" -.sM -.FD 0 -typedef int (*XcmsParseStringProc)\^(\^\fIcolor_string\fP, \fIcolor_return\fP\^) -.br - char *\fIcolor_string\fP\^; -.br - XcmsColor *\fIcolor_return\fP\^; -.FN -.IP \fIcolor_string\fP 1i -Specifies the color string to parse. -.IP \fIcolor_return\fP 1i -Returns the color specification in the color space's format. -.LP -.eM -.NH 3 -Color Specification Conversion Callback -.XS -\*(SN Color Specification Conversion Callback -.XE -.LP -Callback functions in the -.PN XcmsColorSpace -structure for converting a color specification between device-independent -spaces must adhere to the -following software interface specification: -.sM -.FD 0 -Status ConversionProc\^(\^\fIccc\fP, \fIwhite_point\fP, \fIcolors_in_out\fP, \fIncolors\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColor *\fIwhite_point\fP\^; -.br - XcmsColor *\fIcolors_in_out\fP\^; -.br - unsigned int \fIncolors\fP\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.IP \fIwhite_point\fP 1i -Specifies the white point associated with color specifications. -The pixel member should be ignored, -and the entire structure remain unchanged upon return. -.IP \fIcolors_in_out\fP 1i -Specifies an array of color specifications. -Pixel members should be ignored and must remain unchanged upon return. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.LP -.eM -.sp -Callback functions in the -.PN XcmsColorSpace -structure for converting a color specification to or from a device-dependent -space must adhere to the -following software interface specification: -.sM -.FD 0 -Status ConversionProc\^(\^\fIccc\fP, \fIcolors_in_out\fP, \fIncolors\fP, \fIcompression_flags_return\fP\^) -.br - XcmsCCC \fIccc\fP\^; -.br - XcmsColor *\fIcolors_in_out\fP\^; -.br - unsigned int \fIncolors\fP\^; -.br - Bool \fIcompression_flags_return\fP\^[\^]\^; -.FN -.IP \fIccc\fP 1i -Specifies the CCC. -.IP \fIcolors_in_out\fP 1i -Specifies an array of color specifications. -Pixel members should be ignored and must remain unchanged upon return. -.IP \fIncolors\fP 1i -Specifies the number of -.PN XcmsColor -structures in the color-specification array. -.IP \fIcompression_flags_return\fP 1i -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 -.PN True -should be stored at the corresponding index in this array; -otherwise, the array should not be modified. -.LP -.eM -Conversion functions are available globally for use by other color -spaces. -The conversion functions provided by Xlib are: -.TS H -lw(1.8i) lw(1.8i) lw(1.8i). -_ -.sp 6p -.B -Function Converts from Converts to -.sp 6p -_ -.sp 6p -.TH -.R -T{ -.PN XcmsCIELabToCIEXYZ -T} T{ -.PN XcmsCIELabFormat -T} T{ -.PN XcmsCIEXYZFormat -T} -T{ -.PN XcmsCIELuvToCIEuvY -T} T{ -.PN XcmsCIELuvFormat -T} T{ -.PN XcmsCIEuvYFormat -T} -T{ -.PN XcmsCIEXYZToCIELab -T} T{ -.PN XcmsCIEXYZFormat -T} T{ -.PN XcmsCIELabFormat -T} -T{ -.PN XcmsCIEXYZToCIEuvY -T} T{ -.PN XcmsCIEXYZFormat -T} T{ -.PN XcmsCIEuvYFormat -T} -T{ -.PN XcmsCIEXYZToCIExyY -T} T{ -.PN XcmsCIEXYZFormat -T} T{ -.PN XcmsCIExyYFormat -T} -T{ -.PN XcmsCIEXYZToRGBi -T} T{ -.PN XcmsCIEXYZFormat -T} T{ -.PN XcmsRGBiFormat -T} -T{ -.PN XcmsCIEuvYToCIELuv -T} T{ -.PN XcmsCIEuvYFormat -T} T{ -.PN XcmsCIELabFormat -T} -T{ -.PN XcmsCIEuvYToCIEXYZ -T} T{ -.PN XcmsCIEuvYFormat -T} T{ -.PN XcmsCIEXYZFormat -T} -T{ -.PN XcmsCIEuvYToTekHVC -T} T{ -.PN XcmsCIEuvYFormat -T} T{ -.PN XcmsTekHVCFormat -T} -T{ -.PN XcmsCIExyYToCIEXYZ -T} T{ -.PN XcmsCIExyYFormat -T} T{ -.PN XcmsCIEXYZFormat -T} -T{ -.PN XcmsRGBToRGBi -T} T{ -.PN XcmsRGBFormat -T} T{ -.PN XcmsRGBiFormat -T} -T{ -.PN XcmsRGBiToCIEXYZ -T} T{ -.PN XcmsRGBiFormat -T} T{ -.PN XcmsCIEXYZFormat -T} -T{ -.PN XcmsRGBiToRGB -T} T{ -.PN XcmsRGBiFormat -T} T{ -.PN XcmsRGBFormat -T} -T{ -.PN XcmsTekHVCToCIEuvY -T} T{ -.PN XcmsTekHVCFormat -T} T{ -.PN XcmsCIEuvYFormat -T} -.sp 6p -_ -.TE -.NH 3 -Function Sets -.XS -\*(SN Function Sets -.XE -.IN "Function set" -.IN "Function set" "LINEAR_RGB" -.LP -Functions to convert between device-dependent color spaces -and CIE 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 CIE 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. -.IN "Device Color Characterization" -For details about how color characterization data is -stored in root window properties, -see the section on Device Color Characterization in the -\fIInter-Client Communication Conventions Manual\fP. -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. -.NH 3 -Adding Function Sets -.XS -\*(SN Adding Function Sets -.XE -.LP -To add a function set, use -.PN XcmsAddFunctionSet . -.IN "XcmsAddFunctionSet" "" "@DEF@" -.sM -.FD 0 -Status XcmsAddFunctionSet\^(\^\fIfunction_set\fP\^) -.br - XcmsFunctionSet *\fIfunction_set\fP\^; -.FN -.IP \fIfunction_set\fP 1i -Specifies the function set to add. -.LP -.eM -The -.PN XcmsAddFunctionSet -function adds a function set to the color management system. -If the function set uses device-dependent -.PN XcmsColorSpace -structures not accessible in the color management system, -.PN XcmsAddFunctionSet -adds them. -If an added -.PN XcmsColorSpace -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 -.PN XcmsFormatOfPrefix -and -.PN XcmsPrefixOfFormat ). -.LP -Additional function sets should be added before any calls to other -Xlib routines are made. -If not, the -.PN XcmsPerScrnInfo -member of a previously created -.PN XcmsCCC -does not have the opportunity to initialize -with the added function set. -.NH 3 -Creating Additional Function Sets -.XS -\*(SN Creating Additional Function Sets -.XE -.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 -.PN XcmsColorSpace -structures and a means to read and store a -screen's color characterization data. -This data is stored in an -.PN XcmsFunctionSet -structure. -A handle to this structure (that is, by means of global variable) -is usually made accessible to the client program for use with -.PN XcmsAddFunctionSet . -.LP -If a function set uses new device-dependent -.PN XcmsColorSpace -structures, -they will be transparently processed into the color management system. -Function sets can share an -.PN XcmsColorSpace -structure for a device-dependent color space. -In addition, multiple -.PN XcmsColorSpace -structures are allowed for a device-dependent color space; -however, a function set can reference only one of them. -These -.PN XcmsColorSpace -structures will differ in the functions to convert to and from CIE XYZ, -thus tailored for the specific function set. -.sM -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct _XcmsFunctionSet { - XcmsColorSpace **DDColorSpaces; - XcmsScreenInitProc screenInitProc; - XcmsScreenFreeProc screenFreeProc; -} XcmsFunctionSet; -.De -.LP -.eM -The DDColorSpaces member is a pointer to a NULL terminated list -of pointers to -.PN XcmsColorSpace -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 -.PN XcmsPerScrnInfo -structure for a particular screen. -.LP -The screen initialization callback must adhere to the following software -interface specification: -.IN "XcmsScreenInitProc" "" "@DEF@" -.sM -.FD 0 -typedef Status (*XcmsScreenInitProc)\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIscreen_info\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fIscreen_number\fP\^; -.br - XcmsPerScrnInfo *\fIscreen_info\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIscreen_number\fP 1i -Specifies the appropriate screen number on the host server. -.IP \fIscreen_info\fP 1i -Specifies the -.PN XcmsPerScrnInfo -structure, which contains the per screen information. -.LP -.eM -The screen initialization callback in the -.PN XcmsFunctionSet -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 -.PN XcmsPerScrnInfo -structure. -.IN "Device profile" -.IN "Color Characterization Data" -If successful, the procedure fills in the -.PN XcmsPerScrnInfo -structure as follows: -.IP \(bu 5 -It sets the screenData member to the address -of the created device profile data structure -(contents known only by the function set). -.IP \(bu 5 -It next sets the screenWhitePoint member. -.IP \(bu 5 -It next sets the functionSet member to the address of the -.PN XcmsFunctionSet -structure. -.IP \(bu 5 -It then sets the state member to -.PN XcmsInitSuccess -and finally returns -.PN XcmsSuccess . -.LP -If unsuccessful, the procedure sets the state member to -.PN XcmsInitFailure -and returns -.PN XcmsFailure . -.LP -The -.PN XcmsPerScrnInfo -structure contains: -.sM -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct _XcmsPerScrnInfo { - XcmsColor screenWhitePoint; - XPointer functionSet; - XPointer screenData; - unsigned char state; - char pad[3]; -} XcmsPerScrnInfo; -.De -.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: -.IP \(bu 5 -.PN XcmsInitNone -indicates initialization has not been previously attempted. -.IP \(bu 5 -.PN XcmsInitFailure -indicates initialization has been previously attempted but failed. -.IP \(bu 5 -.PN XcmsInitSuccess -indicates initialization has been previously attempted and succeeded. -.LP -The screen free callback must adhere to the following software -interface specification: -.IN "XcmsScreenFreeProc" "" "@DEF@" -.sM -.FD 0 -typedef void (*XcmsScreenFreeProc)\^(\^\fIscreenData\fP\^) -.br - XPointer \fIscreenData\fP\^; -.FN -.IP \fIscreenData\fP 1i -Specifies the data to be freed. -.LP -.eM -This function is called to free the screenData stored in an -.PN XcmsPerScrnInfo -structure. -.bp |