MAN page from CentOS Other libXext-devel-1.3.4-1.el8.i686.rpm
Section: X FUNCTIONS (3)
Updated: libXext 1.3.4Index
DBE - Double Buffer Extension
The Double Buffer Extension (DBE) provides a standard way to utilizedouble-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. Successiveframes of an animation are rendered into the back buffer while the previouslyrendered 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 visualartifacts. Thus, only completely rendered images are presented to the user,and remain visible during the entire time it takes to render a new frame. Theresult is a flicker-free animation.
- Normal windows are created usingXCreateWindow()orXCreateSimpleWindow(),which allocate a set of window attributes and, for InputOutput windows, a frontbuffer, into which an image can be drawn. The contents of this buffer will bedisplayed 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 associatingone or more back buffer names(XIDs)with the window, for use when referringto (i.e., drawing to or reading from) the window's back buffer.The back buffer name is a drawable of typeXdbeBackBuffer.
DBE provides a relative double-buffering model. One XID, the window,always refers to the front buffer. One or more other XIDs, the back buffernames, always refer to the back buffer. After a buffer swap, the windowcontinues to refer to the (new) front buffer, and the back buffer namecontinues to refer to the (new) back buffer. Thus, applications and toolkitsthat want to just render to the back buffer always use the back buffer namefor all drawing requests to the window. Portions of an application that wantto render to the front buffer always use the window XID for all drawingrequests 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 hasdouble-buffering support, and if so, what the back buffer name is. Given theasynchronous nature of the X Window System, this would cause raceconditions. Instead, DBE allows multiple back buffer names to exist for thesame window; they all refer to the same physical back buffer. The first time aback buffer name is allocated for a window, the window becomesdouble-buffered and the back buffer name is associated with the window.Subsequently, the window already is a double-buffered window, and nothingabout the window changes when a new back buffer name is allocated, exceptthat the new back buffer name is associated with the window. The windowremains double-buffered until either the window is destroyed, or until all ofthe back buffer names for the window are deallocated.
In general, both the front and back buffers ae treated the same. Inparticular, 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") inthe same way. When an Expose event is generated for a window, thisevent is considered to apply to both buffers equally. When adouble-buffered window is exposed, both buffers are tiled with thewindow background.Even though the back buffer is not visible, terms such as obscure apply to theback buffer as well as to the front buffer.
It is acceptable at any time to pass anXdbeBackBufferin any function that expects a drawable.This enables an application to draw directly intoXdbeBackBufferin the same fashion as it would draw into any other drawable.
It is an error (Window) to pass anXdbeBackBufferin a function that expects a Window.
AnXdbeBackBufferwill never be sent in a reply, event, or error where a Window is specified.
If backing-store and save-under applies to a double-bufferedwindow, it applies to both buffers equally.
If theXClearArea()orXClearWindow()function is executed on adouble-buffered window, the same area in both the front and back buffersis cleared.
The effect of passing a window to a function that accepts a drawableis unchanged by this extension. The window and front buffer are synonymouswith each other. This includes obeying theXGetImage()andXGetSubImage()semantics and the subwindow-mode semantics if a graphics context isinvolved. Regardless of whether the window was explicitly passed in anXGetImage()orXGetSubImage()call, or implicitly referenced (i.e., one ofthe 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()andXGetSubImage()on a backbuffer return undefined image contents for any obscured regions of the backbuffer that fall within the image.
Drawing to a back buffer always uses the clip region that would be used todraw to the front buffer with a GC subwindow-mode of ClipByChildren. If anancestor of a double-buffered window is drawn to with a GC having asubwindow-mode of IncludeInferiors, the effect on the double-bufferedwindow's back buffer depends on the depth of the double-buffered windowand the ancestor. If the depths are the same, the contents of the back bufferof the double-buffered window are not changed. If the depths are different,the contents of the back buffer of the double-buffered window are undefinedfor the pixels that the IncludeInferiors drawing touched.
DBE adds no new events. DBE does not extend the semantics of any existingevents with the exception of adding a new drawable type calledXdbeBackBuffer.
If events, replies, or errors that contain a drawable(e.g., GraphicsExpose) are generated in response to a request, thedrawable 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. Applicationsthat need such facilities (e.g., to maintain a constant frame rate) shouldinvestigate the Synchronization Extension, an X Consortium standard.
Window Management Operations
- The basic philosophy of DBE is that both buffers are treated the same byX window management operations.
When a double-buffered window is destroyed,both buffers associated with the window are destroyed, and all back buffernames associated with the window are freed.
If the size of a double-buffered window changes, bothbuffers assume the new size. If the window's size increases, the effect on thebuffers depends on whether the implementation honors bit gravity for buffers.If bit gravity is implemented, then the contents of both buffers are moved inaccordance with the window's bit gravity,and the remaining areas are tiled with the window background. Ifbit gravity is not implemented, then the entire unobscured region of bothbuffers is tiled with the window background. In either case, Expose events aregenerated for the region that is tiled with the window background.
If theXGetGeometry()function is executed on anXdbeBackBuffer,the returned x, y, and border-width will be zero.
If the Shape extensionShapeRectangles, ShapeMask, ShapeCombine,orShapeOffsetrequest is executed on a double-buffered window, bothbuffers are reshaped to match the new window shape. The region differenceD = new shape - old shape is tiled with the window background in bothbuffers, and Expose events are generated for D.
Complex Swap Actions
- DBE has no explicit knowledge of ancillary buffers (e.g. depth buffers oralpha buffers), and only has a limited set of defined swap actions. Someapplications may need a richer set of swap actions than DBE provides. SomeDBE implementations have knowledge of ancillary buffers, and/or can providea rich set of swap actions. Instead of continually extending DBE to increaseits set of swap actions, DBE provides a flexible "idiom" mechanism. If anapplication's needs are served by the defined swap actions, it should usethem; otherwise, it should use the following method of expressing a complexswap action as an idiom. Following this policy will ensure the best possibleperformance across a wide variety of implementations.
As suggested by the term "idiom," a complex swap action should be expressedas a group/series of requests. Taken together, this group of requests may becombined into an atomic operation by the implementation, in order tomaximize performance. The set of idioms actually recognized for optimizationis implementation dependent. To help with idiom expression andinterpretation, an idiom must be surrounded by two function calls:XdbeBeginIdiom()andXdbeEndIdiom().Unless this begin-end pairsurrounds the idiom, it may not be recognized by a given implementation, andperformance will suffer.
For example, if an application wants to swap buffers for two windows, and useX to clear only certain planes of the back buffers, the application wouldmake the following calls as a group, and in the following order:
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.
TheXdbeBeginIdiom()andXdbeEndIdiom()functions do not perform anyactions themselves. They are treated as markers by implementations that cancombine certain groups/series of requests as idioms, and are ignored by otherimplementations or for non-recognized groups/series of requests. If thesefunction 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. Forexample, if a swap action of Copied is desired, but only some of the planesshould be copied,XCopyArea()may be used instead ofXdbeSwapBuffers().IfXdbeSwapBuffers()is included in an idiom, it should immediately follow theXdbeBeginIdiom()call. Also, when theXdbeSwapBuffers()is included in an idiom, that request's swap action willstill be valid, and if the swap action might overlap with another request, thenthe final result of the idiom must be as if the separate requests were executedserially. For example, if the specified swap action is Untouched, and if aXFillRectangle()using a client clip rectangle is done to the window's backbuffer after theXdbeSwapBuffers()call, then the contents of the newback buffer (after the idiom) will be the same as if the idiom was notrecognized by the implementation.
It is highly recommended that API providers define, and applicationdevelopers use, "convenience" functions that allow client applications to callone procedure that encapsulates common idioms. These functions willgenerate theXdbeBeginIdiom(),idiom, andXdbeEndIdiom()calls. Usage of these functions will ensure best possibleperformance across a wide variety of implementations.
- SEE ALSO
This document was created byman2html,using the manual pages.