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

NAME

6       X11::Protocol::Ext::MIT_SHM - images in SysV style shared memory
7

SYNOPSIS

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
14        use IPC::SysV;
15        my $shmid = shmget (IPC::SysV::IPC_PRIVATE(),
16                            100000,  # bytes
17                            IPC::SysV::IPC_CREAT() | 0666);
18
19        my $shmseg = $X->new_rsrc;
20        $X->MitShmAttach ($shmseg, $shmid, 0);
21
22        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
27        # $image_bytes is the top-left 16x16 pixels of the screen
28

DESCRIPTION

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
33       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
38       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
42       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
48   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
55       "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
59       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
65   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
70       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
76       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
82       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
87       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

REQUESTS

93       The following requests are available after an "init_extension()" per
94       "EXTENSIONS" in X11::Protocol.
95
96           my $bool = $X->init_extension('MIT-SHM');
97
98       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
103       "($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
108           $server_major and $server_minor are the extension version number
109           implemented by the server.
110
111           $uid and $gid (integers) are the server's effective user ID and
112           group ID ("geteuid()" and "getegid()").  Zero means root.
113
114           $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
119       "$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
123               my $shmseg = $X->new_rsrc;
124               $X->MitShmAttach ($shmseg, $shmid, 0); # read/write
125
126           $shmid is the shared memory ID to attach, as obtained from
127           "shmget()" (see "shmget" in perlfunc).
128
129           $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
133       "$X->MitShmDetach ($shmseg)"
134           Detach the server from shared memory $shmseg (an XID) and release
135           that XID.
136
137               $X->MitShmDetach ($shmseg);
138
139       "$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
145           $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
150           $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
155           $format is "Bitmap", "XYPixmap" or "ZPixmap" (an ImageFormat).
156
157           $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
161           $offset is a byte offset into the shared memory where the image
162           starts.
163
164       "($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
169           $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
172           $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
176           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
180           $shmseg must be attached read-write in the "MitShmAttach()" or an
181           "Access" error results.
182
183       "$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
190               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
198           The "MitShmQueryVersion()" request above reports whether shared
199           memory pixmaps are supported, and if so whether they're "XYPixmap"
200           or "ZPixmap" layout.
201
202           $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
206           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

EVENTS

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
220           name             "MitShmCompletionEvent"
221           synthetic        true if from a SendEvent
222           code             integer opcode
223           sequence_number  integer
224
225       and event-specific fields
226
227           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
233       "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

ERRORS

239       Error type "ShmSeg" is a bad $shmseg resource XID in a request.
240

SEE ALSO

242       X11::Protocol, "shmget" in perlfunc, "SysV IPC" in perlipc, IPC::SysV,
243       IPC::SharedMem
244
245       X11::Protocol::Ext::Damage
246
247       /usr/share/doc/x11proto-xext-dev/shm.txt.gz,
248       /usr/share/X11/doc/hardcopy/Xext/mit-shm.PS.gz
249

HOME PAGE

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

LICENSE

254       Copyright 2011 Kevin Ryde
255
256       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
261       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
266       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/>.
268
269
270
271perl v5.28.1                      2014-01-18    X11::Protocol::Ext::MIT_SHM(3)
Impressum