Man Linux: Main Page and Category List


       DBE - Double Buffer Extension


       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.


              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

                     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

              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:


                     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.


              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.


       XdbeAllocateBackBufferName(),                         XdbeBeginIdiom(),
       XdbeDeallocateBackBufferName(),  XdbeEndIdiom(),  XdbeFreeVisualInfo(),
       XdbeGetBackBufferAttributes(),                     XdbeGetVisualInfo(),
       XdbeQueryExtension(), XdbeSwapBuffers().