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
45 to 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
53 slow for lots of little accesses.
54 "IPC::SysV" (version 2 up) offers a "shmat()" to keep the block
56 attached and "memread()" and "memwrite()" to access it (see IPC::SysV).
57 See 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
61 for not enough memory etc. With that, not being on the same machine,
62 not having identifiable perms, etc, there's a quite a few 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 doesn't matter who else reads the segment.
79 Remember to ask for read-only in the "MitShmAttach()" so the server
80 doesn't want writable too.
81 There's probably no need to risk relaxing permissions for writing.
83 Chances are that if client UID/GID can't be identified then it's
84 because the connection is not local and the server is on a different
85 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
127 "shmget()" (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
131 is 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
210 (in Damage version 1.1) to tell the server about changes made,
211 which it will broadcast to interested damage objects. It's
212 probably unusual to have damage objects listening to a shared
213 pixmap though.
214
216 "MitShmCompletionEvent" is sent to the client when requested in an
217 "MitShmPutImage()". It says the server has finished reading the
218 memory. The event has the usual fields
219 name "MitShmCompletionEvent"
221 synthetic true if from a SendEvent
222 code integer opcode
223 sequence_number integer
224 and event-specific fields
226 drawable XID, target as from request
228 shmseg XID, source as from request
229 offset integer, byte offset as from request
230 major_opcode integer, MIT-SHM extension code
231 minor_opcode integer, 3 for MitShmPutImage
232 "major_opcode" and "minor_opcode" are the codes of the originating
234 "MitShmPutImage()". These fields are similar to the core
235 "GraphicsExposure" and "NoExposure" events, but here there's only one
236 request ("MitShmPutImage()") which gives a completion event.
237
239 Error type "ShmSeg" is a bad $shmseg resource XID in a request.
240
242 X11::Protocol, "shmget" in perlfunc, "SysV IPC" in perlipc, IPC::SysV,
243 IPC::SharedMem
244 X11::Protocol::Ext::Damage
246 /usr/share/doc/x11proto-xext-dev/shm.txt.gz,
248 /usr/share/X11/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.28.0 2014-01-18 X11::Protocol::Ext::MIT_SHM(3)