specs/evi.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="evi">
   7
   8 <bookinfo>
   9    <title>Extended Visual Information Extension</title>
  10    <subtitle>X Project Team Standard</subtitle>
  11    <releaseinfo>Version 1.0</releaseinfo>
  12    <authorgroup>
  13       <author>
  14          <firstname>Peter</firstname><surname>Daifuku</surname>
  15          <affiliation><orgname>Silicon Graphics, Inc.</orgname></affiliation>
  16       </author>
  17    </authorgroup>
  18    <corpname>X Consortium Standard</corpname>
  19    <copyright><year>1986-97</year><holder>The Open Group</holder></copyright>
  20    <affiliation><orgname>X Consortium</orgname></affiliation>
  21    <productnumber>X Version 11, Release 6.8</productnumber>
  22
  23 <legalnotice>
  24
  25 <para>
  26 Permission is hereby granted, free of charge, to any person obtaining a
  27 copy of this
  28 software and associated documentation files (the Software), to use the
  29 Software without restriction, including, without limitation, the rights to
  30 copy, modify, merge, publish, distribute and sublicense the Software,
  31 to make, have made, license and distribute derivative works thereof, and
  32 to permit persons to whom the Software is
  33 furnished to do so, subject to the following conditions:
  34 </para>
  35
  36 <para>
  37 The above copyright notice and the following permission notice shall be
  38 included in all copies of the Software:
  39 </para>
  40
  41 <para>
  42 THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND,
  43 EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE WARRANTIES
  44 OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-
  45 INFRINGEMENT.  IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY
  46 CLAIM, DAMAGES OR OTHER USEABILITIY, WHETHER IN AN ACTION OF
  47 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF, OR IN
  48 CONNNECTION WITH THE SOFTWARE OR THE USE OF OTHER DEALINGS IN
  49 THE SOFTWARE.
  50 </para>
  51
  52 <para>
  53 Except as contained in this notice, the name of The Open Group shall not
  54 be used in advertising or otherwise to promote the use or other dealings
  55 in this Software without prior written authorization from The Open Group.
  56 </para>
  57
  58 <para>
  59 X Window System is a trademark of The Open Group.
  60 </para>
  61
  62 </legalnotice>
  63 </bookinfo>
  64
  65 <chapter>
  66 <title>TITLE</title>
  67 <sect1 id="Introduction">
  68 <title>Introduction</title>
  69 <para>
  70 EVI (Extended Visual Information extension) allows a client to determine
  71 information about core X visuals beyond what the core protocol provides.
  72 </para>
  73 </sect1>
  74
  75 <sect1 id="Goals">
  76 <title>Goals</title>
  77 <para>
  78 As the X Window System has evolved, it has become clear that the information
  79 returned by the core X protocol regarding Visuals is often insufficient for a
  80 client to determine which is the most appropriate visual for its needs. This
  81 extension allows clients to query the X server for additional visual
  82 information, specifically as regards colormaps and framebuffer levels.
  83 </para>
  84
  85 <para>
  86 This extension is meant to address the needs of pure X clients only. It is
  87 specifically and purposefully not designed to address the needs of X
  88 extensions. Extensions that have an impact on visual information should provide
  89 their own mechanisms for delivering that information. For example, the Double
  90 Buffering Extension (DBE) provides its own mechanism for determining which
  91 visuals support double-buffering.
  92 </para>
  93 </sect1>
  94
  95 <sect1 id="Requests">
  96 <title>Requests</title>
  97 <para>
  98 <function>GetVersion</function>
  99 </para>
 100
 101 <informaltable frame="none">
 102   <tgroup cols='1' align='left'>
 103   <colspec colname='c1' colsep="0" colwidth="1*"/>
 104   <tbody>
 105     <row rowsep="0">
 106       <entry>
 107 <emphasis remap='I'>client_major_version</emphasis>: CARD8
 108       </entry>
 109     </row>
 110     <row rowsep="0">
 111       <entry>
 112 <emphasis remap='I'>client_minor_version</emphasis>: CARD8
 113       </entry>
 114     </row>
 115     <row rowsep="0">
 116       <entry>
 117 =&gt;
 118       </entry>
 119     </row>
 120     <row rowsep="0">
 121       <entry>
 122 <emphasis remap='I'>server_major_version</emphasis>: CARD8
 123       </entry>
 124     </row>
 125     <row rowsep="0">
 126       <entry>
 127 <emphasis remap='I'>server_minor_version</emphasis>: CARD8
 128       </entry>
 129     </row>
 130   </tbody>
 131   </tgroup>
 132 </informaltable>
 133
 134
 135
 136 <para>
 137 If supplied, the client_major_version and client_minor_version indicate
 138 what version of the protocol the client wants the server to implement.
 139 The server version numbers returned indicate the protocol this extension
 140 actually supports. This might not equal the version sent by the client.
 141 An implementation can (but need not) support more than one version
 142 simultaneously. The server_major_version and the server_minor_version
 143 are a mechanism to support future revisions of the EVI protocol that
 144 may be necessary. In general, the major version would increment for
 145 incompatible changes, and the minor version would increment for small
 146 upward-compatible changes. Servers that support the protocol defined in
 147 this document will return a server_major_version of one (1), and a
 148 server_minor_version of zero (0).
 149 </para>
 150
 151 <para>
 152 <function>  GetVisualInfo</function>
 153 </para>
 154
 155 <informaltable frame="none">
 156   <tgroup cols='1' align='left'>
 157   <colspec colname='c1' colsep="0" colwidth="1*"/>
 158   <tbody>
 159     <row rowsep="0">
 160       <entry>
 161 <emphasis remap='I'>visual_list</emphasis>: LISTofVISUALID
 162       </entry>
 163     </row>
 164     <row rowsep="0">
 165       <entry>
 166 =&gt;
 167       </entry>
 168     </row>
 169     <row rowsep="0">
 170       <entry>
 171 <emphasis remap='I'>per_visual_info</emphasis>: LISTofVISUALINFO
 172       </entry>
 173     </row>
 174   </tbody>
 175   </tgroup>
 176 </informaltable>
 177
 178 <para>
 179 where:
 180 </para>
 181
 182 <informaltable frame="none">
 183   <tgroup cols='1' align='left'>
 184   <colspec colname='c1' colsep="0" colwidth="1*"/>
 185   <tbody>
 186     <row rowsep="0">
 187       <entry>
 188 VISUALINFO: [core_visual_id: VISUALID
 189       </entry>
 190     </row>
 191     <row rowsep="0">
 192       <entry>
 193 screen: CARD8
 194       </entry>
 195     </row>
 196     <row rowsep="0">
 197       <entry>
 198 level: INT8
 199       </entry>
 200     </row>
 201     <row rowsep="0">
 202       <entry>
 203 transparency_type: CARD8
 204       </entry>
 205     </row>
 206     <row rowsep="0">
 207       <entry>
 208 unused: CARD8
 209       </entry>
 210     </row>
 211     <row rowsep="0">
 212       <entry>
 213 transparency_value: CARD32
 214       </entry>
 215     </row>
 216     <row rowsep="0">
 217       <entry>
 218 min_hw_colormaps: CARD8
 219       </entry>
 220     </row>
 221     <row rowsep="0">
 222       <entry>
 223 max_hw_colormaps: CARD8
 224       </entry>
 225     </row>
 226     <row rowsep="0">
 227       <entry>
 228 num_colormap_conflicts: CARD16
 229       </entry>
 230     </row>
 231     <row rowsep="0">
 232       <entry>
 233 colormap_conflicts: LISTofVISUALID]
 234       </entry>
 235     </row>
 236   </tbody>
 237   </tgroup>
 238 </informaltable>
 239
 240 <itemizedlist>
 241   <listitem>
 242     <para>
 243 level is 0 for normal planes, &gt; 0 for overlays, &lt; 0 for underlays.
 244     </para>
 245   </listitem>
 246   <listitem>
 247     <para>
 248 transparency_type is 0 for none, 1 for transparent pixel, 2 for
 249 transparent mask.
 250     </para>
 251   </listitem>
 252   <listitem>
 253     <para>
 254 transparency_value: value to get transparent pixel if transparency
 255 supported.
 256     </para>
 257   </listitem>
 258   <listitem>
 259     <para>
 260 min_hw_colormaps: minimum number of hardware colormaps backing up the
 261 visual.
 262     </para>
 263   </listitem>
 264   <listitem>
 265     <para>
 266 max_hw_colormaps: maximum number of hardware colormaps backing up the
 267 visual.
 268     </para>
 269     <para>
 270     (architectures with static colormap allocation/reallocation would have min
 271 = max)
 272     </para>
 273   </listitem>
 274   <listitem>
 275     <para>
 276 num_colormap_conflicts: number of elements in colormap_conflicts.
 277     </para>
 278   </listitem>
 279   <listitem>
 280     <para>
 281 colormap_conflicts: list of visuals that may conflict with this one. For
 282 example, if a 12-bit colormap is overloaded to support 8-bit visuals, the
 283 8-bit visuals would conflict with the 12-bit visuals.
 284     </para>
 285   </listitem>
 286 </itemizedlist>
 287
 288 </sect1>
 289 <sect1 id="Events_and_Errors">
 290 <title>Events and Errors</title>
 291 <para>
 292 No new events or errors are defined by this extension.
 293 </para>
 294 </sect1>
 295
 296 <sect1 id="Changes_to_existing_protocol_">
 297 <title>Changes to existing protocol.</title>
 298 <para>
 299 None.
 300 </para>
 301 </sect1>
 302
 303 <sect1 id="Encoding">
 304 <title>Encoding</title>
 305 <para>
 306 The name of this extension is "Extended-Visual-Information".
 307 </para>
 308
 309 <para>
 310 The conventions used here are the same as those for the core X11
 311 Protocol Encoding.
 312 </para>
 313
 314 <literallayout class="monospaced">
 315 <function>GetVersion</function>
 316      1     CARD8               opcode
 317      1     0                   EVI opcode
 318      2     2                   request length
 319      2     CARD16              client_major_version
 320      2     CARD16              client_minor_version
 321 =&gt;
 322      1     1                   reply
 323      1                         unused
 324      2     CARD16              sequence number
 325      4     0                   length
 326      2     CARD16              server_major_version
 327      2     CARD16              server_minor_version
 328      20                        unused
 329 </literallayout>
 330
 331 <literallayout class="monospaced">
 332 <function>GetVisualInfo</function>
 333      1     CARD8               opcode
 334      1     1                   EVI opcode
 335      2     2+n                 request length
 336      4     CARD32              n_visual
 337      4n    CARD32              visual_ids
 338 =&gt;
 339      1     1                   reply
 340      1                         unused
 341      2     CARD16              sequence number
 342      4     n                   length
 343      4     CARD32              n_info
 344      4     CARD32              n_conflicts
 345      16                        unused
 346      16n   LISTofVISUALINFO    items
 347 </literallayout>
 348
 349 <literallayout class="monospaced">
 350 VISUALINFO
 351      4     VisualID            core_visual_id
 352      1     INT8                screen
 353      1     INT8                level
 354      1     CARD8               transparency_type
 355      1     CARD8               unused
 356      4     CARD32              transparency_value
 357      1     CARD8               min_hw_colormaps
 358      1     CARD8               max_hw_colormaps
 359      2     CARD16              num_colormap_conflicts
 360 </literallayout>
 361 </sect1>
 362
 363 <sect1 id="C_Language_Binding">
 364 <title>C Language Binding</title>
 365 <para>
 366 <!-- .LP -->
 367 The C functions provide direct access to the protocol and add no additional
 368 semantics.  For complete details on the effects of these functions, refer
 369 to the appropriate protocol request, which can be derived by deleting Xevi
 370 at the start of the function. All functions that have return type Status
 371 will return nonzero for success and zero for failure.
 372 </para>
 373
 374 <para>
 375 The include file for this extension is:
 376 <function>&lt; X11/extensions/XEVI.h&gt;</function>.
 377 </para>
 378
 379 <funcsynopsis>
 380 <funcprototype>
 381   <funcdef>Bool <function> XeviQueryVersion</function></funcdef>
 382   <paramdef>Display<parameter> *display</parameter></paramdef>
 383   <paramdef>int<parameter> *major_version_return</parameter></paramdef>
 384   <paramdef>int<parameter> *minor_version_return</parameter></paramdef>
 385 </funcprototype>
 386 </funcsynopsis>
 387
 388 <variablelist>
 389   <varlistentry>
 390     <term>
 391       <emphasis remap='I'>display</emphasis>
 392     </term>
 393     <listitem>
 394       <para>
 395 Specifies the connection to the X server.
 396       </para>
 397     </listitem>
 398   </varlistentry>
 399   <varlistentry>
 400     <term>
 401       <emphasis remap='I'>major_version_return</emphasis>
 402     </term>
 403     <listitem>
 404       <para>
 405 Returns the major version supported by the server.
 406       </para>
 407     </listitem>
 408   </varlistentry>
 409   <varlistentry>
 410     <term>
 411       <emphasis remap='I'>minor_version_return</emphasis>
 412     </term>
 413     <listitem>
 414       <para>
 415 Returns the minor version supported by the server.
 416     </para>
 417   </listitem>
 418   </varlistentry>
 419 </variablelist>
 420
 421 <para>
 422 XeviQueryVersion sets major_version_return and minor_version_return to
 423 the major and minor EVI protocol version supported by the server.  If
 424 the EVI library is compatible with the version returned by the server,
 425 it returns nonzero.  If dpy does not support the EVI extension, or if
 426 there was an error during communication with the server, or if the server
 427 and library protocol versions are incompatible, it returns zero.  No other
 428 Xevi functions may be called before this function. If a client violates
 429 this rule, the effects of all subsequent Xevi calls that it makes are
 430 undefined.
 431 </para>
 432
 433 <para>
 434 To get the extended information for any subset of visuals use
 435 XeviGetVisualInfo.
 436 </para>
 437
 438 <funcsynopsis>
 439 <funcprototype>
 440   <funcdef>int <function> XeviGetVisualInfo</function></funcdef>
 441   <paramdef>Display<parameter> *display</parameter></paramdef>
 442   <paramdef>VisualID<parameter> *visual</parameter></paramdef>
 443   <paramdef>int<parameter> n_visual</parameter></paramdef>
 444   <paramdef>ExtendedVisualInfo<parameter> **evi_return</parameter></paramdef>
 445   <paramdef>int<parameter> *n_info_return</parameter></paramdef>
 446 </funcprototype>
 447 </funcsynopsis>
 448
 449 <variablelist>
 450   <varlistentry>
 451     <term>
 452       <emphasis remap='I'>display</emphasis>
 453     </term>
 454     <listitem>
 455       <para>
 456 Specifies the connection to the X server.
 457       </para>
 458     </listitem>
 459   </varlistentry>
 460   <varlistentry>
 461     <term>
 462       <emphasis remap='I'>visual</emphasis>
 463     </term>
 464     <listitem>
 465       <para>
 466 If NULL, then information for all visuals of all
 467 screens is returned. Otherwise, a pointer to a list of visuals for which
 468 extended visual information is desired.
 469       </para>
 470     </listitem>
 471   </varlistentry>
 472   <varlistentry>
 473     <term>
 474       <emphasis remap='I'>n_visual</emphasis>
 475     </term>
 476     <listitem>
 477       <para>
 478 If 0, then information for all visuals of all screens is returned. Otherwise,
 479 the number of elements in the array <emphasis remap='I'>visual</emphasis>.
 480       </para>
 481     </listitem>
 482   </varlistentry>
 483   <varlistentry>
 484     <term>
 485       <emphasis remap='I'>evi_return</emphasis>
 486     </term>
 487     <listitem>
 488       <para>
 489 Returns a pointer to a list of <emphasis remap='I'>ExtendedVisualInfo</emphasis>. When done, the client
 490 should free the list using <emphasis remap='I'>XFree</emphasis>.
 491       </para>
 492     </listitem>
 493   </varlistentry>
 494   <varlistentry>
 495     <term>
 496       <emphasis remap='I'>n_info_return</emphasis>
 497     </term>
 498     <listitem>
 499       <para>
 500 Returns the number of elements in the list of
 501 <emphasis remap='I'>ExtendedVisualInfo</emphasis>.
 502     </para>
 503   </listitem>
 504   </varlistentry>
 505 </variablelist>
 506
 507 <para>
 508 XeviGetVisualInfo returns a list of ExtendedVisualInfo structures that describe
 509 visual information beyond that supported by the core protocol. This includes
 510 layer information relevant for systems supporting overlays and/or underlay
 511 planes, and information that allows applications better to determine the level
 512 of hardware support for multiple colormaps. XeviGetVisualInfo returns Success
 513 if successful, or an X error otherwise.
 514 </para>
 515
 516 </sect1>
 517 </chapter>
 518 </book>