« back to all changes in this revision
Viewing changes to specs/libX11/CH06
- browse files at revision 37
- compare with another revision
- download diff
- download tarball
- view history from revision 37
- Committer: Bazaar Package Importer
- Author(s): Timo Aaltonen
- Date: 2009-12-04 11:43:54 UTC
- mfrom: (1.1.10 upstream) (2.1.5 sid)
- Revision ID: james.westby@ubuntu.com-20091204114354-0lik4mbb1bv1a8nw
Tags: 2:1.3.2-1ubuntu1
* Merge from Debian unstable, remaining changes:
- Add 100_latin_locale_alias.diff (LP 379785)
- Add 100_latin_locale_alias.diff (LP 379785)
- files added:
- debian/libx11-6.symbols
- patches
- specs
- specs/XIM
- specs/i18n
- specs/libX11
- files removed:
- debian/patches/002_arm_abi_brain_damage.diff
- files modified:
- ChangeLog
added
removed
specs/libX11/CH06
1
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
2
.\"
3
.\" Permission is hereby granted, free of charge, to any person obtaining
4
.\" a copy of this software and associated documentation files (the
5
.\" "Software"), to deal in the Software without restriction, including
6
.\" without limitation the rights to use, copy, modify, merge, publish,
7
.\" distribute, sublicense, and/or sell copies of the Software, and to
8
.\" permit persons to whom the Software is furnished to do so, subject to
9
.\" the following conditions:
10
.\"
11
.\" The above copyright notice and this permission notice shall be included
12
.\" in all copies or substantial portions of the Software.
13
.\"
14
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
17
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
18
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
19
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
20
.\" OTHER DEALINGS IN THE SOFTWARE.
21
.\"
22
.\" Except as contained in this notice, the name of the X Consortium shall
23
.\" not be used in advertising or otherwise to promote the sale, use or
24
.\" other dealings in this Software without prior written authorization
25
.\" from the X Consortium.
26
.\"
27
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
28
.\" Digital Equipment Corporation
29
.\"
30
.\" Portions Copyright \(co 1990, 1991 by
31
.\" Tektronix, Inc.
32
.\"
33
.\" Permission to use, copy, modify and distribute this documentation for
34
.\" any purpose and without fee is hereby granted, provided that the above
35
.\" copyright notice appears in all copies and that both that copyright notice
36
.\" and this permission notice appear in all copies, and that the names of
37
.\" Digital and Tektronix not be used in in advertising or publicity pertaining
38
.\" to this documentation without specific, written prior permission.
39
.\" Digital and Tektronix makes no representations about the suitability
40
.\" of this documentation for any purpose.
41
.\" It is provided ``as is'' without express or implied warranty.
42
.\"
43
\&
44
.sp 1
45
.ce 3
46
\s+1\fBChapter 6\fP\s-1
47
48
\s+1\fBColor Management Functions\fP\s-1
49
.sp 2
50
.nr H1 6
51
.nr H2 0
52
.nr H3 0
53
.nr H4 0
54
.nr H5 0
55
.na
56
.LP
57
.XS
58
Chapter 6: Color Management Functions
59
.XE
60
Each X window always has an associated colormap that
61
provides a level of indirection between pixel values and colors displayed
62
on the screen.
63
Xlib provides functions that you can use to manipulate a colormap.
64
The X protocol defines colors using values in the RGB color space.
65
The RGB color space is device dependent;
66
rendering an RGB value on differing output devices typically results
67
in different colors.
68
Xlib also provides a means for clients to specify color using
69
device-independent color spaces for consistent results across devices.
70
Xlib supports device-independent color spaces derivable from the CIE XYZ
71
color space.
72
This includes the CIE XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as
73
the TekHVC color space.
74
.LP
75
This chapter discusses how to:
76
.IP \(bu 5
77
Create, copy, and destroy a colormap
78
.IP \(bu 5
79
Specify colors by name or value
80
.IP \(bu 5
81
Allocate, modify, and free color cells
82
.IP \(bu 5
83
Read entries in a colormap
84
.IP \(bu 5
85
Convert between color spaces
86
.IP \(bu 5
87
Control aspects of color conversion
88
.IP \(bu 5
89
Query the color gamut of a screen
90
.IP \(bu 5
91
Add new color spaces
92
.LP
93
All functions, types, and symbols in this chapter with the prefix ``Xcms''
94
are defined in
95
.hN X11/Xcms.h .
96
The remaining functions and types are defined in
97
.hN X11/Xlib.h .
98
.LP
99
Functions in this chapter manipulate the representation of color on the
100
screen.
101
For each possible value that a pixel can take in a window,
102
there is a color cell in the colormap.
103
For example,
104
if a window is 4 bits deep, pixel values 0 through 15 are defined.
105
A colormap is a collection of color cells.
106
A color cell consists of a triple of red, green, and blue (RGB) values.
107
The hardware imposes limits on the number of significant
108
bits in these values.
109
As each pixel is read out of display memory, the pixel
110
is looked up in a colormap.
111
The RGB value of the cell determines what color is displayed on the screen.
112
On a grayscale display with a black-and-white monitor,
113
the values are combined to determine the brightness on the screen.
114
.LP
115
Typically, an application allocates color cells or sets of color cells
116
to obtain the desired colors.
117
The client can allocate read-only cells.
118
In which case,
119
the pixel values for these colors can be shared among multiple applications,
120
and the RGB value of the cell cannot be changed.
121
If the client allocates read/write cells,
122
they are exclusively owned by the client,
123
and the color associated with the pixel value can be changed at will.
124
Cells must be allocated (and, if read/write, initialized with an RGB value)
125
by a client to obtain desired colors.
126
The use of pixel value for an
127
unallocated cell results in an undefined color.
128
.LP
129
Because colormaps are associated with windows, X supports displays
130
with multiple colormaps and, indeed, different types of colormaps.
131
If there are insufficient colormap resources in the display,
132
some windows will display in their true colors, and others
133
will display with incorrect colors.
134
A window manager usually controls which windows are displayed
135
in their true colors if more than one colormap is required for
136
the color resources the applications are using.
137
At any time, there is a set of installed colormaps for a screen.
138
Windows using one of the installed colormaps display with true colors, and
139
windows using other colormaps generally display with incorrect colors.
140
You can control the set of installed colormaps by using
141
.PN XInstallColormap
142
and
143
.PN XUninstallColormap .
144
.LP
145
Colormaps are local to a particular screen.
146
Screens always have a default colormap,
147
and programs typically allocate cells out of this colormap.
148
Generally, you should not write applications that monopolize
149
color resources.
150
Although some hardware supports multiple colormaps installed at one time,
151
many of the hardware displays
152
built today support only a single installed colormap, so the primitives
153
are written to encourage sharing of colormap entries between applications.
154
.LP
155
The
156
.PN DefaultColormap
157
macro returns the default colormap.
158
The
159
.PN DefaultVisual
160
macro
161
returns the default visual type for the specified screen.
162
.IN "Color map"
163
Possible visual types are
164
.PN StaticGray ,
165
.PN GrayScale ,
166
.PN StaticColor ,
167
.PN PseudoColor ,
168
.PN TrueColor ,
169
or
170
.PN DirectColor
171
(see section 3.1).
172
.NH 2
173
Color Structures
174
.XS
175
\*(SN Color Structures
176
.XE
177
.LP
178
Functions that operate only on RGB color space values use an
179
.PN XColor
180
structure, which contains:
181
.LP
182
.IN "XColor" "" "@DEF@"
183
.sM
184
.Ds 0
185
.TA .5i 2.5i
186
.ta .5i 2.5i
187
typedef struct {
188
unsigned long pixel; /* pixel value */
189
unsigned short red, green, blue; /* rgb values */
190
char flags; /* DoRed, DoGreen, DoBlue */
191
char pad;
192
} XColor;
193
.De
194
.LP
195
.eM
196
The red, green, and blue values are always in the range 0 to 65535
197
inclusive, independent of the number of bits actually used in the
198
display hardware.
199
The server scales these values down to the range used by the hardware.
200
Black is represented by (0,0,0),
201
and white is represented by (65535,65535,65535).
202
.IN "Color"
203
In some functions,
204
the flags member controls which of the red, green, and blue members is used
205
and can be the inclusive OR of zero or more of
206
.PN DoRed ,
207
.PN DoGreen ,
208
and
209
.PN DoBlue .
210
.LP
211
.sp
212
Functions that operate on all color space values use an
213
.PN XcmsColor
214
structure.
215
This structure contains a union of substructures,
216
each supporting color specification encoding for a particular color space.
217
Like the
218
.PN XColor
219
structure, the
220
.PN XcmsColor
221
structure contains pixel
222
and color specification information (the spec member in the
223
.PN XcmsColor
224
structure).
225
.IN "XcmsColor" "" "@DEF@"
226
.sM
227
.LP
228
.Ds 0
229
.TA .5i 1i 2.5i
230
.ta .5i 1i 2.5i
231
typedef unsigned long XcmsColorFormat; /* Color Specification Format */
232
233
typedef struct {
234
union {
235
XcmsRGB RGB;
236
XcmsRGBi RGBi;
237
XcmsCIEXYZ CIEXYZ;
238
XcmsCIEuvY CIEuvY;
239
XcmsCIExyY CIExyY;
240
XcmsCIELab CIELab;
241
XcmsCIELuv CIELuv;
242
XcmsTekHVC TekHVC;
243
XcmsPad Pad;
244
} spec;
245
unsigned long pixel;
246
XcmsColorFormat format;
247
} XcmsColor; /* Xcms Color Structure */
248
.De
249
.LP
250
.eM
251
Because the color specification can be encoded for the various color spaces,
252
encoding for the spec member is identified by the format member,
253
which is of type
254
.PN XcmsColorFormat .
255
The following macros define standard formats.
256
.sM
257
.TS
258
lw(.5i) lw(1.6i) lw(1.4i) lw(1.5i).
259
T{
260
#define
261
T} T{
262
.PN XcmsUndefinedFormat
263
T} T{
264
0x00000000
265
T}
266
T{
267
#define
268
T} T{
269
.PN XcmsCIEXYZFormat
270
T} T{
271
0x00000001
272
T} T{
273
/* CIE XYZ */
274
T}
275
T{
276
#define
277
T} T{
278
.PN XcmsCIEuvYFormat
279
T} T{
280
0x00000002
281
T} T{
282
/* CIE u'v'Y */
283
T}
284
T{
285
#define
286
T} T{
287
.PN XcmsCIExyYFormat
288
T} T{
289
0x00000003
290
T} T{
291
/* CIE xyY */
292
T}
293
T{
294
#define
295
T} T{
296
.PN XcmsCIELabFormat
297
T} T{
298
0x00000004
299
T} T{
300
/* CIE L*a*b* */
301
T}
302
T{
303
#define
304
T} T{
305
.PN XcmsCIELuvFormat
306
T} T{
307
0x00000005
308
T} T{
309
/* CIE L*u*v* */
310
T}
311
T{
312
#define
313
T} T{
314
.PN XcmsTekHVCFormat
315
T} T{
316
0x00000006
317
T} T{
318
/* TekHVC */
319
T}
320
T{
321
#define
322
T} T{
323
.PN XcmsRGBFormat
324
T} T{
325
0x80000000
326
T} T{
327
/* RGB Device */
328
T}
329
T{
330
#define
331
T} T{
332
.PN XcmsRGBiFormat
333
T} T{
334
0x80000001
335
T} T{
336
/* RGB Intensity */
337
T}
338
.TE
339
.LP
340
.eM
341
Formats for device-independent color spaces are
342
distinguishable from those for device-dependent spaces by the 32nd bit.
343
If this bit is set,
344
it indicates that the color specification is in a device-dependent form;
345
otherwise, it is in a device-independent form.
346
If the 31st bit is set,
347
this indicates that the color space has been added to Xlib at run time
348
(see section 6.12.4).
349
The format value for a color space added at run time may be different each
350
time the program is executed.
351
If references to such a color space must be made outside the client
352
(for example, storing a color specification in a file),
353
then reference should be made by color space string prefix
354
(see
355
.PN XcmsFormatOfPrefix
356
and
357
.PN XcmsPrefixOfFormat ).
358
.LP
359
Data types that describe the color specification encoding for the various
360
color spaces are defined as follows:
361
.sM
362
.IN "XcmsRGB" "" "@DEF@"
363
.LP
364
.Ds 0
365
.TA .5i 2.5i
366
.ta .5i 2.5i
367
typedef double XcmsFloat;
368
369
typedef struct {
370
unsigned short red; /* 0x0000 to 0xffff */
371
unsigned short green; /* 0x0000 to 0xffff */
372
unsigned short blue; /* 0x0000 to 0xffff */
373
} XcmsRGB; /* RGB Device */
374
.De
375
.IN "XcmsRGBi" "" "@DEF@"
376
.LP
377
.Ds 0
378
.TA .5i 2.5i
379
.ta .5i 2.5i
380
typedef struct {
381
XcmsFloat red; /* 0.0 to 1.0 */
382
XcmsFloat green; /* 0.0 to 1.0 */
383
XcmsFloat blue; /* 0.0 to 1.0 */
384
} XcmsRGBi; /* RGB Intensity */
385
.De
386
.IN "XcmsCIEXYZ" "" "@DEF@"
387
.LP
388
.Ds 0
389
.TA .5i 2.5i
390
.ta .5i 2.5i
391
typedef struct {
392
XcmsFloat X;
393
XcmsFloat Y; /* 0.0 to 1.0 */
394
XcmsFloat Z;
395
} XcmsCIEXYZ; /* CIE XYZ */
396
.De
397
.IN "XcmsCIEuvY" "" "@DEF@"
398
.LP
399
.Ds 0
400
.TA .5i 2.5i
401
.ta .5i 2.5i
402
typedef struct {
403
XcmsFloat u_prime; /* 0.0 to ~0.6 */
404
XcmsFloat v_prime; /* 0.0 to ~0.6 */
405
XcmsFloat Y; /* 0.0 to 1.0 */
406
} XcmsCIEuvY; /* CIE u'v'Y */
407
.De
408
.IN "XcmsCIExyY" "" "@DEF@"
409
.LP
410
.Ds 0
411
.TA .5i 2.5i
412
.ta .5i 2.5i
413
typedef struct {
414
XcmsFloat x; /* 0.0 to ~.75 */
415
XcmsFloat y; /* 0.0 to ~.85 */
416
XcmsFloat Y; /* 0.0 to 1.0 */
417
} XcmsCIExyY; /* CIE xyY */
418
.De
419
.IN "XcmsCIELab" "" "@DEF@"
420
.LP
421
.Ds 0
422
.TA .5i 2.5i
423
.ta .5i 2.5i
424
typedef struct {
425
XcmsFloat L_star; /* 0.0 to 100.0 */
426
XcmsFloat a_star;
427
XcmsFloat b_star;
428
} XcmsCIELab; /* CIE L*a*b* */
429
.De
430
.IN "XcmsCIELuv" "" "@DEF@"
431
.LP
432
.Ds 0
433
.TA .5i 2.5i
434
.ta .5i 2.5i
435
typedef struct {
436
XcmsFloat L_star; /* 0.0 to 100.0 */
437
XcmsFloat u_star;
438
XcmsFloat v_star;
439
} XcmsCIELuv; /* CIE L*u*v* */
440
.De
441
.IN "XcmsTekHVC" "" "@DEF@"
442
.LP
443
.Ds 0
444
.TA .5i 2.5i
445
.ta .5i 2.5i
446
typedef struct {
447
XcmsFloat H; /* 0.0 to 360.0 */
448
XcmsFloat V; /* 0.0 to 100.0 */
449
XcmsFloat C; /* 0.0 to 100.0 */
450
} XcmsTekHVC; /* TekHVC */
451
.De
452
.IN "XcmsPad" "" "@DEF@"
453
.LP
454
.Ds 0
455
.TA .5i 2.5i
456
.ta .5i 2.5i
457
typedef struct {
458
XcmsFloat pad0;
459
XcmsFloat pad1;
460
XcmsFloat pad2;
461
XcmsFloat pad3;
462
} XcmsPad; /* four doubles */
463
.De
464
.LP
465
.eM
466
The device-dependent formats provided allow color specification in:
467
.IP \(bu 5
468
RGB Intensity
469
.Pn ( XcmsRGBi )
470
.IP
471
Red, green, and blue linear intensity values,
472
floating-point values from 0.0 to 1.0,
473
where 1.0 indicates full intensity, 0.5 half intensity, and so on.
474
.IP \(bu 5
475
RGB Device
476
.Pn ( XcmsRGB )
477
.IP
478
Red, green, and blue values appropriate for the specified output device.
479
.PN XcmsRGB
480
values are of type unsigned short,
481
scaled from 0 to 65535 inclusive,
482
and are interchangeable with the red, green, and blue values in an
483
.PN XColor
484
structure.
485
.LP
486
It is important to note that RGB Intensity values are not gamma corrected
487
values.
488
In contrast,
489
RGB Device values generated as a result of converting color specifications
490
are always gamma corrected, and
491
RGB Device values acquired as a result of querying a colormap
492
or passed in by the client are assumed by Xlib to be gamma corrected.
493
The term \fIRGB value\fP in this manual always refers to an RGB Device value.
494
.NH 2
495
Color Strings
496
.XS
497
\*(SN Color Strings
498
.XE
499
.LP
500
Xlib provides a mechanism for using string names for colors.
501
A color string may either contain an abstract color name
502
or a numerical color specification.
503
Color strings are case-insensitive.
504
.LP
505
Color strings are used in the following functions:
506
.IP \(bu 5
507
.PN XAllocNamedColor
508
.IP \(bu 5
509
.PN XcmsAllocNamedColor
510
.IP \(bu 5
511
.PN XLookupColor
512
.IP \(bu 5
513
.PN XcmsLookupColor
514
.IP \(bu 5
515
.PN XParseColor
516
.IP \(bu 5
517
.PN XStoreNamedColor
518
.LP
519
Xlib supports the use of abstract color names, for example, red or blue.
520
A value for this abstract name is obtained by searching one or more color
521
name databases.
522
Xlib first searches zero or more client-side databases;
523
the number, location, and content of these databases is
524
implementation-dependent and might depend on the current locale.
525
If the name is not found, Xlib then looks for the color in the
526
X server's database.
527
If the color name is not in the Host Portable Character Encoding,
528
the result is implementation-dependent.
529
.LP
530
A numerical color specification
531
consists of a color space name and a set of values in the following syntax:
532
.LP
533
.sM
534
.Ds 0
535
\fI<color_space_name>\fP:\fI<value>/.../<value>\fP
536
.De
537
.LP
538
.eM
539
The following are examples of valid color strings.
540
.LP
541
.Ds 0
542
"CIEXYZ:0.3227/0.28133/0.2493"
543
"RGBi:1.0/0.0/0.0"
544
"rgb:00/ff/00"
545
"CIELuv:50.0/0.0/0.0"
546
.De
547
The syntax and semantics of numerical specifications are given
548
for each standard color space in the following sections.
549
.NH 3
550
RGB Device String Specification
551
.XS
552
\*(SN RGB Device String Specification
553
.XE
554
.LP
555
An RGB Device specification is identified by
556
the prefix ``rgb:'' and conforms to the following syntax:
557
.LP
558
.\" Start marker code here
559
.Ds 0
560
rgb:\fI<red>/<green>/<blue>\fP
561
562
\fI<red>\fP, \fI<green>\fP, \fI<blue>\fP := \fIh\fP | \fIhh\fP | \fIhhh\fP | \fIhhhh\fP
563
\fIh\fP := single hexadecimal digits (case insignificant)
564
.De
565
.\" End marker code here
566
.LP
567
Note that \fIh\fP indicates the value scaled in 4 bits,
568
\fIhh\fP the value scaled in 8 bits,
569
\fIhhh\fP the value scaled in 12 bits,
570
and \fIhhhh\fP the value scaled in 16 bits, respectively.
571
.LP
572
Typical examples are the strings ``rgb:ea/75/52'' and ``rgb:ccc/320/320'',
573
but mixed numbers of hexadecimal digit strings
574
(``rgb:ff/a5/0'' and ``rgb:ccc/32/0'')
575
are also allowed.
576
.LP
577
For backward compatibility, an older syntax for RGB Device is
578
supported, but its continued use is not encouraged.
579
The syntax is an initial sharp sign character followed by
580
a numeric specification, in one of the following formats:
581
.LP
582
.\" Start marker code here
583
.Ds 0
584
.TA 2i
585
.ta 2i
586
#RGB (4 bits each)
587
#RRGGBB (8 bits each)
588
#RRRGGGBBB (12 bits each)
589
#RRRRGGGGBBBB (16 bits each)
590
.De
591
.\" End marker code here
592
.LP
593
The R, G, and B represent single hexadecimal digits.
594
When fewer than 16 bits each are specified,
595
they represent the most significant bits of the value
596
(unlike the ``rgb:'' syntax, in which values are scaled).
597
For example, the string ``#3a7'' is the same as ``#3000a0007000''.
598
.NH 3
599
RGB Intensity String Specification
600
.XS
601
\*(SN RGB Intensity String Specification
602
.XE
603
.LP
604
An RGB intensity specification is identified
605
by the prefix ``rgbi:'' and conforms to the following syntax:
606
.LP
607
.\" Start marker code here
608
.Ds 0
609
rgbi:\fI<red>/<green>/<blue>\fP
610
.De
611
.\" End marker code here
612
.LP
613
Note that red, green, and blue are floating-point values
614
between 0.0 and 1.0, inclusive.
615
The input format for these values is an optional sign,
616
a string of numbers possibly containing a decimal point,
617
and an optional exponent field containing an E or e
618
followed by a possibly signed integer string.
619
.NH 3
620
Device-Independent String Specifications
621
.XS
622
\*(SN Device-Independent String Specifications
623
.XE
624
.LP
625
The standard device-independent string specifications have
626
the following syntax:
627
.LP
628
.\" Start marker code here
629
.Ds 0
630
CIEXYZ:\fI<X>/<Y>/<Z>\fP
631
CIEuvY:\fI<u>/<v>/<Y>\fP
632
CIExyY:\fI<x>/<y>/<Y>\fP
633
CIELab:\fI<L>/<a>/<b>\fP
634
CIELuv:\fI<L>/<u>/<v>\fP
635
TekHVC:\fI<H>/<V>/<C>\fP
636
.De
637
.\" End marker code here
638
.LP
639
All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are
640
floating-point values.
641
The syntax for these values is an optional plus or minus sign,
642
a string of digits possibly containing a decimal point,
643
and an optional exponent field consisting of an ``E'' or ``e''
644
followed by an optional plus or minus followed by a string of digits.
645
.NH 2
646
Color Conversion Contexts and Gamut Mapping
647
.XS
648
\*(SN Color Conversion Contexts and Gamut Mapping
649
.XE
650
.LP
651
When Xlib converts device-independent color specifications
652
into device-dependent specifications and vice versa,
653
it uses knowledge about the color limitations of the screen hardware.
654
This information, typically called the device profile,
655
.IN "Device profile"
656
is available in a Color Conversion Context (CCC).
657
.IN "Color Conversion Context"
658
.IN "CCC"
659
.LP
660
Because a specified color may be outside the color gamut of the target screen
661
and the white point associated with the color specification may differ
662
from the white point inherent to the screen,
663
Xlib applies gamut mapping when it encounters certain conditions:
664
.IN "White point"
665
.IP \(bu 5
666
Gamut compression occurs when conversion of device-independent
667
color specifications to device-dependent color specifications
668
results in a color out of the target screen's gamut.
669
.IP \(bu 5
670
White adjustment occurs when the inherent white point of the screen
671
differs from the white point assumed by the client.
672
.LP
673
Gamut handling methods are stored as callbacks in the CCC,
674
which in turn are used by the color space conversion routines.
675
Client data is also stored in the CCC for each callback.
676
The CCC also contains the white point the client assumes to be
677
associated with color specifications (that is, the Client White Point).
678
.IN "Client White Point"
679
.IN "Gamut compression"
680
.IN "Gamut handling"
681
.IN "White point adjustment"
682
The client can specify the gamut handling callbacks and client data
683
as well as the Client White Point.
684
Xlib does not preclude the X client from performing other
685
forms of gamut handling (for example, gamut expansion);
686
however, Xlib does not provide direct support for gamut handling
687
other than white adjustment and gamut compression.
688
.LP
689
Associated with each colormap is an initial CCC transparently generated by
690
Xlib.
691
.IN "Color Conversion Context" "creation"
692
Therefore,
693
when you specify a colormap as an argument to an Xlib function,
694
you are indirectly specifying a CCC.
695
.IN "CCC" "of colormap"
696
.IN "Color Conversion Context" "of colormap"
697
There is a default CCC associated with each screen.
698
Newly created CCCs inherit attributes from the default CCC,
699
so the default CCC attributes can be modified to affect new CCCs.
700
.IN "CCC" "default"
701
.IN "Color Conversion Context" "default"
702
.LP
703
Xcms functions in which gamut mapping can occur return
704
.PN Status
705
and have specific status values defined for them,
706
as follows:
707
.IP \(bu 5
708
.PN XcmsFailure
709
indicates that the function failed.
710
.IP \(bu 5
711
.PN XcmsSuccess
712
indicates that the function succeeded.
713
In addition,
714
if the function performed any color conversion,
715
the colors did not need to be compressed.
716
.IP \(bu 5
717
.PN XcmsSuccessWithCompression
718
indicates the function performed color conversion
719
and at least one of the colors needed to be compressed.
720
The gamut compression method is determined by the gamut compression
721
procedure in the CCC that is specified directly as a function argument
722
or in the CCC indirectly specified by means of the colormap argument.
723
.NH 2
724
Creating, Copying, and Destroying Colormaps
725
.XS
726
\*(SN Creating, Copying, and Destroying Colormaps
727
.XE
728
.LP
729
To create a colormap for a screen, use
730
.PN XCreateColormap .
731
.IN "XCreateColormap" "" "@DEF@"
732
.sM
733
.FD 0
734
Colormap XCreateColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvisual\fP\^, \fIalloc\fP\^)
735
.br
736
Display *\fIdisplay\fP\^;
737
.br
738
Window \fIw\fP\^;
739
.br
740
Visual *\fIvisual\fP\^;
741
.br
742
int \fIalloc\fP\^;
743
.FN
744
.IP \fIdisplay\fP 1i
745
Specifies the connection to the X server.
746
.ds Wi on whose screen you want to create a colormap
747
.IP \fIw\fP 1i
748
Specifies the window \*(Wi.
749
.IP \fIvisual\fP 1i
750
Specifies a visual type supported on the screen.
751
If the visual type is not one supported by the screen,
752
a
753
.PN BadMatch
754
error results.
755
.IP \fIalloc\fP 1i
756
Specifies the colormap entries to be allocated.
757
You can pass
758
.PN AllocNone
759
or
760
.PN AllocAll .
761
.LP
762
.eM
763
The
764
.PN XCreateColormap
765
function creates a colormap of the specified visual type for the screen
766
on which the specified window resides and returns the colormap ID
767
associated with it.
768
Note that the specified window is only used to determine the screen.
769
.LP
770
The initial values of the colormap entries are undefined for the
771
visual classes
772
.PN GrayScale ,
773
.PN PseudoColor ,
774
and
775
.PN DirectColor .
776
For
777
.PN StaticGray ,
778
.PN StaticColor ,
779
and
780
.PN TrueColor ,
781
the entries have defined values,
782
but those values are specific to the visual and are not defined by X.
783
For
784
.PN StaticGray ,
785
.PN StaticColor ,
786
and
787
.PN TrueColor ,
788
alloc must be
789
.PN AllocNone ,
790
or a
791
.PN BadMatch
792
error results.
793
For the other visual classes,
794
if alloc is
795
.PN AllocNone ,
796
the colormap initially has no allocated entries,
797
and clients can allocate them.
798
For information about the visual types,
799
see section 3.1.
800
.LP
801
If alloc is
802
.PN AllocAll ,
803
the entire colormap is allocated writable.
804
The initial values of all allocated entries are undefined.
805
For
806
.PN GrayScale
807
and
808
.PN PseudoColor ,
809
the effect is as if an
810
.PN XAllocColorCells
811
call returned all pixel values from zero to N \- 1,
812
where N is the colormap entries value in the specified visual.
813
For
814
.PN DirectColor ,
815
the effect is as if an
816
.PN XAllocColorPlanes
817
call returned a pixel value of zero and red_mask, green_mask,
818
and blue_mask values containing the same bits as the corresponding
819
masks in the specified visual.
820
However, in all cases,
821
none of these entries can be freed by using
822
.PN XFreeColors .
823
.LP
824
.PN XCreateColormap
825
can generate
826
.PN BadAlloc ,
827
.PN BadMatch ,
828
.PN BadValue ,
829
and
830
.PN BadWindow
831
errors.
832
.LP
833
.sp
834
To create a new colormap when the allocation out of a previously
835
shared colormap has failed because of resource exhaustion, use
836
.PN XCopyColormapAndFree .
837
.IN "XCopyColormapAndFree" "" "@DEF@"
838
.sM
839
.FD 0
840
Colormap XCopyColormapAndFree\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
841
.br
842
Display *\fIdisplay\fP\^;
843
.br
844
Colormap \fIcolormap\fP\^;
845
.FN
846
.IP \fIdisplay\fP 1i
847
Specifies the connection to the X server.
848
.IP \fIcolormap\fP 1i
849
Specifies the colormap.
850
.LP
851
.eM
852
The
853
.PN XCopyColormapAndFree
854
function creates a colormap of the same visual type and for the same screen
855
as the specified colormap and returns the new colormap ID.
856
It also moves all of the client's existing allocation from the specified
857
colormap to the new colormap with their color values intact
858
and their read-only or writable characteristics intact and frees those entries
859
in the specified colormap.
860
Color values in other entries in the new colormap are undefined.
861
If the specified colormap was created by the client with alloc set to
862
.PN AllocAll ,
863
the new colormap is also created with
864
.PN AllocAll ,
865
all color values for all entries are copied from the specified colormap,
866
and then all entries in the specified colormap are freed.
867
If the specified colormap was not created by the client with
868
.PN AllocAll ,
869
the allocations to be moved are all those pixels and planes
870
that have been allocated by the client using
871
.PN XAllocColor ,
872
.PN XAllocNamedColor ,
873
.PN XAllocColorCells ,
874
or
875
.PN XAllocColorPlanes
876
and that have not been freed since they were allocated.
877
.LP
878
.PN XCopyColormapAndFree
879
can generate
880
.PN BadAlloc
881
and
882
.PN BadColor
883
errors.
884
.LP
885
.sp
886
To destroy a colormap, use
887
.PN XFreeColormap .
888
.IN "XFreeColormap" "" "@DEF@"
889
.sM
890
.FD 0
891
XFreeColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
892
.br
893
Display *\fIdisplay\fP\^;
894
.br
895
Colormap \fIcolormap\fP\^;
896
.FN
897
.IP \fIdisplay\fP 1i
898
Specifies the connection to the X server.
899
.ds Cm that you want to destroy
900
.IP \fIcolormap\fP 1i
901
Specifies the colormap \*(Cm.
902
.LP
903
.eM
904
The
905
.PN XFreeColormap
906
function deletes the association between the colormap resource ID
907
and the colormap and frees the colormap storage.
908
However, this function has no effect on the default colormap for a screen.
909
If the specified colormap is an installed map for a screen,
910
it is uninstalled (see
911
.PN XUninstallColormap ).
912
If the specified colormap is defined as the colormap for a window (by
913
.PN XCreateWindow ,
914
.PN XSetWindowColormap ,
915
or
916
.PN XChangeWindowAttributes ),
917
.PN XFreeColormap
918
changes the colormap associated with the window to
919
.PN None
920
and generates a
921
.PN ColormapNotify
922
event.
923
X does not define the colors displayed for a window with a colormap of
924
.PN None .
925
.LP
926
.PN XFreeColormap
927
can generate a
928
.PN BadColor
929
error.
930
.NH 2
931
Mapping Color Names to Values
932
.XS
933
\*(SN Mapping Color Names to Values
934
.XE
935
.LP
936
.sp
937
To map a color name to an RGB value, use
938
.PN XLookupColor .
939
.IN "Color" "naming"
940
.IN "XLookupColor" "" "@DEF@"
941
.sM
942
.FD 0
943
Status XLookupColor\^(\^\fIdisplay\fP, \fIcolormap\fP, \fIcolor_name\fP, \
944
\fIexact_def_return\fP\^, \fIscreen_def_return\fP\^)
945
.br
946
Display *\fIdisplay\fP\^;
947
.br
948
Colormap \fIcolormap\fP\^;
949
.br
950
char *\fIcolor_name\fP\^;
951
.br
952
XColor *\fIexact_def_return\fP\^, *\fIscreen_def_return\fP\^;
953
.FN
954
.IP \fIdisplay\fP 1i
955
Specifies the connection to the X server.
956
.IP \fIcolormap\fP 1i
957
Specifies the colormap.
958
.IP \fIcolor_name\fP 1i
959
Specifies the color name string (for example, red) whose color
960
definition structure you want returned.
961
.IP \fIexact_def_return\fP 1i
962
Returns the exact RGB values.
963
.IP \fIscreen_def_return\fP 1i
964
Returns the closest RGB values provided by the hardware.
965
.LP
966
.eM
967
The
968
.PN XLookupColor
969
function looks up the string name of a color with respect to the screen
970
associated with the specified colormap.
971
It returns both the exact color values and
972
the closest values provided by the screen
973
with respect to the visual type of the specified colormap.
974
If the color name is not in the Host Portable Character Encoding,
975
the result is implementation-dependent.
976
Use of uppercase or lowercase does not matter.
977
.PN XLookupColor
978
returns nonzero if the name is resolved;
979
otherwise, it returns zero.
980
.LP
981
.PN XLookupColor
982
can generate a
983
.PN BadColor
984
error.
985
.LP
986
.sp
987
To map a color name to the exact RGB value, use
988
.PN XParseColor .
989
.IN "Color" "naming"
990
.IN "XParseColor" "" "@DEF@"
991
.sM
992
.FD 0
993
Status XParseColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \^\fIspec\fP\^, \fIexact_def_return\fP\^)
994
.br
995
Display *\fIdisplay\fP\^;
996
.br
997
Colormap \fIcolormap\fP\^;
998
.br
999
char *\fIspec\fP\^;
1000
.br
1001
XColor *\fIexact_def_return\fP\^;
1002
.FN
1003
.IP \fIdisplay\fP 1i
1004
Specifies the connection to the X server.
1005
.IP \fIcolormap\fP 1i
1006
Specifies the colormap.
1007
.IP \fIspec\fP 1i
1008
Specifies the color name string;
1009
case is ignored.
1010
.IP \fIexact_def_return\fP 1i
1011
Returns the exact color value for later use and sets the
1012
.PN DoRed ,
1013
.PN DoGreen ,
1014
and
1015
.PN DoBlue
1016
flags.
1017
.LP
1018
.eM
1019
The
1020
.PN XParseColor
1021
function looks up the string name of a color with respect to the screen
1022
associated with the specified colormap.
1023
It returns the exact color value.
1024
If the color name is not in the Host Portable Character Encoding,
1025
the result is implementation-dependent.
1026
Use of uppercase or lowercase does not matter.
1027
.PN XParseColor
1028
returns nonzero if the name is resolved;
1029
otherwise, it returns zero.
1030
.LP
1031
.PN XParseColor
1032
can generate a
1033
.PN BadColor
1034
error.
1035
.LP
1036
.sp
1037
To map a color name to a value in an arbitrary color space, use
1038
.PN XcmsLookupColor .
1039
.IN "Color" "naming"
1040
.IN "XcmsLookupColor" "" "@DEF@"
1041
.sM
1042
.FD 0
1043
Status XcmsLookupColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor_string\fP\^, \fIcolor_exact_return\fP\^, \fIcolor_screen_return\fP\^,
1044
.br
1045
\fIresult_format\fP\^)
1046
.br
1047
Display *\fIdisplay\fP\^;
1048
.br
1049
Colormap \fIcolormap\fP\^;
1050
.br
1051
char *\fIcolor_string\fP\^;
1052
.br
1053
XcmsColor *\fIcolor_exact_return\fP\^, *\fIcolor_screen_return\fP\^;
1054
.br
1055
XcmsColorFormat \fIresult_format\fP\^;
1056
.FN
1057
.IP \fIdisplay\fP 1i
1058
Specifies the connection to the X server.
1059
.IP \fIcolormap\fP 1i
1060
Specifies the colormap.
1061
.ds St
1062
.IP \fIcolor_string\fP 1i
1063
Specifies the color string\*(St.
1064
.IP \fIcolor_exact_return\fP 1i
1065
Returns the color specification parsed from the color string
1066
or parsed from the corresponding string found in a color-name database.
1067
.IP \fIcolor_screen_return\fP 1i
1068
Returns the color that can be reproduced on the screen.
1069
.IP \fIresult_format\fP 1i
1070
Specifies the color format for the returned color
1071
specifications (color_screen_return and color_exact_return arguments).
1072
If the format is
1073
.PN XcmsUndefinedFormat
1074
and the color string contains a
1075
numerical color specification,
1076
the specification is returned in the format used in that numerical
1077
color specification.
1078
If the format is
1079
.PN XcmsUndefinedFormat
1080
and the color string contains a color name,
1081
the specification is returned in the format used
1082
to store the color in the database.
1083
.LP
1084
.eM
1085
The
1086
.PN XcmsLookupColor
1087
function looks up the string name of a color with respect to the screen
1088
associated with the specified colormap.
1089
It returns both the exact color values and
1090
the closest values provided by the screen
1091
with respect to the visual type of the specified colormap.
1092
The values are returned in the format specified by result_format.
1093
If the color name is not in the Host Portable Character Encoding,
1094
the result is implementation-dependent.
1095
Use of uppercase or lowercase does not matter.
1096
.PN XcmsLookupColor
1097
returns
1098
.PN XcmsSuccess
1099
or
1100
.PN XcmsSuccessWithCompression
1101
if the name is resolved; otherwise, it returns
1102
.PN XcmsFailure .
1103
If
1104
.PN XcmsSuccessWithCompression
1105
is returned, the color specification returned in
1106
color_screen_return is the result of gamut compression.
1107
.NH 2
1108
Allocating and Freeing Color Cells
1109
.XS
1110
\*(SN Allocating and Freeing Color Cells
1111
.XE
1112
.LP
1113
There are two ways of allocating color cells:
1114
explicitly as read-only entries, one pixel value at a time,
1115
or read/write,
1116
where you can allocate a number of color cells and planes simultaneously.
1117
.IN "Read-only colormap cells"
1118
A read-only cell has its RGB value set by the server.
1119
.IN "Read/write colormap cells"
1120
Read/write cells do not have defined colors initially;
1121
functions described in the next section must be used to store values into them.
1122
Although it is possible for any client to store values into a read/write
1123
cell allocated by another client,
1124
read/write cells normally should be considered private to the client
1125
that allocated them.
1126
.LP
1127
Read-only colormap cells are shared among clients.
1128
The server counts each allocation and freeing of the cell by clients.
1129
When the last client frees a shared cell, the cell is finally deallocated.
1130
If a single client allocates the same read-only cell multiple
1131
times, the server counts each such allocation, not just the first one.
1132
.LP
1133
.sp
1134
To allocate a read-only color cell with an RGB value, use
1135
.PN XAllocColor .
1136
.IN "Allocation" "read-only colormap cells"
1137
.IN "Read-only colormap cells" "allocating"
1138
.IN "Color" "allocation"
1139
.IN "XAllocColor" "" "@DEF@"
1140
.sM
1141
.FD 0
1142
Status XAllocColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIscreen_in_out\fP\^)
1143
.br
1144
Display *\fIdisplay\fP\^;
1145
.br
1146
Colormap \fIcolormap\fP\^;
1147
.br
1148
XColor *\fIscreen_in_out\fP\^;
1149
.FN
1150
.IP \fIdisplay\fP 1i
1151
Specifies the connection to the X server.
1152
.IP \fIcolormap\fP 1i
1153
Specifies the colormap.
1154
.IP \fIscreen_in_out\fP 1i
1155
Specifies and returns the values actually used in the colormap.
1156
.LP
1157
.eM
1158
The
1159
.PN XAllocColor
1160
function allocates a read-only colormap entry corresponding to the closest
1161
RGB value supported by the hardware.
1162
.PN XAllocColor
1163
returns the pixel value of the color closest to the specified
1164
RGB elements supported by the hardware
1165
and returns the RGB value actually used.
1166
The corresponding colormap cell is read-only.
1167
In addition,
1168
.PN XAllocColor
1169
returns nonzero if it succeeded or zero if it failed.
1170
.IN "Color map"
1171
.IN "Color" "allocation"
1172
.IN "Allocation" "colormap"
1173
.IN "read-only colormap cells"
1174
Multiple clients that request the same effective RGB value can be assigned
1175
the same read-only entry, thus allowing entries to be shared.
1176
When the last client deallocates a shared cell, it is deallocated.
1177
.PN XAllocColor
1178
does not use or affect the flags in the
1179
.PN XColor
1180
structure.
1181
.LP
1182
.PN XAllocColor
1183
can generate a
1184
.PN BadColor
1185
error.
1186
.EQ
1187
delim %%
1188
.EN
1189
.LP
1190
.sp
1191
To allocate a read-only color cell with a color in arbitrary format, use
1192
.PN XcmsAllocColor .
1193
.IN "Allocation" "read-only colormap cells"
1194
.IN "Read-only colormap cells" "allocating"
1195
.IN "Color" "allocation"
1196
.IN "XcmsAllocColor" "" "@DEF@"
1197
.sM
1198
.FD 0
1199
Status XcmsAllocColor\^(\^\fIdisplay\fP\^, \fIcolormap\fP\^, \fIcolor_in_out\fP\^, \fIresult_format\fP\^)
1200
.br
1201
Display *\fIdisplay\fP\^;
1202
.br
1203
Colormap \fIcolormap\fP\^;
1204
.br
1205
XcmsColor *\fIcolor_in_out\fP\^;
1206
.br
1207
XcmsColorFormat \fIresult_format\fP\^;
1208
.FN
1209
.IP \fIdisplay\fP 1i
1210
Specifies the connection to the X server.
1211
.IP \fIcolormap\fP 1i
1212
Specifies the colormap.
1213
.IP \fIcolor_in_out\fP 1i
1214
Specifies the color to allocate and returns the pixel and color
1215
that is actually used in the colormap.
1216
.IP \fIresult_format\fP 1i
1217
Specifies the color format for the returned color specification.
1218
.LP
1219
.eM
1220
The
1221
.PN XcmsAllocColor
1222
function is similar to
1223
.PN XAllocColor
1224
except the color can be specified in any format.
1225
The
1226
.PN XcmsAllocColor
1227
function ultimately calls
1228
.PN XAllocColor
1229
to allocate a read-only color cell (colormap entry) with the specified color.
1230
.PN XcmsAllocColor
1231
first converts the color specified
1232
to an RGB value and then passes this to
1233
.PN XAllocColor .
1234
.PN XcmsAllocColor
1235
returns the pixel value of the color cell and the color specification
1236
actually allocated.
1237
This returned color specification is the result of converting the RGB value
1238
returned by
1239
.PN XAllocColor
1240
into the format specified with the result_format argument.
1241
If there is no interest in a returned color specification,
1242
unnecessary computation can be bypassed if result_format is set to
1243
.PN XcmsRGBFormat .
1244
The corresponding colormap cell is read-only.
1245
If this routine returns
1246
.PN XcmsFailure ,
1247
the color_in_out color specification is left unchanged.
1248
.LP
1249
.PN XcmsAllocColor
1250
can generate a
1251
.PN BadColor
1252
error.
1253
.LP
1254
.sp
1255
To allocate a read-only color cell using a color name and return the closest
1256
color supported by the hardware in RGB format, use
1257
.PN XAllocNamedColor .
1258
.IN "Allocation" "read-only colormap cells"
1259
.IN "Read-only colormap cells" "allocating"
1260
.IN "Color" "naming"
1261
.IN "Color" "allocation"
1262
.IN "XAllocNamedColor" "" "@DEF@"
1263
.sM
1264
.FD 0
1265
Status XAllocNamedColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \
1266
\fIcolor_name\fP\^, \fIscreen_def_return\fP\^, \fIexact_def_return\fP\^)
1267
.br
1268
Display *\fIdisplay\fP\^;
1269
.br
1270
Colormap \fIcolormap\fP\^;
1271
.br
1272
char *\fIcolor_name\fP\^;
1273
.br
1274
XColor *\fIscreen_def_return\fP\^, *\fIexact_def_return\fP\^;
1275
.FN
1276
.IP \fIdisplay\fP 1i
1277
Specifies the connection to the X server.
1278
.IP \fIcolormap\fP 1i
1279
Specifies the colormap.
1280
.IP \fIcolor_name\fP 1i
1281
Specifies the color name string (for example, red) whose color
1282
definition structure you want returned.
1283
.IP \fIscreen_def_return\fP 1i
1284
Returns the closest RGB values provided by the hardware.
1285
.IP \fIexact_def_return\fP 1i
1286
Returns the exact RGB values.
1287
.LP
1288
.eM
1289
The
1290
.PN XAllocNamedColor
1291
function looks up the named color with respect to the screen that is
1292
associated with the specified colormap.
1293
It returns both the exact database definition and
1294
the closest color supported by the screen.
1295
The allocated color cell is read-only.
1296
The pixel value is returned in screen_def_return.
1297
If the color name is not in the Host Portable Character Encoding,
1298
the result is implementation-dependent.
1299
Use of uppercase or lowercase does not matter.
1300
If screen_def_return and exact_def_return
1301
point to the same structure, the pixel field will be set correctly,
1302
but the color values are undefined.
1303
.PN XAllocNamedColor
1304
returns nonzero if a cell is allocated;
1305
otherwise, it returns zero.
1306
.LP
1307
.PN XAllocNamedColor
1308
can generate a
1309
.PN BadColor
1310
error.
1311
.LP
1312
.sp
1313
To allocate a read-only color cell using a color name and return the closest
1314
color supported by the hardware in an arbitrary format, use
1315
.PN XcmsAllocNamedColor .
1316
.IN "Allocation" "read-only colormap cells"
1317
.IN "Read-only colormap cells" "allocating"
1318
.IN "Color" "naming"
1319
.IN "Color" "allocation"
1320
.IN "XcmsAllocNamedColor" "" "@DEF@"
1321
.sM
1322
.FD 0
1323
Status XcmsAllocNamedColor\^(\^\fIdisplay\fP\^, \fIcolormap\fP\^, \fIcolor_string\fP\^, \fIcolor_screen_return\fP\^, \fIcolor_exact_return\fP\^,
1324
.br
1325
\fIresult_format\fP\^)
1326
.br
1327
Display *\fIdisplay\fP\^;
1328
.br
1329
Colormap \fIcolormap\fP\^;
1330
.br
1331
char *\fIcolor_string\fP\^;
1332
.br
1333
XcmsColor *\fIcolor_screen_return\fP\^;
1334
.br
1335
XcmsColor *\fIcolor_exact_return\fP\^;
1336
.br
1337
XcmsColorFormat \fIresult_format\fP\^;
1338
.FN
1339
.IP \fIdisplay\fP 1i
1340
Specifies the connection to the X server.
1341
.IP \fIcolormap\fP 1i
1342
Specifies the colormap.
1343
.ds St \ whose color definition structure is to be returned
1344
.IP \fIcolor_string\fP 1i
1345
Specifies the color string\*(St.
1346
.IP \fIcolor_screen_return\fP 1i
1347
Returns the pixel value of the color cell and color specification
1348
that actually is stored for that cell.
1349
.IP \fIcolor_exact_return\fP 1i
1350
Returns the color specification parsed from the color string
1351
or parsed from the corresponding string found in a color-name database.
1352
.IP \fIresult_format\fP 1i
1353
Specifies the color format for the returned color
1354
specifications (color_screen_return and color_exact_return arguments).
1355
If the format is
1356
.PN XcmsUndefinedFormat
1357
and the color string contains a
1358
numerical color specification,
1359
the specification is returned in the format used in that numerical
1360
color specification.
1361
If the format is
1362
.PN XcmsUndefinedFormat
1363
and the color string contains a color name,
1364
the specification is returned in the format used
1365
to store the color in the database.
1366
.LP
1367
.eM
1368
The
1369
.PN XcmsAllocNamedColor
1370
function is similar to
1371
.PN XAllocNamedColor
1372
except that the color returned can be in any format specified.
1373
This function
1374
ultimately calls
1375
.PN XAllocColor
1376
to allocate a read-only color cell with
1377
the color specified by a color string.
1378
The color string is parsed into an
1379
.PN XcmsColor
1380
structure (see
1381
.PN XcmsLookupColor ),
1382
converted
1383
to an RGB value, and finally passed to
1384
.PN XAllocColor .
1385
If the color name is not in the Host Portable Character Encoding,
1386
the result is implementation-dependent.
1387
Use of uppercase or lowercase does not matter.
1388
.LP
1389
This function returns both the color specification as a result
1390
of parsing (exact specification) and the actual color specification
1391
stored (screen specification).
1392
This screen specification is the result of converting the RGB value
1393
returned by
1394
.PN XAllocColor
1395
into the format specified in result_format.
1396
If there is no interest in a returned color specification,
1397
unnecessary computation can be bypassed if result_format is set to
1398
.PN XcmsRGBFormat .
1399
If color_screen_return and color_exact_return
1400
point to the same structure, the pixel field will be set correctly,
1401
but the color values are undefined.
1402
.LP
1403
.PN XcmsAllocNamedColor
1404
can generate a
1405
.PN BadColor
1406
error.
1407
.LP
1408
.sp
1409
To allocate read/write color cell and color plane combinations for a
1410
.PN PseudoColor
1411
model, use
1412
.PN XAllocColorCells .
1413
.IN "Read/write colormap cells" "allocating"
1414
.IN "Allocation" "read/write colormap cells"
1415
.IN "Color" "allocation"
1416
.IN "XAllocColorCells" "" "@DEF@"
1417
.sM
1418
.FD 0
1419
Status XAllocColorCells\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcontig\fP\^, \
1420
\fIplane_masks_return\fP\^, \fInplanes\fP\^,
1421
.br
1422
\fIpixels_return\fP\^, \fInpixels\fP\^)
1423
.br
1424
Display *\fIdisplay\fP\^;
1425
.br
1426
Colormap \fIcolormap\fP\^;
1427
.br
1428
Bool \fIcontig\fP\^;
1429
.br
1430
unsigned long \fIplane_masks_return\fP[\^]\^;
1431
.br
1432
unsigned int \fInplanes\fP\^;
1433
.br
1434
unsigned long \fIpixels_return\fP[\^]\^;
1435
.br
1436
unsigned int \fInpixels\fP\^;
1437
.FN
1438
.IP \fIdisplay\fP 1i
1439
Specifies the connection to the X server.
1440
.IP \fIcolormap\fP 1i
1441
Specifies the colormap.
1442
.IP \fIcontig\fP 1i
1443
Specifies a Boolean value that indicates whether the planes must be contiguous.
1444
.IP \fIplane_mask_return\fP 1i
1445
Returns an array of plane masks.
1446
.\" *** JIM: NEED MORE INFO FOR THIS. ***
1447
.IP \fInplanes\fP 1i
1448
Specifies the number of plane masks that are to be returned in the plane masks
1449
array.
1450
.IP \fIpixels_return\fP 1i
1451
Returns an array of pixel values.
1452
.IP \fInpixels\fP 1i
1453
Specifies the number of pixel values that are to be returned in the
1454
pixels_return array.
1455
.LP
1456
.eM
1457
.EQ
1458
delim %%
1459
.EN
1460
The
1461
.PN XAllocColorCells
1462
function allocates read/write color cells.
1463
The number of colors must be positive and the number of planes nonnegative,
1464
or a
1465
.PN BadValue
1466
error results.
1467
If ncolors and nplanes are requested,
1468
then ncolors pixels
1469
and nplane plane masks are returned.
1470
No mask will have any bits set to 1 in common with
1471
any other mask or with any of the pixels.
1472
By ORing together each pixel with zero or more masks,
1473
ncolors * %2 sup nplanes% distinct pixels can be produced.
1474
All of these are
1475
allocated writable by the request.
1476
For
1477
.PN GrayScale
1478
or
1479
.PN PseudoColor ,
1480
each mask has exactly one bit set to 1.
1481
For
1482
.PN DirectColor ,
1483
each has exactly three bits set to 1.
1484
If contig is
1485
.PN True
1486
and if all masks are ORed
1487
together, a single contiguous set of bits set to 1 will be formed for
1488
.PN GrayScale
1489
or
1490
.PN PseudoColor
1491
and three contiguous sets of bits set to 1 (one within each
1492
pixel subfield) for
1493
.PN DirectColor .
1494
The RGB values of the allocated
1495
entries are undefined.
1496
.PN XAllocColorCells
1497
returns nonzero if it succeeded or zero if it failed.
1498
.LP
1499
.PN XAllocColorCells
1500
can generate
1501
.PN BadColor
1502
and
1503
.PN BadValue
1504
errors.
1505
.LP
1506
.sp
1507
To allocate read/write color resources for a
1508
.PN DirectColor
1509
model, use
1510
.PN XAllocColorPlanes .
1511
.IN "Read/write colormap planes" "allocating"
1512
.IN "Allocation" "read/write colormap planes"
1513
.IN "Color" "allocation"
1514
.IN "XAllocColorPlanes" "" "@DEF@"
1515
.sM
1516
.FD 0
1517
Status XAllocColorPlanes\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcontig\fP\^, \fIpixels_return\fP\^, \fIncolors\fP\^, \fInreds\fP\^, \fIngreens\fP\^,
1518
.br
1519
\fInblues\fP\^, \fIrmask_return\fP\^, \fIgmask_return\fP\^, \fIbmask_return\fP\^)
1520
.br
1521
Display *\fIdisplay\fP\^;
1522
.br
1523
Colormap \fIcolormap\fP\^;
1524
.br
1525
Bool \fIcontig\fP\^;
1526
.br
1527
unsigned long \fIpixels_return\fP[\^]\^;
1528
.br
1529
int \fIncolors\fP\^;
1530
.br
1531
int \fInreds\fP\^, \fIngreens\fP\^, \fInblues\fP\^;
1532
.br
1533
unsigned long *\fIrmask_return\fP\^, *\fIgmask_return\fP\^, *\fIbmask_return\fP\^;
1534
.FN
1535
.IP \fIdisplay\fP 1i
1536
Specifies the connection to the X server.
1537
.IP \fIcolormap\fP 1i
1538
Specifies the colormap.
1539
.IP \fIcontig\fP 1i
1540
Specifies a Boolean value that indicates whether the planes must be contiguous.
1541
.IP \fIpixels_return\fP 1i
1542
Returns an array of pixel values.
1543
.PN XAllocColorPlanes
1544
returns the pixel values in this array.
1545
.IP \fIncolors\fP 1i
1546
Specifies the number of pixel values that are to be returned in the
1547
pixels_return array.
1548
.IP \fInreds\fP 1i
1549
.br
1550
.ns
1551
.IP \fIngreens\fP 1i
1552
.br
1553
.ns
1554
.IP \fInblues\fP 1i
1555
.br
1556
.ns
1557
Specify the number of red, green, and blue planes.
1558
The value you pass must be nonnegative.
1559
.IP \fIrmask_return\fP 1i
1560
.br
1561
.ns
1562
.IP \fIgmask_return\fP 1i
1563
.br
1564
.ns
1565
.IP \fIbmask_return\fP 1i
1566
Return bit masks for the red, green, and blue planes.
1567
.LP
1568
.eM
1569
.EQ
1570
delim %%
1571
.EN
1572
The specified ncolors must be positive;
1573
and nreds, ngreens, and nblues must be nonnegative,
1574
or a
1575
.PN BadValue
1576
error results.
1577
If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested,
1578
ncolors pixels are returned; and the masks have nreds, ngreens, and
1579
nblues bits set to 1, respectively.
1580
If contig is
1581
.PN True ,
1582
each mask will have
1583
a contiguous set of bits set to 1.
1584
No mask will have any bits set to 1 in common with
1585
any other mask or with any of the pixels.
1586
For
1587
.PN DirectColor ,
1588
each mask
1589
will lie within the corresponding pixel subfield.
1590
By ORing together
1591
subsets of masks with each pixel value,
1592
ncolors * %2 sup (nreds+ngreens+nblues)% distinct pixel values can be produced.
1593
All of these are allocated by the request.
1594
However, in the
1595
colormap, there are only ncolors * %2 sup nreds% independent red entries,
1596
ncolors * %2 sup ngreens% independent green entries,
1597
and ncolors * %2 sup nblues% independent blue entries.
1598
This is true even for
1599
.PN PseudoColor .
1600
When the colormap entry of a pixel
1601
value is changed (using
1602
.PN XStoreColors ,
1603
.PN XStoreColor ,
1604
or
1605
.PN XStoreNamedColor ),
1606
the pixel is decomposed according to the masks,
1607
and the corresponding independent entries are updated.
1608
.PN XAllocColorPlanes
1609
returns nonzero if it succeeded or zero if it failed.
1610
.LP
1611
.PN XAllocColorPlanes
1612
can generate
1613
.PN BadColor
1614
and
1615
.PN BadValue
1616
errors.
1617
.LP
1618
.sp
1619
.IN "Freeing" "colors"
1620
To free colormap cells, use
1621
.PN XFreeColors .
1622
.IN "XFreeColors" "" "@DEF@"
1623
.IN "Color" "deallocation"
1624
.sM
1625
.FD 0
1626
XFreeColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIpixels\fP\^, \fInpixels\fP\^, \fIplanes\fP\^)
1627
.br
1628
Display *\fIdisplay\fP\^;
1629
.br
1630
Colormap \fIcolormap\fP\^;
1631
.br
1632
unsigned long \fIpixels\fP\^[\^];
1633
.br
1634
int \fInpixels\fP\^;
1635
.br
1636
unsigned long \fIplanes\fP\^;
1637
.FN
1638
.IP \fIdisplay\fP 1i
1639
Specifies the connection to the X server.
1640
.IP \fIcolormap\fP 1i
1641
Specifies the colormap.
1642
.ds Pi that map to the cells in the specified colormap
1643
.IP \fIpixels\fP 1i
1644
Specifies an array of pixel values \*(Pi.
1645
.IP \fInpixels\fP 1i
1646
Specifies the number of pixels.
1647
.IP \fIplanes\fP 1i
1648
Specifies the planes you want to free.
1649
.LP
1650
.eM
1651
The
1652
.PN XFreeColors
1653
function frees the cells represented by pixels whose values are in the
1654
pixels array.
1655
The planes argument should not have any bits set to 1 in common with any of the
1656
pixels.
1657
The set of all pixels is produced by ORing together subsets of
1658
the planes argument with the pixels.
1659
The request frees all of these pixels that
1660
were allocated by the client (using
1661
.IN XAllocColor
1662
.IN XAllocNamedColor
1663
.IN XAllocColorCells
1664
.IN XAllocColorPlanes
1665
.PN XAllocColor ,
1666
.PN XAllocNamedColor ,
1667
.PN XAllocColorCells ,
1668
and
1669
.PN XAllocColorPlanes ).
1670
Note that freeing an
1671
individual pixel obtained from
1672
.PN XAllocColorPlanes
1673
may not actually allow
1674
it to be reused until all of its related pixels are also freed.
1675
Similarly,
1676
a read-only entry is not actually freed until it has been freed by all clients,
1677
and if a client allocates the same read-only entry multiple times,
1678
it must free the entry that many times before the entry is actually freed.
1679
.LP
1680
All specified pixels that are allocated by the client in the colormap are
1681
freed, even if one or more pixels produce an error.
1682
If a specified pixel is not a valid index into the colormap, a
1683
.PN BadValue
1684
error results.
1685
If a specified pixel is not allocated by the
1686
client (that is, is unallocated or is only allocated by another client)
1687
or if the colormap was created with all entries writable (by passing
1688
.PN AllocAll
1689
to
1690
.PN XCreateColormap ),
1691
a
1692
.PN BadAccess
1693
error results.
1694
If more than one pixel is in error,
1695
the one that gets reported is arbitrary.
1696
.LP
1697
.PN XFreeColors
1698
can generate
1699
.PN BadAccess ,
1700
.PN BadColor ,
1701
and
1702
.PN BadValue
1703
errors.
1704
.NH 2
1705
Modifying and Querying Colormap Cells
1706
.XS
1707
\*(SN Modifying and Querying Colormap Cells
1708
.XE
1709
.LP
1710
.sp
1711
To store an RGB value in a single colormap cell, use
1712
.PN XStoreColor .
1713
.IN "Color" "storing"
1714
.IN "XStoreColor" "" "@DEF@"
1715
.sM
1716
.FD 0
1717
XStoreColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^)
1718
.br
1719
Display *\fIdisplay\fP\^;
1720
.br
1721
Colormap \fIcolormap\fP\^;
1722
.br
1723
XColor *\fIcolor\fP\^;
1724
.FN
1725
.IP \fIdisplay\fP 1i
1726
Specifies the connection to the X server.
1727
.IP \fIcolormap\fP 1i
1728
Specifies the colormap.
1729
.IP \fIcolor\fP 1i
1730
Specifies the pixel and RGB values.
1731
.LP
1732
.eM
1733
The
1734
.PN XStoreColor
1735
function changes the colormap entry of the pixel value specified in the
1736
pixel member of the
1737
.PN XColor
1738
structure.
1739
You specified this value in the
1740
pixel member of the
1741
.PN XColor
1742
structure.
1743
This pixel value must be a read/write cell and a valid index into the colormap.
1744
If a specified pixel is not a valid index into the colormap,
1745
a
1746
.PN BadValue
1747
error results.
1748
.PN XStoreColor
1749
also changes the red, green, and/or blue color components.
1750
You specify which color components are to be changed by setting
1751
.PN DoRed ,
1752
.PN DoGreen ,
1753
and/or
1754
.PN DoBlue
1755
in the flags member of the
1756
.PN XColor
1757
structure.
1758
If the colormap is an installed map for its screen,
1759
the changes are visible immediately.
1760
.LP
1761
.PN XStoreColor
1762
can generate
1763
.PN BadAccess ,
1764
.PN BadColor ,
1765
and
1766
.PN BadValue
1767
errors.
1768
.LP
1769
.sp
1770
To store multiple RGB values in multiple colormap cells, use
1771
.PN XStoreColors .
1772
.IN "Color" "storing"
1773
.IN "XStoreColors" "" "@DEF@"
1774
.sM
1775
.FD 0
1776
XStoreColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^, \fIncolors\fP\^)
1777
.br
1778
Display *\fIdisplay\fP\^;
1779
.br
1780
Colormap \fIcolormap\fP\^;
1781
.br
1782
XColor \fIcolor\fP\^[\^]\^;
1783
.br
1784
int \fIncolors\fP\^;
1785
.FN
1786
.IP \fIdisplay\fP 1i
1787
Specifies the connection to the X server.
1788
.IP \fIcolormap\fP 1i
1789
Specifies the colormap.
1790
.IP \fIcolor\fP 1i
1791
Specifies an array of color definition structures to be stored.
1792
.IP \fIncolors\fP 1i
1793
.\"Specifies the number of color definition structures.
1794
Specifies the number of
1795
.PN XColor
1796
structures in the color definition array.
1797
.LP
1798
.eM
1799
The
1800
.PN XStoreColors
1801
function changes the colormap entries of the pixel values
1802
specified in the pixel members of the
1803
.PN XColor
1804
structures.
1805
You specify which color components are to be changed by setting
1806
.PN DoRed ,
1807
.PN DoGreen ,
1808
and/or
1809
.PN DoBlue
1810
in the flags member of the
1811
.PN XColor
1812
structures.
1813
If the colormap is an installed map for its screen, the
1814
changes are visible immediately.
1815
.PN XStoreColors
1816
changes the specified pixels if they are allocated writable in the colormap
1817
by any client, even if one or more pixels generates an error.
1818
If a specified pixel is not a valid index into the colormap, a
1819
.PN BadValue
1820
error results.
1821
If a specified pixel either is unallocated or is allocated read-only, a
1822
.PN BadAccess
1823
error results.
1824
If more than one pixel is in error,
1825
the one that gets reported is arbitrary.
1826
.LP
1827
.PN XStoreColors
1828
can generate
1829
.PN BadAccess ,
1830
.PN BadColor ,
1831
and
1832
.PN BadValue
1833
errors.
1834
.LP
1835
.sp
1836
To store a color of arbitrary format in a single colormap cell, use
1837
.PN XcmsStoreColor .
1838
.IN "Color" "storing"
1839
.IN "XcmsStoreColor" "" "@DEF@"
1840
.sM
1841
.FD 0
1842
Status XcmsStoreColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^)
1843
.br
1844
Display *\fIdisplay\fP\^;
1845
.br
1846
Colormap \fIcolormap\fP\^;
1847
.br
1848
XcmsColor *\fIcolor\fP\^;
1849
.FN
1850
.IP \fIdisplay\fP 1i
1851
Specifies the connection to the X server.
1852
.IP \fIcolormap\fP 1i
1853
Specifies the colormap.
1854
.IP \fIcolor\fP 1i
1855
Specifies the color cell and the color to store.
1856
Values specified in this
1857
.PN XcmsColor
1858
structure remain unchanged on return.
1859
.LP
1860
.eM
1861
The
1862
.PN XcmsStoreColor
1863
function converts the color specified in the
1864
.PN XcmsColor
1865
structure into RGB values.
1866
It then uses this RGB specification in an
1867
.PN XColor
1868
structure, whose three flags
1869
.Pn ( DoRed ,
1870
.PN DoGreen ,
1871
and
1872
.PN DoBlue )
1873
are set, in a call to
1874
.PN XStoreColor
1875
to change the color cell specified by the pixel member of the
1876
.PN XcmsColor
1877
structure.
1878
This pixel value must be a valid index for the specified colormap,
1879
and the color cell specified by the pixel value must be a read/write cell.
1880
If the pixel value is not a valid index, a
1881
.PN BadValue
1882
error results.
1883
If the color cell is unallocated or is allocated read-only, a
1884
.PN BadAccess
1885
error results.
1886
If the colormap is an installed map for its screen,
1887
the changes are visible immediately.
1888
.LP
1889
Note that
1890
.PN XStoreColor
1891
has no return value; therefore, an
1892
.PN XcmsSuccess
1893
return value from this function indicates that the conversion
1894
to RGB succeeded and the call to
1895
.PN XStoreColor
1896
was made.
1897
To obtain the actual color stored, use
1898
.PN XcmsQueryColor .
1899
Because of the screen's hardware limitations or gamut compression,
1900
the color stored in the colormap may not be identical
1901
to the color specified.
1902
.LP
1903
.PN XcmsStoreColor
1904
can generate
1905
.PN BadAccess ,
1906
.PN BadColor ,
1907
and
1908
.PN BadValue
1909
errors.
1910
.LP
1911
.sp
1912
To store multiple colors of arbitrary format in multiple colormap cells, use
1913
.PN XcmsStoreColors .
1914
.IN "Color" "storing"
1915
.IN "XcmsStoreColors" "" "@DEF@"
1916
.sM
1917
.FD 0
1918
Status XcmsStoreColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolors\fP\^, \fIncolors\fP\^, \fIcompression_flags_return\fP\^)
1919
.br
1920
Display *\fIdisplay\fP\^;
1921
.br
1922
Colormap \fIcolormap\fP\^;
1923
.br
1924
XcmsColor \fIcolors\fP\^[\^]\^;
1925
.br
1926
int \fIncolors\fP\^;
1927
.br
1928
Bool \fIcompression_flags_return\fP\^[\^]\^;
1929
.FN
1930
.IP \fIdisplay\fP 1i
1931
Specifies the connection to the X server.
1932
.IP \fIcolormap\fP 1i
1933
Specifies the colormap.
1934
.IP \fIcolors\fP 1i
1935
Specifies the color specification array of
1936
.PN XcmsColor
1937
structures, each specifying a color cell and the color to store in that
1938
cell.
1939
Values specified in the array remain unchanged upon return.
1940
.IP \fIncolors\fP 1i
1941
Specifies the number of
1942
.PN XcmsColor
1943
structures in the color-specification array.
1944
.IP \fIcompression_flags_return\fP 1i
1945
Returns an array of Boolean values indicating compression status.
1946
If a non-NULL pointer is supplied,
1947
each element of the array is set to
1948
.PN True
1949
if the corresponding color was compressed and
1950
.PN False
1951
otherwise.
1952
Pass NULL if the compression status is not useful.
1953
.LP
1954
.eM
1955
The
1956
.PN XcmsStoreColors
1957
function converts the colors specified in the array of
1958
.PN XcmsColor
1959
structures into RGB values and then uses these RGB specifications in
1960
.PN XColor
1961
structures, whose three flags
1962
.Pn ( DoRed ,
1963
.PN DoGreen ,
1964
and
1965
.PN DoBlue )
1966
are set, in a call to
1967
.PN XStoreColors
1968
to change the color cells specified by the pixel member of the corresponding
1969
.PN XcmsColor
1970
structure.
1971
Each pixel value must be a valid index for the specified colormap,
1972
and the color cell specified by each pixel value must be a read/write cell.
1973
If a pixel value is not a valid index, a
1974
.PN BadValue
1975
error results.
1976
If a color cell is unallocated or is allocated read-only, a
1977
.PN BadAccess
1978
error results.
1979
If more than one pixel is in error,
1980
the one that gets reported is arbitrary.
1981
If the colormap is an installed map for its screen,
1982
the changes are visible immediately.
1983
.LP
1984
Note that
1985
.PN XStoreColors
1986
has no return value; therefore, an
1987
.PN XcmsSuccess
1988
return value from this function indicates that conversions
1989
to RGB succeeded and the call to
1990
.PN XStoreColors
1991
was made.
1992
To obtain the actual colors stored, use
1993
.PN XcmsQueryColors .
1994
Because of the screen's hardware limitations or gamut compression,
1995
the colors stored in the colormap may not be identical
1996
to the colors specified.
1997
.LP
1998
.PN XcmsStoreColors
1999
can generate
2000
.PN BadAccess ,
2001
.PN BadColor ,
2002
and
2003
.PN BadValue
2004
errors.
2005
.LP
2006
.sp
2007
To store a color specified by name in a single colormap cell, use
2008
.PN XStoreNamedColor .
2009
.IN "Color" "storing"
2010
.IN "Color" "naming"
2011
.IN "XStoreNamedColor" "" "@DEF@"
2012
.sM
2013
.FD 0
2014
XStoreNamedColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^, \fIpixel\fP\^, \fIflags\fP\^)
2015
.br
2016
Display *\fIdisplay\fP\^;
2017
.br
2018
Colormap \fIcolormap\fP\^;
2019
.br
2020
char *\^\fIcolor\fP\^;
2021
.br
2022
unsigned long \fIpixel\fP\^;
2023
.br
2024
int \fIflags\fP\^;
2025
.FN
2026
.IP \fIdisplay\fP 1i
2027
Specifies the connection to the X server.
2028
.IP \fIcolormap\fP 1i
2029
Specifies the colormap.
2030
.IP \fIcolor\fP 1i
2031
Specifies the color name string (for example, red).
2032
.IP \fIpixel\fP 1i
2033
Specifies the entry in the colormap.
2034
.IP \fIflags\fP 1i
2035
Specifies which red, green, and blue components are set.
2036
.LP
2037
.eM
2038
The
2039
.PN XStoreNamedColor
2040
function looks up the named color with respect to the screen associated with
2041
the colormap and stores the result in the specified colormap.
2042
The pixel argument determines the entry in the colormap.
2043
The flags argument determines which of the red, green, and blue components
2044
are set.
2045
You can set this member to the
2046
bitwise inclusive OR of the bits
2047
.PN DoRed ,
2048
.PN DoGreen ,
2049
and
2050
.PN DoBlue .
2051
If the color name is not in the Host Portable Character Encoding,
2052
the result is implementation-dependent.
2053
Use of uppercase or lowercase does not matter.
2054
If the specified pixel is not a valid index into the colormap, a
2055
.PN BadValue
2056
error results.
2057
If the specified pixel either is unallocated or is allocated read-only, a
2058
.PN BadAccess
2059
error results.
2060
.LP
2061
.PN XStoreNamedColor
2062
can generate
2063
.PN BadAccess ,
2064
.PN BadColor ,
2065
.PN BadName ,
2066
and
2067
.PN BadValue
2068
errors.
2069
.LP
2070
The
2071
.PN XQueryColor
2072
and
2073
.PN XQueryColors
2074
functions take pixel values in the pixel member of
2075
.PN XColor
2076
structures and store in the structures the RGB values for those
2077
pixels from the specified colormap.
2078
The values returned for an unallocated entry are undefined.
2079
These functions also set the flags member in the
2080
.PN XColor
2081
structure to all three colors.
2082
If a pixel is not a valid index into the specified colormap, a
2083
.PN BadValue
2084
error results.
2085
If more than one pixel is in error,
2086
the one that gets reported is arbitrary.
2087
.LP
2088
.sp
2089
To query the RGB value of a single colormap cell, use
2090
.PN XQueryColor .
2091
.IN "Color" "querying"
2092
.IN "XQueryColor" "" "@DEF@"
2093
.sM
2094
.FD 0
2095
XQueryColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIdef_in_out\fP\^)
2096
.br
2097
Display *\fIdisplay\fP\^;
2098
.br
2099
Colormap \fIcolormap\fP\^;
2100
.br
2101
XColor *\fIdef_in_out\fP\^;
2102
.FN
2103
.IP \fIdisplay\fP 1i
2104
Specifies the connection to the X server.
2105
.IP \fIcolormap\fP 1i
2106
Specifies the colormap.
2107
.IP \fIdef_in_out\fP 1i
2108
Specifies and returns the RGB values for the pixel specified in the structure.
2109
.LP
2110
.eM
2111
The
2112
.PN XQueryColor
2113
function returns the current RGB value for the pixel in the
2114
.PN XColor
2115
structure and sets the
2116
.PN DoRed ,
2117
.PN DoGreen ,
2118
and
2119
.PN DoBlue
2120
flags.
2121
.LP
2122
.PN XQueryColor
2123
can generate
2124
.PN BadColor
2125
and
2126
.PN BadValue
2127
errors.
2128
.LP
2129
.sp
2130
To query the RGB values of multiple colormap cells, use
2131
.PN XQueryColors .
2132
.IN "Color" "querying"
2133
.IN "XQueryColors" "" "@DEF@"
2134
.sM
2135
.FD 0
2136
XQueryColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIdefs_in_out\fP\^, \fIncolors\fP\^)
2137
.br
2138
Display *\fIdisplay\fP\^;
2139
.br
2140
Colormap \fIcolormap\fP\^;
2141
.br
2142
XColor \fIdefs_in_out\fP[\^]\^;
2143
.br
2144
int \fIncolors\fP\^;
2145
.FN
2146
.IP \fIdisplay\fP 1i
2147
Specifies the connection to the X server.
2148
.IP \fIcolormap\fP 1i
2149
Specifies the colormap.
2150
.IP \fIdefs_in_out\fP 1i
2151
Specifies and returns an array of color definition structures for the pixel
2152
specified in the structure.
2153
.IP \fIncolors\fP 1i
2154
.\"Specifies the number of color definition structures.
2155
Specifies the number of
2156
.PN XColor
2157
structures in the color definition array.
2158
.LP
2159
.eM
2160
The
2161
.PN XQueryColors
2162
function returns the RGB value for each pixel in each
2163
.PN XColor
2164
structure and sets the
2165
.PN DoRed ,
2166
.PN DoGreen ,
2167
and
2168
.PN DoBlue
2169
flags in each structure.
2170
2171
.LP
2172
.PN XQueryColors
2173
can generate
2174
.PN BadColor
2175
and
2176
.PN BadValue
2177
errors.
2178
.sp
2179
.LP
2180
To query the color of a single colormap cell in an arbitrary format, use
2181
.PN XcmsQueryColor .
2182
.IN "Color" "querying"
2183
.IN "XcmsQueryColor" "" "@DEF@"
2184
.sM
2185
.FD 0
2186
Status XcmsQueryColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor_in_out\fP\^, \fIresult_format\fP\^)
2187
.br
2188
Display *\fIdisplay\fP\^;
2189
.br
2190
Colormap \fIcolormap\fP\^;
2191
.br
2192
XcmsColor *\fIcolor_in_out\fP\^;
2193
.br
2194
XcmsColorFormat \fIresult_format\fP\^;
2195
.FN
2196
.IP \fIdisplay\fP 1i
2197
Specifies the connection to the X server.
2198
.IP \fIcolormap\fP 1i
2199
Specifies the colormap.
2200
.IP \fIcolor_in_out\fP 1i
2201
Specifies the pixel member that indicates the color cell to query.
2202
The color specification stored for the color cell is returned in this
2203
.PN XcmsColor
2204
structure.
2205
.IP \fIresult_format\fP 1i
2206
Specifies the color format for the returned color specification.
2207
.LP
2208
.eM
2209
The
2210
.PN XcmsQueryColor
2211
function obtains the RGB value
2212
for the pixel value in the pixel member of the specified
2213
.PN XcmsColor
2214
structure and then
2215
converts the value to the target format as
2216
specified by the result_format argument.
2217
If the pixel is not a valid index in the specified colormap, a
2218
.PN BadValue
2219
error results.
2220
.LP
2221
.PN XcmsQueryColor
2222
can generate
2223
.PN BadColor
2224
and
2225
.PN BadValue
2226
errors.
2227
.sp
2228
.LP
2229
To query the color of multiple colormap cells in an arbitrary format, use
2230
.PN XcmsQueryColors .
2231
.IN "Color" "querying"
2232
.IN "XcmsQueryColors" "" "@DEF@"
2233
.sM
2234
.FD 0
2235
Status XcmsQueryColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIresult_format\fP\^)
2236
.br
2237
Display *\fIdisplay\fP\^;
2238
.br
2239
Colormap \fIcolormap\fP\^;
2240
.br
2241
XcmsColor \fIcolors_in_out\fP\^[\^]\^;
2242
.br
2243
unsigned int \fIncolors\fP\^;
2244
.br
2245
XcmsColorFormat \fIresult_format\fP\^;
2246
.FN
2247
.IP \fIdisplay\fP 1i
2248
Specifies the connection to the X server.
2249
.IP \fIcolormap\fP 1i
2250
Specifies the colormap.
2251
.IP \fIcolors_in_out\fP 1i
2252
Specifies an array of
2253
.PN XcmsColor
2254
structures, each pixel member indicating the color cell to query.
2255
The color specifications for the color cells are returned in these structures.
2256
.IP \fIncolors\fP 1i
2257
Specifies the number of
2258
.PN XcmsColor
2259
structures in the color-specification array.
2260
.IP \fIresult_format\fP 1i
2261
Specifies the color format for the returned color specification.
2262
.LP
2263
.eM
2264
The
2265
.PN XcmsQueryColors
2266
function obtains the RGB values
2267
for pixel values in the pixel members of
2268
.PN XcmsColor
2269
structures and then
2270
converts the values to the target format as
2271
specified by the result_format argument.
2272
If a pixel is not a valid index into the specified colormap, a
2273
.PN BadValue
2274
error results.
2275
If more than one pixel is in error,
2276
the one that gets reported is arbitrary.
2277
.LP
2278
.PN XcmsQueryColors
2279
can generate
2280
.PN BadColor
2281
and
2282
.PN BadValue
2283
errors.
2284
.NH 2
2285
Color Conversion Context Functions
2286
.XS
2287
\*(SN Color Conversion Context Functions
2288
.XE
2289
.LP
2290
This section describes functions to create, modify,
2291
and query Color Conversion Contexts (CCCs).
2292
.LP
2293
Associated with each colormap is an initial CCC transparently generated by
2294
Xlib.
2295
.IN "Color Conversion Context" "creation"
2296
Therefore, when you specify a colormap as an argument to a function,
2297
you are indirectly specifying a CCC.
2298
.IN "CCC" "of colormap"
2299
.IN "Color Conversion Context" "of colormap"
2300
The CCC attributes that can be modified by the X client are:
2301
.IP \(bu 5
2302
Client White Point
2303
.IP \(bu 5
2304
Gamut compression procedure and client data
2305
.IP \(bu 5
2306
White point adjustment procedure and client data
2307
.LP
2308
The initial values for these attributes are implementation specific.
2309
The CCC attributes for subsequently created CCCs can be defined
2310
by changing the CCC attributes of the default CCC.
2311
.IN "CCC" "default"
2312
.IN "Color Conversion Context" "default"
2313
There is a default CCC associated with each screen.
2314
.NH 3
2315
Getting and Setting the Color Conversion Context of a Colormap
2316
.XS
2317
\*(SN Getting and Setting the Color Conversion Context of a Colormap
2318
.XE
2319
.LP
2320
.sp
2321
To obtain the CCC associated with a colormap, use
2322
.PN XcmsCCCOfColormap .
2323
.IN "XcmsCCCOfColormap" "" "@DEF@"
2324
.IN "Colormap" "CCC of"
2325
.IN "CCC" "of colormap"
2326
.IN "Color Conversion Context" "of colormap"
2327
.sM
2328
.FD 0
2329
XcmsCCC XcmsCCCOfColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
2330
.br
2331
Display *\fIdisplay\fP\^;
2332
.br
2333
Colormap \fIcolormap\fP\^;
2334
.FN
2335
.IP \fIdisplay\fP 1i
2336
Specifies the connection to the X server.
2337
.IP \fIcolormap\fP 1i
2338
Specifies the colormap.
2339
.LP
2340
.eM
2341
The
2342
.PN XcmsCCCOfColormap
2343
function returns the CCC associated with the specified colormap.
2344
Once obtained,
2345
the CCC attributes can be queried or modified.
2346
Unless the CCC associated with the specified colormap is changed with
2347
.PN XcmsSetCCCOfColormap ,
2348
this CCC is used when the specified colormap is used as an argument
2349
to color functions.
2350
.sp
2351
.LP
2352
To change the CCC associated with a colormap, use
2353
.PN XcmsSetCCCOfColormap .
2354
.IN "XcmsSetCCCOfColormap" "" "@DEF@"
2355
.IN "Colormap" "CCC of"
2356
.IN "CCC" "of colormap"
2357
.IN "Color Conversion Context" "of colormap"
2358
.sM
2359
.FD 0
2360
XcmsCCC XcmsSetCCCOfColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIccc\fP\^)
2361
.br
2362
Display *\fIdisplay\fP\^;
2363
.br
2364
Colormap \fIcolormap\fP\^;
2365
.br
2366
XcmsCCC \fIccc\fP\^;
2367
.FN
2368
.IP \fIdisplay\fP 1i
2369
Specifies the connection to the X server.
2370
.IP \fIcolormap\fP 1i
2371
Specifies the colormap.
2372
.IP \fIccc\fP 1i
2373
Specifies the CCC.
2374
.LP
2375
.eM
2376
The
2377
.PN XcmsSetCCCOfColormap
2378
function changes the CCC associated with the specified colormap.
2379
It returns the CCC previously associated with the colormap.
2380
If they are not used again in the application,
2381
CCCs should be freed by calling
2382
.PN XcmsFreeCCC .
2383
Several colormaps may share the same CCC without restriction; this
2384
includes the CCCs generated by Xlib with each colormap. Xlib, however,
2385
creates a new CCC with each new colormap.
2386
.NH 3
2387
Obtaining the Default Color Conversion Context
2388
.XS
2389
\*(SN Obtaining the Default Color Conversion Context
2390
.XE
2391
.LP
2392
You can change the default CCC attributes for subsequently created CCCs
2393
by changing the CCC attributes of the default CCC.
2394
.IN "CCC" "default"
2395
.IN "Color Conversion Context" "default"
2396
A default CCC is associated with each screen.
2397
.sp
2398
.LP
2399
To obtain the default CCC for a screen, use
2400
.PN XcmsDefaultCCC .
2401
.IN "XcmsDefaultCCC" "" "@DEF@"
2402
.IN "Color Conversion Context" "default"
2403
.IN "CCC" "default"
2404
.sM
2405
.FD 0
2406
XcmsCCC XcmsDefaultCCC\^(\^\fIdisplay\fP, \fIscreen_number\fP\^)
2407
.br
2408
Display *\fIdisplay\fP\^;
2409
.br
2410
int \fIscreen_number\fP\^;
2411
.FN
2412
.IP \fIdisplay\fP 1i
2413
Specifies the connection to the X server.
2414
.IP \fIscreen_number\fP 1i
2415
Specifies the appropriate screen number on the host server.
2416
.LP
2417
.eM
2418
The
2419
.PN XcmsDefaultCCC
2420
function returns the default CCC for the specified screen.
2421
Its visual is the default visual of the screen.
2422
Its initial gamut compression and white point
2423
adjustment procedures as well as the associated client data are implementation
2424
specific.
2425
.NH 3
2426
Color Conversion Context Macros
2427
.XS
2428
\*(SN Color Conversion Context Macros
2429
.XE
2430
.LP
2431
Applications should not directly modify any part of the
2432
.PN XcmsCCC .
2433
The following lists the C language macros, their corresponding function
2434
equivalents for other language bindings, and what data they both
2435
can return.
2436
.sp
2437
.LP
2438
.IN "DisplayOfCCC" "" "@DEF@"
2439
.IN "XcmsDisplayOfCCC" "" "@DEF@"
2440
.sM
2441
.FD 0
2442
DisplayOfCCC\^(\^\fIccc\fP\^)
2443
.br
2444
XcmsCCC \fIccc\fP\^;
2445
.sp
2446
Display *XcmsDisplayOfCCC\^(\^\fIccc\fP\^)
2447
.br
2448
XcmsCCC \fIccc\fP\^;
2449
.FN
2450
.IP \fIccc\fP 1i
2451
Specifies the CCC.
2452
.LP
2453
.eM
2454
Both return the display associated with the specified CCC.
2455
.LP
2456
.sp
2457
.IN "VisualOfCCC" "" "@DEF@"
2458
.IN "XcmsVisualOfCCC" "" "@DEF@"
2459
.sM
2460
.FD 0
2461
VisualOfCCC\^(\^\fIccc\fP\^)
2462
.br
2463
XcmsCCC \fIccc\fP\^;
2464
.sp
2465
Visual *XcmsVisualOfCCC\^(\^\fIccc\fP\^)
2466
.br
2467
XcmsCCC \fIccc\fP\^;
2468
.FN
2469
.IP \fIccc\fP 1i
2470
Specifies the CCC.
2471
.LP
2472
.eM
2473
Both return the visual associated with the specified CCC.
2474
.sp
2475
.LP
2476
.IN "ScreenNumberOfCCC" "" "@DEF@"
2477
.IN "XcmsScreenNumberOfCCC" "" "@DEF@"
2478
.sM
2479
.FD 0
2480
ScreenNumberOfCCC\^(\^\fIccc\fP\^)
2481
.br
2482
XcmsCCC \fIccc\fP\^;
2483
.sp
2484
int XcmsScreenNumberOfCCC\^(\^\fIccc\fP\^)
2485
.br
2486
XcmsCCC \fIccc\fP\^;
2487
.FN
2488
.IP \fIccc\fP 1i
2489
Specifies the CCC.
2490
.LP
2491
.eM
2492
Both return the number of the screen associated with the specified CCC.
2493
.sp
2494
.LP
2495
.IN "ScreenWhitePointOfCCC" "" "@DEF@"
2496
.IN "XcmsScreenWhitePointOfCCC" "" "@DEF@"
2497
.sM
2498
.FD 0
2499
ScreenWhitePointOfCCC\^(\^\fIccc\fP\^)
2500
.br
2501
XcmsCCC \fIccc\fP\^;
2502
.sp
2503
XcmsColor *XcmsScreenWhitePointOfCCC\^(\^\fIccc\fP\^)
2504
.br
2505
XcmsCCC \fIccc\fP\^;
2506
.FN
2507
.IP \fIccc\fP 1i
2508
Specifies the CCC.
2509
.LP
2510
.eM
2511
Both return the white point of the screen associated with the specified CCC.
2512
.sp
2513
.LP
2514
.IN "ClientWhitePointOfCCC" "" "@DEF@"
2515
.IN "XcmsClientWhitePointOfCCC" "" "@DEF@"
2516
.sM
2517
.FD 0
2518
ClientWhitePointOfCCC\^(\^\fIccc\fP\^)
2519
.br
2520
XcmsCCC \fIccc\fP\^;
2521
.sp
2522
XcmsColor *XcmsClientWhitePointOfCCC\^(\^\fIccc\fP\^)
2523
.br
2524
XcmsCCC \fIccc\fP\^;
2525
.FN
2526
.IP \fIccc\fP 1i
2527
Specifies the CCC.
2528
.LP
2529
.eM
2530
Both return the Client White Point of the specified CCC.
2531
.NH 3
2532
Modifying Attributes of a Color Conversion Context
2533
.XS
2534
\*(SN Modifying Attributes of a Color Conversion Context
2535
.XE
2536
.LP
2537
To set the Client White Point in the CCC, use
2538
.PN XcmsSetWhitePoint .
2539
.IN "XcmsSetWhitePoint" "" "@DEF@"
2540
.IN "Client White Point" "of Color Conversion Context"
2541
.sM
2542
.FD 0
2543
Status XcmsSetWhitePoint\^(\^\fIccc\fP\^, \fIcolor\fP\^)
2544
.br
2545
XcmsCCC \fIccc\fP\^;
2546
.br
2547
XcmsColor *\fIcolor\fP\^;
2548
.FN
2549
.IP \fIccc\fP 1i
2550
Specifies the CCC.
2551
.ds Co new Client White Point
2552
.IP \fIcolor\fP 1i
2553
Specifies the \*(Co.
2554
.LP
2555
.eM
2556
The
2557
.PN XcmsSetWhitePoint
2558
function changes the Client White Point in the specified CCC.
2559
Note that the pixel member is ignored
2560
and that the color specification is left unchanged upon return.
2561
The format for the new white point must be
2562
.PN XcmsCIEXYZFormat ,
2563
.PN XcmsCIEuvYFormat ,
2564
.PN XcmsCIExyYFormat ,
2565
or
2566
.PN XcmsUndefinedFormat .
2567
If the color argument is NULL, this function sets the format component of the
2568
Client White Point specification to
2569
.PN XcmsUndefinedFormat ,
2570
indicating that the Client White Point is assumed to be the same as the
2571
Screen White Point.
2572
.LP
2573
This function returns nonzero status
2574
if the format for the new white point is valid;
2575
otherwise, it returns zero.
2576
2577
.sp
2578
.LP
2579
To set the gamut compression procedure and corresponding client data
2580
in a specified CCC, use
2581
.PN XcmsSetCompressionProc .
2582
.IN "XcmsSetCompressionProc" "" "@DEF@"
2583
.IN "Gamut compression" "setting in Color Conversion Context"
2584
.IN "Gamut compression" "procedure"
2585
.IN "Gamut compression" "client data"
2586
.sM
2587
.FD 0
2588
XcmsCompressionProc XcmsSetCompressionProc\^(\^\fIccc\fP\^, \fIcompression_proc\fP\^, \fIclient_data\fP\^)
2589
.br
2590
XcmsCCC \fIccc\fP\^;
2591
.br
2592
XcmsCompressionProc \fIcompression_proc\fP\^;
2593
.br
2594
XPointer \fIclient_data\fP\^;
2595
.FN
2596
.IP \fIccc\fP 1i
2597
Specifies the CCC.
2598
.IP \fIcompression_proc\fP 1i
2599
Specifies the gamut compression procedure that is to be applied
2600
when a color lies outside the screen's color gamut.
2601
If NULL is specified and a function using this CCC must convert
2602
a color specification to a device-dependent format and encounters a color
2603
that lies outside the screen's color gamut,
2604
that function will return
2605
.PN XcmsFailure .
2606
.ds Cd the gamut compression procedure
2607
.IP \fIclient_data\fP 1i
2608
Specifies client data for \*(Cd or NULL.
2609
.LP
2610
.eM
2611
The
2612
.PN XcmsSetCompressionProc
2613
function first sets the gamut compression procedure and client data
2614
in the specified CCC with the newly specified procedure and client data
2615
and then returns the old procedure.
2616
.sp
2617
.LP
2618
To set the white point adjustment procedure and corresponding client data
2619
in a specified CCC, use
2620
.PN XcmsSetWhiteAdjustProc .
2621
.IN "XcmsSetWhiteAdjustProc" "" "@DEF@"
2622
.IN "White point adjustment" "setting in Color Conversion Context"
2623
.IN "White point adjustment" "procedure"
2624
.IN "White point adjustment" "client data"
2625
.FD 0
2626
.sM
2627
XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc\^(\^\fIccc\fP\^, \fIwhite_adjust_proc\fP\^, \fIclient_data\fP\^)
2628
.br
2629
XcmsCCC \fIccc\fP\^;
2630
.br
2631
XcmsWhiteAdjustProc \fIwhite_adjust_proc\fP\^;
2632
.br
2633
XPointer \fIclient_data\fP\^;
2634
.FN
2635
.IP \fIccc\fP 1i
2636
Specifies the CCC.
2637
.IP \fIwhite_adjust_proc\fP 1i
2638
Specifies the white point adjustment procedure.
2639
.ds Cd the white point adjustment procedure
2640
.IP \fIclient_data\fP 1i
2641
Specifies client data for \*(Cd or NULL.
2642
.LP
2643
.eM
2644
The
2645
.PN XcmsSetWhiteAdjustProc
2646
function first sets the white point adjustment procedure and client data
2647
in the specified CCC with the newly specified procedure and client data
2648
and then returns the old procedure.
2649
.NH 3
2650
Creating and Freeing a Color Conversion Context
2651
.XS
2652
\*(SN Creating and Freeing a Color Conversion Context
2653
.XE
2654
.LP
2655
You can explicitly create a CCC within your application by calling
2656
.PN XcmsCreateCCC .
2657
These created CCCs can then be used by those functions that explicitly
2658
call for a CCC argument.
2659
Old CCCs that will not be used by the application should be freed using
2660
.PN XcmsFreeCCC .
2661
.sp
2662
.LP
2663
To create a CCC, use
2664
.PN XcmsCreateCCC .
2665
.IN "XcmsCreateCCC" "" "@DEF@"
2666
.IN "Color Conversion Context" "creation"
2667
.IN "CCC" "creation"
2668
.sM
2669
.FD 0
2670
XcmsCCC XcmsCreateCCC\^(\^\fIdisplay\fP, \fIscreen_number\fP\^, \fIvisual\fP\^, \fIclient_white_point\fP\^, \fIcompression_proc\fP\^,
2671
.br
2672
\fIcompression_client_data\fP\^, \fIwhite_adjust_proc\fP\^, \fIwhite_adjust_client_data\fP\^)
2673
.br
2674
Display *\fIdisplay\fP\^;
2675
.br
2676
int \fIscreen_number\fP\^;
2677
.br
2678
Visual *\fIvisual\fP\^;
2679
.br
2680
XcmsColor *\fIclient_white_point\fP\^;
2681
.br
2682
XcmsCompressionProc \fIcompression_proc\fP\^;
2683
.br
2684
XPointer \fIcompression_client_data\fP\^;
2685
.br
2686
XcmsWhiteAdjustProc \fIwhite_adjust_proc\fP\^;
2687
.br
2688
XPointer \fIwhite_adjust_client_data\fP\^;
2689
.FN
2690
.IP \fIdisplay\fP 1i
2691
Specifies the connection to the X server.
2692
.IP \fIscreen_number\fP 1i
2693
Specifies the appropriate screen number on the host server.
2694
.IP \fIvisual\fP 1i
2695
Specifies the visual type.
2696
.IP \fIclient_white_point\fP 1i
2697
Specifies the Client White Point.
2698
If NULL is specified,
2699
the Client White Point is to be assumed to be the same as the
2700
Screen White Point.
2701
Note that the pixel member is ignored.
2702
.IP \fIcompression_proc\fP 1i
2703
Specifies the gamut compression procedure that is to be applied
2704
when a color lies outside the screen's color gamut.
2705
If NULL is specified and a function using this CCC must convert
2706
a color specification to a device-dependent format and encounters a color
2707
that lies outside the screen's color gamut,
2708
that function will return
2709
.PN XcmsFailure .
2710
.IP \fIcompression_client_data\fP 1i
2711
Specifies client data for use by the gamut compression procedure or NULL.
2712
.IP \fIwhite_adjust_proc\fP 1i
2713
Specifies the white adjustment procedure that is to be applied
2714
when the Client White Point differs from the Screen White Point.
2715
NULL indicates that no white point adjustment is desired.
2716
.IP \fIwhite_adjust_client_data\fP 1i
2717
Specifies client data for use with the white point adjustment procedure or NULL.
2718
.LP
2719
.eM
2720
The
2721
.PN XcmsCreateCCC
2722
function creates a CCC for the specified display, screen, and visual.
2723
.LP
2724
.sp
2725
To free a CCC, use
2726
.PN XcmsFreeCCC .
2727
.IN "XcmsFreeCCC" "" "@DEF@"
2728
.IN "Color Conversion Context" "freeing"
2729
.IN "CCC" "freeing"
2730
.sM
2731
.FD 0
2732
void XcmsFreeCCC\^(\^\fIccc\fP\^)
2733
.br
2734
XcmsCCC \fIccc\fP\^;
2735
.FN
2736
.IP \fIccc\fP 1i
2737
Specifies the CCC.
2738
.LP
2739
.eM
2740
The
2741
.PN XcmsFreeCCC
2742
function frees the memory used for the specified CCC.
2743
Note that default CCCs and those currently associated with colormaps
2744
are ignored.
2745
.NH 2
2746
Converting between Color Spaces
2747
.XS
2748
\*(SN Converting between Color Spaces
2749
.XE
2750
.LP
2751
.sp
2752
To convert an array of color specifications in arbitrary color formats
2753
to a single destination format, use
2754
.PN XcmsConvertColors .
2755
.IN "Color conversion"
2756
.IN "Color" "conversion"
2757
.IN "XcmsConvertColors" "" "@DEF@"
2758
.sM
2759
.FD 0
2760
Status XcmsConvertColors\^(\^\fIccc\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fItarget_format\fP\^, \fIcompression_flags_return\fP\^)
2761
.br
2762
XcmsCCC \fIccc\fP\^;
2763
.br
2764
XcmsColor \fIcolors_in_out\fP\^[\^]\^;
2765
.br
2766
unsigned int \fIncolors\fP\^;
2767
.br
2768
XcmsColorFormat \fItarget_format\fP\^;
2769
.br
2770
Bool \fIcompression_flags_return\fP\^[\^]\^;
2771
.FN
2772
.IP \fIccc\fP 1i
2773
Specifies the CCC.
2774
If conversion is between device-independent color spaces only
2775
(for example, TekHVC to CIELuv),
2776
the CCC is necessary only to specify the Client White Point.
2777
.IP \fIcolors_in_out\fP 1i
2778
Specifies an array of color specifications.
2779
Pixel members are ignored and remain unchanged upon return.
2780
.IP \fIncolors\fP 1i
2781
Specifies the number of
2782
.PN XcmsColor
2783
structures in the color-specification array.
2784
.IP \fItarget_format\fP 1i
2785
Specifies the target color specification format.
2786
.IP \fIcompression_flags_return\fP 1i
2787
Returns an array of Boolean values indicating compression status.
2788
If a non-NULL pointer is supplied,
2789
each element of the array is set to
2790
.PN True
2791
if the corresponding color was compressed and
2792
.PN False
2793
otherwise.
2794
Pass NULL if the compression status is not useful.
2795
.LP
2796
.eM
2797
The
2798
.PN XcmsConvertColors
2799
function converts the color specifications in the specified array of
2800
.PN XcmsColor
2801
structures from their current format to a single target format,
2802
using the specified CCC.
2803
When the return value is
2804
.PN XcmsFailure ,
2805
the contents of the color specification array are left unchanged.
2806
.LP
2807
The array may contain a mixture of color specification formats
2808
(for example, 3 CIE XYZ, 2 CIE Luv, and so on).
2809
When the array contains both device-independent and
2810
device-dependent color specifications and the target_format argument specifies
2811
a device-dependent format (for example,
2812
.PN XcmsRGBiFormat ,
2813
.PN XcmsRGBFormat ),
2814
all specifications are converted to CIE XYZ format and then to the target
2815
device-dependent format.
2816
.NH 2
2817
Callback Functions
2818
.XS
2819
\*(SN Callback Functions
2820
.XE
2821
.LP
2822
This section describes the gamut compression and white point
2823
adjustment callbacks.
2824
.LP
2825
The gamut compression procedure specified in the CCC
2826
is called when an attempt to convert a color specification from
2827
.PN XcmsCIEXYZ
2828
to a device-dependent format (typically
2829
.PN XcmsRGBi )
2830
results in a color that lies outside the screen's color gamut.
2831
If the gamut compression procedure requires client data, this data is passed
2832
via the gamut compression client data in the CCC.
2833
.LP
2834
During color specification conversion between device-independent
2835
and device-dependent color spaces,
2836
if a white point adjustment procedure is specified in the CCC,
2837
it is triggered when the Client White Point and Screen White Point differ.
2838
If required, the client data is obtained from the CCC.
2839
.NH 3
2840
Prototype Gamut Compression Procedure
2841
.XS
2842
\*(SN Prototype Gamut Compression Procedure
2843
.XE
2844
.LP
2845
The gamut compression callback interface must adhere to the
2846
following:
2847
.IN "XcmsCompressionProc" "" "@DEF@"
2848
.sM
2849
.FD 0
2850
typedef Status (*\^XcmsCompressionProc\^)\^(\^\fIccc\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIindex\fP\^, \fIcompression_flags_return\fP\^)
2851
.br
2852
XcmsCCC \fIccc\fP\^;
2853
.br
2854
XcmsColor \fIcolors_in_out[]\fP\^;
2855
.br
2856
unsigned int \fIncolors\fP\^;
2857
.br
2858
unsigned int \fIindex\fP\^;
2859
.br
2860
Bool \fIcompression_flags_return[]\fP\^;
2861
.FN
2862
.IP \fIccc\fP 1i
2863
Specifies the CCC.
2864
.IP \fIcolors_in_out\fP 1i
2865
Specifies an array of color specifications.
2866
Pixel members should be ignored and must remain unchanged upon return.
2867
.IP \fIncolors\fP 1i
2868
Specifies the number of
2869
.PN XcmsColor
2870
structures in the color-specification array.
2871
.IP \fIindex\fP 1i
2872
Specifies the index into the array of
2873
.PN XcmsColor
2874
structures for the encountered color specification that lies outside the
2875
screen's color gamut.
2876
Valid values are 0 (for the first element) to ncolors \- 1.
2877
.IP \fIcompression_flags_return\fP 1i
2878
Returns an array of Boolean values for indicating compression status.
2879
If a non-NULL pointer is supplied
2880
and a color at a given index is compressed, then
2881
.PN True
2882
should be stored at the corresponding index in this array;
2883
otherwise, the array should not be modified.
2884
.LP
2885
.eM
2886
When implementing a gamut compression procedure, consider the following
2887
rules and assumptions:
2888
.IP \(bu 5
2889
The gamut compression procedure can attempt to compress one or multiple
2890
specifications at a time.
2891
.IP \(bu 5
2892
When called, elements 0 to index \- 1 in the color specification
2893
array can be assumed to fall within the screen's color gamut.
2894
In addition, these color specifications are already in some device-dependent
2895
format (typically
2896
.PN XcmsRGBi ).
2897
If any modifications are made to these color specifications,
2898
they must be in their initial device-dependent format upon return.
2899
.IP \(bu 5
2900
When called, the element in the color specification array specified
2901
by the index argument contains the color specification outside the
2902
screen's color gamut encountered by the calling routine.
2903
In addition, this color specification can be assumed to be in
2904
.PN XcmsCIEXYZ .
2905
Upon return, this color specification must be in
2906
.PN XcmsCIEXYZ .
2907
.IP \(bu 5
2908
When called, elements from index to ncolors \- 1
2909
in the color specification array may or may not fall within the
2910
screen's color gamut.
2911
In addition, these color specifications can be assumed to be in
2912
.PN XcmsCIEXYZ .
2913
If any modifications are made to these color specifications,
2914
they must be in
2915
.PN XcmsCIEXYZ
2916
upon return.
2917
.IP \(bu 5
2918
The color specifications passed to the gamut compression procedure
2919
have already been adjusted to the Screen White Point.
2920
This means that at this point the color specification's white point
2921
is the Screen White Point.
2922
.IP \(bu 5
2923
If the gamut compression procedure uses a device-independent color space not
2924
initially accessible for use in the color management system, use
2925
.PN XcmsAddColorSpace
2926
to ensure that it is added.
2927
.NH 3
2928
Supplied Gamut Compression Procedures
2929
.XS
2930
\*(SN Supplied Gamut Compression Procedures
2931
.XE
2932
.LP
2933
The following equations are useful in describing gamut compression
2934
functions:
2935
.EQ
2936
delim %%
2937
.EN
2938
.LP
2939
.Ds 0
2940
%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%
2941
2942
%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%
2943
2944
%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%
2945
2946
%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
2947
.De
2948
.LP
2949
The gamut compression callback procedures provided by Xlib are as follows:
2950
.IP \(bu 5
2951
.PN XcmsCIELabClipL
2952
.IP
2953
This brings the encountered out-of-gamut color specification into the
2954
screen's color gamut by reducing or increasing CIE metric lightness (L*)
2955
in the CIE L*a*b* color space until the color is within the gamut.
2956
If the Psychometric Chroma of the color specification
2957
is beyond maximum for the Psychometric Hue Angle,
2958
then while maintaining the same Psychometric Hue Angle,
2959
the color will be clipped to the CIE L*a*b* coordinates of maximum
2960
Psychometric Chroma.
2961
See
2962
.PN XcmsCIELabQueryMaxC .
2963
No client data is necessary.
2964
.IP \(bu 5
2965
.PN XcmsCIELabClipab
2966
.IP
2967
This brings the encountered out-of-gamut color specification into the
2968
screen's color gamut by reducing Psychometric Chroma,
2969
while maintaining Psychometric Hue Angle,
2970
until the color is within the gamut.
2971
No client data is necessary.
2972
.IP \(bu 5
2973
.PN XcmsCIELabClipLab
2974
.IP
2975
This brings the encountered out-of-gamut color specification into the
2976
screen's color gamut by replacing it with CIE L*a*b* coordinates
2977
that fall within the color gamut while maintaining the original
2978
Psychometric Hue
2979
Angle and whose vector to the original coordinates is the shortest attainable.
2980
No client data is necessary.
2981
.IP \(bu 5
2982
.PN XcmsCIELuvClipL
2983
.IP
2984
This brings the encountered out-of-gamut color specification into the
2985
screen's color gamut by reducing or increasing CIE metric lightness (L*)
2986
in the CIE L*u*v* color space until the color is within the gamut.
2987
If the Psychometric Chroma of the color specification
2988
is beyond maximum for the Psychometric Hue Angle,
2989
then, while maintaining the same Psychometric Hue Angle,
2990
the color will be clipped to the CIE L*u*v* coordinates of maximum
2991
Psychometric Chroma.
2992
See
2993
.PN XcmsCIELuvQueryMaxC .
2994
No client data is necessary.
2995
.IP \(bu 5
2996
.PN XcmsCIELuvClipuv
2997
.IP
2998
This brings the encountered out-of-gamut color specification into the
2999
screen's color gamut by reducing
3000
Psychometric Chroma, while maintaining Psychometric Hue Angle,
3001
until the color is within the gamut.
3002
No client data is necessary.
3003
.IP \(bu 5
3004
.PN XcmsCIELuvClipLuv
3005
.IP
3006
This brings the encountered out-of-gamut color specification into the
3007
screen's color gamut by replacing it with CIE L*u*v* coordinates
3008
that fall within the color gamut while maintaining the original
3009
Psychometric Hue
3010
Angle and whose vector to the original coordinates is the shortest attainable.
3011
No client data is necessary.
3012
.IP \(bu 5
3013
.PN XcmsTekHVCClipV
3014
.IP
3015
This brings the encountered out-of-gamut color specification into the
3016
screen's color gamut by reducing or increasing the Value dimension
3017
in the TekHVC color space until the color is within the gamut.
3018
If Chroma of the color specification is beyond maximum for the particular Hue,
3019
then, while maintaining the same Hue,
3020
the color will be clipped to the Value and Chroma coordinates
3021
that represent maximum Chroma for that particular Hue.
3022
No client data is necessary.
3023
.IP \(bu 5
3024
.PN XcmsTekHVCClipC
3025
.IP
3026
This brings the encountered out-of-gamut color specification into the
3027
screen's color gamut by reducing the Chroma dimension
3028
in the TekHVC color space until the color is within the gamut.
3029
No client data is necessary.
3030
.IP \(bu 5
3031
.PN XcmsTekHVCClipVC
3032
.IP
3033
This brings the encountered out-of-gamut color specification into the
3034
screen's color gamut by replacing it with TekHVC coordinates
3035
that fall within the color gamut while maintaining the original Hue
3036
and whose vector to the original coordinates is the shortest attainable.
3037
No client data is necessary.
3038
.NH 3
3039
Prototype White Point Adjustment Procedure
3040
.XS
3041
\*(SN Prototype White Point Adjustment Procedure
3042
.XE
3043
.LP
3044
The white point adjustment procedure interface must adhere to the following:
3045
.IN "XcmsWhiteAdjustProc" "" "@DEF@"
3046
.sM
3047
.FD 0
3048
typedef Status (*\^XcmsWhiteAdjustProc\^)\^(\^\fIccc\fP\^, \fIinitial_white_point\fP\^, \fItarget_white_point\fP\^, \fItarget_format\fP\^,
3049
.br
3050
\fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIcompression_flags_return\fP\^)
3051
.br
3052
XcmsCCC \fIccc\fP\^;
3053
.br
3054
XcmsColor *\fIinitial_white_point\fP\^;
3055
.br
3056
XcmsColor *\fItarget_white_point\fP\^;
3057
.br
3058
XcmsColorFormat \fItarget_format\fP\^;
3059
.br
3060
XcmsColor \fIcolors_in_out[]\fP\^;
3061
.br
3062
unsigned int \fIncolors\fP\^;
3063
.br
3064
Bool \fIcompression_flags_return[]\fP\^;
3065
.FN
3066
.IP \fIccc\fP 1i
3067
Specifies the CCC.
3068
.IP \fIinitial_white_point\fP 1i
3069
Specifies the initial white point.
3070
.IP \fItarget_white_point\fP 1i
3071
Specifies the target white point.
3072
.IP \fItarget_format\fP 1i
3073
Specifies the target color specification format.
3074
.IP \fIcolors_in_out\fP 1i
3075
Specifies an array of color specifications.
3076
Pixel members should be ignored and must remain unchanged upon return.
3077
.IP \fIncolors\fP 1i
3078
Specifies the number of
3079
.PN XcmsColor
3080
structures in the color-specification array.
3081
.IP \fIcompression_flags_return\fP 1i
3082
Returns an array of Boolean values for indicating compression status.
3083
If a non-NULL pointer is supplied
3084
and a color at a given index is compressed, then
3085
.PN True
3086
should be stored at the corresponding index in this array;
3087
otherwise, the array should not be modified.
3088
.LP
3089
.eM
3090
.NH 3
3091
Supplied White Point Adjustment Procedures
3092
.XS
3093
\*(SN Supplied White Point Adjustment Procedures
3094
.XE
3095
.LP
3096
White point adjustment procedures provided by Xlib are as follows:
3097
.IP \(bu 5
3098
.PN XcmsCIELabWhiteShiftColors
3099
.IP
3100
This uses the CIE L*a*b* color space for adjusting the chromatic character
3101
of colors to compensate for the chromatic differences between the source
3102
and destination white points.
3103
This procedure simply converts the color specifications to
3104
.PN XcmsCIELab
3105
using the source white point and then converts to the target specification
3106
format using the destination's white point.
3107
No client data is necessary.
3108
.IP \(bu 5
3109
.PN XcmsCIELuvWhiteShiftColors
3110
.IP
3111
This uses the CIE L*u*v* color space for adjusting the chromatic character
3112
of colors to compensate for the chromatic differences between the source
3113
and destination white points.
3114
This procedure simply converts the color specifications to
3115
.PN XcmsCIELuv
3116
using the source white point and then converts to the target specification
3117
format using the destination's white point.
3118
No client data is necessary.
3119
.IP \(bu 5
3120
.PN XcmsTekHVCWhiteShiftColors
3121
.IP
3122
This uses the TekHVC color space for adjusting the chromatic character
3123
of colors to compensate for the chromatic differences between the source
3124
and destination white points.
3125
This procedure simply converts the color specifications to
3126
.PN XcmsTekHVC
3127
using the source white point and then converts to the target specification
3128
format using the destination's white point.
3129
An advantage of this procedure over those previously described
3130
is an attempt to minimize hue shift.
3131
No client data is necessary.
3132
.LP
3133
From an implementation point of view,
3134
these white point adjustment procedures convert the color specifications
3135
to a device-independent but white-point-dependent color space
3136
(for example, CIE L*u*v*, CIE L*a*b*, TekHVC) using one white point
3137
and then converting those specifications to the target color space
3138
using another white point.
3139
In other words,
3140
the specification goes in the color space with one white point
3141
but comes out with another white point,
3142
resulting in a chromatic shift based on the chromatic displacement
3143
between the initial white point and target white point.
3144
The CIE color spaces that are assumed to be white-point-independent
3145
are CIE u'v'Y, CIE XYZ, and CIE xyY.
3146
When developing a custom white point adjustment procedure that uses a
3147
device-independent color space not initially accessible for use in the
3148
color management system, use
3149
.PN XcmsAddColorSpace
3150
to ensure that it is added.
3151
.LP
3152
As an example,
3153
if the CCC specifies a white point adjustment procedure
3154
and if the Client White Point and Screen White Point differ, the
3155
.PN XcmsAllocColor
3156
function will use the white point adjustment
3157
procedure twice:
3158
.IP \(bu 5
3159
Once to convert to
3160
.PN XcmsRGB
3161
.IP \(bu 5
3162
A second time to convert from
3163
.PN XcmsRGB
3164
.LP
3165
For example, assume the specification is in
3166
.PN XcmsCIEuvY
3167
and the adjustment procedure is
3168
.PN XcmsCIELuvWhiteShiftColors .
3169
During conversion to
3170
.PN XcmsRGB ,
3171
the call to
3172
.PN XcmsAllocColor
3173
results in the following series of color specification conversions:
3174
.\" Do these need to be font coded?
3175
.IP \(bu 5
3176
From
3177
.PN XcmsCIEuvY
3178
to
3179
.PN XcmsCIELuv
3180
using the Client White Point
3181
.IP \(bu 5
3182
From
3183
.PN XcmsCIELuv
3184
to
3185
.PN XcmsCIEuvY
3186
using the Screen White Point
3187
.IP \(bu 5
3188
From
3189
.PN XcmsCIEuvY
3190
to
3191
.PN XcmsCIEXYZ
3192
(CIE u'v'Y and XYZ are white-point-independent color spaces)
3193
.IP \(bu 5
3194
From
3195
.PN XcmsCIEXYZ
3196
to
3197
.PN XcmsRGBi
3198
.IP \(bu 5
3199
From
3200
.PN XcmsRGBi
3201
to
3202
.PN XcmsRGB
3203
.LP
3204
The resulting RGB specification is passed to
3205
.PN XAllocColor ,
3206
and the RGB
3207
specification returned by
3208
.PN XAllocColor
3209
is converted back to
3210
.PN XcmsCIEuvY
3211
by reversing the color conversion sequence.
3212
.NH 2
3213
Gamut Querying Functions
3214
.XS
3215
\*(SN Gamut Querying Functions
3216
.XE
3217
.LP
3218
This section describes the gamut querying functions that Xlib provides.
3219
These functions allow the client to query the boundary
3220
of the screen's color gamut in terms of the CIE L*a*b*, CIE L*u*v*,
3221
and TekHVC color spaces.
3222
.IN "Gamut querying"
3223
Functions are also provided that allow you to query
3224
the color specification of:
3225
.IP \(bu 5
3226
White (full-intensity red, green, and blue)
3227
.IP \(bu 5
3228
Red (full-intensity red while green and blue are zero)
3229
.IP \(bu 5
3230
Green (full-intensity green while red and blue are zero)
3231
.IP \(bu 5
3232
Blue (full-intensity blue while red and green are zero)
3233
.IP \(bu 5
3234
Black (zero-intensity red, green, and blue)
3235
.LP
3236
The white point associated with color specifications passed to
3237
and returned from these gamut querying
3238
functions is assumed to be the Screen White Point.
3239
.IN "Screen White Point"
3240
This is a reasonable assumption,
3241
because the client is trying to query the screen's color gamut.
3242
.LP
3243
The following naming convention is used for the Max and Min functions:
3244
.LP
3245
.Ds 0
3246
Xcms\fI<color_space>\fPQueryMax\fI<dimensions>\fP
3247
3248
Xcms\fI<color_space>\fPQueryMin\fI<dimensions>\fP
3249
.De
3250
.LP
3251
The <dimensions> consists of a letter or letters
3252
that identify the dimensions of the color space
3253
that are not fixed.
3254
For example,
3255
.PN XcmsTekHVCQueryMaxC
3256
is given a fixed Hue and Value for which maximum Chroma is found.
3257
.NH 3
3258
Red, Green, and Blue Queries
3259
.XS
3260
\*(SN Red, Green, and Blue Queries
3261
.XE
3262
.LP
3263
To obtain the color specification for black
3264
(zero-intensity red, green, and blue), use
3265
.PN XcmsQueryBlack .
3266
.IN "XcmsQueryBlack" "" "@DEF@"
3267
.sM
3268
.FD 0
3269
Status XcmsQueryBlack\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
3270
.br
3271
XcmsCCC \fIccc\fP\^;
3272
.br
3273
XcmsColorFormat \fItarget_format\fP\^;
3274
.br
3275
XcmsColor *\fIcolor_return\fP\^;
3276
.FN
3277
.IP \fIccc\fP 1i
3278
Specifies the CCC.
3279
The CCC's Client White Point and white point adjustment procedures
3280
are ignored.
3281
.IP \fItarget_format\fP 1i
3282
Specifies the target color specification format.
3283
.ds Cs zero-intensity red, green, and blue
3284
.IP \fIcolor_return\fP 1i
3285
Returns the color specification in the specified target format
3286
for \*(Cs.
3287
The white point associated with the returned
3288
color specification is the Screen White Point.
3289
The value returned in the pixel member is undefined.
3290
.LP
3291
.eM
3292
The
3293
.PN XcmsQueryBlack
3294
function returns the color specification in the specified target format
3295
for zero-intensity red, green, and blue.
3296
.sp
3297
.LP
3298
To obtain the color specification for blue
3299
(full-intensity blue while red and green are zero), use
3300
.PN XcmsQueryBlue .
3301
.IN "XcmsQueryBlue" "" "@DEF@"
3302
.sM
3303
.FD 0
3304
Status XcmsQueryBlue\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
3305
.br
3306
XcmsCCC \fIccc\fP\^;
3307
.br
3308
XcmsColorFormat \fItarget_format\fP\^;
3309
.br
3310
XcmsColor *\fIcolor_return\fP\^;
3311
.FN
3312
.IP \fIccc\fP 1i
3313
Specifies the CCC.
3314
The CCC's Client White Point and white point adjustment procedures
3315
are ignored.
3316
.IP \fItarget_format\fP 1i
3317
Specifies the target color specification format.
3318
.ds Cs full-intensity blue while red and green are zero
3319
.IP \fIcolor_return\fP 1i
3320
Returns the color specification in the specified target format
3321
for \*(Cs.
3322
The white point associated with the returned
3323
color specification is the Screen White Point.
3324
The value returned in the pixel member is undefined.
3325
.LP
3326
.eM
3327
The
3328
.PN XcmsQueryBlue
3329
function returns the color specification in the specified target format
3330
for full-intensity blue while red and green are zero.
3331
.sp
3332
.LP
3333
To obtain the color specification for green
3334
(full-intensity green while red and blue are zero), use
3335
.PN XcmsQueryGreen .
3336
.IN "XcmsQueryGreen" "" "@DEF@"
3337
.sM
3338
.FD 0
3339
Status XcmsQueryGreen\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
3340
.br
3341
XcmsCCC \fIccc\fP\^;
3342
.br
3343
XcmsColorFormat \fItarget_format\fP\^;
3344
.br
3345
XcmsColor *\fIcolor_return\fP\^;
3346
.FN
3347
.IP \fIccc\fP 1i
3348
Specifies the CCC.
3349
The CCC's Client White Point and white point adjustment procedures
3350
are ignored.
3351
.IP \fItarget_format\fP 1i
3352
Specifies the target color specification format.
3353
.ds Cs full-intensity green while red and blue are zero
3354
.IP \fIcolor_return\fP 1i
3355
Returns the color specification in the specified target format
3356
for \*(Cs.
3357
The white point associated with the returned
3358
color specification is the Screen White Point.
3359
The value returned in the pixel member is undefined.
3360
.LP
3361
.eM
3362
The
3363
.PN XcmsQueryGreen
3364
function returns the color specification in the specified target format
3365
for full-intensity green while red and blue are zero.
3366
.sp
3367
.LP
3368
To obtain the color specification for red
3369
(full-intensity red while green and blue are zero), use
3370
.PN XcmsQueryRed .
3371
.IN "XcmsQueryRed" "" "@DEF@"
3372
.sM
3373
.FD 0
3374
Status XcmsQueryRed\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
3375
.br
3376
XcmsCCC \fIccc\fP\^;
3377
.br
3378
XcmsColorFormat \fItarget_format\fP\^;
3379
.br
3380
XcmsColor *\fIcolor_return\fP\^;
3381
.FN
3382
.IP \fIccc\fP 1i
3383
Specifies the CCC.
3384
The CCC's Client White Point and white point adjustment procedures
3385
are ignored.
3386
.IP \fItarget_format\fP 1i
3387
Specifies the target color specification format.
3388
.ds Cs full-intensity red while green and blue are zero
3389
.IP \fIcolor_return\fP 1i
3390
Returns the color specification in the specified target format
3391
for \*(Cs.
3392
The white point associated with the returned
3393
color specification is the Screen White Point.
3394
The value returned in the pixel member is undefined.
3395
.LP
3396
.eM
3397
The
3398
.PN XcmsQueryRed
3399
function returns the color specification in the specified target format
3400
for full-intensity red while green and blue are zero.
3401
.LP
3402
.sp
3403
To obtain the color specification for white
3404
(full-intensity red, green, and blue), use
3405
.PN XcmsQueryWhite .
3406
.IN "XcmsQueryWhite" "" "@DEF@"
3407
.sM
3408
.FD 0
3409
Status XcmsQueryWhite\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
3410
.br
3411
XcmsCCC \fIccc\fP\^;
3412
.br
3413
XcmsColorFormat \fItarget_format\fP\^;
3414
.br
3415
XcmsColor *\fIcolor_return\fP\^;
3416
.FN
3417
.IP \fIccc\fP 1i
3418
Specifies the CCC.
3419
The CCC's Client White Point and white point adjustment procedures
3420
are ignored.
3421
.IP \fItarget_format\fP 1i
3422
Specifies the target color specification format.
3423
.ds Cs full-intensity red, green, and blue
3424
.IP \fIcolor_return\fP 1i
3425
Returns the color specification in the specified target format
3426
for \*(Cs.
3427
The white point associated with the returned
3428
color specification is the Screen White Point.
3429
The value returned in the pixel member is undefined.
3430
.LP
3431
.eM
3432
The
3433
.PN XcmsQueryWhite
3434
function returns the color specification in the specified target format
3435
for full-intensity red, green, and blue.
3436
.NH 3
3437
CIELab Queries
3438
.XS
3439
\*(SN CIELab Queries
3440
.XE
3441
.LP
3442
The following equations are useful in describing the CIELab query functions:
3443
.EQ
3444
delim %%
3445
.EN
3446
.LP
3447
.IN "Psychometric Hue Angle"
3448
.IN "CIE metric lightness"
3449
.IN "Psychometric Chroma"
3450
.IN "Psychometric Chroma" "maximum"
3451
.Ds 0
3452
%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%
3453
3454
%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%
3455
.De
3456
.sp
3457
To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma
3458
for a given Psychometric Hue Angle and CIE metric lightness (L*), use
3459
.PN XcmsCIELabQueryMaxC .
3460
.IN "XcmsCIELabQueryMaxC" "" "@DEF@"
3461
.sM
3462
.FD 0
3463
Status XcmsCIELabQueryMaxC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIL_star\fP\^, \fIcolor_return\fP\^)
3464
.br
3465
XcmsCCC \fIccc\fP\^;
3466
.br
3467
XcmsFloat \fIhue_angle\fP\^;
3468
.br
3469
XcmsFloat \fIL_star\fP\^;
3470
.br
3471
XcmsColor *\fIcolor_return\fP\^;
3472
.FN
3473
.IP \fIccc\fP 1i
3474
Specifies the CCC.
3475
The CCC's Client White Point and white point adjustment procedures
3476
are ignored.
3477
.ds Ha maximum chroma
3478
.IP \fIhue_angle\fP 1i
3479
Specifies the hue angle (in degrees) at which to find \*(Ha.
3480
.ds Ls maximum chroma
3481
.IP \fIL_star\fP 1i
3482
Specifies the lightness (L*) at which to find \*(Ls.
3483
.ds Lc maximum chroma
3484
.ds lC hue angle and lightness
3485
.IP \fIcolor_return\fP 1i
3486
Returns the CIE L*a*b* coordinates of \*(Lc
3487
displayable by the screen for the given \*(lC.
3488
The white point associated with the returned
3489
color specification is the Screen White Point.
3490
The value returned in the pixel member is undefined.
3491
.LP
3492
.eM
3493
The
3494
.PN XcmsCIELabQueryMaxC
3495
function, given a hue angle and lightness,
3496
finds the point of maximum chroma displayable by the screen.
3497
It returns this point in CIE L*a*b* coordinates.
3498
.LP
3499
.sp
3500
To obtain the CIE L*a*b* coordinates of maximum CIE metric lightness (L*)
3501
for a given Psychometric Hue Angle and Psychometric Chroma, use
3502
.PN XcmsCIELabQueryMaxL .
3503
.IN "Psychometric Hue Angle"
3504
.IN "CIE metric lightness"
3505
.IN "CIE metric lightness" "maximum"
3506
.IN "XcmsCIELabQueryMaxL" "" "@DEF@"
3507
.sM
3508
.FD 0
3509
Status XcmsCIELabQueryMaxL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
3510
.br
3511
XcmsCCC \fIccc\fP\^;
3512
.br
3513
XcmsFloat \fIhue_angle\fP\^;
3514
.br
3515
XcmsFloat \fIchroma\fP\^;
3516
.br
3517
XcmsColor *\fIcolor_return\fP\^;
3518
.FN
3519
.IP \fIccc\fP 1i
3520
Specifies the CCC.
3521
The CCC's Client White Point and white point adjustment procedures
3522
are ignored.
3523
.ds Ha maximum lightness
3524
.IP \fIhue_angle\fP 1i
3525
Specifies the hue angle (in degrees) at which to find \*(Ha.
3526
.ds Ch maximum lightness
3527
.IP \fIchroma\fP 1i
3528
Specifies the chroma at which to find \*(Ch.
3529
.ds Lc maximum lightness
3530
.ds lC hue angle and chroma
3531
.IP \fIcolor_return\fP 1i
3532
Returns the CIE L*a*b* coordinates of \*(Lc
3533
displayable by the screen for the given \*(lC.
3534
The white point associated with the returned
3535
color specification is the Screen White Point.
3536
The value returned in the pixel member is undefined.
3537
.LP
3538
.eM
3539
The
3540
.PN XcmsCIELabQueryMaxL
3541
function, given a hue angle and chroma,
3542
finds the point in CIE L*a*b* color space of maximum
3543
lightness (L*) displayable by the screen.
3544
It returns this point in CIE L*a*b* coordinates.
3545
An
3546
.PN XcmsFailure
3547
return value usually indicates that the given chroma
3548
is beyond maximum for the given hue angle.
3549
.sp
3550
.LP
3551
To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma
3552
for a given Psychometric Hue Angle, use
3553
.PN XcmsCIELabQueryMaxLC .
3554
.IN "Psychometric Hue Angle"
3555
.IN "Psychometric Chroma"
3556
.IN "CIE metric lightness"
3557
.IN "Psychometric Chroma" "maximum"
3558
.IN "CIE metric lightness" "maximum"
3559
.IN "XcmsCIELabQueryMaxLC" "" "@DEF@"
3560
.sM
3561
.FD 0
3562
Status XcmsCIELabQueryMaxLC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIcolor_return\fP\^)
3563
.br
3564
XcmsCCC \fIccc\fP\^;
3565
.br
3566
XcmsFloat \fIhue_angle\fP\^;
3567
.br
3568
XcmsColor *\fIcolor_return\fP\^;
3569
.FN
3570
.IP \fIccc\fP 1i
3571
Specifies the CCC.
3572
The CCC's Client White Point and white point adjustment procedures
3573
are ignored.
3574
.ds Ha maximum chroma
3575
.IP \fIhue_angle\fP 1i
3576
Specifies the hue angle (in degrees) at which to find \*(Ha.
3577
.ds Lc maximum chroma
3578
.ds lC hue angle
3579
.IP \fIcolor_return\fP 1i
3580
Returns the CIE L*a*b* coordinates of \*(Lc
3581
displayable by the screen for the given \*(lC.
3582
The white point associated with the returned
3583
color specification is the Screen White Point.
3584
The value returned in the pixel member is undefined.
3585
.LP
3586
.eM
3587
The
3588
.PN XcmsCIELabQueryMaxLC
3589
function, given a hue angle,
3590
finds the point of maximum chroma displayable by the screen.
3591
It returns this point in CIE L*a*b* coordinates.
3592
.sp
3593
.LP
3594
To obtain the CIE L*a*b* coordinates of minimum CIE metric lightness (L*)
3595
for a given Psychometric Hue Angle and Psychometric Chroma, use
3596
.PN XcmsCIELabQueryMinL .
3597
.IN "Psychometric Hue Angle"
3598
.IN "CIE metric lightness"
3599
.IN "CIE metric lightness" "minimum"
3600
.IN "XcmsCIELabQueryMinL" "" "@DEF@"
3601
.sM
3602
.FD 0
3603
Status XcmsCIELabQueryMinL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
3604
.br
3605
XcmsCCC \fIccc\fP\^;
3606
.br
3607
XcmsFloat \fIhue_angle\fP\^;
3608
.br
3609
XcmsFloat \fIchroma\fP\^;
3610
.br
3611
XcmsColor *\fIcolor_return\fP\^;
3612
.FN
3613
.IP \fIccc\fP 1i
3614
Specifies the CCC.
3615
The CCC's Client White Point and white point adjustment procedures
3616
are ignored.
3617
.ds Ha minimum lightness
3618
.IP \fIhue_angle\fP 1i
3619
Specifies the hue angle (in degrees) at which to find \*(Ha.
3620
.ds Ch minimum lightness
3621
.IP \fIchroma\fP 1i
3622
Specifies the chroma at which to find \*(Ch.
3623
.ds Lc minimum lightness
3624
.ds lC hue angle and chroma
3625
.IP \fIcolor_return\fP 1i
3626
Returns the CIE L*a*b* coordinates of \*(Lc
3627
displayable by the screen for the given \*(lC.
3628
The white point associated with the returned
3629
color specification is the Screen White Point.
3630
The value returned in the pixel member is undefined.
3631
.LP
3632
.eM
3633
The
3634
.PN XcmsCIELabQueryMinL
3635
function, given a hue angle and chroma,
3636
finds the point of minimum lightness (L*) displayable by the screen.
3637
It returns this point in CIE L*a*b* coordinates.
3638
An
3639
.PN XcmsFailure
3640
return value usually indicates that the given chroma
3641
is beyond maximum for the given hue angle.
3642
.NH 3
3643
CIELuv Queries
3644
.XS
3645
\*(SN CIELuv Queries
3646
.XE
3647
.LP
3648
The following equations are useful in describing the CIELuv query functions:
3649
.EQ
3650
delim %%
3651
.EN
3652
.LP
3653
.IN "Psychometric Hue Angle"
3654
.IN "CIE metric lightness"
3655
.IN "Psychometric Chroma"
3656
.IN "Psychometric Chroma" "maximum"
3657
.Ds 0
3658
%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%
3659
3660
%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
3661
.De
3662
.sp
3663
.LP
3664
To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma
3665
for a given Psychometric Hue Angle and CIE metric lightness (L*), use
3666
.PN XcmsCIELuvQueryMaxC .
3667
.IN "XcmsCIELuvQueryMaxC" "" "@DEF@"
3668
.sM
3669
.FD 0
3670
Status XcmsCIELuvQueryMaxC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIL_star\fP\^, \fIcolor_return\fP\^)
3671
.br
3672
XcmsCCC \fIccc\fP\^;
3673
.br
3674
XcmsFloat \fIhue_angle\fP\^;
3675
.br
3676
XcmsFloat \fIL_star\fP\^;
3677
.br
3678
XcmsColor *\fIcolor_return\fP\^;
3679
.FN
3680
.IP \fIccc\fP 1i
3681
Specifies the CCC.
3682
The CCC's Client White Point and white point adjustment procedures
3683
are ignored.
3684
.ds Ha maximum chroma
3685
.IP \fIhue_angle\fP 1i
3686
Specifies the hue angle (in degrees) at which to find \*(Ha.
3687
.ds Ls maximum chroma
3688
.IP \fIL_star\fP 1i
3689
Specifies the lightness (L*) at which to find \*(Ls.
3690
.ds Lc maximum chroma
3691
.ds lC hue angle and lightness
3692
.IP \fIcolor_return\fP 1i
3693
Returns the CIE L*u*v* coordinates of \*(Lc
3694
displayable by the screen for the given \*(lC.
3695
The white point associated with the returned
3696
color specification is the Screen White Point.
3697
The value returned in the pixel member is undefined.
3698
.LP
3699
.eM
3700
The
3701
.PN XcmsCIELuvQueryMaxC
3702
function, given a hue angle and lightness,
3703
finds the point of maximum chroma displayable by the screen.
3704
It returns this point in CIE L*u*v* coordinates.
3705
.sp
3706
.LP
3707
To obtain the CIE L*u*v* coordinates of maximum CIE metric lightness (L*)
3708
for a given Psychometric Hue Angle and Psychometric Chroma, use
3709
.PN XcmsCIELuvQueryMaxL .
3710
.IN "Psychometric Hue Angle"
3711
.IN "CIE metric lightness"
3712
.IN "CIE metric lightness" "maximum"
3713
.IN "XcmsCIELuvQueryMaxL" "" "@DEF@"
3714
.sM
3715
.FD 0
3716
Status XcmsCIELuvQueryMaxL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
3717
.br
3718
XcmsCCC \fIccc\fP\^;
3719
.br
3720
XcmsFloat \fIhue_angle\fP\^;
3721
.br
3722
XcmsFloat \fIchroma\fP\^;
3723
.br
3724
XcmsColor *\fIcolor_return\fP\^;
3725
.FN
3726
.IP \fIccc\fP 1i
3727
Specifies the CCC.
3728
The CCC's Client White Point and white point adjustment procedures
3729
are ignored.
3730
.ds Ha maximum lightness
3731
.IP \fIhue_angle\fP 1i
3732
Specifies the hue angle (in degrees) at which to find \*(Ha.
3733
.ds Ls maximum lightness
3734
.IP \fIL_star\fP 1i
3735
Specifies the lightness (L*) at which to find \*(Ls.
3736
.ds Lc maximum lightness
3737
.ds lC hue angle and chroma
3738
.IP \fIcolor_return\fP 1i
3739
Returns the CIE L*u*v* coordinates of \*(Lc
3740
displayable by the screen for the given \*(lC.
3741
The white point associated with the returned
3742
color specification is the Screen White Point.
3743
The value returned in the pixel member is undefined.
3744
.LP
3745
.eM
3746
The
3747
.PN XcmsCIELuvQueryMaxL
3748
function, given a hue angle and chroma,
3749
finds the point in CIE L*u*v* color space of maximum
3750
lightness (L*) displayable by the screen.
3751
It returns this point in CIE L*u*v* coordinates.
3752
An
3753
.PN XcmsFailure
3754
return value usually indicates that the given chroma
3755
is beyond maximum for the given hue angle.
3756
.sp
3757
.LP
3758
To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma
3759
for a given Psychometric Hue Angle, use
3760
.PN XcmsCIELuvQueryMaxLC .
3761
.IN "Psychometric Hue Angle"
3762
.IN "Psychometric Chroma"
3763
.IN "CIE metric lightness"
3764
.IN "Psychometric Chroma" "maximum"
3765
.IN "CIE metric lightness" "maximum"
3766
.IN "XcmsCIELuvQueryMaxLC" "" "@DEF@"
3767
.sM
3768
.FD 0
3769
Status XcmsCIELuvQueryMaxLC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIcolor_return\fP\^)
3770
.br
3771
XcmsCCC \fIccc\fP\^;
3772
.br
3773
XcmsFloat \fIhue_angle\fP\^;
3774
.br
3775
XcmsColor *\fIcolor_return\fP\^;
3776
.FN
3777
.IP \fIccc\fP 1i
3778
Specifies the CCC.
3779
The CCC's Client White Point and white point adjustment procedures
3780
are ignored.
3781
.ds Ha maximum chroma
3782
.IP \fIhue_angle\fP 1i
3783
Specifies the hue angle (in degrees) at which to find \*(Ha.
3784
.ds Lc maximum chroma
3785
.ds lC hue angle
3786
.IP \fIcolor_return\fP 1i
3787
Returns the CIE L*u*v* coordinates of \*(Lc
3788
displayable by the screen for the given \*(lC.
3789
The white point associated with the returned
3790
color specification is the Screen White Point.
3791
The value returned in the pixel member is undefined.
3792
.LP
3793
.eM
3794
The
3795
.PN XcmsCIELuvQueryMaxLC
3796
function, given a hue angle,
3797
finds the point of maximum chroma displayable by the screen.
3798
It returns this point in CIE L*u*v* coordinates.
3799
.sp
3800
.LP
3801
To obtain the CIE L*u*v* coordinates of minimum CIE metric lightness (L*)
3802
for a given Psychometric Hue Angle and Psychometric Chroma, use
3803
.PN XcmsCIELuvQueryMinL .
3804
.IN "Psychometric Hue Angle"
3805
.IN "CIE metric lightness"
3806
.IN "CIE metric lightness" "minimum"
3807
.IN "XcmsCIELuvQueryMinL" "" "@DEF@"
3808
.sM
3809
.FD 0
3810
Status XcmsCIELuvQueryMinL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
3811
.br
3812
XcmsCCC \fIccc\fP\^;
3813
.br
3814
XcmsFloat \fIhue_angle\fP\^;
3815
.br
3816
XcmsFloat \fIchroma\fP\^;
3817
.br
3818
XcmsColor *\fIcolor_return\fP\^;
3819
.FN
3820
.IP \fIccc\fP 1i
3821
Specifies the CCC.
3822
The CCC's Client White Point and white point adjustment procedures
3823
are ignored.
3824
.ds Ha minimum lightness
3825
.IP \fIhue_angle\fP 1i
3826
Specifies the hue angle (in degrees) at which to find \*(Ha.
3827
.ds Ch minimum lightness
3828
.IP \fIchroma\fP 1i
3829
Specifies the chroma at which to find \*(Ch.
3830
.ds Lc minimum lightness
3831
.ds lC hue angle and chroma
3832
.IP \fIcolor_return\fP 1i
3833
Returns the CIE L*u*v* coordinates of \*(Lc
3834
displayable by the screen for the given \*(lC.
3835
The white point associated with the returned
3836
color specification is the Screen White Point.
3837
The value returned in the pixel member is undefined.
3838
.LP
3839
.eM
3840
The
3841
.PN XcmsCIELuvQueryMinL
3842
function, given a hue angle and chroma,
3843
finds the point of minimum lightness (L*) displayable by the screen.
3844
It returns this point in CIE L*u*v* coordinates.
3845
An
3846
.PN XcmsFailure
3847
return value usually indicates that the given chroma
3848
is beyond maximum for the given hue angle.
3849
.NH 3
3850
TekHVC Queries
3851
.XS
3852
\*(SN TekHVC Queries
3853
.XE
3854
.LP
3855
To obtain the maximum Chroma for a given Hue and Value, use
3856
.PN XcmsTekHVCQueryMaxC .
3857
.IN "Chroma"
3858
.IN "Chroma" "maximum"
3859
.IN "XcmsTekHVCQueryMaxC" "" "@DEF@"
3860
.sM
3861
.FD 0
3862
Status XcmsTekHVCQueryMaxC\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIvalue\fP\^, \fIcolor_return\fP\^)
3863
.br
3864
XcmsCCC \fIccc\fP\^;
3865
.br
3866
XcmsFloat \fIhue\fP\^;
3867
.br
3868
XcmsFloat \fIvalue\fP\^;
3869
.br
3870
XcmsColor *\fIcolor_return\fP\^;
3871
.FN
3872
.IP \fIccc\fP 1i
3873
Specifies the CCC.
3874
The CCC's Client White Point and white point adjustment procedures
3875
are ignored.
3876
.ds Hu in which to find the maximum Chroma
3877
.IP \fIhue\fP 1i
3878
Specifies the Hue \*(Hu.
3879
.ds Va maximum Chroma
3880
.IP \fIvalue\fP 1i
3881
Specifies the Value in which to find the \*(Va.
3882
.ds Lc maximum Chroma along with the actual Hue and Value
3883
.ds lC maximum Chroma
3884
.IP \fIcolor_return\fP 1i
3885
Returns the \*(Lc at which the \*(lC was found.
3886
The white point associated with the returned
3887
color specification is the Screen White Point.
3888
The value returned in the pixel member is undefined.
3889
.LP
3890
.eM
3891
The
3892
.PN XcmsTekHVCQueryMaxC
3893
function, given a Hue and Value,
3894
determines the maximum Chroma in TekHVC color space
3895
displayable by the screen.
3896
It returns the maximum Chroma along with the actual Hue
3897
and Value at which the maximum Chroma was found.
3898
.sp
3899
.LP
3900
To obtain the maximum Value for a given Hue and Chroma, use
3901
.PN XcmsTekHVCQueryMaxV .
3902
.IN "Value"
3903
.IN "Value" "maximum"
3904
.IN "XcmsTekHVCQueryMaxV" "" "@DEF@"
3905
.sM
3906
.FD 0
3907
Status XcmsTekHVCQueryMaxV\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
3908
.br
3909
XcmsCCC \fIccc\fP\^;
3910
.br
3911
XcmsFloat \fIhue\fP\^;
3912
.br
3913
XcmsFloat \fIchroma\fP\^;
3914
.br
3915
XcmsColor *\fIcolor_return\fP\^;
3916
.FN
3917
.IP \fIccc\fP 1i
3918
Specifies the CCC.
3919
The CCC's Client White Point and white point adjustment procedures
3920
are ignored.
3921
.ds Hu in which to find the maximum Value
3922
.IP \fIhue\fP 1i
3923
Specifies the Hue \*(Hu.
3924
.ds Ch maximum Value
3925
.IP \fIchroma\fP 1i
3926
Specifies the chroma at which to find \*(Ch.
3927
.ds Lc maximum Value along with the Hue and Chroma
3928
.ds lC maximum Value
3929
.IP \fIcolor_return\fP 1i
3930
Returns the \*(Lc at which the \*(lC was found.
3931
The white point associated with the returned
3932
color specification is the Screen White Point.
3933
The value returned in the pixel member is undefined.
3934
.LP
3935
.eM
3936
The
3937
.PN XcmsTekHVCQueryMaxV
3938
function, given a Hue and Chroma,
3939
determines the maximum Value in TekHVC color space
3940
displayable by the screen.
3941
It returns the maximum Value and the actual Hue and Chroma
3942
at which the maximum Value was found.
3943
.sp
3944
.LP
3945
To obtain the maximum Chroma and Value at which it is reached
3946
for a specified Hue, use
3947
.PN XcmsTekHVCQueryMaxVC .
3948
.IN "Chroma"
3949
.IN "Value"
3950
.IN "Chroma" "maximum"
3951
.IN "Value" "maximum"
3952
.IN "XcmsTekHVCQueryMaxVC" "" "@DEF@"
3953
.sM
3954
.FD 0
3955
Status XcmsTekHVCQueryMaxVC\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIcolor_return\fP\^)
3956
.br
3957
XcmsCCC \fIccc\fP\^;
3958
.br
3959
XcmsFloat \fIhue\fP\^;
3960
.br
3961
XcmsColor *\fIcolor_return\fP\^;
3962
.FN
3963
.IP \fIccc\fP 1i
3964
Specifies the CCC.
3965
The CCC's Client White Point and white point adjustment procedures
3966
are ignored.
3967
.ds Hu in which to find the maximum Chroma
3968
.IP \fIhue\fP 1i
3969
Specifies the Hue \*(Hu.
3970
.ds Lc color specification in \
3971
XcmsTekHVC for the maximum Chroma, the Value at which \
3972
that maximum Chroma is reached, and the actual Hue
3973
.ds lC maximum Chroma
3974
.IP \fIcolor_return\fP 1i
3975
Returns the \*(Lc at which the \*(lC was found.
3976
The white point associated with the returned
3977
color specification is the Screen White Point.
3978
The value returned in the pixel member is undefined.
3979
.LP
3980
.eM
3981
The
3982
.PN XcmsTekHVCQueryMaxVC
3983
function, given a Hue,
3984
determines the maximum Chroma in TekHVC color space displayable by the screen
3985
and the Value at which that maximum Chroma is reached.
3986
It returns the maximum Chroma,
3987
the Value at which that maximum Chroma is reached,
3988
and the actual Hue for which the maximum Chroma was found.
3989
.sp
3990
.LP
3991
To obtain a specified number of TekHVC specifications such that they
3992
contain maximum Values for a specified Hue and the
3993
Chroma at which the maximum Values are reached, use
3994
.PN XcmsTekHVCQueryMaxVSamples .
3995
.IN "Chroma"
3996
.IN "Value"
3997
.IN "Chroma" "maximum"
3998
.IN "Value" "maximum"
3999
.IN "XcmsTekHVCQueryMaxVSamples" "" "@DEF@"
4000
.sM
4001
.FD 0
4002
Status XcmsTekHVCQueryMaxVSamples\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIcolors_return\fP\^, \fInsamples\fP\^)
4003
.br
4004
XcmsCCC \fIccc\fP\^;
4005
.br
4006
XcmsFloat \fIhue\fP\^;
4007
.br
4008
XcmsColor \fIcolors_return[]\fP\^;
4009
.br
4010
unsigned int \fInsamples\fP\^;
4011
.FN
4012
.IP \fIccc\fP 1i
4013
Specifies the CCC.
4014
The CCC's Client White Point and white point adjustment procedures
4015
are ignored.
4016
.ds Hu for maximum Chroma/Value samples
4017
.IP \fIhue\fP 1i
4018
Specifies the Hue \*(Hu.
4019
.IP \fInsamples\fP 1i
4020
Specifies the number of samples.
4021
.IP \fIcolors_return\fP 1i
4022
Returns nsamples of color specifications in XcmsTekHVC
4023
such that the Chroma is the maximum attainable for the Value and Hue.
4024
The white point associated with the returned
4025
color specification is the Screen White Point.
4026
The value returned in the pixel member is undefined.
4027
.LP
4028
.eM
4029
The
4030
.PN XcmsTekHVCQueryMaxVSamples
4031
returns nsamples of maximum Value, the Chroma at which that maximum Value
4032
is reached, and the actual Hue for which the maximum Chroma was found.
4033
These sample points may then be used to plot the maximum Value/Chroma
4034
boundary of the screen's color gamut for the specified Hue in TekHVC color
4035
space.
4036
.sp
4037
.LP
4038
To obtain the minimum Value for a given Hue and Chroma, use
4039
.PN XcmsTekHVCQueryMinV .
4040
.IN "Value"
4041
.IN "Value" "minimum"
4042
.IN "XcmsTekHVCQueryMinV" "" "@DEF@"
4043
.sM
4044
.FD 0
4045
Status XcmsTekHVCQueryMinV\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
4046
.br
4047
XcmsCCC \fIccc\fP\^;
4048
.br
4049
XcmsFloat \fIhue\fP\^;
4050
.br
4051
XcmsFloat \fIchroma\fP\^;
4052
.br
4053
XcmsColor *\fIcolor_return\fP\^;
4054
.FN
4055
.IP \fIccc\fP 1i
4056
Specifies the CCC.
4057
The CCC's Client White Point and white point adjustment procedures
4058
are ignored.
4059
.ds Hu in which to find the minimum Value
4060
.IP \fIhue\fP 1i
4061
Specifies the Hue \*(Hu.
4062
.ds Va minimum Value
4063
.IP \fIvalue\fP 1i
4064
Specifies the Value in which to find the \*(Va.
4065
.ds Lc minimum Value and the actual Hue and Chroma
4066
.ds lC minimum Value
4067
.IP \fIcolor_return\fP 1i
4068
Returns the \*(Lc at which the \*(lC was found.
4069
The white point associated with the returned
4070
color specification is the Screen White Point.
4071
The value returned in the pixel member is undefined.
4072
.LP
4073
.eM
4074
The
4075
.PN XcmsTekHVCQueryMinV
4076
function, given a Hue and Chroma,
4077
determines the minimum Value in TekHVC color space displayable by the screen.
4078
It returns the minimum Value and the actual Hue and Chroma at which
4079
the minimum Value was found.
4080
.NH 2
4081
Color Management Extensions
4082
.XS
4083
\*(SN Color Management Extensions
4084
.XE
4085
.LP
4086
The Xlib color management facilities can be extended in two ways:
4087
.IP \(bu 5
4088
Device-Independent Color Spaces
4089
.IP
4090
Device-independent color spaces that are derivable to CIE XYZ
4091
space can be added using the
4092
.PN XcmsAddColorSpace
4093
function.
4094
.IP \(bu 5
4095
Color Characterization Function Set
4096
.IP
4097
A Color Characterization Function Set consists of
4098
device-dependent color spaces and their functions that
4099
convert between these color spaces and the CIE XYZ
4100
color space, bundled together for a specific class of output devices.
4101
A function set can be added using the
4102
.PN XcmsAddFunctionSet
4103
function.
4104
.NH 3
4105
Color Spaces
4106
.XS
4107
\*(SN Color Spaces
4108
.XE
4109
.LP
4110
The CIE XYZ color space serves as the hub for all
4111
conversions between device-independent and device-dependent color spaces.
4112
Therefore, the knowledge to convert an
4113
.PN XcmsColor
4114
structure to and from CIE XYZ format is associated with each color space.
4115
For example, conversion from CIE L*u*v* to RGB requires the knowledge
4116
to convert from CIE L*u*v* to CIE XYZ and from CIE XYZ to RGB.
4117
This knowledge is stored as an array of functions that,
4118
when applied in series, will convert the
4119
.PN XcmsColor
4120
structure to or from CIE XYZ format.
4121
This color specification conversion mechanism facilitates
4122
the addition of color spaces.
4123
.LP
4124
Of course, when converting between only device-independent color spaces
4125
or only device-dependent color spaces,
4126
shortcuts are taken whenever possible.
4127
For example, conversion from TekHVC to CIE L*u*v* is performed
4128
by intermediate conversion to CIE u*v*Y and then to CIE L*u*v*,
4129
thus bypassing conversion between CIE u*v*Y and CIE XYZ.
4130
.NH 3
4131
Adding Device-Independent Color Spaces
4132
.XS
4133
\*(SN Adding Device-Independent Color Spaces
4134
.XE
4135
.LP
4136
To add a device-independent color space, use
4137
.PN XcmsAddColorSpace .
4138
.IN "XcmsAddColorSpace" "" "@DEF@"
4139
.sM
4140
.FD 0
4141
Status XcmsAddColorSpace\^(\^\fIcolor_space\fP\^)
4142
.br
4143
XcmsColorSpace *\fIcolor_space\fP\^;
4144
.FN
4145
.IP \fIcolor_space\fP 1i
4146
Specifies the device-independent color space to add.
4147
.LP
4148
.eM
4149
The
4150
.PN XcmsAddColorSpace
4151
function makes a device-independent color space (actually an
4152
.PN XcmsColorSpace
4153
structure) accessible by the color management system.
4154
Because format values for unregistered color spaces are assigned at run time,
4155
they should be treated as private to the client.
4156
If references to an unregistered color space must be made
4157
outside the client (for example, storing color specifications
4158
in a file using the unregistered color space),
4159
then reference should be made by color space prefix
4160
(see
4161
.PN XcmsFormatOfPrefix
4162
and
4163
.PN XcmsPrefixOfFormat ).
4164
.LP
4165
If the
4166
.PN XcmsColorSpace
4167
structure is already accessible in the color management system,
4168
.PN XcmsAddColorSpace
4169
returns
4170
.PN XcmsSuccess .
4171
.LP
4172
Note that added
4173
.PN XcmsColorSpaces
4174
must be retained for reference by Xlib.
4175
.NH 3
4176
Querying Color Space Format and Prefix
4177
.XS
4178
\*(SN Querying Color Space Format and Prefix
4179
.XE
4180
.LP
4181
To obtain the format associated with the color space
4182
associated with a specified color string prefix, use
4183
.PN XcmsFormatOfPrefix .
4184
.IN "XcmsFormatOfPrefix" "" "@DEF@"
4185
.sM
4186
.FD 0
4187
XcmsColorFormat XcmsFormatOfPrefix\^(\^\fIprefix\fP\^)
4188
.br
4189
char *\fIprefix\fP\^;
4190
.FN
4191
.IP \fIprefix\fP 1i
4192
Specifies the string that contains the color space prefix.
4193
.LP
4194
.eM
4195
The
4196
.PN XcmsFormatOfPrefix
4197
function returns the format for the specified color space prefix
4198
(for example, the string ``CIEXYZ'').
4199
The prefix is case-insensitive.
4200
If the color space is not accessible in the color management system,
4201
.PN XcmsFormatOfPrefix
4202
returns
4203
.PN XcmsUndefinedFormat .
4204
.LP
4205
.sp
4206
To obtain the color string prefix associated with the color space
4207
specified by a color format, use
4208
.PN XcmsPrefixOfFormat .
4209
.IN "XcmsPrefixOfFormat" "" "@DEF@"
4210
.sM
4211
.FD 0
4212
char *XcmsPrefixOfFormat\^(\^\fIformat\fP\^)
4213
.br
4214
XcmsColorFormat \fIformat\fP\^;
4215
.FN
4216
.IP \fIformat\fP 1i
4217
Specifies the color specification format.
4218
.LP
4219
.eM
4220
The
4221
.PN XcmsPrefixOfFormat
4222
function returns the string prefix associated with the color specification
4223
encoding specified by the format argument.
4224
Otherwise, if no encoding is found, it returns NULL.
4225
The returned string must be treated as read-only.
4226
.NH 3
4227
Creating Additional Color Spaces
4228
.XS
4229
\*(SN Creating Additional Color Spaces
4230
.XE
4231
.LP
4232
Color space specific information necessary
4233
for color space conversion and color string parsing is stored in an
4234
.PN XcmsColorSpace
4235
structure.
4236
Therefore, a new structure containing this information is required
4237
for each additional color space.
4238
In the case of device-independent color spaces,
4239
a handle to this new structure (that is, by means of a global variable)
4240
is usually made accessible to the client program for use with the
4241
.PN XcmsAddColorSpace
4242
function.
4243
.LP
4244
If a new
4245
.PN XcmsColorSpace
4246
structure specifies a color space not registered with the X Consortium,
4247
they should be treated as private to the client
4248
because format values for unregistered color spaces are assigned at run time.
4249
If references to an unregistered color space must be made outside the
4250
client (for example, storing color specifications in a file using the
4251
unregistered color space), then reference should be made by color space prefix
4252
(see
4253
.PN XcmsFormatOfPrefix
4254
and
4255
.PN XcmsPrefixOfFormat ).
4256
.sM
4257
.LP
4258
.Ds 0
4259
.TA .5i 2.5i
4260
.ta .5i 2.5i
4261
typedef (*XcmsConversionProc)();
4262
typedef XcmsConversionProc *XcmsFuncListPtr;
4263
/* A NULL terminated list of function pointers*/
4264
4265
typedef struct _XcmsColorSpace {
4266
char *prefix;
4267
XcmsColorFormat format;
4268
XcmsParseStringProc parseString;
4269
XcmsFuncListPtr to_CIEXYZ;
4270
XcmsFuncListPtr from_CIEXYZ;
4271
int inverse_flag;
4272
} XcmsColorSpace;
4273
.De
4274
.LP
4275
.eM
4276
The prefix member specifies the prefix that indicates a color string
4277
is in this color space's string format.
4278
For example, the strings ``ciexyz'' or ``CIEXYZ'' for CIE XYZ,
4279
and ``rgb'' or ``RGB'' for RGB.
4280
The prefix is case insensitive.
4281
The format member specifies the color specification format.
4282
Formats for unregistered color spaces are assigned at run time.
4283
The parseString member contains a pointer to the function
4284
that can parse a color string into an
4285
.PN XcmsColor
4286
structure.
4287
This function returns an integer (int): nonzero if it succeeded
4288
and zero otherwise.
4289
The to_CIEXYZ and from_CIEXYZ members contain pointers,
4290
each to a NULL terminated list of function pointers.
4291
When the list of functions is executed in series,
4292
it will convert the color specified in an
4293
.PN XcmsColor
4294
structure from/to the current color space format to/from the CIE XYZ format.
4295
Each function returns an integer (int): nonzero if it succeeded
4296
and zero otherwise.
4297
The white point to be associated with the colors is specified
4298
explicitly, even though white points can be found in the CCC.
4299
The inverse_flag member, if nonzero, specifies that for each function listed
4300
in to_CIEXYZ,
4301
its inverse function can be found in from_CIEXYZ such that:
4302
.LP
4303
.Ds 0
4304
Given: n = number of functions in each list
4305
4306
for each i, such that 0 <= i < n
4307
from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i].
4308
.De
4309
.LP
4310
This allows Xlib to use the shortest conversion path,
4311
thus bypassing CIE XYZ if possible (for example, TekHVC to CIE L*u*v*).
4312
.NH 3
4313
Parse String Callback
4314
.XS
4315
\*(SN Parse String Callback
4316
.XE
4317
.LP
4318
The callback in the
4319
.PN XcmsColorSpace
4320
structure for parsing a color string for the particular color space must
4321
adhere to the following software interface specification:
4322
.IN "XcmsParseStringProc" "" "@DEF@"
4323
.sM
4324
.FD 0
4325
typedef int (*XcmsParseStringProc)\^(\^\fIcolor_string\fP, \fIcolor_return\fP\^)
4326
.br
4327
char *\fIcolor_string\fP\^;
4328
.br
4329
XcmsColor *\fIcolor_return\fP\^;
4330
.FN
4331
.IP \fIcolor_string\fP 1i
4332
Specifies the color string to parse.
4333
.IP \fIcolor_return\fP 1i
4334
Returns the color specification in the color space's format.
4335
.LP
4336
.eM
4337
.NH 3
4338
Color Specification Conversion Callback
4339
.XS
4340
\*(SN Color Specification Conversion Callback
4341
.XE
4342
.LP
4343
Callback functions in the
4344
.PN XcmsColorSpace
4345
structure for converting a color specification between device-independent
4346
spaces must adhere to the
4347
following software interface specification:
4348
.sM
4349
.FD 0
4350
Status ConversionProc\^(\^\fIccc\fP, \fIwhite_point\fP, \fIcolors_in_out\fP, \fIncolors\fP\^)
4351
.br
4352
XcmsCCC \fIccc\fP\^;
4353
.br
4354
XcmsColor *\fIwhite_point\fP\^;
4355
.br
4356
XcmsColor *\fIcolors_in_out\fP\^;
4357
.br
4358
unsigned int \fIncolors\fP\^;
4359
.FN
4360
.IP \fIccc\fP 1i
4361
Specifies the CCC.
4362
.IP \fIwhite_point\fP 1i
4363
Specifies the white point associated with color specifications.
4364
The pixel member should be ignored,
4365
and the entire structure remain unchanged upon return.
4366
.IP \fIcolors_in_out\fP 1i
4367
Specifies an array of color specifications.
4368
Pixel members should be ignored and must remain unchanged upon return.
4369
.IP \fIncolors\fP 1i
4370
Specifies the number of
4371
.PN XcmsColor
4372
structures in the color-specification array.
4373
.LP
4374
.eM
4375
.sp
4376
Callback functions in the
4377
.PN XcmsColorSpace
4378
structure for converting a color specification to or from a device-dependent
4379
space must adhere to the
4380
following software interface specification:
4381
.sM
4382
.FD 0
4383
Status ConversionProc\^(\^\fIccc\fP, \fIcolors_in_out\fP, \fIncolors\fP, \fIcompression_flags_return\fP\^)
4384
.br
4385
XcmsCCC \fIccc\fP\^;
4386
.br
4387
XcmsColor *\fIcolors_in_out\fP\^;
4388
.br
4389
unsigned int \fIncolors\fP\^;
4390
.br
4391
Bool \fIcompression_flags_return\fP\^[\^]\^;
4392
.FN
4393
.IP \fIccc\fP 1i
4394
Specifies the CCC.
4395
.IP \fIcolors_in_out\fP 1i
4396
Specifies an array of color specifications.
4397
Pixel members should be ignored and must remain unchanged upon return.
4398
.IP \fIncolors\fP 1i
4399
Specifies the number of
4400
.PN XcmsColor
4401
structures in the color-specification array.
4402
.IP \fIcompression_flags_return\fP 1i
4403
Returns an array of Boolean values for indicating compression status.
4404
If a non-NULL pointer is supplied
4405
and a color at a given index is compressed, then
4406
.PN True
4407
should be stored at the corresponding index in this array;
4408
otherwise, the array should not be modified.
4409
.LP
4410
.eM
4411
Conversion functions are available globally for use by other color
4412
spaces.
4413
The conversion functions provided by Xlib are:
4414
.TS H
4415
lw(1.8i) lw(1.8i) lw(1.8i).
4416
_
4417
.sp 6p
4418
.B
4419
Function Converts from Converts to
4420
.sp 6p
4421
_
4422
.sp 6p
4423
.TH
4424
.R
4425
T{
4426
.PN XcmsCIELabToCIEXYZ
4427
T} T{
4428
.PN XcmsCIELabFormat
4429
T} T{
4430
.PN XcmsCIEXYZFormat
4431
T}
4432
T{
4433
.PN XcmsCIELuvToCIEuvY
4434
T} T{
4435
.PN XcmsCIELuvFormat
4436
T} T{
4437
.PN XcmsCIEuvYFormat
4438
T}
4439
T{
4440
.PN XcmsCIEXYZToCIELab
4441
T} T{
4442
.PN XcmsCIEXYZFormat
4443
T} T{
4444
.PN XcmsCIELabFormat
4445
T}
4446
T{
4447
.PN XcmsCIEXYZToCIEuvY
4448
T} T{
4449
.PN XcmsCIEXYZFormat
4450
T} T{
4451
.PN XcmsCIEuvYFormat
4452
T}
4453
T{
4454
.PN XcmsCIEXYZToCIExyY
4455
T} T{
4456
.PN XcmsCIEXYZFormat
4457
T} T{
4458
.PN XcmsCIExyYFormat
4459
T}
4460
T{
4461
.PN XcmsCIEXYZToRGBi
4462
T} T{
4463
.PN XcmsCIEXYZFormat
4464
T} T{
4465
.PN XcmsRGBiFormat
4466
T}
4467
T{
4468
.PN XcmsCIEuvYToCIELuv
4469
T} T{
4470
.PN XcmsCIEuvYFormat
4471
T} T{
4472
.PN XcmsCIELabFormat
4473
T}
4474
T{
4475
.PN XcmsCIEuvYToCIEXYZ
4476
T} T{
4477
.PN XcmsCIEuvYFormat
4478
T} T{
4479
.PN XcmsCIEXYZFormat
4480
T}
4481
T{
4482
.PN XcmsCIEuvYToTekHVC
4483
T} T{
4484
.PN XcmsCIEuvYFormat
4485
T} T{
4486
.PN XcmsTekHVCFormat
4487
T}
4488
T{
4489
.PN XcmsCIExyYToCIEXYZ
4490
T} T{
4491
.PN XcmsCIExyYFormat
4492
T} T{
4493
.PN XcmsCIEXYZFormat
4494
T}
4495
T{
4496
.PN XcmsRGBToRGBi
4497
T} T{
4498
.PN XcmsRGBFormat
4499
T} T{
4500
.PN XcmsRGBiFormat
4501
T}
4502
T{
4503
.PN XcmsRGBiToCIEXYZ
4504
T} T{
4505
.PN XcmsRGBiFormat
4506
T} T{
4507
.PN XcmsCIEXYZFormat
4508
T}
4509
T{
4510
.PN XcmsRGBiToRGB
4511
T} T{
4512
.PN XcmsRGBiFormat
4513
T} T{
4514
.PN XcmsRGBFormat
4515
T}
4516
T{
4517
.PN XcmsTekHVCToCIEuvY
4518
T} T{
4519
.PN XcmsTekHVCFormat
4520
T} T{
4521
.PN XcmsCIEuvYFormat
4522
T}
4523
.sp 6p
4524
_
4525
.TE
4526
.NH 3
4527
Function Sets
4528
.XS
4529
\*(SN Function Sets
4530
.XE
4531
.IN "Function set"
4532
.IN "Function set" "LINEAR_RGB"
4533
.LP
4534
Functions to convert between device-dependent color spaces
4535
and CIE XYZ may differ for different classes of output devices
4536
(for example, color versus gray monitors).
4537
Therefore, the notion of a Color Characterization Function Set
4538
has been developed.
4539
A function set consists of device-dependent color spaces
4540
and the functions that convert color specifications
4541
between these device-dependent color spaces and the CIE XYZ color space
4542
appropriate for a particular class of output devices.
4543
The function set also contains a function that reads
4544
color characterization data off root window properties.
4545
It is this characterization data that will differ between devices within
4546
a class of output devices.
4547
.IN "Device Color Characterization"
4548
For details about how color characterization data is
4549
stored in root window properties,
4550
see the section on Device Color Characterization in the
4551
\fIInter-Client Communication Conventions Manual\fP.
4552
The LINEAR_RGB function set is provided by Xlib
4553
and will support most color monitors.
4554
Function sets may require data that differs
4555
from those needed for the LINEAR_RGB function set.
4556
In that case,
4557
its corresponding data may be stored on different root window properties.
4558
.NH 3
4559
Adding Function Sets
4560
.XS
4561
\*(SN Adding Function Sets
4562
.XE
4563
.LP
4564
To add a function set, use
4565
.PN XcmsAddFunctionSet .
4566
.IN "XcmsAddFunctionSet" "" "@DEF@"
4567
.sM
4568
.FD 0
4569
Status XcmsAddFunctionSet\^(\^\fIfunction_set\fP\^)
4570
.br
4571
XcmsFunctionSet *\fIfunction_set\fP\^;
4572
.FN
4573
.IP \fIfunction_set\fP 1i
4574
Specifies the function set to add.
4575
.LP
4576
.eM
4577
The
4578
.PN XcmsAddFunctionSet
4579
function adds a function set to the color management system.
4580
If the function set uses device-dependent
4581
.PN XcmsColorSpace
4582
structures not accessible in the color management system,
4583
.PN XcmsAddFunctionSet
4584
adds them.
4585
If an added
4586
.PN XcmsColorSpace
4587
structure is for a device-dependent color space not registered
4588
with the X Consortium,
4589
they should be treated as private to the client
4590
because format values for unregistered color spaces are assigned at run time.
4591
If references to an unregistered color space must be made outside the
4592
client (for example, storing color specifications in a file
4593
using the unregistered color space),
4594
then reference should be made by color space prefix
4595
(see
4596
.PN XcmsFormatOfPrefix
4597
and
4598
.PN XcmsPrefixOfFormat ).
4599
.LP
4600
Additional function sets should be added before any calls to other
4601
Xlib routines are made.
4602
If not, the
4603
.PN XcmsPerScrnInfo
4604
member of a previously created
4605
.PN XcmsCCC
4606
does not have the opportunity to initialize
4607
with the added function set.
4608
.NH 3
4609
Creating Additional Function Sets
4610
.XS
4611
\*(SN Creating Additional Function Sets
4612
.XE
4613
.LP
4614
The creation of additional function sets should be
4615
required only when an output device does not conform to existing
4616
function sets or when additional device-dependent color spaces are necessary.
4617
A function set consists primarily of a collection of device-dependent
4618
.PN XcmsColorSpace
4619
structures and a means to read and store a
4620
screen's color characterization data.
4621
This data is stored in an
4622
.PN XcmsFunctionSet
4623
structure.
4624
A handle to this structure (that is, by means of global variable)
4625
is usually made accessible to the client program for use with
4626
.PN XcmsAddFunctionSet .
4627
.LP
4628
If a function set uses new device-dependent
4629
.PN XcmsColorSpace
4630
structures,
4631
they will be transparently processed into the color management system.
4632
Function sets can share an
4633
.PN XcmsColorSpace
4634
structure for a device-dependent color space.
4635
In addition, multiple
4636
.PN XcmsColorSpace
4637
structures are allowed for a device-dependent color space;
4638
however, a function set can reference only one of them.
4639
These
4640
.PN XcmsColorSpace
4641
structures will differ in the functions to convert to and from CIE XYZ,
4642
thus tailored for the specific function set.
4643
.sM
4644
.LP
4645
.Ds 0
4646
.TA .5i 2.5i
4647
.ta .5i 2.5i
4648
typedef struct _XcmsFunctionSet {
4649
XcmsColorSpace **DDColorSpaces;
4650
XcmsScreenInitProc screenInitProc;
4651
XcmsScreenFreeProc screenFreeProc;
4652
} XcmsFunctionSet;
4653
.De
4654
.LP
4655
.eM
4656
The DDColorSpaces member is a pointer to a NULL terminated list
4657
of pointers to
4658
.PN XcmsColorSpace
4659
structures for the device-dependent color spaces that are supported
4660
by the function set.
4661
The screenInitProc member is set to the callback procedure (see the following
4662
interface specification) that initializes the
4663
.PN XcmsPerScrnInfo
4664
structure for a particular screen.
4665
.LP
4666
The screen initialization callback must adhere to the following software
4667
interface specification:
4668
.IN "XcmsScreenInitProc" "" "@DEF@"
4669
.sM
4670
.FD 0
4671
typedef Status (*XcmsScreenInitProc)\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIscreen_info\fP\^)
4672
.br
4673
Display *\fIdisplay\fP\^;
4674
.br
4675
int \fIscreen_number\fP\^;
4676
.br
4677
XcmsPerScrnInfo *\fIscreen_info\fP\^;
4678
.FN
4679
.IP \fIdisplay\fP 1i
4680
Specifies the connection to the X server.
4681
.IP \fIscreen_number\fP 1i
4682
Specifies the appropriate screen number on the host server.
4683
.IP \fIscreen_info\fP 1i
4684
Specifies the
4685
.PN XcmsPerScrnInfo
4686
structure, which contains the per screen information.
4687
.LP
4688
.eM
4689
The screen initialization callback in the
4690
.PN XcmsFunctionSet
4691
structure fetches the color characterization data (device profile) for
4692
the specified screen,
4693
typically off properties on the
4694
screen's root window.
4695
It then initializes the specified
4696
.PN XcmsPerScrnInfo
4697
structure.
4698
.IN "Device profile"
4699
.IN "Color Characterization Data"
4700
If successful, the procedure fills in the
4701
.PN XcmsPerScrnInfo
4702
structure as follows:
4703
.IP \(bu 5
4704
It sets the screenData member to the address
4705
of the created device profile data structure
4706
(contents known only by the function set).
4707
.IP \(bu 5
4708
It next sets the screenWhitePoint member.
4709
.IP \(bu 5
4710
It next sets the functionSet member to the address of the
4711
.PN XcmsFunctionSet
4712
structure.
4713
.IP \(bu 5
4714
It then sets the state member to
4715
.PN XcmsInitSuccess
4716
and finally returns
4717
.PN XcmsSuccess .
4718
.LP
4719
If unsuccessful, the procedure sets the state member to
4720
.PN XcmsInitFailure
4721
and returns
4722
.PN XcmsFailure .
4723
.LP
4724
The
4725
.PN XcmsPerScrnInfo
4726
structure contains:
4727
.sM
4728
.LP
4729
.Ds 0
4730
.TA .5i 2.5i
4731
.ta .5i 2.5i
4732
typedef struct _XcmsPerScrnInfo {
4733
XcmsColor screenWhitePoint;
4734
XPointer functionSet;
4735
XPointer screenData;
4736
unsigned char state;
4737
char pad[3];
4738
} XcmsPerScrnInfo;
4739
.De
4740
.LP
4741
.eM
4742
The screenWhitePoint member specifies the white point inherent to
4743
the screen.
4744
The functionSet member specifies the appropriate function set.
4745
The screenData member specifies the device profile.
4746
The state member is set to one of the following:
4747
.IP \(bu 5
4748
.PN XcmsInitNone
4749
indicates initialization has not been previously attempted.
4750
.IP \(bu 5
4751
.PN XcmsInitFailure
4752
indicates initialization has been previously attempted but failed.
4753
.IP \(bu 5
4754
.PN XcmsInitSuccess
4755
indicates initialization has been previously attempted and succeeded.
4756
.LP
4757
The screen free callback must adhere to the following software
4758
interface specification:
4759
.IN "XcmsScreenFreeProc" "" "@DEF@"
4760
.sM
4761
.FD 0
4762
typedef void (*XcmsScreenFreeProc)\^(\^\fIscreenData\fP\^)
4763
.br
4764
XPointer \fIscreenData\fP\^;
4765
.FN
4766
.IP \fIscreenData\fP 1i
4767
Specifies the data to be freed.
4768
.LP
4769
.eM
4770
This function is called to free the screenData stored in an
4771
.PN XcmsPerScrnInfo
4772
structure.
4773
.bp
Loggerhead is a web-based interface for Breezy
Version: 2.0.1