|
|
This manual page is for Mac OS X version 10.6.3If you are running a different version of Mac OS X, view the documentation locally:
Reading manual pagesManual pages are intended as a quick reference for people who already understand a technology.
|
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. 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 dur-ing during
ing 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 cre-ating creating
ating 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 win-dow's window's
dow'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 associ-ated associated
ated with the window. Subsequently, the window already is a double-buffered window, and noth-ing nothing
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 deal-located. deallocated.
located.
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 DBEnaive
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 doublebuffered
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 hon-ors honors
ors 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 gener-ated generated
ated for the region that is tiled with the window background.
If the XGetGeometry() function is executed on an XdbeBackBuffer, the returned x, y, and bor-der-width border-width
der-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 applica-tions's applications's
tions'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 pol-icy policy
icy 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 recog-nized recognized
nized for optimization is implementation dependent. To help with idiom expression and inter-pretation, interpretation,
pretation, an idiom must be surrounded by two function calls: XdbeBeginIdiom() and XdbeEndId-iom(). XdbeEndIdiom().
iom(). 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, "conve-nience" "convenience"
nience" functions that allow client applications to call one procedure that encapsulates com-mon common
mon 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(), Xdbe-FreeVisualInfo(), XdbeFreeVisualInfo(),
FreeVisualInfo(), XdbeGetBackBufferAttributes(), XdbeGetVisualInfo(), XdbeQueryExtension(), XdbeSwap-Buffers(). XdbeSwapBuffers().
Buffers().
X Version 11 libXext 1.0.5 DBE(3)
|
The way to report a problem with this manual page depends on the type of problem: