upload tizen2.0 source
[framework/uifw/xorg/lib/libxext.git] / specs / dbelib.xml
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>
46 Permission to use, copy, modify, and distribute this documentation for any
47 purpose and without fee is hereby granted, provided that the above copyright
48 notice and this permission notice appear in all copies. Digital Equipment
49 Corporation, Intergraph Corporation, Silicon Graphics, Hewlett-Packard, and
50 the X Consortium make no representations about the suitability for any
51 purpose 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>
62 The Double Buffer Extension (DBE) provides a standard way to utilize
63 double-buffering within the framework of the X Window System.
64 Double-buffering uses two buffers, called front and back, which hold images.
65 The front buffer is visible to the user; the back buffer is not. Successive
66 frames of an animation are rendered into the back buffer while the previously
67 rendered frame is displayed in the front buffer. When a new frame is ready,
68 the back and front buffers swap roles, making the new frame visible. Ideally,
69 this exchange appears to happen instantaneously to the user and with no
70 visual artifacts. Thus, only completely rendered images are presented to the
71 user, and they remain visible during the entire time it takes to render a new
72 frame. The result is a flicker-free animation.
73 </para>
74
75 </chapter>
76
77 <chapter id='Goals'>
78 <title>Goals</title>
79
80 <para>
81 This extension should enable clients to:
82 </para>
83 <itemizedlist>
84   <listitem>
85     <para>
86 Allocate and deallocate double-buffering for a window.
87     </para>
88   </listitem>
89   <listitem>
90     <para>
91 Draw to and read from the front and back buffers associated with a window.
92     </para>
93   </listitem>
94   <listitem>
95     <para>
96 Swap the front and back buffers associated with a window.
97     </para>
98   </listitem>
99   <listitem>
100     <para>
101 Specify a wide range of actions to be taken when a window is swapped.
102 This includes explicit, simple swap actions (defined below), and more
103 complex actions (for example, clearing ancillary buffers) that can be put
104 together within explicit "begin" and "end" requests (defined below).
105     </para>
106   </listitem>
107   <listitem>
108     <para>
109 Request that the front and back buffers associated with multiple
110 double-buffered windows be swapped simultaneously.
111     </para>
112   </listitem>
113 </itemizedlist>
114
115 <para>
116 In addition, the extension should:
117 </para>
118 <itemizedlist>
119   <listitem>
120     <para>
121 Allow multiple clients to use double-buffering on the same window.
122     </para>
123   </listitem>
124   <listitem>
125     <para>
126 Support a range of implementation methods that can capitalize on
127 existing hardware features.
128     </para>
129   </listitem>
130   <listitem>
131     <para>
132 Add no new event types.
133     </para>
134   </listitem>
135   <listitem>
136     <para>
137 Be reasonably easy to integrate with a variety of direct graphics
138 hardware access (DGHA) architectures.
139     </para>
140   </listitem>
141 </itemizedlist>
142
143 </chapter>
144
145 <chapter id='Concepts'>
146 <title>Concepts</title>
147 <para>
148 Normal windows are created using the core CreateWindow request, which
149 allocates a set of window attributes and, for InputOutput windows, a front
150 buffer, into which an image can be drawn. The contents of this buffer will be
151 displayed when the window is visible.
152 </para>
153 <para>
154 This extension enables applications to use double-buffering with a window.
155 This involves creating a second buffer, called a back buffer, and associating
156 one or more back buffer names (XIDs) with the window for use when referring
157 to (that is, drawing to or reading from) the window’s back buffer. The back
158 buffer name is a DRAWABLE of type BACKBUFFER.
159 </para>
160 <para>
161 DBE provides a relative double-buffering model. One XID, the window,
162 always refers to the front buffer. One or more other XIDs, the back buffer
163 names, always refer to the back buffer. After a buffer swap, the window
164 continues to refer to the (new) front buffer, and the back buffer name
165 continues to refer to the (new) back buffer. Thus, applications and toolkits
166 that want to just render to the back buffer always use the back buffer name
167 for all drawing requests to the window. Portions of an application that want
168 to render to the front buffer always use the window XID for all drawing
169 requests to the window.
170 </para>
171 <para>
172 Multiple clients and toolkits can all use double-buffering on the same window.
173 DBE does not provide a request for querying whether a window has
174 double-buffering support, and if so, what the back buffer name is. Given the
175 asynchronous nature of the X Window System, this would cause race
176 conditions. Instead, DBE allows multiple back buffer names to exist for the
177 same window; they all refer to the same physical back buffer. The first time a
178 back buffer name is allocated for a window, the window becomes
179 double-buffered and the back buffer name is associated with the window.
180 Subsequently, the window already is a double-buffered window, and nothing
181 about the window changes when a new back buffer name is allocated, except
182 that the new back buffer name is associated with the window. The window
183 remains double-buffered until either the window is destroyed or until all of the
184 back buffer names for the window are deallocated.
185 </para>
186 <para>
187 In general, both the front and back buffers are treated the same.
188 particular, here are some important characteristics:
189 </para>
190 <itemizedlist>
191   <listitem>
192     <para>
193 Only one buffer per window can be visible at a time (the front buffer).
194     </para>
195   </listitem>
196   <listitem>
197     <para>
198 Both buffers associated with a window have the same visual type, depth,
199 width, height, and shape as the window.
200     </para>
201   </listitem>
202   <listitem>
203     <para>
204 Both buffers associated with a window are "visible" (or "obscured") in
205 the same way. When an Expose event is generated for a window, both
206 buffers should be considered to be damaged in the exposed area.
207 Damage that occurs to either buffer will result in an Expose event on
208 the window. When a double-buffered window is exposed, both buffers
209 are tiled with the window background, exactly as stated by the core
210 protocol. Even though the back buffer is not visible, terms such as
211 obscure apply to the back buffer as well as to the front buffer.
212     </para>
213   </listitem>
214   <listitem>
215     <para>
216 It is acceptable at any time to pass a BACKBUFFER in any request,
217 notably any core or extension drawing request, that expects a
218 DRAWABLE.  This enables an application to draw directly into
219 BACKBUFFERs in the same fashion as it would draw into any other
220 DRAWABLE.
221     </para>
222   </listitem>
223   <listitem>
224     <para>
225 It is an error (Window) to pass a BACKBUFFER in a core request that
226 expects a Window.
227     </para>
228   </listitem>
229   <listitem>
230     <para>
231 A BACKBUFFER will never be sent by core X in a reply, event, or
232 error where a Window is specified.
233     </para>
234   </listitem>
235   <listitem>
236     <para>
237 If core X11 backing-store and save-under applies to a double-buffered
238 window, it applies to both buffers equally.
239     </para>
240   </listitem>
241   <listitem>
242     <para>
243 If the core ClearArea request is executed on a double-buffered window,
244 the same area in both the front and back buffers is cleared.
245     </para>
246   </listitem>
247 </itemizedlist>
248
249 <para>
250 The effect of passing a window to a request that accepts a
251 <function>DRAWABLE</function> is
252 unchanged by this extension. The window and front buffer are synonomous
253 with each other. This includes obeying the <function>GetImage</function>
254 semantics and the
255 subwindow-mode semantics if a core graphics context is involved. Regardless
256 of whether the window was explicitly passed in a
257 <function>GetImage</function> request, or
258 implicitly referenced (that is, one of the window’s ancestors was passed in the
259 request), the front (that is, visible) buffer is always referenced. Thus,
260 DBE-naive screen dump clients will always get the front buffer.
261 <function>GetImage</function> on
262 a back buffer returns undefined image contents for any obscured regions of the
263 back buffer that fall within the image.
264 </para>
265 <para>
266 Drawing to a back buffer always uses the clip region that would be used to
267 draw to the front buffer with a GC subwindow-mode of
268 <function>ClipByChildren</function>. If
269 an ancestor of a double-buffered window is drawn to with a core GC having a
270 subwindow-mode of IncludeInferiors, the effect on the double-buffered
271 window’s back buffer depends on the depth of the double-buffered window
272 and the ancestor. If the depths are the same, the contents of the back buffer
273 of the double-buffered window are not changed. If the depths are different,
274 the contents of the back buffer of the double-buffered window are undefined
275 for the pixels that the <function>IncludeInferiors</function> drawing touched.
276 </para>
277
278
279 <para>
280 DBE adds no new events. DBE does not extend the semantics of any existing
281 events with the exception of adding a new DRAWABLE type called
282 BACKBUFFER. If events, replies, or errors that contain a DRAWABLE (for
283 example, <function>GraphicsExpose</function>) are generated in response to
284 a request, the
285 DRAWABLE returned will be the one specified in the request.
286 </para>
287 <para>
288 DBE advertises which visuals support double-buffering.
289 </para>
290 <para>
291 DBE does not include any timing or synchronization facilities. Applications
292 that need such facilities (for example, to maintain a constant frame rate)
293 should 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>
300 The basic philosophy of DBE is that both buffers are treated the same by core
301 X window management operations.
302 </para>
303 <para>
304 When the core <function>DestroyWindow</function> is executed on a
305 double-buffered window, both buffers associated with the window are
306 destroyed, and all back buffer names associated with the window are freed.
307 </para>
308 <para>
309 If the core <function>ConfigureWindow</function> request changes the size
310 of a window, both buffers assume the new size. If the window’s size
311 increases, the effect on the buffers depends on whether the implementation
312 honors bit gravity for buffers.
313 If bit gravity is implemented, then the contents of both buffers are moved in
314 accordance with the window’s bit gravity (see the core
315 <function>ConfigureWindow</function>
316 request), and the remaining areas are tiled with the window background. If
317 bit gravity is not implemented, then the entire unobscured region of both
318 buffers is tiled with the window background. In either case,
319 <function>Expose</function> events are
320 generated for the region that is tiled with the window background.
321 If the core GetGeometry request is executed on a BACKBUFFER, the
322 returned x, y, and border-width will be zero.
323 </para>
324 <para>
325 If the Shape extension
326 <function>ShapeRectangles</function>,
327 <function>ShapeMask</function>,
328 <function>ShapeCombine</function>, or
329 <function>ShapeOffset</function>
330 request is executed on a double-buffered window, both buffers
331 are reshaped to match the new window shape. The region difference is the
332 following:
333 </para>
334
335 <literallayout remap='Ds'>
336         D = newshape − oldshape
337 </literallayout>
338
339 <para>
340 It is tiled with the window background in both buffers, and
341 <function>Expose</function>
342 events are generated for D.
343 </para>
344
345 </sect1>
346
347 <sect1 id='Complex_Swap_Actions'>
348 <title>Complex Swap Actions</title>
349 <para>
350 DBE has no explicit knowledge of ancillary buffers (for example, depth buffers
351 or alpha buffers), and only has a limited set of defined swap actions. Some
352 applications may need a richer set of swap actions than DBE provides. Some
353 DBE implementations have knowledge of ancillary buffers, and/or can provide
354 a rich set of swap actions. Instead of continually extending DBE to increase
355 its set of swap actions, DBE provides a flexible "idiom" mechanism. If an
356 application’s needs are served by the defined swap actions, it should use them;
357 otherwise, it should use the following method of expressing a complex swap
358 action as an idiom. Following this policy will ensure the best possible
359 performance across a wide variety of implementations.
360 </para>
361 <para>
362 As suggested by the term "idiom," a complex swap action should be expressed
363 as a group/series of requests. Taken together, this group of requests may be
364 combined into an atomic operation by the implementation, in order to
365 maximize performance. The set of idioms actually recognized for optimization
366 is implementation dependent.
367 To help with idiom expression and
368 interpretation, an idiom must be surrounded by two protocol requests:
369 <function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>.
370 Unless this begin-end pair surrounds the idiom, it may not be recognized
371 by a given implementation, and performance will suffer.
372 </para>
373 <para>
374 For example, if an application wants to swap buffers for two windows, and use
375 core X to clear only certain planes of the back buffers, the application would
376 issue 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
388 a swap action of Untouched.
389     </para>
390   </listitem>
391   <listitem>
392     <para>
393 Core X <function>PolyFillRectangle</function> request to the back buffer of one window.
394     </para>
395   </listitem>
396   <listitem>
397     <para>
398 Core X <function>PolyFillRectangle</function> request to the back buffer of the other
399 window.
400     </para>
401   </listitem>
402   <listitem>
403     <para>
404 <function>DBEEndIdiom</function> request.
405     </para>
406   </listitem>
407 </itemizedlist>
408
409 <para>
410 The <function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>
411 requests do not perform any actions
412 themselves. They are treated as markers by implementations that can
413 combine certain groups/series of requests as idioms, and are ignored by other
414 implementations or for nonrecognized groups/series of requests. If these
415 requests are sent out of order, or are mismatched, no errors are sent, and the
416 requests are executed as usual, though performance may suffer.
417 </para>
418
419 <para>
420
421 An idiom need not include a <function>DBESwapBuffers</function> request.
422 For example, if a swap action of <function>Copied</function> is desired,
423 but 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
427 immediately follow the
428 <function>DBEBeginIdiom</function> request. Also, when the
429 <function>DBESwapBuffers</function> is included in an idiom, that
430 request’s swap action will still be valid, and if the swap action
431 might overlap with another request, then the final result of the idiom must be
432 as if the separate requests were executed serially. For example, if the
433 specified swap action is <function>Untouched</function>, and if a
434 <function>PolyFillRectangle</function> using a client clip
435 rectangle is done to the window’s back buffer after the
436 <function>DBESwapBuffers</function> request, then the contents of the new
437 back buffer (after the idiom) will be the
438 same as if the idiom was not recognized by the implementation.
439 </para>
440 <para>
441 It is highly recommended that Application Programming Interface (API)
442 providers define, and application developers use, "convenience" functions that
443 allow client applications to call one procedure that encapsulates common
444 idioms. These functions will generate the
445 <function>DBEBeginIdiom</function> request, the idiom
446 requests, and <function>DBEEndIdiom</function> request. Usage of these
447 functions will ensure best possible performance across a wide
448 variety of implementations.
449 </para>
450
451 </sect1>
452 </chapter>
453
454 <chapter id='C_Language_Binding'>
455 <title>C Language Binding</title>
456 <para>
457 All identifier The header for this extension is &lt;X11/extensions/Xdbe.h&gt;.
458 names provided by this header begin with Xdbe.
459 </para>
460
461 <sect1 id='Types'>
462 <title>Types</title>
463
464 <para>
465 The type <function>XdbeBackBuffer</function> is a <function>Drawable</function>.
466 </para>
467
468 <para>
469 The 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>
481 The C functions provide direct access to the protocol and add no additional
482 semantics. For complete details on the effects of these functions, refer to the
483 appropriate protocol request, which can be derived by replacing Xdbe at the
484 start of the function name with DBE. All functions that have return type
485 <function>Status</function> will return nonzero for success and
486 zero 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
500 version return to the major and minor DBE protocol version supported by
501 the server. If the DBE library is compatible with the version returned by
502 the server, it returns nonzero. If dpy does not support the DBE extension,
503 or if there was an error during communication with the server, or if the
504 server and library protocol versions are incompatible, it returns zero.
505 No other Xdbe functions may be called before this function. If a client
506 violates this rule, the effects of all subsequent Xdbe calls that it makes
507 are 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
522 visuals support double buffering. The argument num_screens specifies how
523 many elements there are in the screen_specifiers list. Each drawable in
524 screen_specifiers designates a screen for which the supported visuals are
525 being requested. If num_screens is zero, information for all screens is
526 requested. In this case, upon return from this function, num_screens will
527 be set to the number of screens that were found. If an error occurs,
528 this function returns NULL; otherwise, it returns a pointer to a list of
529 <function>XdbeScreenVisualInfo</function>
530 structures of length num_screens.  The nth element in the returned list
531 corresponds to the nth drawable in the screen_specifiers list, unless
532
533 element in the returned list corresponds to the nth screen of the server,
534 starting with screen zero.
535 </para>
536
537
538 <para>
539 The XdbeScreenVisualInfo structure has the following fields:
540 </para>
541 <literallayout remap='Ds'>
542 int                     count      number of items in visinfo
543 XdbeVisualInfo*    visinfo     list of visuals and depths for this screen
544 </literallayout>
545
546 <para>
547 The <function>XdbeVisualInfo</function> structure has the following fields:
548 </para>
549
550 <literallayout remap='Ds'>
551 VisualID         visual    one visual ID that supports double-buffering
552 int              depth     depth of visual in bits
553 int              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
583 to refer to the back buffer of the specified window. The swap_action is a
584 hint to indicate the swap_action that will likely be used in subsequent
585 calls to <olink targetdoc='dbelib' targetptr='XdbeSwapBuffers'><function>XdbeSwapBuffers</function></olink>.  The actual swap_action
586 used in calls to <olink targetdoc='dbelib' targetptr='XdbeSwapBuffers'><function>XdbeSwapBuffers</function></olink> does not have to be
587 the same as the swap_action passed to this function, though clients are
588 encouraged 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
601 drawable ID, buffer, that was obtained via
602 <olink targetdoc='dbelib' targetptr='XdbeAllocateBackBufferName'><function>XdbeAllocateBackBufferName</function></olink>. The buffer must be a valid
603 name 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
618 for a list of windows. The argument num_windows specifies how many windows
619 are to have their buffers swapped; it is the number of elements in the
620 swap_info array. The argument swap_info specifies the information needed
621 per window to do the swap.
622 </para>
623 <para>
624 The XdbeSwapInfo structure has the following fields:
625 </para>
626
627 <literallayout remap='Ds'>
628 Window              swap_window    window for which to swap buffers
629 XdbeSwapAction      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
641 sequence. See
642 <link linkend='Complex_Swap_Actions'>
643 <xref linkend='Complex_Swap_Actions'></xref></link>
644 for 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
668 the specified buffer.
669 </para>
670 <para>
671 The XdbeBackBufferAttributes structure has the following fields:
672 </para>
673
674 <literallayout remap='Ds'>
675 Window           window           window that buffer belongs to
676 </literallayout>
677
678 <para>
679 If buffer is not a valid <function>XdbeBackBuffer</function>, window is
680 set to None.
681 </para>
682 <para>
683 The returned <function>XdbeBackBufferAttributes</function> structure
684 can 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>
691 The <function>XdbeBufferError</function> structure has the following fields:
692 </para>
693 <literallayout remap='Ds'>
694 int                 type
695 Display *           display       Display the event was read from
696 XdbeBackBuffer      buffer        resource id
697 unsigned long       serial        serial number of failed request
698 unsigned char       error code    error base + <function>XdbeBadBuffer</function>
699 unsigned char       request code  Major op-code of failed request
700 unsigned 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>
709 We wish to thank the following individuals who have contributed their time
710 and talent toward shaping the DBE specification:
711 </para>
712 <para>
713 T. Alex Chen, IBM; Peter Daifuku, Silicon Graphics, Inc.; Ian Elliott,
714 Hewlett-Packard Company; Stephen Gildea, X Consortium, Inc.; Jim Graham,
715 Sun; Larry Hare, AGE Logic; Jay Hersh, X Consortium, Inc.; Daryl Huff,
716 Sun; Deron Dann Johnson, Sun; Louis Khouw, Sun; Mark Kilgard, Silicon
717 Graphics, Inc.; Rob Lembree, Digital Equipment Corporation; Alan Ricker,
718 Metheus; Michael Rosenblum, Digital Equipment Corporation; Bob Scheifler,
719 X Consortium, Inc.; Larry Seiler, Digital Equipment Corporation; Jeanne
720 Sparlin Smith, IBM; Jeff Stevenson, Hewlett-Packard Company; Walter
721 Strand, Metheus; Ken Tidwell, Hewlett-Packard Company; and David P.
722 Wiggins, X Consortium, Inc.
723 </para>
724 <para>
725 Mark provided the impetus to start the DBE project. Ian wrote the first draft
726 of the specification. David served as architect.
727 </para>
728
729 </chapter>
730 <chapter id='References'>
731 <title>References</title>
732 <para>
733 Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension
734 Specification Version 3.3."
735 </para>
736 <para>
737 Tim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins, "X
738 Synchronization Extension Version 3.0."
739 </para>
740 </chapter>
741 </book>