aboutsummaryrefslogtreecommitdiff
path: root/libXext/man/DBE.man
diff options
context:
space:
mode:
Diffstat (limited to 'libXext/man/DBE.man')
-rw-r--r--libXext/man/DBE.man317
1 files changed, 317 insertions, 0 deletions
diff --git a/libXext/man/DBE.man b/libXext/man/DBE.man
new file mode 100644
index 000000000..e8263cef3
--- /dev/null
+++ b/libXext/man/DBE.man
@@ -0,0 +1,317 @@
+.\" $Xorg: DBE.man,v 1.3 2000/08/17 19:41:55 cpqbld Exp $
+.\"
+.\" Copyright (c) 1995 Hewlett-Packard Company
+.\"
+.\" Permission is hereby granted, free of charge, to any person obtaining a
+.\" copy of this software and associated documentation files (the "Software"),
+.\" to deal in the Software without restriction, including without limitation
+.\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
+.\" and/or sell copies of the Software, and to permit persons to whom the
+.\" Software furnished to do so, subject to the following conditions:
+.\"
+.\" The above copyright notice and this permission notice shall be included in
+.\" all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+.\" HEWLETT-PACKARD COMPANY BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+.\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+.\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+.\" SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of the Hewlett-Packard Company shall not
+.\" be used in advertising or otherwise to promote the sale, use or other
+.\" dealing in this Software without prior written authorization from the
+.\" Hewlett-Packard Company.
+.\"
+.\" $XFree86: xc/doc/man/Xext/dbe/DBE.man,v 3.4 2001/01/27 18:20:19 dawes Exp $
+.\"
+.TH DBE __libmansuffix__ __xorgversion__ "X FUNCTIONS"
+.SH NAME
+DBE - Double Buffer Extension
+.SH SYNOPSIS
+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, 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.
+.SH DESCRIPTION
+.B Concepts
+.RS
+Normal windows are created using
+.B XCreateWindow()
+or
+.B XCreateSimpleWindow(),
+which allocate 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
+.I (XIDs)
+with the window, for use when referring
+to (i.e., drawing to or reading from) the window's back buffer.
+The back buffer name is a drawable of type
+.I XdbeBackBuffer.
+
+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 ae treated the same. In
+particular, here are some important characteristics:
+
+.RS
+Only one buffer per window can be visible at a time (the front buffer).
+
+Both buffers associated with a window have the same visual type, depth,
+width, height, and shape as the window.
+
+Both buffers associated with a window are "visible" (or "obscured") in
+the same way. When an Expose event is generated for a window, this
+event is considered to apply to both buffers equally. When a
+double-buffered window is exposed, both buffers are tiled with the
+window background.
+Even though the back buffer is not visible, terms such as obscure apply to the
+back buffer as well as to the front buffer.
+
+It is acceptable at any time to pass an
+.I XdbeBackBuffer
+in any function that expects a drawable.
+This enables an application to draw directly into
+.I XdbeBackBuffer
+in the same fashion as it would draw into any other drawable.
+
+It is an error (Window) to pass an
+.I XdbeBackBuffer
+in a function that expects a Window.
+
+An
+.I XdbeBackBuffer
+will never be sent in a reply, event, or error where a Window is specified.
+
+If backing-store and save-under applies to a double-buffered
+window, it applies to both buffers equally.
+
+If the
+.B XClearArea()
+or
+.B XClearWindow()
+function is executed on a
+double-buffered window, the same area in both the front and back buffers
+is cleared.
+.RE
+
+The effect of passing a window to a function that accepts a drawable
+is unchanged by this extension. The window and front buffer are synonymous
+with each other. This includes obeying the
+.B XGetImage()
+and
+.B XGetSubImage()
+semantics and the subwindow-mode semantics if a graphics context is
+involved. Regardless of whether the window was explicitly passed in an
+.B XGetImage()
+or
+.B XGetSubImage()
+call, or implicitly referenced (i.e., one of
+the window's ancestors was passed in the function), the front (i.e. visible)
+buffer is always referenced.
+Thus, DBE-naive screen dump clients will always get the front buffer.
+.B XGetImage()
+and
+.B XGetSubImage()
+on a back
+buffer return 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 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 does not extend the semantics of any existing
+events with the exception of adding a new drawable type called
+.I XdbeBackBuffer.
+
+If events, replies, or errors that contain a drawable
+(e.g., 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. Applications
+that need such facilities (e.g., to maintain a constant frame rate) should
+investigate the Synchronization Extension, an X Consortium standard.
+.RE
+
+.B Window Management Operations
+
+.RS
+The basic philosophy of DBE is that both buffers are treated the same by
+X window management operations.
+
+When a double-buffered window is destroyed,
+both buffers associated with the window are destroyed, and all back buffer
+names associated with the window are freed.
+
+If the size of a double-buffered window changes, 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,
+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
+.B XGetGeometry()
+function is executed on an
+.I XdbeBackBuffer,
+the returned x, y, and border-width will be zero.
+
+If the Shape extension
+.B ShapeRectangles, ShapeMask, ShapeCombine,
+or
+.B ShapeOffset
+request is executed on a double-buffered window, both
+buffers are reshaped to match the new window shape. The region difference
+D = new shape - old shape is tiled with the window background in both
+buffers, and Expose events are generated for D.
+.RE
+
+.B Complex Swap Actions
+
+.RS
+DBE has no explicit knowledge of ancillary buffers (e.g. 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
+applications'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 function calls:
+.B XdbeBeginIdiom()
+and
+.B XdbeEndIdiom().
+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
+X to clear only certain planes of the back buffers, the application would
+make the following calls as a group, and in the following order:
+
+.RS
+.B XdbeBeginIdiom().
+
+.B XdbeSwapBuffers()
+with XIDs for two windows, each of which uses a swap action of Untouched.
+
+.B XFillRectangle()
+to the back buffer of one window.
+
+.B XFillRectangle()
+to the back buffer of the other window.
+
+.B XdbeEndIdiom().
+.RE
+
+The
+.B XdbeBeginIdiom()
+and
+.B XdbeEndIdiom()
+functions 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 non-recognized groups/series of requests. If these
+function calls are made out of order, or are mismatched, no errors are sent,
+and the functions are executed as usual, though performance may suffer.
+
+.B XdbeSwapBuffers()
+need not be included in an idiom. For
+example, if a swap action of Copied is desired, but only some of the planes
+should be copied,
+.B XCopyArea()
+may be used instead of
+.B XdbeSwapBuffers().
+If
+.B XdbeSwapBuffers()
+is included in an idiom, it should immediately follow the
+.B XdbeBeginIdiom()
+call. Also, when the
+.B XdbeSwapBuffers()
+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
+.B XFillRectangle()
+using a client clip rectangle is done to the window's back
+buffer after the
+.B XdbeSwapBuffers()
+call, 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 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
+.B XdbeBeginIdiom(),
+idiom, and
+.B XdbeEndIdiom()
+calls. Usage of these functions will ensure best possible
+performance across a wide variety of implementations.
+.SH SEE ALSO
+.I XdbeAllocateBackBufferName(),
+.I XdbeBeginIdiom(),
+.I XdbeDeallocateBackBufferName(),
+.I XdbeEndIdiom(),
+.I XdbeFreeVisualInfo(),
+.I XdbeGetBackBufferAttributes(),
+.I XdbeGetVisualInfo(),
+.I XdbeQueryExtension(),
+.I XdbeSwapBuffers().
+