402 lines
17 KiB
XML
402 lines
17 KiB
XML
<?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 (c) 2007, 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.
|
|
|
|
-->
|
|
<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>
|
|
<author><firstname>Deron</firstname><surname>Johnson</surname>
|
|
<contrib>Overlay Window specification and implementation</contrib>
|
|
<email>deron.johnson@sun.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_base_return</parameter></paramdef>
|
|
<paramdef>int *<parameter>error_base_return</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>Status <function>XCompositeQueryVersion</function></funcdef>
|
|
<paramdef>Display *<parameter>dpy</parameter></paramdef>
|
|
<paramdef>int *<parameter>major_version_return</parameter></paramdef>
|
|
<paramdef>int *<parameter>minor_version_return</parameter></paramdef>
|
|
</funcprototype>
|
|
<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>
|
|
<varlistentry>
|
|
<term>Parent window clipping</term>
|
|
<listitem><para>
|
|
Version 0.4 of the protocol modifies the semantics of parent window
|
|
clipping in the presence of manual redirected children. With this
|
|
version, the area in the parent covered by manual redirected
|
|
children is left in the parent clip list instead of being removed as
|
|
in older versions.
|
|
</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_base_return</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_base_return</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_version_return</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_version_return</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>
|