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">
6 <!-- lifted from troff+ms+XMan by doclifter -->
10 <title>Extending X for Double-Buffering, Multi-Buffering, and Stereo</title>
11 <releaseinfo>X Version 11, Release 6.4</releaseinfo>
15 <firstname>Jeffrey</firstname><surname>Friedberg</surname>
18 <firstname>Larry</firstname><surname>Seiler</surname>
21 <firstname>Jeff</firstname><surname>Vroom</surname>
24 <copyright><year>1989</year><holder>Digital Equipment Corporation</holder></copyright>
25 <copyright><year>1989</year><holder>X Consortium</holder></copyright>
26 <copyright><year>1994</year><holder>X Consortium</holder></copyright>
27 <releaseinfo>Version 3.3</releaseinfo>
28 <affiliation><orgname>X Consortium</orgname></affiliation>
32 Permission to use, copy, modify, and distribute this documentation for any
33 purpose and without fee is hereby granted, provided that the above copyright
34 notice and this permission notice appear in all copies.
35 Digital Equipment Corporation makes no representations
36 about the suitability for any purpose of the information in
37 this document. This documentation is provided "as is"
38 without express or implied warranty. This document
42 Permission is hereby granted, free of charge, to any person obtaining a copy
43 of this software and associated documentation files (the ``Software''), to deal
44 in the Software without restriction, including without limitation the rights
45 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
46 copies of the Software, and to permit persons to whom the Software is
47 furnished to do so, subject to the following conditions:
50 The above copyright notice and this permission notice shall be included in
51 all copies or substantial portions of the Software.
54 THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
55 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
56 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
57 X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
58 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
59 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
62 Except as contained in this notice, the name of the X Consortium shall not be
63 used in advertising or otherwise to promote the sale, use or other dealings
64 in this Software without prior written authorization from the X Consortium.
67 <emphasis remap='I'>X Window System</emphasis> is a trademark of X Consortium, Inc.
76 The <emphasis remap='I'>Multi-Buffering</emphasis> extension described here
77 was a draft standard of the X Consortium prior to Release 6.1. It has been
78 superseded by the Double Buffer
79 Extension (DBE). DBE is an X Consortium Standard as of Release 6.1.
82 <sect1 id="introduction">
83 <title>Introduction</title>
86 Several proposals have been written that address some of the
87 issues surrounding the support of double-buffered, multi-buffered,
88 and stereo windows in the X Window System:
94 <emphasis remap='I'>Extending X for Double-Buffering,</emphasis>
95 Jeffrey Friedberg, Larry Seiler, Randi Rost.
100 <emphasis remap='I'>(Proposal for) Double-Buffering Extensions</emphasis>,
106 <emphasis remap='I'>An Extension to X.11 for Displays with Multiple Buffers,</emphasis>
107 David S.H. Rosenthal.
112 <emphasis remap='I'>A Multiple Buffering/Stereo Proposal</emphasis>,
119 The authors of this proposal have tried to unify the above documents
120 to yield a proposal that incorporates support for double-buffering,
121 multi-buffering, and stereo in a way that is acceptable to all concerned.
129 Clients should be able to:
135 Associate multiple buffers with a window.
140 Paint in any buffer associated with a window.
145 Display any buffer associated with a window.
150 Display a series of buffers in a window in rapid succession
151 to achieve a <emphasis remap='I'>smooth</emphasis> animation.
156 Request simultaneous display of different buffers in different windows.
162 In addition, the extension should:
168 Allow existing X applications to run unchanged.
173 Support a range of implementation methods that can capitalize on
174 existing hardware features.
181 <sect1 id="image_buffers">
182 <title>Image Buffers</title>
185 Normal windows are created using the standard
186 <function>CreateWindow</function> request:
189 <literallayout class="monospaced">
194 visual : VISUALID or CopyFromParent
196 width, height : INT16
199 value_list : LISTofVALUE
203 This request allocates a set of window attributes and
204 a buffer into which an image can be drawn.
205 The contents of this <emphasis remap='I'>image buffer</emphasis> will
206 be displayed when the window is mapped to the screen.
210 To support double-buffering and multi-buffering,
211 we introduce the notion that additional image buffers can
212 be created and bound together to form groups.
213 The following rules will apply:
219 All image buffers in a group will have the same
220 visual type, depth, and geometry (ie: width and height).
225 Only one image buffer per group can be displayed
231 Draw operations can occur to any image buffer at
237 Window management requests (<function>MapWindow</function>, <function>DestroyWindow</function>,
238 <function>ConfigureWindow</function>, etc...)
239 affect all image buffers associated with a window.
244 Appropriate resize and exposure events will be generated
245 for every image buffer that is affected by a window
246 management operation.
252 By allowing draw operations to occur on any image buffer at any time,
253 a client could, on a multi-threaded multi-processor server,
254 simultaneously build up images for display.
255 To support this, each buffer must have its own resource ID.
256 Since buffers are different than windows and pixmaps
257 (buffers are not hierarchical and pixmaps cannot be displayed)
258 a new resource, <function>Buffer</function>, is introduced.
259 Furthermore, a <function>Buffer</function> is also a <function>Drawable</function>, thus
260 draw operations may also be performed on buffers simply
261 by passing a buffer ID to the existing pixmap/window
266 To allow existing X applications to work unchanged, we assume
267 a window ID passed in a draw request, for a multi-buffered
268 window, will be an <emphasis remap='I'>alias</emphasis> for the ID of the currently
269 displayed image buffer. Any draw requests (eq: <function>GetImage</function>) on
270 the window will be relative to the displayed image buffer.
274 In window management requests, only a window ID will be
275 accepted. Requests like <function>QueryTree</function>, will continue to
276 return only window ID's. Most events will return
277 just the window ID. Some new events, described in a subsequent
278 section, will return a buffer ID.
282 When a window has backing store the contents of the window
283 are saved off-screen. Likewise, when the contents of an image
284 buffer of a multi-buffer window is saved off-screen, it is
285 said to have backing store. This applies to all image buffers,
286 whether or not they are selected for display.
290 In some multi-buffer implementations, undisplayed buffers might be
291 implemented using pixmaps. Since the contents of pixmaps exist
292 off-screen and are not affected by occlusion, these image buffers
293 in effect have backing store.
297 On the other hand, both the displayed and undisplayed image buffers
298 might be implemented using a subset of the on-screen pixels.
299 In this case, unless the contents of an image buffer are saved
300 off-screen, these image buffers in effect do not have backing store.
304 Output to any image buffer of an unmapped multi-buffered window
305 that does not have backing store is discarded. Output to any
306 image buffer of a mapped multi-buffer window will be performed;
307 however, portions of an image buffer may be occluded or clipped.
311 When an unmapped multi-buffered window becomes mapped, the contents
312 of any image buffer buffer that did not have backing store is
313 tiled with the background and zero or more exposure events are
314 generated. If no background is defined for the window, then
315 the screen contents are not altered and the contents of any
316 undisplayed image buffers are undefined. If backing store was
317 maintained for an image buffer, then no exposure events are generated.
321 <sect1 id="new_requests">
322 <title>New Requests</title>
325 The new request, <function>CreateImageBuffers</function>, creates a group of
326 image buffers and associates them with a normal X window:
329 <literallayout class="monospaced">
332 buffers : LISTofBUFFER
333 update_action : {Undefined,Background,Untouched,Copied}
334 update_hint : {Frequent,Intermittent,Static}
336 number_buffers : CARD16
338 (Errors: Window, IDChoice, Value)
342 One image buffer will be associated with each ID passed in
343 <emphasis remap='I'>buffers</emphasis>.
344 The first buffer of the list is referred to as buffer[0], the next
345 buffer[1], and so on. Each buffer will have the same visual type
346 and geometry as the window.
347 Buffer[0] will refer to the image buffer already associated
348 with the window ID and its contents will not be modified.
349 The displayed image buffer attribute is set to buffer[0].
353 Image buffers for the remaining ID's (buffer[1],...) are allocated.
354 If the window is mapped, or if these image buffers have backing
355 store, their contents will be tiled with the window background
356 (if no background is defined, the buffer contents are undefined),
357 and zero or more expose events will be generated for each of these
358 buffers. The contents of an image buffer is undefined when
359 the window is unmapped and the buffer does not have backing store.
363 If the window already has a group of image buffers
364 associated with it (ie: from a previous <function>CreateImageBuffers</function> request)
365 the actions described for <function>DestroyImageBuffers</function> are performed first
366 (this will delete the association of the previous buffer ID's and
367 their buffers as well as de-allocate all buffers except for the
368 one already associated with the window ID).
372 To allow a server implementation to efficiently allocate the
373 buffers, the total number of buffers required and
374 the update action (how they will behave during an update)
375 is specified "up front" in the request.
376 If the server cannot allocate all the buffers requested, the
377 total number of buffers actually allocated will be returned.
378 No <function>Alloc</function> errors will be generated \- buffer[0] can
379 always be associated with the existing displayed image buffer.
383 For example, an application that wants to animate a short movie
384 loop may request 64 image buffers. The server may only be able to
385 support 16 image buffers of this type, size, and depth.
386 The application can then decide 16 buffers is sufficient and may
387 truncate the movie loop, or it may decide it really needs
388 64 and will free the buffers and complain to the user.
392 One might be tempted to provide a request that inquires whether
393 <emphasis remap='I'>n</emphasis>
394 buffers of a particular type, size, and depth
395 <emphasis remap='I'>could</emphasis> be allocated.
396 But if the query is decoupled from the actual allocation,
397 another client could sneak in and take the buffers before the
398 original client has allocated them.
402 While any buffer of a group can be selected for display,
403 some applications may display buffers in a predictable order
404 (ie: the movie loop application). The
405 <emphasis remap='I'>list order</emphasis>
406 (buffer[0], buffer[1], ...) will be used as a hint by the
407 server as to which buffer will be displayed next.
408 A client displaying buffers in this order may see a
409 performance improvement.
413 <emphasis remap='I'>update_action</emphasis> indicates what should happen to a previously
414 displayed buffer when a different buffer becomes displayed.
415 Possible actions are:
420 <term>Undefined</term>
423 The contents of the buffer that was
424 last displayed will become undefined after the update. This
425 is the most efficient action since it allows the implementation
426 to trash the contents of the buffer if it needs to.
431 <term>Background</term>
434 The contents of the buffer that was
435 last displayed will be set to the background of the window after the update.
436 The background action allows devices to use a fast clear
437 capability during an update.
442 <term>Untouched</term>
445 The contents of the buffer that was
446 last displayed will be untouched after the update. Used
447 primarily when cycling through images that have already
456 The contents of the buffer that was
457 last displayed will become the same as those that are being
458 displayed after the update. This is useful when incrementally
468 <emphasis remap='I'>update_hint</emphasis> indicates how often the client will
469 request a different buffer to be displayed.
470 This hint will allow smart server implementations to choose the
471 most efficient means to support a multi-buffered window based
472 on the current need of the application (dumb implementations
473 may choose to ignore this hint). Possible hints are:
478 <term>Frequent</term>
481 An animation or movie loop is
482 being attempted and the fastest, most efficient means for
483 multi-buffering should be employed.
488 <term>Intermittent</term>
491 The displayed image will be
492 changed every so often. This is common for images that are
493 displayed at a rate slower than a second. For example, a
494 clock that is updated only once a minute.
502 The displayed image buffer will
503 not be changed any time soon. Typically set by an application
504 whenever there is a pause in the animation.
511 To display an image buffer the following request can be used:
514 <literallayout class="monospaced">
516 buffers : LISTofBUFFER
520 (Errors: Buffer, Match)
524 The image buffers listed will become displayed as simultaneously
525 as possible and the update action, bound at
526 <function>CreateImageBuffers</function>
527 time, will be performed.
531 A list of buffers is specified to
532 allow the server to efficiently change the display of more than one
533 window at a time (ie: when a global screen swap method is used).
534 Attempting to simultaneously display
535 multiple image buffers from the same window is an error
536 (<function>Match</function>) since it violates the rule that only one
537 image buffer per group can be displayed at a time.
541 If a specified buffer is already displayed,
542 any delays and update action will still be
543 performed for that buffer. In this instance,
544 only the update action of <emphasis remap='I'>Background</emphasis>
546 <emphasis remap='I'>Undefined</emphasis>) will have any affect on the
547 contents of the displayed buffer. These semantics allow
548 an animation application to successfully execute
549 even when there is only a single buffer available
554 When a <function>DisplayImageBuffers</function> request is made to an unmapped
555 multi-buffered window, the effect of the update action depends
556 on whether the image buffers involved have backing store.
557 When the target of the update action is an image buffer that
558 does not have backing store, output is discarded. When the
559 target image buffer does have backing store, the update is performed;
560 however, when the source of the update is an image buffer does not
561 have backing store (as in the case of update action
562 <emphasis remap='I'>Copied</emphasis>), the
563 contents of target image buffer will become undefined.
567 <emphasis remap='I'>min_delay</emphasis> and
568 <emphasis remap='I'>max_delay</emphasis> put a bound on how long the
569 server should wait before processing the display request.
570 For each of the windows to be updated by this request, at least
571 <emphasis remap='I'>min_delay</emphasis> milli-seconds should elapse since
573 time any of the windows were updated; conversely, no window
574 should have to wait more than <emphasis remap='I'>max_delay</emphasis>
575 milli-seconds before being updated.
579 <emphasis remap='I'>min_delay</emphasis> allows an application to
580 <emphasis remap='I'>slow down</emphasis> an animation or movie loop so that
582 synchronized at a rate the server can support given the current load.
583 For example, a <emphasis remap='I'>min_delay</emphasis> of 100 indicates the
585 wait at least 1/10 of a second since the last time any of the
586 windows were updated. A <emphasis remap='I'>min_delay</emphasis> of zero
587 indicates no waiting is necessary.
591 <emphasis remap='I'>max_delay</emphasis> can be thought of as an additional
592 delay beyond <emphasis remap='I'>min_delay</emphasis> the server is allowed
594 to facilitate such things as efficient update of multiple windows.
595 If <emphasis remap='I'>max_delay</emphasis> would require an update before
596 <emphasis remap='I'>min_delay</emphasis>
597 is satisfied, then the server should process the display request as
598 soon as the <emphasis remap='I'>min_delay</emphasis> requirement is met. A
599 typical value for <emphasis remap='I'>max_delay</emphasis> is zero.
603 To implement the above functionality, the time since the last
604 update by a <function>DisplayImageBuffers</function> request for each
606 window needs to be saved as state by the server.
607 The server may delay execution of the <function>DisplayImageBuffers</function>
608 request until the appropriate time (e.g. by requeuing the
609 request after computing the timeout);
610 however, the entire request must be processed in one operation.
611 Request execution indivisibility must be maintained. When
612 a server is implemented with internal concurrency, the
613 extension must adhere to the same concurrency semantics
614 as those defined for the core protocol.
618 To explicitly clear a rectangular area of an image buffer to
619 the window background, the following request can be used:
622 <literallayout class="monospaced">
629 (Errors: Buffer, Value)
633 Like the X <function>ClearArea</function> request,
634 <emphasis remap='I'>x</emphasis> and <emphasis remap='I'>y</emphasis>
636 the window's origin and specify the upper-left corner of the rectangle.
637 If <emphasis remap='I'>width</emphasis> is zero, it is replaced with the
639 minus <emphasis remap='I'>x</emphasis>. If
640 <emphasis remap='I'>height</emphasis> is zero it is replaced with the current
641 window height minus <emphasis remap='I'>y</emphasis>. If the window has a
642 defined background tile, the rectangle is tiled with a plane mask of all ones,
643 a function of <emphasis remap='I'>Copy</emphasis>, and a subwindow-mode of
644 <emphasis remap='I'>ClipByChildren</emphasis>.
645 If the window has background <emphasis remap='I'>None</emphasis>, the
646 contents of the buffer
647 are not changed. In either case, if
648 <emphasis remap='I'>exposures</emphasis> is true, then one or
649 more exposure events are generated for regions of the rectangle that are
650 either visible or are being retained in backing store.
655 The group of image buffers allocated by a
656 <function>CreateImageBuffers</function>
657 request can be destroyed with the following request:
660 <literallayout class="monospaced">
668 The association between the buffer ID's and their corresponding
669 image buffers are deleted. Any image buffers not selected for
670 display are de-allocated. If the window is not multi-buffered,
671 the request is ignored.
676 <sect1 id="attributes">
677 <title>Attributes</title>
680 The following attributes will be associated with each window that
684 <literallayout class="monospaced">
685 displayed_buffer : CARD16
686 update_action : {Undefined,Background,Untouched,Copied}
687 update_hint : {Frequent,Intermittent,Static}
688 window_mode : {Mono,Stereo}
689 buffers : LISTofBUFFER
693 <emphasis remap='I'>displayed_buffer</emphasis> is set to the
694 <emphasis remap='I'>index</emphasis> of the currently
695 displayed image buffer (for stereo windows, this will be
696 the index of the left buffer \- the index of the right buffer
697 is simply <emphasis remap='I'>index</emphasis>+1).
698 <emphasis remap='I'>window_mode</emphasis> indicates whether this window is
699 <emphasis remap='I'>Mono</emphasis> or <emphasis remap='I'>Stereo</emphasis>.
700 The ID for each buffer associated with the window is recorded
701 in the <emphasis remap='I'>buffers</emphasis> list.
702 The above attributes can be queried with the following request:
705 <literallayout class="monospaced">
706 GetMultiBufferAttributes
709 displayed_buffer : CARD16
710 update_action : {Undefined,Background,Untouched,Copied}
711 update_hint : {Frequent,Intermittent,Static}
712 window_mode : {Mono,Stereo}
713 buffers : LISTofBUFFER
715 (Errors: Window, Access, Value)
719 If the window is not multi-buffered, a <function>Access</function> error
721 The only multi-buffer attribute that can be explicitly set
722 is <emphasis remap='I'>update_hint</emphasis>. Rather than have a specific
723 request to set this attribute, a generic set request is provided to
724 allow for future expansion:
727 <literallayout class="monospaced">
728 SetMultiBufferAttributes
731 value_list : LISTofVALUE
733 (Errors: Window, Match, Value)
737 If the window is not multi-buffered, a <function>Match</function> error
739 The following attributes are maintained for each buffer of a
740 multi-buffered window:
743 <literallayout class="monospaced">
745 event_mask : SETofEVENT
747 side : {Mono,Left,Right}
751 <emphasis remap='I'>window</emphasis> indicates the window this buffer is
753 <emphasis remap='I'>event_mask</emphasis> specifies which events, relevant to
754 buffers, will be sent back to the client via the associated buffer ID
755 (initially no events are selected).
756 <emphasis remap='I'>index</emphasis> is the list position (0, 1, ...) of the
758 <emphasis remap='I'>side</emphasis> indicates whether this buffer is
760 the left side or right side of a stereo window.
761 For non-stereo windows, this attribute will be set to
762 <emphasis remap='I'>Mono</emphasis>.
763 These attributes can be queried with the following request:
766 <literallayout class="monospaced">
771 event_mask : SETofEVENT
773 side : {Mono,Left,Right}
775 (Errors: Buffer, Value)
779 The only buffer attribute that can be explicitly set
780 is <emphasis remap='I'>event_mask</emphasis>.
781 The only events that are valid are
782 <function>Expose</function> and the new
783 <function>ClobberNotify</function> and <function>UpdateNotify</function>
784 event (see Events section below). <!-- xref -->
785 A <function>Value</function> error will be generated if an event not
786 selectable for a buffer is specified in an event mask.
787 Rather than have a specific request
788 to set this attribute, a generic set request is provided to
789 allow for future expansion:
792 <literallayout class="monospaced">
796 value_list : LISTofVALUE
798 (Errors: Buffer, Value)
802 Clients may want to query the server about basic multi-buffer
803 and stereo capability on a per screen basis. The following request
804 returns a large list of information
805 that would most likely be read once by Xlib for each screen, and used as a
806 data base for other Xlib queries:
809 <literallayout class="monospaced">
813 info : LISTofSCREEN_INFO
817 Where <function>SCREEN_INFO</function> and
818 <function>BUFFER_INFO</function> are defined as:
821 <literallayout class="monospaced">
822 SCREEN_INFO : [ normal_info : LISTofBUFFER_INFO,
823 stereo_info : LISTofBUFFER_INFO ]
825 BUFFER_INFO : [ visual : VISUALID,
826 max_buffers : CARD16,
831 Information regarding multi-buffering of normal (mono) windows
832 is returned in the <emphasis remap='I'>normal_info</emphasis> list.
833 The <emphasis remap='I'>stereo_info</emphasis>
834 list contains information about stereo windows.
835 If the <emphasis remap='I'>stereo_info</emphasis> list is empty, stereo
837 not supported on the screen. If
838 <emphasis remap='I'>max_buffers</emphasis> is zero,
839 the maximum number of buffers for the depth and visual is
840 a function of the size of the created window and current
845 The following request returns the major and minor version numbers
849 <literallayout class="monospaced">
857 The version numbers are an escape hatch in case future revisions of
858 the protocol are necessary. In general, the major version would
859 increment for incompatible changes, and the minor version would
860 increment for small upward compatible changes. Barring changes, the
861 major version will be 1, and the minor version will be 1.
866 <title>Events</title>
869 All events normally generated for single-buffered
870 windows are also generated for multi-buffered windows.
871 Most of these events (ie: <function>ConfigureNotify</function>) will
872 only be generated for the window and not for each buffer.
873 These events will return a window ID.
877 <function>Expose</function> events will be generated for both the window
878 and any buffer affected. When this event is generated for
879 a buffer, the same event structure will be used
880 but a buffer ID is returned instead of a window ID.
881 Clients, when processing these events, will know whether an
882 ID returned in an event structure is for a window or a buffer
883 by comparing the returned ID to the ones returned when the
884 window and buffer were created.
888 <function>GraphicsExposure</function> and
889 <function>NoExposure</function> are generated
890 using whatever ID is specified in the graphics operation.
891 If a window ID is specified, the event will contain the
892 window ID. If a buffer ID is specified, the event will
893 contain the buffer ID.
896 In some implementations, moving a window
897 over a multi-buffered window may cause one or more of its buffers
898 to get overwritten or become unwritable. To allow a
899 client drawing into one of these buffers the opportunity
900 to stop drawing until some portion of the buffer is
901 writable, the following event is added:
904 <literallayout class="monospaced">
907 state : {Unclobbered,PartiallyClobbered,FullyClobbered}
911 The <function>ClobberNotify</function> event is reported to clients selecting
912 <emphasis remap='I'>ClobberNotify</emphasis> on a buffer. When a buffer
914 or partially clobbered becomes unclobbered, an event with
915 <emphasis remap='I'>Unclobbered</emphasis>
916 is generated. When a buffer that was unclobbered becomes
917 partially clobbered, an event with
918 <emphasis remap='I'>PartiallyClobbered</emphasis>
919 is generated. When a buffer that was unclobbered or
920 partially clobbered becomes fully clobbered, an event with
921 <emphasis remap='I'>FullyClobbered</emphasis> is generated.
925 <function>ClobberNotify</function> events on a given buffer are
926 generated before any <function>Expose</function> events on that buffer,
927 but it is not required that all <function>ClobberNotify</function>
928 events on all buffers be generated before all
929 <function>Expose</function> events on all buffers.
933 The ordering of <function>ClobberNotify</function> events with respect
934 to <function>VisibilityNotify</function> events is not constrained.
938 If multiple buffers were used as an image FIFO between an image
939 server and the X display server, then the FIFO manager would like
940 to know when a buffer that was previously displayed, has been
941 undisplayed and updated, as the side effect of a
942 <function>DisplayImageBuffers</function>
943 request. This allows the FIFO manager to load up a future frame as
944 soon as a buffer becomes available. To support this,
945 the following event is added:
948 <literallayout class="monospaced">
954 The <function>UpdateNotify</function> event is reported to clients selecting
955 <emphasis remap='I'>UpdateNotify</emphasis> on a buffer. Whenever a buffer
956 becomes <emphasis remap='I'>updated</emphasis>
957 (e.g. its update action is performed as part of a
958 <function>DisplayImageBuffers</function>
959 request), an <function>UpdateNotify</function> event is generated.
964 <title>Errors</title>
967 The following error type has been added to support
971 <sect2 id="buffer_2">
972 <title>Buffer</title>
974 A value for a BUFFER argument does not name a defined BUFFER.
978 <sect2 id="double_buffering_normal_windows">
979 <title>Double-Buffering Normal Windows</title>
982 The following pseudo-code fragment illustrates how to create and display
983 a double-buffered image:
986 <literallayout class="monospaced">
988 * Create a normal window
990 CreateWindow( W, ... )
993 * Create two image buffers. Assume after display, buffer
994 * contents become "undefined". Assume we will "frequently"
995 * update the display. Abort if we don't get two buffers,
997 n = CreateImageBuffers( W, [B0,B1], Undefined, Frequent )
998 if (n != 2) <abort>
1001 * Map window to the screen
1006 * Draw images using alternate buffers, display every
1007 * 1/10 of a second. Note we draw B1 first so it will
1008 * "pop" on the screen
1012 <draw picture using B1>
1013 DisplayImageBuffers( [B1], 100, 0 )
1015 <draw picture using B0>
1016 DisplayImageBuffers( [B0], 100, 0 )
1020 * Strip image buffers and leave window with
1021 * contents of last displayed image buffer.
1023 DestroyImageBuffers( W )
1028 <sect2 id="multi_buffering_normal_windows">
1029 <title>Multi-Buffering Normal Windows</title>
1032 Multi-buffered images are also supported by these requests.
1033 The following pseudo-code fragment illustrates how to create a
1034 a multi-buffered image and cycle through the images to
1035 simulate a movie loop:
1038 <literallayout class="monospaced">
1040 * Create a normal window
1042 CreateWindow( W, ... )
1045 * Create 'N' image buffers. Assume after display, buffer
1046 * contents are "untouched". Assume we will "frequently"
1047 * update the display. Abort if we don't get all the buffers.
1049 n = CreateImageBuffers( W, [B0,B1,...,B(N-1)], Untouched, Frequent )
1050 if (n != N) <abort>
1053 * Map window to screen
1058 * Draw each frame of movie one per buffer
1061 <draw frame using B(i)>
1064 * Cycle through frames, one frame every 1/10 of a second.
1069 DisplayImageBuffers( [B(i)], 100, 0 )
1075 <sect2 id="stereo_windows">
1076 <title>Stereo Windows</title>
1078 <emphasis remap='I'>How</emphasis> stereo windows are supported on a server
1080 dependent. A server may contain specialized hardware that allows
1081 left and right images to be toggled at field or frame rates. The
1082 stereo affect may only be perceived with the aid of special
1083 viewing glasses. The <emphasis remap='I'>display</emphasis> of a
1084 stereo picture should
1085 be independent of how often the contents of the picture are
1086 <emphasis remap='I'>updated</emphasis> by an application. Double and
1088 of images should be possible regardless of whether the image
1089 is displayed normally or in stereo.
1093 To achieve this goal, a simple extension to normal windows
1094 is suggested. Stereo windows are just like normal windows
1095 except the displayed image is made up of a left image
1096 buffer and a right image buffer. To create a stereo window,
1097 a client makes the following request:
1100 <literallayout class="monospaced">
1104 left, right : BUFFER
1106 visual : VISUALID or CopyFromParent
1108 width, height : INT16
1109 border_width : INT16
1110 value_mask : BITMASK
1111 value_list : LISTofVALUE
1113 (Errors: Alloc, Color, Cursor, Match,
1114 Pixmap, Value, Window)
1118 This request, modeled after the <function>CreateWindow</function> request,
1119 adds just two new parameters: <emphasis remap='I'>left</emphasis> and
1120 <emphasis remap='I'>right</emphasis>.
1121 For stereo, it is essential that one can distinguish whether
1122 a draw operation is to occur on the left image or right image.
1123 While an internal mode could have been added to achieve this,
1124 using two buffer ID's allows clients to simultaneously build up
1125 the left and right components of a stereo image. These
1126 ID's always refer to (are an alias for) the left and right
1127 image buffers that are currently <emphasis remap='I'>displayed</emphasis>.
1131 Like normal windows, the window ID is used whenever a window
1132 management operation is to be performed. Window queries would
1133 also return this window ID (eg: <function>QueryTree</function>) as would most
1134 events. Like the window ID, the left and right buffer ID's
1135 each have their own event mask. They can be set and queried
1136 using the <function>Set/GetBufferAttributes</function> requests.
1140 Using the window ID of a stereo window in a draw request
1141 (eg: <function>GetImage</function>) results in pixels that are
1142 <emphasis remap='I'>undefined</emphasis>.
1143 Possible semantics are that both left and right images get
1144 drawn, or just a single side is operated on (existing applications
1145 will have to be re-written to explicitly use the left and right
1146 buffer ID's in order to successfully create, fetch, and store
1151 Having an explicit <function>CreateStereoWindow</function> request is helpful
1152 in that a server implementation will know from the onset whether
1153 a stereo window is desired and can return appropriate status
1154 to the client if it cannot support this functionality.
1158 Some hardware may support separate stereo and non-stereo modes,
1159 perhaps with different vertical resolutions. For example, the
1160 vertical resolution in stereo mode may be half that of non-stereo
1161 mode. Selecting one mode or the other must be done through some
1162 means outside of this extension (eg: by providing a separate
1163 screen for each hardware display mode). The screen attributes
1164 (ie: x/y resolution) for a screen that supports normal windows,
1165 may differ from a screen that supports stereo windows;
1166 however, all windows, regardless of type, displayed on the
1167 same screen must have the same screen attributes
1168 (ie: pixel aspect ratio).
1172 If a screen that supports stereo windows also supports
1173 normal windows, then the images presented to the left and
1174 right eyes for normal windows should be the same
1175 (ie: have no stereo offset).
1180 <sect2 id="single_buffered_stereo_windows">
1181 <title>Single-Buffered Stereo Windows</title>
1184 The following shows how to create and display a single-buffered
1187 <literallayout class="monospaced">
1189 * Create the stereo window, map it the screen,
1190 * and draw the left and right images
1192 CreateStereoWindow( W, L, R, ... )
1196 <draw picture using L,R>
1200 <sect2 id="double_buffering_stereo_windows">
1201 <title>Double-Buffering Stereo Windows</title>
1204 Additional image buffers may be added to a stereo window
1205 to allow double or multi-buffering of stereo images.
1206 Simply use the the <function>CreateImageBuffers</function> request.
1207 Even numbered buffers (0,2,...) will be left buffers.
1208 Odd numbered buffers (1,3,...) will be right buffers.
1209 Displayable stereo images are formed by consecutive
1210 left/right pairs of image buffers. For example,
1211 (buffer[0],buffer[1]) form the first displayable
1212 stereo image; (buffer[2],buffer[3]) the next;
1217 The <function>CreateImageBuffers</function> request will only create
1218 pairs of left and right image buffers for stereo windows.
1219 By always pairing left and right image
1220 buffers together, implementations might be able to
1221 perform some type of optimization. If an odd number
1222 of buffers is specified, a <function>Value</function> error is generated.
1223 All the rules mentioned at the start of this proposal
1224 still apply to the image buffers supported by a stereo window.
1228 To display a image buffer pair of a multi-buffered stereo image,
1229 either the left buffer ID or right buffer ID may be specified in a
1230 <function>DisplayImageBuffers</function> request, but not both.
1234 To double-buffer a stereo window:
1237 <literallayout class="monospaced">
1239 * Create stereo window and map it to the screen
1241 CreateStereoWindow( W, L, R, ... )
1244 * Create two pairs of image buffers. Assume after display,
1245 * buffer contents become "undefined". Assume we will "frequently"
1246 * update the display. Abort if we did get all the buffers.
1248 n = CreateImageBuffers( W, [L0,R0,L1,R1], Undefined, Frequently )
1249 if (n != 4) <abort>
1252 * Map window to the screen
1257 * Draw images using alternate buffers,
1258 * display every 1/10 of a second.
1262 <draw picture using L1,R1>
1263 DisplayImageBuffers( [L1], 100, 0 )
1265 <draw picture using L0,R0>
1266 DisplayImageBuffers( [L0], 100, 0 )
1272 <sect2 id="multi_buffering_stereo_windows">
1273 <title>Multi-Buffering Stereo Windows</title>
1276 To cycle through <emphasis remap='I'>N</emphasis> stereo images:
1279 <literallayout class="monospaced">
1281 * Create stereo window
1283 CreateStereoWindow( W, L, R, ... )
1286 * Create N pairs of image buffers. Assume after display,
1287 * buffer contents are "untouched". Assume we will "frequently"
1288 * update the display. Abort if we don't get all the buffers.
1290 n = CreateImageBuffers( W, [L0,R0,...,L(N-1),R(N-1)], Untouched, Frequently )
1291 if (n != N*2) <abort>
1294 * Map window to screen
1299 * Draw the left and right halves of each image
1301 foreach stereo image
1302 <draw picture using L(i),R(i)>
1305 * Cycle through images every 1/10 of a second
1309 foreach stereo image
1310 DisplayImageBuffers( [L(i)], 100, 0 )
1315 <sect2 id="protocol_encoding">
1316 <title>Protocol Encoding</title>
1319 The official name of this extension is "Multi-Buffering".
1320 When this string passed to <function>QueryExtension</function> the
1321 information returned should be interpreted as follows:
1326 <term>major-opcode</term>
1329 Specifies the major opcode of this extension.
1330 The first byte of each extension request should
1336 <term>first-event</term>
1339 Specifies the code that will be returned when
1340 <function>ClobberNotify</function> events are generated.
1345 <term>first-error</term>
1348 Specifies the code that will be returned when
1349 <function>Buffer</function> errors are generated.
1356 The following sections describe the protocol
1357 encoding for this extension.
1363 <title>TYPES</title>
1365 <literallayout class="monospaced">
1369 2 CARD16 max-buffers
1374 <literallayout class="monospaced">
1378 #x02000000 ClobberNotify
1379 #x04000000 UpdateNotify
1384 <sect1 id="events_2">
1385 <title>EVENTS</title>
1387 <literallayout class="monospaced">
1388 <function>ClobberNotify</function>
1389 1 see <emphasis remap='I'>first-event</emphasis> code
1391 2 CARD16 sequence number
1395 1 PartiallyClobbered
1400 <literallayout class="monospaced">
1401 <function>UpdateNotify</function>
1402 1 <emphasis remap='I'>first-event</emphasis>+1 code
1404 2 CARD16 sequence number
1410 <sect1 id="errors_2">
1411 <title>ERRORS</title>
1413 <literallayout class="monospaced">
1414 <function>Buffer</function>
1416 1 see <emphasis remap='I'>first-error</emphasis> code
1417 2 CARD16 sequence number
1418 4 CARD32 bad resource id
1419 2 CARD16 minor-opcode
1420 1 CARD8 major-opcode
1426 <sect1 id="requests">
1427 <title>REQUESTS</title>
1429 <literallayout class="monospaced">
1430 <function>GetBufferVersion</function>
1431 1 see <emphasis remap='I'>major-opcode</emphasis> major-opcode
1437 2 CARD16 sequencenumber
1439 1 CARD8 majorversion number
1440 1 CARD8 minorversion number
1444 <function>CreateImageBuffers</function>
1446 1 see <emphasis remap='I'>major-opcode</emphasis> major-opcode
1460 4n LISTofBUFFER buffer-list
1464 2 CARD16 sequencenumber
1466 2 CARD16 number-buffers
1470 <function>DestroyImageBuffers</function>
1472 1 see <emphasis remap='I'>major-opcode</emphasis> major-opcode
1478 <function>DisplayImageBuffers</function>
1481 1 see <emphasis remap='I'>major-opcode</emphasis> major-opcode
1485 4n LISTofBUFFER buffer-list
1488 <function>SetMultiBufferAttributes</function>
1490 1 see <emphasis remap='I'>major-opcode</emphasis> major-opcode
1494 4 BITMASK value-mask (has n bits set to 1)
1495 #x00000001 update-hint
1496 4n LISTofVALUE value-list
1504 <function>GetMultiBufferAttributes</function>
1506 1 see <emphasis remap='I'>major-opcode</emphasis> major-opcode
1513 2 CARD16 sequencenumber
1515 2 CARD16 displayed-buffer
1529 4n LISTofBUFFER buffer list
1532 <function>SetBufferAttributes</function>
1534 1 see <emphasis remap='I'>major-opcode</emphasis> major-opcode
1538 4 BITMASK value-mask (has n bits set to 1)
1539 #x00000001 event-mask
1540 4n LISTofVALUE value-list
1542 4 SETofBUFFER_EVENT event-mask
1544 <function>GetBufferAttributes</function>
1546 1 see <emphasis remap='I'>major-opcode</emphasis> major-opcode
1553 2 CARD16 sequencenumber
1556 4 SETofBUFFER_EVENT event-mask
1564 <function>GetBufferInfo</function>
1566 1 see <emphasis remap='I'>major-opcode</emphasis> major-opcode
1573 2 CARD16 sequencenumber
1574 4 2(n+m) replylength
1575 2 n number BUFFER_INFO in normal-info
1576 2 m number BUFFER_INFO in stereo-info
1578 8n LISTofBUFFER_INFO normal-info
1579 8m LISTofBUFFER_INFO stereo-info
1581 <function>CreateStereoWindow</function>
1583 1 see <emphasis remap='I'>major-opcode</emphasis> major-opcode
1585 2 11+n requestlength
1596 2 CARD16 border-width
1603 4 BITMASK value-mask (has n bits set to 1)
1604 encodings are the same
1606 4n LISTofVALUE value-list
1607 encodings are the same
1611 <function>ClearImageBufferArea</function>
1613 1 see major-opcode major-opcode