specs/tog-cup.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
   4
   5
   6 <book id="tog-cup">
   7
   8 <bookinfo>
   9    <title>Colormap Utilization Policy and Extension</title>
  10    <subtitle>X Project Team Standard</subtitle>
  11    <releaseinfo>Version 1.0</releaseinfo>
  12    <authorgroup>
  13       <author>
  14          <firstname>Kaleb</firstname>
  15          <othername>S.</othername>
  16          <surname>Keithley</surname>
  17          <affiliation><orgname>The Open Group</orgname></affiliation>
  18       </author>
  19    </authorgroup>
  20    <corpname>X Consortium Standard</corpname>
  21    <copyright><year>1986-1997</year><holder>The Open Group</holder></copyright>
  22    <affiliation><orgname>X Consortium</orgname></affiliation>
  23    <productnumber>X Version 11, Release 6.8</productnumber>
  24
  25 <legalnotice>
  26
  27 <para>
  28 Permission is hereby granted, free of charge, to any person obtaining a
  29 copy of this
  30 software and associated documentation files (the Software), to use the
  31 Software
  32 without restriction, including, without limitation, the rights to copy,
  33 modify, merge,
  34 publish, distribute and sublicense the Software, to make, have made,
  35 license and
  36 distribute derivative works thereof, and to permit persons to whom the
  37 Software is
  38 furnished to do so, subject to the following conditions:
  39 </para>
  40 <para>
  41 The above copyright notice and the following permission notice shall be
  42 included in all copies of the Software:
  43 </para>
  44 <para>
  45 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  46 EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE WARRANTIES
  47 OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-
  48 INFRINGEMENT.  IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY
  49 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
  50 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF, OR IN
  51 CONNNECTION WITH THE SOFTWARE OR THE USE OF OTHER DEALINGS IN
  52 THE SOFTWARE.
  53 </para>
  54 <para>
  55 Except as contained in this notice, the name of The Open Group shall not be
  56 used in
  57 advertising or otherwise to promote the use or other dealings in this
  58 Software without prior written authorization from The Open Group.
  59 </para>
  60 <para>
  61 X Window System is a trademark of The Open Group.
  62 </para>
  63
  64 </legalnotice>
  65 </bookinfo>
  66
  67 <chapter>
  68 <title>TITLE</title>
  69 <sect1 id="Overview">
  70 <title>Overview</title>
  71 <para>
  72 This extension has three purposes: a) to provide mechanism for a special
  73 application (a colormap manager) to discover any special colormap
  74 requirements, e.g. the colormap entries that are nominally reserved for
  75 desktop colors in the MS-Windows environment and initialize the default
  76 colormap so that it can be more easily shared; and b) to encourage colormap
  77 sharing and reduce colormap flashing on low-end 8-bit frame buffers by
  78 providing a policy for sharing; and c) when colormaps aren't shared,
  79 define a behavior in the X server color allocation scheme to reduce
  80 colormap flashing.
  81 </para>
  82
  83 <para>
  84 To encourage colormap sharing and accomodate special colormap requirements
  85 two new protocols are defined: the first provides a way to query the
  86 server for a list of reserved colormap entries, and the second is a way
  87 to initialize read-only (shareable) colormap entries at specific locations
  88 in a colormap.
  89 </para>
  90
  91 <para>
  92 To minimize colormap flashing when the root window's default visual is one
  93 of GrayScale, PseudoColor, or DirectColor, and a private colormap for the
  94 default visual is being used, a minor (but compatible) change to the
  95 server implementation of the AllocColor and AllocNamedColor requests is
  96 required. Where the core protocol says nothing about the pixel values
  97 returned, when this extension is in effect, the AllocColor and AllocNamedColor
  98 requests will first look for a matching color in the default colormap, and,
  99 if a match is found and the same cell in the private colormap has not
 100 already been allocated, the color will be allocated in the private colormap
 101 at the same locaton as in the default colormap (instead of in the first
 102 available location.)
 103 </para>
 104 </sect1>
 105
 106 <sect1 id="Requests">
 107 <title>Requests</title>
 108 <para>
 109 <function>QueryVersion</function>
 110 </para>
 111
 112 <informaltable frame="none">
 113   <tgroup cols='1' align='left'>
 114   <colspec colname='c1' colsep="0" colwidth="1*"/>
 115   <tbody>
 116     <row rowsep="0">
 117       <entry>
 118 client_major_version: CARD16
 119       </entry>
 120     </row>
 121     <row rowsep="0">
 122       <entry>
 123 client_minor_version: CARD16
 124       </entry>
 125     </row>
 126     <row rowsep="0">
 127       <entry>
 128 =&gt;
 129       </entry>
 130     </row>
 131     <row rowsep="0">
 132       <entry>
 133 server_major_version: CARD16
 134       </entry>
 135     </row>
 136     <row rowsep="0">
 137       <entry>
 138 server_minor_version: CARD16
 139       </entry>
 140     </row>
 141   </tbody>
 142   </tgroup>
 143 </informaltable>
 144
 145 <para>
 146 If supplied, the client_major_version and client_minor_version indicate
 147 what version of the protocol the client wants the server to implement.
 148 The server version numbers returned indicate the protocol this extension
 149 actually supports. This might not equal the version sent by the client.
 150 An implementation can (but need not) support more than one version
 151 simultaneously. The server_major_version and the server_minor_version
 152 are a mechanism to support future revisions of the TOG-CUP protocol that
 153 may be necessary. In general, the major version would increment for
 154 incompatible changes, and the minor version would increment for small
 155 upward-compatible changes. Servers that support the protocol defined in
 156 this document will return a server_major_version of one (1), and a
 157 server_minor_version of zero (0).
 158 </para>
 159
 160 <para>
 161 <function>GetReservedColormapEntries</function>
 162 </para>
 163
 164 <informaltable frame="none">
 165   <tgroup cols='1' align='left'>
 166   <colspec colname='c1' colsep="0" colwidth="1*"/>
 167   <tbody>
 168     <row rowsep="0">
 169       <entry>
 170 screen: CARD32
 171       </entry>
 172     </row>
 173     <row rowsep="0">
 174       <entry>
 175 =&gt;
 176       </entry>
 177     </row>
 178     <row rowsep="0">
 179       <entry>
 180 entries: LISTofCOLORITEM
 181       </entry>
 182     </row>
 183   </tbody>
 184   </tgroup>
 185 </informaltable>
 186
 187 <para>
 188 This request returns a list of colormap entries (pixels) that are reserved
 189 by the system, e.g. MS-Windows reserved desktop colors. This list will, at a
 190 minimum, contain entries for the BlackPixel and WhitePixel of the specified
 191 screen. The do-red, do-green, and do-blue elements of the COLORITEMs are
 192 unused in this reply.
 193 </para>
 194
 195 <para>
 196 Rationale: There are colormap entries (pixels) that, e.g., MS-Windows
 197 desktop reserves as desktop colors, that should not be altered. If they
 198 are altered then X programs will cause colormap flashing between X and
 199 MS-Windows applications running/displaying on the same desktop.
 200 </para>
 201
 202 <para>
 203 <function>StoreColors</function>
 204 </para>
 205
 206 <informaltable frame="none">
 207   <tgroup cols='1' align='left'>
 208   <colspec colname='c1' colsep="0" colwidth="1*"/>
 209   <tbody>
 210     <row rowsep="0">
 211       <entry>
 212 cmap: COLORMAP
 213       </entry>
 214     </row>
 215     <row rowsep="0">
 216       <entry>
 217 items: LISTofCOLORITEM
 218       </entry>
 219     </row>
 220     <row rowsep="0">
 221       <entry>
 222 =&gt;
 223       </entry>
 224     </row>
 225     <row rowsep="0">
 226       <entry>
 227 items: LISTofCOLORITEM
 228       </entry>
 229     </row>
 230   </tbody>
 231   </tgroup>
 232 </informaltable>
 233
 234 <para>
 235 This request changes the colormap entries of the specified pixels. The
 236 colormap entries are allocated as if by an AllocColor request. The do-red,
 237 do-green, and do-blue elements of the COLORITEMs are unused in this request.
 238 A boolean alloc-ok element (a bit) is returned indicating whether the
 239 particular pixel was successfully allocated or not. If successfully
 240 allocated the RGB and pixel are returned.
 241 </para>
 242
 243 <para>
 244 A Value error is generated if a pixel is not a valid index into cmap. A
 245 BadMatch error is generated if if cmap does not belong to a GrayScale,
 246 PseudoColor, or DirectColor visual.
 247 </para>
 248
 249 </sect1>
 250
 251 <sect1 id="Events_and_Errors">
 252 <title>Events and Errors</title>
 253 <para>
 254 No new events or errors are defined by this extension.
 255 </para>
 256
 257 </sect1>
 258 <sect1 id="Changes_to_existing_protocol_">
 259 <title>Changes to existing protocol.</title>
 260 <para>
 261 None.
 262 </para>
 263 </sect1>
 264
 265 <sect1 id="Encoding">
 266 <title>Encoding</title>
 267 <para>
 268 The name of this extension is "TOG-CUP".
 269 </para>
 270
 271 <para>
 272 The conventions used here are the same as those for the core X11
 273 Protocol Encoding.
 274 </para>
 275
 276 <literallayout class="monospaced">
 277 <function>QueryVersion</function>
 278      1     CARD8               opcode
 279      1     0                   TOG-CUP opcode
 280      2     2                   request length
 281      2     CARD16              client_major_version
 282      2     CARD16              client_minor_version
 283 =&gt;
 284      1     1                   reply
 285      1                         unused
 286      2     CARD16              sequence number
 287      4     0                   length
 288      2     CARD16              server_major_version
 289      2     CARD16              server_minor_number
 290      20                        unused
 291 </literallayout>
 292
 293 <literallayout class="monospaced">
 294 <function>GetReservedColormapEntries</function>
 295      1     CARD8               opcode
 296      1     1                   TOG-CUP opcode
 297      2     2                   request length
 298      4     CARD32              screen
 299 =&gt;
 300      1     1                   reply
 301      1                         unused
 302      2     CARD16              sequence number
 303      4     3n                  length
 304      24                        unused
 305      12n   LISTofCOLORITEM     items
 306 </literallayout>
 307
 308 <literallayout class="monospaced">
 309 <function>StoreColors</function>
 310      1     CARD8               opcode
 311      1     2                   TOG-CUP opcode
 312      2     2+3n                request length
 313      4     COLORMAP            cmap
 314      12n   LISTofCOLORITEM     items
 315 =&gt;
 316      1     1                   reply
 317      1                         unused
 318      2     CARD16              sequence number
 319      4     3n                  length
 320      24                        unused
 321      12n   LISTofCOLORITEM     items
 322 </literallayout>
 323
 324 <para>
 325 (The definition of COLORITEM here is only for the purpose of defining the
 326 additional alloc-ok member in the CUPStoreColors reply.)
 327 </para>
 328
 329 <literallayout class="monospaced">
 330   COLORITEM
 331      4     CARD32              pixel
 332      2     CARD16              red
 333      2     CARD16              green
 334      2     CARD16              blue
 335      1                         alloc-ok
 336            #x07                unused
 337            #x08                alloc-ok (1 is True, 0 is False)
 338            #xF0                unused
 339      1                         unused
 340 </literallayout>
 341 </sect1>
 342
 343 <sect1 id="C_Language_Binding">
 344 <title>C Language Binding</title>
 345
 346 <para>
 347 The C functions provide direct access to the protocol and add no additional
 348 semantics.  For complete details on the effects of these functions, refer
 349 to the appropriate protocol request, which can be derived by deleting XCup
 350 at the start of the function. All functions that have return type Status
 351 will return nonzero for success and zero for failure.
 352 </para>
 353
 354 <para>
 355 The include file for this extension is
 356 <function>&lt;X11/extensions/Xcup.h&gt;</function>.
 357 </para>
 358
 359 <funcsynopsis>
 360 <funcprototype>
 361   <funcdef>Status <function> XCupQueryVersion</function></funcdef>
 362   <paramdef>Display*<parameter> display</parameter></paramdef>
 363   <paramdef>int*<parameter> major_version_return</parameter></paramdef>
 364   <paramdef>int*<parameter> minor_version_return</parameter></paramdef>
 365 </funcprototype>
 366 </funcsynopsis>
 367
 368 <variablelist>
 369   <varlistentry>
 370     <term>
 371       <emphasis remap='I'>display</emphasis>
 372     </term>
 373     <listitem>
 374       <para>
 375 Specifies the connection to the X server.
 376       </para>
 377     </listitem>
 378   </varlistentry>
 379   <varlistentry>
 380     <term>
 381       <emphasis remap='I'>major_version_return</emphasis>
 382     </term>
 383     <listitem>
 384       <para>
 385 Returns the major version supported by the server.
 386       </para>
 387     </listitem>
 388   </varlistentry>
 389   <varlistentry>
 390     <term>
 391       <emphasis remap='I'>minor_version_return</emphasis>
 392     </term>
 393     <listitem>
 394       <para>
 395 Returns the minor version supported by the server.
 396     </para>
 397   </listitem>
 398   </varlistentry>
 399 </variablelist>
 400
 401
 402 <para>
 403 XCupQueryVersions sets major_version_return and minor_version_return to
 404 the major and minor TOG-CUP protocol version supported by the server.  If
 405 the TOG-CUP library is compatible with the version returned by the server,
 406 it returns nonzero.  If dpy does not support the TOG-CUP extension, or if
 407 there was an error during communication with the server, or if the server
 408 and library protocol versions are incompatible, it returns zero.  No other
 409 XCup functions may be called before this function. If a client violates
 410 this rule, the effects of all subsequent XCup calls that it makes are
 411 undefined.
 412 </para>
 413
 414 <para>
 415 To get the list of reserved colormap entries, use
 416 XCupGetReservedColormapEntries.
 417 </para>
 418
 419 <funcsynopsis>
 420 <funcprototype>
 421   <funcdef>Status <function> XCupGetReservedColormapEntries</function></funcdef>
 422   <paramdef>Display*<parameter> display</parameter></paramdef>
 423   <paramdef>int<parameter> screen</parameter></paramdef>
 424   <paramdef>XColor**<parameter> colors_out</parameter></paramdef>
 425   <paramdef>int*<parameter> ncolors</parameter></paramdef>
 426 </funcprototype>
 427 </funcsynopsis>
 428
 429 <variablelist>
 430   <varlistentry>
 431     <term>
 432       <emphasis remap='I'>display</emphasis>
 433     </term>
 434     <listitem>
 435       <para>
 436 Specifies the connection to the X server.
 437       </para>
 438     </listitem>
 439   </varlistentry>
 440   <varlistentry>
 441     <term>
 442       <emphasis remap='I'>colors_out</emphasis>
 443     </term>
 444     <listitem>
 445       <para>
 446 Returns the values reserved by the server.
 447       </para>
 448     </listitem>
 449   </varlistentry>
 450   <varlistentry>
 451     <term>
 452       <emphasis remap='I'>ncolors</emphasis>
 453     </term>
 454     <listitem>
 455       <para>
 456 Returns the number of items in colors_out.
 457     </para>
 458   </listitem>
 459   </varlistentry>
 460 </variablelist>
 461
 462 <para>
 463 The XCupGetReservedColormapEntries function gets system specific colormap
 464 entries. E.g. the MS-Windows desktop uses N colormap entries at the beginning
 465 (0..N) and end (256-N..255) of the colormap. Use XFree to free colors_out.
 466 </para>
 467
 468 <para>
 469 To allocate one or more read-only color cells with RGB values, use
 470 XCupStoreColors.
 471 </para>
 472
 473 <funcsynopsis>
 474 <funcprototype>
 475   <funcdef>Status <function> XCupStoreColors</function></funcdef>
 476   <paramdef>Display*<parameter> display</parameter></paramdef>
 477   <paramdef>Colormap<parameter> colormap</parameter></paramdef>
 478   <paramdef>XColor*<parameter> colors_in_out</parameter></paramdef>
 479   <paramdef>int<parameter> ncolors</parameter></paramdef>
 480 </funcprototype>
 481 </funcsynopsis>
 482
 483 <variablelist>
 484   <varlistentry>
 485     <term>
 486       <emphasis remap='I'>display</emphasis>
 487     </term>
 488     <listitem>
 489       <para>
 490 Specifies the connection to the X server.
 491       </para>
 492     </listitem>
 493   </varlistentry>
 494   <varlistentry>
 495     <term>
 496       <emphasis remap='I'>colormap</emphasis>
 497     </term>
 498     <listitem>
 499       <para>
 500 Specifies the colormap.
 501       </para>
 502     </listitem>
 503   </varlistentry>
 504   <varlistentry>
 505     <term>
 506       <emphasis remap='I'>colors_in_out</emphasis>
 507     </term>
 508     <listitem>
 509       <para>
 510 Specifies and returns the values actually used in the colormap.
 511       </para>
 512     </listitem>
 513   </varlistentry>
 514   <varlistentry>
 515     <term>
 516       <emphasis remap='I'>ncolors</emphasis>
 517     </term>
 518     <listitem>
 519       <para>
 520 Specifies the number of items in colors_in_out.
 521     </para>
 522   </listitem>
 523   </varlistentry>
 524 </variablelist>
 525
 526 <para>
 527 The XCupStoreColors function changes the colormap entries of the pixel
 528 values specified in the pixel members of the XColor structures. The colormap
 529 entries are allocated as if an AllocColor had been used instead, i.e. the
 530 colors are read-only (shareable). XCupStoreColors returns the number of
 531 colors that were successfully allocated in the colormap.
 532 </para>
 533
 534 </sect1>
 535
 536 <sect1 id="Using_the_TOG_CUP_extension_and_Colormap_Utilization_Policy">
 537 <title>Using the TOG-CUP extension and Colormap Utilization Policy</title>
 538 <para>
 539 The X server preallocates any hardware or desktop special colors in the
 540 default colormap; e.g. UNIX X servers preallocate Black and White pixels.
 541 PC X servers should also preallocate the MS-Windows desktop colors. (Note
 542 to implementors: in the Sample Implementation special colors are allocated
 543 in the default colormap in cfbCreateDefColormap for dumb memory framebuffers.)
 544 </para>
 545
 546 <para>
 547 To minimize colormap flash an application which installs its own private
 548 colormap should query the special colors by calling
 549 XCupGetReservedColormapEntries, and can then store those entries (in the
 550 proper location) in its private colormap using XCupStoreColors.
 551 </para>
 552
 553 <para>
 554 Applications which allocate many colors in a screen's default colormap, e.g.
 555 a color-cube or a gray-ramp, should allocate them with XCupStoreColors. By
 556 using XCupStoreColors the colors will be allocated sharable (read-only) and
 557 any other application which allocates the same color will share that color
 558 cell.
 559 </para>
 560 </sect1>
 561 </chapter>
 562 </book>