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