/usr/share/doc/x11proto-xext-dev/dbe.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>Double Buffer Extension Protocol</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.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;
}

/*
 * For documentation having multiple licenses, the copyright and legalnotice
 * elements sequence cannot instantiated multiple times.
 * The copyright notice and license text are therefore coded inside a legalnotice
 * element. The role attribute on the paragraph is used to allow styling of the
 * copyright notice text which should not be italicized.
 */
p.multiLicensing {
  font-style: normal;
  font-size: medium;
}

/*
 * 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"><div class="titlepage"><div><div><h1 class="title"><a id="dbe"></a>Double Buffer Extension Protocol</h1></div><div><h2 class="subtitle">X Consortium Standard</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Ian</span> <span class="surname">Elliott</span></h3><div class="affiliation"><span class="orgname">Hewlett-Packard Company<br /></span></div></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">David</span> <span class="othername">P.</span> <span class="surname">Wiggins</span></h3><div class="affiliation"><span class="orgname">X Consortium<br /></span></div></div></div></div><div><p class="releaseinfo">X Version 11, Release 7.7</p></div><div><p class="releaseinfo">Version 1.0</p></div><div><p class="copyright">Copyright © 1989, 1992, 1993, 1994 X Consortium, Inc.</p></div><div><p class="copyright">Copyright © 1989 Digital Equipment Corporation</p></div><div><p class="copyright">Copyright © 1992 Intergraph Corporation</p></div><div><p class="copyright">Copyright © 1993 Silicon Graphics, Inc.</p></div><div><p class="copyright">Copyright © 1994 Hewlett-Packard Company</p></div><div><div class="legalnotice"><a id="idp50382560"></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, 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.
</p></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><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="#Concepts">3. Concepts</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Window_Management_Operations">Window Management Operations</a></span></dt><dt><span class="sect1"><a href="#Complex_Swap_Actions">Complex Swap Actions</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Requests">4. Requests</a></span></dt><dd><dl><dt><span class="sect1"><a href="#DBEGetVersion">DBEGetVersion</a></span></dt><dt><span class="sect1"><a href="#DBEGetVisualInfo">DBEGetVisualInfo</a></span></dt><dt><span class="sect1"><a href="#DBEAllocateBackBufferName">DBEAllocateBackBufferName</a></span></dt><dt><span class="sect1"><a href="#DBEDeallocateBackBufferName">DBEDeallocateBackBufferName</a></span></dt><dt><span class="sect1"><a href="#DBESwapBuffers">DBESwapBuffers</a></span></dt><dt><span class="sect1"><a href="#DBEBeginIdiom">DBEBeginIdiom</a></span></dt><dt><span class="sect1"><a href="#DBEEndIdiom">DBEEndIdiom</a></span></dt><dt><span class="sect1"><a href="#DBEGetBackBufferAttributes">DBEGetBackBufferAttributes</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Encoding">5. Encoding</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Type">Type</a></span></dt><dt><span class="sect1"><a href="#Error">Error</a></span></dt><dt><span class="sect1"><a href="#Request">Request</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Acknowledgements">6. Acknowledgements</a></span></dt><dt><span class="chapter"><a href="#References">7. References</a></span></dt></dl></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Introduction"></a>Chapter 1. Introduction</h1></div></div></div><p>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.
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Goals"></a>Chapter 2. Goals</h1></div></div></div><p>This extension should enable clients to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Allocate and deallocate double-buffering for a window.</p></li><li class="listitem"><p>
Draw to and read from the front and back buffers associated with a window.
    </p></li><li class="listitem"><p>Swap the front and back buffers associated with a window.</p></li><li class="listitem"><p>
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).
    </p></li><li class="listitem"><p>
Request that the front and back buffers associated with multiple
double-buffered windows be swapped simultaneously.
    </p></li></ul></div><p>
In addition, the extension should:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Allow multiple clients to use double-buffering on the same window.</p></li><li class="listitem"><p>
Support a range of implementation methods that can capitalize on existing
hardware features.
    </p></li><li class="listitem"><p>Add no new event types.</p></li><li class="listitem"><p>
Be reasonably easy to integrate with a variety of direct graphics hardware
access (DGHA) architectures.
    </p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Concepts"></a>Chapter 3. Concepts</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Window_Management_Operations">Window Management Operations</a></span></dt><dt><span class="sect1"><a href="#Complex_Swap_Actions">Complex Swap Actions</a></span></dt></dl></div><p>
Normal windows are created using the core <code class="function">CreateWindow</code>
request, which allocates a set of window attributes and, for InputOutput
windows, a front buffer, into which an image can be drawn. The contents of
this buffer will be displayed when the window is visible.
</p><p>
This extension enables applications to use double-buffering with a window.
This involves creating a second buffer, called a back buffer, and associating
one or more back buffer names (XIDs) with the window for use when referring to
(that is, drawing to or reading from) the window's back buffer. The back
buffer name is a DRAWABLE of type BACKBUFFER.
</p><p>
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.
</p><p>
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.
</p><p>
In general, both the front and back buffers are treated the same. In
particular, here are some important characteristics:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Only one buffer per window can be visible at a time (the front buffer).
    </p></li><li class="listitem"><p>
Both buffers associated with a window have the same visual type, depth,
width, height, and shape as the window.
    </p></li><li class="listitem"><p>
Both buffers associated with a window are "visible" (or "obscured") in
the same way. When an Expose event is generated for a window, both
buffers should be considered to be damaged in the exposed area. Damage
that occurs to either buffer will result in an Expose event on the window.
When a double-buffered window is exposed, both buffers are tiled with the
window background, exactly as stated by the core protocol. Even though
the back buffer is not visible, terms such as obscure apply to the back
buffer as well as to the front buffer.
    </p></li><li class="listitem"><p>
It is acceptable at any time to pass a BACKBUFFER in any
request, notably any core or extension drawing request, that expects
a DRAWABLE. This enables an application to draw directly into
BACKBUFFERs in the same fashion as it would draw into any other
DRAWABLE.
    </p></li><li class="listitem"><p>
It is an error (Window) to pass a BACKBUFFER in a core request that
expects a Window.
    </p></li><li class="listitem"><p>
A BACKBUFFER will never be sent by core X in a reply, event, or error
where a Window is specified.
    </p></li><li class="listitem"><p>
If core X11 backing-store and save-under applies to a double-buffered
window, it applies to both buffers equally.
    </p></li><li class="listitem"><p>
If the core <code class="function">ClearArea</code> request is executed on a
double-buffered window, the same area in both the front and back buffers
is cleared.
    </p></li></ul></div><p>
The effect of passing a window to a request that accepts a DRAWABLE is
unchanged by this extension. The window and front buffer are synonomous with
each other. This includes obeying the <code class="function">GetImage</code> semantics
and the subwindow-mode semantics if a core graphics context is involved.
Regardless of whether the window was explicitly passed in a
<code class="function">GetImage</code> request, or implicitly referenced (that is,
one of the windo's ancestors was passed in the request), the front (that is,
visible) buffer is always referenced. Thus, DBE-naive screen dump clients will
always get the front buffer. <code class="function">GetImage</code> on a back buffer
returns undefined image contents for any obscured regions of the back buffer
that fall within the image.
</p><p>
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
<code class="function">ClipByChildren</code>. If an
ancestor of a double-buffered window is drawn to with a core GC having a
subwindow-mode of <code class="function">IncludeInferiors</code>, 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
<code class="function">IncludeInferiors</code> drawing touched.
</p><p>
DBE adds no new events. DBE does not extend the semantics of any existing
events with the exception of adding a new DRAWABLE type called BACKBUFFER. If
events, replies, or errors that contain a DRAWABLE (for example,
<code class="function">GraphicsExpose</code>) are generated in response to a request,
the DRAWABLE returned will be the one specified in the request.
</p><p>
DBE advertises which visuals support double-buffering.
</p><p>
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.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Window_Management_Operations"></a>Window Management Operations</h2></div></div></div><p>
The basic philosophy of DBE is that both buffers are treated the same by core
X window management operations.
</p><p>
When the core <code class="function">DestroyWindow</code> 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.
</p><p>
If the core <code class="function">ConfigureWindow</code> request changes the size of
a window, both buffers assume the new size. If the windo's size increases,
the effect on the buffers depends on whether the implementation honors bit
gravity for buffers. If bit gravity is implemented, then the contents of
both buffers are moved in accordance with the windo's bit gravity (see the
core <code class="function">ConfigureWindow</code> 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, <code class="function">Expose</code> events are generated
for the region that is tiled with the window background.
</p><p>
If the core <code class="function">GetGeometry</code> request is executed on a
BACKBUFFER, the returned x, y, and border-width will be zero.
</p><p>
If the Shape extension <code class="function">ShapeRectangles</code>,
<code class="function">ShapeMask</code>,
<code class="function">ShapeCombine</code>, or
<code class="function">ShapeOffset</code>
request is executed on a double-buffered window, both buffers are reshaped
to match the new window shape. The region difference is the following:
</p><div class="literallayout"><p><br />
   D = newshape - oldshape<br />
</p></div><p>
It is tiled with the window background in both buffers, and
<code class="function">Expose</code> events are generated for D.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Complex_Swap_Actions"></a>Complex Swap Actions</h2></div></div></div><p>
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.
</p><p>
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:
<code class="function">DBEBeginIdiom</code> and
<code class="function">DBEEndIdiom</code>. Unless this begin-end pair
surrounds the idiom, it may not be recognized by a given implementation, and
performance will suffer.
</p><p>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>DBEBeginIdiom request.</p></li><li class="listitem"><p>
<code class="function">DBESwapBuffers</code> request with XIDs for two windows, each of which uses
a swap action of Untouched.
    </p></li><li class="listitem"><p>
Core X PolyFillRectangle request to the back buffer of one window.
    </p></li><li class="listitem"><p>
Core X PolyFillRectangle request to the back buffer of the other window.
    </p></li><li class="listitem"><p>DBEEndIdiom request.</p></li></ul></div><p>
The <code class="function">DBEBeginIdiom</code> and <code class="function">DBEEndIdiom</code>
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.
</p><p>
An idiom need not include a <code class="function">DBESwapBuffers</code> request. For
example, if a swap action of Copied is desired, but only some of the planes
should be copied, a core X
<code class="function">CopyArea</code> request may be used instead of
<code class="function">DBESwapBuffers</code>.
If <code class="function">DBESwapBuffers</code> is included in an idiom, it should
immediately follow the <code class="function">DBEBeginIdiom</code> request. Also, when
the <code class="function">DBESwapBuffers</code> is included in an idiom, that
request's swap action will still be valid, and if the swap action might
overlap with another request, then the final result of the idiom must be as if
the separate requests were executed serially. For example, if the specified
swap action is Untouched, and if a <code class="function">PolyFillRectangle</code>
using a client clip rectangle is done to the windo's back buffer after the
<code class="function">DBESwapBuffers</code> 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.
</p><p>
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
<code class="function">DBEBeginIdiom</code> request, the idiom requests, and
<code class="function">DBEEndIdiom</code> request. Usage of these functions will
ensure best possible performance across a wide variety of implementations.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Requests"></a>Chapter 4. Requests</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#DBEGetVersion">DBEGetVersion</a></span></dt><dt><span class="sect1"><a href="#DBEGetVisualInfo">DBEGetVisualInfo</a></span></dt><dt><span class="sect1"><a href="#DBEAllocateBackBufferName">DBEAllocateBackBufferName</a></span></dt><dt><span class="sect1"><a href="#DBEDeallocateBackBufferName">DBEDeallocateBackBufferName</a></span></dt><dt><span class="sect1"><a href="#DBESwapBuffers">DBESwapBuffers</a></span></dt><dt><span class="sect1"><a href="#DBEBeginIdiom">DBEBeginIdiom</a></span></dt><dt><span class="sect1"><a href="#DBEEndIdiom">DBEEndIdiom</a></span></dt><dt><span class="sect1"><a href="#DBEGetBackBufferAttributes">DBEGetBackBufferAttributes</a></span></dt></dl></div><p>The DBE defines the following requests.</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="DBEGetVersion"></a>DBEGetVersion</h2></div></div></div><p>
This request returns the major and minor version numbers of this extension.
</p><p>DBEGetVersion</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left">client-major-version</td><td align="left">CARD8</td></tr><tr><td align="left">client-minor-version </td><td align="left">CARD8</td></tr><tr><td align="left">=&gt;</td><td align="left"> </td></tr><tr><td align="left">server-major-version </td><td align="left">CARD8</td></tr><tr><td align="left">server-minor-version </td><td align="left">CARD8</td></tr></tbody></table></div><p>
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).
</p><p>
The DBE client must issue a DBEGetVersion request before any other double
buffering request in order to negotiate a compatible protocol version;
otherwise, the client will get undefined behavior (DBE may or may not work).
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="DBEGetVisualInfo"></a>DBEGetVisualInfo</h2></div></div></div><p>
This request returns information about which visuals support double buffering.
</p><p>DBEGetVisualInfo</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left">screen-specifiers</td><td align="left">LISTofDRAWABLE</td></tr><tr><td align="left">=&gt;</td><td align="left"> </td></tr><tr><td align="left">visinfo</td><td align="left">LISTofSCREENVISINFO</td></tr></tbody></table></div><p>where:</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left">SCREENVISINFO</td><td align="left">LISTofVISINFO</td></tr><tr><td align="left">VISINFO</td><td align="left">[ visual: VISUALID</td></tr><tr><td align="left"> </td><td align="left">depth: CARD8</td></tr><tr><td align="left"> </td><td align="left">perflevel: CARD8 ]</td></tr></tbody></table></div><p>Errors: Drawable</p><p>
All of the values passed in screen-specifiers must be valid DRAWABLEs (or a
<code class="function">Drawable</code> 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.
</p><p>
If the list of screen-specifiers is empty, information for all screens is
returned, starting with screen zero.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="DBEAllocateBackBufferName"></a>DBEAllocateBackBufferName</h2></div></div></div><p>
This request allocates a drawable ID used to refer to the back buffer of a
window.
</p><p>DBEAllocateBackBufferName</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left">window</td><td align="left">WINDOW</td></tr><tr><td align="left">back-buffer-name</td><td align="left">BACKBUFFER</td></tr><tr><td align="left">swap-action-hint</td><td align="left">SWAPACTION </td></tr></tbody></table></div><p>
Errors: Alloc, Value, IDChoice, Match, Window
</p><p>
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 <code class="function">DBESwapBuffers</code>
requests. The swap-action-hint must have one of the values specified for type
SWAPACTION (or a Value error results). See the description of the
<code class="function">DBESwapBuffers</code> request for a complete discussion of
swap actions and the SWAPACTION type.
</p><p>
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.
</p><p>
The window passed into the request must be a valid WINDOW (or a Window error
results). The window passed into the request must be an InputOutput window (or
a Match error results). The visual of the window must be in the list returned
by <code class="function">DBEGetVisualInfo</code> (or a Match error results). The
back-buffer-name must be in the range assigned to the client, and must not
already be in use (or an IDChoice error results). If the server cannot
allocate all resources associated with turning on double-buffering for the
window, an Alloc error results, the windo's double-buffer status (whether it
is already double-buffered or not) remains unchanged, and the
back-buffer-name is freed.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="DBEDeallocateBackBufferName"></a>DBEDeallocateBackBufferName</h2></div></div></div><p>
This request frees a drawable ID that was obtained by
<code class="function">DBEAllocateBackBufferName</code>.
</p><p>DBEDeallocateBackBufferName</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left">back-buffer-name</td><td align="left">BACKBUFFER</td></tr></tbody></table></div><p>Errors: Buffer</p><p>
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.
</p><p>
The back-buffer-name must be a valid BACKBUFFER associated with a window (or
a Buffer error results).
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="DBESwapBuffers"></a>DBESwapBuffers</h2></div></div></div><p>
This request swaps the buffers for all windows listed, applying the
appropriate swap action for each window.
</p><p><code class="function">DBESwapBuffers</code></p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left">windows</td><td align="left">LISTofSWAPINFO</td></tr></tbody></table></div><p>where:</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left">SWAPINFO</td><td align="left">[ window: WINDOW</td></tr><tr><td align="left"> </td><td align="left">swap-action: SWAPACTION ]</td></tr><tr><td align="left">SWAPACTION</td><td align="left">{ Undefined, Background, Untouched, Copied }</td></tr></tbody></table></div><p>Errors: Match, Window, Value</p><p>
Each window passed into the request must be a valid WINDOW (or a
<code class="function">Window</code> error results). Each window passed into the
request must be a double-buffered window (or a <code class="function">Match</code>
error results). Each window passed into the request must only be listed
once (or a <code class="function">Match</code> error results). Each swap-action in
the list must have one of the values specified for type SWAPACTION (or a
<code class="function">Value</code> error results). If an error results, none of
the valid double-buffered windows will have their buffers swapped.
</p><p>
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:
</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">Undefined</span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">Background</span></p></td><td><p>
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.
    </p></td></tr><tr><td><p><span class="term">Untouched</span></p></td><td><p>
The unobscured region of the new back buffer will be unmodified by the swap.
    </p></td></tr><tr><td><p><span class="term">Copied</span></p></td><td><p>
The unobscured region of the new back buffer will be the contents of the
old back buffer.
    </p></td></tr></tbody></table></div><p>
If <code class="function">DBESwapBuffers</code> is included in a "swap and clear"
type of idiom, it must immediately follow the
<code class="function">DBEBeginIdiom</code> request.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="DBEBeginIdiom"></a>DBEBeginIdiom</h2></div></div></div><p>
This request informs the server that a complex swap will immediately follow
this request.
</p><p><code class="function">DBEBeginIdiom</code></p><p>
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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="DBEEndIdiom"></a>DBEEndIdiom</h2></div></div></div><p>
This request informs the server that a complex swap has concluded.
</p><p><code class="function">DBEEndIdiom</code></p><p>
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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="DBEGetBackBufferAttributes"></a>DBEGetBackBufferAttributes</h2></div></div></div><p>This request returns information about a back buffer.</p><p><code class="function">DBEGetBackBufferAttributes</code></p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left">back-buffer-name</td><td align="left">BACKBUFFER</td></tr><tr><td align="left">=&gt;</td><td align="left"> </td></tr><tr><td align="left">attributes</td><td align="left">BUFFER_ATTRIBUTES</td></tr></tbody></table></div><p>where:</p><p>BUFFER_ATTRIBUTES: [ window: WINDOW ]</p><p>
If back-buffer-name is a valid BACKBUFFER, the window field of the
attributes in the reply will be the window which has the back buffer that
back-buffer-name refers to. If back-buffer-name is not a valid BACKBUFFER,
the window field of the attributes in the reply will be None.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Encoding"></a>Chapter 5. Encoding</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Type">Type</a></span></dt><dt><span class="sect1"><a href="#Error">Error</a></span></dt><dt><span class="sect1"><a href="#Request">Request</a></span></dt></dl></div><p>
Please refer to the X11 Protocol Encoding document as this section uses
syntactic conventions and data types established there.
</p><p>The name of this extension is "DOUBLE-BUFFER".</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Type"></a>Type</h2></div></div></div><p>The following new types are used by the extension.
</p><p>BACKBUFFER: XID</p><p>SWAPACTION</p><pre class="literallayout">
#x00  Undefined
#x01  Background
#x02  Untouched
#x03  Copied
</pre><p>SWAPINFO</p><pre class="literallayout">
4     WINDOW                 window
1     SWAPACTION             swap action
3                            unused
</pre><pre class="literallayout">
VISINFO
4     VISUALID                visual
1     CARD8                   depth
1     CARD8                   perflevel
2                             unused

SCREENVISINFO
4     CARD32                  n, number in list
8n    LISTofVISINFO           n VISINFOs

BUFFER_ATTRIBUTES
4     WINDOW                 window
</pre></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Error"></a>Error</h2></div></div></div><p><code class="function">Buffer</code></p><pre class="literallayout">
1     0                       error
1     error base + 0          code
2     CARD16                  sequence number
4     CARD32                  bad buffer
2     CARD16                  minor-opcode
1     CARD8                   major-opcode
21                            unused
</pre></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Request"></a>Request</h2></div></div></div><pre class="literallayout">
DBEGetVersion
1     CARD8                  major-opcode
1     0                      minor-opcode
2     2                      request length
1     CARD8                  client-major-version
1     CARD8                  client-minor-version
2                            unused
=&gt;
1                            unused
2     CARD16                 sequence number
4     0                      reply length
1     CARD8                  server-major-version
1     CARD8                  server-minor-version
22                           unused
</pre><p><code class="function">DBEAllocateBackBufferName</code></p><pre class="literallayout">
1     CARD8                  major-opcode
1     1                      minor-opcode
2     4                      request length
4     WINDOW                 window
4     BACKBUFFER             back buffer name
1     SWAPACTION             swap action hint
3                            unused
</pre><p><code class="function">DBEDeallocateBackBufferName</code></p><pre class="literallayout">
1     CARD8                  major-opcode
1     2                      minor-opcode
2     2                      request length
4     BACKBUFFER             back buffer name
</pre><p><code class="function">DBESwapBuffers</code></p><pre class="literallayout">
1     CARD8                   major-opcode
1     3                       minor-opcode
2     2+2n                    request length
4     CARD32                  n, number of window/swap action pairs in list
8n    LISTofSWAPINFO          window/swap action pairs
</pre><p><code class="function">DBEBeginIdiom</code></p><pre class="literallayout">
1     CARD8                   major-opcode
1     4                       minor-opcode
2     1                       request length
</pre><p><code class="function">DBEEndIdiom</code></p><pre class="literallayout">
1     CARD8                   major-opcode
1     5                       minor-opcode
2     1                       request length
</pre><p><code class="function">DBEGetVisualInfo</code></p><pre class="literallayout">
1     CARD8                   major-opcode
1     6                       minor-opcode
2     2+n                     request length
4     CARD32                  n, number of screen specifiers in list
4n    LISTofDRAWABLE          n screen specifiers
=&gt;
1     1                       Reply
1                             unused
2     CARD16                  sequence number
4     CARD32                  reply length
4     CARD32                  m, number of SCREENVISINFOs in list
20                            unused
4j    LISTofSCREENVISINFO     m SCREENVISINFOs
</pre><p><code class="function">DBEGetBackBufferAttributes</code></p><pre class="literallayout">
1     CARD8                   major-opcode
1     7                       minor-opcode
2     2                       request length
4     BACKBUFFER              back-buffer-name
=&gt;
1                             unused
2     CARD16                  sequence number
4     0                       reply length
4     BUFFER_ATTRIBUTES       attributes
20                            unused
</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Acknowledgements"></a>Chapter 6. Acknowledgements</h1></div></div></div><p>
We wish to thank the following individuals who have contributed their time
and talent toward shaping the DBE specification:
</p><p>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.
</p><p>
Mark provided the impetus to start the DBE project. Ian wrote the first
draft of the specification. David served as architect.
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="References"></a>Chapter 7. References</h1></div></div></div><p>
Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension
Specification Version 3.3."
</p><p>Tim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins,
"X Synchronization Extension Version 3.0."
</p></div></div></body></html>
x11proto-xext-dev 7.3.0-1 / usr / share / doc / x11proto-xext-dev / dbe.html
