specs/dbe.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3           "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4
   5
   6 <!--
   7 by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)
   8 xhtml,docbook,html,refcaption -->
   9
  10 <book id="dbe">
  11
  12 <bookinfo>
  13   <title>Double Buffer Extension Protocol</title>
  14   <subtitle>X Consortium Standard</subtitle>
  15   <releaseinfo>X Version 11, Release 6.4</releaseinfo>
  16   <authorgroup>
  17    <author>
  18      <firstname>Ian</firstname><surname>Elliott</surname>
  19    </author>
  20   </authorgroup>
  21   <othercredit>
  22    <firstname>David</firstname><surname>Wiggins</surname>
  23    <affiliation><orgname>X Consortium</orgname></affiliation>
  24   </othercredit>
  25   <corpname>Hewlett-Packard Company</corpname>
  26   <copyright>
  27    <year>1989</year>
  28    <holder>X Consortium, Inc and Digital Equipment Corporation</holder>
  29   </copyright>
  30   <copyright>
  31    <year>1992</year>
  32    <holder>X Consortium, Inc and Intergraph Corporation</holder>
  33   </copyright>
  34   <copyright>
  35    <year>1993</year>
  36    <holder>X Consortium, Inc and Silicon Graphics, Inc</holder>
  37   </copyright>
  38   <copyright>
  39    <year>1994</year>
  40    <holder>X Consortium, Inc and Hewlett-Packard Company</holder>
  41   </copyright>
  42   <releaseinfo>Version 1.0</releaseinfo>
  43
  44 <legalnotice>
  45 <para>
  46 Permission to use, copy, modify, and distribute this documentation for any
  47 purpose and without fee is hereby granted, provided that the above copyright
  48 notice and this permission notice appear in all copies. Digital Equipment
  49 Corporation, Intergraph Corporation, Silicon Graphics, Hewlett-Packard, and
  50 the X Consortium make no representations about the suitability for any purpose
  51 of the information in this document. This documentation is provided "as is"
  52 without express or implied warranty.
  53 </para>
  54 </legalnotice>
  55 </bookinfo>
  56
  57 <chapter id="introduction">
  58 <title>Introduction</title>
  59 <para>The Double Buffer Extension (DBE) provides a standard way to utilize
  60 double-buffering within the framework of the X Window System. Double-buffering
  61 uses two buffers, called front and back, which hold images. The front buffer
  62 is visible to the user; the back buffer is not. Successive frames of an
  63 animation are rendered into the back buffer while the previously rendered
  64 frame is displayed in the front buffer. When a new frame is ready, the back
  65 and front buffers swap roles, making the new frame visible. Ideally, this
  66 exchange appears to happen instantaneously to the user and with no visual
  67 artifacts. Thus, only completely rendered images are presented to the user,
  68 and they remain visible during the entire time it takes to render a new frame.
  69 The result is a flicker-free animation.
  70 </para>
  71 </chapter>
  72
  73 <chapter id="goals">
  74 <title>Goals</title>
  75 <para>This extension should enable clients to:
  76 </para>
  77
  78 <itemizedlist>
  79   <listitem>
  80     <para>Allocate and deallocate double-buffering for a window.</para>
  81   </listitem>
  82   <listitem>
  83     <para>
  84 Draw to and read from the front and back buffers associated with a window.
  85     </para>
  86   </listitem>
  87   <listitem>
  88     <para>Swap the front and back buffers associated with a window.</para>
  89   </listitem>
  90   <listitem>
  91     <para>
  92 Specify a wide range of actions to be taken when a window is swapped.
  93 This includes explicit, simple swap actions (defined below), and more
  94 complex actions (for example, clearing ancillary buffers) that can be put
  95 together within explicit "begin" and "end" requests (defined below).
  96     </para>
  97   </listitem>
  98   <listitem>
  99     <para>
 100 Request that the front and back buffers associated with multiple
 101 double-buffered windows be swapped simultaneously.
 102     </para>
 103   </listitem>
 104 </itemizedlist>
 105
 106 <para>
 107 In addition, the extension should:
 108 </para>
 109
 110 <itemizedlist>
 111   <listitem>
 112     <para>
 113 Allow multiple clients to use double-buffering on the same window.</para>
 114   </listitem>
 115   <listitem>
 116     <para>
 117 Support a range of implementation methods that can capitalize on existing
 118 hardware features.
 119     </para>
 120   </listitem>
 121   <listitem>
 122     <para>Add no new event types.</para>
 123   </listitem>
 124   <listitem>
 125     <para>
 126 Be reasonably easy to integrate with a variety of direct graphics hardware
 127 access (DGHA) architectures.
 128     </para>
 129   </listitem>
 130 </itemizedlist>
 131
 132 </chapter>
 133
 134 <chapter id="concepts">
 135 <title>Concepts</title>
 136
 137 <para>
 138 Normal windows are created using the core <function>CreateWindow</function>
 139 request, which allocates a set of window attributes and, for InputOutput
 140 windows, a front buffer, into which an image can be drawn. The contents of
 141 this buffer will be displayed when the window is visible.
 142 </para>
 143 <para>
 144 This extension enables applications to use double-buffering with a window.
 145 This involves creating a second buffer, called a back buffer, and associating
 146 one or more back buffer names (XIDs) with the window for use when referring to
 147 (that is, drawing to or reading from) the window's back buffer. The back
 148 buffer name is a DRAWABLE of type BACKBUFFER.
 149 </para>
 150
 151 <para>
 152 DBE provides a relative double-buffering model. One XID, the window, always
 153 refers to the front buffer. One or more other XIDs, the back buffer names,
 154 always refer to the back buffer. After a buffer swap, the window continues to
 155 refer to the (new) front buffer, and the back buffer name continues to refer
 156 to the (new) back buffer. Thus, applications and toolkits that want to just
 157 render to the back buffer always use the back buffer name for all drawing
 158 requests to the window. Portions of an application that want to render to
 159 the front buffer always use the window XID for all drawing requests to the
 160 window.
 161 </para>
 162
 163 <para>
 164 Multiple clients and toolkits can all use double-buffering on the same
 165 window. DBE does not provide a request for querying whether a window has
 166 double-buffering support, and if so, what the back buffer name is. Given
 167 the asynchronous nature of the X Window System, this would cause race
 168 conditions. Instead, DBE allows multiple back buffer names to exist for
 169 the same window; they all refer to the same physical back buffer. The first
 170 time a back buffer name is allocated for a window, the window becomes
 171 double-buffered and the back buffer name is associated with the window.
 172 Subsequently, the window already is a double-buffered window, and nothing
 173 about the window changes when a new back buffer name is allocated, except
 174 that the new back buffer name is associated with the window. The window
 175 remains double-buffered until either the window is destroyed or until all of
 176 the back buffer names for the window are deallocated.
 177 </para>
 178
 179 <para>
 180 In general, both the front and back buffers are treated the same. In
 181 particular, here are some important characteristics:
 182 </para>
 183
 184 <itemizedlist>
 185   <listitem>
 186     <para>
 187 Only one buffer per window can be visible at a time (the front buffer).
 188     </para>
 189   </listitem>
 190   <listitem>
 191     <para>
 192 Both buffers associated with a window have the same visual type, depth,
 193 width, height, and shape as the window.
 194     </para>
 195   </listitem>
 196   <listitem>
 197     <para>
 198 Both buffers associated with a window are "visible" (or "obscured") in
 199 the same way. When an Expose event is generated for a window, both
 200 buffers should be considered to be damaged in the exposed area. Damage
 201 that occurs to either buffer will result in an Expose event on the window.
 202 When a double-buffered window is exposed, both buffers are tiled with the
 203 window background, exactly as stated by the core protocol. Even though
 204 the back buffer is not visible, terms such as obscure apply to the back
 205 buffer as well as to the front buffer.
 206     </para>
 207   </listitem>
 208   <listitem>
 209     <para>
 210 It is acceptable at any time to pass a BACKBUFFER in any
 211 request, notably any core or extension drawing request, that expects
 212 a DRAWABLE. This enables an application to draw directly into
 213 BACKBUFFERs in the same fashion as it would draw into any other
 214 DRAWABLE.
 215     </para>
 216   </listitem>
 217   <listitem>
 218     <para>
 219 It is an error (Window) to pass a BACKBUFFER in a core request that
 220 expects a Window.
 221     </para>
 222   </listitem>
 223   <listitem>
 224     <para>
 225 A BACKBUFFER will never be sent by core X in a reply, event, or error
 226 where a Window is specified.
 227     </para>
 228   </listitem>
 229   <listitem>
 230     <para>
 231 If core X11 backing-store and save-under applies to a double-buffered
 232 window, it applies to both buffers equally.
 233     </para>
 234   </listitem>
 235   <listitem>
 236     <para>
 237 If the core <function>ClearArea</function> request is executed on a
 238 double-buffered window, the same area in both the front and back buffers
 239 is cleared.
 240     </para>
 241   </listitem>
 242 </itemizedlist>
 243 <para>
 244 The effect of passing a window to a request that accepts a DRAWABLE is
 245 unchanged by this extension. The window and front buffer are synonomous with
 246 each other. This includes obeying the <function>GetImage</function> semantics
 247 and the subwindow-mode semantics if a core graphics context is involved.
 248 Regardless of whether the window was explicitly passed in a
 249 <function>GetImage</function> request, or implicitly referenced (that is,
 250 one of the windo's ancestors was passed in the request), the front (that is,
 251 visible) buffer is always referenced. Thus, DBE-naive screen dump clients will
 252 always get the front buffer. <function>GetImage</function> on a back buffer
 253 returns undefined image contents for any obscured regions of the back buffer
 254 that fall within the image.
 255 </para>
 256
 257 <para>
 258 Drawing to a back buffer always uses the clip region that would be used to
 259 draw to the front buffer with a GC subwindow-mode of
 260 <function>ClipByChildren</function>. If an
 261 ancestor of a double-buffered window is drawn to with a core GC having a
 262 subwindow-mode of <function>IncludeInferiors</function>, the effect on the
 263 double-buffered window's back buffer depends on the depth of the
 264 double-buffered window and the ancestor. If the depths are the same, the
 265 contents of the back buffer of the double-buffered window are not changed.
 266 If the depths are different, the contents of the back buffer of the
 267 double-buffered window are undefined for the pixels that the
 268 <function>IncludeInferiors</function> drawing touched.
 269 </para>
 270
 271 <para>
 272 DBE adds no new events. DBE does not extend the semantics of any existing
 273 events with the exception of adding a new DRAWABLE type called BACKBUFFER. If
 274 events, replies, or errors that contain a DRAWABLE (for example,
 275 <function>GraphicsExpose</function>) are generated in response to a request,
 276 the DRAWABLE returned will be the one specified in the request.
 277 </para>
 278
 279 <para>
 280 DBE advertises which visuals support double-buffering.
 281 </para>
 282
 283 <para>
 284 DBE does not include any timing or synchronization facilities.
 285 Applications that need such facilities (for example, to maintain a constant
 286 frame rate) should investigate the Synchronization Extension, an X
 287 Consortium standard.
 288 </para>
 289
 290 <sect1 id="window_management_operations">
 291 <title>Window Management Operations</title>
 292
 293 <para>
 294 The basic philosophy of DBE is that both buffers are treated the same by core
 295 X window management operations.
 296 </para>
 297
 298 <para>
 299 When the core <function>DestroyWindow</function> is executed on a
 300 double-buffered window, both buffers associated with the window are
 301 destroyed, and all back buffer names associated with the window are freed.
 302 </para>
 303
 304 <para>
 305 If the core <function>ConfigureWindow</function> request changes the size of
 306 a window, both buffers assume the new size. If the windo's size increases,
 307 the effect on the buffers depends on whether the implementation honors bit
 308 gravity for buffers. If bit gravity is implemented, then the contents of
 309 both buffers are moved in accordance with the windo's bit gravity (see the
 310 core <function>ConfigureWindow</function> request), and the remaining areas
 311 are tiled with the window background. If bit gravity is not implemented, then
 312 the entire unobscured region of both buffers is tiled with the window
 313 background. In either case, <function>Expose</function> events are generated
 314 for the region that is tiled with the window background.
 315 </para>
 316
 317 <para>
 318 If the core <function>GetGeometry</function> request is executed on a
 319 BACKBUFFER, the returned x, y, and border-width will be zero.
 320 </para>
 321
 322 <para>
 323 If the Shape extension <function>ShapeRectangles</function>,
 324 <function>ShapeMask</function>,
 325 <function>ShapeCombine</function>, or
 326 <function>ShapeOffset</function>
 327 request is executed on a double-buffered window, both buffers are reshaped
 328 to match the new window shape. The region difference is the following:
 329 </para>
 330
 331 <literallayout>
 332    D = newshape - oldshape
 333 </literallayout>
 334
 335 <para>
 336 It is tiled with the window background in both buffers, and
 337 <function>Expose</function> events are generated for D.
 338 </para>
 339
 340 </sect1>
 341
 342 <sect1 id="complex_swap_actions">
 343 <title>Complex Swap Actions</title>
 344 <para>
 345 DBE has no explicit knowledge of ancillary buffers (for example, depth
 346 buffers or alpha buffers), and only has a limited set of defined swap
 347 actions. Some applications may need a richer set of swap actions than DBE
 348 provides. Some DBE implementations have knowledge of ancillary buffers,
 349 and/or can provide a rich set of swap actions. Instead of continually
 350 extending DBE to increase its set of swap actions, DBE provides a flexible
 351 "idiom" mechanism. If an application's needs are served by the defined swap
 352 actions, it should use them; otherwise, it should use the following method
 353 of expressing a complex swap action as an idiom. Following this policy will
 354 ensure the best possible performance across a wide variety of implementations.
 355 </para>
 356
 357 <para>
 358 As suggested by the term "idiom," a complex swap action should be expressed
 359 as a group/series of requests. Taken together, this group of requests may be
 360 combined into an atomic operation by the implementation, in order to maximize
 361 performance. The set of idioms actually recognized for optimization is
 362 implementation dependent. To help with idiom expression and interpretation,
 363 an idiom must be surrounded by two protocol requests:
 364 <function>DBEBeginIdiom</function> and
 365 <function>DBEEndIdiom</function>. Unless this begin-end pair
 366 surrounds the idiom, it may not be recognized by a given implementation, and
 367 performance will suffer.
 368 </para>
 369
 370 <para>
 371 For example, if an application wants to swap buffers for two windows, and
 372 use core X to clear only certain planes of the back buffers, the application
 373 would issue the following protocol requests as a group, and in the following
 374 order:
 375 </para>
 376
 377 <itemizedlist>
 378   <listitem>
 379     <para>DBEBeginIdiom request.</para>
 380   </listitem>
 381   <listitem>
 382     <para>
 383 <function>DBESwapBuffers</function> request with XIDs for two windows, each of which uses
 384 a swap action of Untouched.
 385     </para>
 386   </listitem>
 387   <listitem>
 388     <para>
 389 Core X PolyFillRectangle request to the back buffer of one window.
 390     </para>
 391   </listitem>
 392   <listitem>
 393     <para>
 394 Core X PolyFillRectangle request to the back buffer of the other window.
 395     </para>
 396   </listitem>
 397   <listitem>
 398     <para>DBEEndIdiom request.</para>
 399   </listitem>
 400 </itemizedlist>
 401
 402 <para>
 403 The <function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>
 404 requests do not perform any actions themselves. They are treated as markers
 405 by implementations that can combine certain groups/series of requests as
 406 idioms, and are ignored by other implementations or for nonrecognized
 407 groups/series of requests. If these requests are sent out of order, or are
 408 mismatched, no errors are sent, and the requests are executed as usual,
 409 though performance may suffer.
 410 </para>
 411
 412 <para>
 413 An idiom need not include a <function>DBESwapBuffers</function> request. For
 414 example, if a swap action of Copied is desired, but only some of the planes
 415 should be copied, a core X
 416 <function>CopyArea</function> request may be used instead of
 417 <function>DBESwapBuffers</function>.
 418 If <function>DBESwapBuffers</function> is included in an idiom, it should
 419 immediately follow the <function>DBEBeginIdiom</function> request. Also, when
 420 the <function>DBESwapBuffers</function> is included in an idiom, that
 421 request's swap action will still be valid, and if the swap action might
 422 overlap with another request, then the final result of the idiom must be as if
 423 the separate requests were executed serially. For example, if the specified
 424 swap action is Untouched, and if a <function>PolyFillRectangle</function>
 425 using a client clip rectangle is done to the windo's back buffer after the
 426 <function>DBESwapBuffers</function> request, then the contents of the new
 427 back buffer (after the idiom) will be the same as if the idiom was not
 428 recognized by the implementation.
 429 </para>
 430
 431 <para>
 432 It is highly recommended that Application Programming Interface (API)
 433 providers define, and application developers use, "convenience" functions
 434 that allow client applications to call one procedure that encapsulates
 435 common idioms. These functions will generate the
 436 <function>DBEBeginIdiom</function> request, the idiom requests, and
 437 <function>DBEEndIdiom</function> request. Usage of these functions will
 438 ensure best possible performance across a wide variety of implementations.
 439 </para>
 440
 441 </sect1>
 442 </chapter>
 443
 444 <chapter id="requests">
 445 <title>Requests</title>
 446 <para>The DBE defines the following requests.</para>
 447
 448 <sect1 id="dbegetversion">
 449 <title>DBEGetVersion</title>
 450 <para>
 451 This request returns the major and minor version numbers of this extension.
 452 </para>
 453
 454 <para>DBEGetVersion</para>
 455 <informaltable>
 456   <tgroup cols="2">
 457     <colspec colname="c1"/>
 458     <colspec colname="c2" />
 459     <tbody>
 460       <row>
 461         <entry align="left">client-major-version</entry>
 462         <entry align="left">CARD8</entry>
 463       </row>
 464       <row>
 465         <entry align="left">client-minor-version </entry>
 466         <entry align="left">CARD8</entry>
 467       </row>
 468       <row>
 469         <entry align="left">=></entry>
 470         <entry align="left"></entry>
 471       </row>
 472       <row>
 473         <entry align="left">server-major-version </entry>
 474         <entry align="left">CARD8</entry>
 475       </row>
 476       <row>
 477         <entry align="left">server-minor-version </entry>
 478         <entry align="left">CARD8</entry>
 479       </row>
 480     </tbody>
 481   </tgroup>
 482 </informaltable>
 483
 484 <para>
 485 The client-major-version and client-minor-version numbers indicate what
 486 version of the protocol the client wants the server to implement. The
 487 server-major-version and the server-minor-version numbers returned indicate
 488 the protocol this extension actually supports. This might not equal the
 489 version sent by the client. An implementation can (but need not) support
 490 more than one version simultaneously.  The server-major-version and
 491 server-minor-version allow the creation of future revisions of the DBE
 492 protocol that may be necessary. In general, the major version
 493 would increment for incompatible changes, and the minor version would increment
 494 for small, upward-compatible changes. Servers that support the protocol
 495 defined in this document will return a server-major-version of one (1), and a
 496 server-minor-version of zero (0).
 497 </para>
 498
 499 <para>
 500 The DBE client must issue a DBEGetVersion request before any other double
 501 buffering request in order to negotiate a compatible protocol version;
 502 otherwise, the client will get undefined behavior (DBE may or may not work).
 503 </para>
 504
 505 </sect1>
 506
 507 <sect1 id="dbegetvisualinfo">
 508 <title>DBEGetVisualInfo</title>
 509 <para>
 510 This request returns information about which visuals support double buffering.
 511 </para>
 512
 513 <para>DBEGetVisualInfo</para>
 514
 515 <informaltable>
 516   <tgroup cols="2">
 517     <colspec colname="c1"/>
 518     <colspec colname="c2"/>
 519     <tbody>
 520       <row>
 521         <entry align="left">screen-specifiers</entry>
 522         <entry align="left">LISTofDRAWABLE</entry>
 523       </row>
 524       <row>
 525         <entry align="left">=></entry>
 526         <entry align="left"></entry>
 527       </row>
 528       <row>
 529         <entry align="left">visinfo</entry>
 530         <entry align="left">LISTofSCREENVISINFO</entry>
 531       </row>
 532     </tbody>
 533   </tgroup>
 534 </informaltable>
 535 <para>where:</para>
 536
 537 <informaltable>
 538   <tgroup cols="2">
 539     <colspec colname="c1"/>
 540     <colspec colname="c2"/>
 541     <tbody>
 542       <row>
 543         <entry align="left">SCREENVISINFO</entry>
 544         <entry align="left">LISTofVISINFO</entry>
 545       </row>
 546       <row>
 547         <entry align="left">VISINFO</entry>
 548         <entry align="left">[ visual: VISUALID</entry>
 549       </row>
 550       <row>
 551         <entry align="left"></entry>
 552         <entry align="left">depth: CARD8</entry>
 553       </row>
 554       <row>
 555         <entry align="left"></entry>
 556         <entry align="left">perflevel: CARD8 ]</entry>
 557       </row>
 558     </tbody>
 559   </tgroup>
 560 </informaltable>
 561
 562 <para>Errors: Drawable</para>
 563
 564 <para>
 565 All of the values passed in screen-specifiers must be valid DRAWABLEs (or a
 566 <function>Drawable</function> error results). For each drawable in
 567 screen-specifiers, the reply will contain a list of VISINFO structures for
 568 visuals that support double-buffering on the screen on which the drawable
 569 resides. The visual member specifies the VISUALID. The depth member specifies
 570 the depth in bits for the visual. The perflevel is a performance hint. The
 571 only operation defined on a perflevel is comparison to a perflevel of another
 572 visual on the same screen. The visual having the higher perflevel is likely
 573 to have better double-buffer graphics performance than the visual having the
 574 lower perflevel. Nothing can be deduced from any of the following: the
 575 magnitude of the difference of two perflevels, a perflevel value in isolation,
 576 or comparing perflevels from different servers.
 577 </para>
 578
 579 <para>
 580 If the list of screen-specifiers is empty, information for all screens is
 581 returned, starting with screen zero.
 582 </para>
 583
 584 </sect1>
 585
 586 <sect1 id="dbeallocatebackbuffername">
 587 <title>DBEAllocateBackBufferName</title>
 588
 589 <para>
 590 This request allocates a drawable ID used to refer to the back buffer of a
 591 window.
 592 </para>
 593
 594 <para>DBEAllocateBackBufferName</para>
 595
 596 <informaltable>
 597   <tgroup cols="2">
 598     <colspec colname="c1"/>
 599     <colspec colname="c2"/>
 600     <tbody>
 601       <row>
 602         <entry align="left">window</entry>
 603         <entry align="left">WINDOW</entry>
 604       </row>
 605       <row>
 606         <entry align="left">back-buffer-name</entry>
 607         <entry align="left">BACKBUFFER</entry>
 608       </row>
 609       <row>
 610         <entry align="left">swap-action-hint</entry>
 611         <entry align="left">SWAPACTION </entry>
 612       </row>
 613     </tbody>
 614   </tgroup>
 615 </informaltable>
 616
 617 <para>
 618 Errors: Alloc, Value, IDChoice, Match, Window
 619 </para>
 620
 621 <para>
 622 If the window is not already a double-buffered window, the window becomes
 623 double-buffered, and the back-buffer-name is associated with the window. The
 624 swap-action-hint tells the server which swap action is most likely to be
 625 used with the window in subsequent <function>DBESwapBuffers</function>
 626 requests. The swap-action-hint must have one of the values specified for type
 627 SWAPACTION (or a Value error results). See the description of the
 628 <function>DBESwapBuffers</function> request for a complete discussion of
 629 swap actions and the SWAPACTION type.
 630 </para>
 631
 632 <para>
 633 If the window already is a double-buffered window, nothing about the window
 634 changes, except that an additional back-buffer-name is associated with the
 635 window.  The window remains double-buffered until either the window is
 636 destroyed, or until all of the back buffer names for the window are
 637 deallocated.
 638 </para>
 639
 640 <para>
 641 The window passed into the request must be a valid WINDOW (or a Window error
 642 results). The window passed into the request must be an InputOutput window (or
 643 a Match error results). The visual of the window must be in the list returned
 644 by <function>DBEGetVisualInfo</function> (or a Match error results). The
 645 back-buffer-name must be in the range assigned to the client, and must not
 646 already be in use (or an IDChoice error results). If the server cannot
 647 allocate all resources associated with turning on double-buffering for the
 648 window, an Alloc error results, the windo's double-buffer status (whether it
 649 is already double-buffered or not) remains unchanged, and the
 650 back-buffer-name is freed.
 651 </para>
 652 </sect1>
 653
 654 <sect1 id="dbedeallocatebackbuffername">
 655 <title>DBEDeallocateBackBufferName</title>
 656 <para>
 657 This request frees a drawable ID that was obtained by
 658 <function>DBEAllocateBackBufferName</function>.
 659 </para>
 660
 661 <para>DBEDeallocateBackBufferName</para>
 662
 663 <informaltable>
 664   <tgroup cols="2">
 665   <colspec colname="c1"/>
 666   <colspec colname="c2"/>
 667   <tbody>
 668     <row>
 669       <entry align="left">back-buffer-name</entry>
 670       <entry align="left">BACKBUFFER</entry>
 671     </row>
 672   </tbody>
 673   </tgroup>
 674 </informaltable>
 675
 676 <para>Errors: Buffer</para>
 677
 678 <para>
 679 The back-buffer-name passed in the request is freed and no longer associated
 680 with the window. If this is the last back-buffer-name associated with the
 681 window, then the back buffer is no longer accessible to clients, and all
 682 double-buffering resources associated with the window may be freed. The
 683 window's current front buffer remains the front buffer.
 684 </para>
 685
 686 <para>
 687 The back-buffer-name must be a valid BACKBUFFER associated with a window (or
 688 a Buffer error results).
 689 </para>
 690 </sect1>
 691
 692 <sect1 id="dbeswapbuffers">
 693 <title>DBESwapBuffers</title>
 694 <para>
 695 This request swaps the buffers for all windows listed, applying the
 696 appropriate swap action for each window.
 697 </para>
 698
 699 <para><function>DBESwapBuffers</function></para>
 700
 701 <informaltable>
 702   <tgroup cols="2">
 703   <colspec colname="c1" /><colspec colname="c2"/>
 704   <tbody>
 705     <row>
 706       <entry align="left">windows</entry>
 707       <entry align="left">LISTofSWAPINFO</entry>
 708     </row>
 709   </tbody>
 710   </tgroup>
 711 </informaltable>
 712 <para>where:</para>
 713 <informaltable>
 714   <tgroup cols="2">
 715   <colspec colname="c1" /><colspec colname="c2"/>
 716   <tbody>
 717     <row>
 718       <entry align="left">SWAPINFO</entry>
 719       <entry align="left">[ window: WINDOW</entry>
 720     </row>
 721     <row>
 722       <entry align="left"></entry>
 723       <entry align="left">swap-action: SWAPACTION ]</entry>
 724     </row>
 725     <row>
 726       <entry align="left">SWAPACTION</entry>
 727       <entry align="left">{ Undefined, Background, Untouched, Copied }</entry>
 728     </row>
 729   </tbody>
 730   </tgroup>
 731 </informaltable>
 732
 733 <para>Errors: Match, Window, Value</para>
 734
 735 <para>
 736 Each window passed into the request must be a valid WINDOW (or a
 737 <function>Window</function> error results). Each window passed into the
 738 request must be a double-buffered window (or a <function>Match</function>
 739 error results). Each window passed into the request must only be listed
 740 once (or a <function>Match</function> error results). Each swap-action in
 741 the list must have one of the values specified for type SWAPACTION (or a
 742 <function>Value</function> error results). If an error results, none of
 743 the valid double-buffered windows will have their buffers swapped.
 744 </para>
 745
 746 <para>
 747 The swap-action determines what will happen to the new back buffer of the
 748 window it is paired with in the list in addition to making the old back
 749 buffer become visible.  The defined actions are as follows:
 750 </para>
 751
 752 <variablelist>
 753   <varlistentry>
 754     <term>Undefined</term>
 755       <listitem><para>
 756 The contents of the new back buffer become undefined. This may be the
 757 most efficient action since it allows the implementation to discard the
 758 contents of the buffer if it needs to.
 759       </para></listitem>
 760   </varlistentry>
 761   <varlistentry>
 762     <term>Background</term>
 763     <listitem><para>
 764 The unobscured region of the new back buffer will be tiled with the window
 765 background. The background action allows devices to use a fast clear
 766 capability during a swap.
 767     </para></listitem>
 768   </varlistentry>
 769   <varlistentry>
 770     <term>Untouched</term>
 771     <listitem><para>
 772 The unobscured region of the new back buffer will be unmodified by the swap.
 773     </para></listitem>
 774   </varlistentry>
 775   <varlistentry>
 776     <term>Copied</term>
 777     <listitem><para>
 778 The unobscured region of the new back buffer will be the contents of the
 779 old back buffer.
 780     </para></listitem>
 781   </varlistentry>
 782 </variablelist>
 783
 784 <para>
 785 If <function>DBESwapBuffers</function> is included in a "swap and clear"
 786 type of idiom, it must immediately follow the
 787 <function>DBEBeginIdiom</function> request.
 788 </para>
 789 </sect1>
 790
 791 <sect1 id="dbebeginidiom">
 792 <title>DBEBeginIdiom</title>
 793 <para>
 794 This request informs the server that a complex swap will immediately follow
 795 this request.
 796 </para>
 797
 798 <para><function>DBEBeginIdiom</function></para>
 799
 800 <para>
 801 As previously discussed, a complex swap action is a group/series of
 802 requests that, taken together, may be combined into an atomic operation by
 803 the implementation.  The sole function of this request is to serve as a
 804 "marker" that the server can use to aid in idiom processing. The server is
 805 free to implement this request as a no-op.
 806 </para>
 807 </sect1>
 808
 809 <sect1 id="dbeendidiom">
 810 <title>DBEEndIdiom</title>
 811
 812
 813 <para>
 814 This request informs the server that a complex swap has concluded.
 815 </para>
 816
 817 <para><function>DBEEndIdiom</function></para>
 818
 819 <para>
 820 The sole function of this request is to serve as a "marker" that the server
 821 can use to aid in idiom processing. The server is free to implement this
 822 request as a no-op.
 823 </para>
 824
 825 </sect1>
 826
 827 <sect1 id="dbegetbackbufferattributes">
 828 <title>DBEGetBackBufferAttributes</title>
 829
 830 <para>This request returns information about a back buffer.</para>
 831
 832 <para><function>DBEGetBackBufferAttributes</function></para>
 833
 834 <informaltable>
 835   <tgroup cols="2">
 836   <colspec colname="c1"/>
 837   <colspec colname="c2"/>
 838   <tbody>
 839     <row>
 840       <entry align="left">back-buffer-name</entry>
 841       <entry align="left">BACKBUFFER</entry>
 842     </row>
 843     <row>
 844       <entry align="left">=></entry>
 845       <entry align="left"></entry>
 846     </row>
 847     <row>
 848       <entry align="left">attributes</entry>
 849       <entry align="left">BUFFER_ATTRIBUTES</entry>
 850     </row>
 851   </tbody>
 852   </tgroup>
 853 </informaltable>
 854
 855 <para>where:</para>
 856
 857 <para>BUFFER_ATTRIBUTES: [ window: WINDOW ]</para>
 858
 859 <para>
 860 If back-buffer-name is a valid BACKBUFFER, the window field of the
 861 attributes in the reply will be the window which has the back buffer that
 862 back-buffer-name refers to. If back-buffer-name is not a valid BACKBUFFER,
 863 the window field of the attributes in the reply will be None.
 864 </para>
 865
 866 </sect1>
 867 </chapter>
 868
 869 <chapter id="encoding">
 870 <title>Encoding</title>
 871 <para>
 872 Please refer to the X11 Protocol Encoding document as this section uses
 873 syntactic conventions and data types established there.
 874 </para>
 875
 876 <para>The name of this extension is "DOUBLE-BUFFER".</para>
 877
 878 <sect1 id="type">
 879 <title>Type</title>
 880 <para>The following new types are used by the extension.
 881 </para>
 882
 883 <para>BACKBUFFER: XID</para>
 884 <para>SWAPACTION</para>
 885 <literallayout class="monospaced">
 886 #x00  Undefined
 887 #x01  Background
 888 #x02  Untouched
 889 #x03  Copied
 890 </literallayout>
 891
 892 <para>SWAPINFO</para>
 893 <literallayout class="monospaced">
 894 4     WINDOW                 window
 895 1     SWAPACTION             swap action
 896 3                            unused
 897 </literallayout>
 898
 899 <literallayout class="monospaced">
 900 VISINFO
 901 4     VISUALID                visual
 902 1     CARD8                   depth
 903 1     CARD8                   perflevel
 904 2                             unused
 905
 906 SCREENVISINFO
 907 4     CARD32                  n, number in list
 908 8n    LISTofVISINFO           n VISINFOs
 909
 910 BUFFER_ATTRIBUTES
 911 4     WINDOW                 window
 912 </literallayout>
 913 </sect1>
 914
 915 <sect1 id="error">
 916 <title>Error</title>
 917 <para><function>Buffer</function></para>
 918 <literallayout class="monospaced">
 919 1     0                       error
 920 1     error base + 0          code
 921 2     CARD16                  sequence number
 922 4     CARD32                  bad buffer
 923 2     CARD16                  minor-opcode
 924 1     CARD8                   major-opcode
 925 21                            unused
 926 </literallayout>
 927 </sect1>
 928
 929 <sect1 id="request">
 930 <title>Request</title>
 931
 932 <literallayout class="monospaced">
 933 DBEGetVersion
 934 1     CARD8                  major-opcode
 935 1     0                      minor-opcode
 936 2     2                      request length
 937 1     CARD8                  client-major-version
 938 1     CARD8                  client-minor-version
 939 2                            unused
 940 =>
 941 1                            unused
 942 2     CARD16                 sequence number
 943 4     0                      reply length
 944 1     CARD8                  server-major-version
 945 1     CARD8                  server-minor-version
 946 22                           unused
 947 </literallayout>
 948
 949 <para><function>DBEAllocateBackBufferName</function></para>
 950 <literallayout class="monospaced">
 951 1     CARD8                  major-opcode
 952 1     1                      minor-opcode
 953 2     4                      request length
 954 4     WINDOW                 window
 955 4     BACKBUFFER             back buffer name
 956 1     SWAPACTION             swap action hint
 957 3                            unused
 958 </literallayout>
 959
 960 <para><function>DBEDeallocateBackBufferName</function></para>
 961 <literallayout class="monospaced">
 962 1     CARD8                  major-opcode
 963 1     2                      minor-opcode
 964 2     2                      request length
 965 4     BACKBUFFER             back buffer name
 966 </literallayout>
 967
 968
 969 <para><function>DBESwapBuffers</function></para>
 970 <literallayout class="monospaced">
 971 1     CARD8                   major-opcode
 972 1     3                       minor-opcode
 973 2     2+2n                    request length
 974 4     CARD32                  n, number of window/swap action pairs in list
 975 8n    LISTofSWAPINFO          window/swap action pairs
 976 </literallayout>
 977
 978
 979 <para><function>DBEBeginIdiom</function></para>
 980 <literallayout class="monospaced">
 981 1     CARD8                   major-opcode
 982 1     4                       minor-opcode
 983 2     1                       request length
 984 </literallayout>
 985
 986 <para><function>DBEEndIdiom</function></para>
 987 <literallayout class="monospaced">
 988 1     CARD8                   major-opcode
 989 1     5                       minor-opcode
 990 2     1                       request length
 991 </literallayout>
 992
 993 <para><function>DBEGetVisualInfo</function></para>
 994 <literallayout class="monospaced">
 995 1     CARD8                   major-opcode
 996 1     6                       minor-opcode
 997 2     2+n                     request length
 998 4     CARD32                  n, number of screen specifiers in list
 999 4n    LISTofDRAWABLE          n screen specifiers
1000 =>
1001 1     1                       Reply
1002 1                             unused
1003 2     CARD16                  sequence number
1004 4     CARD32                  reply length
1005 4     CARD32                  m, number of SCREENVISINFOs in list
1006 20                            unused
1007 4j    LISTofSCREENVISINFO     m SCREENVISINFOs
1008 </literallayout>
1009
1010 <para><function>DBEGetBackBufferAttributes</function></para>
1011 <literallayout class="monospaced">
1012 1     CARD8                   major-opcode
1013 1     7                       minor-opcode
1014 2     2                       request length
1015 4     BACKBUFFER              back-buffer-name
1016 =>
1017 1                             unused
1018 2     CARD16                  sequence number
1019 4     0                       reply length
1020 4     BUFFER_ATTRIBUTES       attributes
1021 20                            unused
1022 </literallayout>
1023 </sect1>
1024
1025 </chapter>
1026
1027 <chapter id="acknowledgements">
1028 <title>Acknowledgements</title>
1029 <para>
1030 We wish to thank the following individuals who have contributed their time
1031 and talent toward shaping the DBE specification:
1032 </para>
1033 <para>T. Alex Chen, IBM; Peter Daifuku, Silicon Graphics, Inc.;
1034 Ian Elliott, Hewlett-Packard Company; Stephen Gildea, X Consortium, Inc.;
1035 Jim Graham, Sun; Larry Hare, AGE Logic; Jay Hersh, X Consortium, Inc.;
1036 Daryl Huff, Sun; Deron Dann Johnson, Sun; Louis Khouw, Sun;
1037 Mark Kilgard, Silicon Graphics, Inc.; Rob
1038 Lembree, Digital Equipment Corporation; Alan Ricker, Metheus; Michael
1039 Rosenblum, Digital Equipment Corporation; Bob Scheifler, X Consortium, Inc.;
1040 Larry Seiler, Digital Equipment Corporation; Jeanne Sparlin Smith, IBM;
1041 Jeff Stevenson, Hewlett-Packard Company; Walter Strand, Metheus; Ken
1042 Tidwell, Hewlett-Packard Company; and David P. Wiggins, X Consortium, Inc.
1043 </para>
1044
1045 <para>
1046 Mark provided the impetus to start the DBE project. Ian wrote the first
1047 draft of the specification. David served as architect.
1048 </para>
1049 </chapter>
1050
1051 <chapter id="references">
1052 <title>References</title>
1053 <para>
1054 Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension
1055 Specification Version 3.3."
1056 </para>
1057 <para>Tim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins,
1058 "X Synchronization Extension Version 3.0."
1059 </para>
1060 </chapter>
1061 </book>