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">
6 <!-- lifted from troff+ms+XMan by doclifter -->
10 <title>Double Buffer Extension Library</title>
11 <subtitle>X Consortium Standard</subtitle>
12 <!-- <releaseinfo>X Version 11, Release 6.4</releaseinfo> -->
15 <firstname>Ian</firstname><surname>Elliot</surname>
19 <firstname>Davide</firstname><surname>Wiggins</surname>
21 <corpname>Hewlett-Packard Company</corpname>
22 <copyright><year>1989</year><holder>X Consortium, Inc and Digital Equipment Corporation</holder></copyright>
23 <copyright><year>1992</year><holder>X Consortium, Inc and Intergraph Corporation</holder></copyright>
24 <copyright><year>1993</year><holder>X Consortium, Inc and Silicon Graphics, Inc.</holder></copyright>
25 <copyright><year>1994</year><holder>X Consortium, Inc and Hewlett-Packard Company</holder></copyright>
26 <copyright><year>1995</year><holder>X Consortium, Inc and Hewlett-Packard Company</holder></copyright>
27 <releaseinfo>Version 1.0</releaseinfo>
28 <affiliation><orgname>X Consortium</orgname></affiliation>
29 <productnumber>X Version 11, Release 7</productnumber>
33 Permission to use, copy, modify, and distribute this documentation for any
34 purpose and without fee is hereby granted, provided that the above copyright
35 notice and this permission notice appear in all copies. Digital Equipment
36 Corporation, Intergraph Corporation, Silicon Graphics, Hewlett-Packard, and
37 the X Consortium make no representations about the suitability for any
38 purpose of the information in this document. This documentation is provided
39 "as is" without express or implied warranty.
46 <chapter id="introduction">
47 <title>Introduction</title>
49 The Double Buffer Extension (DBE) provides a standard way to utilize
50 double-buffering within the framework of the X Window System.
51 Double-buffering uses two buffers, called front and back, which hold images.
52 The front buffer is visible to the user; the back buffer is not. Successive
53 frames of an animation are rendered into the back buffer while the previously
54 rendered frame is displayed in the front buffer. When a new frame is ready,
55 the back and front buffers swap roles, making the new frame visible. Ideally,
56 this exchange appears to happen instantaneously to the user and with no
57 visual artifacts. Thus, only completely rendered images are presented to the
58 user, and they remain visible during the entire time it takes to render a new
59 frame. The result is a flicker-free animation.
68 This extension should enable clients to:
73 Allocate and deallocate double-buffering for a window.
78 Draw to and read from the front and back buffers associated with a window.
83 Swap the front and back buffers associated with a window.
88 Specify a wide range of actions to be taken when a window is swapped.
89 This includes explicit, simple swap actions (defined below), and more
90 complex actions (for example, clearing ancillary buffers) that can be put
91 together within explicit "begin" and "end" requests (defined below).
96 Request that the front and back buffers associated with multiple
97 double-buffered windows be swapped simultaneously.
103 In addition, the extension should:
108 Allow multiple clients to use double-buffering on the same window.
113 Support a range of implementation methods that can capitalize on
114 existing hardware features.
119 Add no new event types.
124 Be reasonably easy to integrate with a variety of direct graphics
125 hardware access (DGHA) architectures.
132 <chapter id="concepts">
133 <title>Concepts</title>
135 Normal windows are created using the core CreateWindow request, which
136 allocates a set of window attributes and, for InputOutput windows, a front
137 buffer, into which an image can be drawn. The contents of this buffer will be
138 displayed when the window is visible.
141 This extension enables applications to use double-buffering with a window.
142 This involves creating a second buffer, called a back buffer, and associating
143 one or more back buffer names (XIDs) with the window for use when referring
144 to (that is, drawing to or reading from) the window’s back buffer. The back
145 buffer name is a DRAWABLE of type BACKBUFFER.
148 DBE provides a relative double-buffering model. One XID, the window,
149 always refers to the front buffer. One or more other XIDs, the back buffer
150 names, always refer to the back buffer. After a buffer swap, the window
151 continues to refer to the (new) front buffer, and the back buffer name
152 continues to refer to the (new) back buffer. Thus, applications and toolkits
153 that want to just render to the back buffer always use the back buffer name
154 for all drawing requests to the window. Portions of an application that want
155 to render to the front buffer always use the window XID for all drawing
156 requests to the window.
159 Multiple clients and toolkits can all use double-buffering on the same window.
160 DBE does not provide a request for querying whether a window has
161 double-buffering support, and if so, what the back buffer name is. Given the
162 asynchronous nature of the X Window System, this would cause race
163 conditions. Instead, DBE allows multiple back buffer names to exist for the
164 same window; they all refer to the same physical back buffer. The first time a
165 back buffer name is allocated for a window, the window becomes
166 double-buffered and the back buffer name is associated with the window.
167 Subsequently, the window already is a double-buffered window, and nothing
168 about the window changes when a new back buffer name is allocated, except
169 that the new back buffer name is associated with the window. The window
170 remains double-buffered until either the window is destroyed or until all of the
171 back buffer names for the window are deallocated.
174 In general, both the front and back buffers are treated the same.
175 particular, here are some important characteristics:
180 Only one buffer per window can be visible at a time (the front buffer).
185 Both buffers associated with a window have the same visual type, depth,
186 width, height, and shape as the window.
191 Both buffers associated with a window are "visible" (or "obscured") in
192 the same way. When an Expose event is generated for a window, both
193 buffers should be considered to be damaged in the exposed area.
194 Damage that occurs to either buffer will result in an Expose event on
195 the window. When a double-buffered window is exposed, both buffers
196 are tiled with the window background, exactly as stated by the core
197 protocol. Even though the back buffer is not visible, terms such as
198 obscure apply to the back buffer as well as to the front buffer.
203 It is acceptable at any time to pass a BACKBUFFER in any request,
204 notably any core or extension drawing request, that expects a
205 DRAWABLE. This enables an application to draw directly into
206 BACKBUFFERs in the same fashion as it would draw into any other
212 It is an error (Window) to pass a BACKBUFFER in a core request that
218 A BACKBUFFER will never be sent by core X in a reply, event, or
219 error where a Window is specified.
224 If core X11 backing-store and save-under applies to a double-buffered
225 window, it applies to both buffers equally.
230 If the core ClearArea request is executed on a double-buffered window,
231 the same area in both the front and back buffers is cleared.
237 The effect of passing a window to a request that accepts a
238 <function>DRAWABLE</function> is
239 unchanged by this extension. The window and front buffer are synonomous
240 with each other. This includes obeying the <function>GetImage</function>
242 subwindow-mode semantics if a core graphics context is involved. Regardless
243 of whether the window was explicitly passed in a
244 <function>GetImage</function> request, or
245 implicitly referenced (that is, one of the window’s ancestors was passed in the
246 request), the front (that is, visible) buffer is always referenced. Thus,
247 DBE-naive screen dump clients will always get the front buffer.
248 <function>GetImage</function> on
249 a back buffer returns undefined image contents for any obscured regions of the
250 back buffer that fall within the image.
253 Drawing to a back buffer always uses the clip region that would be used to
254 draw to the front buffer with a GC subwindow-mode of
255 <function>ClipByChildren</function>. If
256 an ancestor of a double-buffered window is drawn to with a core GC having a
257 subwindow-mode of IncludeInferiors, the effect on the double-buffered
258 window’s back buffer depends on the depth of the double-buffered window
259 and the ancestor. If the depths are the same, the contents of the back buffer
260 of the double-buffered window are not changed. If the depths are different,
261 the contents of the back buffer of the double-buffered window are undefined
262 for the pixels that the <function>IncludeInferiors</function> drawing touched.
267 DBE adds no new events. DBE does not extend the semantics of any existing
268 events with the exception of adding a new DRAWABLE type called
269 BACKBUFFER. If events, replies, or errors that contain a DRAWABLE (for
270 example, <function>GraphicsExpose</function>) are generated in response to
272 DRAWABLE returned will be the one specified in the request.
275 DBE advertises which visuals support double-buffering.
278 DBE does not include any timing or synchronization facilities. Applications
279 that need such facilities (for example, to maintain a constant frame rate)
280 should investigate the Synchronization Extension, an X Consortium standard.
283 <sect1 id="window_management_operations">
284 <title>Window Management Operations</title>
287 The basic philosophy of DBE is that both buffers are treated the same by core
288 X window management operations.
291 When the core <function>DestroyWindow</function> is executed on a
292 double-buffered window, both buffers associated with the window are
293 destroyed, and all back buffer names associated with the window are freed.
296 If the core <function>ConfigureWindow</function> request changes the size
297 of a window, both buffers assume the new size. If the window’s size
298 increases, the effect on the buffers depends on whether the implementation
299 honors bit gravity for buffers.
300 If bit gravity is implemented, then the contents of both buffers are moved in
301 accordance with the window’s bit gravity (see the core
302 <function>ConfigureWindow</function>
303 request), and the remaining areas are tiled with the window background. If
304 bit gravity is not implemented, then the entire unobscured region of both
305 buffers is tiled with the window background. In either case,
306 <function>Expose</function> events are
307 generated for the region that is tiled with the window background.
308 If the core GetGeometry request is executed on a BACKBUFFER, the
309 returned x, y, and border-width will be zero.
312 If the Shape extension
313 <function>ShapeRectangles</function>,
314 <function>ShapeMask</function>,
315 <function>ShapeCombine</function>, or
316 <function>ShapeOffset</function>
317 request is executed on a double-buffered window, both buffers
318 are reshaped to match the new window shape. The region difference is the
322 <literallayout remap='Ds'>
323 D = newshape − oldshape
327 It is tiled with the window background in both buffers, and
328 <function>Expose</function>
329 events are generated for D.
334 <sect1 id="complex_swap_actions">
335 <title>Complex Swap Actions</title>
337 DBE has no explicit knowledge of ancillary buffers (for example, depth buffers
338 or alpha buffers), and only has a limited set of defined swap actions. Some
339 applications may need a richer set of swap actions than DBE provides. Some
340 DBE implementations have knowledge of ancillary buffers, and/or can provide
341 a rich set of swap actions. Instead of continually extending DBE to increase
342 its set of swap actions, DBE provides a flexible "idiom" mechanism. If an
343 application’s needs are served by the defined swap actions, it should use them;
344 otherwise, it should use the following method of expressing a complex swap
345 action as an idiom. Following this policy will ensure the best possible
346 performance across a wide variety of implementations.
349 As suggested by the term "idiom," a complex swap action should be expressed
350 as a group/series of requests. Taken together, this group of requests may be
351 combined into an atomic operation by the implementation, in order to
352 maximize performance. The set of idioms actually recognized for optimization
353 is implementation dependent.
354 To help with idiom expression and
355 interpretation, an idiom must be surrounded by two protocol requests:
356 <function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>.
357 Unless this begin-end pair surrounds the idiom, it may not be recognized
358 by a given implementation, and performance will suffer.
361 For example, if an application wants to swap buffers for two windows, and use
362 core X to clear only certain planes of the back buffers, the application would
363 issue the following protocol requests as a group, and in the following order:
369 <function>DBEBeginIdiom</function> request.
374 <function>DBESwapBuffers</function> request with XIDs for two windows, each of which uses
375 a swap action of Untouched.
380 Core X <function>PolyFillRectangle</function> request to the back buffer of one window.
385 Core X <function>PolyFillRectangle</function> request to the back buffer of the other
391 <function>DBEEndIdiom</function> request.
397 The <function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>
398 requests do not perform any actions
399 themselves. They are treated as markers by implementations that can
400 combine certain groups/series of requests as idioms, and are ignored by other
401 implementations or for nonrecognized groups/series of requests. If these
402 requests are sent out of order, or are mismatched, no errors are sent, and the
403 requests are executed as usual, though performance may suffer.
408 An idiom need not include a <function>DBESwapBuffers</function> request.
409 For example, if a swap action of <function>Copied</function> is desired,
410 but only some of the planes should be copied, a core X
411 <function>CopyArea</function> request may be used instead of
412 <function>DBESwapBuffers</function>. If
413 <function>DBESwapBuffers</function> is included in an idiom, it should
414 immediately follow the
415 <function>DBEBeginIdiom</function> request. Also, when the
416 <function>DBESwapBuffers</function> is included in an idiom, that
417 request’s swap action will still be valid, and if the swap action
418 might overlap with another request, then the final result of the idiom must be
419 as if the separate requests were executed serially. For example, if the
420 specified swap action is <function>Untouched</function>, and if a
421 <function>PolyFillRectangle</function> using a client clip
422 rectangle is done to the window’s back buffer after the
423 <function>DBESwapBuffers</function> request, then the contents of the new
424 back buffer (after the idiom) will be the
425 same as if the idiom was not recognized by the implementation.
428 It is highly recommended that Application Programming Interface (API)
429 providers define, and application developers use, "convenience" functions that
430 allow client applications to call one procedure that encapsulates common
431 idioms. These functions will generate the
432 <function>DBEBeginIdiom</function> request, the idiom
433 requests, and <function>DBEEndIdiom</function> request. Usage of these
434 functions will ensure best possible performance across a wide
435 variety of implementations.
441 <chapter id="c_language_bindings">
442 <title>C Language Binding</title>
444 All identifier The header for this extension is <X11/extensions/Xdbe.h>.
445 names provided by this header begin with Xdbe.
452 The type <function>XdbeBackBuffer</function> is a <function>Drawable</function>.
456 The type <function>XdbeSwapAction</function> can be one of the constants
457 <function>XdbeUndefined</function>,
458 <function>XdbeBackground</function>,
459 <function>XdbeUntouched</function>, or
460 <function>XdbeCopied</function>.
465 <sect1 id="c_functions">
466 <title>C Functions</title>
468 The C functions provide direct access to the protocol and add no additional
469 semantics. For complete details on the effects of these functions, refer to the
470 appropriate protocol request, which can be derived by replacing Xdbe at the
471 start of the function name with DBE. All functions that have return type
472 <function>Status</function> will return nonzero for success and
478 <funcdef>Status <function>XdbeQueryExtension</function></funcdef>
479 <paramdef>Display <parameter> *dpy</parameter></paramdef>
480 <paramdef>int <parameter> *major_version_return</parameter></paramdef>
481 <paramdef>int <parameter> *minor_version_return</parameter></paramdef>
486 <function>XdbeQueryExtension</function> sets major version return and minor
487 version return to the major and minor DBE protocol version supported by
488 the server. If the DBE library is compatible with the version returned by
489 the server, it returns nonzero. If dpy does not support the DBE extension,
490 or if there was an error during communication with the server, or if the
491 server and library protocol versions are incompatible, it returns zero.
492 No other Xdbe functions may be called before this function. If a client
493 violates this rule, the effects of all subsequent Xdbe calls that it makes
499 <funcdef>XdbeScreenVisualInfo *<function>XdbeGetVisualInfo</function></funcdef>
500 <paramdef>Display <parameter> *dpy</parameter></paramdef>
501 <paramdef>Drawable <parameter> *screen_specifiers</parameter></paramdef>
502 <paramdef>int <parameter> *num_screens</parameter></paramdef>
508 <function>XdbeGetVisualInfo</function> returns information about which
509 visuals support double buffering. The argument num_screens specifies how
510 many elements there are in the screen_specifiers list. Each drawable in
511 screen_specifiers designates a screen for which the supported visuals are
512 being requested. If num_screens is zero, information for all screens is
513 requested. In this case, upon return from this function, num_screens will
514 be set to the number of screens that were found. If an error occurs,
515 this function returns NULL; otherwise, it returns a pointer to a list of
516 <function>XdbeScreenVisualInfo</function>
517 structures of length num_screens. The nth element in the returned list
518 corresponds to the nth drawable in the screen_specifiers list, unless
520 element in the returned list corresponds to the nth screen of the server,
521 starting with screen zero.
526 The XdbeScreenVisualInfo structure has the following fields:
528 <literallayout remap='Ds'>
529 int count number of items in visinfo
530 XdbeVisualInfo* visinfo list of visuals and depths for this screen
534 The <function>XdbeVisualInfo</function> structure has the following fields:
537 <literallayout remap='Ds'>
538 VisualID visual one visual ID that supports double-buffering
539 int depth depth of visual in bits
540 int perflevel performance level of visual
546 <funcdef>void XdbeFreeVisualInfo <function>XdbeGetVisualInfo</function></funcdef>
547 <paramdef>XdbeScreenVisualInfo <parameter> *visual_info</parameter></paramdef>
552 <function>XdbeFreeVisualInfo</function> frees the list of
553 <function>XdbeScreenVisualInfo</function> returned by
554 <function>XdbeGetVisualInfo</function>.
560 <funcdef>XdbeBackBuffer <function>XdbeAllocateBackBufferName</function></funcdef>
561 <paramdef>Display <parameter> *dpy</parameter></paramdef>
562 <paramdef>Window <parameter> *window</parameter></paramdef>
563 <paramdef>XdbeSwapAction <parameter> swap_action</parameter></paramdef>
569 <function>XdbeAllocateBackBufferName</function> returns a drawable ID used
570 to refer to the back buffer of the specified window. The swap_action is a
571 hint to indicate the swap_action that will likely be used in subsequent
572 calls to <function>XdbeSwapBuffers</function>. The actual swap_action
573 used in calls to <function>XdbeSwapBuffers</function> does not have to be
574 the same as the swap_action passed to this function, though clients are
575 encouraged to provide accurate information whenever possible.
580 <funcdef>Status <function>XdbeDeallocateBackBufferName</function></funcdef>
581 <paramdef>Display <parameter> *dpy</parameter></paramdef>
582 <paramdef>XdbeBackBuffer <parameter> buffer</parameter></paramdef>
587 <function>XdbeDeallocateBackBufferName</function> frees the specified
588 drawable ID, buffer, that was obtained via
589 <function>XdbeAllocateBackBufferName</function>. The buffer must be a valid
590 name for the back buffer of a window, or an
591 <function>XdbeBadBuffer</function> error results.
596 <funcdef>Status <function>XdbeSwapBuffers</function></funcdef>
597 <paramdef>Display <parameter> *dpy</parameter></paramdef>
598 <paramdef>XdbeSwapInfo <parameter> *swap_info</parameter></paramdef>
599 <paramdef>int <parameter> num_windows</parameter></paramdef>
604 <function>XdbeSwapBuffers</function> swaps the front and back buffers
605 for a list of windows. The argument num_windows specifies how many windows
606 are to have their buffers swapped; it is the number of elements in the
607 swap_info array. The argument swap_info specifies the information needed
608 per window to do the swap.
611 The XdbeSwapInfo structure has the following fields:
614 <literallayout remap='Ds'>
615 Window swap_window window for which to swap buffers
616 XdbeSwapAction swap_action swap action to use for this swap window
621 <funcdef>Status <function>XdbeBeginIdiom</function></funcdef>
622 <paramdef>Display <parameter> *dpy</parameter></paramdef>
627 <function>XdbeBeginIdiom</function> marks the beginning of an idiom
629 <link linkend="complex_swap_actions">
630 <xref linkend="complex_swap_actions"></xref></link>
631 for a complete discussion of idioms.
636 <funcdef>Status <function>XdbeEndIdiom</function></funcdef>
637 <paramdef>Display <parameter> *dpy</parameter></paramdef>
642 <function>XdbeEndIdiom</function> marks the end of an idiom sequence.
647 <funcdef>XdbeBackBufferAttributes *<function>XdbeGetBackBufferAttributes</function></funcdef>
648 <paramdef>Display <parameter> *dpy</parameter></paramdef>
649 <paramdef>XdbeBackBuffer <parameter> buffer</parameter></paramdef>
654 <function>XdbeGetBackBufferAttributes</function> returns the attributes associated with
655 the specified buffer.
658 The XdbeBackBufferAttributes structure has the following fields:
661 <literallayout remap='Ds'>
662 Window window window that buffer belongs to
666 If buffer is not a valid <function>XdbeBackBuffer</function>, window is
670 The returned <function>XdbeBackBufferAttributes</function> structure
671 can be freed with the Xlib function <function>XFree</function>.
676 <title>Errors</title>
678 The <function>XdbeBufferError</function> structure has the following fields:
680 <literallayout remap='Ds'>
682 Display * display Display the event was read from
683 XdbeBackBuffer buffer resource id
684 unsigned long serial serial number of failed request
685 unsigned char error code error base + <function>XdbeBadBuffer</function>
686 unsigned char request code Major op-code of failed request
687 unsigned char minor code Minor op-code of failed request
692 <chapter id="acknowledgements">
693 <title>Acknowledgements</title>
696 We wish to thank the following individuals who have contributed their time
697 and talent toward shaping the DBE specification:
700 T. Alex Chen, IBM; Peter Daifuku, Silicon Graphics, Inc.; Ian Elliott,
701 Hewlett-Packard Company; Stephen Gildea, X Consortium, Inc.; Jim Graham,
702 Sun; Larry Hare, AGE Logic; Jay Hersh, X Consortium, Inc.; Daryl Huff,
703 Sun; Deron Dann Johnson, Sun; Louis Khouw, Sun; Mark Kilgard, Silicon
704 Graphics, Inc.; Rob Lembree, Digital Equipment Corporation; Alan Ricker,
705 Metheus; Michael Rosenblum, Digital Equipment Corporation; Bob Scheifler,
706 X Consortium, Inc.; Larry Seiler, Digital Equipment Corporation; Jeanne
707 Sparlin Smith, IBM; Jeff Stevenson, Hewlett-Packard Company; Walter
708 Strand, Metheus; Ken Tidwell, Hewlett-Packard Company; and David P.
709 Wiggins, X Consortium, Inc.
712 Mark provided the impetus to start the DBE project. Ian wrote the first draft
713 of the specification. David served as architect.
717 <chapter id="references">
718 <title>References</title>
720 Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension
721 Specification Version 3.3."
724 Tim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins, "X
725 Synchronization Extension Version 3.0."