The Double Buffer Extension (DBE) provides a standard way to utilize double bufferiing 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, with no visual artifacts. Thus, only completely rendered images are presented to the user, and remain visible during the entire time it takes to render a new frame. The result is a flicker-free animation.
This article contains the following sections:
This extension should enable clients to:
In addition, the extension should:
Normal windows are created using the core CreateWindow 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.
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 (for example, drawing to or reading from) the window's back buffer. The back buffer name is a DRAWABLE of type 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 doesn't 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:
The effect of passing a window to a request that accepts a DRAWABLE is unchanged by this extension. The window and front buffer are synonymous with each other. This includes obeying the GetImage semantics and the subwindow-mode semantics if a core graphics context is involved. Regardless of whether the window was explicitly passed in a GetImage request, or implicitly referenced (for example, one of the window's ancestors was passed in the request), the front (i.e., visible) buffer is always referenced. Thus, DBE-naive screen dump clients will always get the front buffer. 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 ClipByChildren. If an ancestor of a double-buffered window is drawn to with a core GC having a subwindow-mode of 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 IncludeInferiors drawing touched.
DBE adds no new events. DBE doesn't 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, GraphicsExpose) are generated in response to a request, the 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.
The basic philosophy of DBE is that both buffers are treated the same by core X window management operations.
When the core 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 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 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, Expose events are generated for the region that is tiled with the window background.
If the core GetGeometry request is executed on a BACKBUFFER , the returned x, y, and border-width will be zero.
If the Shape extension ShapeRectangles, ShapeMask, ShapeCombine, or ShapeOffset request is executed on a double-buffered window, both buffers are reshaped to match the new window shape. The region difference
D = NewShape - OldShape
is tiled with the window background in both buffers, and Expose events are generated for D.
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 or 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: DBEBeginIdiom and 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:
The DBEBeginIdiom and DBEEndIdiom requests don't perform any actions themselves. They are treated as markers by implementations that can combine certain groups or series of requests as idioms, and are ignored by other implementations or for non-recognized groups or 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 DBESwapBuffers request. For example, if a swap action of Copied is desired, but only some of the planes should be copied, a core X CopyArea request may be used instead of DBESwapBuffers. If DBESwapBuffers is included in an idiom, it should immediately follow the DBEBeginIdiom request. Also, when the 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 Untouched, and if a PolyFillRectangle using a client clip rectangle is done to the window's back buffer after the DBESwapBuffers request, then the contents of the new back buffer (after the idiom) will be the same as if the idiom weren't recognized by the implementation.
This section discusses the following requests:
This request returns the major and minor version numbers of this extension.
client-major-version : CARD8 client-minor-version : CARD8 => server-major-version : CARD8 server-minor-version : CARD8
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 Double Buffering Extension protocol which 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).
The Double Buffering 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).
This request returns information about which visuals support double buffering.
screen-specifiers : LISTofDRAWABLE => visinfo : LISTofSCREENVISINFO
The following type definitions apply:
SCREENVISINFO : LISTofVISINFO
VISINFO: [VISUALID visual;
CARD8 depth;
CARD8 perflevel]
All of the values passed in screen-specifiers must be valid DRAWABLE s (or a Drawable 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.
If the list of screen-specifiers is empty, information for all screens is returned, starting with screen zero.
This request allocates a drawable ID used to refer to the back buffer of a window.
window : WINDOW back-buffer-name : BACKBUFFER swap-action-hint : SWAPACTION
(Errors: Alloc, Value, IDChoice, Match, Window)
If the window isn't 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 DBESwapBuffers 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 DBESwapBuffers request for a complete discussion of swap actions and the SWAPACTION type.
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.
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 DBEGetVisualInfo (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 window's double-buffer* status (whether it is already double-buffered or not) remains unchanged, and the back-buffer-name is freed.
This request frees a drawable ID that was obtained by DBEAllocateBackBufferName.
back-buffer-name : BACKBUFFER
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.
The back-buffer-name must be a valid BACKBUFFER associated with a window (or a Buffer error results).
This request swaps the buffers for all windows listed, applying the appropriate swap action for each window.
windows : LISTofSWAPINFO
(Errors: Match, Window, Value)
The following type definitions apply:
SWAPINFO : [ WINDOW window; SWAPACTION swap-action ]
SWAPACTION : {Undefined, Background, Untouched, Copied}
Each window passed into the request must be a valid WINDOW (or a Window error results). Each window passed into the request must be a double-buffered window (or a Match error results). Each window passed into the request must only be listed once (or a Match error results). Each swap-action in the list must have one of the values specified for type SWAPACTION (or a Value error results). If an error results, none of the valid double-buffered windows will have their buffers swapped.
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:
If DBESwapBuffers is included in a ``swap and clear'' type of idiom, it must immediately follow the DBEBeginIdiom request.
This request informs the server that a complex swap will immediately follow this request.
As previously discussed, a complex swap action is a group/series of requests, which, 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.
This request informs the server that a complex swap has concluded.
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.
This request returns information about a back buffer.
back-buffer-name : BACKBUFFER => attributes : BUFFER_ATTRIBUTES
The following type definitions apply:
BUFFER_ATTRIBUTES: [WINDOW window;]
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.
Refer to the X11 Protocol Encoding document, as this section uses syntactic conventions and data types established there.
The name of this extension is ``DOUBLE-BUFFER''.
The following new types are used by the extension.
BACKBUFFER : XID
SWAPACTION #x00 Undefined #x01 Background #x02 Untouched #x03 Copied
SWAPINFO 4 WINDOW window 1 SWAPACTION swap action 3 unused
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
Buffer 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
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 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 1 CARD8 server-major-version 1 CARD8 server-minor-version 22 unused
1 CARD8 major-opcode 1 1 minor-opcode 4 WINDOW window 4 BACKBUFFER back buffer name 1 SWAPACTION swap action hint 3 unused
1 CARD8 major-opcode 1 2 minor-opcode 4 BACKBUFFER back buffer name
1 CARD8 major-opcode 1 4 minor-opcode 4 CARD32 n, number of window/swap action pairs in list 8n LISTofSWAPINFO window/swap action pairs
1 CARD8 major-opcode 1 4 minor-opcode 2 1 request length
1 CARD8 major-opcode 1 5 minor-opcode 2 1 request length
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
1 CARD8 major-opcode 1 7 minor-opcode4 2 2 request length 4 BACKBUFFER back-buffer-name => 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 4 BUFFER_ATTRIBUTES attributes 20 unused
The header for this extension is <X11/extensions/Xdbe.h>. All identifier names provided by this header begin with Xdbe.
The type XdbeBackBuffer is a Drawable .
The type XdbeSwapAction can be one of the constants XdbeUndefined , XdbeBackground, XdbeUntouched, or XdbeCopied.
The C routines 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 Status will return non-zero for success and zero for failure.
Status XdbeQueryExtension ( Display * dpy , int * major_version_return, int * minor_version_return
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, this function returns non-zero. 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, this function 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.
XdbeScreenVisualInfo * XdbeGetVisualInfo ( Display * dpy, Drawable * screen_specifiers, int * num_screens
This function 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, else it returns a pointer to a list of XdbeScreenVisualInfo structures of length num_screens. The nth element in the returned list corresponds to the nth drawable in the screen_specifiers list, unless num_screens was passed in with the value zero, in which case the nth element in the returned list corresponds to the nth screen of the server, starting with screen zero.
The XdbeScreenVisualInfo structure has the following fields:
int count number of items in visinfo
XdbeVisualInfo* visinfo list of visuals and depths for
this screen
The XdbeVisualInfo structure has the following fields:
VisualID visual one visual ID that supports
double-buffering
int depth depth of visual in bits
int perflevel performance level of visual
void XdbeFreeVisualInfo (XdbeScreenVisualInfo * visual_info)
This function frees the list of XdbeScreenVisualInfo returned by the function XdbeGetVisualInfo.
XdbeBackBuffer XdbeAllocateBackBufferName (Display * dpy , Window window , XdbeSwapAction swap_action)
This function 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 XdbeSwapBuffers. The actual swap action used in calls to 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.
Status XdbeDeallocateBackBufferName (Display * dpy , XdbeBackBuffer buffer)
This function frees a drawable ID, buffer, that was obtained using XdbeAllocateBackBufferName. The buffer must be a valid name for the back buffer of a window, or an XdbeBadBuffer error results.
Status XdbeSwapBuffers (Display * dpy , XdbeSwapInfo * swap_info, int num_windows)
This function 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 XdbeSwapInfo structure has the following fields:
Window swap_window window for which to swap buffers
XdbeSwapAction swap_action swap action to use for this
wap_window
Status XdbeBeginIdiom (Display * dpy)
This function marks the beginning of an idiom sequence. See "Complex Swap Actions"for a complete discussion of idioms.
Status XdbeEndIdiom (Display * dpy)
This function marks the end of an idiom sequence.
XdbeBackBufferAttributes * XdbeGetBackBufferAttributes (Display * dpy , XdbeBackBuffer buffer)
This function returns the attributes associated with the specified buffer.
The XdbeBackBufferAttributes structure has the following fields:
Window window window that buffer belongs to
If buffer is not a valid XdbeBackBuffer, window is set to None.
The returned XdbeBackBufferAttributes structure can be freed with the Xlib function XFree.
The XdbeBufferError structure has the following fields:
int type Display * display Display the event was read from XdbeBackBuffer buffer resource id unsigned long serial serial number of failed request unsigned char error_code error base + XdbeBadBuffer unsigned char request_code Major op-code of failed request unsigned char minor_code Minor op-code of failed request