Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DBE(3)				  X FUNCTIONS				DBE(3)

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.	  Suc-
       cessive	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  instanta-
       neously	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  XCreateSim-
	      pleWindow(),  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 applica-
	      tion that	want to	render to the front buffer always use the win-
	      dow 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  vis-
		     ual 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 back-
		     ground.  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  exe-
		     cuted  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 dif-
	      ferent, 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 con-
	      stant frame rate)	should investigate the Synchronization	Exten-
	      sion, 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 associ-
	      ated  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  win-
	      dow'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 win-
	      dow 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	gener-
	      ated 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	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  ac-
	      tions,  it should	use them; otherwise, it	should use the follow-
	      ing 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  implemen-
	      tation dependent.	 To help with idiom expression and interpreta-
	      tion, an idiom must be surrounded	by two function	calls: XdbeBe-
	      ginIdiom()  and XdbeEndIdiom().  Unless this begin-end pair sur-
	      rounds the idiom,	it may not be recognized by a given  implemen-
	      tation, 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 buf-
	      fers, 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	imple-
	      mentations that can combine certain groups/series	of requests as
	      idioms, and are ignored by other implementations or for non-rec-
	      ognized  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 suf-
	      fer.

	      XdbeSwapBuffers()	need not be included in	an idiom.   For	 exam-
	      ple, 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 id-
	      iom, 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  ac-
	      tion  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 Un-
	      touched, 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 im-
	      plementation.

	      It is highly recommended that API	providers define, and applica-
	      tion  developers	use, "convenience" functions that allow	client
	      applications to call one procedure that encapsulates common  id-
	      ioms.   These  functions will generate the XdbeBeginIdiom(), id-
	      iom, and XdbeEndIdiom() calls.  Usage of	these  functions  will
	      ensure best possible performance across a	wide variety of	imple-
	      mentations.

SEE ALSO
       XdbeAllocateBackBufferName(),   XdbeBeginIdiom(),   XdbeDeallocateBack-
       BufferName(),  XdbeEndIdiom(), XdbeFreeVisualInfo(), XdbeGetBackBuffer-
       Attributes(),  XdbeGetVisualInfo(),   XdbeQueryExtension(),   XdbeSwap-
       Buffers().

X Version 11			 libXext 1.3.3				DBE(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DBE&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help