aboutsummaryrefslogtreecommitdiff
path: root/libXext/man/DBE.man
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2010-10-07 20:22:49 +0000
committermarha <marha@users.sourceforge.net>2010-10-07 20:22:49 +0000
commita0fec3241c7f4bd166dc235d840bea6d660b0339 (patch)
tree8012487695d27e5abd8cdf2461ab075733e8adf6 /libXext/man/DBE.man
parent51f3d1e140307561f64c47dae1d44f912accb5cf (diff)
downloadvcxsrv-a0fec3241c7f4bd166dc235d840bea6d660b0339.tar.gz
vcxsrv-a0fec3241c7f4bd166dc235d840bea6d660b0339.tar.bz2
vcxsrv-a0fec3241c7f4bd166dc235d840bea6d660b0339.zip
libXext xserver libXau libXinerama update 7/10/2010
Diffstat (limited to 'libXext/man/DBE.man')
-rw-r--r--libXext/man/DBE.man630
1 files changed, 313 insertions, 317 deletions
diff --git a/libXext/man/DBE.man b/libXext/man/DBE.man
index e8263cef3..6199d4917 100644
--- a/libXext/man/DBE.man
+++ b/libXext/man/DBE.man
@@ -1,317 +1,313 @@
-.\" $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().
-
+.\" 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 __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().
+