1DBE(3)                            X FUNCTIONS                           DBE(3)
2
3
4

NAME

6       DBE - Double Buffer Extension
7

SYNOPSIS

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

DESCRIPTION

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
30              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
37              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
48              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
64              In general, both the front and back buffers ae treated the same.
65              In particular, here are some important characteristics:
66
67                     Only  one buffer per window can be visible at a time (the
68                     front buffer).
69
70                     Both buffers associated with a window have the same  vis‐
71                     ual type, depth, width, height, and shape as the window.
72
73                     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
82                     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
87                     It  is  an  error (Window) to pass an XdbeBackBuffer in a
88                     function that expects a Window.
89
90                     An XdbeBackBuffer will never be sent in a  reply,  event,
91                     or error where a Window is specified.
92
93                     If  backing-store  and  save-under  applies  to a double-
94                     buffered window, it applies to both buffers equally.
95
96                     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
100              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
114              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
126              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
130              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
134              DBE advertises which visuals support double buffering.
135
136              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
141       Window Management Operations
142
143              The basic philosophy of DBE is that both buffers are treated the
144              same by X window management operations.
145
146              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
150              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
161              If the XGetGeometry() function is executed on an XdbeBackBuffer,
162              the returned x, y, and border-width will be zero.
163
164              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
171       Complex Swap Actions
172
173              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 applications's  needs  are  served  by  the  defined  swap
181              actions,  it  should use them; otherwise, it should use the fol‐
182              lowing 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
186              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
197              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
202                     XdbeBeginIdiom().
203
204                     XdbeSwapBuffers() with XIDs  for  two  windows,  each  of
205                     which uses a swap action of Untouched.
206
207                     XFillRectangle() to the back buffer of one window.
208
209                     XFillRectangle() to the back buffer of the other window.
210
211                     XdbeEndIdiom().
212
213              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
222              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
226              idiom, 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
229              action 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
232              Untouched, and if a XFillRectangle() using a client clip rectan‐
233              gle  is  done  to  the  window's back buffer after the XdbeSwap‐
234              Buffers() call, then the contents of the new back buffer  (after
235              the  idiom)  will be the same as if the idiom was not recognized
236              by the implementation.
237
238              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
241              idioms.   These  functions  will  generate the XdbeBeginIdiom(),
242              idiom, and XdbeEndIdiom() calls.  Usage of these functions  will
243              ensure best possible performance across a wide variety of imple‐
244              mentations.
245

SEE ALSO

247       XdbeAllocateBackBufferName(),   XdbeBeginIdiom(),   XdbeDeallocateBack‐
248       BufferName(),  XdbeEndIdiom(), XdbeFreeVisualInfo(), XdbeGetBackBuffer‐
249       Attributes(),  XdbeGetVisualInfo(),   XdbeQueryExtension(),   XdbeSwap‐
250       Buffers().
251
252
253
254
255X Version 11                     libXext 1.3.3                          DBE(3)
Impressum