XCOMPOSITE(3) libXcomposite XCOMPOSITE(3)

NAME

Xcomposite - X Composite Extension library

SYNOPSIS

#include <X11/extensions/Xcomposite.h>

Bool XCompositeQueryExtension(Display *dpy, int *event_base_return,
int *error_base_return);

Status XCompositeQueryVersion(Display *dpy,
int *major_version_return,
int *minor_version_return);

int XCompositeVersion(void);

void XCompositeRedirectWindow(Display *dpy, Window window,
int update);

void XCompositeRedirectSubwindows(Display *dpy, Window window,
int update);

void XCompositeUnredirectWindow(Display *dpy, Window window,
int update);

void XCompositeUnredirectSubwindows(Display *dpy, Window window,
int update);

XserverRegion XCompositeCreateRegionFromBorderClip(Display *dpy,
Window window);

Pixmap XCompositeNameWindowPixmap(Display *dpy, Window window);

Window XCompositeGetOverlayWindow(Display *dpy, Window window);

void XCompositeReleaseOverlayWindow(Display *dpy, Window window);

DESCRIPTION

The composite extension provides several related mechanisms:

Per-hierarchy storage
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.

Automatic shadow update
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.

Composite Overlay Window
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.

Parent window clipping
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.

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.

The off-screen storage includes the window contents, its borders and
the contents of all descendants.

ARGUMENTS

display
Pointer to the Display structure returned from XOpenDisplay for
the connection to the X server.

event_base_return
Pointer to integer where the base value for Composite Extension
events will be stored.

error_base_return
Pointer to integer where the base value for Composite Extension
errors will be stored.

major_version_return
Pointer to integer where the major version of the Composite
Extension supported by the X server will be stored.

minor_version_return
Pointer to integer where the minor version of the Composite
Extension supported by the X server will be stored.

window
Specifies the window ID to operate on.

update
Specifies the mode for updating the window contents. Must be
either CompositeRedirectAutomatic or CompositeRedirectManual.

FUNCTIONS

XCompositeQueryExtension

XCompositeQueryExtension determines if the Composite Extension is
available on the given display. It returns True if the extension
is supported, otherwise False. 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.

XCompositeQueryVersion

XCompositeQueryVersion 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.

XCompositeVersion

XCompositeVersion returns the version of the X Composite library.
The version number is encoded as: (major * 10000) + (minor * 100)
+ revision

For example, version 1.4.6 would be encoded as the integer 10406.

XCompositeRedirectWindow

XCompositeRedirectWindow requests the X server to direct the
hierarchy starting at window to off-screen storage. The update
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 CompositeRedirectManual, another
attempt will result in a BadAccess error. When all clients
enabling redirection terminate, the redirection will
automatically be disabled.

The root window may not be redirected. Doing so results in a
BadMatch error. Specifying an invalid window id will result in a
BadWindow error.

XCompositeRedirectSubwindows

XCompositeRedirectSubwindows requests the X server to redirect
hierarchies starting at all current and future children of window
as in XCompositeRedirectWindow. If update is
CompositeRedirectManual, then painting of the window background
during window manipulation and ClearArea requests is inhibited.

XCompositeUnredirectWindow

XCompositeUnredirectWindow requests the X server to terminate
redirection of window. If the specified window was not selected
for redirection by the current client, a BadValue error results.

XCompositeUnredirectSubwindows

XCompositeUnredirectWindow requests the X server to terminate
redirection of all children of window. If the specified window
was not selected for sub-redirection by the current client, a
BadValue error results.

XCompositeCreateRegionFromBorderClip

XCompositeCreateRegionFromBorderClip 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.

XCompositeNameWindowPixmap

XCompositeNameWindowPixmap creates and returns a pixmap id that
serves as a reference to the off-screen storage for window. 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 BadMatch error if window is not redirected or is not
visible.

The X server must support at least version 0.2 of the Composite
Extension for XCompositeNameWindowPixmap.

XCompositeGetOverlayWindow

XCompositeGetOverlayWindow returns the window ID of the Composite
Overlay Window for the screen specified by the argument window.
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.

The Composite Overlay Window for a particular screen will be
unmapped when all clients who have called this function have
either called XCompositeReleaseOverlayWindow for that screen, or
terminated their connection to the X server.

The X server must support at least version 0.3 of the Composite
Extension for XCompositeGetOverlayWindow.

XCompositeReleaseOverlayWindow
This request specifies that the client is no longer using the
Composite Overlay Window on the screen specified by the argument
window. A screen's Composite Overlay Window is unmapped when
there are no longer any clients using it.

The X server must support at least version 0.3 of the Composite
Extension for XCompositeReleaseOverlayWindow.

AUTHORS

Keith Packard <keithp@keithp.com>
Extension specification and implementation

Deron Johnson <deron.johnson@sun.com>
Overlay Window specification and implementation

<pubdate>23 April 2007</pubdate> XCOMPOSITE(3)