summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
authorAlan Coopersmith <alan.coopersmith@sun.com>2007-04-23 17:36:41 -0700
committerAlan Coopersmith <alan.coopersmith@sun.com>2007-04-23 17:36:41 -0700
commit258736fa5371c31bcde7f76f1089f0721c7f2275 (patch)
tree212523e488beb332dd87b8248c4b02acb110bef4 /man
parentbb772fb6c515bcccbde0947ca9fad03b350ae012 (diff)
Add libXcomposite man page (converted from protocol specs)
Translate protocol specs + header into library/API documentation in Docbook/XML format Convert XML -> nroff/man at dist time so that only maintainers and developers building from git need xmlto installed.
Diffstat (limited to 'man')
-rw-r--r--man/.gitignore6
-rw-r--r--man/Makefile.am78
-rw-r--r--man/Xcomposite.xml393
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 &lt;X11/extensions/Xcomposite.h&gt;</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&apos;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>