From bfb19bed915a30b5542fe8fee4e91151f25ec3b9 Mon Sep 17 00:00:00 2001 From: marha Date: Fri, 9 Jul 2010 14:19:56 +0000 Subject: git update 9/7/2010 --- libXext/specs/Makefile.am | 64 ++++ libXext/specs/dbelib.tex | 621 ++++++++++++++++++++++++++++++++++ libXext/specs/dbelib.xml | 728 ++++++++++++++++++++++++++++++++++++++++ libXext/specs/dpmslib.xml | 419 +++++++++++++++++++++++ libXext/specs/shapelib.xml | 581 ++++++++++++++++++++++++++++++++ libXext/specs/synclib.tex | 773 +++++++++++++++++++++++++++++++++++++++++++ libXext/specs/synclib.xml | 804 +++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 3990 insertions(+) create mode 100644 libXext/specs/Makefile.am create mode 100644 libXext/specs/dbelib.tex create mode 100644 libXext/specs/dbelib.xml create mode 100644 libXext/specs/dpmslib.xml create mode 100644 libXext/specs/shapelib.xml create mode 100644 libXext/specs/synclib.tex create mode 100644 libXext/specs/synclib.xml (limited to 'libXext') 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||. 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 @@ + + + + + + + + + Double Buffer Extension Library + X Consortium Standard + + + + IanElliot + + + + DavideWiggins + + Hewlett-Packard Company + 1989X Consortium, Inc and Digital Equipment Corporation + 1992X Consortium, Inc and Intergraph Corporation + 1993X Consortium, Inc and Silicon Graphics, Inc. + 1994X Consortium, Inc and Hewlett-Packard Company + 1995X Consortium, Inc and Hewlett-Packard Company + Version 1.0 + X Consortium + X Version 11, Release 7 + + + +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. + + + + + + + +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. + + + + + +Goals + + +This extension should enable clients to: + + + + +Allocate and deallocate double-buffering for a window. + + + + +Draw to and read from the front and back buffers associated with a window. + + + + +Swap the front and back buffers associated with a window. + + + + +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). + + + + +Request that the front and back buffers associated with multiple +double-buffered windows be swapped simultaneously. + + + + + +In addition, the extension should: + + + + +Allow multiple clients to use double-buffering on the same window. + + + + +Support a range of implementation methods that can capitalize on +existing hardware features. + + + + +Add no new event types. + + + + +Be reasonably easy to integrate with a variety of direct graphics +hardware access (DGHA) architectures. + + + + + + + +Concepts + +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. + + +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. + + +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. +particular, here are some important characteristics: + + + + +Only one buffer per window can be visible at a time (the front buffer). + + + + +Both buffers associated with a window have the same visual type, depth, +width, height, and shape as the window. + + + + +Both buffers associated with a window are "visible" (or "obscured") in +the same way. When an Expose event is generated for a window, 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. + + + + +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. + + + + +It is an error (Window) to pass a BACKBUFFER in a core request that +expects a Window. + + + + +A BACKBUFFER will never be sent by core X in a reply, event, or +error where a Window is specified. + + + + +If core X11 backing-store and save-under applies to a double-buffered +window, it applies to both buffers equally. + + + + +If the core ClearArea request is executed on a double-buffered window, +the same area in both the front and back buffers is cleared. + + + + + +The effect of passing a window to a request that accepts a +DRAWABLE is +unchanged by this extension. The window and front buffer are synonomous +with each other. This includes obeying the GetImage +semantics and the +subwindow-mode semantics if a core graphics context is involved. Regardless +of whether the window was explicitly passed in a +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-naive screen dump clients will always get the front buffer. +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 +ClipByChildren. 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 IncludeInferiors drawing touched. + + + + +DBE adds no new events. DBE does not extend the semantics of any existing +events with the exception of adding a new DRAWABLE type called +BACKBUFFER. If events, replies, or errors that contain a DRAWABLE (for +example, GraphicsExpose) are generated in response to +a request, the +DRAWABLE returned will be the one specified in the request. + + +DBE advertises which visuals support double-buffering. + + +DBE does not include any timing or synchronization facilities. Applications +that need such facilities (for example, to maintain a constant frame rate) +should investigate the Synchronization Extension, an X Consortium standard. + + + +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 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 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 +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, +Expose 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. + + +If the Shape extension +ShapeRectangles, +ShapeMask, +ShapeCombine, or +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 = newshape − oldshape + + + +It is tiled with the window background in both buffers, and +Expose +events are generated for D. + + + + + +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: +DBEBeginIdiom and 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: + + + + + +DBEBeginIdiom request. + + + + +DBESwapBuffers request with XIDs for two windows, each of which uses +a swap action of Untouched. + + + + +Core X PolyFillRectangle request to the back buffer of one window. + + + + +Core X PolyFillRectangle request to the back buffer of the other +window. + + + + +DBEEndIdiom request. + + + + + +The DBEBeginIdiom and 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 DBESwapBuffers request. +For example, if a swap action of Copied is desired, +but only some of the planes should be copied, a core X +CopyArea request may be used instead of +DBESwapBuffers. If +DBESwapBuffers is included in an idiom, it should +immediately follow the +DBEBeginIdiom request. Also, when the +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 Untouched, and if a +PolyFillRectangle using a client clip +rectangle is done to the window’s back buffer after the +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 +DBEBeginIdiom request, the idiom +requests, and DBEEndIdiom request. Usage of these +functions will ensure best possible performance across a wide +variety of implementations. + + + + + + +C Language Binding + +All identifier The header for this extension is <X11/extensions/Xdbe.h>. +names provided by this header begin with Xdbe. + + + +Types + + +The type XdbeBackBuffer is a Drawable. + + + +The type XdbeSwapAction can be one of the constants +XdbeUndefined, +XdbeBackground, +XdbeUntouched, or +XdbeCopied. + + + + + +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 +Status will return nonzero for success and +zero for failure. + + + + + Status XdbeQueryExtension + Display *dpy + int *major_version_return + int *minor_version_return + + + + +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. + + + + + XdbeScreenVisualInfo *XdbeGetVisualInfo + Display *dpy + Drawable *screen_specifiers + int *num_screens + + + + + +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 +XdbeScreenVisualInfo +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. + + + + +The XdbeScreenVisualInfo structure has the following fields: + + +int count number of items in visinfo +XdbeVisualInfo* visinfo list of visuals and depths for this screen + + + +The XdbeVisualInfo structure has the following fields: + + + +VisualID visual one visual ID that supports double-buffering +int depth depth of visual in bits +int perflevel performance level of visual + + + + + + void XdbeFreeVisualInfo XdbeGetVisualInfo + XdbeScreenVisualInfo *visual_info + + + + +XdbeFreeVisualInfo frees the list of +XdbeScreenVisualInfo returned by +XdbeGetVisualInfo. + + + + + + XdbeBackBuffer XdbeAllocateBackBufferName + Display *dpy + Window *window + XdbeSwapAction swap_action + + + + + +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 XdbeSwapBuffers. The actual swap_action +used in calls to 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. + + + + + Status XdbeDeallocateBackBufferName + Display *dpy + XdbeBackBuffer buffer + + + + +XdbeDeallocateBackBufferName frees the specified +drawable ID, buffer, that was obtained via +XdbeAllocateBackBufferName. The buffer must be a valid +name for the back buffer of a window, or an +XdbeBadBuffer error results. + + + + + Status XdbeSwapBuffers + Display *dpy + XdbeSwapInfo *swap_info + int num_windows + + + + +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 XdbeSwapInfo structure has the following fields: + + + +Window swap_window window for which to swap buffers +XdbeSwapAction swap_action swap action to use for this swap window + + + + + Status XdbeBeginIdiom + Display *dpy + + + + +XdbeBeginIdiom marks the beginning of an idiom +sequence. See + + +for a complete discussion of idioms. + + + + + Status XdbeEndIdiom + Display *dpy + + + + +XdbeEndIdiom marks the end of an idiom sequence. + + + + + XdbeBackBufferAttributes *XdbeGetBackBufferAttributes + Display *dpy + XdbeBackBuffer buffer + + + + +XdbeGetBackBufferAttributes returns the attributes associated with +the specified buffer. + + +The XdbeBackBufferAttributes structure has the following fields: + + + +Window window window that buffer belongs to + + + +If buffer is not a valid XdbeBackBuffer, window is +set to None. + + +The returned XdbeBackBufferAttributes structure +can be freed with the Xlib function XFree. + + + + +Errors + +The XdbeBufferError structure has the following fields: + + +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 + XdbeBadBuffer +unsigned char request code Major op-code of failed request +unsigned char minor code Minor op-code of failed request + + + + + +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. + + + + +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." + + + 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 @@ + + + + + + + + X Display Power Management Signaling (DPMS) Extension + X Consortium Standard + X Version 11, Release 6.8 + + + RobLembree + + + Digital Equipment Corporation + 1996X Consortium + Version 1.0 + X Consortium + X Version 11, Release 6.8 + + + +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. + + + +X Window System is a trademark of The Open Group. + + + + + + +Overview + +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. + + + +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. + + + +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. + + + +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: + + + +DPMS Extension Power Levels + 0 DPMSModeOn In use + 1 DPMSModeStandby Blanked, low power + 2 DPMSModeSuspend Blanked, lower power + 3 DPMSModeOff Shut off, awaiting activity + + + + + +DPMS Functions + + + + + Bool DPMSQueryExtention + Display *display + int event_base + int error_base + + + + + + *display + Specifies the connection to the X server. + + + event_base + Specifies the return location for the assigned base event + + + error_base + Specifies the return location for the assigned base error + + + + +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 event_base and +error_base 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 +event_base and +error_base are undefined. + + + + + Status DPMSGetVersion + Display *display + int *major_version + int *minor_version + + + + + + display + Specifies the connection to the X server. + + + major_version + Specifies the return location for the extension major version. + + + minor_version + Specifies the return location for the extension minor version. + + + + + +The DPMSGetVersion function returns the version of the DPMS extension +implemented by the X server. The version is returned in +major_version and +minor_version. +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. + + + + + Bool DPMSCapable + Display *display + + + + + + display + Specifies the connection to the X server. + + + + + +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. + + + + + Status DPMSSetTimeouts + Display *display + CARD16 standby + CARD16 suspend + CARD16 off + + + + + + display + Specifies the connection to the X server. + + + standby + Specifies the new standby timeout in seconds. + + + suspend + Specifies the new suspend timeout in seconds. + + + off + Specifies the new off timeout in seconds. + + + + +The DPMSSetTimeouts function permits applications to set the timeout values +used by the X server for DPMS timings. + + + +The value standby 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. + + + +The value suspend 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. + + + +The value off 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. + + + +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. + + + + + Status DPMSGetTimeouts + Display *display + CARD16 *standby + CARD16 *suspend + CARD16 *off + + + + + + display + Specifies the connection to the X server. + + + standby + Specifies the new standby timeout in seconds. + + + suspend + Specifies the new suspend timeout in seconds. + + + off + Specifies the new off timeout in seconds. + + + + +The DPMSGetTimeouts function retrieves the timeout values used by the X +server for DPMS timings. + + + +The value standby 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. + + + +The value suspend 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. + + + +The value off 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. + + + + + Status DPMSEnable + Display *display + + + + + + display + Specifies the connection to the X server. + + + + +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. + + + + + Status DPMSDisable + Display *display + + + + + + display + Specifies the connection to the X server. + + + + +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. + + + + + Status DPMSForceLevel + Display *display + CARD16 level + + + + + + display + Specifies the connection to the X server. + + + level + Specifies the level to force power to. + + + + +The DPMSForceLevel function forces a DPMS capable display into the +specified power level. The level 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. + + +Status DPMSInfo(display, power_level, state) + + + + Status DPMSInfo + Display *display + CARD16 power_level + BOOL *state + + + + + + display + Specifies the connection to the X server. + + + power_level + Specifies the current power level. + + + state + Specifies the current DPMS state. + + + + +The DPMSInfo function returns information about the current DPMS state. +The state return parameter indicates whether +or not DPMS is enabled (TRUE) or disabled (FALSE). The +power_level return parameter indicates the +current power level (one of DPMSModeOn, DPMSModeStandby, DPMSModeSuspend, +or DPMSModeOff.) + + + + 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 @@ + + + + + + + + X Nonrectangular Window Shape Extension Library + X Consortium Standard + X Version 11, Release 6.4 + + + KeithPackard + + + MIT X Consortium + 1989X Consortium + Version 1.0 + MIT X Consortium + X Version 11, Release 6.4 + + + + +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. + + + + + +Overview + +This extension provides arbitrary window and border shapes within +the X11 protocol. + + + +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 +“drop shadow” 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. + + + +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. + + + + +Description + + +Each window (even with no shapes specified) is defined by two regions: the +bounding region and the +clip region. 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. + + + +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 +default bounding region and the +default clip region. For a window with +inside size of width by +height and border width +bwidth, the default bounding and clip +regions are the rectangles (relative to the window origin): + + + +bounding.x = -bwidth +bounding.y = -bwidth +bounding.width = width + 2 * bwidth +bounding.height = height + 2 * bwidth + +clip.x = 0 +clip.y = 0 +clip.width = width +clip.height = height + + + +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 +client bounding region and the +client clip region. 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. + + + +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. + + + +The effective bounding region 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. + + + +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. + + + +The effective clip region 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. + + + +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. + + + +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. + + + +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. + + + +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. + + +An +InputOnly +window can have its bounding region set, but it is a +Match +error to attempt to set a clip region on an +InputOnly +window or to specify its clip region as a source to a request +in this extension. + + + +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. + + + + +C Language Binding + + +The C functions provide direct access to the protocol and add no additional +semantics. + + +The include file for this extension is +<X11/extensions/shape.h>. +The defined shape kinds are +ShapeBounding +and +ShapeClip +The defined region operations are +ShapeSet +ShapeUnion +ShapeIntersect +ShapeSubtract +and +ShapeInvert. + + + +Bool XShapeQueryExtension +Display *display +int *event_base +int *error_base + + + + +XShapeQueryExtension +returns +True +if the specified display supports the SHAPE extension else +False +If the extension is supported, *event_base is set to the event number for +ShapeNotify +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). + + + + +Status XShapeQueryVersion +Display *display +int *major_version +int *minor_version + + + + +If the extension is supported, +XShapeQueryVersion +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. + + + + +XShapeCombineRegion +Display *display +Window dest +int dest_kind +int x_off +int y_off +int region +int op +REGION *region + + + + +XShapeCombineRegion +converts the specified region into a list of rectangles and calls +XShapeCombineRectangles + + + + +XShapeCombineRectangles +Display *display +Window dest +int dest_kind +int x_off +int y_off +XRectangle *rectangles +int n_rects +int op +int ordering + + + + +If the extension is supported, +XShapeCombineRectangles +performs a +ShapeRectangles +operation; otherwise, the request is ignored. + + + + +XShapeCombineMask +Display *display +int dest +int dest_kind +int x_off +int y_off +Pixmap src +int op + + + + +If the extension is supported, +XShapeCombineMask +performs a +ShapeMask +operation; otherwise, the request is ignored. + + + + +XShapeCombineShape +Display *display +Window dest +int dest_kind +int x_off +int y_off +Window src +int src_kind +int op + + + + +If the extension is supported, +XShapeCombineShape +performs a +ShapeCombine +operation; otherwise, the request is ignored. + + + + +XShapeOffsetShape +display +dest +dest_kind +x_off +y_off + + + + +If the extension is supported, +XShapeOffsetShape +performs a +ShapeOffset +operation; otherwise, the request is ignored. + + + + +Status XShapeQueryExtents +Display *display +Window window +Bool *bounding_shaped +int *x_bounding +int *y_bounding +unsigned int *w_bounding +unsigned int *h_bounding +Bool *clip_shaped +int *x_clip +int *y_clip +unsigned int *w_clip +unsigned int *h_clip + + + + +If the extension is supported, +XShapeQueryExtents +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. + + + +If the extension is supported, a nonzero value is returned; otherwise, +zero is returned. + + + + +XShapeSelectInput +Display *display +Window window +unsigned long mask + + + + +To make this extension more compatible with other interfaces, although +only one event type can be selected via the extension, +XShapeSelectInput +provides a general mechanism similar to the standard Xlib binding for +window events. A mask value has been defined, +ShapeNotifyMask +that is the only valid bit in mask that may be specified. +The structure for this event is defined as follows: + + + +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; + + + + +unsigned long XShapeInputSelected +Display *display +Window window + + + + +XShapeInputSelected +returns the current input mask for extension events on the specified +window; the value returned if +ShapeNotify +is selected for is +ShapeNotifyMask +otherwise, it returns zero. +If the extension is not supported, it returns zero. + + + + +XRectangle *XShapeGetRectangles +Display *display +Window window +int kind +int *count +int *ordering + + + + +If the extension is not supported, +XShapeGetRectangles +returns NULL. Otherwise, it returns a list of rectangles that describe the +region specified by kind. + + + + + + +Glossary + + bounding region + The area of the parent window that this window will occupy. +This area is divided into two parts: the border and the interior. + + + + + clip region + 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. + + + + default bounding region + The rectangular area, as described by the core protocol +window size, that covers the interior of the window and its border. + + + + + default clip region + The rectangular area, as described by the core protocol +window size, that covers the interior of the window and excludes the border. + + + + + client bounding region + The region associated with a window that is directly +modified via this extension when specified by +ShapeBounding +This region is used in conjunction with the default bounding region +to produce the effective bounding region. + + + + client clip region + The region associated with a window that is directly +modified via this extension when specified by +ShapeClip +This region is used in conjunction with the default clip region +and the client bounding region to produce the effective clip region. + + + + + effective bounding region + 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. + + + + + effective clip region + 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. + + + + + + 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||. + +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 @@ + + + + + + + + + X Synchronization Extension Library + X Consortium Standard + X Version 11, Release 6.4 + + + TimGlauert + Olivetti Research/MultiWorks + + + Dave + Carver + Digital EquipmentCorporation, MIT/Project Athena + + + Jim + Gettys + Digital EquipmentCorporation, Cambridge Research Laboratory + + + David + Wiggins + X Consortium, Inc. + + + 1991Olivetti Research Limited, Cambridge England and Digital Equipment Corporation, Maynard, Massachusetts + 1991X Consortium + Version 3.0 + X Consortium + X Version 11, Release 6.4 + + + +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. + + + +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. + + + + + + +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. + + + +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 Counter and +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 Await request that waits until +one of a set of synchronization conditions, called TRIGGERs, becomes TRUE. + + +The CreateCounter request allows a client to create +a Counter that can be changed by explicit +SetCounter and ChangeCounter +requests. These can be used to implement synchronization between +different clients. + + +There are some counters, called 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 Alarm mechanism that allows clients to receive an +event on a regular basis when a particular counter is changed. + + + + + +C Language Binding + + +The C routines provide direct access to the protocol and add no additional +semantics. + + +The include file for this extension is <X11/extensions/sync.h>. +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. + + + +C Functions + + +Most of the following functions generate SYNC protocol requests. + + + + + Status XSyncQueryExtension + Display *dpy + int *event_base_return + int *error_base_return + + + + +If dpy supports the SYNC extension, +XSyncQueryExtension 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. + + + + + Status XSyncInitialize + Display *dpy + int *major_version_return + int *minor_version_return + + + + +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 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 False. +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. + + + + + XSyncSystemCounter *XSyncListSystemCounters + Display *dpy + int *n_counters_return + + + + +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 +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. + + + +XSyncSystemCounter has the following fields: + + + +char * name; /* null-terminated name of system counter */ +XSyncCounter counter; /* counter id of this system counter */ +XSyncValue resolution; /* resolution of this system counter */ + + + + + void XSyncFreeSystemCounterList + XSyncSystemCounter *list + + + + +XSyncFreeSystemCounterList frees the memory +associated with the system counter list returned by +XSyncListSystemCounters. + + + + + XSyncCounter XSyncCreateCounter + Display *dpy + XSyncValue initial_value + + + + +XSyncCreateCounter creates a counter on the dpy +with the given initial value and returns the counter ID. It returns +None if dpy does not support the SYNC extension. + + + + + Status XSyncSetCounter + Display *dpy + XSyncCounter counter + XSyncValue value + + + + + +XSyncSetCounter sets counter to value. It returns +False if dpy does not +support the SYNC extension; otherwise, it returns True. + + + + + Status XSyncChangeCounter + Display *dpy + XSyncCounter counter + XSyncValue value + + + + +XSyncChangeCounter adds value to counter. It returns +False if dpy does not support the SYNC extension; +otherwise, it returns +True. + + + + Status XSyncDestroyCounter + Display *dpy + XSyncCounter counter + + + + +XSyncDestroyCounter destroys counter. It returns +False if dpy does not support the SYNC extension; +otherwise, it returns True. + + + + + Status XSyncQueryCounter + Display *dpy + XSyncCounter counter + XSyncValue *value_return + + + + +XSyncQueryCounter sets *value_return to the current +value of counter. It returns False if there was an +error during communication with the server or if dpy does not support the +SYNC extension; otherwise, it returns True. + + + + + Status XSyncAwait + Display *dpy + XSyncWaitCondition *wait_list + int n_conditions + + + + +XSyncAwait awaits on the conditions in wait_list. +The n_conditions is the number of wait conditions in wait_list. It +returns False if dpy does not support the SYNC +extension; otherwise, it returns True. The await is +processed asynchronously by the server; this function always returns +immediately after issuing the request. + + +XSyncWaitCondition has the following fields: + + + +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 */ + + + +XSyncValueType can be either +XSyncAbsolute or XSyncRelative. + + + +XSyncTestType can be one of +XSyncPositiveTransition, +XSyncNegativeTransition, +XSyncPositiveComparison, or +XSyncNegativeComparison. + + + + + XSyncAlarm XSyncCreateAlarm + Display *dpy + unsigned long values_mask + XSyncAlarmAttributes *values` + + + + +XSyncCreateAlarm 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. + + + +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 CreateAlarm for the +defaults. + + + +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 + + + + + Status XSyncDestroyAlarm + Display *dpy + XSyncAlarm alarm + + + + +XSyncDestroyAlarm destroys alarm. It returns +False if dpy does not support +the SYNC extension; otherwise, it returns True. + + + + + Status XSyncQueryAlarm + Display *dpy + XSyncAlarm alarm + XSyncAlarmAttributes *values_return + + + + + +XSyncQueryAlarm sets *values_return to the alarm’s +attributes. It returns False if there was an error +during communication with the server or if dpy does not support the +SYNC extension; otherwise, it returns True. + + + + + Status XSyncChangeAlarm + Display *dpy + XSyncAlarm alarm + unsigned long values_mask + XSyncAlarmAttributes *values + + + + +XSyncChangeAlarm changes alarm’s attributes. The +attributes to change are specified as in +XSyncCreateAlarm. It returns +False if dpy does not support +the SYNC extension; otherwise, it returns True. + + + + + Status XSyncSetPriority + Display *dpy + XID client_resource_id + int priority + + + + +XSyncSetPriority 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 +False if dpy does not support the SYNC extension; +otherwise, it returns True. + + + + + Status XSyncGetPriority + Display *dpy + XID client_resource_id + int *return_priority + + + + +XSyncGetPriority 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 +False if there was an error during communication +with the server or if dpy does not support the SYNC extension; otherwise, it +returns True. + + + + + +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. + + + + + void XSyncIntToValue + XSyncValue *pv + int i + + + + +Converts i to an XSyncValue and stores it in *pv. +Performs sign extension (*pv will have the same sign as i.) + + + + + void XSyncIntsToValue + XSyncValue *pv + unsigned int low + int high + + + + +Stores low in the low 32 bits of *pv and high in the high 32 bits of *pv. + + + + + + Bool XSyncValueGreaterThan + XSyncValue a + XSyncValue b + + + + +Returns True if a is greater than b, else returns +False. + + + + + Bool XSyncValueLessThan + XSyncValue a + XSyncValue b + + + + +Returns True if a is less than b, else returns +False. + + + + + + Bool XSyncValueGreaterOrEqual + XSyncValue a + XSyncValue b + + + + +Returns True if a is greater than or equal to b, +else returns False. + + + + + Bool XSyncValueLessOrEqual + XSyncValue a + XSyncValue b + + + + +Returns True if a is less than or equal to b, +else returns False. + + + + + Bool XSyncValueEqual + XSyncValue a + XSyncValue b + + + + +Returns True if a is equal to b, +else returns False. + + + + + Bool XSyncValueIsNegative + XSyncValue v + + + + +Returns True if v is negative, +else returns False. + + + + + Bool XSyncValueIsZero + XSyncValue v + + + + +Returns True if v is zero, +else returns False. + + + + + Bool XSyncValueIsPositive + XSyncValue v + + + + +Returns True if v is positive, +else returns False. + + + + + unsigned int XSyncValueLow32 + XSyncValue v + + + + +Returns the low 32 bits of v. + + + + + unsigned int XSyncValueHigh32 + XSyncValue v + + + + +Returns the high 32 bits of v. + + + + + void XSyncValueAdd + XSyncValue *presult + XSyncValue a + XSyncValue b + Bool *poverflow + + + + +Adds a to b and stores the result in *presult. If the result could not +fit in 64 bits, *poverflow is set to True, else it is +set to False. + + + + + void XSyncValueSubtract + XSyncValue *presult + XSyncValue a + XSyncValue b + Bool *poverflow + + + + +Subtracts b from a and stores the result in *presult. If the result could not +fit in 64 bits, *poverflow is set to True, else it is +set to False. + + + + + void XSyncMaxValue + XSyncValue *pv + + + + +Sets *pv to the maximum value expressible in 64 bits. + + + + + void XSyncMinValue + XSyncValue *pv + + + + +Sets *pv to the minimum value expressible in 64 bits. + + + + + +Events + + +Let event_base be the value event base return as defined in the function +XSyncQueryExtension. + + + +An XSyncCounterNotifyEvent’s type field has the value +event_base + XSyncCounterNotify. The fields of this +structure are: + + + +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 */ + + + +An XSyncAlarmNotifyEvent’s type field has the value +event_base + XSyncAlarmNotify. The fields of +this structure are: + + + +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 */ + + + + + +Errors + +Let error_base be the value +error_base_return as defined in the function +XSyncQueryExtension. + + + +An XSyncAlarmError’s error_code field has +XSyncBadAlarm. The fields of this structure are: + + + +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 */ + + + +An XSyncCounterError’s error code field has the value +error_base + XSyncBadCounter. The fields of this +structure are: + + +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 */ + + + + + -- cgit v1.2.3