Geek Gadgets 1/ADE-1.bin/ade-bin/x11r6.1/man/cat3/dbe.0

Text File | 1996-10-17 | 15.8 KB | 397 lines

DBE(3X11)           X FUNCTIONS            DBE(3X11)


NNAAMMEE
       DBE - Double Buffer Extension

SSYYNNOOPPSSIISS
       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 com-
       pletely 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.

DDEESSCCRRIIPPTTIIOONN
       CCoonncceeppttss
          Normal windows are created using XXCCrreeaatteeWWiinnddooww(()) or
          XXCCrreeaatteeSSiimmpplleeWWiinnddooww(()),, which allocate a set of win-
          dow 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 associat-
          ing one or more back buffer names _(_X_I_D_s_)    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 _X_d_b_e_B_a_c_k_-
          _B_u_f_f_e_r_.

          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 con-
          tinues 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-



X Version 11           Release 6.1                1





DBE(3X11)           X FUNCTIONS            DBE(3X11)


          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 win-
          dow already is a double-buffered window, and  noth-
          ing 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 win-
             dow, 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
             _X_d_b_e_B_a_c_k_B_u_f_f_e_r  in any function that expects
             a drawable.  This enables an application  to
             draw  directly  into  _X_d_b_e_B_a_c_k_B_u_f_f_e_r  in the
             same fashion as it would draw into any other
             drawable.

             It is an error (Window) to pass an _X_d_b_e_B_a_c_k_-
             _B_u_f_f_e_r in a function that expects a  Window.

             An     _X_d_b_e_B_a_c_k_B_u_f_f_e_r     will  never be sent in a
             reply, event, or error  where  a  Window  is
             specified.

             If backing-store and save-under applies to a



X Version 11           Release 6.1                2





DBE(3X11)           X FUNCTIONS            DBE(3X11)


             double-buffered window, it applies     to  both
             buffers equally.

             If     the XXCClleeaarrAArreeaa(()) or XXCClleeaarrWWiinnddooww(()) func-
             tion is executed on a  double-buffered  win-
             dow,  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     synonomous  with
          each  other.  This includes obeying the XXGGeettIImmaaggee(())
          and XXGGeettSSuubbIImmaaggee(()) semantics and the subwindow-mode
          semantics      if  a     graphics  context  is    involved.
          Regardless of whether  the  window  was  explicitly
          passed in an XXGGeettIImmaaggee(()) or XXGGeettSSuubbIImmaaggee(()) 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.  XXGGeettIImmaaggee(()) and XXGGeettSSuubbIImmaaggee(()) 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 IncludeIn-
          feriors, 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    _X_d_b_e_B_a_c_k_-
          _B_u_f_f_e_r_.

          If  events, replies, or errors that contain a draw-
          able  (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 buffer-
          ing.

          DBE  does not include any timing or synchronization



X Version 11           Release 6.1                3





DBE(3X11)           X FUNCTIONS            DBE(3X11)


          facilities.  Applications that need such facilities
          (e.g.,  to  maintain  a constant frame rate) should
          investigate the  Synchronization    Extension,  an    X
          Consortium standard.

       WWiinnddooww MMaannaaggeemmeenntt OOppeerraattiioonnss

          The  basic  philosophy  of DBE is that both buffers
          are treated the same by X window management  opera-
          tions.

          When  a  double-buffered    window is destroyed, both
          buffers associated with the window  are  destroyed,
          and  all back buffer names associated with the win-
          dow 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 accor-
          dance  with  the    window's  bit  gravity,     and  the
          remaining     areas    are  tiled  with the window back-
          ground.  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 XXGGeettGGeeoommeettrryy(()) function is     executed  on  an
          _X_d_b_e_B_a_c_k_B_u_f_f_e_r_, the returned x, y, and border-width
          will be zero.

          If the Shape extension SShhaappeeRReeccttaanngglleess,,  SShhaappeeMMaasskk,,
          SShhaappeeCCoommbbiinnee,, or SShhaappeeOOffffsseett request is executed on
          a double-buffered window, both buffers are reshaped
          to  match the new window shape.  The region differ-
          ence D = new shape - old shape is     tiled    with  the
          window  background  in  both  buffers,  and  Expose
          events are generated for D.

       CCoommpplleexx SSwwaapp AAccttiioonnss

          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 appli-
          cations  may need a richer set of swap actions than
          DBE provides.  Some DBE implementations have knowl-
          edge  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



X Version 11           Release 6.1                4





DBE(3X11)           X FUNCTIONS            DBE(3X11)


          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 optimiza-
          tion is implementation  dependent.   To  help  with
          idiom  expression and interpretation, an idiom must
          be surrounded by two function  calls:  XXddbbeeBBeeggiinnIIdd--
          iioomm(())  and  XXddbbeeEEnnddIIddiioomm(())..   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:

             XXddbbeeBBeeggiinnIIddiioomm(())..

             XXddbbeeSSwwaappBBuuffffeerrss(()) with XIDs for two windows,
             each   of     which    uses  a     swap  action  of
             Untouched.

             XXFFiillllRReeccttaannggllee(()) to the back buffer  of  one
             window.

             XXFFiillllRReeccttaannggllee(())  to  the back buffer of the
             other window.

             XXddbbeeEEnnddIIddiioomm(())..

          The XXddbbeeBBeeggiinnIIddiioomm(()) and    XXddbbeeEEnnddIIddiioomm(())    functions
          do  not  perform    any actions themselves.     They are
          treated as markers by implementations that can com-
          bine  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  mis-
          matched,    no errors are sent, and the functions are
          executed as usual, though performance may suffer.

          XXddbbeeSSwwaappBBuuffffeerrss(()) 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, XXCCoopp--
          yyAArreeaa(())  may  be used instead of XXddbbeeSSwwaappBBuuffffeerrss(())..



X Version 11           Release 6.1                5





DBE(3X11)           X FUNCTIONS            DBE(3X11)


          If XXddbbeeSSwwaappBBuuffffeerrss(()) is included in  an  idiom,  it
          should   immediately  follow  the     XXddbbeeBBeeggiinnIIddiioomm(())
          call.  Also, when the XXddbbeeSSwwaappBBuuffffeerrss(()) 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     XXFFiillllRReeccttaannggllee(())
          using  a    client clip rectangle is done to the win-
          dow's back buffer after the XXddbbeeSSwwaappBBuuffffeerrss(()) 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" func-
          tions  that  allow  client applications to call one
          procedure that encapsulates common  idioms.   These
          functions      will     generate  the    XXddbbeeBBeeggiinnIIddiioomm(()),,
          idiom, and XXddbbeeEEnnddIIddiioomm(()) calls.     Usage    of  these
          functions     will  ensure  best  possible performance
          across a wide variety of implementations.

SSEEEE AALLSSOO
       _X_d_b_e_A_l_l_o_c_a_t_e_B_a_c_k_B_u_f_f_e_r_N_a_m_e_(_)_, _X_d_b_e_B_e_g_i_n_I_d_i_o_m_(_)_,    _X_d_b_e_D_e_a_l_-
       _l_o_c_a_t_e_B_a_c_k_B_u_f_f_e_r_N_a_m_e_(_)_,     _X_d_b_e_E_n_d_I_d_i_o_m_(_)_,  _X_d_b_e_F_r_e_e_V_i_s_u_a_l_-
       _I_n_f_o_(_)_,     _X_d_b_e_G_e_t_B_a_c_k_B_u_f_f_e_r_A_t_t_r_i_b_u_t_e_s_(_)_,       _X_d_b_e_G_e_t_V_i_s_u_a_l_-
       _I_n_f_o_(_)_, _X_d_b_e_Q_u_e_r_y_E_x_t_e_n_s_i_o_n_(_)_, _X_d_b_e_S_w_a_p_B_u_f_f_e_r_s_(_)_.




























X Version 11           Release 6.1                6