specs: convert protocol .ms specs from xorg-docs module to DocBook XML

Signed-off-by: Gaetan Nadon <memsize@videotron.ca>

1 files changed, 1061 insertions, 0 deletions

diff --git a/specs/dbe.xml b/specs/dbe.xml
new file mode 100644
index 0000000..ce7a327
--- /dev/null
+++ b/specs/dbe.xml
@@ -0,0 +1,1061 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+
+<!--
+by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)
+xhtml,docbook,html,refcaption -->
+
+<book id="dbe">
+
+<bookinfo>
+  <title>Double Buffer Extension Protocol</title>
+  <subtitle>X Consortium Standard</subtitle>
+  <releaseinfo>X Version 11, Release 6.4</releaseinfo>
+  <authorgroup>
+   <author>
+     <firstname>Ian</firstname><surname>Elliott</surname>
+   </author>
+  </authorgroup>
+  <othercredit>
+   <firstname>David</firstname><surname>Wiggins</surname>
+   <affiliation><orgname>X Consortium</orgname></affiliation>
+  </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>
+  <releaseinfo>Version 1.0</releaseinfo>
+
+<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 <function>CreateWindow</function>
+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. In
+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 <function>ClearArea</function> 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 DRAWABLE 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 windo'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 <function>IncludeInferiors</function>, 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 windo'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 windo'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.
+</para>
+
+<para>
+If the core <function>GetGeometry</function> 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>
+   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>DBEBeginIdiom 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 PolyFillRectangle request to the back buffer of one window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Core X PolyFillRectangle request to the back buffer of the other window.
+    </para>
+  </listitem>
+  <listitem>
+    <para>DBEEndIdiom 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 Copied 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 Untouched, and if a <function>PolyFillRectangle</function>
+using a client clip rectangle is done to the windo'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="requests">
+<title>Requests</title>
+<para>The DBE defines the following requests.</para>
+
+<sect1 id="dbegetversion">
+<title>DBEGetVersion</title>
+<para>
+This request returns the major and minor version numbers of this extension.
+</para>
+
+<para>DBEGetVersion</para>
+<informaltable>
+  <tgroup cols="2">
+    <colspec colname="c1"/>
+    <colspec colname="c2" />
+    <tbody>
+      <row>
+        <entry align="left">client-major-version</entry>
+        <entry align="left">CARD8</entry>
+      </row>
+      <row>
+        <entry align="left">client-minor-version </entry>
+        <entry align="left">CARD8</entry>
+      </row>
+      <row>
+        <entry align="left">=></entry>
+        <entry align="left"></entry>
+      </row>
+      <row>
+        <entry align="left">server-major-version </entry>
+        <entry align="left">CARD8</entry>
+      </row>
+      <row>
+        <entry align="left">server-minor-version </entry>
+        <entry align="left">CARD8</entry>
+      </row>
+    </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+The client-major-version and client-minor-version numbers indicate what
+version of the protocol the client wants the server to implement. The
+server-major-version and the server-minor-version numbers returned indicate
+the protocol this extension actually supports. This might not equal the
+version sent by the client. An implementation can (but need not) support
+more than one version simultaneously.  The server-major-version and
+server-minor-version allow the creation of future revisions of the DBE
+protocol that may be necessary. In general, the major version
+would increment for incompatible changes, and the minor version would increment
+for small, upward-compatible changes. Servers that support the protocol
+defined in this document will return a server-major-version of one (1), and a
+server-minor-version of zero (0).
+</para>
+
+<para>
+The DBE client must issue a DBEGetVersion request before any other double
+buffering request in order to negotiate a compatible protocol version;
+otherwise, the client will get undefined behavior (DBE may or may not work).
+</para>
+
+</sect1>
+
+<sect1 id="dbegetvisualinfo">
+<title>DBEGetVisualInfo</title>
+<para>
+This request returns information about which visuals support double buffering.
+</para>
+
+<para>DBEGetVisualInfo</para>
+
+<informaltable>
+  <tgroup cols="2">
+    <colspec colname="c1"/>
+    <colspec colname="c2"/>
+    <tbody>
+      <row>
+        <entry align="left">screen-specifiers</entry>
+        <entry align="left">LISTofDRAWABLE</entry>
+      </row>
+      <row>
+        <entry align="left">=></entry>
+        <entry align="left"></entry>
+      </row>
+      <row>
+        <entry align="left">visinfo</entry>
+        <entry align="left">LISTofSCREENVISINFO</entry>
+      </row>
+    </tbody>
+  </tgroup>
+</informaltable>
+<para>where:</para>
+
+<informaltable>
+  <tgroup cols="2">
+    <colspec colname="c1"/>
+    <colspec colname="c2"/>
+    <tbody>
+      <row>
+        <entry align="left">SCREENVISINFO</entry>
+        <entry align="left">LISTofVISINFO</entry>
+      </row>
+      <row>
+        <entry align="left">VISINFO</entry>
+        <entry align="left">[ visual: VISUALID</entry>
+      </row>
+      <row>
+        <entry align="left"></entry>
+        <entry align="left">depth: CARD8</entry>
+      </row>
+      <row>
+        <entry align="left"></entry>
+        <entry align="left">perflevel: CARD8 ]</entry>
+      </row>
+    </tbody>
+  </tgroup>
+</informaltable>
+
+<para>Errors: Drawable</para>
+
+<para>
+All of the values passed in screen-specifiers must be valid DRAWABLEs (or a
+<function>Drawable</function> error results). For each drawable in
+screen-specifiers, the reply will contain a list of VISINFO structures for
+visuals that support double-buffering on the screen on which the drawable
+resides. The visual member specifies the VISUALID. The depth member specifies
+the depth in bits for the visual. The perflevel is a performance hint. The
+only operation defined on a perflevel is comparison to a perflevel of another
+visual on the same screen. The visual having the higher perflevel is likely
+to have better double-buffer graphics performance than the visual having the
+lower perflevel. Nothing can be deduced from any of the following: the
+magnitude of the difference of two perflevels, a perflevel value in isolation,
+or comparing perflevels from different servers.
+</para>
+
+<para>
+If the list of screen-specifiers is empty, information for all screens is
+returned, starting with screen zero.
+</para>
+
+</sect1>
+
+<sect1 id="dbeallocatebackbuffername">
+<title>DBEAllocateBackBufferName</title>
+
+<para>
+This request allocates a drawable ID used to refer to the back buffer of a
+window.
+</para>
+
+<para>DBEAllocateBackBufferName</para>
+
+<informaltable>
+  <tgroup cols="2">
+    <colspec colname="c1"/>
+    <colspec colname="c2"/>
+    <tbody>
+      <row>
+        <entry align="left">window</entry>
+        <entry align="left">WINDOW</entry>
+      </row>
+      <row>
+        <entry align="left">back-buffer-name</entry>
+        <entry align="left">BACKBUFFER</entry>
+      </row>
+      <row>
+        <entry align="left">swap-action-hint</entry>
+        <entry align="left">SWAPACTION </entry>
+      </row>
+    </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+Errors: Alloc, Value, IDChoice, Match, Window
+</para>
+
+<para>
+If the window is not already a double-buffered window, the window becomes
+double-buffered, and the back-buffer-name is associated with the window. The
+swap-action-hint tells the server which swap action is most likely to be
+used with the window in subsequent <function>DBESwapBuffers</function>
+requests. The swap-action-hint must have one of the values specified for type
+SWAPACTION (or a Value error results). See the description of the
+<function>DBESwapBuffers</function> request for a complete discussion of
+swap actions and the SWAPACTION type.
+</para>
+
+<para>
+If the window already is a double-buffered window, nothing about the window
+changes, except that an additional 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>
+The window passed into the request must be a valid WINDOW (or a Window error
+results). The window passed into the request must be an InputOutput window (or
+a Match error results). The visual of the window must be in the list returned
+by <function>DBEGetVisualInfo</function> (or a Match error results). The
+back-buffer-name must be in the range assigned to the client, and must not
+already be in use (or an IDChoice error results). If the server cannot
+allocate all resources associated with turning on double-buffering for the
+window, an Alloc error results, the windo's double-buffer status (whether it
+is already double-buffered or not) remains unchanged, and the
+back-buffer-name is freed.
+</para>
+</sect1>
+
+<sect1 id="dbedeallocatebackbuffername">
+<title>DBEDeallocateBackBufferName</title>
+<para>
+This request frees a drawable ID that was obtained by
+<function>DBEAllocateBackBufferName</function>.
+</para>
+
+<para>DBEDeallocateBackBufferName</para>
+
+<informaltable>
+  <tgroup cols="2">
+  <colspec colname="c1"/>
+  <colspec colname="c2"/>
+  <tbody>
+    <row>
+      <entry align="left">back-buffer-name</entry>
+      <entry align="left">BACKBUFFER</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>Errors: Buffer</para>
+
+<para>
+The back-buffer-name passed in the request is freed and no longer associated
+with the window. If this is the last back-buffer-name associated with the
+window, then the back buffer is no longer accessible to clients, and all
+double-buffering resources associated with the window may be freed. The
+window's current front buffer remains the front buffer.
+</para>
+
+<para>
+The back-buffer-name must be a valid BACKBUFFER associated with a window (or
+a Buffer error results).
+</para>
+</sect1>
+
+<sect1 id="dbeswapbuffers">
+<title>DBESwapBuffers</title>
+<para>
+This request swaps the buffers for all windows listed, applying the
+appropriate swap action for each window.
+</para>
+
+<para><function>DBESwapBuffers</function></para>
+
+<informaltable>
+  <tgroup cols="2">
+  <colspec colname="c1" /><colspec colname="c2"/>
+  <tbody>
+    <row>
+      <entry align="left">windows</entry>
+      <entry align="left">LISTofSWAPINFO</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+<para>where:</para>
+<informaltable>
+  <tgroup cols="2">
+  <colspec colname="c1" /><colspec colname="c2"/>
+  <tbody>
+    <row>
+      <entry align="left">SWAPINFO</entry>
+      <entry align="left">[ window: WINDOW</entry>
+    </row>
+    <row>
+      <entry align="left"></entry>
+      <entry align="left">swap-action: SWAPACTION ]</entry>
+    </row>
+    <row>
+      <entry align="left">SWAPACTION</entry>
+      <entry align="left">{ Undefined, Background, Untouched, Copied }</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>Errors: Match, Window, Value</para>
+
+<para>
+Each window passed into the request must be a valid WINDOW (or a
+<function>Window</function> error results). Each window passed into the
+request must be a double-buffered window (or a <function>Match</function>
+error results). Each window passed into the request must only be listed
+once (or a <function>Match</function> error results). Each swap-action in
+the list must have one of the values specified for type SWAPACTION (or a
+<function>Value</function> error results). If an error results, none of
+the valid double-buffered windows will have their buffers swapped.
+</para>
+
+<para>
+The swap-action determines what will happen to the new back buffer of the
+window it is paired with in the list in addition to making the old back
+buffer become visible.  The defined actions are as follows:
+</para>
+
+<variablelist>
+  <varlistentry>
+    <term>Undefined</term>
+      <listitem><para>
+The contents of the new back buffer become undefined. This may be the
+most efficient action since it allows the implementation to discard the
+contents of the buffer if it needs to.
+      </para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Background</term>
+    <listitem><para>
+The unobscured region of the new back buffer will be tiled with the window
+background. The background action allows devices to use a fast clear
+capability during a swap.
+    </para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Untouched</term>
+    <listitem><para>
+The unobscured region of the new back buffer will be unmodified by the swap.
+    </para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Copied</term>
+    <listitem><para>
+The unobscured region of the new back buffer will be the contents of the
+old back buffer.
+    </para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+If <function>DBESwapBuffers</function> is included in a "swap and clear"
+type of idiom, it must immediately follow the
+<function>DBEBeginIdiom</function> request.
+</para>
+</sect1>
+
+<sect1 id="dbebeginidiom">
+<title>DBEBeginIdiom</title>
+<para>
+This request informs the server that a complex swap will immediately follow
+this request.
+</para>
+
+<para><function>DBEBeginIdiom</function></para>
+
+<para>
+As previously discussed, a complex swap action is a group/series of
+requests that, taken together, may be combined into an atomic operation by
+the implementation.  The sole function of this request is to serve as a
+"marker" that the server can use to aid in idiom processing. The server is
+free to implement this request as a no-op.
+</para>
+</sect1>
+
+<sect1 id="dbeendidiom">
+<title>DBEEndIdiom</title>
+
+
+<para>
+This request informs the server that a complex swap has concluded.
+</para>
+
+<para><function>DBEEndIdiom</function></para>
+
+<para>
+The sole function of this request is to serve as a "marker" that the server
+can use to aid in idiom processing. The server is free to implement this
+request as a no-op.
+</para>
+
+</sect1>
+
+<sect1 id="dbegetbackbufferattributes">
+<title>DBEGetBackBufferAttributes</title>
+
+<para>This request returns information about a back buffer.</para>
+
+<para><function>DBEGetBackBufferAttributes</function></para>
+
+<informaltable>
+  <tgroup cols="2">
+  <colspec colname="c1"/>
+  <colspec colname="c2"/>
+  <tbody>
+    <row>
+      <entry align="left">back-buffer-name</entry>
+      <entry align="left">BACKBUFFER</entry>
+    </row>
+    <row>
+      <entry align="left">=></entry>
+      <entry align="left"></entry>
+    </row>
+    <row>
+      <entry align="left">attributes</entry>
+      <entry align="left">BUFFER_ATTRIBUTES</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>where:</para>
+
+<para>BUFFER_ATTRIBUTES: [ window: WINDOW ]</para>
+
+<para>
+If back-buffer-name is a valid BACKBUFFER, the window field of the
+attributes in the reply will be the window which has the back buffer that
+back-buffer-name refers to. If back-buffer-name is not a valid BACKBUFFER,
+the window field of the attributes in the reply will be None.
+</para>
+
+</sect1>
+</chapter>
+
+<chapter id="encoding">
+<title>Encoding</title>
+<para>
+Please refer to the X11 Protocol Encoding document as this section uses
+syntactic conventions and data types established there.
+</para>
+
+<para>The name of this extension is "DOUBLE-BUFFER".</para>
+
+<sect1 id="type">
+<title>Type</title>
+<para>The following new types are used by the extension.
+</para>
+
+<para>BACKBUFFER: XID</para>
+<para>SWAPACTION</para>
+<literallayout class="monospaced">
+#x00  Undefined
+#x01  Background
+#x02  Untouched
+#x03  Copied
+</literallayout>
+
+<para>SWAPINFO</para>
+<literallayout class="monospaced">
+4     WINDOW                 window
+1     SWAPACTION             swap action
+3                            unused
+</literallayout>
+
+<literallayout class="monospaced">
+VISINFO
+4     VISUALID                visual
+1     CARD8                   depth
+1     CARD8                   perflevel
+2                             unused
+
+SCREENVISINFO
+4     CARD32                  n, number in list
+8n    LISTofVISINFO           n VISINFOs
+
+BUFFER_ATTRIBUTES
+4     WINDOW                 window
+</literallayout>
+</sect1>
+
+<sect1 id="error">
+<title>Error</title>
+<para><function>Buffer</function></para>
+<literallayout class="monospaced">
+1     0                       error
+1     error base + 0          code
+2     CARD16                  sequence number
+4     CARD32                  bad buffer
+2     CARD16                  minor-opcode
+1     CARD8                   major-opcode
+21                            unused
+</literallayout>
+</sect1>
+
+<sect1 id="request">
+<title>Request</title>
+
+<literallayout class="monospaced">
+DBEGetVersion
+1     CARD8                  major-opcode
+1     0                      minor-opcode
+2     2                      request length
+1     CARD8                  client-major-version
+1     CARD8                  client-minor-version
+2                            unused
+=>
+1                            unused
+2     CARD16                 sequence number
+4     0                      reply length
+1     CARD8                  server-major-version
+1     CARD8                  server-minor-version
+22                           unused
+</literallayout>
+
+<para><function>DBEAllocateBackBufferName</function></para>
+<literallayout class="monospaced">
+1     CARD8                  major-opcode
+1     1                      minor-opcode
+2     4                      request length
+4     WINDOW                 window
+4     BACKBUFFER             back buffer name
+1     SWAPACTION             swap action hint
+3                            unused
+</literallayout>
+
+<para><function>DBEDeallocateBackBufferName</function></para>
+<literallayout class="monospaced">
+1     CARD8                  major-opcode
+1     2                      minor-opcode
+2     2                      request length
+4     BACKBUFFER             back buffer name
+</literallayout>
+
+
+<para><function>DBESwapBuffers</function></para>
+<literallayout class="monospaced">
+1     CARD8                   major-opcode
+1     3                       minor-opcode
+2     2+2n                    request length
+4     CARD32                  n, number of window/swap action pairs in list
+8n    LISTofSWAPINFO          window/swap action pairs
+</literallayout>
+
+
+<para><function>DBEBeginIdiom</function></para>
+<literallayout class="monospaced">
+1     CARD8                   major-opcode
+1     4                       minor-opcode
+2     1                       request length
+</literallayout>
+
+<para><function>DBEEndIdiom</function></para>
+<literallayout class="monospaced">
+1     CARD8                   major-opcode
+1     5                       minor-opcode
+2     1                       request length
+</literallayout>
+
+<para><function>DBEGetVisualInfo</function></para>
+<literallayout class="monospaced">
+1     CARD8                   major-opcode
+1     6                       minor-opcode
+2     2+n                     request length
+4     CARD32                  n, number of screen specifiers in list
+4n    LISTofDRAWABLE          n screen specifiers
+=>
+1     1                       Reply
+1                             unused
+2     CARD16                  sequence number
+4     CARD32                  reply length
+4     CARD32                  m, number of SCREENVISINFOs in list
+20                            unused
+4j    LISTofSCREENVISINFO     m SCREENVISINFOs
+</literallayout>
+
+<para><function>DBEGetBackBufferAttributes</function></para>
+<literallayout class="monospaced">
+1     CARD8                   major-opcode
+1     7                       minor-opcode
+2     2                       request length
+4     BACKBUFFER              back-buffer-name
+=>
+1                             unused
+2     CARD16                  sequence number
+4     0                       reply length
+4     BUFFER_ATTRIBUTES       attributes
+20                            unused
+</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>