From fe2ccbf887ddf31f99d6f630830e3180ff259e40 Mon Sep 17 00:00:00 2001 From: marha Date: Mon, 20 Dec 2010 09:39:54 +0000 Subject: xserver libXext git update 20-12-2010 --- libXext/specs/dbelib.tex | 620 ------------------------------------- libXext/specs/synclib.tex | 770 ---------------------------------------------- 2 files changed, 1390 deletions(-) delete mode 100644 libXext/specs/dbelib.tex delete mode 100644 libXext/specs/synclib.tex (limited to 'libXext/specs') diff --git a/libXext/specs/dbelib.tex b/libXext/specs/dbelib.tex deleted file mode 100644 index e9793bc32..000000000 --- a/libXext/specs/dbelib.tex +++ /dev/null @@ -1,620 +0,0 @@ -% 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||. 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/synclib.tex b/libXext/specs/synclib.tex deleted file mode 100644 index 0775eb9fd..000000000 --- a/libXext/specs/synclib.tex +++ /dev/null @@ -1,770 +0,0 @@ -% 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||. - -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} -- cgit v1.2.3