1e8a5466aSmrg<?xml version="1.0" encoding="UTF-8" ?> 2a5602400Smrg<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 3af9a7ee5Smrg "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" 4af9a7ee5Smrg[ 5af9a7ee5Smrg<!ENTITY % defs SYSTEM "defs.ent"> %defs; 6af9a7ee5Smrg]> 7e8a5466aSmrg 8e8a5466aSmrg 9e8a5466aSmrg<!-- lifted from troff+ms+XMan by doclifter --> 10e8a5466aSmrg<book id="dbelib"> 11e8a5466aSmrg 12e8a5466aSmrg<bookinfo> 13e8a5466aSmrg <title>Double Buffer Extension Library</title> 14e8a5466aSmrg <subtitle>X Consortium Standard</subtitle> 15af9a7ee5Smrg <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo> 16af9a7ee5Smrg <releaseinfo>Version 1.0</releaseinfo> 17e8a5466aSmrg <authorgroup> 18e8a5466aSmrg <author> 19e8a5466aSmrg <firstname>Ian</firstname><surname>Elliot</surname> 20af9a7ee5Smrg <affiliation><orgname>Hewlett-Packard Company</orgname></affiliation> 21e8a5466aSmrg </author> 22af9a7ee5Smrg <othercredit> 23af9a7ee5Smrg <firstname>David</firstname><othername>P.</othername><surname>Wiggins</surname> 24af9a7ee5Smrg <affiliation><orgname>X Consortium, Inc</orgname></affiliation> 25af9a7ee5Smrg </othercredit> 26e8a5466aSmrg </authorgroup> 27af9a7ee5Smrg <copyright><year>1989</year> 28af9a7ee5Smrg <holder>X Consortium Inc</holder> 29af9a7ee5Smrg <holder>Digital Equipment Corporation</holder> 30af9a7ee5Smrg </copyright> 31af9a7ee5Smrg <copyright><year>1992</year> 32af9a7ee5Smrg <holder>X Consortium Inc</holder> 33af9a7ee5Smrg <holder>Intergraph Corporation</holder> 34af9a7ee5Smrg </copyright> 35af9a7ee5Smrg <copyright><year>1993</year> 36af9a7ee5Smrg <holder>X Consortium Inc</holder> 37af9a7ee5Smrg <holder>Silicon Graphics, Inc.</holder> 38af9a7ee5Smrg </copyright> 39af9a7ee5Smrg <copyright><year>1994</year><year>1995</year> 40af9a7ee5Smrg <holder>X Consortium Inc</holder> 41af9a7ee5Smrg <holder>Hewlett-Packard Company</holder> 42af9a7ee5Smrg </copyright> 43e8a5466aSmrg 44e8a5466aSmrg<legalnotice> 45e8a5466aSmrg<para> 46e8a5466aSmrgPermission to use, copy, modify, and distribute this documentation for any 47e8a5466aSmrgpurpose and without fee is hereby granted, provided that the above copyright 48e8a5466aSmrgnotice and this permission notice appear in all copies. Digital Equipment 49e8a5466aSmrgCorporation, Intergraph Corporation, Silicon Graphics, Hewlett-Packard, and 50e8a5466aSmrgthe X Consortium make no representations about the suitability for any 51e8a5466aSmrgpurpose of the information in this document. This documentation is provided 52e8a5466aSmrg"as is" without express or implied warranty. 53e8a5466aSmrg</para> 54e8a5466aSmrg 55e8a5466aSmrg</legalnotice> 56e8a5466aSmrg 57e8a5466aSmrg</bookinfo> 58e8a5466aSmrg 59af9a7ee5Smrg<chapter id='Introduction'> 60e8a5466aSmrg<title>Introduction</title> 61e8a5466aSmrg<para> 62e8a5466aSmrgThe Double Buffer Extension (DBE) provides a standard way to utilize 63e8a5466aSmrgdouble-buffering within the framework of the X Window System. 64e8a5466aSmrgDouble-buffering uses two buffers, called front and back, which hold images. 65e8a5466aSmrgThe front buffer is visible to the user; the back buffer is not. Successive 66e8a5466aSmrgframes of an animation are rendered into the back buffer while the previously 67e8a5466aSmrgrendered frame is displayed in the front buffer. When a new frame is ready, 68e8a5466aSmrgthe back and front buffers swap roles, making the new frame visible. Ideally, 69e8a5466aSmrgthis exchange appears to happen instantaneously to the user and with no 70e8a5466aSmrgvisual artifacts. Thus, only completely rendered images are presented to the 71e8a5466aSmrguser, and they remain visible during the entire time it takes to render a new 72e8a5466aSmrgframe. The result is a flicker-free animation. 73e8a5466aSmrg</para> 74e8a5466aSmrg 75e8a5466aSmrg</chapter> 76e8a5466aSmrg 77af9a7ee5Smrg<chapter id='Goals'> 78e8a5466aSmrg<title>Goals</title> 79e8a5466aSmrg 80e8a5466aSmrg<para> 81e8a5466aSmrgThis extension should enable clients to: 82e8a5466aSmrg</para> 83e8a5466aSmrg<itemizedlist> 84e8a5466aSmrg <listitem> 85e8a5466aSmrg <para> 86e8a5466aSmrgAllocate and deallocate double-buffering for a window. 87e8a5466aSmrg </para> 88e8a5466aSmrg </listitem> 89e8a5466aSmrg <listitem> 90e8a5466aSmrg <para> 91e8a5466aSmrgDraw to and read from the front and back buffers associated with a window. 92e8a5466aSmrg </para> 93e8a5466aSmrg </listitem> 94e8a5466aSmrg <listitem> 95e8a5466aSmrg <para> 96e8a5466aSmrgSwap the front and back buffers associated with a window. 97e8a5466aSmrg </para> 98e8a5466aSmrg </listitem> 99e8a5466aSmrg <listitem> 100e8a5466aSmrg <para> 101e8a5466aSmrgSpecify a wide range of actions to be taken when a window is swapped. 102e8a5466aSmrgThis includes explicit, simple swap actions (defined below), and more 103e8a5466aSmrgcomplex actions (for example, clearing ancillary buffers) that can be put 104e8a5466aSmrgtogether within explicit "begin" and "end" requests (defined below). 105e8a5466aSmrg </para> 106e8a5466aSmrg </listitem> 107e8a5466aSmrg <listitem> 108e8a5466aSmrg <para> 109e8a5466aSmrgRequest that the front and back buffers associated with multiple 110e8a5466aSmrgdouble-buffered windows be swapped simultaneously. 111e8a5466aSmrg </para> 112e8a5466aSmrg </listitem> 113e8a5466aSmrg</itemizedlist> 114e8a5466aSmrg 115e8a5466aSmrg<para> 116e8a5466aSmrgIn addition, the extension should: 117e8a5466aSmrg</para> 118e8a5466aSmrg<itemizedlist> 119e8a5466aSmrg <listitem> 120e8a5466aSmrg <para> 121e8a5466aSmrgAllow multiple clients to use double-buffering on the same window. 122e8a5466aSmrg </para> 123e8a5466aSmrg </listitem> 124e8a5466aSmrg <listitem> 125e8a5466aSmrg <para> 126e8a5466aSmrgSupport a range of implementation methods that can capitalize on 127e8a5466aSmrgexisting hardware features. 128e8a5466aSmrg </para> 129e8a5466aSmrg </listitem> 130e8a5466aSmrg <listitem> 131e8a5466aSmrg <para> 132e8a5466aSmrgAdd no new event types. 133e8a5466aSmrg </para> 134e8a5466aSmrg </listitem> 135e8a5466aSmrg <listitem> 136e8a5466aSmrg <para> 137e8a5466aSmrgBe reasonably easy to integrate with a variety of direct graphics 138e8a5466aSmrghardware access (DGHA) architectures. 139e8a5466aSmrg </para> 140e8a5466aSmrg </listitem> 141e8a5466aSmrg</itemizedlist> 142e8a5466aSmrg 143e8a5466aSmrg</chapter> 144e8a5466aSmrg 145af9a7ee5Smrg<chapter id='Concepts'> 146e8a5466aSmrg<title>Concepts</title> 147e8a5466aSmrg<para> 148e8a5466aSmrgNormal windows are created using the core CreateWindow request, which 149e8a5466aSmrgallocates a set of window attributes and, for InputOutput windows, a front 150e8a5466aSmrgbuffer, into which an image can be drawn. The contents of this buffer will be 151e8a5466aSmrgdisplayed when the window is visible. 152e8a5466aSmrg</para> 153e8a5466aSmrg<para> 154e8a5466aSmrgThis extension enables applications to use double-buffering with a window. 155e8a5466aSmrgThis involves creating a second buffer, called a back buffer, and associating 156e8a5466aSmrgone or more back buffer names (XIDs) with the window for use when referring 157e8a5466aSmrgto (that is, drawing to or reading from) the window’s back buffer. The back 158e8a5466aSmrgbuffer name is a DRAWABLE of type BACKBUFFER. 159e8a5466aSmrg</para> 160e8a5466aSmrg<para> 161e8a5466aSmrgDBE provides a relative double-buffering model. One XID, the window, 162e8a5466aSmrgalways refers to the front buffer. One or more other XIDs, the back buffer 163e8a5466aSmrgnames, always refer to the back buffer. After a buffer swap, the window 164e8a5466aSmrgcontinues to refer to the (new) front buffer, and the back buffer name 165e8a5466aSmrgcontinues to refer to the (new) back buffer. Thus, applications and toolkits 166e8a5466aSmrgthat want to just render to the back buffer always use the back buffer name 167e8a5466aSmrgfor all drawing requests to the window. Portions of an application that want 168e8a5466aSmrgto render to the front buffer always use the window XID for all drawing 169e8a5466aSmrgrequests to the window. 170e8a5466aSmrg</para> 171e8a5466aSmrg<para> 172e8a5466aSmrgMultiple clients and toolkits can all use double-buffering on the same window. 173e8a5466aSmrgDBE does not provide a request for querying whether a window has 174e8a5466aSmrgdouble-buffering support, and if so, what the back buffer name is. Given the 175e8a5466aSmrgasynchronous nature of the X Window System, this would cause race 176e8a5466aSmrgconditions. Instead, DBE allows multiple back buffer names to exist for the 177e8a5466aSmrgsame window; they all refer to the same physical back buffer. The first time a 178e8a5466aSmrgback buffer name is allocated for a window, the window becomes 179e8a5466aSmrgdouble-buffered and the back buffer name is associated with the window. 180e8a5466aSmrgSubsequently, the window already is a double-buffered window, and nothing 181e8a5466aSmrgabout the window changes when a new back buffer name is allocated, except 182e8a5466aSmrgthat the new back buffer name is associated with the window. The window 183e8a5466aSmrgremains double-buffered until either the window is destroyed or until all of the 184e8a5466aSmrgback buffer names for the window are deallocated. 185e8a5466aSmrg</para> 186e8a5466aSmrg<para> 187e8a5466aSmrgIn general, both the front and back buffers are treated the same. 188e8a5466aSmrgparticular, here are some important characteristics: 189e8a5466aSmrg</para> 190e8a5466aSmrg<itemizedlist> 191e8a5466aSmrg <listitem> 192e8a5466aSmrg <para> 193e8a5466aSmrgOnly one buffer per window can be visible at a time (the front buffer). 194e8a5466aSmrg </para> 195e8a5466aSmrg </listitem> 196e8a5466aSmrg <listitem> 197e8a5466aSmrg <para> 198e8a5466aSmrgBoth buffers associated with a window have the same visual type, depth, 199e8a5466aSmrgwidth, height, and shape as the window. 200e8a5466aSmrg </para> 201e8a5466aSmrg </listitem> 202e8a5466aSmrg <listitem> 203e8a5466aSmrg <para> 204e8a5466aSmrgBoth buffers associated with a window are "visible" (or "obscured") in 205e8a5466aSmrgthe same way. When an Expose event is generated for a window, both 206e8a5466aSmrgbuffers should be considered to be damaged in the exposed area. 207e8a5466aSmrgDamage that occurs to either buffer will result in an Expose event on 208e8a5466aSmrgthe window. When a double-buffered window is exposed, both buffers 209e8a5466aSmrgare tiled with the window background, exactly as stated by the core 210e8a5466aSmrgprotocol. Even though the back buffer is not visible, terms such as 211e8a5466aSmrgobscure apply to the back buffer as well as to the front buffer. 212e8a5466aSmrg </para> 213e8a5466aSmrg </listitem> 214e8a5466aSmrg <listitem> 215e8a5466aSmrg <para> 216e8a5466aSmrgIt is acceptable at any time to pass a BACKBUFFER in any request, 217e8a5466aSmrgnotably any core or extension drawing request, that expects a 218e8a5466aSmrgDRAWABLE. This enables an application to draw directly into 219e8a5466aSmrgBACKBUFFERs in the same fashion as it would draw into any other 220e8a5466aSmrgDRAWABLE. 221e8a5466aSmrg </para> 222e8a5466aSmrg </listitem> 223e8a5466aSmrg <listitem> 224e8a5466aSmrg <para> 225e8a5466aSmrgIt is an error (Window) to pass a BACKBUFFER in a core request that 226e8a5466aSmrgexpects a Window. 227e8a5466aSmrg </para> 228e8a5466aSmrg </listitem> 229e8a5466aSmrg <listitem> 230e8a5466aSmrg <para> 231e8a5466aSmrgA BACKBUFFER will never be sent by core X in a reply, event, or 232e8a5466aSmrgerror where a Window is specified. 233e8a5466aSmrg </para> 234e8a5466aSmrg </listitem> 235e8a5466aSmrg <listitem> 236e8a5466aSmrg <para> 237e8a5466aSmrgIf core X11 backing-store and save-under applies to a double-buffered 238e8a5466aSmrgwindow, it applies to both buffers equally. 239e8a5466aSmrg </para> 240e8a5466aSmrg </listitem> 241e8a5466aSmrg <listitem> 242e8a5466aSmrg <para> 243e8a5466aSmrgIf the core ClearArea request is executed on a double-buffered window, 244e8a5466aSmrgthe same area in both the front and back buffers is cleared. 245e8a5466aSmrg </para> 246e8a5466aSmrg </listitem> 247e8a5466aSmrg</itemizedlist> 248e8a5466aSmrg 249e8a5466aSmrg<para> 250e8a5466aSmrgThe effect of passing a window to a request that accepts a 251e8a5466aSmrg<function>DRAWABLE</function> is 2520760f5d2Smrgunchanged by this extension. The window and front buffer are synonymous 253e8a5466aSmrgwith each other. This includes obeying the <function>GetImage</function> 254e8a5466aSmrgsemantics and the 255e8a5466aSmrgsubwindow-mode semantics if a core graphics context is involved. Regardless 256e8a5466aSmrgof whether the window was explicitly passed in a 257e8a5466aSmrg<function>GetImage</function> request, or 258e8a5466aSmrgimplicitly referenced (that is, one of the window’s ancestors was passed in the 259e8a5466aSmrgrequest), the front (that is, visible) buffer is always referenced. Thus, 260e8a5466aSmrgDBE-naive screen dump clients will always get the front buffer. 261e8a5466aSmrg<function>GetImage</function> on 262e8a5466aSmrga back buffer returns undefined image contents for any obscured regions of the 263e8a5466aSmrgback buffer that fall within the image. 264e8a5466aSmrg</para> 265e8a5466aSmrg<para> 266e8a5466aSmrgDrawing to a back buffer always uses the clip region that would be used to 267e8a5466aSmrgdraw to the front buffer with a GC subwindow-mode of 268e8a5466aSmrg<function>ClipByChildren</function>. If 269e8a5466aSmrgan ancestor of a double-buffered window is drawn to with a core GC having a 270e8a5466aSmrgsubwindow-mode of IncludeInferiors, the effect on the double-buffered 271e8a5466aSmrgwindow’s back buffer depends on the depth of the double-buffered window 272e8a5466aSmrgand the ancestor. If the depths are the same, the contents of the back buffer 273e8a5466aSmrgof the double-buffered window are not changed. If the depths are different, 274e8a5466aSmrgthe contents of the back buffer of the double-buffered window are undefined 275e8a5466aSmrgfor the pixels that the <function>IncludeInferiors</function> drawing touched. 276e8a5466aSmrg</para> 277e8a5466aSmrg 278e8a5466aSmrg 279e8a5466aSmrg<para> 280e8a5466aSmrgDBE adds no new events. DBE does not extend the semantics of any existing 281e8a5466aSmrgevents with the exception of adding a new DRAWABLE type called 282e8a5466aSmrgBACKBUFFER. If events, replies, or errors that contain a DRAWABLE (for 283e8a5466aSmrgexample, <function>GraphicsExpose</function>) are generated in response to 284e8a5466aSmrga request, the 285e8a5466aSmrgDRAWABLE returned will be the one specified in the request. 286e8a5466aSmrg</para> 287e8a5466aSmrg<para> 288e8a5466aSmrgDBE advertises which visuals support double-buffering. 289e8a5466aSmrg</para> 290e8a5466aSmrg<para> 291e8a5466aSmrgDBE does not include any timing or synchronization facilities. Applications 292e8a5466aSmrgthat need such facilities (for example, to maintain a constant frame rate) 293e8a5466aSmrgshould investigate the Synchronization Extension, an X Consortium standard. 294e8a5466aSmrg</para> 295e8a5466aSmrg 296af9a7ee5Smrg<sect1 id='Window_Management_Operations'> 297e8a5466aSmrg<title>Window Management Operations</title> 298e8a5466aSmrg 299e8a5466aSmrg<para> 300e8a5466aSmrgThe basic philosophy of DBE is that both buffers are treated the same by core 301e8a5466aSmrgX window management operations. 302e8a5466aSmrg</para> 303e8a5466aSmrg<para> 304e8a5466aSmrgWhen the core <function>DestroyWindow</function> is executed on a 305e8a5466aSmrgdouble-buffered window, both buffers associated with the window are 306e8a5466aSmrgdestroyed, and all back buffer names associated with the window are freed. 307e8a5466aSmrg</para> 308e8a5466aSmrg<para> 309e8a5466aSmrgIf the core <function>ConfigureWindow</function> request changes the size 310e8a5466aSmrgof a window, both buffers assume the new size. If the window’s size 311e8a5466aSmrgincreases, the effect on the buffers depends on whether the implementation 312e8a5466aSmrghonors bit gravity for buffers. 313e8a5466aSmrgIf bit gravity is implemented, then the contents of both buffers are moved in 314e8a5466aSmrgaccordance with the window’s bit gravity (see the core 315e8a5466aSmrg<function>ConfigureWindow</function> 316e8a5466aSmrgrequest), and the remaining areas are tiled with the window background. If 317e8a5466aSmrgbit gravity is not implemented, then the entire unobscured region of both 318e8a5466aSmrgbuffers is tiled with the window background. In either case, 319e8a5466aSmrg<function>Expose</function> events are 320e8a5466aSmrggenerated for the region that is tiled with the window background. 321e8a5466aSmrgIf the core GetGeometry request is executed on a BACKBUFFER, the 322e8a5466aSmrgreturned x, y, and border-width will be zero. 323e8a5466aSmrg</para> 324e8a5466aSmrg<para> 325e8a5466aSmrgIf the Shape extension 326e8a5466aSmrg<function>ShapeRectangles</function>, 327e8a5466aSmrg<function>ShapeMask</function>, 328e8a5466aSmrg<function>ShapeCombine</function>, or 329e8a5466aSmrg<function>ShapeOffset</function> 330e8a5466aSmrgrequest is executed on a double-buffered window, both buffers 331e8a5466aSmrgare reshaped to match the new window shape. The region difference is the 332e8a5466aSmrgfollowing: 333e8a5466aSmrg</para> 334e8a5466aSmrg 335e8a5466aSmrg<literallayout remap='Ds'> 336e8a5466aSmrg D = newshape − oldshape 337e8a5466aSmrg</literallayout> 338e8a5466aSmrg 339e8a5466aSmrg<para> 340e8a5466aSmrgIt is tiled with the window background in both buffers, and 341e8a5466aSmrg<function>Expose</function> 342e8a5466aSmrgevents are generated for D. 343e8a5466aSmrg</para> 344e8a5466aSmrg 345e8a5466aSmrg</sect1> 346e8a5466aSmrg 347af9a7ee5Smrg<sect1 id='Complex_Swap_Actions'> 348e8a5466aSmrg<title>Complex Swap Actions</title> 349e8a5466aSmrg<para> 350e8a5466aSmrgDBE has no explicit knowledge of ancillary buffers (for example, depth buffers 351e8a5466aSmrgor alpha buffers), and only has a limited set of defined swap actions. Some 352e8a5466aSmrgapplications may need a richer set of swap actions than DBE provides. Some 353e8a5466aSmrgDBE implementations have knowledge of ancillary buffers, and/or can provide 354e8a5466aSmrga rich set of swap actions. Instead of continually extending DBE to increase 355e8a5466aSmrgits set of swap actions, DBE provides a flexible "idiom" mechanism. If an 356e8a5466aSmrgapplication’s needs are served by the defined swap actions, it should use them; 357e8a5466aSmrgotherwise, it should use the following method of expressing a complex swap 358e8a5466aSmrgaction as an idiom. Following this policy will ensure the best possible 359e8a5466aSmrgperformance across a wide variety of implementations. 360e8a5466aSmrg</para> 361e8a5466aSmrg<para> 362e8a5466aSmrgAs suggested by the term "idiom," a complex swap action should be expressed 363e8a5466aSmrgas a group/series of requests. Taken together, this group of requests may be 364e8a5466aSmrgcombined into an atomic operation by the implementation, in order to 365e8a5466aSmrgmaximize performance. The set of idioms actually recognized for optimization 366e8a5466aSmrgis implementation dependent. 367e8a5466aSmrgTo help with idiom expression and 368e8a5466aSmrginterpretation, an idiom must be surrounded by two protocol requests: 369e8a5466aSmrg<function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>. 370e8a5466aSmrgUnless this begin-end pair surrounds the idiom, it may not be recognized 371e8a5466aSmrgby a given implementation, and performance will suffer. 372e8a5466aSmrg</para> 373e8a5466aSmrg<para> 374e8a5466aSmrgFor example, if an application wants to swap buffers for two windows, and use 375e8a5466aSmrgcore X to clear only certain planes of the back buffers, the application would 376e8a5466aSmrgissue the following protocol requests as a group, and in the following order: 377e8a5466aSmrg</para> 378e8a5466aSmrg 379e8a5466aSmrg<itemizedlist> 380e8a5466aSmrg <listitem> 381e8a5466aSmrg <para> 382e8a5466aSmrg<function>DBEBeginIdiom</function> request. 383e8a5466aSmrg </para> 384e8a5466aSmrg </listitem> 385e8a5466aSmrg <listitem> 386e8a5466aSmrg <para> 387e8a5466aSmrg<function>DBESwapBuffers</function> request with XIDs for two windows, each of which uses 388e8a5466aSmrga swap action of Untouched. 389e8a5466aSmrg </para> 390e8a5466aSmrg </listitem> 391e8a5466aSmrg <listitem> 392e8a5466aSmrg <para> 393e8a5466aSmrgCore X <function>PolyFillRectangle</function> request to the back buffer of one window. 394e8a5466aSmrg </para> 395e8a5466aSmrg </listitem> 396e8a5466aSmrg <listitem> 397e8a5466aSmrg <para> 398e8a5466aSmrgCore X <function>PolyFillRectangle</function> request to the back buffer of the other 399e8a5466aSmrgwindow. 400e8a5466aSmrg </para> 401e8a5466aSmrg </listitem> 402e8a5466aSmrg <listitem> 403e8a5466aSmrg <para> 404e8a5466aSmrg<function>DBEEndIdiom</function> request. 405e8a5466aSmrg </para> 406e8a5466aSmrg </listitem> 407e8a5466aSmrg</itemizedlist> 408e8a5466aSmrg 409e8a5466aSmrg<para> 410e8a5466aSmrgThe <function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function> 411e8a5466aSmrgrequests do not perform any actions 412e8a5466aSmrgthemselves. They are treated as markers by implementations that can 413e8a5466aSmrgcombine certain groups/series of requests as idioms, and are ignored by other 414e8a5466aSmrgimplementations or for nonrecognized groups/series of requests. If these 415e8a5466aSmrgrequests are sent out of order, or are mismatched, no errors are sent, and the 416e8a5466aSmrgrequests are executed as usual, though performance may suffer. 417e8a5466aSmrg</para> 418e8a5466aSmrg 419e8a5466aSmrg<para> 420e8a5466aSmrg 421e8a5466aSmrgAn idiom need not include a <function>DBESwapBuffers</function> request. 422e8a5466aSmrgFor example, if a swap action of <function>Copied</function> is desired, 423e8a5466aSmrgbut only some of the planes should be copied, a core X 424e8a5466aSmrg<function>CopyArea</function> request may be used instead of 425e8a5466aSmrg<function>DBESwapBuffers</function>. If 426e8a5466aSmrg<function>DBESwapBuffers</function> is included in an idiom, it should 427e8a5466aSmrgimmediately follow the 428e8a5466aSmrg<function>DBEBeginIdiom</function> request. Also, when the 429e8a5466aSmrg<function>DBESwapBuffers</function> is included in an idiom, that 430e8a5466aSmrgrequest’s swap action will still be valid, and if the swap action 431e8a5466aSmrgmight overlap with another request, then the final result of the idiom must be 432e8a5466aSmrgas if the separate requests were executed serially. For example, if the 433e8a5466aSmrgspecified swap action is <function>Untouched</function>, and if a 434e8a5466aSmrg<function>PolyFillRectangle</function> using a client clip 435e8a5466aSmrgrectangle is done to the window’s back buffer after the 436e8a5466aSmrg<function>DBESwapBuffers</function> request, then the contents of the new 437e8a5466aSmrgback buffer (after the idiom) will be the 438e8a5466aSmrgsame as if the idiom was not recognized by the implementation. 439e8a5466aSmrg</para> 440e8a5466aSmrg<para> 441e8a5466aSmrgIt is highly recommended that Application Programming Interface (API) 442e8a5466aSmrgproviders define, and application developers use, "convenience" functions that 443e8a5466aSmrgallow client applications to call one procedure that encapsulates common 444e8a5466aSmrgidioms. These functions will generate the 445e8a5466aSmrg<function>DBEBeginIdiom</function> request, the idiom 446e8a5466aSmrgrequests, and <function>DBEEndIdiom</function> request. Usage of these 447e8a5466aSmrgfunctions will ensure best possible performance across a wide 448e8a5466aSmrgvariety of implementations. 449e8a5466aSmrg</para> 450e8a5466aSmrg 451e8a5466aSmrg</sect1> 452e8a5466aSmrg</chapter> 453e8a5466aSmrg 454af9a7ee5Smrg<chapter id='C_Language_Binding'> 455e8a5466aSmrg<title>C Language Binding</title> 456e8a5466aSmrg<para> 457e8a5466aSmrgAll identifier The header for this extension is <X11/extensions/Xdbe.h>. 458e8a5466aSmrgnames provided by this header begin with Xdbe. 459e8a5466aSmrg</para> 460e8a5466aSmrg 461af9a7ee5Smrg<sect1 id='Types'> 462e8a5466aSmrg<title>Types</title> 463e8a5466aSmrg 464e8a5466aSmrg<para> 465e8a5466aSmrgThe type <function>XdbeBackBuffer</function> is a <function>Drawable</function>. 466e8a5466aSmrg</para> 467e8a5466aSmrg 468e8a5466aSmrg<para> 469e8a5466aSmrgThe type <function>XdbeSwapAction</function> can be one of the constants 470e8a5466aSmrg<function>XdbeUndefined</function>, 471e8a5466aSmrg<function>XdbeBackground</function>, 472e8a5466aSmrg<function>XdbeUntouched</function>, or 473e8a5466aSmrg<function>XdbeCopied</function>. 474e8a5466aSmrg</para> 475e8a5466aSmrg 476e8a5466aSmrg</sect1> 477e8a5466aSmrg 478af9a7ee5Smrg<sect1 id='C_Functions'> 479e8a5466aSmrg<title>C Functions</title> 480e8a5466aSmrg<para> 481e8a5466aSmrgThe C functions provide direct access to the protocol and add no additional 482e8a5466aSmrgsemantics. For complete details on the effects of these functions, refer to the 483e8a5466aSmrgappropriate protocol request, which can be derived by replacing Xdbe at the 484e8a5466aSmrgstart of the function name with DBE. All functions that have return type 485e8a5466aSmrg<function>Status</function> will return nonzero for success and 486e8a5466aSmrgzero for failure. 487e8a5466aSmrg</para> 488e8a5466aSmrg 489af9a7ee5Smrg<funcsynopsis id='XdbeQueryExtension'> 490e8a5466aSmrg<funcprototype> 491e8a5466aSmrg <funcdef>Status <function>XdbeQueryExtension</function></funcdef> 492e8a5466aSmrg <paramdef>Display <parameter> *dpy</parameter></paramdef> 493e8a5466aSmrg <paramdef>int <parameter> *major_version_return</parameter></paramdef> 494e8a5466aSmrg <paramdef>int <parameter> *minor_version_return</parameter></paramdef> 495e8a5466aSmrg</funcprototype> 496e8a5466aSmrg</funcsynopsis> 497e8a5466aSmrg 498e8a5466aSmrg<para> 499af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeQueryExtension'><function>XdbeQueryExtension</function></olink> sets major version return and minor 500e8a5466aSmrgversion return to the major and minor DBE protocol version supported by 501e8a5466aSmrgthe server. If the DBE library is compatible with the version returned by 502e8a5466aSmrgthe server, it returns nonzero. If dpy does not support the DBE extension, 503e8a5466aSmrgor if there was an error during communication with the server, or if the 504e8a5466aSmrgserver and library protocol versions are incompatible, it returns zero. 505e8a5466aSmrgNo other Xdbe functions may be called before this function. If a client 506e8a5466aSmrgviolates this rule, the effects of all subsequent Xdbe calls that it makes 507e8a5466aSmrgare undefined. 508e8a5466aSmrg</para> 509e8a5466aSmrg 510af9a7ee5Smrg<funcsynopsis id='XdbeGetVisualInfo'> 511e8a5466aSmrg<funcprototype> 512e8a5466aSmrg <funcdef>XdbeScreenVisualInfo *<function>XdbeGetVisualInfo</function></funcdef> 513e8a5466aSmrg <paramdef>Display <parameter> *dpy</parameter></paramdef> 514e8a5466aSmrg <paramdef>Drawable <parameter> *screen_specifiers</parameter></paramdef> 515e8a5466aSmrg <paramdef>int <parameter> *num_screens</parameter></paramdef> 516e8a5466aSmrg</funcprototype> 517e8a5466aSmrg</funcsynopsis> 518e8a5466aSmrg 519e8a5466aSmrg<para> 520e8a5466aSmrg 521af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeGetVisualInfo'><function>XdbeGetVisualInfo</function></olink> returns information about which 522e8a5466aSmrgvisuals support double buffering. The argument num_screens specifies how 523e8a5466aSmrgmany elements there are in the screen_specifiers list. Each drawable in 524e8a5466aSmrgscreen_specifiers designates a screen for which the supported visuals are 525e8a5466aSmrgbeing requested. If num_screens is zero, information for all screens is 526e8a5466aSmrgrequested. In this case, upon return from this function, num_screens will 527e8a5466aSmrgbe set to the number of screens that were found. If an error occurs, 528e8a5466aSmrgthis function returns NULL; otherwise, it returns a pointer to a list of 529e8a5466aSmrg<function>XdbeScreenVisualInfo</function> 530e8a5466aSmrgstructures of length num_screens. The nth element in the returned list 531e8a5466aSmrgcorresponds to the nth drawable in the screen_specifiers list, unless 532e8a5466aSmrg 533e8a5466aSmrgelement in the returned list corresponds to the nth screen of the server, 534e8a5466aSmrgstarting with screen zero. 535e8a5466aSmrg</para> 536e8a5466aSmrg 537e8a5466aSmrg 538e8a5466aSmrg<para> 539e8a5466aSmrgThe XdbeScreenVisualInfo structure has the following fields: 540e8a5466aSmrg</para> 541e8a5466aSmrg<literallayout remap='Ds'> 542e8a5466aSmrgint count number of items in visinfo 543e8a5466aSmrgXdbeVisualInfo* visinfo list of visuals and depths for this screen 544e8a5466aSmrg</literallayout> 545e8a5466aSmrg 546e8a5466aSmrg<para> 547e8a5466aSmrgThe <function>XdbeVisualInfo</function> structure has the following fields: 548e8a5466aSmrg</para> 549e8a5466aSmrg 550e8a5466aSmrg<literallayout remap='Ds'> 551e8a5466aSmrgVisualID visual one visual ID that supports double-buffering 552e8a5466aSmrgint depth depth of visual in bits 553e8a5466aSmrgint perflevel performance level of visual 554e8a5466aSmrg</literallayout> 555e8a5466aSmrg 556e8a5466aSmrg 557e8a5466aSmrg<funcsynopsis> 558e8a5466aSmrg<funcprototype> 559e8a5466aSmrg <funcdef>void XdbeFreeVisualInfo <function>XdbeGetVisualInfo</function></funcdef> 560e8a5466aSmrg <paramdef>XdbeScreenVisualInfo <parameter> *visual_info</parameter></paramdef> 561e8a5466aSmrg</funcprototype> 562e8a5466aSmrg</funcsynopsis> 563e8a5466aSmrg 564e8a5466aSmrg<para> 565e8a5466aSmrg<function>XdbeFreeVisualInfo</function> frees the list of 566e8a5466aSmrg<function>XdbeScreenVisualInfo</function> returned by 567af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeGetVisualInfo'><function>XdbeGetVisualInfo</function></olink>. 568e8a5466aSmrg</para> 569e8a5466aSmrg 570e8a5466aSmrg 571af9a7ee5Smrg<funcsynopsis id='XdbeAllocateBackBufferName'> 572e8a5466aSmrg<funcprototype> 573e8a5466aSmrg <funcdef>XdbeBackBuffer <function>XdbeAllocateBackBufferName</function></funcdef> 574e8a5466aSmrg <paramdef>Display <parameter> *dpy</parameter></paramdef> 575e8a5466aSmrg <paramdef>Window <parameter> *window</parameter></paramdef> 576e8a5466aSmrg <paramdef>XdbeSwapAction <parameter> swap_action</parameter></paramdef> 577e8a5466aSmrg</funcprototype> 578e8a5466aSmrg</funcsynopsis> 579e8a5466aSmrg 580e8a5466aSmrg 581e8a5466aSmrg<para> 582af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeAllocateBackBufferName'><function>XdbeAllocateBackBufferName</function></olink> returns a drawable ID used 583e8a5466aSmrgto refer to the back buffer of the specified window. The swap_action is a 584e8a5466aSmrghint to indicate the swap_action that will likely be used in subsequent 585af9a7ee5Smrgcalls to <olink targetdoc='dbelib' targetptr='XdbeSwapBuffers'><function>XdbeSwapBuffers</function></olink>. The actual swap_action 586af9a7ee5Smrgused in calls to <olink targetdoc='dbelib' targetptr='XdbeSwapBuffers'><function>XdbeSwapBuffers</function></olink> does not have to be 587e8a5466aSmrgthe same as the swap_action passed to this function, though clients are 588e8a5466aSmrgencouraged to provide accurate information whenever possible. 589e8a5466aSmrg</para> 590e8a5466aSmrg 591af9a7ee5Smrg<funcsynopsis id='XdbeDeallocateBackBufferName'> 592e8a5466aSmrg<funcprototype> 593e8a5466aSmrg <funcdef>Status <function>XdbeDeallocateBackBufferName</function></funcdef> 594e8a5466aSmrg <paramdef>Display <parameter> *dpy</parameter></paramdef> 595e8a5466aSmrg <paramdef>XdbeBackBuffer <parameter> buffer</parameter></paramdef> 596e8a5466aSmrg</funcprototype> 597e8a5466aSmrg</funcsynopsis> 598e8a5466aSmrg 599e8a5466aSmrg<para> 600af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeDeallocateBackBufferName'><function>XdbeDeallocateBackBufferName</function></olink> frees the specified 601e8a5466aSmrgdrawable ID, buffer, that was obtained via 602af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeAllocateBackBufferName'><function>XdbeAllocateBackBufferName</function></olink>. The buffer must be a valid 603e8a5466aSmrgname for the back buffer of a window, or an 604e8a5466aSmrg<function>XdbeBadBuffer</function> error results. 605e8a5466aSmrg</para> 606e8a5466aSmrg 607af9a7ee5Smrg<funcsynopsis id='XdbeSwapBuffers'> 608e8a5466aSmrg<funcprototype> 609e8a5466aSmrg <funcdef>Status <function>XdbeSwapBuffers</function></funcdef> 610e8a5466aSmrg <paramdef>Display <parameter> *dpy</parameter></paramdef> 611e8a5466aSmrg <paramdef>XdbeSwapInfo <parameter> *swap_info</parameter></paramdef> 612e8a5466aSmrg <paramdef>int <parameter> num_windows</parameter></paramdef> 613e8a5466aSmrg</funcprototype> 614e8a5466aSmrg</funcsynopsis> 615e8a5466aSmrg 616e8a5466aSmrg<para> 617af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeSwapBuffers'><function>XdbeSwapBuffers</function></olink> swaps the front and back buffers 618e8a5466aSmrgfor a list of windows. The argument num_windows specifies how many windows 619e8a5466aSmrgare to have their buffers swapped; it is the number of elements in the 620e8a5466aSmrgswap_info array. The argument swap_info specifies the information needed 621e8a5466aSmrgper window to do the swap. 622e8a5466aSmrg</para> 623e8a5466aSmrg<para> 624e8a5466aSmrgThe XdbeSwapInfo structure has the following fields: 625e8a5466aSmrg</para> 626e8a5466aSmrg 627e8a5466aSmrg<literallayout remap='Ds'> 628e8a5466aSmrgWindow swap_window window for which to swap buffers 629e8a5466aSmrgXdbeSwapAction swap_action swap action to use for this swap window 630e8a5466aSmrg</literallayout> 631e8a5466aSmrg 632af9a7ee5Smrg<funcsynopsis id='XdbeBeginIdiom'> 633e8a5466aSmrg<funcprototype> 634e8a5466aSmrg <funcdef>Status <function>XdbeBeginIdiom</function></funcdef> 635e8a5466aSmrg <paramdef>Display <parameter> *dpy</parameter></paramdef> 636e8a5466aSmrg</funcprototype> 637e8a5466aSmrg</funcsynopsis> 638e8a5466aSmrg 639e8a5466aSmrg<para> 640af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeBeginIdiom'><function>XdbeBeginIdiom</function></olink> marks the beginning of an idiom 641e8a5466aSmrgsequence. See 642af9a7ee5Smrg<link linkend='Complex_Swap_Actions'> 643af9a7ee5Smrg<xref linkend='Complex_Swap_Actions'></xref></link> 644e8a5466aSmrgfor a complete discussion of idioms. 645e8a5466aSmrg</para> 646e8a5466aSmrg 647af9a7ee5Smrg<funcsynopsis id='XdbeEndIdiom'> 648e8a5466aSmrg<funcprototype> 649e8a5466aSmrg <funcdef>Status <function>XdbeEndIdiom</function></funcdef> 650e8a5466aSmrg <paramdef>Display <parameter> *dpy</parameter></paramdef> 651e8a5466aSmrg</funcprototype> 652e8a5466aSmrg</funcsynopsis> 653e8a5466aSmrg 654e8a5466aSmrg<para> 655af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeEndIdiom'><function>XdbeEndIdiom</function></olink> marks the end of an idiom sequence. 656e8a5466aSmrg</para> 657e8a5466aSmrg 658af9a7ee5Smrg<funcsynopsis id='XdbeGetBackBufferAttributes'> 659e8a5466aSmrg<funcprototype> 660e8a5466aSmrg <funcdef>XdbeBackBufferAttributes *<function>XdbeGetBackBufferAttributes</function></funcdef> 661e8a5466aSmrg <paramdef>Display <parameter> *dpy</parameter></paramdef> 662e8a5466aSmrg <paramdef>XdbeBackBuffer <parameter> buffer</parameter></paramdef> 663e8a5466aSmrg</funcprototype> 664e8a5466aSmrg</funcsynopsis> 665e8a5466aSmrg 666e8a5466aSmrg<para> 667af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeGetBackBufferAttributes'><function>XdbeGetBackBufferAttributes</function></olink> returns the attributes associated with 668e8a5466aSmrgthe specified buffer. 669e8a5466aSmrg</para> 670e8a5466aSmrg<para> 671e8a5466aSmrgThe XdbeBackBufferAttributes structure has the following fields: 672e8a5466aSmrg</para> 673e8a5466aSmrg 674e8a5466aSmrg<literallayout remap='Ds'> 675e8a5466aSmrgWindow window window that buffer belongs to 676e8a5466aSmrg</literallayout> 677e8a5466aSmrg 678e8a5466aSmrg<para> 679e8a5466aSmrgIf buffer is not a valid <function>XdbeBackBuffer</function>, window is 680e8a5466aSmrgset to None. 681e8a5466aSmrg</para> 682e8a5466aSmrg<para> 683e8a5466aSmrgThe returned <function>XdbeBackBufferAttributes</function> structure 684af9a7ee5Smrgcan be freed with the Xlib function <olink targetdoc='libX11' targetptr='XFree'><function>XFree</function></olink>. 685e8a5466aSmrg</para> 686e8a5466aSmrg</sect1> 687e8a5466aSmrg 688af9a7ee5Smrg<sect1 id='Errors'> 689e8a5466aSmrg<title>Errors</title> 690e8a5466aSmrg<para> 691e8a5466aSmrgThe <function>XdbeBufferError</function> structure has the following fields: 692e8a5466aSmrg</para> 693e8a5466aSmrg<literallayout remap='Ds'> 694e8a5466aSmrgint type 695e8a5466aSmrgDisplay * display Display the event was read from 696e8a5466aSmrgXdbeBackBuffer buffer resource id 697e8a5466aSmrgunsigned long serial serial number of failed request 698e8a5466aSmrgunsigned char error code error base + <function>XdbeBadBuffer</function> 699e8a5466aSmrgunsigned char request code Major op-code of failed request 700e8a5466aSmrgunsigned char minor code Minor op-code of failed request 701e8a5466aSmrg</literallayout> 702e8a5466aSmrg</sect1> 703e8a5466aSmrg</chapter> 704e8a5466aSmrg 705af9a7ee5Smrg<chapter id='Acknowledgements'> 706e8a5466aSmrg<title>Acknowledgements</title> 707e8a5466aSmrg 708e8a5466aSmrg<para> 709e8a5466aSmrgWe wish to thank the following individuals who have contributed their time 710e8a5466aSmrgand talent toward shaping the DBE specification: 711e8a5466aSmrg</para> 712e8a5466aSmrg<para> 713e8a5466aSmrgT. Alex Chen, IBM; Peter Daifuku, Silicon Graphics, Inc.; Ian Elliott, 714e8a5466aSmrgHewlett-Packard Company; Stephen Gildea, X Consortium, Inc.; Jim Graham, 715e8a5466aSmrgSun; Larry Hare, AGE Logic; Jay Hersh, X Consortium, Inc.; Daryl Huff, 716e8a5466aSmrgSun; Deron Dann Johnson, Sun; Louis Khouw, Sun; Mark Kilgard, Silicon 717e8a5466aSmrgGraphics, Inc.; Rob Lembree, Digital Equipment Corporation; Alan Ricker, 718e8a5466aSmrgMetheus; Michael Rosenblum, Digital Equipment Corporation; Bob Scheifler, 719e8a5466aSmrgX Consortium, Inc.; Larry Seiler, Digital Equipment Corporation; Jeanne 720e8a5466aSmrgSparlin Smith, IBM; Jeff Stevenson, Hewlett-Packard Company; Walter 721e8a5466aSmrgStrand, Metheus; Ken Tidwell, Hewlett-Packard Company; and David P. 722e8a5466aSmrgWiggins, X Consortium, Inc. 723e8a5466aSmrg</para> 724e8a5466aSmrg<para> 725e8a5466aSmrgMark provided the impetus to start the DBE project. Ian wrote the first draft 726e8a5466aSmrgof the specification. David served as architect. 727e8a5466aSmrg</para> 728e8a5466aSmrg 729e8a5466aSmrg</chapter> 730af9a7ee5Smrg<chapter id='References'> 731e8a5466aSmrg<title>References</title> 732e8a5466aSmrg<para> 733e8a5466aSmrgJeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension 734e8a5466aSmrgSpecification Version 3.3." 735e8a5466aSmrg</para> 736e8a5466aSmrg<para> 737e8a5466aSmrgTim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins, "X 738e8a5466aSmrgSynchronization Extension Version 3.0." 739e8a5466aSmrg</para> 740e8a5466aSmrg</chapter> 741e8a5466aSmrg</book> 742