diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/.gitignore | 6 | ||||
| -rw-r--r-- | man/Makefile.am | 78 | ||||
| -rw-r--r-- | man/Xcomposite.xml | 393 |
3 files changed, 477 insertions, 0 deletions
diff --git a/man/.gitignore b/man/.gitignore new file mode 100644 index 0000000..2dcc75c --- /dev/null +++ b/man/.gitignore @@ -0,0 +1,6 @@ +shadows.DONE +*.3 +*~ +Xcomposite.man +Makefile +Makefile.in diff --git a/man/Makefile.am b/man/Makefile.am new file mode 100644 index 0000000..0cd6d0a --- /dev/null +++ b/man/Makefile.am @@ -0,0 +1,78 @@ +libmandir = $(LIB_MAN_DIR) + +LIB_MAN_DIR_SUFFIX = $(LIB_MAN_DIR:@mandir@/man%=%) + +libman_xml = Xcomposite.xml + +libman_PRE = $(libman_xml:xml=man) + +Xcomposite_man_aliases = \ + XCompositeQueryExtension \ + XCompositeQueryVersion \ + XCompositeVersion \ + XCompositeRedirectWindow \ + XCompositeRedirectSubwindows \ + XCompositeUnredirectWindow \ + XCompositeUnredirectSubwindows \ + XCompositeCreateRegionFromBorderClip \ + XCompositeNameWindowPixmap \ + XCompositeGetOverlayWindow \ + XCompositeReleaseOverlayWindow + +libman_DATA = $(libman_PRE:man=@LIB_MAN_SUFFIX@) \ + $(Xcomposite_man_aliases:=.@LIB_MAN_SUFFIX@) + +EXTRA_DIST = $(libman_PRE) $(libman_xml) + +CLEANFILES = $(libman_DATA) + +MAINTAINERCLEANFILES = $(libman_PRE) + +# Generate man page shadow files (Replaces InstallManPageAliases from Imake) + +BUILT_SOURCES = shadows.DONE + +shadows.DONE: + -rm -f $(Xcomposite_man_aliases:=.@LIB_MAN_SUFFIX@) + (for i in $(Xcomposite_man_aliases:=.@LIB_MAN_SUFFIX@) ; do \ + echo .so man$(LIB_MAN_DIR_SUFFIX)/Xcomposite.$(LIB_MAN_SUFFIX) > $$i; \ + done) + touch shadows.DONE + +CLEANFILES += shadows.DONE + +# Substitute system-specific values in man pages + +XORGRELSTRING = @PACKAGE_STRING@ + XORGMANNAME = X Version 11 + +MAN_SUBSTS = \ + -e 's|"__vendorversion__"|"$(XORGRELSTRING)" "$(XORGMANNAME)"|' \ + -e 's|__xorgversion__|"$(XORGRELSTRING)" "$(XORGMANNAME)"|' \ + -e 's|__xservername__|Xorg|g' \ + -e 's|__xconfigfile__|xorg.conf|g' \ + -e 's|__projectroot__|$(prefix)|g' \ + -e 's|__apploaddir__|$(appdefaultdir)|' \ + -e 's|__appmansuffix__|$(APP_MAN_SUFFIX)|g' \ + -e 's|__libmansuffix__|$(LIB_MAN_SUFFIX)|g' \ + -e 's|__adminmansuffix__|$(ADMIN_MAN_SUFFIX)|g' \ + -e 's|__miscmansuffix__|$(MISC_MAN_SUFFIX)|g' \ + -e 's|__filemansuffix__|$(FILE_MAN_SUFFIX)|g' + +SUFFIXES = .$(LIB_MAN_SUFFIX) .man + +.man.$(LIB_MAN_SUFFIX): + sed $(MAN_SUBSTS) < $< > $@ + +# Generate nroff sources from DocBook/xml + +dist-hook: $(libman_PRE) + +if HAVE_XMLTO +SUFFIXES += .xml + +.xml.man: + $(XMLTO) man $< && mv $*.__libmansuffix__ $@ + + +endif HAVE_XMLTO diff --git a/man/Xcomposite.xml b/man/Xcomposite.xml new file mode 100644 index 0000000..f849f6a --- /dev/null +++ b/man/Xcomposite.xml @@ -0,0 +1,393 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" > +<reference> +<!-- + Based on proto/compositeproto/compositeproto.txt + + Conversion to DocBook/XML API documentation is: + + Copyright 2007 Sun Microsystems, Inc. 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, and/or sell copies of the Software, and to permit persons + to whom the Software is furnished to do so, provided that the above + copyright notice(s) and this permission notice appear in all copies of + the Software and that both the above copyright notice(s) and this + permission notice appear in supporting documentation. + + 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 + OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR + HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR 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. + + Except as contained in this notice, the name of a copyright holder + shall not be used in advertising or otherwise to promote the sale, use + or other dealings in this Software without prior written authorization + of the copyright holder. + + --> +<title>X Composite Extension Library</title> + +<refentry id='Xcomposite.man'> + <refentryinfo> + <productname>__vendorversion__</productname> + <pubdate>23 April 2007</pubdate> + <authorgroup> + <author><firstname>Keith</firstname><surname>Packard</surname> + <contrib>Extension specification and implementation</contrib> + <email>keithp@keithp.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>Xcomposite</refentrytitle> + <manvolnum>__libmansuffix__</manvolnum> + </refmeta> + <refnamediv> + <refname>Xcomposite</refname> + <refpurpose>X Composite Extension library</refpurpose> + </refnamediv> + <refsynopsisdiv><funcsynopsis> + <funcsynopsisinfo>#include <X11/extensions/Xcomposite.h></funcsynopsisinfo> + <funcprototype> + <funcdef>Bool <function>XCompositeQueryExtension</function></funcdef> + <paramdef><type>Display *</type><parameter>dpy</parameter></paramdef> + <paramdef>int *<parameter>event_basep</parameter></paramdef> + <paramdef>int *<parameter>error_basep</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>Status <function>XCompositeQueryVersion</function></funcdef> + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>int *<parameter>major_versionp</parameter></paramdef> + <paramdef>int *<parameter>minor_versionp</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>XCompositeVersion</function></funcdef> + <void /> + </funcprototype> + <funcprototype> + <funcdef>void <function>XCompositeRedirectWindow</function></funcdef> + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + <paramdef>int <parameter>update</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>void <function>XCompositeRedirectSubwindows</function></funcdef> + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + <paramdef>int <parameter>update</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>void <function>XCompositeUnredirectWindow</function></funcdef> + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + <paramdef>int <parameter>update</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>void <function>XCompositeUnredirectSubwindows</function></funcdef> + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + <paramdef>int <parameter>update</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>XserverRegion <function>XCompositeCreateRegionFromBorderClip</function></funcdef> + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>Pixmap <function>XCompositeNameWindowPixmap</function></funcdef> + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>Window <function>XCompositeGetOverlayWindow</function></funcdef> + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>void <function>XCompositeReleaseOverlayWindow</function></funcdef> + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + </funcprototype> + </funcsynopsis></refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +The composite extension provides several related mechanisms: + <variablelist> + <varlistentry> + <term>Per-hierarchy storage</term> + <listitem><para> + The rendering of an entire hierarchy of windows + is redirected to off-screen storage. The pixels of that hierarchy + are available whenever it is viewable. Storage is automatically + reallocated when the top level window changes size. Contents beyond + the geometry of the top window are not preserved. + </para></listitem> + </varlistentry> + <varlistentry> + <term>Automatic shadow update</term> + <listitem><para> + When a hierarchy is rendered off-screen, + the X server provides an automatic mechanism for presenting those + contents within the parent window. The implementation is free to + make this update lag behind actual rendering operations by an + unspecified amount of time. This automatic update mechanism may + be disabled so that the parent window contents can be completely + determined by an external application. + </para></listitem> + </varlistentry> + <varlistentry> + <term>Composite Overlay Window</term> + <listitem><para> + Version 0.3 of the protocol adds the Composite Overlay Window, which + provides compositing managers with a surface on which to draw without + interference. This window is always above normal windows and is always + below the screen saver window. It is an InputOutput window whose width + and height are the screen dimensions. Its visual is the root visual + and its border width is zero. Attempts to redirect it using the + composite extension are ignored. This window does not appear in the + reply of the QueryTree request. It is also an override redirect window. + These last two features make it invisible to window managers and other + X11 clients. The only way to access the XID of this window is via the + CompositeGetOverlayWindow request. Initially, the Composite Overlay + Window is unmapped. + </para></listitem> + </varlistentry> + </variablelist> +</para> +<para> +Per-hierarchy storage may be created for individual windows or for all +children of a window. Manual shadow update may be selected by only a single +application for each window; manual update may also be selected on a +per-window basis or for each child of a window. Detecting when to update +may be done with the Damage extension. +</para> +<para> +The off-screen storage includes the window contents, its borders and the +contents of all descendants. +</para> +</refsect1> +<refsect1><title>Arguments</title> +<para> + <variablelist> + <varlistentry> + <term><parameter>display</parameter></term> + <listitem><para> + Pointer to the <type>Display</type> structure returned from + <function>XOpenDisplay</function> for the connection to the X server. + </para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>event_basep</parameter></term> + <listitem><para> + Pointer to integer where the base value for Composite Extension events + will be stored. + </para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>error_basep</parameter></term> + <listitem><para> + Pointer to integer where the base value for Composite Extension errors + will be stored. + </para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>major_versionp</parameter></term> + <listitem><para> + Pointer to integer where the major version of the Composite Extension + supported by the X server will be stored. + </para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>minor_versionp</parameter></term> + <listitem><para> + Pointer to integer where the minor version of the Composite Extension + supported by the X server will be stored. + </para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>window</parameter></term> + <listitem><para> + Specifies the window ID to operate on. + </para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>update</parameter></term> + <listitem><para> + Specifies the mode for updating the window contents. Must be either + <constant>CompositeRedirectAutomatic</constant> or + <constant>CompositeRedirectManual</constant>. + </para></listitem> + </varlistentry> + </variablelist> +</para></refsect1> +<refsect1><title>Functions</title> +<para> + <variablelist> + <varlistentry> + <term><function>XCompositeQueryExtension</function></term> + <listitem><para> + <function>XCompositeQueryExtension</function> determines if the + Composite Extension is available on the given display. It returns + <constant>True</constant> if the extension is supported, otherwise + <constant>False</constant>. If the extension is present, the base + values for events and errors are returned, and can be used to + decode incoming event and error values. + </para></listitem> + </varlistentry> + <varlistentry> + <term><function>XCompositeQueryVersion</function></term> + <listitem><para> + <function>XCompositeQueryVersion</function> determines if the X Server + supports a version of the X Composite Extension which is compatible + with the client library. A non-zero Status is returned if a compatible + version of the extension is supported, otherwise a zero Status is returned. + If the extension is supported, the major and minor version numbers are + returned to indicate the level of Composite Extension support. + No other XComposite functions (except XCompositeQueryExtension) may be + called before this function. If a client violates this rule, the + effects of all subsequent XComposite calls that it makes are undefined. + </para></listitem> + </varlistentry> + <varlistentry> + <term><function>XCompositeVersion</function></term> + <listitem><para> + <function>XCompositeVersion</function> returns the version of the + X Composite library. The version number is encoded as: + <blockquote><para><code language="C"> + (major * 10000) + (minor * 100) + revision + </code></para></blockquote> + </para> + <para> + For example, version 1.4.6 would be encoded as the integer 10406. + </para></listitem> + </varlistentry> + <varlistentry> + <term><function>XCompositeRedirectWindow</function></term> + <listitem><para> + <function>XCompositeRedirectWindow</function> requests the X server + to direct the hierarchy starting at <parameter>window</parameter> to + off-screen storage. + The <parameter>update</parameter> argument specifies whether + the contents are mirrored to the parent window automatically or not. + Only one client at a time may specify an update type of + <constant>CompositeRedirectManual</constant>, another attempt will + result in a <errorname>BadAccess</errorname> error. When all clients + enabling redirection terminate, the redirection will automatically be + disabled. + </para><para> + The root window may not be redirected. Doing so results in a + <errorname>BadMatch</errorname> error. Specifying an invalid + window id will result in a <errorname>BadWindow</errorname> error. + </para></listitem> + </varlistentry> + <varlistentry> + <term><function>XCompositeRedirectSubwindows</function></term> + <listitem><para> + <function>XCompositeRedirectSubwindows</function> requests the X + server to redirect hierarchies starting at all current and future + children of <parameter>window</parameter> as in + <function>XCompositeRedirectWindow</function>. + If <parameter>update</parameter> is + <constant>CompositeRedirectManual</constant>, then painting of the + window background during window manipulation and ClearArea requests + is inhibited. + </para></listitem> + </varlistentry> + <varlistentry> + <term><function>XCompositeUnredirectWindow</function></term> + <listitem><para> + <function>XCompositeUnredirectWindow</function> requests the X + server to terminate redirection of <parameter>window</parameter>. + If the specified window was not selected for redirection by the + current client, a <errorname>BadValue</errorname> error results. + </para></listitem> + </varlistentry> + <varlistentry> + <term><function>XCompositeUnredirectSubwindows</function></term> + <listitem><para> + <function>XCompositeUnredirectWindow</function> requests the X + server to terminate redirection of all children of + <parameter>window</parameter>. + If the specified window was not selected for sub-redirection by the + current client, a <errorname>BadValue</errorname> error results. + </para></listitem> + </varlistentry> + <varlistentry> + <term><function>XCompositeCreateRegionFromBorderClip</function></term> + <listitem><para> + <function>XCompositeCreateRegionFromBorderClip</function> + creates a region containing the "usual" border clip + value; that is the area of the window clipped against siblings and + the parent. This region can be used to restrict rendering to + suitable areas while updating only a single window. The region + is copied at the moment the request is executed; future changes + to the window hierarchy will not be reflected in this region. + </para></listitem> + </varlistentry> + <varlistentry> + <term><function>XCompositeNameWindowPixmap</function></term> + <listitem><para> + <function>XCompositeNameWindowPixmap</function> creates and returns + a pixmap id that serves as a reference to the off-screen storage for + <parameter>window</parameter>. This pixmap will remain allocated + until freed, even if the window is unmapped, reconfigured or + destroyed. However, the window will get a new pixmap allocated each + time it is mapped or resized, so this function will need to be + reinvoked for the client to continue to refer to the storage holding + the current window contents. Generates a + <errorname>BadMatch</errorname> error if <parameter>window</parameter> + is not redirected or is not visible. + </para><para> + The X server must support at least version 0.2 of the Composite + Extension for <function>XCompositeNameWindowPixmap</function>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><function>XCompositeGetOverlayWindow</function></term> + <listitem><para> + <function>XCompositeGetOverlayWindow</function> returns the window ID + of the Composite Overlay Window for + the screen specified by the argument <parameter>window</parameter>. + This function notifies the X server that the client wishes to use + the Composite Overlay Window of this screen. If this + Composite Overlay Window has not yet been mapped, it is mapped by this + request. + </para><para> + The Composite Overlay Window for a particular screen will be + unmapped when all clients who have called this function have + either called <function>XCompositeReleaseOverlayWindow</function> + for that screen, or terminated their connection to the X server. + </para><para> + The X server must support at least version 0.3 of the Composite + Extension for <function>XCompositeGetOverlayWindow</function>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><function>XCompositeReleaseOverlayWindow</function></term> + <listitem><para> + This request specifies that the client is no longer using the + Composite Overlay Window on the screen specified by the + argument <parameter>window</parameter>. A screen's Composite + Overlay Window is unmapped when there are no longer any clients using it. + </para><para> + The X server must support at least version 0.3 of the Composite + Extension for <function>XCompositeReleaseOverlayWindow</function>. + </para></listitem> + </varlistentry> + </variablelist> +</para> +</refsect1> +</refentry> +</reference> |