xenocara/doc/xorg-docs/specs/Xext/dbe.tex

% $Xorg: dbe.tex,v 1.3 2000/08/17 19:42:31 cpqbld Exp $
% edited for DP edits and code consistency w/ core protocol/xlib 3/30/96
% split into separate library and protocol documentos 4/15/96
\documentstyle{article}
\pagestyle{myheadings}
\markboth{Double Buffer Extension Specification}{Double Buffer Extension Specification}
\setlength{\parindent}{0 pt}
\setlength{\parskip}{6pt}
\setlength{\topsep}{0 pt}

% Request names are literal symbols; therefore, use the same font for both.
\newcommand{\requestname}[1]{{\tt #1}}
\newcommand{\literal}[1]{\mbox{\tt #1}}

\newcommand{\encodingsection}[1]{{\bf #1}}
\newcommand{\requestsection}[1]{{\bf #1}}

% Font treatment of type names differs between protocol and library sections.
\newcommand{\libtypename}[1]{\mbox{\tt #1}}
\newcommand{\typename}[1]{\mbox{\rm #1}}  % default font
\newcommand{\typeargname}[1]{\mbox{\rm #1}}  % default font
\newcommand{\argname}[1]{\mbox{\it #1}}
\newcommand{\argdecl}[2]{\argname{#1} & : \typename{#2}\\}
\newcommand{\areplyargdecl}[2]{#1 & : \typename{#2}\\}

\newenvironment{arequest}[1]{\requestsection{#1} \\ \begin{tabular}{ll}}{\end{tabular}}
\newcommand{\areply}{$\Rightarrow$\\}

\newcommand{\etabstops}{\hspace*{0cm}\=\hspace*{1cm}\=\hspace*{5cm}\=\kill}

\newcommand{\eargdecl}[3]{\> #1 \> \typename{#2} \> #3 \\}

\newenvironment{keeptogether}{\vbox \bgroup}{\egroup}

\newenvironment{erequest}[3]{\pagebreak[3] \begin{keeptogether} \encodingsection{#1} \begin{tabbing} \etabstops \eargdecl{1}{CARD8}{major-opcode} \eargdecl{1}{#2}{minor-opcode} \eargdecl{2}{#3}{request length}}{\end{tabbing} \end{keeptogether}}

\newenvironment{eerror}[1]{\begin{keeptogether} \encodingsection{#1} \begin{tabbing} \etabstops }{\end{tabbing} \end{keeptogether}}

\newenvironment{etypedef}[1]{\begin{keeptogether} \typename{#1} \begin{tabbing} \etabstops }{\end{tabbing} \end{keeptogether}}

\newcommand{\cfunctionname}[1]{\mbox{\tt #1}}
\newcommand{\cfunctiondecl}[1]{\mbox{\rm #1}}
\newcommand{\cargdecl}[2]{\penalty -1\typename{#1} \argname{#2}}
\newenvironment{cfunction}[2]{\begin{sloppypar}\begin{keeptogether}\vspace{5mm}\typename{#1}\\ \cfunctiondecl{#2}\ (}{)\end{keeptogether}\end{sloppypar}{\hangafter=2 \hangindent=20pt \raggedright\par}}

% make things easier with all the long names
\spaceskip .3333em plus 5em
\tolerance=2000

\begin{document}

\title{Double Buffer Extension Protocol\\Protocol Version 1.0\\X Consortium Standard}
\author{Ian Elliott\\Hewlett-Packard Company \and David P. Wiggins\\X Consortium, Inc.}
\maketitle
\thispagestyle{empty}

\eject

Copyright \copyright 1989 X Consortium, Inc. and Digital Equipment Corporation.

Copyright \copyright 1992 X Consortium, Inc. and Intergraph Corporation.

Copyright \copyright 1993 X Consortium, Inc. and Silicon Graphics, Inc.

Copyright \copyright 1994, 1995 X Consortium, Inc. and Hewlett-Packard Company.

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.

\eject

\section{Introduction}

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.

\section{Goals}

This extension should enable clients to:
\begin{itemize}

\item Allocate and deallocate double-buffering for a window.

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

\item Swap the front and back buffers associated with a window.

\item 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).

\item Request that the front and back buffers associated with multiple
double-buffered windows be swapped simultaneously.

\end{itemize}

In addition, the extension should:

\begin{itemize}

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

\item Support a range of implementation methods that can capitalize on
existing hardware features.

\item Add no new event types.

\item Be reasonably easy to integrate with a variety of direct graphics
hardware access (DGHA) architectures.
\end{itemize}

\section{Concepts}

Normal windows are created using the core \requestname{CreateWindow}
request, which allocates a set of window attributes and, for
\literal{InputOutput} windows, a front buffer,
into which an image can be drawn.
The contents of this buffer will be displayed when the window is
visible.

This extension enables applications to use double-buffering with a
window.  This involves creating a second buffer, called a back buffer,
and associating one or more back buffer names (\typename{XID}s) 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
\typename{DRAWABLE} of type \typename{BACKBUFFER}.

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.

Multiple clients and toolkits can all use double-buffering on the same
window.  DBE does not provide a request for querying whether a window
has double-buffering support, and if so, what the back buffer name is.
Given the asynchronous nature of the X Window System, this would cause
race conditions.  Instead, DBE allows multiple back buffer names to
exist for the same window; they all refer to the same physical back
buffer.  The first time a back buffer name is allocated for a window,
the window becomes double-buffered and the back buffer name is
associated with the window.  Subsequently, the window already is a
double-buffered window, and nothing about the window changes when a
new back buffer name is allocated, except that the new back buffer
name is associated with the window.  The window remains
double-buffered until either the window is destroyed or until all of
the back buffer names for the window are deallocated.

In general, both the front and back buffers are treated the same.  In
particular, here are some important characteristics:

\begin{itemize}

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

\item Both buffers associated with a window have the same visual type,
depth, width, height, and shape as the window.

\item Both buffers associated with a window are ``visible'' (or
``obscured'') in the same way.  When an \literal{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
\literal{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.

\item It is acceptable at any time to pass a \typename{BACKBUFFER} in
any request, notably any core or extension drawing request, that
expects a \typename{DRAWABLE}.  This enables an application to draw
directly into \typename{BACKBUFFER}s in the same fashion as it would
draw into any other \typename{DRAWABLE}.

\item It is an error (\literal{Window}) to pass a \typename{BACKBUFFER} in a
core request that expects a Window.

\item A \typename{BACKBUFFER} will never be sent by core X in a reply,
event, or error where a Window is specified.
\item If core X11 backing-store and save-under applies to a
double-buffered window, it applies to both buffers equally.

\item If the core \requestname{ClearArea} request is executed on a
double-buffered window, the same area in both the front and back
buffers is cleared.

\end{itemize}

The effect of passing a window to a request that accepts a
\typename{DRAWABLE} is unchanged by this extension.  The window and
front buffer are synonomous with each other.  This includes obeying
the \requestname{GetImage} semantics and the subwindow-mode semantics
if a core graphics context is involved.  Regardless of whether the
window was explicitly passed in a \requestname{GetImage} 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-na\"{\i}ve screen dump clients will always get the front buffer.
\requestname{GetImage} on a back buffer returns undefined image
contents for any obscured regions of the back buffer that fall within
the image.

Drawing to a back buffer always uses the clip region that would be
used to draw to the front buffer with a GC subwindow-mode of
\literal{ClipByChildren}.  If an ancestor of a double-buffered window is drawn
to with a core GC having a subwindow-mode of \literal{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 \literal{IncludeInferiors} drawing touched.

DBE adds no new events.  DBE does not extend the semantics of any
existing events with the exception of adding a new \typename{DRAWABLE}
type called \typename{BACKBUFFER}.  If events, replies, or errors that
contain a \typename{DRAWABLE} (for example, \literal{GraphicsExpose}) are
generated in
response to a request, the \typename{DRAWABLE} returned will be the
one specified in the request.

DBE advertises which visuals support double-buffering.

DBE does not include any timing or synchronization facilities.
Applications that need such facilities (for example, to maintain a constant
frame rate) should investigate the Synchronization Extension, an X
Consortium standard.

\subsection{Window Management Operations}

The basic philosophy of DBE is that both buffers are treated the same by
core X window management operations.

When the core \requestname{DestroyWindow} 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.

If the core \requestname{ConfigureWindow} 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
\requestname{ConfigureWindow} 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, \literal{Expose} events are generated for
the region that is tiled with the window background.

If the core \requestname{GetGeometry} request is executed on a
\typename{BACKBUFFER}, the returned x, y, and border-width will be
zero.

If the Shape extension \requestname{ShapeRectangles},
\requestname{ShapeMask}, \requestname{ShapeCombine}, or
\requestname{ShapeOffset} request is executed on a double-buffered
window, both buffers are reshaped to match the new window shape.  The
region difference is the following:

\[ D = new shape - old shape \]

It is tiled with the window background in both buffers,
and \literal{Expose} events are generated for D.

\subsection{Complex Swap Actions}

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.

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: \requestname{DBEBeginIdiom} and
\requestname{DBEEndIdiom}.  Unless this begin-end pair surrounds the
idiom, it may not be recognized by a given implementation, and
performance will suffer.

For example, if an application wants to swap buffers for two windows,
and use 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:

\begin{itemize}
\item \requestname{DBEBeginIdiom} request.
\item \requestname{DBESwapBuffers} request with XIDs for two windows, each
of which uses a swap action of \literal{Untouched}.
\item Core X \requestname{PolyFillRectangle} request to the back buffer of one window.
\item Core X \requestname{PolyFillRectangle} request to the back buffer of the other window.
\item \requestname{DBEEndIdiom} request.
\end{itemize}

The \requestname{DBEBeginIdiom} and \requestname{DBEEndIdiom} 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.

An idiom need not include a \requestname{DBESwapBuffers} request.  For
example, if a swap action of \literal{Copied} is desired, but only some of the
planes should be copied, a core X \requestname{CopyArea} request may
be used instead of \requestname{DBESwapBuffers}.  If
\requestname{DBESwapBuffers} is included in an idiom, it should
immediately follow the \requestname{DBEBeginIdiom} request.  Also,
when the \requestname{DBESwapBuffers} 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 \literal{Untouched}, and if a
\requestname{PolyFillRectangle} using a client clip rectangle is done
to the window's back buffer after the \requestname{DBESwapBuffers}
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.

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 \requestname{DBEBeginIdiom} request,
the idiom requests, and \requestname{DBEEndIdiom} request.  Usage of
these functions will ensure best possible performance across a wide
variety of implementations.

\section{Requests}

The DBE defines the following requests.

\subsection{DBEGetVersion}

This request returns the major and minor version numbers of this
extension.

% start marker
\begin{arequest}{DBEGetVersion}
\argdecl{client-major-version}{CARD8}
\argdecl{client-minor-version}{CARD8}
\areply
\areplyargdecl{server-major-version}{CARD8}
\areplyargdecl{server-minor-version}{CARD8}
\end{arequest}
% end marker

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

The DBE client must issue a \requestname{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).

\subsection{DBEGetVisualInfo}

This request returns information about which visuals support double
buffering.

% start marker
\begin{arequest}{DBEGetVisualInfo}
\argdecl{screen-specifiers}{LISTofDRAWABLE}
\areply
\areplyargdecl{visinfo}{LISTofSCREENVISINFO}
\end{arequest}

where:
\begin{tabbing}
\typename{SCREENVISINFO}: \= \typename{LISTofVISINFO}\\
\typename{VISINFO}: \> [ \= \typeargname{visual}: \typename{VISUALID}\\
			\>\> \typeargname{depth}: \typename{CARD8}\\
			\>\> \typeargname{perflevel}: \typename{CARD8} ]
\end{tabbing}
%
Errors: \literal{Drawable}
% end marker

All of the values passed in screen-specifiers must be valid
\typename{DRAWABLE}s (or a \literal{Drawable} 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.

If the list of screen-specifiers is empty, information for
all screens is returned, starting with screen zero.

\subsection{DBEAllocateBackBufferName}

This request allocates a drawable ID used to refer to the back buffer of a
window.

% start marker
\begin{arequest}{DBEAllocateBackBufferName}
\argdecl{window}{WINDOW}
\argdecl{back-buffer-name}{BACKBUFFER}
\argdecl{swap-action-hint}{SWAPACTION}
\end{arequest}

Errors: \literal{Alloc, Value, IDChoice, Match, Window}
% end marker

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 \requestname{DBESwapBuffers} requests.  The
swap-action-hint must have one of the values specified for
type \typename{SWAPACTION} (or a \literal{Value} error results).  See the
description of the \requestname{DBESwapBuffers} request for a complete
discussion of swap actions and the \typename{SWAPACTION} type.

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.

The window passed into the request must be a valid \typename{WINDOW}
(or a \literal{Window} error results).
The window passed into the request must
be an \literal{InputOutput} window (or a \literal{Match} error results).
The visual of the window must be in the list returned by
\requestname{DBEGetVisualInfo} (or a \literal{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 \literal{IDChoice}
error results).
If the server cannot allocate all resources associated with turning on
double-buffering for the window, an \literal{Alloc} error results, the
window's double-buffer status (whether it is already double-buffered or not)
remains unchanged, and the back-buffer-name is freed.

\subsection{DBEDeallocateBackBufferName}

This request frees a drawable ID that was obtained by
\requestname{DBEAllocateBackBufferName}.

% start marker
\begin{arequest}{DBEDeallocateBackBufferName}
\argdecl{back-buffer-name}{BACKBUFFER}
\end{arequest}

Errors: \literal{Buffer}
% end marker

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.

The back-buffer-name must be a valid \typename{BACKBUFFER}
associated with a window (or a \literal{Buffer} error results).

\subsection{DBESwapBuffers}

This request swaps the buffers for all windows listed, applying the
appropriate swap action for each window.

% start marker
\begin{arequest}{DBESwapBuffers}
\argdecl{windows}{LISTofSWAPINFO}
\end{arequest}

where:
\begin{tabbing}
\typename{SWAPINFO}: \= [ \= \typeargname{window}: \typename{WINDOW}\\
			\>\> \typeargname{swap-action}: \typename{SWAPACTION} ]\\
\typename{SWAPACTION}: \{\literal{Undefined, Background, Untouched, Copied}\}
\end{tabbing}
%
Errors: \literal{Match, Window, Value}
% end marker

Each window passed into the request must be a valid \typename{WINDOW}
(or a \literal{Window} error results).
Each window passed into the request must
be a double-buffered window (or a \literal{Match} error results).
Each window passed into the request must only be listed once
(or a \literal{Match} error results).
Each swap-action in the list must have one of the
values specified for type \typename{SWAPACTION} (or a \literal{Value} error
results).  If an error results, none of the valid double-buffered
windows will have their buffers swapped.

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:

\begin{description}
\setlength{\labelsep}{2em}
\item[\literal{Undefined}]	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.

\item[\literal{Background}]	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.

\item[\literal{Untouched}]	The unobscured region of the new back buffer
				will be unmodified by the swap.

\item[\literal{Copied}]		The unobscured region of the new back buffer
				will be the contents of the old back buffer.
\end{description}

If \requestname{DBESwapBuffers} is included in a ``swap and clear''
type of idiom, it must immediately follow the \requestname{DBEBeginIdiom}
request.

\subsection{DBEBeginIdiom}

This request informs the server that a complex swap will immediately
follow this request.  

% start marker
\begin{arequest}{DBEBeginIdiom}
\end{arequest}
% end marker

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.

\subsection{DBEEndIdiom}

This request informs the server that a complex swap has concluded.  

% start marker
\begin{arequest}{DBEEndIdiom}
\end{arequest}
% end marker

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.


\subsection{DBEGetBackBufferAttributes}

This request returns information about a back buffer.

% start marker
\begin{arequest}{DBEGetBackBufferAttributes}
\argdecl{back-buffer-name}{BACKBUFFER}
\areply
\areplyargdecl{attributes}{BUFFER\_ATTRIBUTES}
\end{arequest}

where:

\typename{BUFFER\_ATTRIBUTES}: [\typeargname{window}: \typename{WINDOW} ]
% end marker

If back-buffer-name is a valid \typename{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 \typename{BACKBUFFER}, the window field of
the attributes in the reply will be \literal{None}.

\section{Encoding}

Please refer to the X11 Protocol Encoding document as this section uses
syntactic conventions and data types established there.

The name of this extension is ``DOUBLE-BUFFER''.

\subsection{Types}

The following new types are used by the extension.

\typename{BACKBUFFER}: \typename{XID}
\vspace{5mm}

\begin{etypedef}{SWAPACTION}
\eargdecl{\#x00}{Undefined}{}
\eargdecl{\#x01}{Background}{}
\eargdecl{\#x02}{Untouched}{}
\eargdecl{\#x03}{Copied}{}
\end{etypedef}

\begin{etypedef}{SWAPINFO}
\eargdecl{4}{WINDOW}{window}
\eargdecl{1}{SWAPACTION}{swap action}
\eargdecl{3}{}{unused}
\end{etypedef}

\begin{etypedef}{VISINFO}
\eargdecl{4}{VISUALID}{visual}
\eargdecl{1}{CARD8}{depth}
\eargdecl{1}{CARD8}{perflevel}
\eargdecl{2}{}{unused}
\end{etypedef}

\begin{etypedef}{SCREENVISINFO}
\eargdecl{4}{CARD32}{n, number in list}
\eargdecl{8n}{LISTofVISINFO}{n VISINFOs}
\end{etypedef}

\begin{etypedef}{BUFFER\_ATTRIBUTES}
\eargdecl{4}{WINDOW}{window}
\end{etypedef}

\subsection{Errors}

\begin{eerror}{Buffer}
\eargdecl{1}{0}{error}
\eargdecl{1}{error base + 0}{code}
\eargdecl{2}{CARD16}{sequence number}
\eargdecl{4}{CARD32}{bad buffer}
\eargdecl{2}{CARD16}{minor-opcode}
\eargdecl{1}{CARD8}{major-opcode}
\eargdecl{21}{}{unused}
\end{eerror}

\subsection{Requests}

\begin{erequest}{DBEGetVersion}{0}{2}
\eargdecl{1}{CARD8}{client-major-version}
\eargdecl{1}{CARD8}{client-minor-version}
\eargdecl{2}{}{unused}
\areply
\eargdecl{1}{1}{Reply}
\eargdecl{1}{}{unused}
\eargdecl{2}{CARD16}{sequence number}
\eargdecl{4}{0}{reply length}
\eargdecl{1}{CARD8}{server-major-version}
\eargdecl{1}{CARD8}{server-minor-version}
\eargdecl{22}{}{unused}
\end{erequest}

\begin{erequest}{DBEAllocateBackBufferName}{1}{4}
\eargdecl{4}{WINDOW}{window}
\eargdecl{4}{BACKBUFFER}{back buffer name}
\eargdecl{1}{SWAPACTION}{swap action hint}
\eargdecl{3}{}{unused}
\end{erequest}

\begin{erequest}{DBEDeallocateBackBufferName}{2}{2}
\eargdecl{4}{BACKBUFFER}{back buffer name}
\end{erequest}

\begin{erequest}{DBESwapBuffers}{3}{2+2n}
\eargdecl{4}{CARD32}{n, number of window/swap action pairs in list}
\eargdecl{8n}{LISTofSWAPINFO}{window/swap action pairs}
\end{erequest}

\begin{erequest}{DBEBeginIdiom}{4}{1}
\end{erequest}

\begin{erequest}{DBEEndIdiom}{5}{1}
\end{erequest}

\begin{erequest}{DBEGetVisualInfo}{6}{2+n}
\eargdecl{4}{CARD32}{n, number of screen specifiers in list}
\eargdecl{4n}{LISTofDRAWABLE}{n screen specifiers}
\areply
\eargdecl{1}{1}{Reply}
\eargdecl{1}{}{unused}
\eargdecl{2}{CARD16}{sequence number}
\eargdecl{4}{CARD32}{reply length}
\eargdecl{4}{CARD32}{m, number of SCREENVISINFOs in list}
\eargdecl{20}{}{unused}
\eargdecl{4j}{LISTofSCREENVISINFO}{m SCREENVISINFOs}
\end{erequest}

\begin{erequest}{DBEGetBackBufferAttributes}{7}{2}
\eargdecl{4}{BACKBUFFER}{back-buffer-name}
\areply
\eargdecl{1}{1}{Reply}
\eargdecl{1}{}{unused}
\eargdecl{2}{CARD16}{sequence number}
\eargdecl{4}{0}{reply length}
\eargdecl{4}{BUFFER\_ATTRIBUTES}{attributes}
\eargdecl{20}{}{unused}
\end{erequest}

\pagebreak[4]
\section{Acknowledgements}

We wish to thank the following individuals who have contributed their
time and talent toward shaping the DBE specification:

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.

Mark provided the impetus to start the DBE project.  Ian wrote the
first draft of the specification.  David served as architect.

\section{References}

Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, ``Multi-buffering Extension
Specification Version 3.3.''

Tim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins,
``X Synchronization Extension Version 3.0.'' 

\end{document}