<HTML>
<HEAD>
<TITLE></TITLE>
</HEAD>
<BODY>
<PRE>



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


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

DESCRIPTION
       Concepts
	      Normal windows are created using XCreateWindow() or
	      XCreateSimpleWindow(), 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 (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 XdbeBack_
	      Buffer.

	      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
		     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 XdbeBack_
		     Buffer 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



X Version 11		   Release 6.1				2





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


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

		     If	 the XClearArea() or XClearWindow() 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 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 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	XdbeBack_
	      Buffer.

	      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.

       Window Management Operations

	      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 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 differ
	      ence 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 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:  XdbeBeginId
	      iom()  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 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.

	      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, XCop
	      yArea()  may  be used instead of XdbeSwapBuffers().



X Version 11		   Release 6.1				5





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


	      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 win
	      dow'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" func
	      tions  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(),	XdbeDeal_
       locateBackBufferName(),	 XdbeEndIdiom(),  XdbeFreeVisual_
       Info(),	 XdbeGetBackBufferAttributes(),	   XdbeGetVisual_
       Info(), XdbeQueryExtension(), XdbeSwapBuffers().




























X Version 11		   Release 6.1				6


</PRE>
</BODY>
</HTML>
