X11::P...mposite(3pm)

📦
version 31 · 7 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 X11::P...mposite — the Perl manual page, but make it a group chat 💖

okay bestie so you found the X11::P...mposite(3pm) page — that's the X11::Protocol::Ext::Composite module from User Contributed Perl Documentation, and it's giving off-screen window contents energy. let's get into it 🫶

✨ NAME ✨

X11::Protocol::Ext::Composite — off-screen window contents. that's it, that's the whole vibe 💅

🌸 SYNOPSIS 🌸

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

$X->CompositeRedirectWindow ($mywindow, 'Automatic');

literally just load it up, check the extension actually showed up, and go ✨

🦋 DESCRIPTION 🦋

so here's the tea, bestie: the Composite extension keeps the full pixel contents of windows in off-screen storage, just sitting there ready for stuff like CopyArea(). normally the server is lowkey stingy and only keeps the visible parts of a window — not the areas that are overlapped or obscured. rude honestly 😭

in "Automatic" mode, the visible parts of a window get displayed on screen like normal, no drama. the off-screen storage is then kinda like the backing store feature, except it only kicks in when one or more clients declare an interest in the full content. main character behavior only 🌟

in "Manual" mode, the window contents are not drawn on screen at all — only kept off-screen. this mode is for special "composite manager" programs which might make a composite display (hence the name of the extension, iykyk) of the overlapping windows with partial-transparency or shadowing effects. gorgeous. stunning. 💅

but heads up — there's nothing here to draw or combine to actually make a composite window result. when you need that, it's done with the usual core protocol drawing or with drawing extensions such as RENDER (peep X11::Protocol::Ext::RENDER). 💜

🔥 REQUESTS 🔥

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, and the returned $server_major and $server_minor is what the server will do, which might be less than requested (but not more than). fr fr.
not me finding out that the X.org server circa 1.10 will return a higher minor version than the client requests. iconic behavior honestly 😭

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. and bestie, the root window cannot be redirected. periodt. 🚫

$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). sharing is not caring here 💀

redirection is a per-client setting and is automatically unredirected if the client disconnects. an unredirect when not redirected is a "BadValue" error — so like, don't do that 🙈. 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. yeah the original doc says that, i'm not making it up, it literally says "umm" 😭

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. and 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. the way that it just resets like that 😭

👑 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. generous queen 💅

  • $X->CompositeReleaseOverlayWindow ($window) — release the composite overlay window for the screen of $window. when all clients release it the overlay window is destroyed. bye bestie 👋

🌈 SEE ALSO 🌈

  • X11::Protocol
  • X11::Protocol::Ext::XFIXES
  • X11::Protocol::Ext::DOUBLE_BUFFER

and also, from the source material:

🧚 HOME PAGE 🧚

<http://user42.tuxfamily.org/x11-protocol-other/index.html>

go off, the homepage is right there 🫶

💜 LICENSE 💜

Copyright 2011, 2012, 2013, 2014, 2017 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/>.

no cap: that warranty disclaimer is doing the most, but it's legally iconic so we keep it verbatim 💀

aaand that's the whole page, bestie ✨ this one was generated by perl v5.28.1 and dated 2019-08-26 — so if you're reading it, congrats, you're deep in the X11::Protocol::Ext::Composite lore. slay, hydrate, and always call init_extension('Composite') first 💖🎀

📦 where this page comes from