/usr/share/doc/libxext-dev/dbelib.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 Library</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="dbelib"></a>Double Buffer Extension Library</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">Elliot</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, Inc<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 X Consortium Inc, Digital Equipment Corporation</p></div><div><p class="copyright">Copyright © 1992 X Consortium Inc, Intergraph Corporation</p></div><div><p class="copyright">Copyright © 1993 X Consortium Inc, Silicon Graphics, Inc.</p></div><div><p class="copyright">Copyright © 1994, 1995 X Consortium Inc, Hewlett-Packard Company</p></div><div><div class="legalnotice"><a id="idp36341776"></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="#C_Language_Binding">4. C Language Binding</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Types">Types</a></span></dt><dt><span class="sect1"><a href="#C_Functions">C Functions</a></span></dt><dt><span class="sect1"><a href="#Errors">Errors</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Acknowledgements">5. Acknowledgements</a></span></dt><dt><span class="chapter"><a href="#References">6. 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 CreateWindow request, which
allocates a set of window attributes and, for InputOutput windows, a front
buffer, into which an image can be drawn. The contents of this buffer will be
displayed when the window is visible.
</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.
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 ClearArea 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
<code class="function">DRAWABLE</code> 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 window’s ancestors was passed in the
request), the front (that is, visible) buffer is always referenced. Thus,
DBE-naive screen dump clients will always get the front buffer.
<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 IncludeInferiors, the effect on the double-buffered
window’s back buffer depends on the depth of the double-buffered window
and the ancestor. If the depths are the same, the contents of the back buffer
of the double-buffered window are not changed. If the depths are different,
the contents of the back buffer of the double-buffered window are undefined
for the pixels that the <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 window’s size
increases, the effect on the buffers depends on whether the implementation
honors bit gravity for buffers.
If bit gravity is implemented, then the contents of both buffers are moved in
accordance with the window’s bit gravity (see the core
<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.
If the core GetGeometry 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>
<code class="function">DBEBeginIdiom</code> 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 <code class="function">PolyFillRectangle</code> request to the back buffer of one window.
    </p></li><li class="listitem"><p>
Core X <code class="function">PolyFillRectangle</code> request to the back buffer of the other
window.
    </p></li><li class="listitem"><p>
<code class="function">DBEEndIdiom</code> 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 <code class="function">Copied</code> 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 <code class="function">Untouched</code>, and if a
<code class="function">PolyFillRectangle</code> using a client clip
rectangle is done to the window’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="C_Language_Binding"></a>Chapter 4. C Language Binding</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Types">Types</a></span></dt><dt><span class="sect1"><a href="#C_Functions">C Functions</a></span></dt><dt><span class="sect1"><a href="#Errors">Errors</a></span></dt></dl></div><p>
All identiﬁer The header for this extension is &lt;X11/extensions/Xdbe.h&gt;.
names provided by this header begin with Xdbe.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Types"></a>Types</h2></div></div></div><p>
The type <code class="function">XdbeBackBuffer</code> is a <code class="function">Drawable</code>.
</p><p>
The type <code class="function">XdbeSwapAction</code> can be one of the constants
<code class="function">XdbeUndefined</code>,
<code class="function">XdbeBackground</code>,
<code class="function">XdbeUntouched</code>, or
<code class="function">XdbeCopied</code>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="C_Functions"></a>C Functions</h2></div></div></div><p>
The C functions provide direct access to the protocol and add no additional
semantics. For complete details on the effects of these functions, refer to the
appropriate protocol request, which can be derived by replacing Xdbe at the
start of the function name with DBE. All functions that have return type
<code class="function">Status</code> will return nonzero for success and
zero for failure.
</p><div class="funcsynopsis"><a id="XdbeQueryExtension"></a><p><code class="funcdef">Status <strong class="fsfunc">XdbeQueryExtension</strong>(</code>Display <var class="pdparam"> *dpy</var>, int <var class="pdparam"> *major_version_return</var>, int <var class="pdparam"> *minor_version_return</var><code>)</code>;</p></div><p>
<span class="olink"><code class="function">XdbeQueryExtension</code></span> sets major version return and minor
version return to the major and minor DBE protocol version supported by
the server. If the DBE library is compatible with the version returned by
the server, it returns nonzero. If dpy does not support the DBE extension,
or if there was an error during communication with the server, or if the
server and library protocol versions are incompatible, it returns zero.
No other Xdbe functions may be called before this function. If a client
violates this rule, the effects of all subsequent Xdbe calls that it makes
are undefined.
</p><div class="funcsynopsis"><a id="XdbeGetVisualInfo"></a><p><code class="funcdef">XdbeScreenVisualInfo *<strong class="fsfunc">XdbeGetVisualInfo</strong>(</code>Display <var class="pdparam"> *dpy</var>, Drawable <var class="pdparam"> *screen_specifiers</var>, int <var class="pdparam"> *num_screens</var><code>)</code>;</p></div><p>

<span class="olink"><code class="function">XdbeGetVisualInfo</code></span> returns information about which
visuals support double buffering. The argument num_screens specifies how
many elements there are in the screen_specifiers list. Each drawable in
screen_specifiers designates a screen for which the supported visuals are
being requested. If num_screens is zero, information for all screens is
requested. In this case, upon return from this function, num_screens will
be set to the number of screens that were found. If an error occurs,
this function returns NULL; otherwise, it returns a pointer to a list of
<code class="function">XdbeScreenVisualInfo</code>
structures of length num_screens.  The nth element in the returned list
corresponds to the nth drawable in the screen_specifiers list, unless

element in the returned list corresponds to the nth screen of the server,
starting with screen zero.
</p><p>
The XdbeScreenVisualInfo structure has the following fields:
</p><div class="literallayout"><p><br />
int                     count      number of items in visinfo<br />
XdbeVisualInfo*    visinfo     list of visuals and depths for this screen<br />
</p></div><p>
The <code class="function">XdbeVisualInfo</code> structure has the following fields:
</p><div class="literallayout"><p><br />
VisualID         visual    one visual ID that supports double-buffering<br />
int              depth     depth of visual in bits<br />
int              perflevel  performance level of visual<br />
</p></div><div class="funcsynopsis"><p><code class="funcdef">void XdbeFreeVisualInfo <strong class="fsfunc">XdbeGetVisualInfo</strong>(</code>XdbeScreenVisualInfo <var class="pdparam"> *visual_info</var><code>)</code>;</p></div><p>
<code class="function">XdbeFreeVisualInfo</code> frees the list of
<code class="function">XdbeScreenVisualInfo</code> returned by
<span class="olink"><code class="function">XdbeGetVisualInfo</code></span>.
</p><div class="funcsynopsis"><a id="XdbeAllocateBackBufferName"></a><p><code class="funcdef">XdbeBackBuffer <strong class="fsfunc">XdbeAllocateBackBufferName</strong>(</code>Display <var class="pdparam"> *dpy</var>, Window <var class="pdparam"> *window</var>, XdbeSwapAction <var class="pdparam"> swap_action</var><code>)</code>;</p></div><p>
<span class="olink"><code class="function">XdbeAllocateBackBufferName</code></span> returns a drawable ID used
to refer to the back buffer of the specified window. The swap_action is a
hint to indicate the swap_action that will likely be used in subsequent
calls to <span class="olink"><code class="function">XdbeSwapBuffers</code></span>.  The actual swap_action
used in calls to <span class="olink"><code class="function">XdbeSwapBuffers</code></span> does not have to be
the same as the swap_action passed to this function, though clients are
encouraged to provide accurate information whenever possible.
</p><div class="funcsynopsis"><a id="XdbeDeallocateBackBufferName"></a><p><code class="funcdef">Status <strong class="fsfunc">XdbeDeallocateBackBufferName</strong>(</code>Display <var class="pdparam"> *dpy</var>, XdbeBackBuffer <var class="pdparam"> buffer</var><code>)</code>;</p></div><p>
<span class="olink"><code class="function">XdbeDeallocateBackBufferName</code></span> frees the specified
drawable ID, buffer, that was obtained via
<span class="olink"><code class="function">XdbeAllocateBackBufferName</code></span>. The buffer must be a valid
name for the back buffer of a window, or an
<code class="function">XdbeBadBuffer</code> error results.
</p><div class="funcsynopsis"><a id="XdbeSwapBuffers"></a><p><code class="funcdef">Status <strong class="fsfunc">XdbeSwapBuffers</strong>(</code>Display <var class="pdparam"> *dpy</var>, XdbeSwapInfo <var class="pdparam"> *swap_info</var>, int <var class="pdparam"> num_windows</var><code>)</code>;</p></div><p>
<span class="olink"><code class="function">XdbeSwapBuffers</code></span> swaps the front and back buffers
for a list of windows. The argument num_windows specifies how many windows
are to have their buffers swapped; it is the number of elements in the
swap_info array. The argument swap_info specifies the information needed
per window to do the swap.
</p><p>
The XdbeSwapInfo structure has the following fields:
</p><div class="literallayout"><p><br />
Window              swap_window    window for which to swap buffers<br />
XdbeSwapAction      swap_action    swap action to use for this swap window<br />
</p></div><div class="funcsynopsis"><a id="XdbeBeginIdiom"></a><p><code class="funcdef">Status <strong class="fsfunc">XdbeBeginIdiom</strong>(</code>Display <var class="pdparam"> *dpy</var><code>)</code>;</p></div><p>
<span class="olink"><code class="function">XdbeBeginIdiom</code></span> marks the beginning of an idiom
sequence. See
<a class="link" href="#Complex_Swap_Actions" title="Complex Swap Actions">
the section called “Complex Swap Actions”</a>
for a complete discussion of idioms.
</p><div class="funcsynopsis"><a id="XdbeEndIdiom"></a><p><code class="funcdef">Status <strong class="fsfunc">XdbeEndIdiom</strong>(</code>Display <var class="pdparam"> *dpy</var><code>)</code>;</p></div><p>
<span class="olink"><code class="function">XdbeEndIdiom</code></span> marks the end of an idiom sequence.
</p><div class="funcsynopsis"><a id="XdbeGetBackBufferAttributes"></a><p><code class="funcdef">XdbeBackBufferAttributes *<strong class="fsfunc">XdbeGetBackBufferAttributes</strong>(</code>Display <var class="pdparam"> *dpy</var>, XdbeBackBuffer <var class="pdparam"> buffer</var><code>)</code>;</p></div><p>
<span class="olink"><code class="function">XdbeGetBackBufferAttributes</code></span> returns the attributes associated with
the specified buffer.
</p><p>
The XdbeBackBufferAttributes structure has the following fields:
</p><div class="literallayout"><p><br />
Window           window           window that buffer belongs to<br />
</p></div><p>
If buffer is not a valid <code class="function">XdbeBackBuffer</code>, window is
set to None.
</p><p>
The returned <code class="function">XdbeBackBufferAttributes</code> structure
can be freed with the Xlib function <span class="olink"><code class="function">XFree</code></span>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Errors"></a>Errors</h2></div></div></div><p>
The <code class="function">XdbeBufferError</code> structure has the following fields:
</p><div class="literallayout"><p><br />
int                 type<br />
Display *           display       Display the event was read from<br />
XdbeBackBuffer      buffer        resource id<br />
unsigned long       serial        serial number of failed request<br />
unsigned char       error code    error base + <code class="function">XdbeBadBuffer</code><br />
unsigned char       request code  Major op-code of failed request<br />
unsigned char       minor code    Minor op-code of failed request<br />
</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Acknowledgements"></a>Chapter 5. 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 6. 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>
libxext-doc 2:1.3.3-1 / usr / share / doc / libxext-dev / dbelib.html
