libX11 libXext libXmu mesa xkeyboard-config git update Jun 2011

1 files changed, 728 insertions, 728 deletions

diff --git a/libXext/specs/dbelib.xml b/libXext/specs/dbelib.xml
index c786cae81..5a969a287 100644
--- a/libXext/specs/dbelib.xml
+++ b/libXext/specs/dbelib.xml
@@ -1,728 +1,728 @@
-<?xml version="1.0" encoding="UTF-8" ?>

-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"

-                   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

-

-

-<!-- lifted from troff+ms+XMan by doclifter -->

-<book id="dbelib">

-

-<bookinfo>

-   <title>Double Buffer Extension Library</title>

-   <subtitle>X Consortium Standard</subtitle>

-   <!-- <releaseinfo>X Version 11, Release 6.4</releaseinfo> -->

-   <authorgroup>

-      <author>

-         <firstname>Ian</firstname><surname>Elliot</surname>

-      </author>

-   </authorgroup>

-   <othercredit>

-      <firstname>Davide</firstname><surname>Wiggins</surname>

-   </othercredit>

-   <corpname>Hewlett-Packard Company</corpname>

-   <copyright><year>1989</year><holder>X Consortium, Inc and Digital Equipment Corporation</holder></copyright>

-   <copyright><year>1992</year><holder>X Consortium, Inc and Intergraph Corporation</holder></copyright>

-   <copyright><year>1993</year><holder>X Consortium, Inc and Silicon Graphics, Inc.</holder></copyright>

-   <copyright><year>1994</year><holder>X Consortium, Inc and Hewlett-Packard Company</holder></copyright>

-   <copyright><year>1995</year><holder>X Consortium, Inc and Hewlett-Packard Company</holder></copyright>

-   <releaseinfo>Version 1.0</releaseinfo>

-   <affiliation><orgname>X Consortium</orgname></affiliation>

-   <productnumber>X Version 11, Release 7</productnumber>

-

-<legalnotice>

-<para>

-Permission to use, copy, modify, and distribute this documentation for any

-purpose and without fee is hereby granted, provided that the above copyright

-notice and this permission notice appear in all copies. Digital Equipment

-Corporation, Intergraph Corporation, Silicon Graphics, Hewlett-Packard, and

-the X Consortium make no representations about the suitability for any

-purpose of the information in this document. This documentation is provided

-"as is" without express or implied warranty.

-</para>

-

-</legalnotice>

-

-</bookinfo>

-

-<chapter id="introduction">

-<title>Introduction</title>

-<para>

-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 and with no

-visual artifacts. Thus, only completely rendered images are presented to the

-user, and they remain visible during the entire time it takes to render a new

-frame. The result is a flicker-free animation.

-</para>

-

-</chapter>

-

-<chapter id="goals">

-<title>Goals</title>

-

-<para>

-This extension should enable clients to:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Allocate and deallocate double-buffering for a window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Draw to and read from the front and back buffers associated with a window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Swap the front and back buffers associated with a window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Specify a wide range of actions to be taken when a window is swapped.

-This includes explicit, simple swap actions (defined below), and more

-complex actions (for example, clearing ancillary buffers) that can be put

-together within explicit "begin" and "end" requests (defined below).

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Request that the front and back buffers associated with multiple

-double-buffered windows be swapped simultaneously.

-    </para>

-  </listitem>

-</itemizedlist>

-

-<para>

-In addition, the extension should:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Allow multiple clients to use double-buffering on the same window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Support a range of implementation methods that can capitalize on

-existing hardware features.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Add no new event types.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Be reasonably easy to integrate with a variety of direct graphics

-hardware access (DGHA) architectures.

-    </para>

-  </listitem>

-</itemizedlist>

-

-</chapter>

-

-<chapter id="concepts">

-<title>Concepts</title>

-<para>

-Normal windows are created using the core CreateWindow request, which

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

-</para>

-<para>

-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 (that is, drawing to or reading from) the window’s back buffer. The back

-buffer name is a DRAWABLE of type BACKBUFFER.

-</para>

-<para>

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

-</para>

-<para>

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

-</para>

-<para>

-In general, both the front and back buffers are treated the same.

-particular, here are some important characteristics:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Only one buffer per window can be visible at a time (the front buffer).

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Both buffers associated with a window have the same visual type, depth,

-width, height, and shape as the window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Both buffers associated with a window are "visible" (or "obscured") in

-the same way. When an Expose event is generated for a window, both

-buffers should be considered to be damaged in the exposed area.

-Damage that occurs to either buffer will result in an Expose event on

-the window. When a double-buffered window is exposed, both buffers

-are tiled with the window background, exactly as stated by the core

-protocol. Even though the back buffer is not visible, terms such as

-obscure apply to the back buffer as well as to the front buffer.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-It is acceptable at any time to pass a BACKBUFFER in any request,

-notably any core or extension drawing request, that expects a

-DRAWABLE.  This enables an application to draw directly into

-BACKBUFFERs in the same fashion as it would draw into any other

-DRAWABLE.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-It is an error (Window) to pass a BACKBUFFER in a core request that

-expects a Window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-A BACKBUFFER will never be sent by core X in a reply, event, or

-error where a Window is specified.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If core X11 backing-store and save-under applies to a double-buffered

-window, it applies to both buffers equally.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If the core ClearArea request is executed on a double-buffered window,

-the same area in both the front and back buffers is cleared.

-    </para>

-  </listitem>

-</itemizedlist>

-

-<para>

-The effect of passing a window to a request that accepts a

-<function>DRAWABLE</function> is

-unchanged by this extension. The window and front buffer are synonomous

-with each other. This includes obeying the <function>GetImage</function>

-semantics and the

-subwindow-mode semantics if a core graphics context is involved. Regardless

-of whether the window was explicitly passed in a

-<function>GetImage</function> request, or

-implicitly referenced (that is, one of the window’s ancestors was passed in the

-request), the front (that is, visible) buffer is always referenced. Thus,

-DBE-naive screen dump clients will always get the front buffer.

-<function>GetImage</function> on

-a back buffer returns undefined image contents for any obscured regions of the

-back buffer that fall within the image.

-</para>

-<para>

-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

-<function>ClipByChildren</function>. If

-an ancestor of a double-buffered window is drawn to with a core 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 <function>IncludeInferiors</function> drawing touched.

-</para>

-

-

-<para>

-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

-BACKBUFFER. If events, replies, or errors that contain a DRAWABLE (for

-example, <function>GraphicsExpose</function>) are generated in response to

-a request, the

-DRAWABLE returned will be the one specified in the request.

-</para>

-<para>

-DBE advertises which visuals support double-buffering.

-</para>

-<para>

-DBE does not include any timing or synchronization facilities. Applications

-that need such facilities (for example, to maintain a constant frame rate)

-should investigate the Synchronization Extension, an X Consortium standard.

-</para>

-

-<sect1 id="window_management_operations">

-<title>Window Management Operations</title>

-

-<para>

-The basic philosophy of DBE is that both buffers are treated the same by core

-X window management operations.

-</para>

-<para>

-When the core <function>DestroyWindow</function> is executed on a

-double-buffered window, both buffers associated with the window are

-destroyed, and all back buffer names associated with the window are freed.

-</para>

-<para>

-If the core <function>ConfigureWindow</function> request changes the size

-of a window, 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 (see the core

-<function>ConfigureWindow</function>

-request), 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,

-<function>Expose</function> events are

-generated for the region that is tiled with the window background.

-If the core GetGeometry request is executed on a BACKBUFFER, the

-returned x, y, and border-width will be zero.

-</para>

-<para>

-If the Shape extension

-<function>ShapeRectangles</function>,

-<function>ShapeMask</function>,

-<function>ShapeCombine</function>, or

-<function>ShapeOffset</function>

-request is executed on a double-buffered window, both buffers

-are reshaped to match the new window shape. The region difference is the

-following:

-</para>

-

-<literallayout remap='Ds'>

-        D = newshape − oldshape

-</literallayout>

-

-<para>

-It is tiled with the window background in both buffers, and

-<function>Expose</function>

-events are generated for D.

-</para>

-

-</sect1>

-

-<sect1 id="complex_swap_actions">

-<title>Complex Swap Actions</title>

-<para>

-DBE has no explicit knowledge of ancillary buffers (for example, 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

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

-</para>

-<para>

-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 protocol requests:

-<function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>.

-Unless this begin-end pair surrounds the idiom, it may not be recognized

-by a given implementation, and performance will suffer.

-</para>

-<para>

-For example, if an application wants to swap buffers for two windows, and use

-core X to clear only certain planes of the back buffers, the application would

-issue the following protocol requests as a group, and in the following order:

-</para>

-

-<itemizedlist>

-  <listitem>

-    <para>

-<function>DBEBeginIdiom</function> request.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>DBESwapBuffers</function> request with XIDs for two windows, each of which uses

-a swap action of Untouched.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Core X <function>PolyFillRectangle</function> request to the back buffer of one window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Core X <function>PolyFillRectangle</function> request to the back buffer of the other

-window.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<function>DBEEndIdiom</function> request.

-    </para>

-  </listitem>

-</itemizedlist>

-

-<para>

-The <function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>

-requests 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 nonrecognized groups/series of requests. If these

-requests are sent out of order, or are mismatched, no errors are sent, and the

-requests are executed as usual, though performance may suffer.

-</para>

-

-<para>

-

-An idiom need not include a <function>DBESwapBuffers</function> request.

-For example, if a swap action of <function>Copied</function> is desired,

-but only some of the planes should be copied, a core X

-<function>CopyArea</function> request may be used instead of

-<function>DBESwapBuffers</function>. If

-<function>DBESwapBuffers</function> is included in an idiom, it should

-immediately follow the

-<function>DBEBeginIdiom</function> request. Also, when the

-<function>DBESwapBuffers</function> 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 <function>Untouched</function>, and if a

-<function>PolyFillRectangle</function> using a client clip

-rectangle is done to the window’s back buffer after the

-<function>DBESwapBuffers</function> request, 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.

-</para>

-<para>

-It is highly recommended that Application Programming Interface (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

-<function>DBEBeginIdiom</function> request, the idiom

-requests, and <function>DBEEndIdiom</function> request. Usage of these

-functions will ensure best possible performance across a wide

-variety of implementations.

-</para>

-

-</sect1>

-</chapter>

-

-<chapter id="c_language_bindings">

-<title>C Language Binding</title>

-<para>

-All identifier The header for this extension is &lt;X11/extensions/Xdbe.h&gt;.

-names provided by this header begin with Xdbe.

-</para>

-

-<sect1 id="types">

-<title>Types</title>

-

-<para>

-The type <function>XdbeBackBuffer</function> is a <function>Drawable</function>.

-</para>

-

-<para>

-The type <function>XdbeSwapAction</function> can be one of the constants

-<function>XdbeUndefined</function>,

-<function>XdbeBackground</function>,

-<function>XdbeUntouched</function>, or

-<function>XdbeCopied</function>.

-</para>

-

-</sect1>

-

-<sect1 id="c_functions">

-<title>C Functions</title>

-<para>

-The C functions provide direct access to the protocol and add no additional

-semantics. For complete details on the effects of these functions, refer to the

-appropriate protocol request, which can be derived by replacing Xdbe at the

-start of the function name with DBE. All functions that have return type

-<function>Status</function> will return nonzero for success and

-zero for failure.

-</para>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XdbeQueryExtension</function></funcdef>

-    <paramdef>Display <parameter> *dpy</parameter></paramdef>

-    <paramdef>int <parameter> *major_version_return</parameter></paramdef>

-    <paramdef>int <parameter> *minor_version_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<para>

-<function>XdbeQueryExtension</function> sets major version return and minor

-version return to the major and minor DBE protocol version supported by

-the server. If the DBE library is compatible with the version returned by

-the server, it returns nonzero. If dpy does not support the DBE extension,

-or if there was an error during communication with the server, or if the

-server and library protocol versions are incompatible, it returns zero.

-No other Xdbe functions may be called before this function. If a client

-violates this rule, the effects of all subsequent Xdbe calls that it makes

-are undefined.

-</para>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XdbeScreenVisualInfo *<function>XdbeGetVisualInfo</function></funcdef>

-    <paramdef>Display <parameter> *dpy</parameter></paramdef>

-    <paramdef>Drawable <parameter> *screen_specifiers</parameter></paramdef>

-    <paramdef>int <parameter> *num_screens</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<para>

-

-<function>XdbeGetVisualInfo</function> returns information about which

-visuals support double buffering. The argument num_screens specifies how

-many elements there are in the screen_specifiers list. Each drawable in

-screen_specifiers designates a screen for which the supported visuals are

-being requested. If num_screens is zero, information for all screens is

-requested. In this case, upon return from this function, num_screens will

-be set to the number of screens that were found. If an error occurs,

-this function returns NULL; otherwise, it returns a pointer to a list of

-<function>XdbeScreenVisualInfo</function>

-structures of length num_screens.  The nth element in the returned list

-corresponds to the nth drawable in the screen_specifiers list, unless

-

-element in the returned list corresponds to the nth screen of the server,

-starting with screen zero.

-</para>

-

-

-<para>

-The XdbeScreenVisualInfo structure has the following fields:

-</para>

-<literallayout remap='Ds'>

-int                     count      number of items in visinfo

-XdbeVisualInfo*    visinfo     list of visuals and depths for this screen

-</literallayout>

-

-<para>

-The <function>XdbeVisualInfo</function> structure has the following fields:

-</para>

-

-<literallayout remap='Ds'>

-VisualID         visual    one visual ID that supports double-buffering

-int              depth     depth of visual in bits

-int              perflevel  performance level of visual

-</literallayout>

-

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>void XdbeFreeVisualInfo <function>XdbeGetVisualInfo</function></funcdef>

-    <paramdef>XdbeScreenVisualInfo <parameter> *visual_info</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<para>

-<function>XdbeFreeVisualInfo</function> frees the list of

-<function>XdbeScreenVisualInfo</function> returned by

-<function>XdbeGetVisualInfo</function>.

-</para>

-

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XdbeBackBuffer <function>XdbeAllocateBackBufferName</function></funcdef>

-    <paramdef>Display <parameter> *dpy</parameter></paramdef>

-    <paramdef>Window <parameter> *window</parameter></paramdef>

-    <paramdef>XdbeSwapAction <parameter> swap_action</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-

-<para>

-<function>XdbeAllocateBackBufferName</function> returns a drawable ID used

-to refer to the back buffer of the specified window. The swap_action is a

-hint to indicate the swap_action that will likely be used in subsequent

-calls to <function>XdbeSwapBuffers</function>.  The actual swap_action

-used in calls to <function>XdbeSwapBuffers</function> does not have to be

-the same as the swap_action passed to this function, though clients are

-encouraged to provide accurate information whenever possible.

-</para>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XdbeDeallocateBackBufferName</function></funcdef>

-    <paramdef>Display <parameter> *dpy</parameter></paramdef>

-    <paramdef>XdbeBackBuffer <parameter> buffer</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<para>

-<function>XdbeDeallocateBackBufferName</function> frees the specified

-drawable ID, buffer, that was obtained via

-<function>XdbeAllocateBackBufferName</function>. The buffer must be a valid

-name for the back buffer of a window, or an

-<function>XdbeBadBuffer</function> error results.

-</para>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XdbeSwapBuffers</function></funcdef>

-    <paramdef>Display <parameter> *dpy</parameter></paramdef>

-    <paramdef>XdbeSwapInfo <parameter> *swap_info</parameter></paramdef>

-    <paramdef>int <parameter> num_windows</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<para>

-<function>XdbeSwapBuffers</function> swaps the front and back buffers

-for a list of windows. The argument num_windows specifies how many windows

-are to have their buffers swapped; it is the number of elements in the

-swap_info array. The argument swap_info specifies the information needed

-per window to do the swap.

-</para>

-<para>

-The XdbeSwapInfo structure has the following fields:

-</para>

-

-<literallayout remap='Ds'>

-Window              swap_window    window for which to swap buffers

-XdbeSwapAction      swap_action    swap action to use for this swap window

-</literallayout>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XdbeBeginIdiom</function></funcdef>

-    <paramdef>Display <parameter> *dpy</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<para>

-<function>XdbeBeginIdiom</function> marks the beginning of an idiom

-sequence. See

-<link linkend="complex_swap_actions">

-<xref linkend="complex_swap_actions"></xref></link>

-for a complete discussion of idioms.

-</para>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XdbeEndIdiom</function></funcdef>

-    <paramdef>Display <parameter> *dpy</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<para>

-<function>XdbeEndIdiom</function> marks the end of an idiom sequence.

-</para>

-

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XdbeBackBufferAttributes *<function>XdbeGetBackBufferAttributes</function></funcdef>

-    <paramdef>Display <parameter> *dpy</parameter></paramdef>

-    <paramdef>XdbeBackBuffer <parameter> buffer</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-

-<para>

-<function>XdbeGetBackBufferAttributes</function> returns the attributes associated with

-the specified buffer.

-</para>

-<para>

-The XdbeBackBufferAttributes structure has the following fields:

-</para>

-

-<literallayout remap='Ds'>

-Window           window           window that buffer belongs to

-</literallayout>

-

-<para>

-If buffer is not a valid <function>XdbeBackBuffer</function>, window is

-set to None.

-</para>

-<para>

-The returned <function>XdbeBackBufferAttributes</function> structure

-can be freed with the Xlib function <function>XFree</function>.

-</para>

-</sect1>

-

-<sect1 id="errors">

-<title>Errors</title>

-<para>

-The <function>XdbeBufferError</function> structure has the following fields:

-</para>

-<literallayout remap='Ds'>

-int                 type

-Display *           display       Display the event was read from

-XdbeBackBuffer      buffer        resource id

-unsigned long       serial        serial number of failed request

-unsigned char       error code    error base + <function>XdbeBadBuffer</function>

-unsigned char       request code  Major op-code of failed request

-unsigned char       minor code    Minor op-code of failed request

-</literallayout>

-</sect1>

-</chapter>

-

-<chapter id="acknowledgements">

-<title>Acknowledgements</title>

-

-<para>

-We wish to thank the following individuals who have contributed their time

-and talent toward shaping the DBE specification:

-</para>

-<para>

-T. Alex Chen, IBM; Peter Daifuku, Silicon Graphics, Inc.; Ian Elliott,

-Hewlett-Packard Company; Stephen Gildea, X Consortium, Inc.; Jim Graham,

-Sun; Larry Hare, AGE Logic; Jay Hersh, X Consortium, Inc.; Daryl Huff,

-Sun; Deron Dann Johnson, Sun; Louis Khouw, Sun; Mark Kilgard, Silicon

-Graphics, Inc.; Rob Lembree, Digital Equipment Corporation; Alan Ricker,

-Metheus; Michael Rosenblum, Digital Equipment Corporation; Bob Scheifler,

-X Consortium, Inc.; Larry Seiler, Digital Equipment Corporation; Jeanne

-Sparlin Smith, IBM; Jeff Stevenson, Hewlett-Packard Company; Walter

-Strand, Metheus; Ken Tidwell, Hewlett-Packard Company; and David P.

-Wiggins, X Consortium, Inc.

-</para>

-<para>

-Mark provided the impetus to start the DBE project. Ian wrote the first draft

-of the specification. David served as architect.

-</para>

-

-</chapter>

-<chapter id="references">

-<title>References</title>

-<para>

-Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension

-Specification Version 3.3."

-</para>

-<para>

-Tim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins, "X

-Synchronization Extension Version 3.0."

-</para>

-</chapter>

-</book>

+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+
+<!-- lifted from troff+ms+XMan by doclifter -->
+<book id="dbelib">
+
+<bookinfo>
+   <title>Double Buffer Extension Library</title>
+   <subtitle>X Consortium Standard</subtitle>
+   <!-- <releaseinfo>X Version 11, Release 6.4</releaseinfo> -->
+   <authorgroup>
+      <author>
+         <firstname>Ian</firstname><surname>Elliot</surname>
+      </author>
+   </authorgroup>
+   <othercredit>
+      <firstname>Davide</firstname><surname>Wiggins</surname>
+   </othercredit>
+   <corpname>Hewlett-Packard Company</corpname>
+   <copyright><year>1989</year><holder>X Consortium, Inc and Digital Equipment Corporation</holder></copyright>
+   <copyright><year>1992</year><holder>X Consortium, Inc and Intergraph Corporation</holder></copyright>
+   <copyright><year>1993</year><holder>X Consortium, Inc and Silicon Graphics, Inc.</holder></copyright>
+   <copyright><year>1994</year><holder>X Consortium, Inc and Hewlett-Packard Company</holder></copyright>
+   <copyright><year>1995</year><holder>X Consortium, Inc and Hewlett-Packard Company</holder></copyright>
+   <releaseinfo>Version 1.0</releaseinfo>
+   <affiliation><orgname>X Consortium</orgname></affiliation>
+   <productnumber>X Version 11, Release 7</productnumber>
+
+<legalnotice>
+<para>
+Permission to use, copy, modify, and distribute this documentation for any
+purpose and without fee is hereby granted, provided that the above copyright
+notice and this permission notice appear in all copies. Digital Equipment
+Corporation, Intergraph Corporation, Silicon Graphics, Hewlett-Packard, and
+the X Consortium make no representations about the suitability for any
+purpose of the information in this document. This documentation is provided
+"as is" without express or implied warranty.
+</para>
+
+</legalnotice>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+<para>
+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 and with no
+visual artifacts. Thus, only completely rendered images are presented to the
+user, and they remain visible during the entire time it takes to render a new
+frame. The result is a flicker-free animation.
+</para>
+
+</chapter>
+
+<chapter id="goals">
+<title>Goals</title>
+
+<para>
+This extension should enable clients to:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Allocate and deallocate double-buffering for a window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Draw to and read from the front and back buffers associated with a window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Swap the front and back buffers associated with a window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Specify a wide range of actions to be taken when a window is swapped.
+This includes explicit, simple swap actions (defined below), and more
+complex actions (for example, clearing ancillary buffers) that can be put
+together within explicit "begin" and "end" requests (defined below).
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Request that the front and back buffers associated with multiple
+double-buffered windows be swapped simultaneously.
+    </para>
+  </listitem>
+</itemizedlist>
+
+<para>
+In addition, the extension should:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Allow multiple clients to use double-buffering on the same window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Support a range of implementation methods that can capitalize on
+existing hardware features.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Add no new event types.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Be reasonably easy to integrate with a variety of direct graphics
+hardware access (DGHA) architectures.
+    </para>
+  </listitem>
+</itemizedlist>
+
+</chapter>
+
+<chapter id="concepts">
+<title>Concepts</title>
+<para>
+Normal windows are created using the core CreateWindow request, which
+allocates 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.
+</para>
+<para>
+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 (that is, drawing to or reading from) the window’s back buffer. The back
+buffer name is a DRAWABLE of type BACKBUFFER.
+</para>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+<para>
+In general, both the front and back buffers are treated the same.
+particular, here are some important characteristics:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Only one buffer per window can be visible at a time (the front buffer).
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Both buffers associated with a window have the same visual type, depth,
+width, height, and shape as the window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Both buffers associated with a window are "visible" (or "obscured") in
+the same way. When an Expose event is generated for a window, both
+buffers should be considered to be damaged in the exposed area.
+Damage that occurs to either buffer will result in an Expose event on
+the window. When a double-buffered window is exposed, both buffers
+are tiled with the window background, exactly as stated by the core
+protocol. Even though the back buffer is not visible, terms such as
+obscure apply to the back buffer as well as to the front buffer.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+It is acceptable at any time to pass a BACKBUFFER in any request,
+notably any core or extension drawing request, that expects a
+DRAWABLE.  This enables an application to draw directly into
+BACKBUFFERs in the same fashion as it would draw into any other
+DRAWABLE.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+It is an error (Window) to pass a BACKBUFFER in a core request that
+expects a Window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A BACKBUFFER will never be sent by core X in a reply, event, or
+error where a Window is specified.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If core X11 backing-store and save-under applies to a double-buffered
+window, it applies to both buffers equally.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If the core ClearArea request is executed on a double-buffered window,
+the same area in both the front and back buffers is cleared.
+    </para>
+  </listitem>
+</itemizedlist>
+
+<para>
+The effect of passing a window to a request that accepts a
+<function>DRAWABLE</function> is
+unchanged by this extension. The window and front buffer are synonomous
+with each other. This includes obeying the <function>GetImage</function>
+semantics and the
+subwindow-mode semantics if a core graphics context is involved. Regardless
+of whether the window was explicitly passed in a
+<function>GetImage</function> request, or
+implicitly referenced (that is, one of the window’s ancestors was passed in the
+request), the front (that is, visible) buffer is always referenced. Thus,
+DBE-naive screen dump clients will always get the front buffer.
+<function>GetImage</function> on
+a back buffer returns undefined image contents for any obscured regions of the
+back buffer that fall within the image.
+</para>
+<para>
+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
+<function>ClipByChildren</function>. If
+an ancestor of a double-buffered window is drawn to with a core 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 <function>IncludeInferiors</function> drawing touched.
+</para>
+
+
+<para>
+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
+BACKBUFFER. If events, replies, or errors that contain a DRAWABLE (for
+example, <function>GraphicsExpose</function>) are generated in response to
+a request, the
+DRAWABLE returned will be the one specified in the request.
+</para>
+<para>
+DBE advertises which visuals support double-buffering.
+</para>
+<para>
+DBE does not include any timing or synchronization facilities. Applications
+that need such facilities (for example, to maintain a constant frame rate)
+should investigate the Synchronization Extension, an X Consortium standard.
+</para>
+
+<sect1 id="window_management_operations">
+<title>Window Management Operations</title>
+
+<para>
+The basic philosophy of DBE is that both buffers are treated the same by core
+X window management operations.
+</para>
+<para>
+When the core <function>DestroyWindow</function> is executed on a
+double-buffered window, both buffers associated with the window are
+destroyed, and all back buffer names associated with the window are freed.
+</para>
+<para>
+If the core <function>ConfigureWindow</function> request changes the size
+of a window, 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 (see the core
+<function>ConfigureWindow</function>
+request), 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,
+<function>Expose</function> events are
+generated for the region that is tiled with the window background.
+If the core GetGeometry request is executed on a BACKBUFFER, the
+returned x, y, and border-width will be zero.
+</para>
+<para>
+If the Shape extension
+<function>ShapeRectangles</function>,
+<function>ShapeMask</function>,
+<function>ShapeCombine</function>, or
+<function>ShapeOffset</function>
+request is executed on a double-buffered window, both buffers
+are reshaped to match the new window shape. The region difference is the
+following:
+</para>
+
+<literallayout remap='Ds'>
+        D = newshape − oldshape
+</literallayout>
+
+<para>
+It is tiled with the window background in both buffers, and
+<function>Expose</function>
+events are generated for D.
+</para>
+
+</sect1>
+
+<sect1 id="complex_swap_actions">
+<title>Complex Swap Actions</title>
+<para>
+DBE has no explicit knowledge of ancillary buffers (for example, 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
+application’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.
+</para>
+<para>
+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 protocol requests:
+<function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>.
+Unless this begin-end pair surrounds the idiom, it may not be recognized
+by a given implementation, and performance will suffer.
+</para>
+<para>
+For example, if an application wants to swap buffers for two windows, and use
+core X to clear only certain planes of the back buffers, the application would
+issue the following protocol requests as a group, and in the following order:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+<function>DBEBeginIdiom</function> request.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>DBESwapBuffers</function> request with XIDs for two windows, each of which uses
+a swap action of Untouched.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Core X <function>PolyFillRectangle</function> request to the back buffer of one window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Core X <function>PolyFillRectangle</function> request to the back buffer of the other
+window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>DBEEndIdiom</function> request.
+    </para>
+  </listitem>
+</itemizedlist>
+
+<para>
+The <function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>
+requests 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 nonrecognized groups/series of requests. If these
+requests are sent out of order, or are mismatched, no errors are sent, and the
+requests are executed as usual, though performance may suffer.
+</para>
+
+<para>
+
+An idiom need not include a <function>DBESwapBuffers</function> request.
+For example, if a swap action of <function>Copied</function> is desired,
+but only some of the planes should be copied, a core X
+<function>CopyArea</function> request may be used instead of
+<function>DBESwapBuffers</function>. If
+<function>DBESwapBuffers</function> is included in an idiom, it should
+immediately follow the
+<function>DBEBeginIdiom</function> request. Also, when the
+<function>DBESwapBuffers</function> 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 <function>Untouched</function>, and if a
+<function>PolyFillRectangle</function> using a client clip
+rectangle is done to the window’s back buffer after the
+<function>DBESwapBuffers</function> request, 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.
+</para>
+<para>
+It is highly recommended that Application Programming Interface (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
+<function>DBEBeginIdiom</function> request, the idiom
+requests, and <function>DBEEndIdiom</function> request. Usage of these
+functions will ensure best possible performance across a wide
+variety of implementations.
+</para>
+
+</sect1>
+</chapter>
+
+<chapter id="c_language_bindings">
+<title>C Language Binding</title>
+<para>
+All identifier The header for this extension is &lt;X11/extensions/Xdbe.h&gt;.
+names provided by this header begin with Xdbe.
+</para>
+
+<sect1 id="types">
+<title>Types</title>
+
+<para>
+The type <function>XdbeBackBuffer</function> is a <function>Drawable</function>.
+</para>
+
+<para>
+The type <function>XdbeSwapAction</function> can be one of the constants
+<function>XdbeUndefined</function>,
+<function>XdbeBackground</function>,
+<function>XdbeUntouched</function>, or
+<function>XdbeCopied</function>.
+</para>
+
+</sect1>
+
+<sect1 id="c_functions">
+<title>C Functions</title>
+<para>
+The C functions provide direct access to the protocol and add no additional
+semantics. For complete details on the effects of these functions, refer to the
+appropriate protocol request, which can be derived by replacing Xdbe at the
+start of the function name with DBE. All functions that have return type
+<function>Status</function> will return nonzero for success and
+zero for failure.
+</para>
+
+<funcsynopsis id='xdbequeryextension'>
+<funcprototype>
+  <funcdef>Status <function>XdbeQueryExtension</function></funcdef>
+    <paramdef>Display <parameter> *dpy</parameter></paramdef>
+    <paramdef>int <parameter> *major_version_return</parameter></paramdef>
+    <paramdef>int <parameter> *minor_version_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<function>XdbeQueryExtension</function> sets major version return and minor
+version return to the major and minor DBE protocol version supported by
+the server. If the DBE library is compatible with the version returned by
+the server, it returns nonzero. If dpy does not support the DBE extension,
+or if there was an error during communication with the server, or if the
+server and library protocol versions are incompatible, it returns zero.
+No other Xdbe functions may be called before this function. If a client
+violates this rule, the effects of all subsequent Xdbe calls that it makes
+are undefined.
+</para>
+
+<funcsynopsis id='xdbegetvisualinfo'>
+<funcprototype>
+  <funcdef>XdbeScreenVisualInfo *<function>XdbeGetVisualInfo</function></funcdef>
+    <paramdef>Display <parameter> *dpy</parameter></paramdef>
+    <paramdef>Drawable <parameter> *screen_specifiers</parameter></paramdef>
+    <paramdef>int <parameter> *num_screens</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+
+<function>XdbeGetVisualInfo</function> returns information about which
+visuals support double buffering. The argument num_screens specifies how
+many elements there are in the screen_specifiers list. Each drawable in
+screen_specifiers designates a screen for which the supported visuals are
+being requested. If num_screens is zero, information for all screens is
+requested. In this case, upon return from this function, num_screens will
+be set to the number of screens that were found. If an error occurs,
+this function returns NULL; otherwise, it returns a pointer to a list of
+<function>XdbeScreenVisualInfo</function>
+structures of length num_screens.  The nth element in the returned list
+corresponds to the nth drawable in the screen_specifiers list, unless
+
+element in the returned list corresponds to the nth screen of the server,
+starting with screen zero.
+</para>
+
+
+<para>
+The XdbeScreenVisualInfo structure has the following fields:
+</para>
+<literallayout remap='Ds'>
+int                     count      number of items in visinfo
+XdbeVisualInfo*    visinfo     list of visuals and depths for this screen
+</literallayout>
+
+<para>
+The <function>XdbeVisualInfo</function> structure has the following fields:
+</para>
+
+<literallayout remap='Ds'>
+VisualID         visual    one visual ID that supports double-buffering
+int              depth     depth of visual in bits
+int              perflevel  performance level of visual
+</literallayout>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void XdbeFreeVisualInfo <function>XdbeGetVisualInfo</function></funcdef>
+    <paramdef>XdbeScreenVisualInfo <parameter> *visual_info</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<function>XdbeFreeVisualInfo</function> frees the list of
+<function>XdbeScreenVisualInfo</function> returned by
+<function>XdbeGetVisualInfo</function>.
+</para>
+
+
+<funcsynopsis id='xdbeallocatebackbuffername'>
+<funcprototype>
+  <funcdef>XdbeBackBuffer <function>XdbeAllocateBackBufferName</function></funcdef>
+    <paramdef>Display <parameter> *dpy</parameter></paramdef>
+    <paramdef>Window <parameter> *window</parameter></paramdef>
+    <paramdef>XdbeSwapAction <parameter> swap_action</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<para>
+<function>XdbeAllocateBackBufferName</function> returns a drawable ID used
+to refer to the back buffer of the specified window. The swap_action is a
+hint to indicate the swap_action that will likely be used in subsequent
+calls to <function>XdbeSwapBuffers</function>.  The actual swap_action
+used in calls to <function>XdbeSwapBuffers</function> does not have to be
+the same as the swap_action passed to this function, though clients are
+encouraged to provide accurate information whenever possible.
+</para>
+
+<funcsynopsis id='xdbedeallocatebackbuffername'>
+<funcprototype>
+  <funcdef>Status <function>XdbeDeallocateBackBufferName</function></funcdef>
+    <paramdef>Display <parameter> *dpy</parameter></paramdef>
+    <paramdef>XdbeBackBuffer <parameter> buffer</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<function>XdbeDeallocateBackBufferName</function> frees the specified
+drawable ID, buffer, that was obtained via
+<function>XdbeAllocateBackBufferName</function>. The buffer must be a valid
+name for the back buffer of a window, or an
+<function>XdbeBadBuffer</function> error results.
+</para>
+
+<funcsynopsis id='xdbeswapbuffers'>
+<funcprototype>
+  <funcdef>Status <function>XdbeSwapBuffers</function></funcdef>
+    <paramdef>Display <parameter> *dpy</parameter></paramdef>
+    <paramdef>XdbeSwapInfo <parameter> *swap_info</parameter></paramdef>
+    <paramdef>int <parameter> num_windows</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<function>XdbeSwapBuffers</function> swaps the front and back buffers
+for a list of windows. The argument num_windows specifies how many windows
+are to have their buffers swapped; it is the number of elements in the
+swap_info array. The argument swap_info specifies the information needed
+per window to do the swap.
+</para>
+<para>
+The XdbeSwapInfo structure has the following fields:
+</para>
+
+<literallayout remap='Ds'>
+Window              swap_window    window for which to swap buffers
+XdbeSwapAction      swap_action    swap action to use for this swap window
+</literallayout>
+
+<funcsynopsis id='xdbebeginidiom'>
+<funcprototype>
+  <funcdef>Status <function>XdbeBeginIdiom</function></funcdef>
+    <paramdef>Display <parameter> *dpy</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<function>XdbeBeginIdiom</function> marks the beginning of an idiom
+sequence. See
+<link linkend="complex_swap_actions">
+<xref linkend="complex_swap_actions"></xref></link>
+for a complete discussion of idioms.
+</para>
+
+<funcsynopsis id='xdbeendidiom'>
+<funcprototype>
+  <funcdef>Status <function>XdbeEndIdiom</function></funcdef>
+    <paramdef>Display <parameter> *dpy</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<function>XdbeEndIdiom</function> marks the end of an idiom sequence.
+</para>
+
+<funcsynopsis id='xdbegetbackbufferattributes'>
+<funcprototype>
+  <funcdef>XdbeBackBufferAttributes *<function>XdbeGetBackBufferAttributes</function></funcdef>
+    <paramdef>Display <parameter> *dpy</parameter></paramdef>
+    <paramdef>XdbeBackBuffer <parameter> buffer</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<function>XdbeGetBackBufferAttributes</function> returns the attributes associated with
+the specified buffer.
+</para>
+<para>
+The XdbeBackBufferAttributes structure has the following fields:
+</para>
+
+<literallayout remap='Ds'>
+Window           window           window that buffer belongs to
+</literallayout>
+
+<para>
+If buffer is not a valid <function>XdbeBackBuffer</function>, window is
+set to None.
+</para>
+<para>
+The returned <function>XdbeBackBufferAttributes</function> structure
+can be freed with the Xlib function <function>XFree</function>.
+</para>
+</sect1>
+
+<sect1 id="errors">
+<title>Errors</title>
+<para>
+The <function>XdbeBufferError</function> structure has the following fields:
+</para>
+<literallayout remap='Ds'>
+int                 type
+Display *           display       Display the event was read from
+XdbeBackBuffer      buffer        resource id
+unsigned long       serial        serial number of failed request
+unsigned char       error code    error base + <function>XdbeBadBuffer</function>
+unsigned char       request code  Major op-code of failed request
+unsigned char       minor code    Minor op-code of failed request
+</literallayout>
+</sect1>
+</chapter>
+
+<chapter id="acknowledgements">
+<title>Acknowledgements</title>
+
+<para>
+We wish to thank the following individuals who have contributed their time
+and talent toward shaping the DBE specification:
+</para>
+<para>
+T. Alex Chen, IBM; Peter Daifuku, Silicon Graphics, Inc.; Ian Elliott,
+Hewlett-Packard Company; Stephen Gildea, X Consortium, Inc.; Jim Graham,
+Sun; Larry Hare, AGE Logic; Jay Hersh, X Consortium, Inc.; Daryl Huff,
+Sun; Deron Dann Johnson, Sun; Louis Khouw, Sun; Mark Kilgard, Silicon
+Graphics, Inc.; Rob Lembree, Digital Equipment Corporation; Alan Ricker,
+Metheus; Michael Rosenblum, Digital Equipment Corporation; Bob Scheifler,
+X Consortium, Inc.; Larry Seiler, Digital Equipment Corporation; Jeanne
+Sparlin Smith, IBM; Jeff Stevenson, Hewlett-Packard Company; Walter
+Strand, Metheus; Ken Tidwell, Hewlett-Packard Company; and David P.
+Wiggins, X Consortium, Inc.
+</para>
+<para>
+Mark provided the impetus to start the DBE project. Ian wrote the first draft
+of the specification. David served as architect.
+</para>
+
+</chapter>
+<chapter id="references">
+<title>References</title>
+<para>
+Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension
+Specification Version 3.3."
+</para>
+<para>
+Tim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins, "X
+Synchronization Extension Version 3.0."
+</para>
+</chapter>
+</book>