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

💖 X11::P...TOG_CUP(3pm) — bestie edition 💖

okay so this is the manual page for X11::Protocol::Ext::TOG_CUP, aka the colormap utilization policy extension, living in the User Contributed Perl Documentation section (3pm). yes the title up top is squished to X11::P...TOG_CUP(3pm) because man pages have commitment issues with long names. anyway. sit down, grab a boba, we're doing colormaps 🧋✨

---

✨ SYNOPSIS ✨

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

that's it. that's the whole vibe check. 🫶

---

🌸 DESCRIPTION 🌸

so TOG-CUP is here to help applications that use private colormaps all agree on the same pixel for the same color across different colormaps. sharing is caring, fr fr.

the whole point of using common pixel values where possible is this: when a private colormap is in use (that's $x->InstallColormap(), and usually the window manager is the one doing it), some of the colours in your other windows will still show up correctly instead of turning into chaos. iconic behaviour honestly. 💅

heads up bestie, this extension makes a subtle change to the core $X->AllocColor() and $X->AllocNamedColor() requests. normally they'd just allocate the first available pixel, but with TOG-CUP, if there's a matching colour in the default colormap and that same pixel in the target colormap is free, then that pixel gets allocated instead — which makes that colour match across the two colormaps. lowkey genius.

---

👑 REQUESTS 👑

these all become available once you do an init_extension(), per EXTENSIONS in X11::Protocol.

my $bool = $X->init_extension('TOG-CUP');

• ($server_major, $server_minor) = $X->CupQueryVersion ($client_major, $client_minor) — negotiate a protocol version with the server, like texting back "u up?" before committing. $client_major and $client_minor is what the client would like, and the returned $server_major and $server_minor is what the server will actually do, which might be different (it's giving "we'll see").

the current code supports up to 1.0. the intention would be to automatically negotiate inside init_extension() if necessary — which it's currently not doing. so no, it doesn't do that yet. 🙈

• @colors = $X->CupGetReservedColormapEntries ($screen) — returns a list of reserved colormap entries in the default colormap of screen number $screen (an integer, 0 upwards).

every returned element is an arrayref:

[ $pixel, $red16, $blue16, $green16, $alloc_flags ]

$red16, $blue16 and $green16 are RGB colour components in the range 0 to 65535. $alloc_flags is currently unused, so don't stress about it.

reserved colours are pre-allocated and unchanging — no takebacks. the core protocol specifies $X->{'black_pixel'} and $X->{'white_pixel'} and they're included in the result, plus any further colours which might be reserved. so black and white are always in the group chat.

for example, under the MS-DOS graphical overlay manager there's a certain set of "desktop" colours which a server on that system might treat as reserved. nostalgic tbh. 🍓

• @colors = $X->CupStoreColors ($colormap, [$pixel,$red16,$green16,$blue16],...) — allocate read-only colours in $colormap at particular pixels.

each argument is an arrayref of desired pixel and RGB colour. (a $do_mask parameter can be present at the end too, but it's unused and can be omitted — so just ghost it.)

[ $pixel, $red16, $blue16, $green16 ]

the desired colour is allocated shareable read-only (like $X->AllocColor()) at the given $pixel if possible, or another one if necessary. no drama.

the return is a similar list of arrayref elements, one for each argument:

[ $pixel, $red16, $blue16, $green16, $alloc_flags ]

the returned $pixel might differ from what was requested. if the requested $pixel is already allocated, and it has a different colour, then another pixel value is chosen. the server is the main character here, not you. 😭

the returned RGB components are the actual colour shade allocated. this might differ if the visual has limited colour resolution (which is likely — expect it).

the returned $alloc_flags has bit 0x08 set if the pixel was successfully allocated, or clear if not. other bits in $alloc_flags are currently unused.

for example:

my @ret = $X->CupStoreColors
            ($colormap,
             [ 2,  65535,0,0],           # red
             [ 3,  0,65535,0],           # green
             [ 4,  16383,16383,16383]);  # grey

foreach my $elem (@ret) {
  my ($pixel, $red,$green,$blue, $alloc_ok) = @$elem;
  my $ok = ($alloc_ok & 8 ? "allocated" : "oops, not allocated");
  print "at $pixel actual $red,$green,$blue  $ok\n";
}

slay. 🎀

---

🔥 SEE ALSO 🔥

• X11::Protocol
• Colormap Utilization Policy and Extension, Version 1.0 — <http://www.xfree86.org/current/tog-cup.html>
• /usr/share/doc/x11proto-xext-dev/tog-cup.txt.gz, /usr/share/X11/doc/hardcopy/Xext/tog-cup.PS.gz

---

🦋 HOME PAGE 🦋

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

---

💜 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/>.

---

and that's the whole page bestie 💖 this one's perl v5.28.1, dated 2019-08-26, and the header/footer insisted on calling it X11::P...TOG_CUP(3pm) — go forth and allocate responsibly, no cap. 👑✨🌸