/usr/share/doc/x11proto-xext-dev/multibuf.html

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Extending X for Double-Buffering, Multi-Buffering, and Stereo</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><style xmlns="" type="text/css">/*
 * Copyright (c) 2011 Gaetan Nadon
 * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the next
 * paragraph) shall be included in all copies or substantial portions of the
 * Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

/*
 * Shared stylesheet for X.Org documentation translated to HTML format
 * http://www.sagehill.net/docbookxsl/UsingCSS.html
 * http://www.w3schools.com/css/default.asp
 * https://addons.mozilla.org/en-US/firefox/addon/web-developer/developers
 * https://addons.mozilla.org/en-US/firefox/addon/font-finder/
 */

/*
 * The sans-serif fonts are considered more legible on a computer screen
 * http://dry.sailingissues.com/linux-equivalents-verdana-arial.html
 *
 */
body {
  font-family: "Bitstream Vera Sans", "DejaVu Sans", Tahoma, Geneva, Arial, Sans-serif;
  /* In support of using "em" font size unit, the w3c recommended method */
  font-size: 100%;
}

/*
 * Selection: all elements requiring mono spaced fonts.
 *
 * The family names attempt to match the proportionally spaced font
 * family names such that the same font name is used for both.
 * We'd like to use Bitstream, for example, in both proportionally and
 * mono spaced font text.
 */
.command,
.errorcode,
.errorname,
.errortype,
.filename,
.funcsynopsis,
.function,
.parameter,
.programlisting,
.property,
.screen,
.structname,
.symbol,
.synopsis,
.type
{
  font-family:  "Bitstream Vera Sans Mono", "DejaVu Sans Mono", Courier, "Liberation Mono", Monospace;
}

/*
 * Books have a title page, a preface, some chapters and appendices,
 * a glossary, an index and a bibliography, in that order.
 *
 * An Article has no preface and no chapters. It has sections, appendices,
 * a glossary, an index and a bibliography.
 */

/*
 * Selection: book main title and subtitle
 */
div.book>div.titlepage h1.title,
div.book>div.titlepage h2.subtitle {
  text-align: center;
}

/*
 * Selection: article main title and subtitle
 */
div.article>div.titlepage h2.title,
div.article>div.titlepage h3.subtitle,
div.article>div.sect1>div.titlepage h2.title,
div.article>div.section>div.titlepage h2.title {
  text-align: center;
}

/*
 * Selection: various types of authors and collaborators, individuals or corporate
 *
 * These authors are not always contained inside an authorgroup.
 * They can be contained inside a lot of different parent types where they might
 * not be centered.
 * Reducing the margin at the bottom makes a visual separation between authors
 * We specify here the ones on the title page, others may be added based on merit.
 */
div.titlepage .authorgroup,
div.titlepage .author,
div.titlepage .collab,
div.titlepage .corpauthor,
div.titlepage .corpcredit,
div.titlepage .editor,
div.titlepage .othercredit {
  text-align: center;
  margin-bottom: 0.25em;
}

/*
 * Selection: the affiliation of various types of authors and collaborators,
 * individuals or corporate.
 */
div.titlepage .affiliation {
  text-align: center;
}

/*
 * Selection: product release information (X Version 11, Release 7)
 *
 * The releaseinfo element can be contained inside a lot of different parent
 * types where it might not be centered.
 * We specify here the one on the title page, others may be added based on merit.
 */
div.titlepage p.releaseinfo {
  font-weight: bold;
  text-align: center;
}

/*
 * Selection: publishing date
 */
div.titlepage .pubdate {
  text-align: center;
}

/*
 * The legal notices are displayed in smaller sized fonts
 * Justification is only supported in IE and therefore not requested.
 *
 */
.legalnotice {
  font-size: small;
  font-style: italic;
}

/*
 * Selection: book or article main ToC title
 * A paragraph is generated for the title rather than a level 2 heading.
 * We do not want to select chapters sub table of contents, only the main one
 */
div.book>div.toc>p,
div.article>div.toc>p {
  font-size: 1.5em;
  text-align: center;
}

/*
 * Selection: major sections of a book or an article
 *
 * Unlike books, articles do not have a titlepage element for appendix.
 * Using the selector "div.titlepage h2.title" would be too general.
 */
div.book>div.preface>div.titlepage h2.title,
div.book>div.chapter>div.titlepage h2.title,
div.article>div.sect1>div.titlepage h2.title,
div.article>div.section>div.titlepage h2.title,
div.book>div.appendix>div.titlepage h2.title,
div.article>div.appendix h2.title,
div.glossary>div.titlepage h2.title,
div.index>div.titlepage h2.title,
div.bibliography>div.titlepage h2.title {
   /* Add a border top over the major parts, just like printed books */
   /* The Gray color is already used for the ruler over the main ToC. */
  border-top-style: solid;
  border-top-width: 2px;
  border-top-color: Gray;
  /* Put some space between the border and the title */
  padding-top: 0.2em;
  text-align: center;
}

/*
 * A Screen is a verbatim environment for displaying text that the user might
 * see on a computer terminal. It is often used to display the results of a command.
 *
 * http://www.css3.info/preview/rounded-border/
 */
.screen {
  background: #e0ffff;
  border-width: 1px;
  border-style: solid;
  border-color: #B0C4DE;
  border-radius: 1.0em;
  /* Browser's vendor properties prior to CSS 3 */
  -moz-border-radius: 1.0em;
  -webkit-border-radius: 1.0em;
  -khtml-border-radius: 1.0em;
  margin-left: 1.0em;
  margin-right: 1.0em;
  padding: 0.5em;
}

/*
 * Emphasis program listings with a light shade of gray similar to what
 * DocBook XSL guide does: http://www.sagehill.net/docbookxsl/ProgramListings.html
 * Found many C API docs on the web using like shades of gray.
 */
.programlisting {
  background: #F4F4F4;
  border-width: 1px;
  border-style: solid;
  border-color: Gray;
  padding: 0.5em;
}

/*
 * Emphasis functions synopsis using a darker shade of gray.
 * Add a border such that it stands out more.
 * Set the padding so the text does not touch the border.
 */
.funcsynopsis, .synopsis {
  background: #e6e6fa;
  border-width: 1px;
  border-style: solid;
  border-color: Gray;
  clear: both;
  margin: 0.5em;
  padding: 0.25em;
}

/*
 * Selection: paragraphs inside synopsis
 *
 * Removes the default browser margin, let the container set the padding.
 * Paragraphs are not always used in synopsis
 */
.funcsynopsis p,
.synopsis p {
  margin: 0;
  padding: 0;
}

/*
 * Selection: variable lists, informal tables and tables
 *
 * Note the parameter name "variablelist.as.table" in xorg-xhtml.xsl
 * A table with rows and columns is constructed inside div.variablelist
 *
 * Set the left margin so it is indented to the right
 * Display informal tables with single line borders
 */
table {
  margin-left: 0.5em;
  border-collapse: collapse;
}

/*
 * Selection: paragraphs inside tables
 *
 * Removes the default browser margin, let the container set the padding.
 * Paragraphs are not always used in tables
 */
td p {
  margin: 0;
  padding: 0;
}

/*
 * Add some space between the left and right column.
 * The vertical alignment helps the reader associate a term
 * with a multi-line definition.
 */
td, th {
  padding-left: 1.0em;
  padding-right: 1.0em;
  vertical-align: top;
}

.warning {
  border: 1px solid red;
  background: #FFFF66;
  padding-left: 0.5em;
}
</style></head><body><div class="book" title="Extending X for Double-Buffering, Multi-Buffering, and Stereo"><div class="titlepage"><div><div><h1 class="title"><a id="multibuf"></a>Extending X for Double-Buffering, Multi-Buffering, and Stereo</h1></div><div><div class="authorgroup"><div class="othercredit"><h3 class="othercredit"><span class="firstname">Jeffrey</span> <span class="surname">Friedberg</span></h3></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Larry</span> <span class="surname">Seiler</span></h3></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Jeff</span> <span class="surname">Vroom</span></h3></div></div></div><div><p class="releaseinfo">X Version 11, Release 7.6</p></div><div><p class="releaseinfo">Version 3.3</p></div><div><p class="copyright">Copyright © 1989 Digital Equipment Corporation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="idp16478320"></a><p>
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 makes 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.  This document
is subject to change.
</p></div></div><div><div class="legalnotice" title="Legal Notice"><a id="idp16782152"></a><p class="multiLicensing">Copyright © 1989, 1994 X Consortium</p><p>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the ``Software''), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
</p><p>
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
</p><p>
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
</p><p>
Except as contained in this notice, the name of the X Consortium shall not be
used in advertising or otherwise to promote the sale, use or other dealings
in this Software without prior written authorization from the X Consortium.
</p><p>X Window System is a trademark of The OpenGroup.</p></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="preface"><a href="#idp16740080">Warning</a></span></dt><dt><span class="chapter"><a href="#Introduction">1. Introduction</a></span></dt><dt><span class="chapter"><a href="#Goals">2. Goals</a></span></dt><dt><span class="chapter"><a href="#Image_Buffers">3. Image Buffers</a></span></dt><dt><span class="chapter"><a href="#New_Requests">4. New Requests</a></span></dt><dt><span class="chapter"><a href="#Attributes">5. Attributes</a></span></dt><dt><span class="chapter"><a href="#Events">6. Events</a></span></dt><dt><span class="chapter"><a href="#Errors">7. Errors</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Buffer_2">Buffer</a></span></dt><dt><span class="sect1"><a href="#Double_Buffering_Normal_Windows">Double-Buffering Normal Windows</a></span></dt><dt><span class="sect1"><a href="#Multi_Buffering_Normal_Windows">Multi-Buffering Normal Windows</a></span></dt><dt><span class="sect1"><a href="#Stereo_Windows">Stereo Windows</a></span></dt><dt><span class="sect1"><a href="#Single_Buffered_Stereo_Windows">Single-Buffered Stereo Windows</a></span></dt><dt><span class="sect1"><a href="#Double_Buffering_Stereo_Windows">Double-Buffering Stereo Windows</a></span></dt><dt><span class="sect1"><a href="#Multi_Buffering_Stereo_Windows">Multi-Buffering Stereo Windows</a></span></dt><dt><span class="sect1"><a href="#Protocol_Encoding">Protocol Encoding</a></span></dt></dl></dd><dt><span class="chapter"><a href="#TYPES">8. TYPES</a></span></dt><dt><span class="chapter"><a href="#EVENTS_2">9. EVENTS</a></span></dt><dt><span class="chapter"><a href="#ERRORS_2">10. ERRORS</a></span></dt><dt><span class="chapter"><a href="#Requests">11. REQUESTS</a></span></dt></dl></div><div class="preface" title="Warning"><div class="titlepage"><div><div><h2 class="title"><a id="idp16740080"></a>Warning</h2></div></div></div><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
The <span class="emphasis"><em>Multi-Buffering</em></span> extension described here
was a draft standard of the X Consortium prior to Release 6.1.  It has been
superseded by the Double Buffer
Extension (DBE).  DBE is an X Consortium Standard as of Release 6.1.
</p></div></div><div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a id="Introduction"></a>Chapter 1. Introduction</h2></div></div></div><p>
Several proposals have been written that address some of the
issues surrounding the support of double-buffered, multi-buffered,
and stereo windows in the X Window System:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
<span class="emphasis"><em>Extending X for Double-Buffering,</em></span>
Jeffrey Friedberg, Larry Seiler, Randi Rost.
    </p></li><li class="listitem"><p>
<span class="emphasis"><em>(Proposal for) Double-Buffering Extensions</em></span>,
Jeff Vroom.
    </p></li><li class="listitem"><p>
<span class="emphasis"><em>An Extension to X.11 for Displays with Multiple Buffers,</em></span>
David S.H. Rosenthal.
    </p></li><li class="listitem"><p>
<span class="emphasis"><em>A Multiple Buffering/Stereo Proposal</em></span>,
Mark Patrick.
    </p></li></ul></div><p>
The authors of this proposal have tried to unify the above documents
to yield a proposal that incorporates support for double-buffering,
multi-buffering, and stereo in a way that is acceptable to all concerned.
</p></div><div class="chapter" title="Chapter 2. Goals"><div class="titlepage"><div><div><h2 class="title"><a id="Goals"></a>Chapter 2. Goals</h2></div></div></div><p>
Clients should be able to:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
Associate multiple buffers with a window.
    </p></li><li class="listitem"><p>
Paint in any buffer associated with a window.
    </p></li><li class="listitem"><p>
Display any buffer associated with a window.
    </p></li><li class="listitem"><p>
Display a series of buffers in a window in rapid succession
to achieve a <span class="emphasis"><em>smooth</em></span> animation.
    </p></li><li class="listitem"><p>
Request simultaneous display of different buffers in different windows.
    </p></li></ul></div><p>
In addition, the extension should:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
Allow existing X applications to run unchanged.
    </p></li><li class="listitem"><p>
Support a range of implementation methods that can capitalize on
existing hardware features.
    </p></li></ul></div></div><div class="chapter" title="Chapter 3. Image Buffers"><div class="titlepage"><div><div><h2 class="title"><a id="Image_Buffers"></a>Chapter 3. Image Buffers</h2></div></div></div><p>
Normal windows are created using the standard
<code class="function">CreateWindow</code> request:
</p><pre class="literallayout">
CreateWindow
     parent          : WINDOW
     w_id            : WINDOW
     depth           : CARD8
     visual          : VISUALID or CopyFromParent
     x, y            : INT16
     width, height   : INT16
     border_width    : INT16
     value_mask      : BITMASK
     value_list      : LISTofVALUE
</pre><p>
This request allocates a set of window attributes and
a buffer into which an image can be drawn.
The contents of this <span class="emphasis"><em>image buffer</em></span> will
be displayed when the window is mapped to the screen.
</p><p>
To support double-buffering and multi-buffering,
we introduce the notion that additional image buffers can
be created and bound together to form groups.
The following rules will apply:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
All image buffers in a group will have the same
visual type, depth, and geometry (ie: width and height).
    </p></li><li class="listitem"><p>
Only one image buffer per group can be displayed
at a time.
    </p></li><li class="listitem"><p>
Draw operations can occur to any image buffer at
any time.
    </p></li><li class="listitem"><p>
Window management requests (<code class="function">MapWindow</code>, <code class="function">DestroyWindow</code>,
<code class="function">ConfigureWindow</code>, etc...)
affect all image buffers associated with a window.
    </p></li><li class="listitem"><p>
Appropriate resize and exposure events will be generated
for every image buffer that is affected by a window
management operation.
    </p></li></ul></div><p>
By allowing draw operations to occur on any image buffer at any time,
a client could, on a multi-threaded multi-processor server,
simultaneously build up images for display.
To support this, each buffer must have its own resource ID.
Since buffers are different than windows and pixmaps
(buffers are not hierarchical and pixmaps cannot be displayed)
a new resource, <code class="function">Buffer</code>, is introduced.
Furthermore, a <code class="function">Buffer</code> is also a <code class="function">Drawable</code>, thus
draw operations may also be performed on buffers simply
by passing a buffer ID to the existing pixmap/window
interface.
</p><p>
To allow existing X applications to work unchanged, we assume
a window ID passed in a draw request, for a multi-buffered
window, will be an <span class="emphasis"><em>alias</em></span> for the ID of the currently
displayed image buffer.  Any draw requests (eq: <code class="function">GetImage</code>) on
the window will be relative to the displayed image buffer.
</p><p>
In window management requests, only a window ID will be
accepted.  Requests like <code class="function">QueryTree</code>, will continue to
return only window ID's.  Most events will return
just the window ID.  Some new events, described in a subsequent
section, will return a buffer ID.
</p><p>
When a window has backing store the contents of the window
are saved off-screen.  Likewise, when the contents of an image
buffer of a multi-buffer window is saved off-screen, it is
said to have backing store.  This applies to all image buffers,
whether or not they are selected for display.
</p><p>
In some multi-buffer implementations, undisplayed buffers might be
implemented using pixmaps.  Since the contents of pixmaps exist
off-screen and are not affected by occlusion, these image buffers
in effect have backing store.
</p><p>
On the other hand, both the displayed and undisplayed image buffers
might be implemented using a subset of the on-screen pixels.
In this case, unless the contents of an image buffer are saved
off-screen, these image buffers in effect do not have backing store.
</p><p>
Output to any image buffer of an unmapped multi-buffered window
that does not have backing store is discarded.  Output to any
image buffer of a mapped multi-buffer window will be performed;
however, portions of an image buffer may be occluded or clipped.
</p><p>
When an unmapped multi-buffered window becomes mapped, the contents
of any image buffer buffer that did not have backing store is
tiled with the background and zero or more exposure events are
generated.  If no background is defined for the window, then
the screen contents are not altered and the contents of any
undisplayed image buffers are undefined.  If backing store was
maintained for an image buffer, then no exposure events are generated.
</p></div><div class="chapter" title="Chapter 4. New Requests"><div class="titlepage"><div><div><h2 class="title"><a id="New_Requests"></a>Chapter 4. New Requests</h2></div></div></div><p>
The new request, <code class="function">CreateImageBuffers</code>, creates a group of
image buffers and associates them with a normal X window:
</p><pre class="literallayout">
CreateImageBuffers
     w_id           : WINDOW
     buffers        : LISTofBUFFER
     update_action  : {Undefined,Background,Untouched,Copied}
     update_hint    : {Frequent,Intermittent,Static}
     =&gt;
     number_buffers : CARD16

     (Errors: Window, IDChoice, Value)
</pre><p>
One image buffer will be associated with each ID passed in
<span class="emphasis"><em>buffers</em></span>.
The first buffer of the list is referred to as buffer[0], the next
buffer[1], and so on.  Each buffer will have the same visual type
and geometry as the window.
Buffer[0] will refer to the image buffer already associated
with the window ID and its contents will not be modified.
The displayed image buffer attribute is set to buffer[0].
</p><p>
Image buffers for the remaining ID's (buffer[1],...) are allocated.
If the window is mapped, or if these image buffers have backing
store, their contents will be tiled with the window background
(if no background is defined, the buffer contents are undefined),
and zero or more expose events will be generated for each of these
buffers.  The contents of an image buffer is undefined when
the window is unmapped and the buffer does not have backing store.
</p><p>
If the window already has a group of image buffers
associated with it (ie: from a previous <code class="function">CreateImageBuffers</code> request)
the actions described for <code class="function">DestroyImageBuffers</code> are performed first
(this will delete the association of the previous buffer ID's and
their buffers as well as de-allocate all buffers except for the
one already associated with the window ID).
</p><p>
To allow a server implementation to efficiently allocate the
buffers, the total number of buffers required and
the update action (how they will behave during an update)
is specified "up front" in the request.
If the server cannot allocate all the buffers requested, the
total number of buffers actually allocated will be returned.
No <code class="function">Alloc</code> errors will be generated \- buffer[0] can
always be associated with the existing displayed image buffer.
</p><p>
For example, an application that wants to animate a short movie
loop may request 64 image buffers.  The server may only be able to
support 16 image buffers of this type, size, and depth.
The application can then decide 16 buffers is sufficient and may
truncate the movie loop, or it may decide it really needs
64 and will free the buffers and complain to the user.
</p><p>
One might be tempted to provide a request that inquires whether
<span class="emphasis"><em>n</em></span>
buffers of a particular type, size, and depth
<span class="emphasis"><em>could</em></span> be allocated.
But if the query is decoupled from the actual allocation,
another client could sneak in and take the buffers before the
original client has allocated them.
</p><p>
While any buffer of a group can be selected for display,
some applications may display buffers in a predictable order
(ie: the movie loop application).  The
<span class="emphasis"><em>list order</em></span>
(buffer[0], buffer[1], ...) will be used as a hint by the
server as to which buffer will be displayed next.
A client displaying buffers in this order may see a
performance improvement.
</p><p>
<span class="emphasis"><em>update_action</em></span> indicates what should happen to a previously
displayed buffer when a different buffer becomes displayed.
Possible actions are:
</p><div class="variablelist"><table border="0"><col align="left" valign="top" /><tbody><tr><td><p><span class="term">Undefined</span></p></td><td><p>
The contents of the buffer that was
last displayed will become undefined after the update.  This
is the most efficient action since it allows the implementation
to trash the contents of the buffer if it needs to.
      </p></td></tr><tr><td><p><span class="term">Background</span></p></td><td><p>
The contents of the buffer that was
last displayed will be set to the background of the window after the update.
The background action allows devices to use a fast clear
capability during an update.
      </p></td></tr><tr><td><p><span class="term">Untouched</span></p></td><td><p>
The contents of the buffer that was
last displayed will be untouched after the update.  Used
primarily when cycling through images that have already
been drawn.
      </p></td></tr><tr><td><p><span class="term">Copied</span></p></td><td><p>
The contents of the buffer that was
last displayed will become the same as those that are being
displayed after the update.  This is useful when incrementally
adding to an image.
      </p></td></tr></tbody></table></div><p>
<span class="emphasis"><em>update_hint</em></span> indicates how often the client will
request a different buffer to be displayed.
This hint will allow smart server implementations to choose the
most efficient means to support a multi-buffered window based
on the current need of the application (dumb implementations
may choose to ignore this hint).  Possible hints are:
</p><div class="variablelist"><table border="0"><col align="left" valign="top" /><tbody><tr><td><p><span class="term">Frequent</span></p></td><td><p>
An animation or movie loop is
being attempted and the fastest, most efficient means for
multi-buffering should be employed.
      </p></td></tr><tr><td><p><span class="term">Intermittent</span></p></td><td><p>
The displayed image will be
changed every so often.  This is common for images that are
displayed at a rate slower than a second.  For example, a
clock that is updated only once a minute.
      </p></td></tr><tr><td><p><span class="term">Static</span></p></td><td><p>
The displayed image buffer will
not be changed any time soon.  Typically set by an application
whenever there is a pause in the animation.
      </p></td></tr></tbody></table></div><p>
To display an image buffer the following request can be used:
</p><pre class="literallayout">
DisplayImageBuffers
     buffers         : LISTofBUFFER
     min_delay       : CARD16
     max_delay       : CARD16

     (Errors: Buffer, Match)
</pre><p>
The image buffers listed will become displayed as simultaneously
as possible and the update action, bound at
<code class="function">CreateImageBuffers</code>
time, will be performed.
</p><p>
A list of buffers is specified to
allow the server to efficiently change the display of more than one
window at a time (ie: when a global screen swap method is used).
Attempting to simultaneously display
multiple image buffers from the same window is an error
(<code class="function">Match</code>) since it violates the rule that only one
image buffer per group can be displayed at a time.
</p><p>
If a specified buffer is already displayed,
any delays and update action will still be
performed for that buffer.  In this instance,
only the update action of <span class="emphasis"><em>Background</em></span>
(and possibly
<span class="emphasis"><em>Undefined</em></span>) will have any affect on the
contents of the displayed buffer.  These semantics allow
an animation application to successfully execute
even when there is only a single buffer available
for a window.
</p><p>

When a <code class="function">DisplayImageBuffers</code> request is made to an unmapped
multi-buffered window, the effect of the update action depends
on whether the image buffers involved have backing store.
When the target of the update action is an image buffer that
does not have backing store, output is discarded.  When the
target image buffer does have backing store, the update is performed;
however, when the source of the update is an image buffer does not
have backing store (as in the case of update action
<span class="emphasis"><em>Copied</em></span>), the
contents of target image buffer will become undefined.
</p><p>

<span class="emphasis"><em>min_delay</em></span> and
<span class="emphasis"><em>max_delay</em></span> put a bound on how long the
server should wait before processing the display request.
For each of the windows to be updated by this request, at least
<span class="emphasis"><em>min_delay</em></span> milli-seconds should elapse since
the last
time any of the windows were updated; conversely, no window
should have to wait more than <span class="emphasis"><em>max_delay</em></span>
milli-seconds before being updated.
</p><p>
<span class="emphasis"><em>min_delay</em></span> allows an application to
<span class="emphasis"><em>slow down</em></span> an animation or movie loop so that
it appears
synchronized at a rate the server can support given the current load.
For example, a <span class="emphasis"><em>min_delay</em></span> of 100 indicates the
server should
wait at least 1/10 of a second since the last time any of the
windows were updated.  A <span class="emphasis"><em>min_delay</em></span> of zero
indicates no waiting is necessary.
</p><p>
<span class="emphasis"><em>max_delay</em></span> can be thought of as an additional
delay beyond <span class="emphasis"><em>min_delay</em></span> the server is allowed
to wait
to facilitate such things as efficient update of multiple windows.
If <span class="emphasis"><em>max_delay</em></span> would require an update before
<span class="emphasis"><em>min_delay</em></span>
is satisfied, then the server should process the display request as
soon as the <span class="emphasis"><em>min_delay</em></span> requirement is met.  A
typical value for <span class="emphasis"><em>max_delay</em></span> is zero.
</p><p>
To implement the above functionality, the time since the last
update by a <code class="function">DisplayImageBuffers</code> request for each
multi-buffered
window needs to be saved as state by the server.
The server may delay execution of the <code class="function">DisplayImageBuffers</code>
request until the appropriate time (e.g. by requeuing the
request after computing the timeout);
however, the entire request must be processed in one operation.
Request execution indivisibility must be maintained.  When
a server is implemented with internal concurrency, the
extension must adhere to the same concurrency semantics
as those defined for the core protocol.
</p><p>
To explicitly clear a rectangular area of an image buffer to
the window background, the following request can be used:
</p><pre class="literallayout">
ClearImageBufferArea
     buffer          : BUFFER
     x, y            : INT16
     w, h            : CARD16
     exposures       : BOOL

     (Errors: Buffer, Value)
</pre><p>
Like the X <code class="function">ClearArea</code> request,
<span class="emphasis"><em>x</em></span> and <span class="emphasis"><em>y</em></span>
are relative to
the window's origin and specify the upper-left corner of the rectangle.
If <span class="emphasis"><em>width</em></span> is zero, it is replaced with the
current window width
minus <span class="emphasis"><em>x</em></span>.  If
<span class="emphasis"><em>height</em></span> is zero it is replaced with the current
window height minus <span class="emphasis"><em>y</em></span>.  If the window has a
defined background tile, the rectangle is tiled with a plane mask of all ones,
a function of <span class="emphasis"><em>Copy</em></span>, and a subwindow-mode of
<span class="emphasis"><em>ClipByChildren</em></span>.
If the window has background <span class="emphasis"><em>None</em></span>, the
contents of the buffer
are not changed.  In either case, if
<span class="emphasis"><em>exposures</em></span> is true, then one or
more exposure events are generated for regions of the rectangle that are
either visible or are being retained in backing store.
</p><p>

The group of image buffers allocated by a
<code class="function">CreateImageBuffers</code>
request can be destroyed with the following request:
</p><pre class="literallayout">
DestroyImageBuffers
     w_id          : WINDOW

     (Error: Window)
</pre><p>
The association between the buffer ID's and their corresponding
image buffers are deleted.  Any image buffers not selected for
display are de-allocated.  If the window is not multi-buffered,
the request is ignored.
</p></div><div class="chapter" title="Chapter 5. Attributes"><div class="titlepage"><div><div><h2 class="title"><a id="Attributes"></a>Chapter 5. Attributes</h2></div></div></div><p>
The following attributes will be associated with each window that
is multi-buffered:
</p><pre class="literallayout">
     displayed_buffer : CARD16
     update_action    : {Undefined,Background,Untouched,Copied}
     update_hint      : {Frequent,Intermittent,Static}
     window_mode      : {Mono,Stereo}
     buffers          : LISTofBUFFER
</pre><p>
<span class="emphasis"><em>displayed_buffer</em></span> is set to the
<span class="emphasis"><em>index</em></span> of the currently
displayed image buffer (for stereo windows, this will be
the index of the left buffer \- the index of the right buffer
is simply <span class="emphasis"><em>index</em></span>+1).
<span class="emphasis"><em>window_mode</em></span> indicates whether this window is
<span class="emphasis"><em>Mono</em></span> or <span class="emphasis"><em>Stereo</em></span>.
The ID for each buffer associated with the window is recorded
in the <span class="emphasis"><em>buffers</em></span> list.
The above attributes can be queried with the following request:
</p><pre class="literallayout">
GetMultiBufferAttributes
     w_id             : WINDOW
     =&gt;
     displayed_buffer : CARD16
     update_action    : {Undefined,Background,Untouched,Copied}
     update_hint      : {Frequent,Intermittent,Static}
     window_mode      : {Mono,Stereo}
     buffers          : LISTofBUFFER

     (Errors: Window, Access, Value)
</pre><p>
If the window is not multi-buffered, a <code class="function">Access</code> error
will be generated.
The only multi-buffer attribute that can be explicitly set
is <span class="emphasis"><em>update_hint</em></span>.  Rather than have a specific
request to set this attribute, a generic set request is provided to
allow for future expansion:
</p><pre class="literallayout">
SetMultiBufferAttributes
     w_id            : WINDOW
     value_mask      : BITMASK
     value_list      : LISTofVALUE

     (Errors: Window, Match, Value)
</pre><p>
If the window is not multi-buffered, a <code class="function">Match</code> error
will be generated.
The following attributes are maintained for each buffer of a
multi-buffered window:
</p><pre class="literallayout">
     window           : WINDOW
     event_mask       : SETofEVENT
     index            : CARD16
     side             : {Mono,Left,Right}
</pre><p>
<span class="emphasis"><em>window</em></span> indicates the window this buffer is
associated with.
<span class="emphasis"><em>event_mask</em></span> specifies which events, relevant to
buffers, will be sent back to the client via the associated buffer ID
(initially no events are selected).
<span class="emphasis"><em>index</em></span> is the list position (0, 1, ...) of the
buffer.
<span class="emphasis"><em>side</em></span> indicates whether this buffer is
associated with
the left side or right side of a stereo window.
For non-stereo windows, this attribute will be set to
<span class="emphasis"><em>Mono</em></span>.
These attributes can be queried with the following request:
</p><pre class="literallayout">
GetBufferAttributes
     buffer          : BUFFER
     =&gt;
     window           : WINDOW
     event_mask       : SETofEVENT
     index            : CARD16
     side             : {Mono,Left,Right}

     (Errors: Buffer, Value)
</pre><p>
The only buffer attribute that can be explicitly set
is <span class="emphasis"><em>event_mask</em></span>.
The only events that are valid are
<code class="function">Expose</code> and the new
<code class="function">ClobberNotify</code> and <code class="function">UpdateNotify</code>
event (see Events section below). 
A <code class="function">Value</code> error will be generated if an event not
selectable for a buffer is specified in an event mask.
Rather than have a specific request
to set this attribute, a generic set request is provided to
allow for future expansion:
</p><pre class="literallayout">
SetBufferAttributes
     buffer          : BUFFER
     value_mask      : BITMASK
     value_list      : LISTofVALUE

     (Errors: Buffer, Value)
</pre><p>
Clients may want to query the server about basic multi-buffer
and stereo capability on a per screen basis.  The following request
returns a large list of information
that would most likely be read once by Xlib for each screen, and used as a
data base for other Xlib queries:
</p><pre class="literallayout">
GetBufferInfo
     root            : WINDOW
     =&gt;
     info            : LISTofSCREEN_INFO
</pre><p>
Where <code class="function">SCREEN_INFO</code> and
<code class="function">BUFFER_INFO</code> are defined as:
</p><pre class="literallayout">
     SCREEN_INFO     : [ normal_info : LISTofBUFFER_INFO,
                         stereo_info : LISTofBUFFER_INFO ]

     BUFFER_INFO     : [ visual      : VISUALID,
                         max_buffers : CARD16,
                         depth       : CARD8 ]
</pre><p>
Information regarding multi-buffering of normal (mono) windows
is returned in the <span class="emphasis"><em>normal_info</em></span> list.
The <span class="emphasis"><em>stereo_info</em></span>
list contains information about stereo windows.
If the <span class="emphasis"><em>stereo_info</em></span> list is empty, stereo
windows are
not supported on the screen.  If
<span class="emphasis"><em>max_buffers</em></span> is zero,
the maximum number of buffers for the depth and visual is
a function of the size of the created window and current
memory limitations.
</p><p>
The following request returns the major and minor version numbers
of this extension:
</p><pre class="literallayout">
GetBufferVersion
     =&gt;
     major_number    : CARD8
     minor_number    : CARD8
</pre><p>
The version numbers are an escape hatch in case future revisions of
the protocol are necessary.  In general, the major version would
increment for incompatible changes, and the minor version would
increment for small upward compatible changes.  Barring changes, the
major version will be 1, and the minor version will be 1.
</p></div><div class="chapter" title="Chapter 6. Events"><div class="titlepage"><div><div><h2 class="title"><a id="Events"></a>Chapter 6. Events</h2></div></div></div><p>
All events normally generated for single-buffered
windows are also generated for multi-buffered windows.
Most of these events (ie: <code class="function">ConfigureNotify</code>) will
only be generated for the window and not for each buffer.
These events will return a window ID.
</p><p>
<code class="function">Expose</code> events will be generated for both the window
and any buffer affected.  When this event is generated for
a buffer, the same event structure will be used
but a buffer ID is returned instead of a window ID.
Clients, when processing these events, will know whether an
ID returned in an event structure is for a window or a buffer
by comparing the returned ID to the ones returned when the
window and buffer were created.
</p><p>
<code class="function">GraphicsExposure</code> and
<code class="function">NoExposure</code> are generated
using whatever ID is specified in the graphics operation.
If a window ID is specified, the event will contain the
window ID.  If a buffer ID is specified, the event will
contain the buffer ID.
</p><p>
In some implementations, moving a window
over a multi-buffered window may cause one or more of its buffers
to get overwritten or become unwritable.  To allow a
client drawing into one of these buffers the opportunity
to stop drawing until some portion of the buffer is
writable, the following event is added:
</p><pre class="literallayout">
ClobberNotify
     buffer         :  BUFFER
     state          : {Unclobbered,PartiallyClobbered,FullyClobbered}
</pre><p>
The <code class="function">ClobberNotify</code> event is reported to clients selecting
<span class="emphasis"><em>ClobberNotify</em></span> on a buffer.  When a buffer
that was fully
or partially clobbered becomes unclobbered, an event with
<span class="emphasis"><em>Unclobbered</em></span>
is generated.  When a buffer that was unclobbered becomes
partially clobbered, an event with
<span class="emphasis"><em>PartiallyClobbered</em></span>
is generated.  When a buffer that was unclobbered or
partially clobbered becomes fully clobbered, an event with
<span class="emphasis"><em>FullyClobbered</em></span> is generated.
</p><p>
<code class="function">ClobberNotify</code> events on a given buffer are
generated before any <code class="function">Expose</code> events on that buffer,
but it is not required that all <code class="function">ClobberNotify</code>
events on all buffers be generated before all
<code class="function">Expose</code> events on all buffers.
</p><p>
The ordering of <code class="function">ClobberNotify</code> events with respect
to <code class="function">VisibilityNotify</code> events is not constrained.
</p><p>
If multiple buffers were used as an image FIFO between an image
server and the X display server, then the FIFO manager would like
to know when a buffer that was previously displayed, has been
undisplayed and updated, as the side effect of a
<code class="function">DisplayImageBuffers</code>
request.  This allows the FIFO manager to load up a future frame as
soon as a buffer becomes available.  To support this,
the following event is added:
</p><pre class="literallayout">
UpdateNotify
     buffer         :  BUFFER
</pre><p>
The <code class="function">UpdateNotify</code> event is reported to clients selecting
<span class="emphasis"><em>UpdateNotify</em></span> on a buffer.  Whenever a buffer
becomes <span class="emphasis"><em>updated</em></span>
(e.g. its update action is performed as part of a
<code class="function">DisplayImageBuffers</code>
request), an <code class="function">UpdateNotify</code> event is generated.
</p></div><div class="chapter" title="Chapter 7. Errors"><div class="titlepage"><div><div><h2 class="title"><a id="Errors"></a>Chapter 7. Errors</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="sect1"><a href="#Buffer_2">Buffer</a></span></dt><dt><span class="sect1"><a href="#Double_Buffering_Normal_Windows">Double-Buffering Normal Windows</a></span></dt><dt><span class="sect1"><a href="#Multi_Buffering_Normal_Windows">Multi-Buffering Normal Windows</a></span></dt><dt><span class="sect1"><a href="#Stereo_Windows">Stereo Windows</a></span></dt><dt><span class="sect1"><a href="#Single_Buffered_Stereo_Windows">Single-Buffered Stereo Windows</a></span></dt><dt><span class="sect1"><a href="#Double_Buffering_Stereo_Windows">Double-Buffering Stereo Windows</a></span></dt><dt><span class="sect1"><a href="#Multi_Buffering_Stereo_Windows">Multi-Buffering Stereo Windows</a></span></dt><dt><span class="sect1"><a href="#Protocol_Encoding">Protocol Encoding</a></span></dt></dl></div><p>
The following error type has been added to support
this extension:
</p><div class="sect1" title="Buffer"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Buffer_2"></a>Buffer</h2></div></div></div><p>
A value for a BUFFER argument does not name a defined BUFFER.
</p></div><div class="sect1" title="Double-Buffering Normal Windows"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Double_Buffering_Normal_Windows"></a>Double-Buffering Normal Windows</h2></div></div></div><p>
The following pseudo-code fragment illustrates how to create and display
a double-buffered image:
</p><pre class="literallayout">
/*
 * Create a normal window
 */
CreateWindow( W, ... )

/*
 * Create two image buffers.  Assume after display, buffer
 * contents become "undefined".  Assume we will "frequently"
 * update the display.  Abort if we don't get two buffers,
 */
n = CreateImageBuffers( W, [B0,B1], Undefined, Frequent )
if (n != 2) &lt;abort&gt;

/*
 * Map window to the screen
 */
MapWindow( W )

/*
 * Draw images using alternate buffers, display every
 * 1/10 of a second.  Note we draw B1 first so it will
 * "pop" on the screen
 */
while animating
{
     &lt;draw picture using B1&gt;
     DisplayImageBuffers( [B1], 100, 0 )

     &lt;draw picture using B0&gt;
     DisplayImageBuffers( [B0], 100, 0 )
}

/*
 * Strip image buffers and leave window with
 * contents of last displayed image buffer.
 */
DestroyImageBuffers( W )
</pre></div><div class="sect1" title="Multi-Buffering Normal Windows"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Multi_Buffering_Normal_Windows"></a>Multi-Buffering Normal Windows</h2></div></div></div><p>
Multi-buffered images are also supported by these requests.
The following pseudo-code fragment illustrates how to create a
a multi-buffered image and cycle through the images to
simulate a movie loop:
</p><pre class="literallayout">
/*
 * Create a normal window
 */
CreateWindow( W, ... )

/*
 * Create 'N' image buffers.  Assume after display, buffer
 * contents are "untouched".  Assume we will "frequently"
 * update the display.  Abort if we don't get all the buffers.
 */
n = CreateImageBuffers( W, [B0,B1,...,B(N-1)], Untouched, Frequent )
if (n != N) &lt;abort&gt;

/*
 * Map window to screen
 */
MapWindow( W )

/*
 * Draw each frame of movie one per buffer
 */
foreach frame
     &lt;draw frame using B(i)&gt;

/*
 * Cycle through frames, one frame every 1/10 of a second.
 */
while animating
{
     foreach frame
          DisplayImageBuffers( [B(i)], 100, 0 )
}
</pre></div><div class="sect1" title="Stereo Windows"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Stereo_Windows"></a>Stereo Windows</h2></div></div></div><p>
<span class="emphasis"><em>How</em></span> stereo windows are supported on a server
is implementation
dependent.  A server may contain specialized hardware that allows
left and right images to be toggled at field or frame rates.  The
stereo affect may only be perceived with the aid of special
viewing glasses.  The <span class="emphasis"><em>display</em></span> of a
stereo picture should
be independent of how often the contents of the picture are
<span class="emphasis"><em>updated</em></span> by an application.  Double and
multi-buffering
of images should be possible regardless of whether the image
is displayed normally or in stereo.
</p><p>
To achieve this goal, a simple extension to normal windows
is suggested.  Stereo windows are just like normal windows
except the displayed image is made up of a left image
buffer and a right image buffer.  To create a stereo window,
a client makes the following request:
</p><pre class="literallayout">
CreateStereoWindow
     parent          : WINDOW
     w_id            : WINDOW
     left, right     : BUFFER
     depth           : CARD8
     visual          : VISUALID or CopyFromParent
     x, y            : INT16
     width, height   : INT16
     border_width    : INT16
     value_mask      : BITMASK
     value_list      : LISTofVALUE

     (Errors: Alloc, Color, Cursor, Match,
              Pixmap, Value, Window)
</pre><p>
This request, modeled after the <code class="function">CreateWindow</code> request,
adds just two new parameters: <span class="emphasis"><em>left</em></span> and
<span class="emphasis"><em>right</em></span>.
For stereo, it is essential that one can distinguish whether
a draw operation is to occur on the left image or right image.
While an internal mode could have been added to achieve this,
using two buffer ID's allows clients to simultaneously build up
the left and right components of a stereo image.  These
ID's always refer to (are an alias for) the left and right
image buffers that are currently <span class="emphasis"><em>displayed</em></span>.
</p><p>
Like normal windows, the window ID is used whenever a window
management operation is to be performed.  Window queries would
also return this window ID (eg: <code class="function">QueryTree</code>) as would most
events.  Like the window ID, the left and right buffer ID's
each have their own event mask.  They can be set and queried
using the <code class="function">Set/GetBufferAttributes</code> requests.
</p><p>
Using the window ID of a stereo window in a draw request
(eg: <code class="function">GetImage</code>) results in pixels that are
<span class="emphasis"><em>undefined</em></span>.
Possible semantics are that both left and right images get
drawn, or just a single side is operated on (existing applications
will have to be re-written to explicitly use the left and right
buffer ID's in order to successfully create, fetch, and store
stereo images).
</p><p>
Having an explicit <code class="function">CreateStereoWindow</code> request is helpful
in that a server implementation will know from the onset whether
a stereo window is desired and can return appropriate status
to the client if it cannot support this functionality.
</p><p>
Some hardware may support separate stereo and non-stereo modes,
perhaps with different vertical resolutions.  For example, the
vertical resolution in stereo mode may be half that of non-stereo
mode.  Selecting one mode or the other must be done through some
means outside of this extension (eg: by providing a separate
screen for each hardware display mode).  The screen attributes
(ie: x/y resolution) for a screen that supports normal windows,
may differ from a screen that supports stereo windows;
however, all windows, regardless of type, displayed on the
same screen must have the same screen attributes
(ie: pixel aspect ratio).
</p><p>
If a screen that supports stereo windows also supports
normal windows, then the images presented to the left and
right eyes for normal windows should be the same
(ie: have no stereo offset).
</p></div><div class="sect1" title="Single-Buffered Stereo Windows"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Single_Buffered_Stereo_Windows"></a>Single-Buffered Stereo Windows</h2></div></div></div><p>
The following shows how to create and display a single-buffered
stereo image:
</p><pre class="literallayout">
/*
 * Create the stereo window, map it the screen,
 * and draw the left and right images
 */
CreateStereoWindow( W, L, R, ... )

MapWindow( W )

&lt;draw picture using L,R&gt;
</pre></div><div class="sect1" title="Double-Buffering Stereo Windows"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Double_Buffering_Stereo_Windows"></a>Double-Buffering Stereo Windows</h2></div></div></div><p>
Additional image buffers may be added to a stereo window
to allow double or multi-buffering of stereo images.
Simply use the the <code class="function">CreateImageBuffers</code> request.
Even numbered buffers (0,2,...) will be left buffers.
Odd numbered buffers (1,3,...) will be right buffers.
Displayable stereo images are formed by consecutive
left/right pairs of image buffers.  For example,
(buffer[0],buffer[1]) form the first displayable
stereo image; (buffer[2],buffer[3]) the next;
and so on.
</p><p>
The <code class="function">CreateImageBuffers</code> request will only create
pairs of left and right image buffers for stereo windows.
By always pairing left and right image
buffers together, implementations might be able to
perform some type of optimization.  If an odd number
of buffers is specified, a <code class="function">Value</code> error is generated.
All the rules mentioned at the start of this proposal
still apply to the image buffers supported by a stereo window.
</p><p>
To display a image buffer pair of a multi-buffered stereo image,
either the left buffer ID or right buffer ID may be specified in a
<code class="function">DisplayImageBuffers</code> request, but not both.
</p><p>
To double-buffer a stereo window:
</p><pre class="literallayout">
/*
 * Create stereo window and map it to the screen
 */
CreateStereoWindow( W, L, R, ... )

/*
 * Create two pairs of image buffers.  Assume after display,
 * buffer contents become "undefined".  Assume we will "frequently"
 * update the display.  Abort if we did get all the buffers.
 */
n = CreateImageBuffers( W, [L0,R0,L1,R1], Undefined, Frequently )
if (n != 4) &lt;abort&gt;

/*
 * Map window to the screen
 */
MapWindow( W )

/*
 * Draw images using alternate buffers,
 * display every 1/10 of a second.
 */
while animating
{
     &lt;draw picture using L1,R1&gt;
     DisplayImageBuffers( [L1], 100, 0 )

     &lt;draw picture using L0,R0&gt;
     DisplayImageBuffers( [L0], 100, 0 )
}
</pre></div><div class="sect1" title="Multi-Buffering Stereo Windows"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Multi_Buffering_Stereo_Windows"></a>Multi-Buffering Stereo Windows</h2></div></div></div><p>
To cycle through <span class="emphasis"><em>N</em></span> stereo images:
</p><pre class="literallayout">
/*
 * Create stereo window
 */
CreateStereoWindow( W, L, R, ... )

/*
 * Create N pairs of image buffers.  Assume after display,
 * buffer contents are "untouched".  Assume we will "frequently"
 * update the display.  Abort if we don't get all the buffers.
 */
n = CreateImageBuffers( W, [L0,R0,...,L(N-1),R(N-1)], Untouched, Frequently )
if (n != N*2) &lt;abort&gt;

/*
 * Map window to screen
 */
MapWindow( W )

/*
 * Draw the left and right halves of each image
 */
foreach stereo image
     &lt;draw picture using L(i),R(i)&gt;

/*
 * Cycle through images every 1/10 of a second
 */
while animating
{
     foreach stereo image
          DisplayImageBuffers( [L(i)], 100, 0 )
}
</pre></div><div class="sect1" title="Protocol Encoding"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Protocol_Encoding"></a>Protocol Encoding</h2></div></div></div><p>
The official name of this extension is "Multi-Buffering".
When this string passed to <code class="function">QueryExtension</code> the
information returned should be interpreted as follows:
</p><div class="variablelist"><table border="0"><col align="left" valign="top" /><tbody><tr><td><p><span class="term">major-opcode</span></p></td><td><p>
Specifies the major opcode of this extension.
The first byte of each extension request should
specify this value.
      </p></td></tr><tr><td><p><span class="term">first-event</span></p></td><td><p>
Specifies the code that will be returned when
<code class="function">ClobberNotify</code> events are generated.
      </p></td></tr><tr><td><p><span class="term">first-error</span></p></td><td><p>
Specifies the code that will be returned when
<code class="function">Buffer</code> errors are generated.
      </p></td></tr></tbody></table></div><p>
The following sections describe the protocol
encoding for this extension.
</p></div></div><div class="chapter" title="Chapter 8. TYPES"><div class="titlepage"><div><div><h2 class="title"><a id="TYPES"></a>Chapter 8. TYPES</h2></div></div></div><pre class="literallayout">
BUFFER_INFO

4       VISUALID     visual
2       CARD16       max-buffers
1       CARD8        depth
1                    unused
</pre><pre class="literallayout">
SETofBUFFER_EVENT

        #x00008000   Exposure
        #x02000000   ClobberNotify
        #x04000000   UpdateNotify
</pre></div><div class="chapter" title="Chapter 9. EVENTS"><div class="titlepage"><div><div><h2 class="title"><a id="EVENTS_2"></a>Chapter 9. EVENTS</h2></div></div></div><pre class="literallayout">
<code class="function">ClobberNotify</code>
1       see <span class="emphasis"><em>first-event</em></span> code
1                                unused
2       CARD16                   sequence number
4       BUFFER                   buffer
1                                state
        0 Unclobbered
        1 PartiallyClobbered
        2 FullyClobbered
23                                unused
</pre><pre class="literallayout">
<code class="function">UpdateNotify</code>
1 <span class="emphasis"><em>first-event</em></span>+1 code
1                       unused
2      CARD16           sequence number
4      BUFFER           buffer
24                      unused
</pre></div><div class="chapter" title="Chapter 10. ERRORS"><div class="titlepage"><div><div><h2 class="title"><a id="ERRORS_2"></a>Chapter 10. ERRORS</h2></div></div></div><pre class="literallayout">
<code class="function">Buffer</code>
1     0                 Error
1     see <span class="emphasis"><em>first-error</em></span> code
2     CARD16                 sequence number
4     CARD32                 bad resource id
2     CARD16                 minor-opcode
1     CARD8                  major-opcode
21                           unused
</pre></div><div class="chapter" title="Chapter 11. REQUESTS"><div class="titlepage"><div><div><h2 class="title"><a id="Requests"></a>Chapter 11. REQUESTS</h2></div></div></div><pre class="literallayout">
<code class="function">GetBufferVersion</code>
1       see <span class="emphasis"><em>major-opcode</em></span>         major-opcode
1       0                  minor-opcode
2       1                  request length
-&gt;
1       1                  Reply
1                          unused
2       CARD16             sequencenumber
4       0                  reply length
1       CARD8              majorversion number
1       CARD8              minorversion number
22                         unused


<code class="function">CreateImageBuffers</code>

1        see <span class="emphasis"><em>major-opcode</em></span>  major-opcode
1        1                 minor-opcode
2        3+n               requestlength
4        WINDOW            wid
1                          update-action
         0 Undefined
         1 Background
         2 Untouched
         3 Copied
1                          update-hint
         0 Frequent
         1 Intermittent
         2 Static
2                          unused
4n     LISTofBUFFER        buffer-list
-&gt;
1        1                 Reply
1                          unused
2      CARD16              sequencenumber
4      0                   reply length
2      CARD16              number-buffers
22                         unused


<code class="function">DestroyImageBuffers</code>

1        see <span class="emphasis"><em>major-opcode</em></span>  major-opcode
1       2                  minor-opcode
2       2                  request length
4       WINDOW             wid


<code class="function">DisplayImageBuffers</code>


1        see <span class="emphasis"><em>major-opcode</em></span>  major-opcode
2        2+n               requestlength
2        CARD16            min-delay
2        CARD16            max-delay
4n       LISTofBUFFER      buffer-list


<code class="function">SetMultiBufferAttributes</code>

1        see <span class="emphasis"><em>major-opcode</em></span>  major-opcode
1        4                 minor-opcode
2        3+n               requestlength
4        WINDOW            wid
4        BITMASK           value-mask (has n bits set to 1)
         #x00000001        update-hint
4n        LISTofVALUE      value-list
VALUEs
1                          update-hint
         0 Frequent
         1 Intermittent
         2 Static


<code class="function">GetMultiBufferAttributes</code>

1        see <span class="emphasis"><em>major-opcode</em></span>  major-opcode
1        5                 minor-opcode
2        2                 request length
4        WINDOW            wid
®
1        1                 Reply
1                          unused
2        CARD16            sequencenumber
4        n                 reply length
2        CARD16            displayed-buffer
1                          update-action
         0 Undefined
         1 Background
         2 Untouched
         3 Copied
1                          update-hint
         0 Frequent
         1 Intermittent
         2 Static
1                          window-mode
         0 Mono
         1 Stereo
19                         unused
4n       LISTofBUFFER      buffer list


<code class="function">SetBufferAttributes</code>

1        see <span class="emphasis"><em>major-opcode</em></span>  major-opcode
1        6                 minor-opcode
2        3+n               requestlength
4        BUFFER            buffer
4        BITMASK           value-mask (has n bits set to 1)
         #x00000001        event-mask
4n       LISTofVALUE       value-list
VALUEs
4        SETofBUFFER_EVENT event-mask

<code class="function">GetBufferAttributes</code>

1        see <span class="emphasis"><em>major-opcode</em></span>  major-opcode
1        7                 minor-opcode
2        2                 request length
4        BUFFER            buffer
-&gt;
1        1                 Reply
1                          unused
2        CARD16            sequencenumber
4        0                 reply length
4        WINDOW            wid
4        SETofBUFFER_EVENT event-mask
2        CARD16            index
         1 side
         0 Mono
         1 Left
         2 Right
13                         unused

<code class="function">GetBufferInfo</code>

1        see <span class="emphasis"><em>major-opcode</em></span>  major-opcode
1        8                   minor-opcode
2        2                   request length
4        WINDOW              root
®
1        1                   Reply
1                            unused
2        CARD16              sequencenumber
4        2(n+m)              replylength
2        n                   number BUFFER_INFO in normal-info
2        m                   number BUFFER_INFO in stereo-info
20                           unused
8n       LISTofBUFFER_INFO   normal-info
8m       LISTofBUFFER_INFO   stereo-info

<code class="function">CreateStereoWindow</code>

1        see <span class="emphasis"><em>major-opcode</em></span>  major-opcode
1        9 minor-opcode
2        11+n                    requestlength
3                                unused
1        CARD8                   depth
4        WINDOW                  wid
4        WINDOW                  parent
4        BUFFER                  left
4        BUFFER                  right
2        INT16                   x
2        INT16                   y
2        CARD16                  width
2        CARD16                  height
2        CARD16                  border-width
2                                class
         0 CopyFromParent
         1 InputOutput
         2 InputOnly
4        VISUALID                visual
         0 CopyFromParent
4        BITMASK                 value-mask (has n bits set to 1)
         encodings are the same
         as for CreateWindow
4n       LISTofVALUE             value-list
         encodings are the same
         as for CreateWindow


<code class="function">ClearImageBufferArea</code>

1 see major-opcode major-opcode
1        10                      minor-opcode
2        5                       request length
4        WINDOW                  buffer
2        INT16                   x
2        INT16                   y
2        CARD16                  width
2        CARD16                  height
3                                unused
1        BOOL                    exposures

</pre></div></div></body></html>
x11proto-xext-dev 7.3.0-1~precise2 / usr / share / doc / x11proto-xext-dev / multibuf.html
