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