% $Xorg: dbelib.tex,v 1.3 2000/08/17 19:42:31 cpqbld Exp $ % edited for DP edits and code consistency w/ core protocol/xlib 3/30/96 % split into separate library and protocol documentos 4/15/96 \documentstyle{article} \pagestyle{myheadings} \markboth{Double Buffer Extension Specification}{Double Buffer Extension Specification} \setlength{\parindent}{0 pt} \setlength{\parskip}{6pt} \setlength{\topsep}{0 pt} % Request names are literal symbols; therefore, use the same font for both. \newcommand{\requestname}[1]{{\tt #1}} \newcommand{\literal}[1]{\mbox{\tt #1}} \newcommand{\encodingsection}[1]{{\bf #1}} \newcommand{\requestsection}[1]{{\bf #1}} % Font treatment of type names differs between protocol and library sections. \newcommand{\libtypename}[1]{\mbox{\tt #1}} \newcommand{\typename}[1]{\mbox{\rm #1}} % default font \newcommand{\typeargname}[1]{\mbox{\rm #1}} % default font \newcommand{\argname}[1]{\mbox{\it #1}} \newcommand{\argdecl}[2]{\argname{#1} & : \typename{#2}\\} \newcommand{\areplyargdecl}[2]{#1 & : \typename{#2}\\} \newenvironment{arequest}[1]{\requestsection{#1} \\ \begin{tabular}{ll}}{\end{tabular}} \newcommand{\areply}{$\Rightarrow$\\} \newcommand{\etabstops}{\hspace*{0cm}\=\hspace*{1cm}\=\hspace*{5cm}\=\kill} \newcommand{\eargdecl}[3]{\> #1 \> \typename{#2} \> #3 \\} \newenvironment{keeptogether}{\vbox \bgroup}{\egroup} \newenvironment{erequest}[3]{\pagebreak[3] \begin{keeptogether} \encodingsection{#1} \begin{tabbing} \etabstops \eargdecl{1}{CARD8}{major-opcode} \eargdecl{1}{#2}{minor-opcode} \eargdecl{2}{#3}{request length}}{\end{tabbing} \end{keeptogether}} \newenvironment{eerror}[1]{\begin{keeptogether} \encodingsection{#1} \begin{tabbing} \etabstops }{\end{tabbing} \end{keeptogether}} \newenvironment{etypedef}[1]{\begin{keeptogether} \typename{#1} \begin{tabbing} \etabstops }{\end{tabbing} \end{keeptogether}} \newcommand{\cfunctionname}[1]{\mbox{\tt #1}} \newcommand{\cfunctiondecl}[1]{\mbox{\rm #1}} \newcommand{\cargdecl}[2]{\penalty -1\typename{#1} \argname{#2}} \newenvironment{cfunction}[2]{\begin{sloppypar}\begin{keeptogether}\vspace{5mm}\typename{#1}\\ \cfunctiondecl{#2}\ (}{)\end{keeptogether}\end{sloppypar}{\hangafter=2 \hangindent=20pt \raggedright\par}} % make things easier with all the long names \spaceskip .3333em plus 5em \tolerance=2000 \begin{document} \title{Double Buffer Extension Library\\Protocol Version 1.0\\X Consortium Standard} \author{Ian Elliott\\Hewlett-Packard Company \and David P. Wiggins\\X Consortium, Inc.} \maketitle \thispagestyle{empty} \eject Copyright \copyright 1989 X Consortium, Inc. and Digital Equipment Corporation. Copyright \copyright 1992 X Consortium, Inc. and Intergraph Corporation. Copyright \copyright 1993 X Consortium, Inc. and Silicon Graphics, Inc. Copyright \copyright 1994, 1995 X Consortium, Inc. and Hewlett-Packard Company. 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. \eject \section{Introduction} 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. \section{Goals} This extension should enable clients to: \begin{itemize} \item Allocate and deallocate double-buffering for a window. \item Draw to and read from the front and back buffers associated with a window. \item Swap the front and back buffers associated with a window. \item 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). \item Request that the front and back buffers associated with multiple double-buffered windows be swapped simultaneously. \end{itemize} In addition, the extension should: \begin{itemize} \item Allow multiple clients to use double-buffering on the same window. \item Support a range of implementation methods that can capitalize on existing hardware features. \item Add no new event types. \item Be reasonably easy to integrate with a variety of direct graphics hardware access (DGHA) architectures. \end{itemize} \section{Concepts} Normal windows are created using the core \requestname{CreateWindow} request, which allocates a set of window attributes and, for \literal{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. 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 (\typename{XID}s) 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 \typename{DRAWABLE} of type \typename{BACKBUFFER}. 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. 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. In general, both the front and back buffers are treated the same. In particular, here are some important characteristics: \begin{itemize} \item Only one buffer per window can be visible at a time (the front buffer). \item Both buffers associated with a window have the same visual type, depth, width, height, and shape as the window. \item Both buffers associated with a window are ``visible'' (or ``obscured'') in the same way. When an \literal{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 \literal{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. \item It is acceptable at any time to pass a \typename{BACKBUFFER} in any request, notably any core or extension drawing request, that expects a \typename{DRAWABLE}. This enables an application to draw directly into \typename{BACKBUFFER}s in the same fashion as it would draw into any other \typename{DRAWABLE}. \item It is an error (\literal{Window}) to pass a \typename{BACKBUFFER} in a core request that expects a Window. \item A \typename{BACKBUFFER} will never be sent by core X in a reply, event, or error where a Window is specified. \item If core X11 backing-store and save-under applies to a double-buffered window, it applies to both buffers equally. \item If the core \requestname{ClearArea} request is executed on a double-buffered window, the same area in both the front and back buffers is cleared. \end{itemize} The effect of passing a window to a request that accepts a \typename{DRAWABLE} is unchanged by this extension. The window and front buffer are synonomous with each other. This includes obeying the \requestname{GetImage} semantics and the subwindow-mode semantics if a core graphics context is involved. Regardless of whether the window was explicitly passed in a \requestname{GetImage} request, or implicitly referenced (that is, one of the window's ancestors was passed in the request), the front (that is, visible) buffer is always referenced. Thus, DBE-na\"{\i}ve screen dump clients will always get the front buffer. \requestname{GetImage} on a back buffer returns undefined image contents for any obscured regions of the back buffer that fall within the image. 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 \literal{ClipByChildren}. If an ancestor of a double-buffered window is drawn to with a core GC having a subwindow-mode of \literal{IncludeInferiors}, 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 \literal{IncludeInferiors} drawing touched. DBE adds no new events. DBE does not extend the semantics of any existing events with the exception of adding a new \typename{DRAWABLE} type called \typename{BACKBUFFER}. If events, replies, or errors that contain a \typename{DRAWABLE} (for example, \literal{GraphicsExpose}) are generated in response to a request, the \typename{DRAWABLE} returned will be the one specified in the request. DBE advertises which visuals support double-buffering. 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. \subsection{Window Management Operations} The basic philosophy of DBE is that both buffers are treated the same by core X window management operations. When the core \requestname{DestroyWindow} 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. If the core \requestname{ConfigureWindow} request changes the size of a window, both buffers assume the new size. If the window'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 window's bit gravity (see the core \requestname{ConfigureWindow} 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, \literal{Expose} events are generated for the region that is tiled with the window background. If the core \requestname{GetGeometry} request is executed on a \typename{BACKBUFFER}, the returned x, y, and border-width will be zero. If the Shape extension \requestname{ShapeRectangles}, \requestname{ShapeMask}, \requestname{ShapeCombine}, or \requestname{ShapeOffset} request is executed on a double-buffered window, both buffers are reshaped to match the new window shape. The region difference is the following: \[ D = new shape - old shape \] It is tiled with the window background in both buffers, and \literal{Expose} events are generated for D. \subsection{Complex Swap Actions} 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. 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: \requestname{DBEBeginIdiom} and \requestname{DBEEndIdiom}. Unless this begin-end pair surrounds the idiom, it may not be recognized by a given implementation, and performance will suffer. 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: \begin{itemize} \item \requestname{DBEBeginIdiom} request. \item \requestname{DBESwapBuffers} request with XIDs for two windows, each of which uses a swap action of \literal{Untouched}. \item Core X \requestname{PolyFillRectangle} request to the back buffer of one window. \item Core X \requestname{PolyFillRectangle} request to the back buffer of the other window. \item \requestname{DBEEndIdiom} request. \end{itemize} The \requestname{DBEBeginIdiom} and \requestname{DBEEndIdiom} 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. An idiom need not include a \requestname{DBESwapBuffers} request. For example, if a swap action of \literal{Copied} is desired, but only some of the planes should be copied, a core X \requestname{CopyArea} request may be used instead of \requestname{DBESwapBuffers}. If \requestname{DBESwapBuffers} is included in an idiom, it should immediately follow the \requestname{DBEBeginIdiom} request. Also, when the \requestname{DBESwapBuffers} 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 \literal{Untouched}, and if a \requestname{PolyFillRectangle} using a client clip rectangle is done to the window's back buffer after the \requestname{DBESwapBuffers} 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. 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 \requestname{DBEBeginIdiom} request, the idiom requests, and \requestname{DBEEndIdiom} request. Usage of these functions will ensure best possible performance across a wide variety of implementations. \section{C Language Binding} The header for this extension is \verb||. All identifier names provided by this header begin with Xdbe. \subsection{Types} The type \libtypename{XdbeBackBuffer} is a \libtypename{Drawable}. The type \libtypename{XdbeSwapAction} can be one of the constants \literal{XdbeUndefined}, \literal{XdbeBackground}, \literal{XdbeUntouched}, or \literal{XdbeCopied}. \subsection{C Functions} The C functions provide direct access to the protocol and add no additional semantics. For complete details on the effects of these functions, refer to the appropriate protocol request, which can be derived by replacing Xdbe at the start of the function name with DBE\@. All functions that have return type \libtypename{Status} will return nonzero for success and zero for failure. % start marker \begin{keeptogether} \begin{cfunction}{Status}{XdbeQueryExtension} \cargdecl{Display *}{dpy}, \cargdecl{int *}{major\_version\_return}, \cargdecl{int *}{minor\_version\_return} \end{cfunction} % end marker \cfunctionname{XdbeQueryExtension} sets major\_version\_return and minor\_version\_return to the major and minor DBE protocol version supported by the server. If the DBE library is compatible with the version returned by the server, it returns nonzero. If dpy does not support the DBE extension, or if there was an error during communication with the server, or if the server and library protocol versions are incompatible, it returns zero. No other Xdbe functions may be called before this function. If a client violates this rule, the effects of all subsequent Xdbe calls that it makes are undefined. \end{keeptogether} % start marker \begin{keeptogether} \begin{cfunction}{XdbeScreenVisualInfo *}{XdbeGetVisualInfo} \cargdecl{Display *}{dpy}, \cargdecl{Drawable *}{screen\_specifiers}, \cargdecl{int *}{num\_screens} \end{cfunction} % end marker \cfunctionname{XdbeGetVisualInfo} returns information about which visuals support double buffering. The argument num\_screens specifies how many elements there are in the screen\_specifiers list. Each drawable in screen\_specifiers designates a screen for which the supported visuals are being requested. If num\_screens is zero, information for all screens is requested. In this case, upon return from this function, num\_screens will be set to the number of screens that were found. If an error occurs, this function returns NULL; otherwise, it returns a pointer to a list of \libtypename{XdbeScreenVisualInfo} structures of length num\_screens. The {\it n}th element in the returned list corresponds to the {\it n}th drawable in the screen\_specifiers list, unless num\_screens was passed in with the value zero, in which case the {\it n}th element in the returned list corresponds to the {\it n}th screen of the server, starting with screen zero. The \libtypename{XdbeScreenVisualInfo} structure has the following fields: \begin{tabular}{lll} \typename{int} & \argname{count} & number of items in visinfo \\ \typename{XdbeVisualInfo *} & \argname{visinfo} & list of visuals and depths for this screen \\ \end{tabular} The \libtypename{XdbeVisualInfo} structure has the following fields: \begin{tabular}{lll} \typename{VisualID} & \argname{visual} & one visual ID that supports double-buffering\\ \typename{int} & \argname{depth} & depth of visual in bits \\ \typename{int} & \argname{perflevel} & performance level of visual \\ \end{tabular} \end{keeptogether} % start marker \begin{keeptogether} \begin{cfunction}{void }{XdbeFreeVisualInfo} \cargdecl{XdbeScreenVisualInfo *}{visual\_info} \end{cfunction} % end marker \cfunctionname{XdbeFreeVisualInfo} frees the list of \libtypename{XdbeScreenVisualInfo} returned by \cfunctionname{XdbeGetVisualInfo}. \end{keeptogether} % start marker \begin{keeptogether} \begin{cfunction}{XdbeBackBuffer}{XdbeAllocateBackBufferName} \cargdecl{Display *}{dpy}, \cargdecl{Window}{window}, \cargdecl{XdbeSwapAction}{swap\_action} \end{cfunction} % end marker \cfunctionname{XdbeAllocateBackBufferName} returns a drawable ID used to refer to the back buffer of the specified window. The swap\_action is a hint to indicate the swap action that will likely be used in subsequent calls to \cfunctionname{XdbeSwapBuffers}. The actual swap action used in calls to \cfunctionname{XdbeSwapBuffers} does not have to be the same as the swap\_action passed to this function, though clients are encouraged to provide accurate information whenever possible. \end{keeptogether} % start marker \begin{keeptogether} \begin{cfunction}{Status}{XdbeDeallocateBackBufferName} \cargdecl{Display *}{dpy}, \cargdecl{XdbeBackBuffer}{buffer} \end{cfunction} % end marker \cfunctionname{XdbeDeallocateBackBufferName} frees the specified drawable ID, buffer, that was obtained via \cfunctionname{XdbeAllocateBackBufferName}. The buffer must be a valid name for the back buffer of a window, or an \literal{XdbeBadBuffer} error results. \end{keeptogether} % start marker \begin{keeptogether} \begin{cfunction}{Status}{XdbeSwapBuffers} \cargdecl{Display *}{dpy}, \cargdecl{XdbeSwapInfo *}{swap\_info}, \cargdecl{int}{num\_windows} \end{cfunction} % end marker \cfunctionname{XdbeSwapBuffers} swaps the front and back buffers for a list of windows. The argument num\_windows specifies how many windows are to have their buffers swapped; it is the number of elements in the swap\_info array. The argument swap\_info specifies the information needed per window to do the swap. The \libtypename{XdbeSwapInfo} structure has the following fields: \begin{tabular}{lll} \typename{Window} & \argname{swap\_window} & window for which to swap buffers \\ \typename{XdbeSwapAction} & \argname{swap\_action} & swap action to use for this swap\_window \\ \end{tabular} \end{keeptogether} % start marker \begin{keeptogether} \begin{cfunction}{Status}{XdbeBeginIdiom} \cargdecl{Display *}{dpy} \end{cfunction} % end marker \cfunctionname{XdbeBeginIdiom} marks the beginning of an idiom sequence. See section 3.2 for a complete discussion of idioms. \end{keeptogether} % start marker \begin{keeptogether} \begin{cfunction}{Status}{XdbeEndIdiom} \cargdecl{Display *}{dpy} \end{cfunction} % end marker \cfunctionname{XdbeEndIdiom} marks the end of an idiom sequence. \end{keeptogether} % start marker \begin{keeptogether} \begin{cfunction}{XdbeBackBufferAttributes *}{XdbeGetBackBufferAttributes} \cargdecl{Display *}{dpy}, \cargdecl{XdbeBackBuffer}{buffer} \end{cfunction} % end marker \cfunctionname{XdbeGetBackBufferAttributes} returns the attributes associated with the specified buffer. The \libtypename{XdbeBackBufferAttributes} structure has the following fields: \begin{tabular}{lll} \typename{Window} & \argname{window} & window that buffer belongs to \\ \end{tabular} If buffer is not a valid \libtypename{XdbeBackBuffer}, window is set to \literal{None}. The returned \libtypename{XdbeBackBufferAttributes} structure can be freed with the Xlib function \cfunctionname{XFree}. \end{keeptogether} \begin{keeptogether} \subsection{Errors} The \libtypename{XdbeBufferError} structure has the following fields: \begin{tabular}{lll} \typename{int} & \argname{type} \\ \typename{Display *} & \argname{display}& Display the event was read from\\ \typename{XdbeBackBuffer} & \argname{buffer}& resource id \\ \typename{unsigned long} & \argname{serial}& serial number of failed request\\ \typename{unsigned char} & \argname{error\_code}& error base + \literal{XdbeBadBuffer}\\ \typename{unsigned char} & \argname{request\_code}& Major op-code of failed request\\ \typename{unsigned char} & \argname{minor\_code}& Minor op-code of failed request\\ \end{tabular} \end{keeptogether} \pagebreak[4] \section{Acknowledgements} We wish to thank the following individuals who have contributed their time and talent toward shaping the DBE specification: 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. Mark provided the impetus to start the DBE project. Ian wrote the first draft of the specification. David served as architect. \section{References} Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, ``Multi-buffering Extension Specification Version 3.3.'' Tim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins, ``X Synchronization Extension Version 3.0.'' \end{document}