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