DBE(3X11)
NAME
DBE - Double Buffer Extension
SYNOPSIS
The Double Buffer Extension (DBE) provides a standard way
to utilize double-buffering within the framework of the X
Window 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 previously 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 com-
pletely 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.
DESCRIPTION
Concepts
Normal windows are created using XCreateWindow() or
XCreateSimpleWindow(), which allocate a set of win-
dow 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 associat-
ing 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 XdbeBack-
Buffer.
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 con-
tinues 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-
buffering support, and if so, what the back buffer
name is. Given the asynchronous nature of the X
Window System, 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 win-
dow already is a double-buffered window, and noth-
ing 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
destroyed, 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
"visible" (or "obscured") in the same way.
When an Expose event is generated for a win-
dow, 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
XdbeBackBuffer 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 XdbeBack-
Buffer 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.
If the XClearArea() or XClearWindow() func-
tion is executed on a double-buffered win-
dow, 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 synonomous with
each other. This includes obeying the XGetImage()
and XGetSubImage() 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 function), the front
(i.e. visible) buffer is always referenced. 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 IncludeIn-
feriors, 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
semantics of any existing events with the exception
of adding a new drawable type called XdbeBack-
Buffer.
If events, replies, or errors that contain a draw-
able (e.g., GraphicsExpose) are generated in
response to a request, the drawable returned will
be the one specified in the request.
DBE advertises which visuals support double buffer-
ing.
DBE does not include any timing or synchronization
facilities. Applications that need such facilities
(e.g., to maintain a constant frame rate) should
investigate the Synchronization Extension, an X
Consortium standard.
Window Management Operations
The basic philosophy of DBE is that both buffers
are treated the same by X window management opera-
tions.
When a double-buffered window is destroyed, both
buffers associated with the window are destroyed,
and all back buffer names associated with the win-
dow 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 accor-
dance with the window's bit gravity, and the
remaining areas are tiled with the window back-
ground. 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 differ-
ence D = new shape - old shape is tiled with the
window background 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 appli-
cations may need a richer set of swap actions than
DBE provides. Some DBE implementations have knowl-
edge 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 flexible "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. Following this policy
will ensure the best possible performance 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. 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 actually recognized for optimiza-
tion is implementation dependent. To help with
idiom expression and interpretation, an idiom must
be surrounded by two function calls: XdbeBeginId-
iom() 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 com-
bine 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 mis-
matched, 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, XCop-
yArea() may be used instead of XdbeSwapBuffers().
If XdbeSwapBuffers() is included in an idiom, it
should immediately 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 win-
dow's back buffer after the XdbeSwapBuffers() 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" func-
tions that allow client applications to call one
procedure that encapsulates common idioms. These
functions will generate the XdbeBeginIdiom(),
idiom, and XdbeEndIdiom() calls. Usage of these
functions will ensure best possible performance
across a wide variety of implementations.
SEE ALSO
XdbeAllocateBackBufferName() XdbeBeginIdiom() XdbeDeal-
locateBackBufferName() XdbeEndIdiom() XdbeFreeVisual-
Info() XdbeGetBackBufferAttributes() XdbeGetVisual-
Info() XdbeQueryExtension() XdbeSwapBuffers().