NAME

       X11::Protocol::Ext::TOG_CUP - colormap utilization policy extension

SYNOPSIS

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

DESCRIPTION

       The TOG-CUP extension helps applications with private colormaps use the same pixel for the same color in
       different colormaps.

       Using common pixel values, were possible, means that when a private colormap is in use
       ("$x->InstallColormap()", usually done by the window manager) some of the colours in other windows will
       still appear correctly.

       Note that this extension makes a subtle change to the core "$X->AllocColor()" and "$X->AllocNamedColor()"
       requests.  Normally they 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 is
       allocated, thus making that colour the same in the two colormaps.

REQUESTS

       The following are made available with 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.  $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
           different.

           The  current  code  supports  up  to  1.0.   The  intention  would  be  to automatically negotiate in
           "init_extension()" if necessary, which it's currently not.

       "@colors = $X->CupGetReservedColormapEntries ($screen)"
           Return a list of reserved colormap entries in the default  colormap  of  screen  number  $screen  (an
           integer 0 upwards).  Each 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.

           Reserved colours are pre-allocated and unchanging.  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.

           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.

       "@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 is unused and can be omitted.)

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

           The desired colour is allocated shareable read-only (like "$X->AllocColor()") at the given $pixel  if
           possible,  or  another if necessary.  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  returned  RGB components are the actual colour shade allocated.  This might differ if the visual
           has limited colour resolution (which is likely).

           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";
               }

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

perl v5.28.1                                       2019-08-26                   X11::Protocol::Ext::TOG_CUP(3pm)