X11::Protocol::Ext::Composite(3) off-screen window contents


use X11::Protocol;
my $X = X11::Protocol->new;
or print "Composite extension not available";
$X->CompositeRedirectWindow ($mywindow, 'Automatic');


The Composite extension holds the full pixel contents of windows in off-screen storage, ready for things like "CopyArea()". Normally the server only keeps the visible parts of a window, not areas overlapped or obscured.

In ``Automatic'' mode the visible parts of a window are displayed on screen as normal. The off-screen storage is then a little like the backing store feature, but just when one or more clients declare an interest in the full content.

In ``Manual'' mode the window contents are not drawn on screen, only kept off-screen. This mode is for use by special ``composite manager'' programs which might make a composite display (hence the name of the extension) of the overlapping windows with partial-transparency or shadowing effects.

There's nothing here to draw or combine to actually make a composite window result. When required that's done with the usual core protocol drawing or with drawing extensions such as RENDER (see X11::Protocol::Ext::RENDER).


The following requests are made available with an "init_extension()", as per ``EXTENSIONS'' in X11::Protocol.

    my $is_available = $X->init_extension('Composite');

Composite 0.1

"($server_major, $server_minor) = $X->CompositeQueryVersion ($client_major, $client_minor)"
Negotiate a protocol version with the server. $client_major and $client_minor is what the client would like, the returned $server_major and $server_minor is what the server will do, which might be less than requested (but not more than).

Actually the X.org server circa 1.10 will return a higher minor version than the client requests.

The current code supports up to 0.3 and the intention is to automatically negotiate in "init_extension()" if/when necessary.

"$X->CompositeRedirectWindow ($window, $update)"
"$X->CompositeRedirectSubwindows ($window, $update)"
"$X->CompositeUnredirectWindow ($window, $update)"
"$X->CompositeUnredirectSubwindows ($window, $update)"
Enable or disable a redirect of $window to off-screen storage.

"Window()" acts on just the given $window. "Subwindows()" acts on $window and also any subwindows it has now or in the future. The root window cannot be redirected.

$update is string ``Automatic'' or ``Manual''. Only one client at a time may use Manual mode on a given $window (normally a ``composite manager'' program).

Redirection is a per-client setting and is automatically unredirected if the client disconnects. An unredirect when not redirected is a "BadValue" error. Off-screen storage remains in effect while at least one current client has requested it.

"$X->CompositeCreateRegionFromBorderClip ($region, $window)"
Create $region (a new XID) as a server-side region object initialized to, umm, something about $window and its current border or visible parts or whatnot.

Region objects are from XFIXES 2.0 (X11::Protocol::Ext::XFIXES). "CompositeCreateRegionFromBorderClip()" can be used without "init_extension()" of XFIXES, but there's not much which can be done with a region except through XFIXES.

Composite 0.2

"$X->CompositeNameWindowPixmap ($window, $pixmap)"
Set $pixmap (a new XID) to refer to the off-screen storage of $window. $window must be viewable (mapped and all of its parents mapped) and must be redirected (by any client).

    my $pixmap = $X->new_rsrc;
    $X->CompositeNameWindowPixmap ($window, $pixmap);

$pixmap is released with "FreePixmap()" in the usual way. If $window or a parent is unmapped then $pixmap continues to exist, but it's association with $window is lost. If $window is mapped and redirected again later then it has a new off-screen storage and a new "CompositeNameWindowPixmap()" must be called to get a new pixmap for it.

Composite 0.3

"$overlay_window = $X->CompositeGetOverlayWindow ($window)"
Return the composite overlay window for the screen of $window.

This window covers the whole screen and is always above ordinary windows but below any screen saver, and doesn't appear in a "QueryTree()". It's created when the first client asks for it, and shared by any further clients who ask.

"$X->CompositeReleaseOverlayWindow ($window)"
Release the composite overlay window for the screen of $window. When all clients release it the overlay window is destroyed.


Copyright 2011, 2012, 2013 Kevin Ryde

X11-Protocol-Other is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

X11-Protocol-Other is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with X11-Protocol-Other. If not, see <http://www.gnu.org/licenses/>.