git update 9/7/2010

7 files changed, 3990 insertions, 0 deletions

diff --git a/libXext/specs/Makefile.am b/libXext/specs/Makefile.am
new file mode 100644
index 000000000..700969074
--- /dev/null
+++ b/libXext/specs/Makefile.am
@@ -0,0 +1,64 @@
+#

+# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.

+#

+# 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 is furnished to do so, subject to the following conditions:

+#

+# The above copyright notice and this permission notice (including the next

+# paragraph) 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

+# THE AUTHORS OR COPYRIGHT HOLDERS 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.

+#

+

+if ENABLE_SPECS

+doc_sources = dbelib.xml dpmslib.xml shapelib.xml synclib.xml

+dist_doc_DATA = $(doc_sources)

+

+if HAVE_XMLTO

+doc_DATA = $(doc_sources:.xml=.html)

+

+if HAVE_FOP

+doc_DATA += $(doc_sources:.xml=.ps) $(doc_sources:.xml=.pdf)

+endif

+

+if HAVE_XMLTO_TEXT

+doc_DATA += $(doc_sources:.xml=.txt)

+endif

+

+if HAVE_STYLESHEETS

+XMLTO_FLAGS = -m $(XSL_STYLESHEET)

+

+doc_DATA += xorg.css

+xorg.css: $(STYLESHEET_SRCDIR)/xorg.css

+	$(AM_V_GEN)cp -pf $(STYLESHEET_SRCDIR)/xorg.css $@

+endif

+

+CLEANFILES = $(doc_DATA)

+

+SUFFIXES = .xml .ps .pdf .txt .html

+

+.xml.txt:

+	$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $<

+

+.xml.html:

+	$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $<

+

+.xml.pdf:

+	$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $<

+

+.xml.ps:

+	$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $<

+

+endif HAVE_XMLTO

+endif ENABLE_SPECS

diff --git a/libXext/specs/dbelib.tex b/libXext/specs/dbelib.tex
new file mode 100644
index 000000000..a1b526b6f
--- /dev/null
+++ b/libXext/specs/dbelib.tex
@@ -0,0 +1,621 @@
+% $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|<X11/extensions/Xdbe.h>|.  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}

diff --git a/libXext/specs/dbelib.xml b/libXext/specs/dbelib.xml
new file mode 100644
index 000000000..34bcc711b
--- /dev/null
+++ b/libXext/specs/dbelib.xml
@@ -0,0 +1,728 @@
+<?xml version="1.0" encoding="UTF-8" ?>

+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

+

+

+<!-- lifted from troff+ms+XMan by doclifter -->

+<book id="dbelib">

+

+<bookinfo>

+   <title>Double Buffer Extension Library</title>

+   <subtitle>X Consortium Standard</subtitle>

+   <!-- <releaseinfo>X Version 11, Release 6.4</releaseinfo> -->

+   <authorgroup>

+      <author>

+         <firstname>Ian</firstname><surname>Elliot</surname>

+      </author>

+   </authorgroup>

+   <othercredit>

+      <firstname>Davide</firstname><surname>Wiggins</surname>

+   </othercredit>

+   <corpname>Hewlett-Packard Company</corpname>

+   <copyright><year>1989</year><holder>X Consortium, Inc and Digital Equipment Corporation</holder></copyright>

+   <copyright><year>1992</year><holder>X Consortium, Inc and Intergraph Corporation</holder></copyright>

+   <copyright><year>1993</year><holder>X Consortium, Inc and Silicon Graphics, Inc.</holder></copyright>

+   <copyright><year>1994</year><holder>X Consortium, Inc and Hewlett-Packard Company</holder></copyright>

+   <copyright><year>1995</year><holder>X Consortium, Inc and Hewlett-Packard Company</holder></copyright>

+   <releaseinfo>Version 1.0</releaseinfo>

+   <affiliation><orgname>X Consortium</orgname></affiliation>

+   <productnumber>X Version 11, Release 7</productnumber>

+

+<legalnotice>

+<para>

+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.

+</para>

+

+</legalnotice>

+

+</bookinfo>

+

+<chapter id="introduction">

+<title>Introduction</title>

+<para>

+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.

+</para>

+

+</chapter>

+

+<chapter id="goals">

+<title>Goals</title>

+

+<para>

+This extension should enable clients to:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Allocate and deallocate double-buffering for a window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Draw to and read from the front and back buffers associated with a window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Swap the front and back buffers associated with a window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+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).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Request that the front and back buffers associated with multiple

+double-buffered windows be swapped simultaneously.

+    </para>

+  </listitem>

+</itemizedlist>

+

+<para>

+In addition, the extension should:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Allow multiple clients to use double-buffering on the same window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Support a range of implementation methods that can capitalize on

+existing hardware features.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Add no new event types.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Be reasonably easy to integrate with a variety of direct graphics

+hardware access (DGHA) architectures.

+    </para>

+  </listitem>

+</itemizedlist>

+

+</chapter>

+

+<chapter id="concepts">

+<title>Concepts</title>

+<para>

+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.

+</para>

+<para>

+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 (that is, drawing to or reading from) the window’s back buffer. The back

+buffer name is a DRAWABLE of type BACKBUFFER.

+</para>

+<para>

+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.

+</para>

+<para>

+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.

+</para>

+<para>

+In general, both the front and back buffers are treated the same.

+particular, here are some important characteristics:

+</para>

+<itemizedlist>

+  <listitem>

+    <para>

+Only one buffer per window can be visible at a time (the front buffer).

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Both buffers associated with a window have the same visual type, depth,

+width, height, and shape as the window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Both buffers associated with a window are "visible" (or "obscured") in

+the same way. When an 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 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.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It is acceptable at any time to pass a BACKBUFFER in any request,

+notably any core or extension drawing request, that expects a

+DRAWABLE.  This enables an application to draw directly into

+BACKBUFFERs in the same fashion as it would draw into any other

+DRAWABLE.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+It is an error (Window) to pass a BACKBUFFER in a core request that

+expects a Window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+A BACKBUFFER will never be sent by core X in a reply, event, or

+error where a Window is specified.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If core X11 backing-store and save-under applies to a double-buffered

+window, it applies to both buffers equally.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+If the core ClearArea request is executed on a double-buffered window,

+the same area in both the front and back buffers is cleared.

+    </para>

+  </listitem>

+</itemizedlist>

+

+<para>

+The effect of passing a window to a request that accepts a

+<function>DRAWABLE</function> is

+unchanged by this extension. The window and front buffer are synonomous

+with each other. This includes obeying the <function>GetImage</function>

+semantics and the

+subwindow-mode semantics if a core graphics context is involved. Regardless

+of whether the window was explicitly passed in a

+<function>GetImage</function> 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-naive screen dump clients will always get the front buffer.

+<function>GetImage</function> on

+a back buffer returns undefined image contents for any obscured regions of the

+back buffer that fall within the image.

+</para>

+<para>

+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

+<function>ClipByChildren</function>. 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 <function>IncludeInferiors</function> drawing touched.

+</para>

+

+

+<para>

+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

+BACKBUFFER. If events, replies, or errors that contain a DRAWABLE (for

+example, <function>GraphicsExpose</function>) are generated in response to

+a request, the

+DRAWABLE returned will be the one specified in the request.

+</para>

+<para>

+DBE advertises which visuals support double-buffering.

+</para>

+<para>

+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.

+</para>

+

+<sect1 id="window_management_operations">

+<title>Window Management Operations</title>

+

+<para>

+The basic philosophy of DBE is that both buffers are treated the same by core

+X window management operations.

+</para>

+<para>

+When the core <function>DestroyWindow</function> 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.

+</para>

+<para>

+If the core <function>ConfigureWindow</function> 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

+<function>ConfigureWindow</function>

+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,

+<function>Expose</function> 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.

+</para>

+<para>

+If the Shape extension

+<function>ShapeRectangles</function>,

+<function>ShapeMask</function>,

+<function>ShapeCombine</function>, or

+<function>ShapeOffset</function>

+request is executed on a double-buffered window, both buffers

+are reshaped to match the new window shape. The region difference is the

+following:

+</para>

+

+<literallayout remap='Ds'>

+        D = newshape − oldshape

+</literallayout>

+

+<para>

+It is tiled with the window background in both buffers, and

+<function>Expose</function>

+events are generated for D.

+</para>

+

+</sect1>

+

+<sect1 id="complex_swap_actions">

+<title>Complex Swap Actions</title>

+<para>

+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.

+</para>

+<para>

+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:

+<function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>.

+Unless this begin-end pair surrounds the idiom, it may not be recognized

+by a given implementation, and performance will suffer.

+</para>

+<para>

+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:

+</para>

+

+<itemizedlist>

+  <listitem>

+    <para>

+<function>DBEBeginIdiom</function> request.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>DBESwapBuffers</function> request with XIDs for two windows, each of which uses

+a swap action of Untouched.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Core X <function>PolyFillRectangle</function> request to the back buffer of one window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+Core X <function>PolyFillRectangle</function> request to the back buffer of the other

+window.

+    </para>

+  </listitem>

+  <listitem>

+    <para>

+<function>DBEEndIdiom</function> request.

+    </para>

+  </listitem>

+</itemizedlist>

+

+<para>

+The <function>DBEBeginIdiom</function> and <function>DBEEndIdiom</function>

+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.

+</para>

+

+<para>

+

+An idiom need not include a <function>DBESwapBuffers</function> request.

+For example, if a swap action of <function>Copied</function> is desired,

+but only some of the planes should be copied, a core X

+<function>CopyArea</function> request may be used instead of

+<function>DBESwapBuffers</function>. If

+<function>DBESwapBuffers</function> is included in an idiom, it should

+immediately follow the

+<function>DBEBeginIdiom</function> request. Also, when the

+<function>DBESwapBuffers</function> 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 <function>Untouched</function>, and if a

+<function>PolyFillRectangle</function> using a client clip

+rectangle is done to the window’s back buffer after the

+<function>DBESwapBuffers</function> 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.

+</para>

+<para>

+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

+<function>DBEBeginIdiom</function> request, the idiom

+requests, and <function>DBEEndIdiom</function> request. Usage of these

+functions will ensure best possible performance across a wide

+variety of implementations.

+</para>

+

+</sect1>

+</chapter>

+

+<chapter id="c_language_bindings">

+<title>C Language Binding</title>

+<para>

+All identifier The header for this extension is &lt;X11/extensions/Xdbe.h&gt;.

+names provided by this header begin with Xdbe.

+</para>

+

+<sect1 id="types">

+<title>Types</title>

+

+<para>

+The type <function>XdbeBackBuffer</function> is a <function>Drawable</function>.

+</para>

+

+<para>

+The type <function>XdbeSwapAction</function> can be one of the constants

+<function>XdbeUndefined</function>,

+<function>XdbeBackground</function>,

+<function>XdbeUntouched</function>, or

+<function>XdbeCopied</function>.

+</para>

+

+</sect1>

+

+<sect1 id="c_functions">

+<title>C Functions</title>

+<para>

+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

+<function>Status</function> will return nonzero for success and

+zero for failure.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XdbeQueryExtension</function></funcdef>

+    <paramdef>Display <parameter> *dpy</parameter></paramdef>

+    <paramdef>int <parameter> *major_version_return</parameter></paramdef>

+    <paramdef>int <parameter> *minor_version_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XdbeQueryExtension</function> 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.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XdbeScreenVisualInfo *<function>XdbeGetVisualInfo</function></funcdef>

+    <paramdef>Display <parameter> *dpy</parameter></paramdef>

+    <paramdef>Drawable <parameter> *screen_specifiers</parameter></paramdef>

+    <paramdef>int <parameter> *num_screens</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+

+<function>XdbeGetVisualInfo</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; otherwise, it returns a pointer to a list of

+<function>XdbeScreenVisualInfo</function>

+structures of length num_screens.  The nth element in the returned list

+corresponds to the nth drawable in the screen_specifiers list, unless

+

+element in the returned list corresponds to the nth screen of the server,

+starting with screen zero.

+</para>

+

+

+<para>

+The XdbeScreenVisualInfo structure has the following fields:

+</para>

+<literallayout remap='Ds'>

+int                     count      number of items in visinfo

+XdbeVisualInfo*    visinfo     list of visuals and depths for this screen

+</literallayout>

+

+<para>

+The <function>XdbeVisualInfo</function> structure has the following fields:

+</para>

+

+<literallayout remap='Ds'>

+VisualID         visual    one visual ID that supports double-buffering

+int              depth     depth of visual in bits

+int              perflevel  performance level of visual

+</literallayout>

+

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void XdbeFreeVisualInfo <function>XdbeGetVisualInfo</function></funcdef>

+    <paramdef>XdbeScreenVisualInfo <parameter> *visual_info</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XdbeFreeVisualInfo</function> frees the list of

+<function>XdbeScreenVisualInfo</function> returned by

+<function>XdbeGetVisualInfo</function>.

+</para>

+

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XdbeBackBuffer <function>XdbeAllocateBackBufferName</function></funcdef>

+    <paramdef>Display <parameter> *dpy</parameter></paramdef>

+    <paramdef>Window <parameter> *window</parameter></paramdef>

+    <paramdef>XdbeSwapAction <parameter> swap_action</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+

+<para>

+<function>XdbeAllocateBackBufferName</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 <function>XdbeSwapBuffers</function>.  The actual swap_action

+used in calls to <function>XdbeSwapBuffers</function> 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.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XdbeDeallocateBackBufferName</function></funcdef>

+    <paramdef>Display <parameter> *dpy</parameter></paramdef>

+    <paramdef>XdbeBackBuffer <parameter> buffer</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XdbeDeallocateBackBufferName</function> frees the specified

+drawable ID, buffer, that was obtained via

+<function>XdbeAllocateBackBufferName</function>. The buffer must be a valid

+name for the back buffer of a window, or an

+<function>XdbeBadBuffer</function> error results.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XdbeSwapBuffers</function></funcdef>

+    <paramdef>Display <parameter> *dpy</parameter></paramdef>

+    <paramdef>XdbeSwapInfo <parameter> *swap_info</parameter></paramdef>

+    <paramdef>int <parameter> num_windows</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XdbeSwapBuffers</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.

+</para>

+<para>

+The XdbeSwapInfo structure has the following fields:

+</para>

+

+<literallayout remap='Ds'>

+Window              swap_window    window for which to swap buffers

+XdbeSwapAction      swap_action    swap action to use for this swap window

+</literallayout>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XdbeBeginIdiom</function></funcdef>

+    <paramdef>Display <parameter> *dpy</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XdbeBeginIdiom</function> marks the beginning of an idiom

+sequence. See

+<link linkend="complex_swap_actions">

+<xref linkend="complex_swap_actions"></xref></link>

+for a complete discussion of idioms.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XdbeEndIdiom</function></funcdef>

+    <paramdef>Display <parameter> *dpy</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XdbeEndIdiom</function> marks the end of an idiom sequence.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XdbeBackBufferAttributes *<function>XdbeGetBackBufferAttributes</function></funcdef>

+    <paramdef>Display <parameter> *dpy</parameter></paramdef>

+    <paramdef>XdbeBackBuffer <parameter> buffer</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XdbeGetBackBufferAttributes</function> returns the attributes associated with

+the specified buffer.

+</para>

+<para>

+The XdbeBackBufferAttributes structure has the following fields:

+</para>

+

+<literallayout remap='Ds'>

+Window           window           window that buffer belongs to

+</literallayout>

+

+<para>

+If buffer is not a valid <function>XdbeBackBuffer</function>, window is

+set to None.

+</para>

+<para>

+The returned <function>XdbeBackBufferAttributes</function> structure

+can be freed with the Xlib function <function>XFree</function>.

+</para>

+</sect1>

+

+<sect1 id="errors">

+<title>Errors</title>

+<para>

+The <function>XdbeBufferError</function> structure has the following fields:

+</para>

+<literallayout remap='Ds'>

+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 + <function>XdbeBadBuffer</function>

+unsigned char       request code  Major op-code of failed request

+unsigned char       minor code    Minor op-code of failed request

+</literallayout>

+</sect1>

+</chapter>

+

+<chapter id="acknowledgements">

+<title>Acknowledgements</title>

+

+<para>

+We wish to thank the following individuals who have contributed their time

+and talent toward shaping the DBE specification:

+</para>

+<para>

+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.

+</para>

+<para>

+Mark provided the impetus to start the DBE project. Ian wrote the first draft

+of the specification. David served as architect.

+</para>

+

+</chapter>

+<chapter id="references">

+<title>References</title>

+<para>

+Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension

+Specification Version 3.3."

+</para>

+<para>

+Tim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins, "X

+Synchronization Extension Version 3.0."

+</para>

+</chapter>

+</book>

diff --git a/libXext/specs/dpmslib.xml b/libXext/specs/dpmslib.xml
new file mode 100644
index 000000000..fead7a8c3
--- /dev/null
+++ b/libXext/specs/dpmslib.xml
@@ -0,0 +1,419 @@
+<?xml version="1.0" encoding="UTF-8" ?>

+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

+

+<!-- lifted from troff+ms+XMan by doclifter -->

+<book id="dpmslib">

+

+<bookinfo>

+   <title>X Display Power Management Signaling (DPMS) Extension</title>

+   <subtitle>X Consortium Standard</subtitle>

+   <releaseinfo>X Version 11, Release 6.8</releaseinfo>

+   <authorgroup>

+      <author>

+         <firstname>Rob</firstname><surname>Lembree</surname>

+      </author>

+   </authorgroup>

+   <corpname>Digital Equipment Corporation</corpname>

+   <copyright><year>1996</year><holder>X Consortium</holder></copyright>

+   <releaseinfo>Version 1.0</releaseinfo>

+   <affiliation><orgname>X Consortium</orgname></affiliation>

+   <productnumber>X Version 11, Release 6.8</productnumber>

+

+<legalnotice>

+<para>

+Permission to use, copy, modify, distribute, and sell this

+documentation for any purpose is hereby granted without fee,

+provided that the above copyright notice and this permission

+notice appear in all copies.  Digital Equipment Corporation

+makes 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.

+</para>

+

+<para>

+<emphasis remap='I'>X Window System</emphasis> is a trademark of The Open Group.

+</para>

+</legalnotice>

+

+</bookinfo>

+

+<chapter id='overview'>

+<title>Overview</title>

+

+<para>This extension provides X Protocol control over the VESA Display

+Power Management Signaling (DPMS) characteristics of video boards

+under control of the X Window System.

+</para>

+

+<para>

+Traditionally, the X Window System has provided for both blanking and

+non-blanking screen savers.  Timeouts associated with these built-in

+screen saver mechanisms are limited to idle (dwell) time, and a change

+timeout that specifies the change interval for non-blanking screen savers.

+</para>

+

+<para>

+The United States' Environmental Protection Agency (EPA) Energy Star program

+requires that monitors power down after some idle time by default.

+While it is possible to simply overload the existing screen saver timeouts,

+this solution leaves the non-privileged user little to no control over

+the DPMS characteristics of his or her system.  For example, disabling

+DPMS would require some unintended side effect in the core screen saver,

+such as disabling the changing of a non-blanking screen saver.  Providing

+clients with this control requires an extension to the core X Window System

+Protocol, and this extension seeks to fill this gap.

+</para>

+

+<para>

+There are four power levels specified by the Video Electronics Standards

+Association (VESA) Display Power Management Signaling (DPMS) standard.

+These are mapped onto the X DPMS Extension like this:

+</para>

+

+<literallayout remap='Ds'>

+<function>DPMS Extension Power Levels</function>

+     0     DPMSModeOn               In use

+     1     DPMSModeStandby          Blanked, low power

+     2     DPMSModeSuspend          Blanked, lower power

+     3     DPMSModeOff               Shut off, awaiting activity

+</literallayout> <!-- remap='De' -->

+

+</chapter>

+

+<chapter id='dpms_functions'>

+<title>DPMS Functions</title>

+

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function>DPMSQueryExtention</function></funcdef>

+    <paramdef>Display <parameter>*display</parameter></paramdef>

+    <paramdef>int <parameter>event_base</parameter></paramdef>

+    <paramdef>int <parameter>error_base</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist remap='IP'>

+  <varlistentry>

+    <term><emphasis remap='I'>*display</emphasis></term>

+    <listitem><para>Specifies the connection to the X server.</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>event_base</emphasis></term>

+    <listitem><para>Specifies the return location for the assigned base event</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>error_base</emphasis></term>

+    <listitem><para>Specifies the return location for the assigned base error</para></listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+The DPMSQueryExtension function queries the X server to determine the

+availability of the DPMS Extension.  If the extension is available, the

+return value is TRUE, and <emphasis remap='I'>event_base</emphasis> and

+<emphasis remap='I'>error_base</emphasis> are set to the base event number

+and base error number for the extension, respectively.  Otherwise, the

+return value is FALSE, and the values of

+<emphasis remap='I'>event_base</emphasis> and

+<emphasis remap='I'>error_base</emphasis> are undefined.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>DPMSGetVersion</function></funcdef>

+    <paramdef>Display <parameter>*display</parameter></paramdef>

+    <paramdef>int <parameter>*major_version</parameter></paramdef>

+    <paramdef>int <parameter>*minor_version</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist remap='IP'>

+  <varlistentry>

+    <term><emphasis remap='I'>display</emphasis></term>

+    <listitem><para>Specifies the connection to the X server.</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>major_version</emphasis></term>

+    <listitem><para>Specifies the return location for the extension major version.</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>minor_version</emphasis></term>

+    <listitem><para>Specifies the return location for the extension minor version.</para></listitem>

+  </varlistentry>

+</variablelist>

+

+

+<para>

+The DPMSGetVersion function returns the version of the DPMS extension

+implemented by the X server.  The version is returned in

+<emphasis remap='I'>major_version</emphasis> and

+<emphasis remap='I'>minor_version</emphasis>.

+The major version and minor version for this specification are '1' and '1',

+respectively.  The major version will be incremented for protocol

+incompatible changes, and the minor version will be incremented for small,

+upwardly compatible changes.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function>DPMSCapable</function></funcdef>

+    <paramdef>Display <parameter>*display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist remap='IP'>

+  <varlistentry>

+    <term><emphasis remap='I'>display</emphasis></term>

+    <listitem><para>Specifies the connection to the X server.</para></listitem>

+  </varlistentry>

+</variablelist>

+

+

+<para>

+The DPMSCapable function returns the DPMS capability of the X server, either

+TRUE (capable of DPMS) or FALSE (incapable of DPMS).  The capability of an

+X server is implementation defined.  For example, if a multi-headed  X server

+is capable of DPMS on one head, and incapable on another, the truth value of

+this function is defined by the X server implementation.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>DPMSSetTimeouts</function></funcdef>

+    <paramdef>Display <parameter>*display</parameter></paramdef>

+    <paramdef>CARD16 <parameter>standby</parameter></paramdef>

+    <paramdef>CARD16 <parameter>suspend</parameter></paramdef>

+    <paramdef>CARD16 <parameter>off</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist remap='IP'>

+  <varlistentry>

+    <term><emphasis remap='I'>display</emphasis></term>

+    <listitem><para>Specifies the connection to the X server.</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>standby</emphasis></term>

+    <listitem><para>Specifies the new standby timeout in seconds.</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>suspend</emphasis></term>

+    <listitem><para>Specifies the new suspend timeout in seconds.</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>off</emphasis></term>

+    <listitem><para>Specifies the new off timeout in seconds.</para></listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+The DPMSSetTimeouts function permits applications to set the timeout values

+used by the X server for DPMS timings.

+</para>

+

+<para>

+The value <emphasis remap='I'>standby</emphasis> is the amount of time of

+inactivity in seconds before standby mode is invoked. The actual effects of

+this mode are implementation defined, but in the case of DPMS compliant

+hardware, it is implemented by shutting off the horizontal sync signal,

+and pulsing the vertical sync signal.

+Standby mode provides the quickest monitor recovery time.  Note also that

+many monitors implement this mode identically to suspend mode.  A value

+of zero disables this mode.

+</para>

+

+<para>

+The value <emphasis remap='I'>suspend</emphasis> is the amount of time of

+inactivity in seconds before the second level of power savings is invoked.

+Suspend mode's physical and electrical characteristics are implementation

+defined, but in DPMS compliant hardware, results in the pulsing of the

+horizontal sync signal, and shutting off of the vertical sync signal.

+Suspend mode recovery is considered to be slower than standby mode, but

+faster than off mode, however this is monitor dependent.  As noted above,

+many monitors implement this mode identically to standby mode.  A value of

+zero disables this mode.

+</para>

+

+<para>

+The value <emphasis remap='I'>off</emphasis> is the amount of time of

+inactivity in seconds before the third and final level of power savings is

+invoked. Off mode's physical and electrical characteristics are

+implementation defined, but in DPMS compliant hardware, is implemented by

+shutting off both horizontal and vertical sync signals, resulting in

+the power-down of the monitor.  Recovery time is implementation dependant,

+but frequently is similar to the power-up time of the monitor.  A value

+of zero disables this mode.

+</para>

+

+<para>

+Chronologically, standby mode occurs before or simultaneously with

+suspend mode, and suspend mode must occur before or simultaneously with

+off mode.  Therefore, non-zero mode timeout values must be greater than

+or equal to the timeout values of earlier modes.  If inconsistent values

+are supplied, a BadValue error will result.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>DPMSGetTimeouts</function></funcdef>

+    <paramdef>Display <parameter>*display</parameter></paramdef>

+    <paramdef>CARD16 <parameter>*standby</parameter></paramdef>

+    <paramdef>CARD16 <parameter>*suspend</parameter></paramdef>

+    <paramdef>CARD16 <parameter>*off</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist remap='IP'>

+  <varlistentry>

+    <term><emphasis remap='I'>display</emphasis></term>

+    <listitem><para>Specifies the connection to the X server.</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>standby</emphasis></term>

+    <listitem><para>Specifies the new standby timeout in seconds.</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>suspend</emphasis></term>

+    <listitem><para>Specifies the new suspend timeout in seconds.</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>off</emphasis></term>

+    <listitem><para>Specifies the new off timeout in seconds.</para></listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+The DPMSGetTimeouts function retrieves the timeout values used by the X

+server for DPMS timings.

+</para>

+

+<para>

+The value <emphasis remap='I'>standby</emphasis> is the amount of time of

+inactivity in seconds before standby mode is invoked. A value of zero

+indicates that this mode has been disabled.

+</para>

+

+<para>

+The value <emphasis remap='I'>suspend</emphasis> is the amount of time of

+inactivity in seconds before the second level of power savings is invoked.

+A value of zero indicates that this mode has been disabled.

+</para>

+

+<para>

+The value <emphasis remap='I'>off</emphasis> is the amount of time of

+inactivity in seconds before the third and final level of power savings is

+invoked. A value of zero indicates that this mode has been disabled.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>DPMSEnable</function></funcdef>

+    <paramdef>Display <parameter>*display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist remap='IP'>

+  <varlistentry>

+    <term><emphasis remap='I'>display</emphasis></term>

+    <listitem><para>Specifies the connection to the X server.</para></listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+The DPMSEnable function enables DPMS on the specified display.  When

+enabled, DPMS will use the currently saved timeout values, and will

+invoke the DPMS power mode appropriate for the amount of time that

+the workstation input devices have been idle.  If DPMSEnable is invoked

+on a display with DPMS already enabled, no change is made, and no

+error is returned.  If DPMSEnable is invoked on a display without

+support for DPMS, no change is made and no error is returned.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>DPMSDisable</function></funcdef>

+    <paramdef>Display <parameter>*display</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist remap='IP'>

+  <varlistentry>

+    <term><emphasis remap='I'>display</emphasis></term>

+    <listitem><para>Specifies the connection to the X server.</para></listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+The DPMSDisable function disables DPMS on the specified display.  When

+disabled, DPMS returns the display to DPMSModeOn.  If DPMSDisable is

+invoked on a display with DPMS already disabled, no change is made,

+and no error is returned.  If DPMSDisable is invoked on a display

+without support for DPMS, no change is made and no error is returned.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>DPMSForceLevel</function></funcdef>

+    <paramdef>Display <parameter>*display</parameter></paramdef>

+    <paramdef>CARD16 <parameter>level</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist remap='IP'>

+  <varlistentry>

+    <term><emphasis remap='I'>display</emphasis></term>

+    <listitem><para>Specifies the connection to the X server.</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>level</emphasis></term>

+    <listitem><para>Specifies the level to force power to.</para></listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+The DPMSForceLevel function forces a DPMS capable display into the

+specified power level.  The <emphasis remap='I'>level</emphasis> must be one of

+DPMSModeOn, DPMSModeStandby, DPMSModeSuspend, or DPMSModeOff.

+Values other than these will result in a BadValue error.  If DPMS

+is disabled on the display, a BadMatch protocol error will result.

+</para>

+

+<para>Status DPMSInfo(<emphasis remap='I'>display, power_level, state</emphasis>)</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>DPMSInfo</function></funcdef>

+    <paramdef>Display <parameter>*display</parameter></paramdef>

+    <paramdef>CARD16 <parameter>power_level</parameter></paramdef>

+    <paramdef>BOOL <parameter>*state</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<variablelist remap='IP'>

+  <varlistentry>

+    <term><emphasis remap='I'>display</emphasis></term>

+    <listitem><para>Specifies the connection to the X server.</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>power_level</emphasis></term>

+    <listitem><para>Specifies the current power level.</para></listitem>

+  </varlistentry>

+  <varlistentry>

+    <term><emphasis remap='I'>state</emphasis></term>

+    <listitem><para>Specifies the current DPMS state.</para></listitem>

+  </varlistentry>

+</variablelist>

+

+<para>

+The DPMSInfo function returns information about the current DPMS state.

+The <emphasis remap='I'>state</emphasis> return parameter indicates whether

+or not DPMS is enabled (TRUE) or disabled (FALSE).  The

+<emphasis remap='I'>power_level</emphasis> return parameter indicates the

+current power level (one of DPMSModeOn, DPMSModeStandby, DPMSModeSuspend,

+or DPMSModeOff.)

+</para>

+

+</chapter>

+</book>

diff --git a/libXext/specs/shapelib.xml b/libXext/specs/shapelib.xml
new file mode 100644
index 000000000..a059cf2a6
--- /dev/null
+++ b/libXext/specs/shapelib.xml
@@ -0,0 +1,581 @@
+<?xml version="1.0" encoding="UTF-8" ?>

+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

+

+<!-- lifted from troff+ms+XMan by doclifter -->

+<book id="shapelib">

+

+<bookinfo>

+   <title>X Nonrectangular Window Shape Extension Library</title>

+   <subtitle>X Consortium Standard</subtitle>

+   <releaseinfo>X Version 11, Release 6.4</releaseinfo>

+   <authorgroup>

+      <author>

+         <firstname>Keith</firstname><surname>Packard</surname>

+      </author>

+   </authorgroup>

+   <corpname>MIT X Consortium</corpname>

+   <copyright><year>1989</year><holder>X Consortium</holder></copyright>

+   <releaseinfo>Version 1.0</releaseinfo>

+   <affiliation><orgname>MIT X Consortium</orgname></affiliation>

+   <productnumber>X Version 11, Release 6.4</productnumber>

+

+<legalnotice>

+

+<para>

+Permission is hereby granted, free of charge, to any person obtaining a copy

+of this software and associated documentation files

+(the &ldquo;Software&rdquo;), 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 is furnished to do so, subject to

+the following conditions:

+</para>

+

+<para>

+The above copyright notice and this permission notice shall be included in

+all copies or substantial portions of the Software.

+</para>

+

+<para>

+THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, 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 THE X CONSORTIUM 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.

+</para>

+

+<para>

+Except as contained in this notice, the name of the X Consortium shall not be

+used in advertising or otherwise to promote the sale, use or other dealings

+in this Software without prior written authorization from the X Consortium.

+</para>

+</legalnotice>

+</bookinfo>

+

+<chapter id='overview'>

+<title>Overview</title>

+

+<para>This extension provides arbitrary window and border shapes within

+the X11 protocol.

+</para>

+

+<para>

+The restriction of rectangular windows within the X protocol is a significant

+limitation in the implementation of many styles of user interface.  For

+example, many transient windows would like to display a

+&ldquo;drop shadow&rdquo; to give the illusion of 3 dimensions.  As

+another example, some user interface style guides call for buttons with

+rounded corners; the full simulation of a nonrectangular shape,

+particularly with respect to event distribution and cursor shape, is not

+possible within the core X protocol.  As a final example, round clocks

+and nonrectangular icons are desirable visual addition to the desktop.

+</para>

+

+<para>

+This extension provides mechanisms for changing the visible shape of a

+window to an arbitrary, possibly disjoint, nonrectangular form.  The intent

+of the extension is to supplement the existing semantics, not replace them.

+In particular, it is desirable for clients that are unaware of the

+extension to still be able to cope reasonably with shaped windows.  For

+example, window managers should still be able to negotiate screen

+real estate in rectangular pieces.  Toward this end, any shape specified for

+a window is clipped by the bounding rectangle for the window as specified by

+the window's geometry in the core protocol.  An expected convention would be

+that client programs expand their shape to fill the area offered by the

+window manager.

+</para>

+</chapter>

+

+<chapter id='description'>

+<title>Description</title>

+

+<para>

+Each window (even with no shapes specified) is defined by two regions:  the

+<emphasis remap='I'>bounding region</emphasis> and the

+<emphasis remap='I'>clip region</emphasis>.  The bounding region is the

+area of the parent window that the window will occupy (including border).

+The clip region is the subset of the bounding region that is available for

+subwindows and graphics.  The area between the bounding region and the

+clip region is defined to be the border of the window.

+</para>

+

+<para>

+A nonshaped window will have a bounding region that is a rectangle spanning

+the window, including its border; the clip region will be a rectangle

+filling the inside dimensions (not including the border).  In this document,

+these areas are referred to as the

+<emphasis remap='I'>default bounding region</emphasis> and the

+<emphasis remap='I'>default clip region</emphasis>.  For a window with

+inside size of <emphasis remap='I'>width</emphasis> by

+<emphasis remap='I'>height</emphasis> and border width

+<emphasis remap='I'>bwidth</emphasis>, the default bounding and clip

+regions are the rectangles (relative to the window origin):

+</para>

+

+<literallayout remap='Ds'>

+bounding.x = -<emphasis remap='I'>bwidth</emphasis>

+bounding.y = -<emphasis remap='I'>bwidth</emphasis>

+bounding.width = <emphasis remap='I'>width</emphasis> + 2 * <emphasis remap='I'>bwidth</emphasis>

+bounding.height = <emphasis remap='I'>height</emphasis> + 2 * <emphasis remap='I'>bwidth</emphasis>

+

+clip.x = 0

+clip.y = 0

+clip.width = <emphasis remap='I'>width</emphasis>

+clip.height = <emphasis remap='I'>height</emphasis>

+</literallayout>

+

+<para>

+This extension allows a client to modify either or both of the bounding or

+clip regions by specifying new regions that combine with the default

+regions.  These new regions are called the

+<emphasis remap='I'>client bounding region</emphasis> and the

+<emphasis remap='I'>client clip region</emphasis>.  They are specified

+relative to the origin of the window and are always defined by offsets

+relative to the window origin (that is, region adjustments are not

+required when the window is moved).  Three mechanisms for specifying

+regions are provided:  a list of rectangles, a bitmap, and an existing

+bounding or clip region from a window.  This is modeled on the specification

+of regions in graphics contexts in the core protocol and allows a variety

+of different uses of the extension.

+</para>

+

+<para>

+When using an existing window shape as an operand in specifying a new shape,

+the client region is used, unless none has been set, in which case the

+default region is used instead.

+</para>

+

+<para>

+The <emphasis remap='I'>effective bounding region</emphasis> of a window is

+defined to be the intersection of the client bounding region with the default

+bounding region.  Any portion of the client bounding region that is not

+included in the default bounding region will not be included in the

+effective bounding region on the screen.  This means that window managers

+(or other geometry managers) used to dealing with rectangular client windows

+will be able to constrain the client to a rectangular area of the screen.

+</para>

+

+<para>

+Construction of the effective bounding region is dynamic; the client bounding

+region is not mutated to obtain the effective bounding region.  If a client

+bounding region is specified that extends beyond the current default bounding

+region, and the window is later enlarged, the effective bounding region will

+be enlarged to include more of the client bounding region.

+</para>

+

+<para>

+The <emphasis remap='I'>effective clip region</emphasis> of a window is

+defined to be the intersection of the client clip region with both the

+default clip region and the client bounding region.  Any portion of the

+client clip region that is not included in both the default clip region

+and the client bounding region will not be included in the effective clip

+region on the screen.

+</para>

+

+<para>

+Construction of the effective clip region is dynamic; the client clip region is

+not mutated to obtain the effective clip region.  If a client clip region is

+specified that extends beyond the current default clip region and the

+window or its bounding region is later enlarged, the effective clip region will

+be enlarged to include more of the client clip region if it is included in

+the effective bounding region.

+</para>

+

+<para>

+The border of a window is defined to be the difference between the effective

+bounding region and the effective clip region.  If this region is empty, no

+border is displayed.  If this region is nonempty, the border is filled

+using the border-tile or border-pixel of the window as specified in the core

+protocol.  Note that a window with a nonzero border width will never be able

+to draw beyond the default clip region of the window.  Also note that a zero

+border width does not prevent a window from having a border, since the clip

+shape can still be made smaller than the bounding shape.

+</para>

+

+<para>

+All output to the window and visible regions of any subwindows will be

+clipped to the effective clip region.  The server must not retain window

+contents beyond the effective bounding region with backing store.  The window's

+origin (for graphics operations, background tiling, and subwindow placement)

+is not affected by the existence of a bounding region or clip region.

+</para>

+

+<para>

+Areas that are inside the default bounding region but outside the effective

+bounding region are not part of the window; these areas of the screen will

+be occupied by other windows.  Input events that occur within the default

+bounding region but outside the effective bounding region will be delivered as

+if the window was not occluding the event position.  Events that occur in

+a nonrectangular border of a window will be delivered to that window, just

+as for events that occur in a normal rectangular border.

+</para>

+

+<para>An

+<function>InputOnly</function>

+window can have its bounding region set, but it is a

+<function>Match</function>

+error to attempt to set a clip region on an

+<function>InputOnly</function>

+window or to specify its clip region as a source to a request

+in this extension.

+</para>

+

+<para>

+The server must accept changes to the clip region of a root window, but

+the server is permitted to ignore requested changes to the bounding region

+of a root window.  If the server accepts bounding region changes, the contents

+of the screen outside the bounding region are implementation dependent.

+</para>

+</chapter>

+

+<chapter id='c_language_binding'>

+<title>C Language Binding</title>

+

+<para>

+The C functions provide direct access to the protocol and add no additional

+semantics.

+</para>

+

+<para>The include file for this extension is

+&lt;<symbol role='Pn'>X11/extensions/shape.h</symbol>&gt;.

+The defined shape kinds are

+<function>ShapeBounding</function>

+and

+<function>ShapeClip</function>

+The defined region operations are

+<function>ShapeSet</function>

+<function>ShapeUnion</function>

+<function>ShapeIntersect</function>

+<function>ShapeSubtract</function>

+and

+<function>ShapeInvert</function>.</para>

+

+<funcsynopsis>

+<funcprototype>

+<funcdef>Bool<function> XShapeQueryExtension</function></funcdef>

+<paramdef>Display <parameter>*display</parameter></paramdef>

+<paramdef>int <parameter>*event_base</parameter></paramdef>

+<paramdef>int <parameter>*error_base</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XShapeQueryExtension</function>

+returns

+<function>True</function>

+if the specified display supports the SHAPE extension else

+<function>False</function>

+If the extension is supported, *event_base is set to the event number for

+<function>ShapeNotify</function>

+events and *error_base would be set to the error number for the first error for

+this extension.  Because no errors are defined for this version of

+the extension, the value returned here is not defined (nor useful).

+</para>

+

+<funcsynopsis>

+<funcprototype>

+<funcdef>Status<function> XShapeQueryVersion</function></funcdef>

+<paramdef>Display<parameter> *display</parameter></paramdef>

+<paramdef>int<parameter> *major_version</parameter></paramdef>

+<paramdef>int<parameter> *minor_version</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+If the extension is supported,

+<function>XShapeQueryVersion</function>

+sets the major and minor version numbers of the

+extension supported by the display and returns a nonzero value.

+Otherwise, the arguments are not set and zero is returned.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+<funcdef><function>XShapeCombineRegion</function></funcdef>

+<paramdef>Display<parameter> *display</parameter></paramdef>

+<paramdef>Window<parameter> dest</parameter></paramdef>

+<paramdef>int<parameter> dest_kind</parameter></paramdef>

+<paramdef>int<parameter> x_off</parameter></paramdef>

+<paramdef>int<parameter> y_off</parameter></paramdef>

+<paramdef>int<parameter> region</parameter></paramdef>

+<paramdef>int<parameter> op</parameter></paramdef>

+<paramdef>REGION<parameter> *region</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XShapeCombineRegion</function>

+converts the specified region into a list of rectangles and calls

+<function>XShapeCombineRectangles</function>

+</para>

+

+<funcsynopsis>

+<funcprototype>

+<funcdef><function>XShapeCombineRectangles</function></funcdef>

+<paramdef>Display<parameter> *display</parameter></paramdef>

+<paramdef>Window<parameter> dest</parameter></paramdef>

+<paramdef>int<parameter> dest_kind</parameter></paramdef>

+<paramdef>int<parameter> x_off</parameter></paramdef>

+<paramdef>int<parameter> y_off</parameter></paramdef>

+<paramdef>XRectangle<parameter> *rectangles</parameter></paramdef>

+<paramdef>int<parameter> n_rects</parameter></paramdef>

+<paramdef>int<parameter> op</parameter></paramdef>

+<paramdef>int<parameter> ordering</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+If the extension is supported,

+<function>XShapeCombineRectangles</function>

+performs a

+<function>ShapeRectangles</function>

+operation; otherwise, the request is ignored.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+<funcdef><function>XShapeCombineMask</function></funcdef>

+<paramdef>Display<parameter> *display</parameter></paramdef>

+<paramdef>int<parameter> dest</parameter></paramdef>

+<paramdef>int<parameter> dest_kind</parameter></paramdef>

+<paramdef>int<parameter> x_off</parameter></paramdef>

+<paramdef>int<parameter> y_off</parameter></paramdef>

+<paramdef>Pixmap<parameter> src</parameter></paramdef>

+<paramdef>int<parameter> op</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+If the extension is supported,

+<function>XShapeCombineMask</function>

+performs a

+<function>ShapeMask</function>

+operation; otherwise, the request is ignored.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+<funcdef><function>XShapeCombineShape</function></funcdef>

+<paramdef>Display<parameter> *display</parameter></paramdef>

+<paramdef>Window<parameter> dest</parameter></paramdef>

+<paramdef>int<parameter> dest_kind</parameter></paramdef>

+<paramdef>int<parameter> x_off</parameter></paramdef>

+<paramdef>int<parameter> y_off</parameter></paramdef>

+<paramdef>Window<parameter> src</parameter></paramdef>

+<paramdef>int<parameter> src_kind</parameter></paramdef>

+<paramdef>int<parameter> op</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+If the extension is supported,

+<function>XShapeCombineShape</function>

+performs a

+<function>ShapeCombine</function>

+operation; otherwise, the request is ignored.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+<funcdef><function>XShapeOffsetShape</function></funcdef>

+<paramdef><parameter>display</parameter></paramdef>

+<paramdef><parameter>dest</parameter></paramdef>

+<paramdef><parameter>dest_kind</parameter></paramdef>

+<paramdef><parameter>x_off</parameter></paramdef>

+<paramdef><parameter>y_off</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+If the extension is supported,

+<function>XShapeOffsetShape</function>

+performs a

+<function>ShapeOffset</function>

+operation; otherwise, the request is ignored.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+<funcdef>Status <function>XShapeQueryExtents</function></funcdef>

+<paramdef>Display<parameter> *display</parameter></paramdef>

+<paramdef>Window<parameter> window</parameter></paramdef>

+<paramdef>Bool<parameter> *bounding_shaped</parameter></paramdef>

+<paramdef>int<parameter> *x_bounding</parameter></paramdef>

+<paramdef>int<parameter> *y_bounding</parameter></paramdef>

+<paramdef>unsigned int<parameter> *w_bounding</parameter></paramdef>

+<paramdef>unsigned int<parameter> *h_bounding</parameter></paramdef>

+<paramdef>Bool<parameter> *clip_shaped</parameter></paramdef>

+<paramdef>int<parameter> *x_clip</parameter></paramdef>

+<paramdef>int<parameter> *y_clip</parameter></paramdef>

+<paramdef>unsigned int<parameter> *w_clip</parameter></paramdef>

+<paramdef>unsigned int<parameter> *h_clip</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+If the extension is supported,

+<function>XShapeQueryExtents</function>

+sets x_bounding, y_bounding, w_bounding, h_bounding to the extents of the

+bounding shape and sets x_clip, y_clip, w_clip, h_clip to the extents of

+the clip shape.  For unspecified client regions, the extents of the

+corresponding default region are used.

+</para>

+

+<para>

+If the extension is supported, a nonzero value is returned; otherwise,

+zero is returned.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+<funcdef><function>XShapeSelectInput</function></funcdef>

+<paramdef>Display<parameter> *display</parameter></paramdef>

+<paramdef>Window<parameter> window</parameter></paramdef>

+<paramdef>unsigned long<parameter> mask</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+To make this extension more compatible with other interfaces, although

+only one event type can be selected via the extension,

+<function>XShapeSelectInput</function>

+provides a general mechanism similar to the standard Xlib binding for

+window events.  A mask value has been defined,

+<function>ShapeNotifyMask</function>

+that is the only valid bit in mask that may be specified.

+The structure for this event is defined as follows:

+</para>

+

+<literallayout remap='Ds'>

+typedef struct {

+    int type;     /* of event */

+    unsigned long serial;     /* # of last request processed by server */

+    Bool send_event;     /* true if this came frome a SendEvent request */

+    Display *display;     /* Display the event was read from */

+    Window window;     /* window of event */

+    int kind;     /* ShapeBounding or ShapeClip */

+    int x, y;     /* extents of new region */

+    unsigned width, height;

+    Time time;     /* server timestamp when region changed */

+    Bool shaped;     /* true if the region exists */

+} XShapeEvent;

+</literallayout>

+

+<funcsynopsis>

+<funcprototype>

+<funcdef>unsigned long <function>XShapeInputSelected</function></funcdef>

+<paramdef>Display<parameter> *display</parameter></paramdef>

+<paramdef>Window<parameter> window</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XShapeInputSelected</function>

+returns the current input mask for extension events on the specified

+window; the value returned if

+<function>ShapeNotify</function>

+is selected for is

+<function>ShapeNotifyMask</function>

+otherwise, it returns zero.

+If the extension is not supported, it returns zero.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+<funcdef>XRectangle<function> *XShapeGetRectangles</function></funcdef>

+<paramdef>Display<parameter> *display</parameter></paramdef>

+<paramdef>Window<parameter> window</parameter></paramdef>

+<paramdef>int<parameter> kind</parameter></paramdef>

+<paramdef>int<parameter> *count</parameter></paramdef>

+<paramdef>int<parameter> *ordering</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+If the extension is not supported,

+<function>XShapeGetRectangles</function>

+returns NULL.  Otherwise, it returns a list of rectangles that describe the

+region specified by kind.

+</para>

+</chapter>

+

+<glossary id='glossary'>

+

+<glossdiv>

+<title>Glossary</title>

+<glossentry id='bounding_region'>

+  <glossterm>bounding region</glossterm>

+  <glossdef><para>The area of the parent window that this window will occupy.

+This area is divided into two parts:  the border and the interior.</para>

+  </glossdef>

+</glossentry>

+

+<glossentry id='clip_region'>

+  <glossterm>clip region</glossterm>

+  <glossdef><para>The interior of the window, as a subset of the bounding

+region.  This region describes the area that will be painted with the

+window background when the window is cleared, will contain all graphics

+output to the window, and will clip any subwindows.</para></glossdef>

+</glossentry>

+

+<glossentry id='default_bounding_region'>

+  <glossterm>default bounding region</glossterm>

+  <glossdef><para>The rectangular area, as described by the core protocol

+window size, that covers the interior of the window and its border.</para>

+  </glossdef>

+</glossentry>

+

+<glossentry id='default_clip_region'>

+  <glossterm>default clip region</glossterm>

+  <glossdef><para>The rectangular area, as described by the core protocol

+window size, that covers the interior of the window and excludes the border.

+  </para></glossdef>

+</glossentry>

+

+<glossentry id='client_bounding_region'>

+  <glossterm>client bounding region</glossterm>

+  <glossdef><para>The region associated with a window that is directly

+modified via this extension when specified by

+<function>ShapeBounding</function>

+This region is used in conjunction with the default bounding region

+to produce the effective bounding region.</para></glossdef>

+</glossentry>

+

+<glossentry id='client_clip_region'>

+  <glossterm>client clip region</glossterm>

+  <glossdef><para>The region associated with a window that is directly

+modified via this extension when specified by

+<function>ShapeClip</function>

+This region is used in conjunction with the default clip region

+and the client bounding region to produce the effective clip region.</para>

+  </glossdef>

+</glossentry>

+

+<glossentry id='effective_bounding_region'>

+  <glossterm>effective bounding region</glossterm>

+  <glossdef><para>The actual shape of the window on the screen, including

+border and interior (but excluding the effects of overlapping windows).

+When a window has a client bounding region, the effective bounding region

+is the intersection of the default bounding region and the client bounding

+region.  Otherwise, the effective bounding region is the same as the

+default bounding region.</para>

+  </glossdef>

+</glossentry>

+

+<glossentry id='effective_clip_region'>

+  <glossterm>effective clip region</glossterm>

+  <glossdef><para>The actual shape of the interior of the window on the

+screen (excluding the effects of overlapping windows).  When a window

+has a client clip region or a client bounding region, the effective

+clip region is the intersection of the default clip region, the client

+clip region (if any) and the client bounding region (if any).  Otherwise,

+the effective clip region is the same as the default clip region.</para>

+  </glossdef>

+</glossentry>

+

+</glossdiv>

+</glossary>

+</book>

diff --git a/libXext/specs/synclib.tex b/libXext/specs/synclib.tex
new file mode 100644
index 000000000..a8e573006
--- /dev/null
+++ b/libXext/specs/synclib.tex
@@ -0,0 +1,773 @@
+% $Xorg: synclib.tex,v 1.3 2000/08/17 19:42:37 cpqbld Exp $

+% $XdotOrg: xc/doc/specs/Xext/synclib.tex,v 1.2 2004/04/23 18:42:18 eich Exp $

+%

+% Copyright 1991 by Olivetti Research Limited, Cambridge, England and

+% Digital Equipment Corporation, Maynard, Massachusetts.

+%

+%                        All Rights Reserved

+%

+% Permission to use, copy, modify, and distribute this software and its 

+% documentation for any purpose and without fee is hereby granted, 

+% provided that the above copyright notice appear in all copies and that

+% both that copyright notice and this permission notice appear in 

+% supporting documentation, and that the names of Digital or Olivetti

+% not be used in advertising or publicity pertaining to distribution of the

+% software without specific, written prior permission.  

+%

+% DIGITAL AND OLIVETTI DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,

+% INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT

+% SHALL THEY BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR

+% ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER

+% IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT

+% OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

+

+%\documentstyle[a4]{article}

+\documentstyle{article}

+

+\setlength{\parindent}{0 pt}

+\setlength{\parskip}{6pt}

+

+% Protocol Section

+% For the DP book, these four should be assigned the font for global symbols.

+

+\newcommand{\request}[1]{{\bf #1}}

+\newcommand{\event}[1]{{\bf #1}}

+\newcommand{\error}[1]{{\bf #1}}

+\newcommand{\enum}[1]{{\bf #1}}

+

+% The following fonts are not reassigned for the DP book.

+

+\newcommand{\system}[1]{{\sc #1}}

+\newcommand{\param}[1]{{\it #1}}

+

+\newcommand{\eventdef}[1]{\item {\bf#1}}

+\newcommand{\requestdef}[1]{\item {\bf#1}}

+\newcommand{\errordef}[1]{\item {\bf#1}}

+

+\newcommand{\defn}[1]{{\bf #1}}

+

+\newcommand{\tabstopsA}{\hspace*{4cm}\=\hspace*{1cm}\=\hspace*{7cm}\=\kill}

+\newcommand{\tabstopsB}{\hspace*{1cm}\=\hspace*{1cm}\=\hspace*{3cm}\=\kill}

+\newcommand{\tabstopsC}{\hspace*{1cm}\=\hspace*{1cm}\=\hspace*{5cm}\=\kill}

+

+% commands for formatting the API

+% For the DP book, these three should be assigned the font for global symbols.

+

+\newcommand{\cfunctionname}[1]{\mbox{\tt#1}}

+\newcommand{\ctypename}[1]{\mbox{\tt#1}}

+\newcommand{\cconst}[1]{\mbox{\tt#1}}

+

+% For the DP book, within function definitions, the type and name are in

+% the ordinary font; therefore, ctypenamedef and cfunctionnamedef are used

+% and defined below.

+\newcommand{\ctypenamedef}[1]{\mbox{#1}}

+\newcommand{\cfunctionnamedef}[1]{\mbox{#1}}

+\newcommand{\cargname}[1]{\mbox{\it#1}}

+\newcommand{\cstartfunction}[2]{\begin{sloppypar}\begin{samepage}\ctypenamedef{#1}\\ \cfunctionnamedef{#2}\ (}

+\newcommand{\cargdecl}[2]{\penalty -1\ctypenamedef{#1} \cargname{#2}}

+\newcommand{\cendfunctiondecl}{){\hangafter=2 \hangindent=20pt \raggedright\par}}

+\newcommand{\cendfuncdescription}{\end{samepage}\end{sloppypar}}

+

+\newcommand{\cstartmacro}[2]{\begin{sloppypar}\begin{samepage}\ctypenamedef{#1}\\ \cfunctionnamedef{#2}\ (}

+\newcommand{\cendmacrodecl}{)\par}

+\newcommand{\cendmacrodescription}{\end{samepage}\end{sloppypar}}

+

+% make things easier with all the long names

+\spaceskip .3333em plus 5em

+\tolerance=2000

+

+\begin{document}

+

+\begin{center}

+

+{\large X Synchronization Extension Library}\\[10pt]

+{\large Version 3.0}\\[15pt]

+{\large X Consortium Standard}\\[15pt]

+{\large X Version 11, Release 6.8}\\[15pt]

+{\it Tim Glauert}\\[0pt]

+{\tt thg@cam-orl.co.uk}\\[0pt]

+{\bf Olivetti Research / MultiWorks}\\[5pt]

+{\it Dave Carver}\\[0pt]

+{\tt dcc@athena.mit.edu}\\[0pt]

+{\bf Digital Equipment Corporation,}\\[0pt]

+{\bf MIT / Project Athena}\\[5pt]

+{\it Jim Gettys}\\[0pt]

+{\tt jg@crl.dec.com}\\[0pt]

+{\bf Digital Equipment Corporation,}\\[0pt]

+{\bf Cambridge Research Laboratory}\\[5pt]

+{\it David P. Wiggins}\\[0pt]

+{\tt dpw@x.org}\\[0pt]

+{\bf X Consortium, Inc.}\\[0pt]

+

+\end {center}

+

+Copyright 1991 by Olivetti Research Limited, Cambridge, England and

+Digital Equipment Corporation, Maynard, Massachusetts.

+

+{\small Permission to use, copy, modify, and distribute this documentation

+for any purpose and without fee is hereby granted, provided that the above

+copyright notice appear in all copies. Olivetti, Digital, MIT, 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.}

+

+Copyright (c) 1991 X Consortium, Inc.

+

+{\small 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 is

+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 THE

+X CONSORTIUM 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 X Consortium shall not be

+used in advertising or otherwise to promote the sale, use or other dealings

+in this Software without prior written authorization from the X Consortium.}

+\eject

+

+\section{Synchronization Protocol}

+

+The core X protocol makes no guarantees about the relative order of execution

+of requests for different clients. This means that any synchronization between

+clients must be done at the client level in an operating system-dependent and

+network-dependent manner. Even if there was an accepted standard for such

+synchronization, the use of a network introduces unpredictable delays between

+the synchronization of the clients and the delivery of the resulting requests

+to the X server.

+

+The core X protocol also makes no guarantees about the time at which requests

+are executed, which means that all clients with real-time constraints must

+implement their timing on the host computer. Any such timings are subject to

+error introduced by delays within the operating system and network and are

+inefficient because of the need for round-trip requests that keep the client and

+server synchronized.

+

+The synchronization extension provides primitives that allow synchronization

+between clients to take place entirely within the X server. This removes any

+error introduced by the network and makes it possible to synchronize clients

+on different hosts running different operating systems. This is important for

+multimedia applications, where audio, video, and graphics data streams are

+being synchronized. The extension also provides internal timers within the X

+server to which client requests can be synchronized. This allows simple

+animation applications to be implemented without any round-trip requests and

+makes best use of buffering within the client, network, and server.

+

+\subsection{Description}

+

+The mechanism used by this extension for synchronization within the X server

+is to block the processing of requests from a client until a specific

+synchronization condition occurs. When the condition occurs, the client is

+released and processing of requests continues. Multiple clients may block on

+the same condition to give inter-client synchronization.  Alternatively, a

+single client may block on a condition such as an animation frame marker.

+

+The extension adds \defn{Counter} and \defn{Alarm} to the set of resources

+managed by the server. A counter has a 64-bit integer value that may be

+increased or decreased by client requests or by the server internally. A

+client can block by sending an \request{Await} request that waits until

+one of a set of synchronization conditions, called TRIGGERs, becomes TRUE.

+

+The \request{CreateCounter} request allows a client to create a

+\defn{Counter} that can be changed by explicit \request{SetCounter} and

+\request{ChangeCounter} requests. These can be used to implement

+synchronization between different clients.

+

+There are some counters, called \defn{System Counters}, that are changed by

+the server internally rather than by client requests. The effect of any change

+to a system counter is not visible until the server has finished processing the

+current request. In other words, system counters are apparently updated in the

+gaps between the execution of requests rather than during the actual execution

+of a request. The extension provides a system counter that advances with the

+server time as defined by the core protocol, and it may also provide counters

+that advance with the real-world time or that change each time the CRT

+screen is refreshed.  Other extensions may provide their own

+extension-specific system counters.

+

+The extension provides an \defn{Alarm} mechanism that allows clients to

+receive an event on a regular basis when a particular counter is changed.

+

+\section{C Language Binding}

+

+The C routines provide direct access to	the protocol and add

+no additional semantics.

+

+The include file for this extension is \verb|<X11/extensions/sync.h>|.

+

+Most of the names in the language binding are derived from the

+protocol names by prepending \cfunctionname{XSync} to the protocol name and changing

+the capitalization.

+

+\subsection{C Functions}

+

+Most of the following functions generate SYNC protocol requests.

+

+% start marker

+\cstartfunction{Status}{XSyncQueryExtension}

+\cargdecl{Display *}{dpy},

+\cargdecl{int *}{event\_base\_return},

+\cargdecl{int *}{error\_base\_return}

+\cendfunctiondecl

+% end marker

+

+If dpy supports the SYNC extension, \cfunctionname{XSyncQueryExtension}

+returns \cconst{True}, sets *event\_base\_return to the event number for the

+first SYNC event, and sets

+*error\_base\_return to the error number for the first SYNC

+error.  If dpy does not support the SYNC extension, it

+returns \cconst{False}.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{Status}{XSyncInitialize}

+\cargdecl{Display *}{dpy},

+\cargdecl{int *}{major\_version\_return},

+\cargdecl{int *}{minor\_version\_return}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncInitialize} sets *major\_version\_return and

+*minor\_version\_return to the major/minor SYNC protocol

+version supported by the server.  If the XSync library is compatible

+with the version returned by the server, this function returns \cconst{True}.

+If dpy does not support the SYNC 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 \cconst{False}.  The only

+XSync function that may be called before this function is

+\cfunctionname{XSyncQueryExtension}.  If a client violates this rule,

+the effects of all XSync calls that it makes are undefined.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{XSyncSystemCounter *}{XSyncListSystemCounters}

+\cargdecl{Display *}{dpy},

+\cargdecl{int *}{n\_counters\_return}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncListSystemCounters} returns a pointer to an

+array of system counters supported by the display and sets 

+*n\_counters\_return to the number of

+counters in the array.  The array should be freed with

+\cfunctionname{XSyncFreeSystemCounterList}.  If dpy does not

+support the SYNC extension,

+or if there was an error during communication with the

+server, or if the server does not support any system counters, this

+function returns NULL.

+

+\ctypename{XSyncSystemCounter} has the following fields:

+

+\begin{tabular}{lll}

+char * & name; & /* null-terminated name of system counter */\\

+XSyncCounter & counter; & /* counter id of this system counter */\\

+XSyncValue & resolution; & /* resolution of this system counter */\\

+\end{tabular}

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{void}{XSyncFreeSystemCounterList}

+\cargdecl{XSyncSystemCounter *}{list}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncFreeSystemCounterList} frees the memory associated 

+with the system counter list returned by \cfunctionname{XSyncListSystemCounters}.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{XSyncCounter}{XSyncCreateCounter}

+\cargdecl{Display *}{dpy}, 

+\cargdecl{XSyncValue}{initial\_value}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncCreateCounter} creates a counter on the dpy

+with the given initial\_value and returns the counter ID. 

+It returns \cconst{None} if dpy does not

+support the SYNC extension.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{Status}{XSyncSetCounter}

+\cargdecl{Display *}{dpy},

+\cargdecl{XSyncCounter}{counter},

+\cargdecl{XSyncValue}{value}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncSetCounter} sets counter to value.  

+It returns \cconst{False} if dpy does not support the SYNC extension;

+otherwise, it returns \cconst{True}.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{Status}{XSyncChangeCounter}

+\cargdecl{Display *}{dpy},

+\cargdecl{XSyncCounter}{counter},

+\cargdecl{XSyncValue}{value}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncChangeCounter} adds value to counter.

+It returns \cconst{False} if dpy does not support the SYNC extension;

+otherwise, it returns \cconst{True}.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{Status}{XSyncDestroyCounter}

+\cargdecl{Display *}{dpy}, 

+\cargdecl{XSyncCounter}{counter}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncDestroyCounter} destroys counter. 

+It returns \cconst{False} if dpy does not

+support the SYNC extension; otherwise, it returns \cconst{True}.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{Status}{XSyncQueryCounter}

+\cargdecl{Display *}{dpy},

+\cargdecl{XSyncCounter}{counter},

+\cargdecl{XSyncValue *}{value\_return}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncQueryCounter} sets *value\_return to the current value of

+counter.  It returns \cconst{False} if there was an error during

+communication with the server or if dpy does not support

+the SYNC extension; otherwise, it returns \cconst{True}.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{Status}{XSyncAwait}

+\cargdecl{Display *}{dpy},

+\cargdecl{XSyncWaitCondition *}{wait\_list},

+\cargdecl{int}{n\_conditions}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncAwait} awaits on the conditions in wait\_list.

+The n\_conditions is the number of wait conditions in

+wait\_list.  It returns \cconst{False} if dpy does not

+support the SYNC extension; otherwise, it returns \cconst{True}.

+The await is processed asynchronously by the server;

+this function always returns immediately

+after issuing the request.

+

+\ctypename{XSyncWaitCondition} has the following fields:

+

+\begin{tabular}{lll}

+XSyncCounter & trigger.counter; & /* counter to trigger on */ \\

+XSyncValueType & trigger.value\_type; & /* absolute/relative */ \\

+XSyncValue & trigger.wait\_value; & /* value to compare counter to */ \\

+XSyncTestType & trigger.test\_type;	& /* pos/neg comparison/transtion */ \\

+XSyncValue & event\_threshold; & /* send event if past threshold */ \\

+\end{tabular}

+

+\ctypename{XSyncValueType} can be either \cconst{XSyncAbsolute} or \cconst{XSyncRelative}.

+

+\ctypename{XSyncTestType} can be one of \cconst{XSyncPositiveTransition},

+\cconst{XSyncNegativeTransition}, \cconst{XSyncPositiveComparison}, or

+\cconst{XSyncNegativeComparison}.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{XSyncAlarm}{XSyncCreateAlarm}

+\cargdecl{Display *}{dpy},

+\cargdecl{unsigned long}{values\_mask},

+\cargdecl{XSyncAlarmAttributes *}{values}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncCreateAlarm} creates an alarm and returns the alarm ID.

+It returns \cconst{None} if the display does not support the SYNC extension. 

+The values\_mask and values specify the alarm attributes.

+

+\ctypename{XSyncAlarmAttributes} has the following fields.  The attribute\_mask

+column specifies the symbol that the caller should OR into

+values\_mask to indicate that the value for the corresponding

+attribute was actually supplied.  Default values are used for all

+attributes that do not have their attribute\_mask OR'ed into 

+values\_mask.

+See the protocol

+description for \request{CreateAlarm} for the defaults.

+

+\begin{tabular}{lll}

+type & field name & attribute\_mask \\

+XSyncCounter & trigger.counter; & \cconst{XSyncCACounter} \\

+XSyncValueType & trigger.value\_type; & \cconst{XSyncCAValueType} \\

+XSyncValue & trigger.wait\_value; & \cconst{XSyncCAValue} \\

+XSyncTestType & trigger.test\_type; & \cconst{XSyncCATestType} \\

+XSyncValue & delta;	& \cconst{XSyncCADelta} \\

+Bool & events; & \cconst{XSyncCAEvents} \\

+XSyncAlarmState & state; & client cannot set this \\

+\end{tabular}

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{Status}{XSyncDestroyAlarm}

+\cargdecl{Display *}{dpy},

+\cargdecl{XSyncAlarm}{alarm}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncDestroyAlarm} destroys alarm. 

+It returns \cconst{False} if dpy does not

+support the SYNC extension; otherwise, it returns \cconst{True}.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{Status}{XSyncQueryAlarm}

+\cargdecl{Display *}{dpy},

+\cargdecl{XSyncAlarm}{alarm},

+\cargdecl{XSyncAlarmAttributes *}{values\_return}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncQueryAlarm} sets *values\_return to the alarm's

+attributes.  It returns \cconst{False} if there was an error 

+during communication with the server or if dpy does not support 

+the SYNC extension; otherwise, it returns \cconst{True}.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{Status}{XSyncChangeAlarm}

+\cargdecl{Display *}{dpy},

+\cargdecl{XSyncAlarm}{alarm},

+\cargdecl{unsigned long}{values\_mask},

+\cargdecl{XSyncAlarmAttributes *}{values}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncChangeAlarm} changes alarm's attributes.

+The attributes to change are specified as in \cfunctionname{XSyncCreateAlarm}.

+It returns \cconst{False} if dpy does not support the SYNC extension; 

+otherwise, it returns \cconst{True}.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{Status}{XSyncSetPriority}

+\cargdecl{Display *}{dpy},

+\cargdecl{XID}{client\_resource\_id},

+\cargdecl{int}{priority}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncSetPriority} sets the priority of the client owning 

+client\_resource\_id to priority.  

+If client\_resource\_id is \cconst{None},

+it sets the caller's priority.  It returns \cconst{False} if dpy

+does not support the SYNC extension; otherwise, it returns \cconst{True}.

+\cendfuncdescription

+

+

+% start marker

+\cstartfunction{Status}{XSyncGetPriority}

+\cargdecl{Display *}{dpy},

+\cargdecl{XID}{client\_resource\_id},

+\cargdecl{int *}{return\_priority}

+\cendfunctiondecl

+% end marker

+

+\cfunctionname{XSyncGetPriority} sets *return\_priority to the priority

+of the client owning client\_resource\_id. 

+If client\_resource\_id is

+\cconst{None}, it sets *return\_priority to the caller's priority.

+It returns \cconst{False} if there was an error

+during communication with the server or if dpy does not

+support the SYNC extension; otherwise, it returns \cconst{True}.

+\cendfuncdescription

+

+\subsection{C Macros/Functions}

+

+The following procedures manipulate 64-bit values.  They are defined

+both as macros and as functions.  By default, the macro form is used.

+To use the function form, \#undef the macro name to uncover the

+function.

+

+

+% start marker

+\cstartmacro{void}{XSyncIntToValue}

+\cargdecl{XSyncValue}{*pv},

+\cargdecl{int}{i}

+\cendmacrodecl

+% end marker

+

+Converts i to an \ctypename{XSyncValue} and stores it in

+*pv.  Performs sign extension (*pv will have the

+same sign as i.)

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{void}{XSyncIntsToValue}

+\cargdecl{XSyncValue}{*pv},

+\cargdecl{unsigned int}{low},

+\cargdecl{int}{high}

+\cendmacrodecl

+% end marker

+

+Stores low in the low 32 bits of *pv and 

+high in the high 32 bits of *pv.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{Bool}{XSyncValueGreaterThan}

+\cargdecl{XSyncValue}{a},

+\cargdecl{XSyncValue}{b}

+\cendmacrodecl

+% end marker

+

+Returns \cconst{True} if a is greater than b,

+else returns \cconst{False}.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{Bool}{XSyncValueLessThan}

+\cargdecl{XSyncValue}{a},

+\cargdecl{XSyncValue}{b}

+\cendmacrodecl

+% end marker

+

+Returns \cconst{True} if a is less than b,

+else returns \cconst{False}.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{Bool}{XSyncValueGreaterOrEqual}

+\cargdecl{XSyncValue}{a},

+\cargdecl{XSyncValue}{b}

+\cendmacrodecl

+% end marker

+

+Returns \cconst{True} if a is greater than or equal to b,

+else returns \cconst{False}.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{Bool}{XSyncValueLessOrEqual}

+\cargdecl{XSyncValue}{a},

+\cargdecl{XSyncValue}{b}

+\cendmacrodecl

+% end marker

+

+Returns \cconst{True} if a is less than or equal to b.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{Bool}{XSyncValueEqual}

+\cargdecl{XSyncValue}{a},

+\cargdecl{XSyncValue}{b}

+\cendmacrodecl

+% end marker

+

+Returns \cconst{True} if a is equal to b,

+else returns \cconst{False}.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{Bool}{XSyncValueIsNegative}

+\cargdecl{XSyncValue}{v}

+\cendmacrodecl

+% end marker

+

+Returns \cconst{True} if v is negative, else returns

+\cconst{False}.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{Bool}{XSyncValueIsZero}

+\cargdecl{XSyncValue}{v}

+\cendmacrodecl

+% end marker

+

+Returns \cconst{True} if v is zero,

+else returns \cconst{False}.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{Bool}{XSyncValueIsPositive}

+\cargdecl{XSyncValue}{v}

+\cendmacrodecl

+% end marker

+

+Returns \cconst{True} if v is positive, else returns

+\cconst{False}.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{unsigned int}{XSyncValueLow32}

+\cargdecl{XSyncValue}{v}

+\cendmacrodecl

+% end marker

+

+Returns the low 32 bits of v.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{int}{XSyncValueHigh32}

+\cargdecl{XSyncValue}{v}

+\cendmacrodecl

+% end marker

+

+Returns the high 32 bits of v.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{void}{XSyncValueAdd}

+\cargdecl{XSyncValue *}{presult},

+\cargdecl{XSyncValue}{a},

+\cargdecl{XSyncValue}{b},

+\cargdecl{Bool *}{poverflow}

+\cendmacrodecl

+% end marker

+

+Adds a to b and stores the result in *presult.

+If the result could not fit in 64 bits, *poverflow is set to

+\cconst{True}, else it is set to \cconst{False}.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{void}{XSyncValueSubtract}

+\cargdecl{XSyncValue *}{presult},

+\cargdecl{XSyncValue}{a},

+\cargdecl{XSyncValue}{b},

+\cargdecl{Bool *}{poverflow}

+\cendmacrodecl

+% end marker

+

+Subtracts b from a and stores the result in

+*presult.

+If the result could not fit in 64 bits, overflow is set to

+\cconst{True}, else it is set to \cconst{False}.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{void}{XSyncMaxValue}

+\cargdecl{XSyncValue *}{pv}

+\cendmacrodecl

+% end marker

+

+Sets *pv to the maximum value expressible in 64 bits.

+\cendmacrodescription

+

+

+% start marker

+\cstartmacro{void}{XSyncMinValue}

+\cargdecl{XSyncValue *}{pv}

+\cendmacrodecl

+% end marker

+

+Sets *pv to the minimum value expressible in 64 bits.

+\cendmacrodescription

+

+\subsection{Events}

+

+Let \cargname{event\_base} be the value \cargname{event\_base\_return}

+as defined in the function \cfunctionname{XSyncQueryExtension}.

+

+An \ctypename{XSyncCounterNotifyEvent}'s type field has the value

+\cargname{event\_base} + \cconst{XSyncCounterNotify}.  The fields of

+this structure are:

+

+\begin{tabular}{lll}

+int & type;	& /* event base + \cconst{XSyncCounterNotify} */ \\

+unsigned long & serial; & /* number of last request processed by server */ \\

+Bool & send\_event;& /* true if this came from a SendEvent request */ \\

+Display * & display; & /* Display the event was read from */\\

+XSyncCounter & counter;	& /* counter involved in await */\\

+XSyncValue & wait\_value; & /* value being waited for */\\

+XSyncValue & counter\_value; & /* counter value when this event was sent */\\

+Time & time; & /* milliseconds */\\

+int & count; & /* how many more events to come */\\

+Bool & destroyed; & /* True if counter was destroyed */\\

+\end{tabular}

+

+An \ctypename{XSyncAlarmNotifyEvent}'s type field has the value

+\cargname{event\_base} + \cconst{XSyncAlarmNotify}.  The fields of this

+structure are:

+

+\begin{tabular}{lll}

+int & type;&	/* event base + \cconst{XSyncAlarmNotify} */\\

+unsigned long & serial;&/* number of last request processed by server */\\

+Bool & send\_event;& /* true if this came from a SendEvent request */\\

+Display * & display;&	/* Display the event was read from */\\

+XSyncAlarm & alarm;&	/* alarm that triggered */\\

+XSyncValue & counter\_value;&/* value that triggered the alarm */\\

+XSyncValue & alarm\_value;&	/* test  value of trigger in alarm */\\

+Time & time;&	/* milliseconds */\\

+XSyncAlarmState & state;&	/* new state of alarm */\\

+\end{tabular}

+

+\subsection{Errors}

+

+Let \cargname{error\_base} be the value \cargname{error\_base\_return}

+as defined in the function \cfunctionname{XSyncQueryExtension}.

+

+An \ctypename{XSyncAlarmError}'s error\_code field has the value

+\cargname{error\_base} + \cconst{XSyncBadAlarm}.  The fields of

+this structure are:

+

+\begin{tabular}{lll}

+int & type;	\\

+Display * & display;& /* Display the event was read from */\\

+XSyncAlarm &  alarm;& /* resource id */\\

+unsigned long & serial;& /* serial number of failed request */\\

+unsigned char & error\_code;&/* error base + XSyncBadAlarm */\\

+unsigned char & request\_code;&/* Major op-code of failed request */\\

+unsigned char & minor\_code;&/* Minor op-code of failed request */\\

+\end{tabular}

+

+An \ctypename{XSyncCounterError}'s error\_code field has the value

+\cargname{error\_base} + \cconst{XSyncBadCounter}.  The fields of

+this structure are:

+

+\begin{tabular}{lll}

+int &type;\\

+Display * & display;&	/* Display the event was read from */\\

+XSyncCounter & counter;&	/* resource id */\\

+unsigned long & serial;&	/* serial number of failed request */\\

+unsigned char & error\_code;&/* error base + XSyncBadCounter */\\

+unsigned char & request\_code;&/* Major op-code of failed request */\\

+unsigned char & minor\_code;& /* Minor op-code of failed request */\\

+\end{tabular}

+

+\end{document}

diff --git a/libXext/specs/synclib.xml b/libXext/specs/synclib.xml
new file mode 100644
index 000000000..938261fdd
--- /dev/null
+++ b/libXext/specs/synclib.xml
@@ -0,0 +1,804 @@
+<?xml version="1.0" encoding="UTF-8" ?>

+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

+

+

+<!-- lifted from troff+ms+XMan by doclifter -->

+<book id="recordlib">

+

+<bookinfo>

+   <title>X Synchronization Extension Library</title>

+   <subtitle>X Consortium Standard</subtitle>

+   <releaseinfo>X Version 11, Release 6.4</releaseinfo>

+   <authorgroup>

+      <author>

+        <firstname>Tim</firstname><surname>Glauert</surname>

+        <affiliation><orgname>Olivetti Research/MultiWorks</orgname></affiliation>

+      </author>

+      <othercredit>

+          <firstname>Dave</firstname>

+          <surname>Carver</surname>

+          <affiliation><orgname>Digital EquipmentCorporation, MIT/Project Athena</orgname></affiliation>

+      </othercredit>

+      <othercredit>

+        <firstname>Jim</firstname>

+        <surname>Gettys</surname>

+        <affiliation><orgname>Digital EquipmentCorporation, Cambridge Research Laboratory</orgname></affiliation>

+      </othercredit>

+      <othercredit>

+        <firstname>David</firstname>

+        <surname>Wiggins</surname>

+        <affiliation><orgname>X Consortium, Inc.</orgname></affiliation>

+      </othercredit>

+   </authorgroup>

+   <copyright><year>1991</year><holder>Olivetti Research Limited, Cambridge England and Digital Equipment Corporation, Maynard, Massachusetts</holder></copyright>

+   <copyright><year>1991</year><holder>X Consortium</holder></copyright>

+   <releaseinfo>Version 3.0</releaseinfo>

+   <affiliation><orgname>X Consortium</orgname></affiliation>

+   <productnumber>X Version 11, Release 6.4</productnumber>

+<legalnotice>

+

+<para>

+Permission to use, copy, modify, and distribute this documentation for any

+purpose and without fee is hereby granted, provided that the above

+copyright notice appear in all copies. Olivetti, Digital, MIT, 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.

+</para>

+

+<para>

+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 is furnished

+to do so, subject to the following conditions:

+</para>

+

+<para>

+The above copyright notice and this permission notice shall be included in

+all copies or substantial portions of the Software.

+</para>

+

+<para>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 THE X CONSORTIUM 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.

+</para>

+

+<para>

+Except as contained in this notice, the name of the X Consortium shall

+not be used in advertising or otherwise to promote the sale, use or other

+dealings in this Software without prior written authorization from the

+X Consortium.

+</para>

+

+</legalnotice>

+</bookinfo>

+

+<chapter id="synchronization_protocol">

+<title>Synchronization Protocol</title>

+

+<para>

+The core X protocol makes no guarantees about the relative order of

+execution of requests for different clients.  This means that any

+synchronization between clients must be done at the client level in an

+operating system-dependent and network-dependent manner. Even if there

+was an accepted standard for such synchronization, the use of a network

+introduces unpredictable delays between the synchronization of the clients and

+the delivery of the resulting requests to the X server.

+</para>

+<para>

+The core X protocol also makes no guarantees about the time at which

+requests are executed, which means that all clients with real-time constraints

+must implement their timing on the host computer. Any such timings are

+subject to error introduced by delays within the operating system and

+network and are inefficient because of the need for round-trip requests that

+keep the client and server synchronized.

+</para>

+<para>

+The synchronization extension provides primitives that allow synchronization

+between clients to take place entirely within the X server. This removes any

+error introduced by the network and makes it possible to synchronize clients

+on different hosts running different operating systems. This is important for

+multimedia applications, where audio, video, and graphics data streams are

+being synchronized. The extension also provides internal timers within the X

+server to which client requests can be synchronized. This allows simple

+animation applications to be implemented without any round-trip requests

+and makes best use of buffering within the client, network, and server.

+</para>

+

+<sect1 id="description">

+<title>Description</title>

+<para>

+The mechanism used by this extension for synchronization within the X server

+is to block the processing of requests from a client until a specific

+synchronization condition occurs. When the condition occurs, the client is

+released and processing of requests continues. Multiple clients may block on

+the same condition to give inter-client synchronization. Alternatively, a single

+client may block on a condition such as an animation frame marker.

+</para>

+<para>

+The extension adds <function>Counter</function> and

+<function>Alarm</function> to the set of resources managed by

+the server. A counter has a 64-bit integer value that may be increased or

+decreased by client requests or by the server internally. A client can

+block by sending an <function>Await</function> request that waits until

+one of a set of synchronization conditions, called TRIGGERs, becomes TRUE.

+</para>

+<para>

+The <function>CreateCounter</function> request allows a client to create

+a <function>Counter</function> that can be changed by explicit

+<function>SetCounter</function> and <function>ChangeCounter</function>

+requests. These can be used to implement synchronization between

+different clients.

+</para>

+<para>

+There are some counters, called <function>System Counters</function>,

+that are changed by the server internally rather than by client

+requests. The effect of any change to a system counter is not visible

+until the server has finished processing the current request. In other

+words, system counters are apparently updated in the gaps between the

+execution of requests rather than during the actual execution of a

+request. The extension provides a system counter that advances with the

+server time as defined by the core protocol, and it may also provide

+counters that advance with the real-world time or that change each

+time the CRT screen is refreshed. Other extensions may provide their own

+extension-specific system counters.

+</para>

+<para>

+The extension provides an <function>Alarm</function> mechanism that allows clients to receive an

+event on a regular basis when a particular counter is changed.

+</para>

+</sect1>

+</chapter>

+

+<chapter id="c_language_binding">

+<title>C Language Binding</title>

+

+<para>

+The C routines provide direct access to the protocol and add no additional

+semantics.

+</para>

+<para>

+The include file for this extension is &lt;X11/extensions/sync.h&gt;.

+Most of the names in the language binding are derived from the protocol

+names by prepending XSync to the protocol name and changing the

+capitalization.

+</para>

+

+<sect1 id="c_functions">

+<title>C Functions</title>

+

+<para>

+Most of the following functions generate SYNC protocol requests.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XSyncQueryExtension</function></funcdef>

+    <paramdef>Display <parameter> *dpy</parameter></paramdef>

+    <paramdef>int <parameter> *event_base_return</parameter></paramdef>

+    <paramdef>int <parameter> *error_base_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+If dpy supports the SYNC extension,

+<function>XSyncQueryExtension</function> returns True,

+sets *event_base_return to the event number for the first SYNC event, and

+sets *error_base_return to the error number for the first SYNC error. If dpy

+does not support the SYNC extension, it returns False.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XSyncInitialize</function></funcdef>

+    <paramdef>Display <parameter> *dpy</parameter></paramdef>

+    <paramdef>int <parameter> *major_version_return</parameter></paramdef>

+    <paramdef>int <parameter> *minor_version_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncInitialize</function> sets *major_version_return and

+*minor version return to the major/minor SYNC protocol version supported

+by the server. If the XSync library is compatible with the version

+returned by the server, this function returns <function>True</function>.

+If dpy does not support the SYNC 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 <function>False</function>.

+The only XSync function that may be called before this function is

+XSyncQueryExtension. If a client violates this rule, the effects of all XSync

+calls that it makes are undefined.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XSyncSystemCounter *<function>XSyncListSystemCounters</function></funcdef>

+    <paramdef>Display <parameter> *dpy</parameter></paramdef>

+    <paramdef>int <parameter> *n_counters_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncListSystemCounters</function> returns a pointer to an array

+of system counters supported by the display and sets *n_counters_return

+to the number of counters in the array.  The array should be freed with

+<function>XSyncFreeSystemCounterList</function>. If dpy does not support

+the SYNC extension, or if there was an error during communication with

+the server, or if the server does not support any system counters,

+this function returns NULL.

+</para>

+

+<para>

+XSyncSystemCounter has the following fields:

+</para>

+

+<literallayout remap='Ds'>

+char *              name;        /* null-terminated name of system counter */

+XSyncCounter        counter;     /* counter id of this system counter */

+XSyncValue          resolution;  /* resolution of this system counter */

+</literallayout>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function>XSyncFreeSystemCounterList</function></funcdef>

+    <paramdef>XSyncSystemCounter <parameter> *list</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncFreeSystemCounterList</function> frees the memory

+associated with the system counter list returned by

+<function>XSyncListSystemCounters</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XSyncCounter <function>XSyncCreateCounter</function></funcdef>

+    <paramdef>Display<parameter> *dpy</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> initial_value</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncCreateCounter</function> creates a counter on the dpy

+with the given initial value and returns the counter ID. It returns

+<function>None</function> if dpy does not support the SYNC extension.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XSyncSetCounter</function></funcdef>

+    <paramdef>Display<parameter> *dpy</parameter></paramdef>

+    <paramdef>XSyncCounter<parameter> counter</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> value</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+

+<para>

+<function>XSyncSetCounter</function> sets counter to value. It returns

+<function>False </function> if dpy does not

+support the SYNC extension; otherwise, it returns <function>True</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XSyncChangeCounter</function></funcdef>

+    <paramdef>Display<parameter> *dpy</parameter></paramdef>

+    <paramdef>XSyncCounter<parameter> counter</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> value</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncChangeCounter</function> adds value to counter. It returns

+<function>False</function> if dpy does not support the SYNC extension;

+otherwise, it returns

+<function>True</function>.

+</para>

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XSyncDestroyCounter</function></funcdef>

+    <paramdef>Display<parameter> *dpy</parameter></paramdef>

+    <paramdef>XSyncCounter<parameter> counter</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncDestroyCounter</function> destroys counter. It returns

+<function>False</function> if dpy does not support the SYNC extension;

+otherwise, it returns <function>True</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XSyncQueryCounter</function></funcdef>

+    <paramdef>Display<parameter> *dpy</parameter></paramdef>

+    <paramdef>XSyncCounter<parameter> counter</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> *value_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncQueryCounter</function> sets *value_return to the current

+value of counter. It returns <function>False</function> if there was an

+error during communication with the server or if dpy does not support the

+SYNC extension; otherwise, it returns <function>True</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XSyncAwait</function></funcdef>

+    <paramdef>Display<parameter> *dpy</parameter></paramdef>

+    <paramdef>XSyncWaitCondition<parameter> *wait_list</parameter></paramdef>

+    <paramdef>int<parameter> n_conditions</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncAwait</function> awaits on the conditions in wait_list.

+The n_conditions is the number of wait conditions in wait_list. It

+returns <function>False</function> if dpy does not support the SYNC

+extension; otherwise, it returns <function>True</function>. The await is

+processed asynchronously by the server; this function always returns

+immediately after issuing the request.

+</para>

+<para>

+XSyncWaitCondition has the following fields:

+</para>

+

+<literallayout remap='Ds'>

+XSyncCounter     trigger.counter;    /*counter to trigger on */

+XSyncValueType   trigger.value_type; /*absolute/relative */

+XSyncValue       trigger.wait_value; /*value to compare counter to */

+XSyncTestType    trigger.test_type;  /*pos/neg comparison/transtion */

+XSyncValue       event_threshold;    /*send event if past threshold */

+</literallayout>

+

+<para>

+<function>XSyncValueType</function> can be either

+<function>XSyncAbsolute</function> or <function>XSyncRelative</function>.

+</para>

+

+<para>

+<function>XSyncTestType</function> can be one of

+<function>XSyncPositiveTransition</function>,

+<function>XSyncNegativeTransition</function>,

+<function>XSyncPositiveComparison</function>, or

+<function>XSyncNegativeComparison</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>XSyncAlarm <function>XSyncCreateAlarm</function></funcdef>

+    <paramdef>Display<parameter> *dpy</parameter></paramdef>

+    <paramdef>unsigned long<parameter> values_mask</parameter></paramdef>

+    <paramdef>XSyncAlarmAttributes<parameter> *values`</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncCreateAlarm</function> creates an alarm and returns the

+alarm ID. It returns None if the display does not support the SYNC

+extension. The values_mask and values specify the alarm attributes.

+</para>

+

+<para>

+<function>XSyncAlarmAttributes</function> has the following fields. The

+attribute_mask column specifies the symbol that the caller should OR

+into values_mask to indicate that the value for the corresponding

+attribute was actually supplied. Default values are used for all

+attributes that do not have their attribute_mask OR’ed into values_mask.

+See the protocol description for <function>CreateAlarm</function> for the

+defaults.

+</para>

+

+<literallayout remap='Ds'>

+type                 field name           attribute_mask

+XSyncCounter       trigger.counter;     XSyncCACounter

+XSyncValueType     trigger.value_type;  XSyncCAValueType

+XSyncValue         trigger.wait_value;  XSyncCAValue

+XSyncTestType      trigger.test_type;   XSyncCATestType

+XSyncValue         delta;               XSyncCADelta

+Bool               events;              XSyncCAEvents

+XSyncAlarmState    state;               client cannot set this

+</literallayout>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XSyncDestroyAlarm</function></funcdef>

+    <paramdef>Display<parameter> *dpy</parameter></paramdef>

+    <paramdef>XSyncAlarm<parameter> alarm</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncDestroyAlarm</function> destroys alarm. It returns

+<function>False</function> if dpy does not support

+the SYNC extension; otherwise, it returns <function>True</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XSyncQueryAlarm</function></funcdef>

+    <paramdef>Display<parameter> *dpy</parameter></paramdef>

+    <paramdef>XSyncAlarm<parameter> alarm</parameter></paramdef>

+    <paramdef>XSyncAlarmAttributes<parameter> *values_return</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+

+<para>

+<function>XSyncQueryAlarm</function> sets *values_return to the alarm’s

+attributes. It returns <function>False</function> if there was an error

+during communication with the server or if dpy does not support the

+SYNC extension; otherwise, it returns <function>True</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XSyncChangeAlarm</function></funcdef>

+    <paramdef>Display<parameter> *dpy</parameter></paramdef>

+    <paramdef>XSyncAlarm<parameter> alarm</parameter></paramdef>

+    <paramdef>unsigned long<parameter> values_mask</parameter></paramdef>

+    <paramdef>XSyncAlarmAttributes<parameter> *values</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncChangeAlarm</function> changes alarm’s attributes. The

+attributes to change are specified as in

+<function>XSyncCreateAlarm</function>. It returns

+<function>False</function> if dpy does not support

+the SYNC extension; otherwise, it returns <function>True</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XSyncSetPriority</function></funcdef>

+    <paramdef>Display<parameter> *dpy</parameter></paramdef>

+    <paramdef>XID<parameter> client_resource_id</parameter></paramdef>

+    <paramdef>int<parameter> priority</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncSetPriority</function> sets the priority of the client

+owning client_resource_id to priority. If client_resource_id is None, it

+sets the caller’s priority. It returns

+<function>False</function> if dpy does not support the SYNC extension;

+otherwise, it returns <function>True</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Status <function>XSyncGetPriority</function></funcdef>

+    <paramdef>Display<parameter> *dpy</parameter></paramdef>

+    <paramdef>XID<parameter> client_resource_id</parameter></paramdef>

+    <paramdef>int<parameter> *return_priority</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+<function>XSyncGetPriority</function> sets *return_priority to the

+priority of the client owning client_resource_id. If client_resource_id

+is None, it sets *return_priority to the caller’s priority. It returns

+<function>False</function> if there was an error during communication

+with the server or if dpy does not support the SYNC extension; otherwise, it

+returns <function>True</function>.

+</para>

+

+</sect1>

+

+<sect1 id="c_macros_functions">

+<title>C Macros/Functions</title>

+

+<para>

+The following procedures manipulate 64-bit values. They are defined both as

+macros and as functions. By default, the macro form is used. To use the

+function form, #undef the macro name to uncover the function.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function>XSyncIntToValue</function></funcdef>

+    <paramdef>XSyncValue<parameter> *pv</parameter></paramdef>

+    <paramdef>int<parameter> i</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Converts i to an <function>XSyncValue</function> and stores it in *pv.

+Performs sign extension (*pv will have the same sign as i.)

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function>XSyncIntsToValue</function></funcdef>

+    <paramdef>XSyncValue<parameter> *pv</parameter></paramdef>

+    <paramdef>unsigned int<parameter> low</parameter></paramdef>

+    <paramdef>int<parameter> high</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Stores low in the low 32 bits of *pv and high in the high 32 bits of *pv.

+</para>

+

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function>XSyncValueGreaterThan</function></funcdef>

+    <paramdef>XSyncValue<parameter> a</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> b</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Returns <function>True</function> if a is greater than b, else returns

+<function>False</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function>XSyncValueLessThan</function></funcdef>

+    <paramdef>XSyncValue<parameter> a</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> b</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Returns <function>True</function> if a is less than b, else returns

+<function>False</function>.

+</para>

+

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function>XSyncValueGreaterOrEqual</function></funcdef>

+    <paramdef>XSyncValue<parameter> a</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> b</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Returns <function>True</function> if a is greater than or equal to b,

+else returns <function>False</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function>XSyncValueLessOrEqual</function></funcdef>

+    <paramdef>XSyncValue<parameter> a</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> b</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Returns <function>True</function> if a is less than or equal to b,

+else returns <function>False</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function>XSyncValueEqual</function></funcdef>

+    <paramdef>XSyncValue<parameter> a</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> b</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Returns <function>True</function> if a is equal to b,

+else returns <function>False</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function>XSyncValueIsNegative</function></funcdef>

+    <paramdef>XSyncValue<parameter> v</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Returns <function>True</function> if v is negative,

+else returns <function>False</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function>XSyncValueIsZero</function></funcdef>

+    <paramdef>XSyncValue<parameter> v</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Returns <function>True</function> if v is zero,

+else returns <function>False</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>Bool <function>XSyncValueIsPositive</function></funcdef>

+    <paramdef>XSyncValue<parameter> v</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Returns <function>True</function> if v is positive,

+else returns <function>False</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned int <function>XSyncValueLow32</function></funcdef>

+    <paramdef>XSyncValue<parameter> v</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Returns the low 32 bits of v.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>unsigned int <function>XSyncValueHigh32</function></funcdef>

+    <paramdef>XSyncValue<parameter> v</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Returns the high 32 bits of v.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function>XSyncValueAdd</function></funcdef>

+    <paramdef>XSyncValue<parameter> *presult</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> a</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> b</parameter></paramdef>

+    <paramdef>Bool<parameter> *poverflow</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Adds a to b and stores the result in *presult. If the result could not

+fit in 64 bits, *poverflow is set to <function>True</function>, else it is

+set to <function>False</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function>XSyncValueSubtract</function></funcdef>

+    <paramdef>XSyncValue<parameter> *presult</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> a</parameter></paramdef>

+    <paramdef>XSyncValue<parameter> b</parameter></paramdef>

+    <paramdef>Bool<parameter> *poverflow</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Subtracts b from a and stores the result in *presult. If the result could not

+fit in 64 bits, *poverflow is set to <function>True</function>, else it is

+set to <function>False</function>.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function>XSyncMaxValue</function></funcdef>

+    <paramdef>XSyncValue<parameter> *pv</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Sets *pv to the maximum value expressible in 64 bits.

+</para>

+

+<funcsynopsis>

+<funcprototype>

+  <funcdef>void <function>XSyncMinValue</function></funcdef>

+    <paramdef>XSyncValue<parameter> *pv</parameter></paramdef>

+</funcprototype>

+</funcsynopsis>

+

+<para>

+Sets *pv to the minimum value expressible in 64 bits.

+</para>

+

+</sect1>

+

+<sect1 id="events">

+<title>Events</title>

+

+<para>

+Let <emphasis remap='I'>event_base</emphasis> be the value event base return as defined in the function

+<function>XSyncQueryExtension</function>.

+</para>

+

+<para>

+An <function>XSyncCounterNotifyEvent</function>’s type field has the value

+event_base + <function>XSyncCounterNotify</function>. The fields of this

+structure are:

+</para>

+

+<literallayout remap='Ds'>

+int              type;          /* event base + XSyncCounterNotify */

+unsigned long    serial;        /* number of last request processed by server */

+Bool             send event;    /* true if this came from a SendEvent request */

+Display *        display;       /* Display the event was read from */

+XSyncCounter     counter;       /* counter involved in await */

+XSyncValue       wait_value;    /* value being waited for */

+XSyncValue       counter_value; /* counter value when this event was sent */

+Time             time;          /* milliseconds */

+int              count;         /* how many more events to come */

+Bool             destroyed;     /* True if counter was destroyed */

+</literallayout>

+

+<para>

+An <function>XSyncAlarmNotifyEvent</function>’s type field has the value

+event_base + <function>XSyncAlarmNotify</function>. The fields of

+this structure are:

+</para>

+

+<literallayout remap='Ds'>

+int             type;         /* event_base + XSyncAlarmNotify */

+unsigned long   serial;       /* number of last request processed by server */

+Bool            send_event;   /* true if this came from a SendEvent request */

+Display *       display;      /*Display the event was read from */

+XSyncAlarm      alarm;        /* alarm that triggered */

+XSyncValue      counter_value /* value that triggered the alarm */

+XSyncValue      alarm_value   /* test value of trigger in alarm */

+Time            time;         /* milliseconds */

+XSyncAlarmState state;        /* new state of alarm */

+</literallayout>

+

+</sect1>

+

+<sect1 id="errors">

+<title>Errors</title>

+<para>

+Let <emphasis remap='I'>error_base</emphasis> be the value

+<emphasis remap='I'>error_base_return</emphasis> as defined in the function

+<function>XSyncQueryExtension</function>.

+</para>

+

+<para>

+An <function>XSyncAlarmError</function>’s error_code field has

+<function>XSyncBadAlarm</function>. The fields of this structure are:

+</para>

+

+<literallayout remap='Ds'>

+int                type

+Display *          display;      /* Display the event was read from */

+XSyncCounter       counter;      /* resource id */

+unsigned long      serial;       /* serial number of failed request */

+unsigned char      error_code;   /* error_base + XSyncBadAlarm */

+unsigned char      request_code; /* Major op-code of failed request */

+unsigned char      minor_code;   /* Minor op-code of failed request */

+</literallayout>

+

+<para>

+An <function>XSyncCounterError</function>’s error code field has the value

+error_base + <function>XSyncBadCounter</function>. The fields of this

+structure are:

+</para>

+<literallayout remap='Ds'>

+int                type

+Display *          display;      /* Display the event was read from */

+XSyncCounter       counter;      /* resource id */

+unsigned long      serial;       /* serial number of failed request */

+unsigned char      error_code;   /* error_base + XSyncBadCounter */

+unsigned char      request_code; /* Major op-code of failed request */

+unsigned char      minor_code;   /* Minor op-code of failed request */

+</literallayout>

+

+</sect1>

+</chapter>

+</book>