1X11::Protocol::Ext::MITU_sSeHrM(C3o)ntributed Perl DocumXe1n1t:a:tPiroontocol::Ext::MIT_SHM(3)
2
6 X11::Protocol::Ext::MIT_SHM - images in SysV style shared memory
7
9 use X11::Protocol;
10 my $X = X11::Protocol->new;
11 $X->init_extension('MIT-SHM')
12 or print "MIT-SHM extension not available";
13 use IPC::SysV;
15 my $shmid = shmget (IPC::SysV::IPC_PRIVATE(),
16 100000, # bytes
17 IPC::SysV::IPC_CREAT() | 0666);
18 my $shmseg = $X->new_rsrc;
20 $X->MitShmAttach ($shmseg, $shmid, 0);
21 my ($depth, $visual, $size) = $X->MitShmGetImage
23 ($window, 0,0, 16,16, ~0, 'ZPixmap', $shmseg, 0);
24 my $image_bytes;
25 shmread ($shmid, $image_bytes, 0, 16*16*$bpp) || die "$!";
26 # $image_bytes is the top-left 16x16 pixels of the screen
28
30 The MIT-SHM extension allows a client and server running on the same
31 machine to transfer image data through System-V shared memory segments.
32 The client creates a memory segment with shmget() (see "shmget" in
34 perlfunc and "SysV IPC" in perlipc) and asks the server to attach to it
35 and then read or write with equivalents to the core GetImage and
36 PutImage.
37 The aim is to avoid sending large images through the I/O connection
39 when on the same machine. Memory is faster, and may help avoid request
40 size limits for very big images.
41 Byte order, padding, etc, required or generated in images is specified
43 by the server "$X->{'image_byte_order'}", "$X->{'pixmap_formats'}",
44 etc, the same as for the core GetImage() and PutImage(). It's up to
45 the client to adapt to the server's layout, which can be a bit of a
46 chore.
47 Shm from Perl
49 A shared memory segment can be created from Perl with shmget(), then
50 read or write its contents with shmread() and shmwrite(). Those
51 functions attach and detach it each time with shmat() and shmdt()
52 system calls, which is fine for grabbing the lot but will be a bit slow
53 for lots of little accesses.
54 "IPC::SysV" (version 2 up) offers a shmat() to keep the block attached
56 and memread() and memwrite() to access it (see IPC::SysV). See
57 IPC::SharedMem for an object-oriented wrapper around this too.
58 Incidentally, if shmget() is not available on the system then Perl's
60 shmget() croaks. It's always possible for it to return "undef" too for
61 not enough memory etc. With that, not being on the same machine, not
62 having identifiable permissions, etc, there's several cases where a
63 fallback to plain I/O will be necessary.
64 Shm Permissions
66 A SysV shared memory segment has owner/group/other permission bits
67 similar to a file. The server will only attach to segments which the
68 requesting client UID/GID has permission to read or write.
69 The server can usually determine a client's UID/GID on a local
71 connection such as Unix socket (X11::Protocol::Connection::UNIXSocket,
72 and "SO_PEERCRED" in socket(7)), and perhaps on a TCP localhost
73 loopback. Failing that the server treats the client as "other" and
74 will only attach to world-readable (or world read-writable) segments.
75 You can make a shm segment world-readable to ensure the server can read
77 it. If the data for a PutImage etc is already from a world-readable
78 file or is public then it shouldn't matter much who else reads the
79 segment. Remember to ask for read-only in the MitShmAttach() so the
80 server doesn't want writable too.
81 There's probably no need to risk relaxing permissions for segment
83 writing. Chances are that if client UID/GID can't be identified then
84 it's because the connection is not local and the server is on a
85 different machine so shared memory can't be used anyway.
86 It's usual for the server to run as root, hence it's own permission
88 checks, but it's also possible for the server to be an ordinary user.
89 In that case the shm segments it can access will be limited in the
90 usual way for the user it's running as.
91
93 The following requests are available after an init_extension() per
94 "EXTENSIONS" in X11::Protocol.
95 my $bool = $X->init_extension('MIT-SHM');
97 In the following $shmid is the shared memory ID (an integer) as
99 obtained from the kernel with shmget(). $shmseg is an XID (allocated
100 as usual by client "$X->new_rsrc()") on the server representing the
101 server attachment to the block.
102 "($server_major, $server_minor, $uid, $gid, $shared_pixmaps,
104 $pixmap_format) = $X->MitShmQueryVersion ()"
105 Return information about the MIT-SHM extension. Unlike other
106 extensions there's no client version / server version negotiation.
107 $server_major and $server_minor are the extension version number
109 implemented by the server.
110 $uid and $gid (integers) are the server's effective user ID and
112 group ID (geteuid() and getegid()). Zero means root.
113 $shared_pixmaps is non-zero if pixmaps in shared memory are
115 supported (see MitShmCreatePixmap() below). $pixmap_format (an
116 ImageFormat) is "XYPixmap" or "ZPixmap" for the layout required in
117 such a pixmap.
118 "$X->MitShmAttach ($shmseg, $shmid, $readonly)"
120 Attach the server to a given shared memory segment. $shmseg is a
121 new XID to represent the attached memory.
122 my $shmseg = $X->new_rsrc;
124 $X->MitShmAttach ($shmseg, $shmid, 0); # read/write
125 $shmid is the shared memory ID to attach, as obtained from shmget()
127 (see "shmget" in perlfunc).
128 $readonly is 1 to have the server attach read-only, or 0 for read-
130 write. Read-only suffices for MitShmPutImage(), but read-write is
131 needed for MitShmGetImage() and MitShmCreatePixmap().
132 "$X->MitShmDetach ($shmseg)"
134 Detach the server from shared memory $shmseg (an XID) and release
135 that XID.
136 $X->MitShmDetach ($shmseg);
138 "$X->MitShmPutImage ($drawable, $gc, $depth, $total_width,
140 $total_height, $src_x, $src_y, $src_width, $src_height, $dst_x, $dst_y,
141 $format, $send_event, $shmseg, $offset)"
142 Put image data from $shmseg (an XID) to $drawable. The parameters
143 are similar to the core PutImage().
144 $depth is the depth of the image. For $format "Bitmap" this must
146 be 1 and the foreground and background colours of $gc are then
147 drawn. For $format "XYPixmap" and "ZPixmap" $depth must be the
148 depth of $drawable.
149 $total_width,$total_height is the full size of the image in the
151 shared memory. $src_x,$src_y and $src_width,$src_height are the
152 portion of it to draw. $dst_x,$dst_y is where in $drawable to put
153 it.
154 $format is "Bitmap", "XYPixmap" or "ZPixmap" (an ImageFormat).
156 $send_event is 1 to have an "MitShmCompletionEvent" sent to the
158 client when drawing is finished (see "EVENTS" below), or 0 if
159 that's not wanted.
160 $offset is a byte offset into the shared memory where the image
162 starts.
163 "($depth, $visual, $size) = $X->MitShmGetImage ($drawable, $x, $y,
165 $width, $height, $planemask, $format, $shmseg, $offset)"
166 Copy an image from $drawable to shared memory $shmseg (an XID).
167 The parameters are similar to the core GetImage().
168 $x,$y, $width,$height are the part of $drawable to get. $planemask
170 is a bit mask for which bit planes of the pixels are wanted.
171 $format is "XYPixmap" or "ZPixmap" for the layout to be written to
173 the shared memory, and $offset is a byte offset into the memory
174 where the image should start.
175 The returned $depth (an integer) is the depth of $drawable.
177 $visual (integer ID) is its visual for a window, or "None" for a
178 pixmap. $size is how many bytes were written.
179 $shmseg must be attached read-write in the MitShmAttach() or an
181 "Access" error results.
182 "$X->MitShmCreatePixmap ($pixmap, $drawable, $depth, $width, $height,
184 $shmseg, $offset)"
185 Create $pixmap (a new XID) as a pixmap with contents in shared
186 memory $shmseg (an XID). When the client reads or writes that
187 memory it changes the pixmap contents. The parameters are similar
188 to the core CreatePixmap().
189 my $pixmap = $X->new_rsrc;
191 $X->MitShmCreatePixmap ($pixmap, # new XID
192 $X->root, # for the screen
193 $X->root_depth, # depth
194 10,10, # width,height
195 $shmseg,
196 0); # byte offset into shm
197 The MitShmQueryVersion() request above reports whether shared
199 memory pixmaps are supported, and if so whether they're "XYPixmap"
200 or "ZPixmap" layout.
201 $drawable is used to determine the screen for the new $pixmap.
203 $offset is a byte offset into the shared memory where the pixmap
204 data will begin.
205 If damage objects from the DAMAGE extension (see
207 X11::Protocol::Ext::DAMAGE) are monitoring a shared $pixmap then
208 client writes to the shared memory generally don't produce
209 "DamageNotify" events. The client can use DamageAdd() requests (in
210 Damage version 1.1) to tell the server about changes made, which it
211 will broadcast to interested damage objects. It's probably unusual
212 to have damage objects listening to a shared pixmap though.
213
215 "MitShmCompletionEvent" is sent to the client when requested in an
216 MitShmPutImage(). It says the server has finished reading the memory.
217 The event has the usual fields
218 name "MitShmCompletionEvent"
220 synthetic true if from a SendEvent
221 code integer opcode
222 sequence_number integer
223 and event-specific fields
225 drawable XID, target as from request
227 shmseg XID, source as from request
228 offset integer, byte offset as from request
229 major_opcode integer, MIT-SHM extension code
230 minor_opcode integer, 3 for MitShmPutImage
231 "major_opcode" and "minor_opcode" are the codes of the originating
233 MitShmPutImage(). These fields are similar to the core
234 "GraphicsExposure" and "NoExposure" events, but here there's only one
235 request (MitShmPutImage()) which gives a completion event.
236
238 Error type "ShmSeg" is a bad $shmseg resource XID in a request.
239
241 X11::Protocol, "shmget" in perlfunc, "SysV IPC" in perlipc, IPC::SysV,
242 IPC::SharedMem
243 X11::Protocol::Ext::Damage
245 /usr/share/doc/x11proto-xext-dev/shm.txt.gz,
247 /usr/share/X11/doc/hardcopy/Xext/mit-shm.PS.gz,
248 ftp://ftp.xfree86.org/pub/mirror/X.Org/pub/R6.6/xc/doc/hardcopy/Xext/mit-shm.PS.gz
249
251 <http://user42.tuxfamily.org/x11-protocol-other/index.html>
252
254 Copyright 2011 Kevin Ryde
255 X11-Protocol-Other is free software; you can redistribute it and/or
257 modify it under the terms of the GNU General Public License as
258 published by the Free Software Foundation; either version 3, or (at
259 your option) any later version.
260 X11-Protocol-Other is distributed in the hope that it will be useful,
262 but WITHOUT ANY WARRANTY; without even the implied warranty of
263 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
264 General Public License for more details.
265 You should have received a copy of the GNU General Public License along
267 with X11-Protocol-Other. If not, see <http://www.gnu.org/licenses/>.
268perl v5.38.0 2023-07-21 X11::Protocol::Ext::MIT_SHM(3)