1e8a5466aSmrg<?xml version="1.0" encoding="UTF-8" ?>
2a5602400Smrg<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3af9a7ee5Smrg                   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
4af9a7ee5Smrg[
5af9a7ee5Smrg<!ENTITY % defs SYSTEM "defs.ent"> %defs;
6af9a7ee5Smrg]>
7e8a5466aSmrg
8e8a5466aSmrg
9e8a5466aSmrg<!-- lifted from troff+ms+XMan by doclifter -->
10e8a5466aSmrg<book id="dbelib">
11e8a5466aSmrg
12e8a5466aSmrg<bookinfo>
13e8a5466aSmrg   <title>Double Buffer Extension Library</title>
14e8a5466aSmrg   <subtitle>X Consortium Standard</subtitle>
15af9a7ee5Smrg   <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
16af9a7ee5Smrg   <releaseinfo>Version 1.0</releaseinfo>
17e8a5466aSmrg   <authorgroup>
18e8a5466aSmrg      <author>
19e8a5466aSmrg         <firstname>Ian</firstname><surname>Elliot</surname>
20af9a7ee5Smrg         <affiliation><orgname>Hewlett-Packard Company</orgname></affiliation>
21e8a5466aSmrg      </author>
22af9a7ee5Smrg      <othercredit>
23af9a7ee5Smrg         <firstname>David</firstname><othername>P.</othername><surname>Wiggins</surname>
24af9a7ee5Smrg         <affiliation><orgname>X Consortium, Inc</orgname></affiliation>
25af9a7ee5Smrg      </othercredit>
26e8a5466aSmrg   </authorgroup>
27af9a7ee5Smrg   <copyright><year>1989</year>
28af9a7ee5Smrg     <holder>X Consortium Inc</holder>
29af9a7ee5Smrg     <holder>Digital Equipment Corporation</holder>
30af9a7ee5Smrg   </copyright>
31af9a7ee5Smrg   <copyright><year>1992</year>
32af9a7ee5Smrg     <holder>X Consortium Inc</holder>
33af9a7ee5Smrg     <holder>Intergraph Corporation</holder>
34af9a7ee5Smrg   </copyright>
35af9a7ee5Smrg   <copyright><year>1993</year>
36af9a7ee5Smrg     <holder>X Consortium Inc</holder>
37af9a7ee5Smrg     <holder>Silicon Graphics, Inc.</holder>
38af9a7ee5Smrg   </copyright>
39af9a7ee5Smrg   <copyright><year>1994</year><year>1995</year>
40af9a7ee5Smrg     <holder>X Consortium Inc</holder>
41af9a7ee5Smrg     <holder>Hewlett-Packard Company</holder>
42af9a7ee5Smrg   </copyright>
43e8a5466aSmrg
44e8a5466aSmrg<legalnotice>
45e8a5466aSmrg<para>
46e8a5466aSmrgPermission to use, copy, modify, and distribute this documentation for any
47e8a5466aSmrgpurpose and without fee is hereby granted, provided that the above copyright
48e8a5466aSmrgnotice and this permission notice appear in all copies. Digital Equipment
49e8a5466aSmrgCorporation, Intergraph Corporation, Silicon Graphics, Hewlett-Packard, and
50e8a5466aSmrgthe X Consortium make no representations about the suitability for any
51e8a5466aSmrgpurpose of the information in this document. This documentation is provided
52e8a5466aSmrg"as is" without express or implied warranty.
53e8a5466aSmrg</para>
54e8a5466aSmrg
55e8a5466aSmrg</legalnotice>
56e8a5466aSmrg
57e8a5466aSmrg</bookinfo>
58e8a5466aSmrg
59af9a7ee5Smrg<chapter id='Introduction'>
60e8a5466aSmrg<title>Introduction</title>
61e8a5466aSmrg<para>
62e8a5466aSmrgThe Double Buffer Extension (DBE) provides a standard way to utilize
63e8a5466aSmrgdouble-buffering within the framework of the X Window System.
64e8a5466aSmrgDouble-buffering uses two buffers, called front and back, which hold images.
65e8a5466aSmrgThe front buffer is visible to the user; the back buffer is not. Successive
66e8a5466aSmrgframes of an animation are rendered into the back buffer while the previously
67e8a5466aSmrgrendered frame is displayed in the front buffer. When a new frame is ready,
68e8a5466aSmrgthe back and front buffers swap roles, making the new frame visible. Ideally,
69e8a5466aSmrgthis exchange appears to happen instantaneously to the user and with no
70e8a5466aSmrgvisual artifacts. Thus, only completely rendered images are presented to the
71e8a5466aSmrguser, and they remain visible during the entire time it takes to render a new
72e8a5466aSmrgframe. The result is a flicker-free animation.
73e8a5466aSmrg</para>
74e8a5466aSmrg
75e8a5466aSmrg</chapter>
76e8a5466aSmrg
77af9a7ee5Smrg<chapter id='Goals'>
78e8a5466aSmrg<title>Goals</title>
79e8a5466aSmrg
80e8a5466aSmrg<para>
81e8a5466aSmrgThis extension should enable clients to:
82e8a5466aSmrg</para>
83e8a5466aSmrg<itemizedlist>
84e8a5466aSmrg  <listitem>
85e8a5466aSmrg    <para>
86e8a5466aSmrgAllocate and deallocate double-buffering for a window.
87e8a5466aSmrg    </para>
88e8a5466aSmrg  </listitem>
89e8a5466aSmrg  <listitem>
90e8a5466aSmrg    <para>
91e8a5466aSmrgDraw to and read from the front and back buffers associated with a window.
92e8a5466aSmrg    </para>
93e8a5466aSmrg  </listitem>
94e8a5466aSmrg  <listitem>
95e8a5466aSmrg    <para>
96e8a5466aSmrgSwap the front and back buffers associated with a window.
97e8a5466aSmrg    </para>
98e8a5466aSmrg  </listitem>
99e8a5466aSmrg  <listitem>
100e8a5466aSmrg    <para>
101e8a5466aSmrgSpecify a wide range of actions to be taken when a window is swapped.
102e8a5466aSmrgThis includes explicit, simple swap actions (defined below), and more
103e8a5466aSmrgcomplex actions (for example, clearing ancillary buffers) that can be put
104e8a5466aSmrgtogether within explicit "begin" and "end" requests (defined below).
105e8a5466aSmrg    </para>
106e8a5466aSmrg  </listitem>
107e8a5466aSmrg  <listitem>
108e8a5466aSmrg    <para>
109e8a5466aSmrgRequest that the front and back buffers associated with multiple
110e8a5466aSmrgdouble-buffered windows be swapped simultaneously.
111e8a5466aSmrg    </para>
112e8a5466aSmrg  </listitem>
113e8a5466aSmrg</itemizedlist>
114e8a5466aSmrg
115e8a5466aSmrg<para>
116e8a5466aSmrgIn addition, the extension should:
117e8a5466aSmrg</para>
118e8a5466aSmrg<itemizedlist>
119e8a5466aSmrg  <listitem>
120e8a5466aSmrg    <para>
121e8a5466aSmrgAllow multiple clients to use double-buffering on the same window.
122e8a5466aSmrg    </para>
123e8a5466aSmrg  </listitem>
124e8a5466aSmrg  <listitem>
125e8a5466aSmrg    <para>
126e8a5466aSmrgSupport a range of implementation methods that can capitalize on
127e8a5466aSmrgexisting hardware features.
128e8a5466aSmrg    </para>
129e8a5466aSmrg  </listitem>
130e8a5466aSmrg  <listitem>
131e8a5466aSmrg    <para>
132e8a5466aSmrgAdd no new event types.
133e8a5466aSmrg    </para>
134e8a5466aSmrg  </listitem>
135e8a5466aSmrg  <listitem>
136e8a5466aSmrg    <para>
137e8a5466aSmrgBe reasonably easy to integrate with a variety of direct graphics
138e8a5466aSmrghardware access (DGHA) architectures.
139e8a5466aSmrg    </para>
140e8a5466aSmrg  </listitem>
141e8a5466aSmrg</itemizedlist>
142e8a5466aSmrg
143e8a5466aSmrg</chapter>
144e8a5466aSmrg
145af9a7ee5Smrg<chapter id='Concepts'>
146e8a5466aSmrg<title>Concepts</title>
147e8a5466aSmrg<para>
148e8a5466aSmrgNormal windows are created using the core CreateWindow request, which
149e8a5466aSmrgallocates a set of window attributes and, for InputOutput windows, a front
150e8a5466aSmrgbuffer, into which an image can be drawn. The contents of this buffer will be
151e8a5466aSmrgdisplayed when the window is visible.
152e8a5466aSmrg</para>
153e8a5466aSmrg<para>
154e8a5466aSmrgThis extension enables applications to use double-buffering with a window.
155e8a5466aSmrgThis involves creating a second buffer, called a back buffer, and associating
156e8a5466aSmrgone or more back buffer names (XIDs) with the window for use when referring
157e8a5466aSmrgto (that is, drawing to or reading from) the window’s back buffer. The back
158e8a5466aSmrgbuffer name is a DRAWABLE of type BACKBUFFER.
159e8a5466aSmrg</para>
160e8a5466aSmrg<para>
161e8a5466aSmrgDBE provides a relative double-buffering model. One XID, the window,
162e8a5466aSmrgalways refers to the front buffer. One or more other XIDs, the back buffer
163e8a5466aSmrgnames, always refer to the back buffer. After a buffer swap, the window
164e8a5466aSmrgcontinues to refer to the (new) front buffer, and the back buffer name
165e8a5466aSmrgcontinues to refer to the (new) back buffer. Thus, applications and toolkits
166e8a5466aSmrgthat want to just render to the back buffer always use the back buffer name
167e8a5466aSmrgfor all drawing requests to the window. Portions of an application that want
168e8a5466aSmrgto render to the front buffer always use the window XID for all drawing
169e8a5466aSmrgrequests to the window.
170e8a5466aSmrg</para>
171e8a5466aSmrg<para>
172e8a5466aSmrgMultiple clients and toolkits can all use double-buffering on the same window.
173e8a5466aSmrgDBE does not provide a request for querying whether a window has
174e8a5466aSmrgdouble-buffering support, and if so, what the back buffer name is. Given the
175e8a5466aSmrgasynchronous nature of the X Window System, this would cause race
176e8a5466aSmrgconditions. Instead, DBE allows multiple back buffer names to exist for the
177e8a5466aSmrgsame window; they all refer to the same physical back buffer. The first time a
178e8a5466aSmrgback buffer name is allocated for a window, the window becomes
179e8a5466aSmrgdouble-buffered and the back buffer name is associated with the window.
180e8a5466aSmrgSubsequently, the window already is a double-buffered window, and nothing
181e8a5466aSmrgabout the window changes when a new back buffer name is allocated, except
182e8a5466aSmrgthat the new back buffer name is associated with the window. The window
183e8a5466aSmrgremains double-buffered until either the window is destroyed or until all of the
184e8a5466aSmrgback buffer names for the window are deallocated.
185e8a5466aSmrg</para>
186e8a5466aSmrg<para>
187e8a5466aSmrgIn general, both the front and back buffers are treated the same.
188e8a5466aSmrgparticular, here are some important characteristics:
189e8a5466aSmrg</para>
190e8a5466aSmrg<itemizedlist>
191e8a5466aSmrg  <listitem>
192e8a5466aSmrg    <para>
193e8a5466aSmrgOnly one buffer per window can be visible at a time (the front buffer).
194e8a5466aSmrg    </para>
195e8a5466aSmrg  </listitem>
196e8a5466aSmrg  <listitem>
197e8a5466aSmrg    <para>
198e8a5466aSmrgBoth buffers associated with a window have the same visual type, depth,
199e8a5466aSmrgwidth, height, and shape as the window.
200e8a5466aSmrg    </para>
201e8a5466aSmrg  </listitem>
202e8a5466aSmrg  <listitem>
203e8a5466aSmrg    <para>
204e8a5466aSmrgBoth buffers associated with a window are "visible" (or "obscured") in
205e8a5466aSmrgthe same way. When an Expose event is generated for a window, both
206e8a5466aSmrgbuffers should be considered to be damaged in the exposed area.
207e8a5466aSmrgDamage that occurs to either buffer will result in an Expose event on
208e8a5466aSmrgthe window. When a double-buffered window is exposed, both buffers
209e8a5466aSmrgare tiled with the window background, exactly as stated by the core
210e8a5466aSmrgprotocol. Even though the back buffer is not visible, terms such as
211e8a5466aSmrgobscure apply to the back buffer as well as to the front buffer.
212e8a5466aSmrg    </para>
213e8a5466aSmrg  </listitem>
214e8a5466aSmrg  <listitem>
215e8a5466aSmrg    <para>
216e8a5466aSmrgIt is acceptable at any time to pass a BACKBUFFER in any request,
217e8a5466aSmrgnotably any core or extension drawing request, that expects a
218e8a5466aSmrgDRAWABLE.  This enables an application to draw directly into
219e8a5466aSmrgBACKBUFFERs in the same fashion as it would draw into any other
220e8a5466aSmrgDRAWABLE.
221e8a5466aSmrg    </para>
222e8a5466aSmrg  </listitem>
223e8a5466aSmrg  <listitem>
224e8a5466aSmrg    <para>
225e8a5466aSmrgIt is an error (Window) to pass a BACKBUFFER in a core request that
226e8a5466aSmrgexpects a Window.
227e8a5466aSmrg    </para>
228e8a5466aSmrg  </listitem>
229e8a5466aSmrg  <listitem>
230e8a5466aSmrg    <para>
231e8a5466aSmrgA BACKBUFFER will never be sent by core X in a reply, event, or
232e8a5466aSmrgerror where a Window is specified.
233e8a5466aSmrg    </para>
234e8a5466aSmrg  </listitem>
235e8a5466aSmrg  <listitem>
236e8a5466aSmrg    <para>
237e8a5466aSmrgIf core X11 backing-store and save-under applies to a double-buffered
238e8a5466aSmrgwindow, it applies to both buffers equally.
239e8a5466aSmrg    </para>
240e8a5466aSmrg  </listitem>
241e8a5466aSmrg  <listitem>
242e8a5466aSmrg    <para>
243e8a5466aSmrgIf the core ClearArea request is executed on a double-buffered window,
244e8a5466aSmrgthe same area in both the front and back buffers is cleared.
245e8a5466aSmrg    </para>
246e8a5466aSmrg  </listitem>
247e8a5466aSmrg</itemizedlist>
248e8a5466aSmrg
249e8a5466aSmrg<para>
250e8a5466aSmrgThe effect of passing a window to a request that accepts a
251e8a5466aSmrg<function>DRAWABLE</function> is
2520760f5d2Smrgunchanged by this extension. The window and front buffer are synonymous
253e8a5466aSmrgwith each other. This includes obeying the <function>GetImage</function>
254e8a5466aSmrgsemantics and the
255e8a5466aSmrgsubwindow-mode semantics if a core graphics context is involved. Regardless
256e8a5466aSmrgof whether the window was explicitly passed in a
257e8a5466aSmrg<function>GetImage</function> request, or
258e8a5466aSmrgimplicitly referenced (that is, one of the window’s ancestors was passed in the
259e8a5466aSmrgrequest), the front (that is, visible) buffer is always referenced. Thus,
260e8a5466aSmrgDBE-naive screen dump clients will always get the front buffer.
261e8a5466aSmrg<function>GetImage</function> on
262e8a5466aSmrga back buffer returns undefined image contents for any obscured regions of the
263e8a5466aSmrgback buffer that fall within the image.
264e8a5466aSmrg</para>
265e8a5466aSmrg<para>
266e8a5466aSmrgDrawing to a back buffer always uses the clip region that would be used to
267e8a5466aSmrgdraw to the front buffer with a GC subwindow-mode of
268e8a5466aSmrg<function>ClipByChildren</function>. If
269e8a5466aSmrgan ancestor of a double-buffered window is drawn to with a core GC having a
270e8a5466aSmrgsubwindow-mode of IncludeInferiors, the effect on the double-buffered
271e8a5466aSmrgwindow’s back buffer depends on the depth of the double-buffered window
272e8a5466aSmrgand the ancestor. If the depths are the same, the contents of the back buffer
273e8a5466aSmrgof the double-buffered window are not changed. If the depths are different,
274e8a5466aSmrgthe contents of the back buffer of the double-buffered window are undefined
275e8a5466aSmrgfor the pixels that the <function>IncludeInferiors</function> drawing touched.
276e8a5466aSmrg</para>
277e8a5466aSmrg
278e8a5466aSmrg
279e8a5466aSmrg<para>
280e8a5466aSmrgDBE adds no new events. DBE does not extend the semantics of any existing
281e8a5466aSmrgevents with the exception of adding a new DRAWABLE type called
282e8a5466aSmrgBACKBUFFER. If events, replies, or errors that contain a DRAWABLE (for
283e8a5466aSmrgexample, <function>GraphicsExpose</function>) are generated in response to
284e8a5466aSmrga request, the
285e8a5466aSmrgDRAWABLE returned will be the one specified in the request.
286e8a5466aSmrg</para>
287e8a5466aSmrg<para>
288e8a5466aSmrgDBE advertises which visuals support double-buffering.
289e8a5466aSmrg</para>
290e8a5466aSmrg<para>
291e8a5466aSmrgDBE does not include any timing or synchronization facilities. Applications
292e8a5466aSmrgthat need such facilities (for example, to maintain a constant frame rate)
293e8a5466aSmrgshould investigate the Synchronization Extension, an X Consortium standard.
294e8a5466aSmrg</para>
295e8a5466aSmrg
296af9a7ee5Smrg<sect1 id='Window_Management_Operations'>
297e8a5466aSmrg<title>Window Management Operations</title>
298e8a5466aSmrg
299e8a5466aSmrg<para>
300e8a5466aSmrgThe basic philosophy of DBE is that both buffers are treated the same by core
301e8a5466aSmrgX window management operations.
302e8a5466aSmrg</para>
303e8a5466aSmrg<para>
304e8a5466aSmrgWhen the core <function>DestroyWindow</function> is executed on a
305e8a5466aSmrgdouble-buffered window, both buffers associated with the window are
306e8a5466aSmrgdestroyed, and all back buffer names associated with the window are freed.
307e8a5466aSmrg</para>
308e8a5466aSmrg<para>
309e8a5466aSmrgIf the core <function>ConfigureWindow</function> request changes the size
310e8a5466aSmrgof a window, both buffers assume the new size. If the window’s size
311e8a5466aSmrgincreases, the effect on the buffers depends on whether the implementation
312e8a5466aSmrghonors bit gravity for buffers.
313e8a5466aSmrgIf bit gravity is implemented, then the contents of both buffers are moved in
314e8a5466aSmrgaccordance with the window’s bit gravity (see the core
315e8a5466aSmrg<function>ConfigureWindow</function>
316e8a5466aSmrgrequest), and the remaining areas are tiled with the window background. If
317e8a5466aSmrgbit gravity is not implemented, then the entire unobscured region of both
318e8a5466aSmrgbuffers is tiled with the window background. In either case,
319e8a5466aSmrg<function>Expose</function> events are
320e8a5466aSmrggenerated for the region that is tiled with the window background.
321e8a5466aSmrgIf the core GetGeometry request is executed on a BACKBUFFER, the
322e8a5466aSmrgreturned x, y, and border-width will be zero.
323e8a5466aSmrg</para>
324e8a5466aSmrg<para>
325e8a5466aSmrgIf the Shape extension
326e8a5466aSmrg<function>ShapeRectangles</function>,
327e8a5466aSmrg<function>ShapeMask</function>,
328e8a5466aSmrg<function>ShapeCombine</function>, or
329e8a5466aSmrg<function>ShapeOffset</function>
330e8a5466aSmrgrequest is executed on a double-buffered window, both buffers
331e8a5466aSmrgare reshaped to match the new window shape. The region difference is the
332e8a5466aSmrgfollowing:
333e8a5466aSmrg</para>
334e8a5466aSmrg
335e8a5466aSmrg<literallayout remap='Ds'>
336e8a5466aSmrg        D = newshape − oldshape
337e8a5466aSmrg</literallayout>
338e8a5466aSmrg
339e8a5466aSmrg<para>
340e8a5466aSmrgIt is tiled with the window background in both buffers, and
341e8a5466aSmrg<function>Expose</function>
342e8a5466aSmrgevents are generated for D.
343e8a5466aSmrg</para>
344e8a5466aSmrg
345e8a5466aSmrg</sect1>
346e8a5466aSmrg
347af9a7ee5Smrg<sect1 id='Complex_Swap_Actions'>
348e8a5466aSmrg<title>Complex Swap Actions</title>
349e8a5466aSmrg<para>
350e8a5466aSmrgDBE has no explicit knowledge of ancillary buffers (for example, depth buffers
351e8a5466aSmrgor alpha buffers), and only has a limited set of defined swap actions. Some
352e8a5466aSmrgapplications may need a richer set of swap actions than DBE provides. Some
353e8a5466aSmrgDBE implementations have knowledge of ancillary buffers, and/or can provide
354e8a5466aSmrga rich set of swap actions. Instead of continually extending DBE to increase
355e8a5466aSmrgits set of swap actions, DBE provides a flexible "idiom" mechanism. If an
356e8a5466aSmrgapplication’s needs are served by the defined swap actions, it should use them;
357e8a5466aSmrgotherwise, it should use the following method of expressing a complex swap
358e8a5466aSmrgaction as an idiom. Following this policy will ensure the best possible
359e8a5466aSmrgperformance across a wide variety of implementations.
360e8a5466aSmrg</para>
361e8a5466aSmrg<para>
362e8a5466aSmrgAs suggested by the term "idiom," a complex swap action should be expressed
363e8a5466aSmrgas a group/series of requests. Taken together, this group of requests may be
364e8a5466aSmrgcombined into an atomic operation by the implementation, in order to
365e8a5466aSmrgmaximize performance. The set of idioms actually recognized for optimization
366e8a5466aSmrgis implementation dependent.
367e8a5466aSmrgTo help with idiom expression and
368e8a5466aSmrginterpretation, an idiom must be surrounded by two protocol requests:
369e8a5466aSmrg<function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>.
370e8a5466aSmrgUnless this begin-end pair surrounds the idiom, it may not be recognized
371e8a5466aSmrgby a given implementation, and performance will suffer.
372e8a5466aSmrg</para>
373e8a5466aSmrg<para>
374e8a5466aSmrgFor example, if an application wants to swap buffers for two windows, and use
375e8a5466aSmrgcore X to clear only certain planes of the back buffers, the application would
376e8a5466aSmrgissue the following protocol requests as a group, and in the following order:
377e8a5466aSmrg</para>
378e8a5466aSmrg
379e8a5466aSmrg<itemizedlist>
380e8a5466aSmrg  <listitem>
381e8a5466aSmrg    <para>
382e8a5466aSmrg<function>DBEBeginIdiom</function> request.
383e8a5466aSmrg    </para>
384e8a5466aSmrg  </listitem>
385e8a5466aSmrg  <listitem>
386e8a5466aSmrg    <para>
387e8a5466aSmrg<function>DBESwapBuffers</function> request with XIDs for two windows, each of which uses
388e8a5466aSmrga swap action of Untouched.
389e8a5466aSmrg    </para>
390e8a5466aSmrg  </listitem>
391e8a5466aSmrg  <listitem>
392e8a5466aSmrg    <para>
393e8a5466aSmrgCore X <function>PolyFillRectangle</function> request to the back buffer of one window.
394e8a5466aSmrg    </para>
395e8a5466aSmrg  </listitem>
396e8a5466aSmrg  <listitem>
397e8a5466aSmrg    <para>
398e8a5466aSmrgCore X <function>PolyFillRectangle</function> request to the back buffer of the other
399e8a5466aSmrgwindow.
400e8a5466aSmrg    </para>
401e8a5466aSmrg  </listitem>
402e8a5466aSmrg  <listitem>
403e8a5466aSmrg    <para>
404e8a5466aSmrg<function>DBEEndIdiom</function> request.
405e8a5466aSmrg    </para>
406e8a5466aSmrg  </listitem>
407e8a5466aSmrg</itemizedlist>
408e8a5466aSmrg
409e8a5466aSmrg<para>
410e8a5466aSmrgThe <function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>
411e8a5466aSmrgrequests do not perform any actions
412e8a5466aSmrgthemselves. They are treated as markers by implementations that can
413e8a5466aSmrgcombine certain groups/series of requests as idioms, and are ignored by other
414e8a5466aSmrgimplementations or for nonrecognized groups/series of requests. If these
415e8a5466aSmrgrequests are sent out of order, or are mismatched, no errors are sent, and the
416e8a5466aSmrgrequests are executed as usual, though performance may suffer.
417e8a5466aSmrg</para>
418e8a5466aSmrg
419e8a5466aSmrg<para>
420e8a5466aSmrg
421e8a5466aSmrgAn idiom need not include a <function>DBESwapBuffers</function> request.
422e8a5466aSmrgFor example, if a swap action of <function>Copied</function> is desired,
423e8a5466aSmrgbut only some of the planes should be copied, a core X
424e8a5466aSmrg<function>CopyArea</function> request may be used instead of
425e8a5466aSmrg<function>DBESwapBuffers</function>. If
426e8a5466aSmrg<function>DBESwapBuffers</function> is included in an idiom, it should
427e8a5466aSmrgimmediately follow the
428e8a5466aSmrg<function>DBEBeginIdiom</function> request. Also, when the
429e8a5466aSmrg<function>DBESwapBuffers</function> is included in an idiom, that
430e8a5466aSmrgrequest’s swap action will still be valid, and if the swap action
431e8a5466aSmrgmight overlap with another request, then the final result of the idiom must be
432e8a5466aSmrgas if the separate requests were executed serially. For example, if the
433e8a5466aSmrgspecified swap action is <function>Untouched</function>, and if a
434e8a5466aSmrg<function>PolyFillRectangle</function> using a client clip
435e8a5466aSmrgrectangle is done to the window’s back buffer after the
436e8a5466aSmrg<function>DBESwapBuffers</function> request, then the contents of the new
437e8a5466aSmrgback buffer (after the idiom) will be the
438e8a5466aSmrgsame as if the idiom was not recognized by the implementation.
439e8a5466aSmrg</para>
440e8a5466aSmrg<para>
441e8a5466aSmrgIt is highly recommended that Application Programming Interface (API)
442e8a5466aSmrgproviders define, and application developers use, "convenience" functions that
443e8a5466aSmrgallow client applications to call one procedure that encapsulates common
444e8a5466aSmrgidioms. These functions will generate the
445e8a5466aSmrg<function>DBEBeginIdiom</function> request, the idiom
446e8a5466aSmrgrequests, and <function>DBEEndIdiom</function> request. Usage of these
447e8a5466aSmrgfunctions will ensure best possible performance across a wide
448e8a5466aSmrgvariety of implementations.
449e8a5466aSmrg</para>
450e8a5466aSmrg
451e8a5466aSmrg</sect1>
452e8a5466aSmrg</chapter>
453e8a5466aSmrg
454af9a7ee5Smrg<chapter id='C_Language_Binding'>
455e8a5466aSmrg<title>C Language Binding</title>
456e8a5466aSmrg<para>
457e8a5466aSmrgAll identifier The header for this extension is &lt;X11/extensions/Xdbe.h&gt;.
458e8a5466aSmrgnames provided by this header begin with Xdbe.
459e8a5466aSmrg</para>
460e8a5466aSmrg
461af9a7ee5Smrg<sect1 id='Types'>
462e8a5466aSmrg<title>Types</title>
463e8a5466aSmrg
464e8a5466aSmrg<para>
465e8a5466aSmrgThe type <function>XdbeBackBuffer</function> is a <function>Drawable</function>.
466e8a5466aSmrg</para>
467e8a5466aSmrg
468e8a5466aSmrg<para>
469e8a5466aSmrgThe type <function>XdbeSwapAction</function> can be one of the constants
470e8a5466aSmrg<function>XdbeUndefined</function>,
471e8a5466aSmrg<function>XdbeBackground</function>,
472e8a5466aSmrg<function>XdbeUntouched</function>, or
473e8a5466aSmrg<function>XdbeCopied</function>.
474e8a5466aSmrg</para>
475e8a5466aSmrg
476e8a5466aSmrg</sect1>
477e8a5466aSmrg
478af9a7ee5Smrg<sect1 id='C_Functions'>
479e8a5466aSmrg<title>C Functions</title>
480e8a5466aSmrg<para>
481e8a5466aSmrgThe C functions provide direct access to the protocol and add no additional
482e8a5466aSmrgsemantics. For complete details on the effects of these functions, refer to the
483e8a5466aSmrgappropriate protocol request, which can be derived by replacing Xdbe at the
484e8a5466aSmrgstart of the function name with DBE. All functions that have return type
485e8a5466aSmrg<function>Status</function> will return nonzero for success and
486e8a5466aSmrgzero for failure.
487e8a5466aSmrg</para>
488e8a5466aSmrg
489af9a7ee5Smrg<funcsynopsis id='XdbeQueryExtension'>
490e8a5466aSmrg<funcprototype>
491e8a5466aSmrg  <funcdef>Status <function>XdbeQueryExtension</function></funcdef>
492e8a5466aSmrg    <paramdef>Display <parameter> *dpy</parameter></paramdef>
493e8a5466aSmrg    <paramdef>int <parameter> *major_version_return</parameter></paramdef>
494e8a5466aSmrg    <paramdef>int <parameter> *minor_version_return</parameter></paramdef>
495e8a5466aSmrg</funcprototype>
496e8a5466aSmrg</funcsynopsis>
497e8a5466aSmrg
498e8a5466aSmrg<para>
499af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeQueryExtension'><function>XdbeQueryExtension</function></olink> sets major version return and minor
500e8a5466aSmrgversion return to the major and minor DBE protocol version supported by
501e8a5466aSmrgthe server. If the DBE library is compatible with the version returned by
502e8a5466aSmrgthe server, it returns nonzero. If dpy does not support the DBE extension,
503e8a5466aSmrgor if there was an error during communication with the server, or if the
504e8a5466aSmrgserver and library protocol versions are incompatible, it returns zero.
505e8a5466aSmrgNo other Xdbe functions may be called before this function. If a client
506e8a5466aSmrgviolates this rule, the effects of all subsequent Xdbe calls that it makes
507e8a5466aSmrgare undefined.
508e8a5466aSmrg</para>
509e8a5466aSmrg
510af9a7ee5Smrg<funcsynopsis id='XdbeGetVisualInfo'>
511e8a5466aSmrg<funcprototype>
512e8a5466aSmrg  <funcdef>XdbeScreenVisualInfo *<function>XdbeGetVisualInfo</function></funcdef>
513e8a5466aSmrg    <paramdef>Display <parameter> *dpy</parameter></paramdef>
514e8a5466aSmrg    <paramdef>Drawable <parameter> *screen_specifiers</parameter></paramdef>
515e8a5466aSmrg    <paramdef>int <parameter> *num_screens</parameter></paramdef>
516e8a5466aSmrg</funcprototype>
517e8a5466aSmrg</funcsynopsis>
518e8a5466aSmrg
519e8a5466aSmrg<para>
520e8a5466aSmrg
521af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeGetVisualInfo'><function>XdbeGetVisualInfo</function></olink> returns information about which
522e8a5466aSmrgvisuals support double buffering. The argument num_screens specifies how
523e8a5466aSmrgmany elements there are in the screen_specifiers list. Each drawable in
524e8a5466aSmrgscreen_specifiers designates a screen for which the supported visuals are
525e8a5466aSmrgbeing requested. If num_screens is zero, information for all screens is
526e8a5466aSmrgrequested. In this case, upon return from this function, num_screens will
527e8a5466aSmrgbe set to the number of screens that were found. If an error occurs,
528e8a5466aSmrgthis function returns NULL; otherwise, it returns a pointer to a list of
529e8a5466aSmrg<function>XdbeScreenVisualInfo</function>
530e8a5466aSmrgstructures of length num_screens.  The nth element in the returned list
531e8a5466aSmrgcorresponds to the nth drawable in the screen_specifiers list, unless
532e8a5466aSmrg
533e8a5466aSmrgelement in the returned list corresponds to the nth screen of the server,
534e8a5466aSmrgstarting with screen zero.
535e8a5466aSmrg</para>
536e8a5466aSmrg
537e8a5466aSmrg
538e8a5466aSmrg<para>
539e8a5466aSmrgThe XdbeScreenVisualInfo structure has the following fields:
540e8a5466aSmrg</para>
541e8a5466aSmrg<literallayout remap='Ds'>
542e8a5466aSmrgint                     count      number of items in visinfo
543e8a5466aSmrgXdbeVisualInfo*    visinfo     list of visuals and depths for this screen
544e8a5466aSmrg</literallayout>
545e8a5466aSmrg
546e8a5466aSmrg<para>
547e8a5466aSmrgThe <function>XdbeVisualInfo</function> structure has the following fields:
548e8a5466aSmrg</para>
549e8a5466aSmrg
550e8a5466aSmrg<literallayout remap='Ds'>
551e8a5466aSmrgVisualID         visual    one visual ID that supports double-buffering
552e8a5466aSmrgint              depth     depth of visual in bits
553e8a5466aSmrgint              perflevel  performance level of visual
554e8a5466aSmrg</literallayout>
555e8a5466aSmrg
556e8a5466aSmrg
557e8a5466aSmrg<funcsynopsis>
558e8a5466aSmrg<funcprototype>
559e8a5466aSmrg  <funcdef>void XdbeFreeVisualInfo <function>XdbeGetVisualInfo</function></funcdef>
560e8a5466aSmrg    <paramdef>XdbeScreenVisualInfo <parameter> *visual_info</parameter></paramdef>
561e8a5466aSmrg</funcprototype>
562e8a5466aSmrg</funcsynopsis>
563e8a5466aSmrg
564e8a5466aSmrg<para>
565e8a5466aSmrg<function>XdbeFreeVisualInfo</function> frees the list of
566e8a5466aSmrg<function>XdbeScreenVisualInfo</function> returned by
567af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeGetVisualInfo'><function>XdbeGetVisualInfo</function></olink>.
568e8a5466aSmrg</para>
569e8a5466aSmrg
570e8a5466aSmrg
571af9a7ee5Smrg<funcsynopsis id='XdbeAllocateBackBufferName'>
572e8a5466aSmrg<funcprototype>
573e8a5466aSmrg  <funcdef>XdbeBackBuffer <function>XdbeAllocateBackBufferName</function></funcdef>
574e8a5466aSmrg    <paramdef>Display <parameter> *dpy</parameter></paramdef>
575e8a5466aSmrg    <paramdef>Window <parameter> *window</parameter></paramdef>
576e8a5466aSmrg    <paramdef>XdbeSwapAction <parameter> swap_action</parameter></paramdef>
577e8a5466aSmrg</funcprototype>
578e8a5466aSmrg</funcsynopsis>
579e8a5466aSmrg
580e8a5466aSmrg
581e8a5466aSmrg<para>
582af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeAllocateBackBufferName'><function>XdbeAllocateBackBufferName</function></olink> returns a drawable ID used
583e8a5466aSmrgto refer to the back buffer of the specified window. The swap_action is a
584e8a5466aSmrghint to indicate the swap_action that will likely be used in subsequent
585af9a7ee5Smrgcalls to <olink targetdoc='dbelib' targetptr='XdbeSwapBuffers'><function>XdbeSwapBuffers</function></olink>.  The actual swap_action
586af9a7ee5Smrgused in calls to <olink targetdoc='dbelib' targetptr='XdbeSwapBuffers'><function>XdbeSwapBuffers</function></olink> does not have to be
587e8a5466aSmrgthe same as the swap_action passed to this function, though clients are
588e8a5466aSmrgencouraged to provide accurate information whenever possible.
589e8a5466aSmrg</para>
590e8a5466aSmrg
591af9a7ee5Smrg<funcsynopsis id='XdbeDeallocateBackBufferName'>
592e8a5466aSmrg<funcprototype>
593e8a5466aSmrg  <funcdef>Status <function>XdbeDeallocateBackBufferName</function></funcdef>
594e8a5466aSmrg    <paramdef>Display <parameter> *dpy</parameter></paramdef>
595e8a5466aSmrg    <paramdef>XdbeBackBuffer <parameter> buffer</parameter></paramdef>
596e8a5466aSmrg</funcprototype>
597e8a5466aSmrg</funcsynopsis>
598e8a5466aSmrg
599e8a5466aSmrg<para>
600af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeDeallocateBackBufferName'><function>XdbeDeallocateBackBufferName</function></olink> frees the specified
601e8a5466aSmrgdrawable ID, buffer, that was obtained via
602af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeAllocateBackBufferName'><function>XdbeAllocateBackBufferName</function></olink>. The buffer must be a valid
603e8a5466aSmrgname for the back buffer of a window, or an
604e8a5466aSmrg<function>XdbeBadBuffer</function> error results.
605e8a5466aSmrg</para>
606e8a5466aSmrg
607af9a7ee5Smrg<funcsynopsis id='XdbeSwapBuffers'>
608e8a5466aSmrg<funcprototype>
609e8a5466aSmrg  <funcdef>Status <function>XdbeSwapBuffers</function></funcdef>
610e8a5466aSmrg    <paramdef>Display <parameter> *dpy</parameter></paramdef>
611e8a5466aSmrg    <paramdef>XdbeSwapInfo <parameter> *swap_info</parameter></paramdef>
612e8a5466aSmrg    <paramdef>int <parameter> num_windows</parameter></paramdef>
613e8a5466aSmrg</funcprototype>
614e8a5466aSmrg</funcsynopsis>
615e8a5466aSmrg
616e8a5466aSmrg<para>
617af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeSwapBuffers'><function>XdbeSwapBuffers</function></olink> swaps the front and back buffers
618e8a5466aSmrgfor a list of windows. The argument num_windows specifies how many windows
619e8a5466aSmrgare to have their buffers swapped; it is the number of elements in the
620e8a5466aSmrgswap_info array. The argument swap_info specifies the information needed
621e8a5466aSmrgper window to do the swap.
622e8a5466aSmrg</para>
623e8a5466aSmrg<para>
624e8a5466aSmrgThe XdbeSwapInfo structure has the following fields:
625e8a5466aSmrg</para>
626e8a5466aSmrg
627e8a5466aSmrg<literallayout remap='Ds'>
628e8a5466aSmrgWindow              swap_window    window for which to swap buffers
629e8a5466aSmrgXdbeSwapAction      swap_action    swap action to use for this swap window
630e8a5466aSmrg</literallayout>
631e8a5466aSmrg
632af9a7ee5Smrg<funcsynopsis id='XdbeBeginIdiom'>
633e8a5466aSmrg<funcprototype>
634e8a5466aSmrg  <funcdef>Status <function>XdbeBeginIdiom</function></funcdef>
635e8a5466aSmrg    <paramdef>Display <parameter> *dpy</parameter></paramdef>
636e8a5466aSmrg</funcprototype>
637e8a5466aSmrg</funcsynopsis>
638e8a5466aSmrg
639e8a5466aSmrg<para>
640af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeBeginIdiom'><function>XdbeBeginIdiom</function></olink> marks the beginning of an idiom
641e8a5466aSmrgsequence. See
642af9a7ee5Smrg<link linkend='Complex_Swap_Actions'>
643af9a7ee5Smrg<xref linkend='Complex_Swap_Actions'></xref></link>
644e8a5466aSmrgfor a complete discussion of idioms.
645e8a5466aSmrg</para>
646e8a5466aSmrg
647af9a7ee5Smrg<funcsynopsis id='XdbeEndIdiom'>
648e8a5466aSmrg<funcprototype>
649e8a5466aSmrg  <funcdef>Status <function>XdbeEndIdiom</function></funcdef>
650e8a5466aSmrg    <paramdef>Display <parameter> *dpy</parameter></paramdef>
651e8a5466aSmrg</funcprototype>
652e8a5466aSmrg</funcsynopsis>
653e8a5466aSmrg
654e8a5466aSmrg<para>
655af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeEndIdiom'><function>XdbeEndIdiom</function></olink> marks the end of an idiom sequence.
656e8a5466aSmrg</para>
657e8a5466aSmrg
658af9a7ee5Smrg<funcsynopsis id='XdbeGetBackBufferAttributes'>
659e8a5466aSmrg<funcprototype>
660e8a5466aSmrg  <funcdef>XdbeBackBufferAttributes *<function>XdbeGetBackBufferAttributes</function></funcdef>
661e8a5466aSmrg    <paramdef>Display <parameter> *dpy</parameter></paramdef>
662e8a5466aSmrg    <paramdef>XdbeBackBuffer <parameter> buffer</parameter></paramdef>
663e8a5466aSmrg</funcprototype>
664e8a5466aSmrg</funcsynopsis>
665e8a5466aSmrg
666e8a5466aSmrg<para>
667af9a7ee5Smrg<olink targetdoc='dbelib' targetptr='XdbeGetBackBufferAttributes'><function>XdbeGetBackBufferAttributes</function></olink> returns the attributes associated with
668e8a5466aSmrgthe specified buffer.
669e8a5466aSmrg</para>
670e8a5466aSmrg<para>
671e8a5466aSmrgThe XdbeBackBufferAttributes structure has the following fields:
672e8a5466aSmrg</para>
673e8a5466aSmrg
674e8a5466aSmrg<literallayout remap='Ds'>
675e8a5466aSmrgWindow           window           window that buffer belongs to
676e8a5466aSmrg</literallayout>
677e8a5466aSmrg
678e8a5466aSmrg<para>
679e8a5466aSmrgIf buffer is not a valid <function>XdbeBackBuffer</function>, window is
680e8a5466aSmrgset to None.
681e8a5466aSmrg</para>
682e8a5466aSmrg<para>
683e8a5466aSmrgThe returned <function>XdbeBackBufferAttributes</function> structure
684af9a7ee5Smrgcan be freed with the Xlib function <olink targetdoc='libX11' targetptr='XFree'><function>XFree</function></olink>.
685e8a5466aSmrg</para>
686e8a5466aSmrg</sect1>
687e8a5466aSmrg
688af9a7ee5Smrg<sect1 id='Errors'>
689e8a5466aSmrg<title>Errors</title>
690e8a5466aSmrg<para>
691e8a5466aSmrgThe <function>XdbeBufferError</function> structure has the following fields:
692e8a5466aSmrg</para>
693e8a5466aSmrg<literallayout remap='Ds'>
694e8a5466aSmrgint                 type
695e8a5466aSmrgDisplay *           display       Display the event was read from
696e8a5466aSmrgXdbeBackBuffer      buffer        resource id
697e8a5466aSmrgunsigned long       serial        serial number of failed request
698e8a5466aSmrgunsigned char       error code    error base + <function>XdbeBadBuffer</function>
699e8a5466aSmrgunsigned char       request code  Major op-code of failed request
700e8a5466aSmrgunsigned char       minor code    Minor op-code of failed request
701e8a5466aSmrg</literallayout>
702e8a5466aSmrg</sect1>
703e8a5466aSmrg</chapter>
704e8a5466aSmrg
705af9a7ee5Smrg<chapter id='Acknowledgements'>
706e8a5466aSmrg<title>Acknowledgements</title>
707e8a5466aSmrg
708e8a5466aSmrg<para>
709e8a5466aSmrgWe wish to thank the following individuals who have contributed their time
710e8a5466aSmrgand talent toward shaping the DBE specification:
711e8a5466aSmrg</para>
712e8a5466aSmrg<para>
713e8a5466aSmrgT. Alex Chen, IBM; Peter Daifuku, Silicon Graphics, Inc.; Ian Elliott,
714e8a5466aSmrgHewlett-Packard Company; Stephen Gildea, X Consortium, Inc.; Jim Graham,
715e8a5466aSmrgSun; Larry Hare, AGE Logic; Jay Hersh, X Consortium, Inc.; Daryl Huff,
716e8a5466aSmrgSun; Deron Dann Johnson, Sun; Louis Khouw, Sun; Mark Kilgard, Silicon
717e8a5466aSmrgGraphics, Inc.; Rob Lembree, Digital Equipment Corporation; Alan Ricker,
718e8a5466aSmrgMetheus; Michael Rosenblum, Digital Equipment Corporation; Bob Scheifler,
719e8a5466aSmrgX Consortium, Inc.; Larry Seiler, Digital Equipment Corporation; Jeanne
720e8a5466aSmrgSparlin Smith, IBM; Jeff Stevenson, Hewlett-Packard Company; Walter
721e8a5466aSmrgStrand, Metheus; Ken Tidwell, Hewlett-Packard Company; and David P.
722e8a5466aSmrgWiggins, X Consortium, Inc.
723e8a5466aSmrg</para>
724e8a5466aSmrg<para>
725e8a5466aSmrgMark provided the impetus to start the DBE project. Ian wrote the first draft
726e8a5466aSmrgof the specification. David served as architect.
727e8a5466aSmrg</para>
728e8a5466aSmrg
729e8a5466aSmrg</chapter>
730af9a7ee5Smrg<chapter id='References'>
731e8a5466aSmrg<title>References</title>
732e8a5466aSmrg<para>
733e8a5466aSmrgJeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension
734e8a5466aSmrgSpecification Version 3.3."
735e8a5466aSmrg</para>
736e8a5466aSmrg<para>
737e8a5466aSmrgTim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins, "X
738e8a5466aSmrgSynchronization Extension Version 3.0."
739e8a5466aSmrg</para>
740e8a5466aSmrg</chapter>
741e8a5466aSmrg</book>
742