Provided by: libxext-dev_1.3.3-1_amd64 bug

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  during  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  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 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
              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 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:

                     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,
              "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.

SEE ALSO

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