man/DBE.man

   1 .\" Copyright (c) 1995  Hewlett-Packard Company
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining a
   4 .\" copy of this software and associated documentation files (the "Software"),
   5 .\" to deal in the Software without restriction, including without limitation
   6 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
   7 .\" and/or sell copies of the Software, and to permit persons to whom the
   8 .\" Software furnished to do so, subject to the following conditions:
   9 .\"
  10 .\" The above copyright notice and this permission notice shall be included in
  11 .\" all copies or substantial portions of the Software.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  14 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  15 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  16 .\" HEWLETT-PACKARD COMPANY BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  17 .\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
  18 .\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  19 .\" SOFTWARE.
  20 .\"
  21 .\" Except as contained in this notice, the name of the Hewlett-Packard Company shall not
  22 .\" be used in advertising or otherwise to promote the sale, use or other
  23 .\" dealing in this Software without prior written authorization from the
  24 .\" Hewlett-Packard Company.
  25 .\"
  26 .TH DBE __libmansuffix__ __xorgversion__ "X FUNCTIONS"
  27 .SH NAME
  28 DBE - Double Buffer Extension
  29 .SH SYNOPSIS
  30 The Double Buffer Extension (DBE) provides a standard way to utilize
  31 double-buffering within the framework of the X Window System.
  32 Double-buffering uses two buffers, called front and back, which hold images.
  33 The front buffer is visible to the user; the back buffer is not.  Successive
  34 frames of an animation are rendered into the back buffer while the previously
  35 rendered frame is displayed in the front buffer.  When a new frame is ready,
  36 the back and front buffers swap roles, making the new frame visible.  Ideally,
  37 this exchange appears to happen instantaneously to the user, with no visual
  38 artifacts.  Thus, only completely rendered images are presented to the user,
  39 and remain visible during the entire time it takes to render a new frame.  The
  40 result is a flicker-free animation.
  41 .SH DESCRIPTION
  42 .B Concepts
  43 .RS
  44 Normal windows are created using
  45 .B XCreateWindow()
  46 or
  47 .B XCreateSimpleWindow(),
  48 which allocate a set of window attributes and, for InputOutput windows, a front
  49 buffer, into which an image can be drawn.  The contents of this buffer will be
  50 displayed when the window is visible.
  51
  52 This extension enables applications to use double-buffering with a window.
  53 This involves creating a second buffer, called a back buffer, and associating
  54 one or more back buffer names
  55 .I (XIDs)
  56 with the window, for use when referring
  57 to (i.e., drawing to or reading from) the window's back buffer.
  58 The back buffer name is a drawable of type
  59 .I XdbeBackBuffer.
  60
  61 DBE provides a relative double-buffering model.  One XID, the window,
  62 always refers to the front buffer.  One or more other XIDs, the back buffer
  63 names, always refer to the back buffer.  After a buffer swap, the window
  64 continues to refer to the (new) front buffer, and the back buffer name
  65 continues to refer to the (new) back buffer.  Thus, applications and toolkits
  66 that want to just render to the back buffer always use the back buffer name
  67 for all drawing requests to the window.  Portions of an application that want
  68 to render to the front buffer always use the window XID for all drawing
  69 requests to the window.
  70
  71 Multiple clients and toolkits can all use double-buffering on the same window.
  72 DBE does not provide a request for querying whether a window has
  73 double-buffering support, and if so, what the back buffer name is.  Given the
  74 asynchronous nature of the X Window System, this would cause race
  75 conditions.  Instead, DBE allows multiple back buffer names to exist for the
  76 same window; they all refer to the same physical back buffer.  The first time a
  77 back buffer name is allocated for a window, the window becomes
  78 double-buffered and the back buffer name is associated with the window.
  79 Subsequently, the window already is a double-buffered window, and nothing
  80 about the window changes when a new back buffer name is allocated, except
  81 that the new back buffer name is associated with the window.  The window
  82 remains double-buffered until either the window is destroyed, or until all of
  83 the back buffer names for the window are deallocated.
  84
  85 In general, both the front and back buffers ae treated the same.  In
  86 particular, here are some important characteristics:
  87
  88 .RS
  89 Only one buffer per window can be visible at a time (the front buffer).
  90
  91 Both buffers associated with a window have the same visual type, depth,
  92 width, height, and shape as the window.
  93
  94 Both buffers associated with a window are "visible" (or "obscured") in
  95 the same way.  When an Expose event is generated for a window, this
  96 event is considered to apply to both buffers equally.  When a
  97 double-buffered window is exposed, both buffers are tiled with the
  98 window background.
  99 Even though the back buffer is not visible, terms such as obscure apply to the
 100 back buffer as well as to the front buffer.
 101
 102 It is acceptable at any time to pass an
 103 .I XdbeBackBuffer
 104 in any function that expects a drawable.
 105 This enables an application to draw directly into
 106 .I XdbeBackBuffer
 107 in the same fashion as it would draw into any other drawable.
 108
 109 It is an error (Window) to pass an
 110 .I XdbeBackBuffer
 111 in a function that expects a Window.
 112
 113 An
 114 .I XdbeBackBuffer
 115 will never be sent in a reply, event, or error where a Window is specified.
 116
 117 If backing-store and save-under applies to a double-buffered
 118 window, it applies to both buffers equally.
 119
 120 If the
 121 .B XClearArea()
 122 or
 123 .B XClearWindow()
 124 function is executed on a
 125 double-buffered window, the same area in both the front and back buffers
 126 is cleared.
 127 .RE
 128
 129 The effect of passing a window to a function that accepts a drawable
 130 is unchanged by this extension.  The window and front buffer are synonymous
 131 with each other.  This includes obeying the
 132 .B XGetImage()
 133 and
 134 .B XGetSubImage()
 135 semantics and the subwindow-mode semantics if a graphics context is
 136 involved.  Regardless of whether the window was explicitly passed in an
 137 .B XGetImage()
 138 or
 139 .B XGetSubImage()
 140 call, or implicitly referenced (i.e., one of
 141 the window's ancestors was passed in the function), the front (i.e. visible)
 142 buffer is always referenced.
 143 Thus, DBE-naive screen dump clients will always get the front buffer.
 144 .B XGetImage()
 145 and
 146 .B XGetSubImage()
 147 on a back
 148 buffer return undefined image contents for any obscured regions of the back
 149 buffer that fall within the image.
 150
 151 Drawing to a back buffer always uses the clip region that would be used to
 152 draw to the front buffer with a GC subwindow-mode of ClipByChildren.  If an
 153 ancestor of a double-buffered window is drawn to with a GC having a
 154 subwindow-mode of IncludeInferiors, the effect on the double-buffered
 155 window's back buffer depends on the depth of the double-buffered window
 156 and the ancestor.  If the depths are the same, the contents of the back buffer
 157 of the double-buffered window are not changed.  If the depths are different,
 158 the contents of the back buffer of the double-buffered window are undefined
 159 for the pixels that the IncludeInferiors drawing touched.
 160
 161 DBE adds no new events.  DBE does not extend the semantics of any existing
 162 events with the exception of adding a new drawable type called
 163 .I XdbeBackBuffer.
 164
 165 If events, replies, or errors that contain a drawable
 166 (e.g., GraphicsExpose) are generated in response to a request, the
 167 drawable returned will be the one specified in the request.
 168
 169 DBE advertises which visuals support double buffering.
 170
 171 DBE does not include any timing or synchronization facilities.  Applications
 172 that need such facilities (e.g., to maintain a constant frame rate) should
 173 investigate the Synchronization Extension, an X Consortium standard.
 174 .RE
 175
 176 .B Window Management Operations
 177
 178 .RS
 179 The basic philosophy of DBE is that both buffers are treated the same by
 180 X window management operations.
 181
 182 When a double-buffered window is destroyed,
 183 both buffers associated with the window are destroyed, and all back buffer
 184 names associated with the window are freed.
 185
 186 If the size of a double-buffered window changes, both
 187 buffers assume the new size.  If the window's size increases, the effect on the
 188 buffers depends on whether the implementation honors bit gravity for buffers.
 189 If bit gravity is implemented, then the contents of both buffers are moved in
 190 accordance with the window's bit gravity,
 191 and the remaining areas are tiled with the window background.  If
 192 bit gravity is not implemented, then the entire unobscured region of both
 193 buffers is tiled with the window background.  In either case, Expose events are
 194 generated for the region that is tiled with the window background.
 195
 196 If the
 197 .B XGetGeometry()
 198 function is executed on an
 199 .I XdbeBackBuffer,
 200 the returned x, y, and border-width will be zero.
 201
 202 If the Shape extension
 203 .B ShapeRectangles, ShapeMask, ShapeCombine,
 204 or
 205 .B ShapeOffset
 206 request is executed on a double-buffered window, both
 207 buffers are reshaped to match the new window shape.  The region difference
 208 D = new shape - old shape is tiled with the window background in both
 209 buffers, and Expose events are generated for D.
 210 .RE
 211
 212 .B Complex Swap Actions
 213
 214 .RS
 215 DBE has no explicit knowledge of ancillary buffers (e.g. depth buffers or
 216 alpha buffers), and only has a limited set of defined swap actions.  Some
 217 applications may need a richer set of swap actions than DBE provides.  Some
 218 DBE implementations have knowledge of ancillary buffers, and/or can provide
 219 a rich set of swap actions. Instead of continually extending DBE to increase
 220 its set of swap actions, DBE provides a flexible "idiom" mechanism.  If an
 221 applications's needs are served by the defined swap actions, it should use
 222 them; otherwise, it should use the following method of expressing a complex
 223 swap action as an idiom.  Following this policy will ensure the best possible
 224 performance across a wide variety of implementations.
 225
 226 As suggested by the term "idiom," a complex swap action should be expressed
 227 as a group/series of requests.  Taken together, this group of requests may be
 228 combined into an atomic operation by the implementation, in order to
 229 maximize performance.  The set of idioms actually recognized for optimization
 230 is implementation dependent.  To help with idiom expression and
 231 interpretation, an idiom must be surrounded by two function calls:
 232 .B XdbeBeginIdiom()
 233 and
 234 .B XdbeEndIdiom().
 235 Unless this begin-end pair
 236 surrounds the idiom, it may not be recognized by a given implementation, and
 237 performance will suffer.
 238
 239 For example, if an application wants to swap buffers for two windows, and use
 240 X to clear only certain planes of the back buffers, the application would
 241 make the following calls as a group, and in the following order:
 242
 243 .RS
 244 .B XdbeBeginIdiom().
 245
 246 .B XdbeSwapBuffers()
 247 with XIDs for two windows, each of which uses a swap action of Untouched.
 248
 249 .B XFillRectangle()
 250 to the back buffer of one window.
 251
 252 .B XFillRectangle()
 253 to the back buffer of the other window.
 254
 255 .B XdbeEndIdiom().
 256 .RE
 257
 258 The
 259 .B XdbeBeginIdiom()
 260 and
 261 .B XdbeEndIdiom()
 262 functions do not perform any
 263 actions themselves.  They are treated as markers by implementations that can
 264 combine certain groups/series of requests as idioms, and are ignored by other
 265 implementations or for non-recognized groups/series of requests.  If these
 266 function calls are made out of order, or are mismatched, no errors are sent,
 267 and the functions are executed as usual, though performance may suffer.
 268
 269 .B XdbeSwapBuffers()
 270 need not be included in an idiom.  For
 271 example, if a swap action of Copied is desired, but only some of the planes
 272 should be copied,
 273 .B XCopyArea()
 274 may be used instead of
 275 .B XdbeSwapBuffers().
 276 If
 277 .B XdbeSwapBuffers()
 278 is included in an idiom, it should immediately follow the
 279 .B XdbeBeginIdiom()
 280 call.  Also, when the
 281 .B XdbeSwapBuffers()
 282 is included in an idiom, that request's swap action will
 283 still be valid, and if the swap action might overlap with another request, then
 284 the final result of the idiom must be as if the separate requests were executed
 285 serially.  For example, if the specified swap action is Untouched, and if a
 286 .B XFillRectangle()
 287 using a client clip rectangle is done to the window's back
 288 buffer after the
 289 .B XdbeSwapBuffers()
 290 call, then the contents of the new
 291 back buffer (after the idiom) will be the same as if the idiom was not
 292 recognized by the implementation.
 293
 294 It is highly recommended that API providers define, and application
 295 developers use, "convenience" functions that allow client applications to call
 296 one procedure that encapsulates common idioms.  These functions will
 297 generate the
 298 .B XdbeBeginIdiom(),
 299 idiom, and
 300 .B XdbeEndIdiom()
 301 calls.  Usage of these functions will ensure best possible
 302 performance across a wide variety of implementations.
 303 .SH SEE ALSO
 304 .I XdbeAllocateBackBufferName(),
 305 .I XdbeBeginIdiom(),
 306 .I XdbeDeallocateBackBufferName(),
 307 .I XdbeEndIdiom(),
 308 .I XdbeFreeVisualInfo(),
 309 .I XdbeGetBackBufferAttributes(),
 310 .I XdbeGetVisualInfo(),
 311 .I XdbeQueryExtension(),
 312 .I XdbeSwapBuffers().
 313