DBE(3) X FUNCTIONS DBE(3)
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. Suc-
cessive 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 instanta-
neously 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.
DESCRIPTION
Concepts
Normal windows are created using XCreateWindow() or XCreateSim-
pleWindow(), 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 applica-
tion that want to render to the front buffer always use the win-
dow 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 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 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 win-
dow.
Both buffers associated with a window are "visible" (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 back-
ground. 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 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.
If the XClearArea() or XClearWindow() function is exe-
cuted 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 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 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 dif-
ferent, 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 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 specified 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 con-
stant frame rate) should investigate the Synchronization Exten-
sion, an X Consortium standard.
Window Management Operations
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 associ-
ated 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 win-
dow'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 win-
dow 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 background in both buffers, and Expose events are gener-
ated 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 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 fol-
lowing 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 optimization is implemen-
tation dependent. To help with idiom expression and interpreta-
tion, an idiom must be surrounded by two function calls: XdbeBe-
ginIdiom() and XdbeEndIdiom(). Unless this begin-end pair sur-
rounds the idiom, it may not be recognized by a given implemen-
tation, 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 imple-
mentations that can combine certain groups/series of requests as
idioms, and are ignored by other implementations or for non-rec-
ognized 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 suf-
fer.
XdbeSwapBuffers() need not be included in an idiom. For exam-
ple, 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 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 rectan-
gle is done to the window's back buffer after the XdbeSwap-
Buffers() 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 applica-
tion developers use, "convenience" functions 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 imple-
mentations.
SEE ALSO
XdbeAllocateBackBufferName(3), XdbeBeginIdiom(3),
dbeDeallocateBackBufferName(3), XdbeEndIdiom(3), XdbeFreeVisualInfo(3),
XdbeGetBackBufferAttributes(3), XdbeGetVisualInfo(3),
XdbeQueryExtension(3), XdbeSwapBuffers(3).
X Version 11 libXext 1.0.5 DBE(3)
Mac OS X 10.6 X11 - Generated Sun Mar 7 12:29:32 CST 2010