Provided by: libxext-dev_1.3.3-1_amd64 
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 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 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-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 window.
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 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 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 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 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 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 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 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 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 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 applications
may need a richer set of swap actions than DBE provides. 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 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 optimization is implementation dependent.
To help with idiom expression and interpretation, 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 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 window'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" 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 implementations.
SEE ALSO
XdbeAllocateBackBufferName(), XdbeBeginIdiom(), XdbeDeallocateBackBufferName(),
XdbeEndIdiom(), XdbeFreeVisualInfo(), XdbeGetBackBufferAttributes(), XdbeGetVisualInfo(),
XdbeQueryExtension(), XdbeSwapBuffers().