diff options
Diffstat (limited to 'specs/dbe.xml')
| -rw-r--r-- | specs/dbe.xml | 1065 |
1 files changed, 1065 insertions, 0 deletions
diff --git a/specs/dbe.xml b/specs/dbe.xml new file mode 100644 index 0000000..5af90a6 --- /dev/null +++ b/specs/dbe.xml @@ -0,0 +1,1065 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ +<!ENTITY % defs SYSTEM "defs.ent"> %defs; +]> + + +<!-- +by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) +xhtml,docbook,html,refcaption --> + +<book id="dbe"> + +<bookinfo> + <title>Double Buffer Extension Protocol</title> + <subtitle>X Consortium Standard</subtitle> + <authorgroup> + <author> + <firstname>Ian</firstname><surname>Elliott</surname> + <affiliation><orgname>Hewlett-Packard Company</orgname></affiliation> + </author> + <othercredit> + <firstname>David</firstname><othername>P.</othername><surname>Wiggins</surname> + <affiliation><orgname>X Consortium</orgname></affiliation> + </othercredit> + </authorgroup> + <copyright><year>1989</year><year>1992</year><year>1993</year><year>1994</year> + <holder>X Consortium, Inc.</holder> + </copyright> + <copyright><year>1989</year><holder>Digital Equipment Corporation</holder></copyright> + <copyright><year>1992</year><holder>Intergraph Corporation</holder></copyright> + <copyright><year>1993</year><holder>Silicon Graphics, Inc.</holder></copyright> + <copyright><year>1994</year><holder>Hewlett-Packard Company</holder></copyright> + <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo> + <releaseinfo>Version 1.0</releaseinfo> + +<legalnotice> +<para> +Permission to use, copy, modify, and distribute this documentation for any +purpose and without fee is hereby granted, provided that the above copyright +notice and this permission notice appear in all copies. Digital Equipment +Corporation, Intergraph Corporation, Silicon Graphics, Hewlett-Packard, and +the X Consortium make no representations about the suitability for any purpose +of the information in this document. This documentation is provided “as is” +without express or implied warranty. +</para> +</legalnotice> +</bookinfo> + +<chapter id='Introduction'> +<title>Introduction</title> +<para>The Double Buffer Extension (DBE) provides a standard way to utilize +double-buffering within the framework of the X Window System. Double-buffering +uses two buffers, called front and back, which hold images. The front buffer +is visible to the user; the back buffer is not. Successive frames of an +animation are rendered into the back buffer while the previously rendered +frame is displayed in the front buffer. When a new frame is ready, the back +and front buffers swap roles, making the new frame visible. Ideally, this +exchange appears to happen instantaneously to the user and with no visual +artifacts. Thus, only completely rendered images are presented to the user, +and they remain visible during the entire time it takes to render a new frame. +The result is a flicker-free animation. +</para> +</chapter> + +<chapter id='Goals'> +<title>Goals</title> +<para>This extension should enable clients to: +</para> + +<itemizedlist> + <listitem> + <para>Allocate and deallocate double-buffering for a window.</para> + </listitem> + <listitem> + <para> +Draw to and read from the front and back buffers associated with a window. + </para> + </listitem> + <listitem> + <para>Swap the front and back buffers associated with a window.</para> + </listitem> + <listitem> + <para> +Specify a wide range of actions to be taken when a window is swapped. +This includes explicit, simple swap actions (defined below), and more +complex actions (for example, clearing ancillary buffers) that can be put +together within explicit "begin" and "end" requests (defined below). + </para> + </listitem> + <listitem> + <para> +Request that the front and back buffers associated with multiple +double-buffered windows be swapped simultaneously. + </para> + </listitem> +</itemizedlist> + +<para> +In addition, the extension should: +</para> + +<itemizedlist> + <listitem> + <para> +Allow multiple clients to use double-buffering on the same window.</para> + </listitem> + <listitem> + <para> +Support a range of implementation methods that can capitalize on existing +hardware features. + </para> + </listitem> + <listitem> + <para>Add no new event types.</para> + </listitem> + <listitem> + <para> +Be reasonably easy to integrate with a variety of direct graphics hardware +access (DGHA) architectures. + </para> + </listitem> +</itemizedlist> + +</chapter> + +<chapter id='Concepts'> +<title>Concepts</title> + +<para> +Normal windows are created using the core <function>CreateWindow</function> +request, which allocates a set of window attributes and, for InputOutput +windows, a front buffer, into which an image can be drawn. The contents of +this buffer will be displayed when the window is visible. +</para> +<para> +This extension enables applications to use double-buffering with a window. +This involves creating a second buffer, called a back buffer, and associating +one or more back buffer names (XIDs) with the window for use when referring to +(that is, drawing to or reading from) the window's back buffer. The back +buffer name is a DRAWABLE of type BACKBUFFER. +</para> + +<para> +DBE provides a relative double-buffering model. One XID, the window, always +refers to the front buffer. One or more other XIDs, the back buffer names, +always refer to the back buffer. After a buffer swap, the window continues to +refer to the (new) front buffer, and the back buffer name continues to refer +to the (new) back buffer. Thus, applications and toolkits that want to just +render to the back buffer always use the back buffer name for all drawing +requests to the window. Portions of an application that want to render to +the front buffer always use the window XID for all drawing requests to the +window. +</para> + +<para> +Multiple clients and toolkits can all use double-buffering on the same +window. DBE does not provide a request for querying whether a window has +double-buffering support, and if so, what the back buffer name is. Given +the asynchronous nature of the X Window System, this would cause race +conditions. Instead, DBE allows multiple back buffer names to exist for +the same window; they all refer to the same physical back buffer. The first +time a back buffer name is allocated for a window, the window becomes +double-buffered and the back buffer name is associated with the window. +Subsequently, the window already is a double-buffered window, and nothing +about the window changes when a new back buffer name is allocated, except +that the new back buffer name is associated with the window. The window +remains double-buffered until either the window is destroyed or until all of +the back buffer names for the window are deallocated. +</para> + +<para> +In general, both the front and back buffers are treated the same. In +particular, here are some important characteristics: +</para> + +<itemizedlist> + <listitem> + <para> +Only one buffer per window can be visible at a time (the front buffer). + </para> + </listitem> + <listitem> + <para> +Both buffers associated with a window have the same visual type, depth, +width, height, and shape as the window. + </para> + </listitem> + <listitem> + <para> +Both buffers associated with a window are "visible" (or "obscured") in +the same way. When an Expose event is generated for a window, both +buffers should be considered to be damaged in the exposed area. Damage +that occurs to either buffer will result in an Expose event on the window. +When a double-buffered window is exposed, both buffers are tiled with the +window background, exactly as stated by the core protocol. Even though +the back buffer is not visible, terms such as obscure apply to the back +buffer as well as to the front buffer. + </para> + </listitem> + <listitem> + <para> +It is acceptable at any time to pass a BACKBUFFER in any +request, notably any core or extension drawing request, that expects +a DRAWABLE. This enables an application to draw directly into +BACKBUFFERs in the same fashion as it would draw into any other +DRAWABLE. + </para> + </listitem> + <listitem> + <para> +It is an error (Window) to pass a BACKBUFFER in a core request that +expects a Window. + </para> + </listitem> + <listitem> + <para> +A BACKBUFFER will never be sent by core X in a reply, event, or error +where a Window is specified. + </para> + </listitem> + <listitem> + <para> +If core X11 backing-store and save-under applies to a double-buffered +window, it applies to both buffers equally. + </para> + </listitem> + <listitem> + <para> +If the core <function>ClearArea</function> request is executed on a +double-buffered window, the same area in both the front and back buffers +is cleared. + </para> + </listitem> +</itemizedlist> +<para> +The effect of passing a window to a request that accepts a DRAWABLE is +unchanged by this extension. The window and front buffer are synonomous with +each other. This includes obeying the <function>GetImage</function> semantics +and the subwindow-mode semantics if a core graphics context is involved. +Regardless of whether the window was explicitly passed in a +<function>GetImage</function> request, or implicitly referenced (that is, +one of the windo's ancestors was passed in the request), the front (that is, +visible) buffer is always referenced. Thus, DBE-naive screen dump clients will +always get the front buffer. <function>GetImage</function> on a back buffer +returns undefined image contents for any obscured regions of the back buffer +that fall within the image. +</para> + +<para> +Drawing to a back buffer always uses the clip region that would be used to +draw to the front buffer with a GC subwindow-mode of +<function>ClipByChildren</function>. If an +ancestor of a double-buffered window is drawn to with a core GC having a +subwindow-mode of <function>IncludeInferiors</function>, the effect on the +double-buffered window's back buffer depends on the depth of the +double-buffered window and the ancestor. If the depths are the same, the +contents of the back buffer of the double-buffered window are not changed. +If the depths are different, the contents of the back buffer of the +double-buffered window are undefined for the pixels that the +<function>IncludeInferiors</function> drawing touched. +</para> + +<para> +DBE adds no new events. DBE does not extend the semantics of any existing +events with the exception of adding a new DRAWABLE type called BACKBUFFER. If +events, replies, or errors that contain a DRAWABLE (for example, +<function>GraphicsExpose</function>) are generated in response to a request, +the DRAWABLE returned will be the one specified in the request. +</para> + +<para> +DBE advertises which visuals support double-buffering. +</para> + +<para> +DBE does not include any timing or synchronization facilities. +Applications that need such facilities (for example, to maintain a constant +frame rate) should investigate the Synchronization Extension, an X +Consortium standard. +</para> + +<sect1 id='Window_Management_Operations'> +<title>Window Management Operations</title> + +<para> +The basic philosophy of DBE is that both buffers are treated the same by core +X window management operations. +</para> + +<para> +When the core <function>DestroyWindow</function> is executed on a +double-buffered window, both buffers associated with the window are +destroyed, and all back buffer names associated with the window are freed. +</para> + +<para> +If the core <function>ConfigureWindow</function> request changes the size of +a window, both buffers assume the new size. If the windo's size increases, +the effect on the buffers depends on whether the implementation honors bit +gravity for buffers. If bit gravity is implemented, then the contents of +both buffers are moved in accordance with the windo's bit gravity (see the +core <function>ConfigureWindow</function> request), and the remaining areas +are tiled with the window background. If bit gravity is not implemented, then +the entire unobscured region of both buffers is tiled with the window +background. In either case, <function>Expose</function> events are generated +for the region that is tiled with the window background. +</para> + +<para> +If the core <function>GetGeometry</function> request is executed on a +BACKBUFFER, the returned x, y, and border-width will be zero. +</para> + +<para> +If the Shape extension <function>ShapeRectangles</function>, +<function>ShapeMask</function>, +<function>ShapeCombine</function>, or +<function>ShapeOffset</function> +request is executed on a double-buffered window, both buffers are reshaped +to match the new window shape. The region difference is the following: +</para> + +<literallayout> + D = newshape - oldshape +</literallayout> + +<para> +It is tiled with the window background in both buffers, and +<function>Expose</function> events are generated for D. +</para> + +</sect1> + +<sect1 id='Complex_Swap_Actions'> +<title>Complex Swap Actions</title> +<para> +DBE has no explicit knowledge of ancillary buffers (for example, depth +buffers or alpha buffers), and only has a limited set of defined swap +actions. Some applications may need a richer set of swap actions than DBE +provides. Some DBE implementations have knowledge of ancillary buffers, +and/or can provide a rich set of swap actions. Instead of continually +extending DBE to increase its set of swap actions, DBE provides a flexible +"idiom" mechanism. If an application's needs are served by the defined swap +actions, it should use them; otherwise, it should use the following method +of expressing a complex swap action as an idiom. Following this policy will +ensure the best possible performance across a wide variety of implementations. +</para> + +<para> +As suggested by the term "idiom," a complex swap action should be expressed +as a group/series of requests. Taken together, this group of requests may be +combined into an atomic operation by the implementation, in order to maximize +performance. The set of idioms actually recognized for optimization is +implementation dependent. To help with idiom expression and interpretation, +an idiom must be surrounded by two protocol requests: +<function>DBEBeginIdiom</function> and +<function>DBEEndIdiom</function>. Unless this begin-end pair +surrounds the idiom, it may not be recognized by a given implementation, and +performance will suffer. +</para> + +<para> +For example, if an application wants to swap buffers for two windows, and +use core X to clear only certain planes of the back buffers, the application +would issue the following protocol requests as a group, and in the following +order: +</para> + +<itemizedlist> + <listitem> + <para>DBEBeginIdiom request.</para> + </listitem> + <listitem> + <para> +<function>DBESwapBuffers</function> request with XIDs for two windows, each of which uses +a swap action of Untouched. + </para> + </listitem> + <listitem> + <para> +Core X PolyFillRectangle request to the back buffer of one window. + </para> + </listitem> + <listitem> + <para> +Core X PolyFillRectangle request to the back buffer of the other window. + </para> + </listitem> + <listitem> + <para>DBEEndIdiom request.</para> + </listitem> +</itemizedlist> + +<para> +The <function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function> +requests do not perform any actions themselves. They are treated as markers +by implementations that can combine certain groups/series of requests as +idioms, and are ignored by other implementations or for nonrecognized +groups/series of requests. If these requests are sent out of order, or are +mismatched, no errors are sent, and the requests are executed as usual, +though performance may suffer. +</para> + +<para> +An idiom need not include a <function>DBESwapBuffers</function> request. For +example, if a swap action of Copied is desired, but only some of the planes +should be copied, a core X +<function>CopyArea</function> request may be used instead of +<function>DBESwapBuffers</function>. +If <function>DBESwapBuffers</function> is included in an idiom, it should +immediately follow the <function>DBEBeginIdiom</function> request. Also, when +the <function>DBESwapBuffers</function> is included in an idiom, that +request's swap action will still be valid, and if the swap action might +overlap with another request, then the final result of the idiom must be as if +the separate requests were executed serially. For example, if the specified +swap action is Untouched, and if a <function>PolyFillRectangle</function> +using a client clip rectangle is done to the windo's back buffer after the +<function>DBESwapBuffers</function> request, then the contents of the new +back buffer (after the idiom) will be the same as if the idiom was not +recognized by the implementation. +</para> + +<para> +It is highly recommended that Application Programming Interface (API) +providers define, and application developers use, "convenience" functions +that allow client applications to call one procedure that encapsulates +common idioms. These functions will generate the +<function>DBEBeginIdiom</function> request, the idiom requests, and +<function>DBEEndIdiom</function> request. Usage of these functions will +ensure best possible performance across a wide variety of implementations. +</para> + +</sect1> +</chapter> + +<chapter id='Requests'> +<title>Requests</title> +<para>The DBE defines the following requests.</para> + +<sect1 id='DBEGetVersion'> +<title>DBEGetVersion</title> +<para> +This request returns the major and minor version numbers of this extension. +</para> + +<para>DBEGetVersion</para> +<informaltable frame='none'> + <?dbfo keep-together="always" ?> + <tgroup cols="2" align='left' colsep='0' rowsep='0'> + <colspec colname="c1" colwidth='1.0*'/> + <colspec colname="c2" colwidth='2.0*'/> + <tbody> + <row> + <entry>client-major-version</entry> + <entry>CARD8</entry> + </row> + <row> + <entry>client-minor-version </entry> + <entry>CARD8</entry> + </row> + <row> + <entry>=></entry> + <entry></entry> + </row> + <row> + <entry>server-major-version </entry> + <entry>CARD8</entry> + </row> + <row> + <entry>server-minor-version </entry> + <entry>CARD8</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +The client-major-version and client-minor-version numbers indicate what +version of the protocol the client wants the server to implement. The +server-major-version and the server-minor-version numbers returned indicate +the protocol this extension actually supports. This might not equal the +version sent by the client. An implementation can (but need not) support +more than one version simultaneously. The server-major-version and +server-minor-version allow the creation of future revisions of the DBE +protocol that may be necessary. In general, the major version +would increment for incompatible changes, and the minor version would increment +for small, upward-compatible changes. Servers that support the protocol +defined in this document will return a server-major-version of one (1), and a +server-minor-version of zero (0). +</para> + +<para> +The DBE client must issue a DBEGetVersion request before any other double +buffering request in order to negotiate a compatible protocol version; +otherwise, the client will get undefined behavior (DBE may or may not work). +</para> + +</sect1> + +<sect1 id='DBEGetVisualInfo'> +<title>DBEGetVisualInfo</title> +<para> +This request returns information about which visuals support double buffering. +</para> + +<para>DBEGetVisualInfo</para> + +<informaltable frame='none'> + <?dbfo keep-together="always" ?> + <tgroup cols="2" align='left' colsep='0' rowsep='0'> + <colspec colname="c1" colwidth='1.0*'/> + <colspec colname="c2" colwidth='2.0*'/> + <tbody> + <row> + <entry>screen-specifiers</entry> + <entry>LISTofDRAWABLE</entry> + </row> + <row> + <entry>=></entry> + <entry></entry> + </row> + <row> + <entry>visinfo</entry> + <entry>LISTofSCREENVISINFO</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<para>where:</para> + +<informaltable frame='none'> + <?dbfo keep-together="always" ?> + <tgroup cols="2" align='left' colsep='0' rowsep='0'> + <colspec colname="c1" colwidth='1.0*'/> + <colspec colname="c2" colwidth='2.0*'/> + <tbody> + <row> + <entry>SCREENVISINFO</entry> + <entry>LISTofVISINFO</entry> + </row> + <row> + <entry>VISINFO</entry> + <entry>[ visual: VISUALID</entry> + </row> + <row> + <entry></entry> + <entry>depth: CARD8</entry> + </row> + <row> + <entry></entry> + <entry>perflevel: CARD8 ]</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para>Errors: Drawable</para> + +<para> +All of the values passed in screen-specifiers must be valid DRAWABLEs (or a +<function>Drawable</function> error results). For each drawable in +screen-specifiers, the reply will contain a list of VISINFO structures for +visuals that support double-buffering on the screen on which the drawable +resides. The visual member specifies the VISUALID. The depth member specifies +the depth in bits for the visual. The perflevel is a performance hint. The +only operation defined on a perflevel is comparison to a perflevel of another +visual on the same screen. The visual having the higher perflevel is likely +to have better double-buffer graphics performance than the visual having the +lower perflevel. Nothing can be deduced from any of the following: the +magnitude of the difference of two perflevels, a perflevel value in isolation, +or comparing perflevels from different servers. +</para> + +<para> +If the list of screen-specifiers is empty, information for all screens is +returned, starting with screen zero. +</para> + +</sect1> + +<sect1 id='DBEAllocateBackBufferName'> +<title>DBEAllocateBackBufferName</title> + +<para> +This request allocates a drawable ID used to refer to the back buffer of a +window. +</para> + +<para>DBEAllocateBackBufferName</para> + +<informaltable frame='none'> + <?dbfo keep-together="always" ?> + <tgroup cols="2" align='left' colsep='0' rowsep='0'> + <colspec colname="c1" colwidth='1.0*'/> + <colspec colname="c2" colwidth='2.0*'/> + <tbody> + <row> + <entry>window</entry> + <entry>WINDOW</entry> + </row> + <row> + <entry>back-buffer-name</entry> + <entry>BACKBUFFER</entry> + </row> + <row> + <entry>swap-action-hint</entry> + <entry>SWAPACTION </entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +Errors: Alloc, Value, IDChoice, Match, Window +</para> + +<para> +If the window is not already a double-buffered window, the window becomes +double-buffered, and the back-buffer-name is associated with the window. The +swap-action-hint tells the server which swap action is most likely to be +used with the window in subsequent <function>DBESwapBuffers</function> +requests. The swap-action-hint must have one of the values specified for type +SWAPACTION (or a Value error results). See the description of the +<function>DBESwapBuffers</function> request for a complete discussion of +swap actions and the SWAPACTION type. +</para> + +<para> +If the window already is a double-buffered window, nothing about the window +changes, except that an additional back-buffer-name is associated with the +window. The window remains double-buffered until either the window is +destroyed, or until all of the back buffer names for the window are +deallocated. +</para> + +<para> +The window passed into the request must be a valid WINDOW (or a Window error +results). The window passed into the request must be an InputOutput window (or +a Match error results). The visual of the window must be in the list returned +by <function>DBEGetVisualInfo</function> (or a Match error results). The +back-buffer-name must be in the range assigned to the client, and must not +already be in use (or an IDChoice error results). If the server cannot +allocate all resources associated with turning on double-buffering for the +window, an Alloc error results, the windo's double-buffer status (whether it +is already double-buffered or not) remains unchanged, and the +back-buffer-name is freed. +</para> +</sect1> + +<sect1 id='DBEDeallocateBackBufferName'> +<title>DBEDeallocateBackBufferName</title> +<para> +This request frees a drawable ID that was obtained by +<function>DBEAllocateBackBufferName</function>. +</para> + +<para>DBEDeallocateBackBufferName</para> + +<informaltable frame='none'> + <?dbfo keep-together="always" ?> + <tgroup cols="2" align='left' colsep='0' rowsep='0'> + <colspec colname="c1" colwidth='1.0*'/> + <colspec colname="c2" colwidth='2.0*'/> + <tbody> + <row> + <entry>back-buffer-name</entry> + <entry>BACKBUFFER</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para>Errors: Buffer</para> + +<para> +The back-buffer-name passed in the request is freed and no longer associated +with the window. If this is the last back-buffer-name associated with the +window, then the back buffer is no longer accessible to clients, and all +double-buffering resources associated with the window may be freed. The +window's current front buffer remains the front buffer. +</para> + +<para> +The back-buffer-name must be a valid BACKBUFFER associated with a window (or +a Buffer error results). +</para> +</sect1> + +<sect1 id='DBESwapBuffers'> +<title>DBESwapBuffers</title> +<para> +This request swaps the buffers for all windows listed, applying the +appropriate swap action for each window. +</para> + +<para><function>DBESwapBuffers</function></para> + +<informaltable frame='none'> + <?dbfo keep-together="always" ?> + <tgroup cols="2" align='left' colsep='0' rowsep='0'> + <colspec colname="c1" colwidth='1.0*'/> + <colspec colname="c2" colwidth='3.0*'/> + <tbody> + <row> + <entry>windows</entry> + <entry>LISTofSWAPINFO</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<para>where:</para> +<informaltable frame='none'> + <?dbfo keep-together="always" ?> + <tgroup cols="2" align='left' colsep='0' rowsep='0'> + <colspec colname="c1" colwidth='1.0*'/> + <colspec colname="c2" colwidth='2.0*'/> + <tbody> + <row> + <entry>SWAPINFO</entry> + <entry>[ window: WINDOW</entry> + </row> + <row> + <entry></entry> + <entry>swap-action: SWAPACTION ]</entry> + </row> + <row> + <entry>SWAPACTION</entry> + <entry>{ Undefined, Background, Untouched, Copied }</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para>Errors: Match, Window, Value</para> + +<para> +Each window passed into the request must be a valid WINDOW (or a +<function>Window</function> error results). Each window passed into the +request must be a double-buffered window (or a <function>Match</function> +error results). Each window passed into the request must only be listed +once (or a <function>Match</function> error results). Each swap-action in +the list must have one of the values specified for type SWAPACTION (or a +<function>Value</function> error results). If an error results, none of +the valid double-buffered windows will have their buffers swapped. +</para> + +<para> +The swap-action determines what will happen to the new back buffer of the +window it is paired with in the list in addition to making the old back +buffer become visible. The defined actions are as follows: +</para> + +<variablelist> + <varlistentry> + <term>Undefined</term> + <listitem><para> +The contents of the new back buffer become undefined. This may be the +most efficient action since it allows the implementation to discard the +contents of the buffer if it needs to. + </para></listitem> + </varlistentry> + <varlistentry> + <term>Background</term> + <listitem><para> +The unobscured region of the new back buffer will be tiled with the window +background. The background action allows devices to use a fast clear +capability during a swap. + </para></listitem> + </varlistentry> + <varlistentry> + <term>Untouched</term> + <listitem><para> +The unobscured region of the new back buffer will be unmodified by the swap. + </para></listitem> + </varlistentry> + <varlistentry> + <term>Copied</term> + <listitem><para> +The unobscured region of the new back buffer will be the contents of the +old back buffer. + </para></listitem> + </varlistentry> +</variablelist> + +<para> +If <function>DBESwapBuffers</function> is included in a "swap and clear" +type of idiom, it must immediately follow the +<function>DBEBeginIdiom</function> request. +</para> +</sect1> + +<sect1 id='DBEBeginIdiom'> +<title>DBEBeginIdiom</title> +<para> +This request informs the server that a complex swap will immediately follow +this request. +</para> + +<para><function>DBEBeginIdiom</function></para> + +<para> +As previously discussed, a complex swap action is a group/series of +requests that, taken together, may be combined into an atomic operation by +the implementation. The sole function of this request is to serve as a +"marker" that the server can use to aid in idiom processing. The server is +free to implement this request as a no-op. +</para> +</sect1> + +<sect1 id='DBEEndIdiom'> +<title>DBEEndIdiom</title> + + +<para> +This request informs the server that a complex swap has concluded. +</para> + +<para><function>DBEEndIdiom</function></para> + +<para> +The sole function of this request is to serve as a "marker" that the server +can use to aid in idiom processing. The server is free to implement this +request as a no-op. +</para> + +</sect1> + +<sect1 id='DBEGetBackBufferAttributes'> +<title>DBEGetBackBufferAttributes</title> + +<para>This request returns information about a back buffer.</para> + +<para><function>DBEGetBackBufferAttributes</function></para> + +<informaltable frame='none'> + <?dbfo keep-together="always" ?> + <tgroup cols="2" align='left' colsep='0' rowsep='0'> + <colspec colname="c1" colwidth='1.0*'/> + <colspec colname="c2" colwidth='2.0*'/> + <tbody> + <row> + <entry>back-buffer-name</entry> + <entry>BACKBUFFER</entry> + </row> + <row> + <entry>=></entry> + <entry></entry> + </row> + <row> + <entry>attributes</entry> + <entry>BUFFER_ATTRIBUTES</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para>where:</para> + +<para>BUFFER_ATTRIBUTES: [ window: WINDOW ]</para> + +<para> +If back-buffer-name is a valid BACKBUFFER, the window field of the +attributes in the reply will be the window which has the back buffer that +back-buffer-name refers to. If back-buffer-name is not a valid BACKBUFFER, +the window field of the attributes in the reply will be None. +</para> + +</sect1> +</chapter> + +<chapter id='Encoding'> +<title>Encoding</title> +<para> +Please refer to the X11 Protocol Encoding document as this section uses +syntactic conventions and data types established there. +</para> + +<para>The name of this extension is "DOUBLE-BUFFER".</para> + +<sect1 id='Type'> +<title>Type</title> +<para>The following new types are used by the extension. +</para> + +<para>BACKBUFFER: XID</para> +<para>SWAPACTION</para> +<literallayout class="monospaced"> +#x00 Undefined +#x01 Background +#x02 Untouched +#x03 Copied +</literallayout> + +<para>SWAPINFO</para> +<literallayout class="monospaced"> +4 WINDOW window +1 SWAPACTION swap action +3 unused +</literallayout> + +<literallayout class="monospaced"> +VISINFO +4 VISUALID visual +1 CARD8 depth +1 CARD8 perflevel +2 unused + +SCREENVISINFO +4 CARD32 n, number in list +8n LISTofVISINFO n VISINFOs + +BUFFER_ATTRIBUTES +4 WINDOW window +</literallayout> +</sect1> + +<sect1 id='Error'> +<title>Error</title> +<para><function>Buffer</function></para> +<literallayout class="monospaced"> +1 0 error +1 error base + 0 code +2 CARD16 sequence number +4 CARD32 bad buffer +2 CARD16 minor-opcode +1 CARD8 major-opcode +21 unused +</literallayout> +</sect1> + +<sect1 id='Request'> +<title>Request</title> + +<literallayout class="monospaced"> +DBEGetVersion +1 CARD8 major-opcode +1 0 minor-opcode +2 2 request length +1 CARD8 client-major-version +1 CARD8 client-minor-version +2 unused +=> +1 unused +2 CARD16 sequence number +4 0 reply length +1 CARD8 server-major-version +1 CARD8 server-minor-version +22 unused +</literallayout> + +<para><function>DBEAllocateBackBufferName</function></para> +<literallayout class="monospaced"> +1 CARD8 major-opcode +1 1 minor-opcode +2 4 request length +4 WINDOW window +4 BACKBUFFER back buffer name +1 SWAPACTION swap action hint +3 unused +</literallayout> + +<para><function>DBEDeallocateBackBufferName</function></para> +<literallayout class="monospaced"> +1 CARD8 major-opcode +1 2 minor-opcode +2 2 request length +4 BACKBUFFER back buffer name +</literallayout> + + +<para><function>DBESwapBuffers</function></para> +<literallayout class="monospaced"> +1 CARD8 major-opcode +1 3 minor-opcode +2 2+2n request length +4 CARD32 n, number of window/swap action pairs in list +8n LISTofSWAPINFO window/swap action pairs +</literallayout> + + +<para><function>DBEBeginIdiom</function></para> +<literallayout class="monospaced"> +1 CARD8 major-opcode +1 4 minor-opcode +2 1 request length +</literallayout> + +<para><function>DBEEndIdiom</function></para> +<literallayout class="monospaced"> +1 CARD8 major-opcode +1 5 minor-opcode +2 1 request length +</literallayout> + +<para><function>DBEGetVisualInfo</function></para> +<literallayout class="monospaced"> +1 CARD8 major-opcode +1 6 minor-opcode +2 2+n request length +4 CARD32 n, number of screen specifiers in list +4n LISTofDRAWABLE n screen specifiers +=> +1 1 Reply +1 unused +2 CARD16 sequence number +4 CARD32 reply length +4 CARD32 m, number of SCREENVISINFOs in list +20 unused +4j LISTofSCREENVISINFO m SCREENVISINFOs +</literallayout> + +<para><function>DBEGetBackBufferAttributes</function></para> +<literallayout class="monospaced"> +1 CARD8 major-opcode +1 7 minor-opcode +2 2 request length +4 BACKBUFFER back-buffer-name +=> +1 unused +2 CARD16 sequence number +4 0 reply length +4 BUFFER_ATTRIBUTES attributes +20 unused +</literallayout> +</sect1> + +</chapter> + +<chapter id='Acknowledgements'> +<title>Acknowledgements</title> +<para> +We wish to thank the following individuals who have contributed their time +and talent toward shaping the DBE specification: +</para> +<para>T. Alex Chen, IBM; Peter Daifuku, Silicon Graphics, Inc.; +Ian Elliott, Hewlett-Packard Company; Stephen Gildea, X Consortium, Inc.; +Jim Graham, Sun; Larry Hare, AGE Logic; Jay Hersh, X Consortium, Inc.; +Daryl Huff, Sun; Deron Dann Johnson, Sun; Louis Khouw, Sun; +Mark Kilgard, Silicon Graphics, Inc.; Rob +Lembree, Digital Equipment Corporation; Alan Ricker, Metheus; Michael +Rosenblum, Digital Equipment Corporation; Bob Scheifler, X Consortium, Inc.; +Larry Seiler, Digital Equipment Corporation; Jeanne Sparlin Smith, IBM; +Jeff Stevenson, Hewlett-Packard Company; Walter Strand, Metheus; Ken +Tidwell, Hewlett-Packard Company; and David P. Wiggins, X Consortium, Inc. +</para> + +<para> +Mark provided the impetus to start the DBE project. Ian wrote the first +draft of the specification. David served as architect. +</para> +</chapter> + +<chapter id='References'> +<title>References</title> +<para> +Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension +Specification Version 3.3." +</para> +<para>Tim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins, +"X Synchronization Extension Version 3.0." +</para> +</chapter> +</book> |