1DBE(3) X FUNCTIONS DBE(3)
2
6 DBE - Double Buffer Extension
7
9 The Double Buffer Extension (DBE) provides a standard way to utilize
10 double-buffering within the framework of the X Window System. Double-
11 buffering uses two buffers, called front and back, which hold images.
12 The front buffer is visible to the user; the back buffer is not. Suc‐
13 cessive frames of an animation are rendered into the back buffer while
14 the previously rendered frame is displayed in the front buffer. When a
15 new frame is ready, the back and front buffers swap roles, making the
16 new frame visible. Ideally, this exchange appears to happen instanta‐
17 neously to the user, with no visual artifacts. Thus, only completely
18 rendered images are presented to the user, and remain visible during
19 the entire time it takes to render a new frame. The result is a
20 flicker-free animation.
21
23 Concepts
24 Normal windows are created using XCreateWindow() or XCreateSim‐
25 pleWindow(), which allocate a set of window attributes and, for
26 InputOutput windows, a front buffer, into which an image can be
27 drawn. The contents of this buffer will be displayed when the
28 window is visible.
29 This extension enables applications to use double-buffering with
31 a window. This involves creating a second buffer, called a back
32 buffer, and associating one or more back buffer names (XIDs)
33 with the window, for use when referring to (i.e., drawing to or
34 reading from) the window's back buffer. The back buffer name is
35 a drawable of type XdbeBackBuffer.
36 DBE provides a relative double-buffering model. One XID, the
38 window, always refers to the front buffer. One or more other
39 XIDs, the back buffer names, always refer to the back buffer.
40 After a buffer swap, the window continues to refer to the (new)
41 front buffer, and the back buffer name continues to refer to the
42 (new) back buffer. Thus, applications and toolkits that want to
43 just render to the back buffer always use the back buffer name
44 for all drawing requests to the window. Portions of an applica‐
45 tion that want to render to the front buffer always use the win‐
46 dow XID for all drawing requests to the window.
47 Multiple clients and toolkits can all use double-buffering on
49 the same window. DBE does not provide a request for querying
50 whether a window has double-buffering support, and if so, what
51 the back buffer name is. Given the asynchronous nature of the X
52 Window System, this would cause race conditions. Instead, DBE
53 allows multiple back buffer names to exist for the same window;
54 they all refer to the same physical back buffer. The first time
55 a back buffer name is allocated for a window, the window becomes
56 double-buffered and the back buffer name is associated with the
57 window. Subsequently, the window already is a double-buffered
58 window, and nothing about the window changes when a new back
59 buffer name is allocated, except that the new back buffer name
60 is associated with the window. The window remains double-
61 buffered until either the window is destroyed, or until all of
62 the back buffer names for the window are deallocated.
63 In general, both the front and back buffers ae treated the same.
65 In particular, here are some important characteristics:
66 Only one buffer per window can be visible at a time (the
68 front buffer).
69 Both buffers associated with a window have the same vis‐
71 ual type, depth, width, height, and shape as the window.
72 Both buffers associated with a window are "visible" (or
74 "obscured") in the same way. When an Expose event is
75 generated for a window, this event is considered to apply
76 to both buffers equally. When a double-buffered window
77 is exposed, both buffers are tiled with the window back‐
78 ground. Even though the back buffer is not visible,
79 terms such as obscure apply to the back buffer as well as
80 to the front buffer.
81 It is acceptable at any time to pass an XdbeBackBuffer in
83 any function that expects a drawable. This enables an
84 application to draw directly into XdbeBackBuffer in the
85 same fashion as it would draw into any other drawable.
86 It is an error (Window) to pass an XdbeBackBuffer in a
88 function that expects a Window.
89 An XdbeBackBuffer will never be sent in a reply, event,
91 or error where a Window is specified.
92 If backing-store and save-under applies to a double-
94 buffered window, it applies to both buffers equally.
95 If the XClearArea() or XClearWindow() function is exe‐
97 cuted on a double-buffered window, the same area in both
98 the front and back buffers is cleared.
99 The effect of passing a window to a function that accepts a
101 drawable is unchanged by this extension. The window and front
102 buffer are synonymous with each other. This includes obeying
103 the XGetImage() and XGetSubImage() semantics and the subwindow-
104 mode semantics if a graphics context is involved. Regardless of
105 whether the window was explicitly passed in an XGetImage() or
106 XGetSubImage() call, or implicitly referenced (i.e., one of the
107 window's ancestors was passed in the function), the front (i.e.
108 visible) buffer is always referenced. Thus, DBE-naive screen
109 dump clients will always get the front buffer. XGetImage() and
110 XGetSubImage() on a back buffer return undefined image contents
111 for any obscured regions of the back buffer that fall within the
112 image.
113 Drawing to a back buffer always uses the clip region that would
115 be used to draw to the front buffer with a GC subwindow-mode of
116 ClipByChildren. If an ancestor of a double-buffered window is
117 drawn to with a GC having a subwindow-mode of IncludeInferiors,
118 the effect on the double-buffered window's back buffer depends
119 on the depth of the double-buffered window and the ancestor. If
120 the depths are the same, the contents of the back buffer of the
121 double-buffered window are not changed. If the depths are dif‐
122 ferent, the contents of the back buffer of the double-buffered
123 window are undefined for the pixels that the IncludeInferiors
124 drawing touched.
125 DBE adds no new events. DBE does not extend the semantics of
127 any existing events with the exception of adding a new drawable
128 type called XdbeBackBuffer.
129 If events, replies, or errors that contain a drawable (e.g.,
131 GraphicsExpose) are generated in response to a request, the
132 drawable returned will be the one specified in the request.
133 DBE advertises which visuals support double buffering.
135 DBE does not include any timing or synchronization facilities.
137 Applications that need such facilities (e.g., to maintain a con‐
138 stant frame rate) should investigate the Synchronization Exten‐
139 sion, an X Consortium standard.
140 Window Management Operations
142 The basic philosophy of DBE is that both buffers are treated the
144 same by X window management operations.
145 When a double-buffered window is destroyed, both buffers associ‐
147 ated with the window are destroyed, and all back buffer names
148 associated with the window are freed.
149 If the size of a double-buffered window changes, both buffers
151 assume the new size. If the window's size increases, the effect
152 on the buffers depends on whether the implementation honors bit
153 gravity for buffers. If bit gravity is implemented, then the
154 contents of both buffers are moved in accordance with the win‐
155 dow's bit gravity, and the remaining areas are tiled with the
156 window background. If bit gravity is not implemented, then the
157 entire unobscured region of both buffers is tiled with the win‐
158 dow background. In either case, Expose events are generated for
159 the region that is tiled with the window background.
160 If the XGetGeometry() function is executed on an XdbeBackBuffer,
162 the returned x, y, and border-width will be zero.
163 If the Shape extension ShapeRectangles, ShapeMask, ShapeCombine,
165 or ShapeOffset request is executed on a double-buffered window,
166 both buffers are reshaped to match the new window shape. The
167 region difference D = new shape - old shape is tiled with the
168 window background in both buffers, and Expose events are gener‐
169 ated for D.
170 Complex Swap Actions
172 DBE has no explicit knowledge of ancillary buffers (e.g. depth
174 buffers or alpha buffers), and only has a limited set of defined
175 swap actions. Some applications may need a richer set of swap
176 actions than DBE provides. Some DBE implementations have knowl‐
177 edge of ancillary buffers, and/or can provide a rich set of swap
178 actions. Instead of continually extending DBE to increase its
179 set of swap actions, DBE provides a flexible "idiom" mechanism.
180 If an application's needs are served by the defined swap ac‐
181 tions, it should use them; otherwise, it should use the follow‐
182 ing method of expressing a complex swap action as an idiom.
183 Following this policy will ensure the best possible performance
184 across a wide variety of implementations.
185 As suggested by the term "idiom," a complex swap action should
187 be expressed as a group/series of requests. Taken together,
188 this group of requests may be combined into an atomic operation
189 by the implementation, in order to maximize performance. The
190 set of idioms actually recognized for optimization is implemen‐
191 tation dependent. To help with idiom expression and interpreta‐
192 tion, an idiom must be surrounded by two function calls: XdbeBe‐
193 ginIdiom() and XdbeEndIdiom(). Unless this begin-end pair sur‐
194 rounds the idiom, it may not be recognized by a given implemen‐
195 tation, and performance will suffer.
196 For example, if an application wants to swap buffers for two
198 windows, and use X to clear only certain planes of the back buf‐
199 fers, the application would make the following calls as a group,
200 and in the following order:
201 XdbeBeginIdiom().
203 XdbeSwapBuffers() with XIDs for two windows, each of
205 which uses a swap action of Untouched.
206 XFillRectangle() to the back buffer of one window.
208 XFillRectangle() to the back buffer of the other window.
210 XdbeEndIdiom().
212 The XdbeBeginIdiom() and XdbeEndIdiom() functions do not perform
214 any actions themselves. They are treated as markers by imple‐
215 mentations that can combine certain groups/series of requests as
216 idioms, and are ignored by other implementations or for non-rec‐
217 ognized groups/series of requests. If these function calls are
218 made out of order, or are mismatched, no errors are sent, and
219 the functions are executed as usual, though performance may suf‐
220 fer.
221 XdbeSwapBuffers() need not be included in an idiom. For exam‐
223 ple, if a swap action of Copied is desired, but only some of the
224 planes should be copied, XCopyArea() may be used instead of
225 XdbeSwapBuffers(). If XdbeSwapBuffers() is included in an id‐
226 iom, it should immediately follow the XdbeBeginIdiom() call.
227 Also, when the XdbeSwapBuffers() is included in an idiom, that
228 request's swap action will still be valid, and if the swap ac‐
229 tion might overlap with another request, then the final result
230 of the idiom must be as if the separate requests were executed
231 serially. For example, if the specified swap action is Un‐
232 touched, and if a XFillRectangle() using a client clip rectangle
233 is done to the window's back buffer after the XdbeSwapBuffers()
234 call, then the contents of the new back buffer (after the idiom)
235 will be the same as if the idiom was not recognized by the im‐
236 plementation.
237 It is highly recommended that API providers define, and applica‐
239 tion developers use, "convenience" functions that allow client
240 applications to call one procedure that encapsulates common id‐
241 ioms. These functions will generate the XdbeBeginIdiom(), id‐
242 iom, and XdbeEndIdiom() calls. Usage of these functions will
243 ensure best possible performance across a wide variety of imple‐
244 mentations.
245
247 XdbeAllocateBackBufferName(), XdbeBeginIdiom(), XdbeDeallocateBack‐
248 BufferName(), XdbeEndIdiom(), XdbeFreeVisualInfo(), XdbeGetBackBuffer‐
249 Attributes(), XdbeGetVisualInfo(), XdbeQueryExtension(), XdbeSwap‐
250 Buffers().
251X Version 11 libXext 1.3.5 DBE(3)