R6.6 is the Xorg base-lineXORG-MAINXORG-STABLE

1 files changed, 314 insertions, 0 deletions

diff --git a/man/DBE.man b/man/DBE.man
new file mode 100644
index 0000000..bf36222
--- /dev/null
+++ b/man/DBE.man
@@ -0,0 +1,314 @@
+.\" $Xorg: DBE.man,v 1.4 2001/03/16 17:49:55 pookie 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.
+.TH DBE 3X11 "Release 6.6" "X Version 11" "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 synonomous
+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().
+