DBE(3X11) X FUNCTIONS DBE(3X11)
DBE - Double Buffer Extension
The Double Buffer Extension (DBE) provides a standard way to
utilize double-buffering within the framework of the X Win-
dow System. Double-buffering uses two buffers, called front
and back, which hold images. The front buffer is visible to
the user; the back buffer is not. Successive frames of an
animation are rendered into the back buffer while the previ-
ously rendered frame is displayed in the front buffer. When
a new frame is ready, the back and front buffers swap roles,
making the new frame visible. Ideally, this exchange
appears to happen instantaneously to the user, with no
visual artifacts. Thus, only completely rendered images are
presented to the user, and remain visible during the entire
time it takes to render a new frame. The result is a
flicker-free animation.
Concepts
Normal windows are created using XCreateWindow() or
XCreateSimpleWindow(), which allocate a set of window
attributes and, for InputOutput windows, a front
buffer, into which an image can be drawn. The contents
of this buffer will be displayed when the window is
visible.
This extension enables applications to use double-
buffering with a window. This involves creating a
second buffer, called a back buffer, and associating
one or more back buffer names (XIDs) with the window,
for use when referring to (i.e., drawing to or reading
from) the window's back buffer. The back buffer name is
a drawable of type XdbeBackBuffer.
DBE provides a relative double-buffering model. One
XID, the window, always refers to the front buffer.
One or more other XIDs, the back buffer names, always
refer to the back buffer. After a buffer swap, the
window continues to refer to the (new) front buffer,
and the back buffer name continues to refer to the
(new) back buffer. Thus, applications and toolkits
that want to just render to the back buffer always use
the back buffer name for all drawing requests to the
window. Portions of an application that want to render
to the front buffer always use the window XID for all
drawing requests to the window.
Multiple clients and toolkits can all use double-
buffering on the same window. DBE does not provide a
request for querying whether a window has double-
XFree86 Version 4.5.0 1
DBE(3X11) X FUNCTIONS DBE(3X11)
buffering support, and if so, what the back buffer name
is. Given the asynchronous nature of the X Window Sys-
tem, this would cause race conditions. Instead, DBE
allows multiple back buffer names to exist for the same
window; they all refer to the same physical back
buffer. The first time a back buffer name is allocated
for a window, the window becomes double-buffered and
the back buffer name is associated with the window.
Subsequently, the window already is a double-buffered
window, and nothing about the window changes when a new
back buffer name is allocated, except that the new back
buffer name is associated with the window. The window
remains double-buffered until either the window is des-
troyed, or until all of the back buffer names for the
window are deallocated.
In general, both the front and back buffers ae treated
the same. In particular, here are some important
characteristics:
Only one buffer per window can be visible at a
time (the front buffer).
Both buffers associated with a window have the
same visual type, depth, width, height, and shape
as the window.
Both buffers associated with a window are "visi-
ble" (or "obscured") in the same way. When an
Expose event is generated for a window, this event
is considered to apply to both buffers equally.
When a double-buffered window is exposed, both
buffers are tiled with the window background. Even
though the back buffer is not visible, terms such
as obscure apply to the back buffer as well as to
the front buffer.
It is acceptable at any time to pass an XdbeBack-
Buffer in any function that expects a drawable.
This enables an application to draw directly into
XdbeBackBuffer in the same fashion as it would
draw into any other drawable.
It is an error (Window) to pass an XdbeBackBuffer
in a function that expects a Window.
An XdbeBackBuffer will never be sent in a reply,
event, or error where a Window is specified.
If backing-store and save-under applies to a
double-buffered window, it applies to both buffers
equally.
XFree86 Version 4.5.0 2
DBE(3X11) X FUNCTIONS DBE(3X11)
If the XClearArea() or XClearWindow() function is
executed on a double-buffered window, the same
area in both the front and back buffers is
cleared.
The effect of passing a window to a function that
accepts a drawable is unchanged by this extension. The
window and front buffer are synonymous with each other.
This includes obeying the XGetImage() and XGetSubIm-
age() semantics and the subwindow-mode semantics if a
graphics context is involved. Regardless of whether
the window was explicitly passed in an XGetImage() or
XGetSubImage() call, or implicitly referenced (i.e.,
one of the window's ancestors was passed in the func-
tion), the front (i.e. visible) buffer is always refer-
enced. Thus, DBE-naive screen dump clients will always
get the front buffer. XGetImage() and XGetSubImage() on
a back buffer return undefined image contents for any
obscured regions of the back buffer that fall within
the image.
Drawing to a back buffer always uses the clip region
that would be used to draw to the front buffer with a
GC subwindow-mode of ClipByChildren. If an ancestor of
a double-buffered window is drawn to with a GC having a
subwindow-mode of IncludeInferiors, the effect on the
double-buffered window's back buffer depends on the
depth of the double-buffered window and the ancestor.
If the depths are the same, the contents of the back
buffer of the double-buffered window are not changed.
If the depths are different, the contents of the back
buffer of the double-buffered window are undefined for
the pixels that the IncludeInferiors drawing touched.
DBE adds no new events. DBE does not extend the seman-
tics of any existing events with the exception of
adding a new drawable type called XdbeBackBuffer.
If events, replies, or errors that contain a drawable
(e.g., GraphicsExpose) are generated in response to a
request, the drawable returned will be the one speci-
fied in the request.
DBE advertises which visuals support double buffering.
DBE does not include any timing or synchronization
facilities. Applications that need such facilities
(e.g., to maintain a constant frame rate) should inves-
tigate the Synchronization Extension, an X Consortium
standard.
Window Management Operations
XFree86 Version 4.5.0 3
DBE(3X11) X FUNCTIONS DBE(3X11)
The basic philosophy of DBE is that both buffers are
treated the same by X window management operations.
When a double-buffered window is destroyed, both
buffers associated with the window are destroyed, and
all back buffer names associated with the window are
freed.
If the size of a double-buffered window changes, both
buffers assume the new size. If the window's size
increases, the effect on the buffers depends on whether
the implementation honors bit gravity for buffers. If
bit gravity is implemented, then the contents of both
buffers are moved in accordance with the window's bit
gravity, and the remaining areas are tiled with the
window background. If bit gravity is not implemented,
then the entire unobscured region of both buffers is
tiled with the window background. In either case,
Expose events are generated for the region that is
tiled with the window background.
If the XGetGeometry() function is executed on an
XdbeBackBuffer, the returned x, y, and border-width
will be zero.
If the Shape extension ShapeRectangles, ShapeMask,
ShapeCombine, or ShapeOffset request is executed on a
double-buffered window, both buffers are reshaped to
match the new window shape. The region difference D =
new shape - old shape is tiled with the window back-
ground in both buffers, and Expose events are generated
for D.
Complex Swap Actions
DBE has no explicit knowledge of ancillary buffers
(e.g. depth buffers or alpha buffers), and only has a
limited set of defined swap actions. Some applications
may need a richer set of swap actions than DBE pro-
vides. Some DBE implementations have knowledge of
ancillary buffers, and/or can provide a rich set of
swap actions. Instead of continually extending DBE to
increase its set of swap actions, DBE provides a flexi-
ble "idiom" mechanism. If an applications's needs are
served by the defined swap actions, it should use them;
otherwise, it should use the following method of
expressing a complex swap action as an idiom. Follow-
ing this policy will ensure the best possible perfor-
mance across a wide variety of implementations.
As suggested by the term "idiom," a complex swap action
should be expressed as a group/series of requests.
XFree86 Version 4.5.0 4
DBE(3X11) X FUNCTIONS DBE(3X11)
Taken together, this group of requests may be combined
into an atomic operation by the implementation, in
order to maximize performance. The set of idioms actu-
ally recognized for optimization is implementation
dependent. To help with idiom expression and interpre-
tation, an idiom must be surrounded by two function
calls: XdbeBeginIdiom() and XdbeEndIdiom(). Unless this
begin-end pair surrounds the idiom, it may not be
recognized by a given implementation, and performance
will suffer.
For example, if an application wants to swap buffers
for two windows, and use X to clear only certain planes
of the back buffers, the application would make the
following calls as a group, and in the following order:
XdbeBeginIdiom().
XdbeSwapBuffers() with XIDs for two windows, each
of which uses a swap action of Untouched.
XFillRectangle() to the back buffer of one window.
XFillRectangle() to the back buffer of the other
window.
XdbeEndIdiom().
The XdbeBeginIdiom() and XdbeEndIdiom() functions do
not perform any actions themselves. They are treated
as markers by implementations that can combine certain
groups/series of requests as idioms, and are ignored by
other implementations or for non-recognized
groups/series of requests. If these function calls are
made out of order, or are mismatched, no errors are
sent, and the functions are executed as usual, though
performance may suffer.
XdbeSwapBuffers() need not be included in an idiom.
For example, if a swap action of Copied is desired, but
only some of the planes should be copied, XCopyArea()
may be used instead of XdbeSwapBuffers(). If XdbeSwap-
Buffers() is included in an idiom, it should immedi-
ately follow the XdbeBeginIdiom() call. Also, when the
XdbeSwapBuffers() is included in an idiom, that
request's swap action will still be valid, and if the
swap action might overlap with another request, then
the final result of the idiom must be as if the
separate requests were executed serially. For example,
if the specified swap action is Untouched, and if a
XFillRectangle() using a client clip rectangle is done
to the window's back buffer after the XdbeSwapBuffers()
XFree86 Version 4.5.0 5
DBE(3X11) X FUNCTIONS DBE(3X11)
call, then the contents of the new back buffer (after
the idiom) will be the same as if the idiom was not
recognized by the implementation.
It is highly recommended that API providers define, and
application developers use, "convenience" functions
that allow client applications to call one procedure
that encapsulates common idioms. These functions will
generate the XdbeBeginIdiom(), idiom, and XdbeEndI-
diom() calls. Usage of these functions will ensure
best possible performance across a wide variety of
implementations.
XdbeAllocateBackBufferName(), XdbeBeginIdiom(), XdbeDeallo-
cateBackBufferName(), XdbeEndIdiom(), XdbeFreeVisualInfo(),
XdbeGetBackBufferAttributes(), XdbeGetVisualInfo(), Xdbe-
QueryExtension(), XdbeSwapBuffers().
XFree86 Version 4.5.0 6
Generated on 2012-02-20 02:47:02 by $MirOS: src/scripts/roff2htm,v 1.70 2011/12/03 18:21:12 tg Exp $
These manual pages and other documentation are copyrighted by their respective writers;
their source is available at our CVSweb,
AnonCVS, and other mirrors. The rest is Copyright © 2002‒2011 The MirOS Project, Germany.
This product includes material
provided by Thorsten Glaser.
This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.