X11::Protocol::Ext::TOG_CUP(3pm)

1X11::Protocol::Ext::TOGU_sCeUrP(C3o)ntributed Perl DocumXe1n1t:a:tPiroontocol::Ext::TOG_CUP(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

15       The TOG-CUP extension helps applications with private colormaps use the
16       same pixel for the same color in different colormaps.
17
18       Using common pixel values, were possible, means that when a private
19       colormap is in use ("$x->InstallColormap()", usually done by the window
20       manager) some of the colours in other windows will still appear
21       correctly.
22
23       Note that this extension makes a subtle change to the core
24       "$X->AllocColor()" and "$X->AllocNamedColor()" requests.  Normally they
25       allocate the first available pixel, but with TOG-CUP if there's a
26       matching colour in the default colormap and that same pixel in the
27       target colormap is free then that pixel is allocated, thus making that
28       colour the same in the two colormaps.
29

REQUESTS

31       The following are made available with an "init_extension()" per
32       "EXTENSIONS" in X11::Protocol.
33
34           my $bool = $X->init_extension('TOG-CUP');
35
36       "($server_major, $server_minor) = $X->CupQueryVersion ($client_major,
37       $client_minor)"
38           Negotiate a protocol version with the server.  $client_major and
39           $client_minor is what the client would like, the returned
40           $server_major and $server_minor is what the server will do, which
41           might be different.
42
43           The current code supports up to 1.0.  The intention would be to
44           automatically negotiate in "init_extension()" if necessary, which
45           it's currently not.
46
47       "@colors = $X->CupGetReservedColormapEntries ($screen)"
48           Return a list of reserved colormap entries in the default colormap
49           of screen number $screen (an integer 0 upwards).  Each returned
50           element is an arrayref
51
52               [ $pixel, $red16, $blue16, $green16, $alloc_flags ]
53
54           $red16, $blue16 and $green16 are RGB colour components in the range
55           0 to 65535.  $alloc_flags is currently unused.
56
57           Reserved colours are pre-allocated and unchanging.  The core
58           protocol specifies "$X->{'black_pixel'}" and "$X->{'white_pixel'}"
59           and they're included in the result, plus any further colours which
60           might be reserved.
61
62           For example under the MS-DOS graphical overlay manager there's a
63           certain set of "desktop" colours which a server on that system
64           might treat as reserved.
65
66       "@colors = $X->CupStoreColors ($colormap,
67       [$pixel,$red16,$green16,$blue16],...)"
68           Allocate read-only colours in $colormap at particular pixels.
69
70           Each argument is an arrayref of desired pixel and RGB colour.  (A
71           $do_mask parameter can be present at the end too but is unused and
72           can be omitted.)
73
74               [ $pixel, $red16, $blue16, $green16 ]
75
76           The desired colour is allocated shareable read-only (like
77           "$X->AllocColor()") at the given $pixel if possible, or another if
78           necessary.  The return is a similar list of arrayref elements, one
79           for each argument
80
81               [ $pixel, $red16, $blue16, $green16, $alloc_flags ]
82
83           The returned $pixel might differ from what was requested.  If the
84           requested $pixel is already allocated, and it has a different
85           colour, then another pixel value is chosen.
86
87           The returned RGB components are the actual colour shade allocated.
88           This might differ if the visual has limited colour resolution
89           (which is likely).
90
91           The returned $alloc_flags has bit 0x08 set if the pixel was
92           successfully allocated, or clear if not.  Other bits in
93           $alloc_flags are currently unused.
94
95           For example
96
97               my @ret = $X->CupStoreColors
98                           ($colormap,
99                            [ 2,  65535,0,0],           # red
100                            [ 3,  0,65535,0],           # green
101                            [ 4,  16383,16383,16383]);  # grey
102
103               foreach my $elem (@ret) {
104                 my ($pixel, $red,$green,$blue, $alloc_ok) = @$elem;
105                 my $ok = ($alloc_ok & 8 ? "allocated" : "oops, not allocated");
106                 print "at $pixel actual $red,$green,$blue  $ok\n";
107               }
108

HOME PAGE

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

LICENSE

122       Copyright 2011, 2012, 2013, 2014, 2017 Kevin Ryde
123
124       X11-Protocol-Other is free software; you can redistribute it and/or
125       modify it under the terms of the GNU General Public License as
126       published by the Free Software Foundation; either version 3, or (at
127       your option) any later version.
128
129       X11-Protocol-Other is distributed in the hope that it will be useful,
130       but WITHOUT ANY WARRANTY; without even the implied warranty of
131       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
132       General Public License for more details.
133
134       You should have received a copy of the GNU General Public License along
135       with X11-Protocol-Other.  If not, see <http://www.gnu.org/licenses/>.
136
137
138
139perl v5.36.0                      2022-07-22    X11::Protocol::Ext::TOG_CUP(3)

NAME

SYNOPSIS

DESCRIPTION

REQUESTS

SEE ALSO

HOME PAGE

LICENSE