specs/shm.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
   4
   5
   6 <!-- lifted from troff+ms+XMan by doclifter -->
   7 <book id="mit-shm">
   8
   9 <bookinfo>
  10    <title>MIT-SHM(The MIT Shared Memory Extension)</title>
  11    <subtitle>How the shared memory extension works</subtitle>
  12    <releaseinfo>Version 1.0</releaseinfo>
  13    <authorgroup>
  14       <author>
  15          <firstname>Jonathan</firstname><surname>Corbet</surname>
  16          <affiliation><orgname>Atmospheric Technology Division National Center for Atmospheric Research</orgname></affiliation>
  17       <email>corbet@ncar.ucar.edu</email>
  18       </author>
  19       <othercredit>
  20          <contrib>Formatted and edited for release 5 by</contrib>
  21          <firstname>Keith</firstname><surname>Packard</surname>
  22          <affiliation><orgname>MIT X Consortium</orgname></affiliation>
  23       </othercredit>
  24    </authorgroup>
  25    <corpname>X Consortium Standard</corpname>
  26    <copyright><year>1991</year><holder>X Consortium</holder></copyright>
  27    <affiliation><orgname>X Consortium</orgname></affiliation>
  28    <productnumber>X Version 11, Release 7</productnumber>
  29
  30 <abstract>
  31 <para>
  32 This document briefly describes how to use the MIT-SHM shared memory
  33 extension.  I have tried to make it accurate, but it would not surprise me
  34 if some errors remained.  If you find anything wrong, do let me know and I
  35 will incorporate the corrections.  Meanwhile, please take this document "as
  36 is" (eman improvement over what was there before, but certainly not the
  37 definitive word.)
  38 </para>
  39 </abstract>
  40
  41 <legalnotice>
  42 <para>
  43 Permission is hereby granted, free of charge, to any person obtaining a copy
  44 of this software and associated documentation files (the "Software"), to deal
  45 in the Software without restriction, including without limitation the rights
  46 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  47 copies of the Software, and to permit persons to whom the Software is
  48 furnished to do so, subject to the following conditions:
  49 </para>
  50 <para>
  51 The above copyright notice and this permission notice shall be included in
  52 all copies or substantial portions of the Software.
  53 </para>
  54 <para>
  55 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  56 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  57 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  58 X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  59 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  60 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  61 </para>
  62 <para>
  63 Except as contained in this notice, the name of the X Consortium shall not be
  64 used in advertising or otherwise to promote the sale, use or other dealings
  65 in this Software without prior written authorization from the X Consortium.
  66 </para>
  67 </legalnotice>
  68 </bookinfo>
  69
  70 <chapter>
  71 <title>TITLE</title>
  72 <sect1 id="REQUIREMENTS">
  73 <title>REQUIREMENTS</title>
  74 <para>
  75 The shared memory extension is provided only by some X servers.  To find out
  76 if your server supports the extension, use xdpyinfo(1).  In particular, to
  77 be able to use this extension, your system must provide the SYSV shared
  78 memory primitives.  There is not an mmap-based version of this extension.
  79 To use shared memory on Sun systems, you must have built your kernel with
  80 SYSV shared memory enabled -- which is not the default configuration.
  81 Additionally, the shared memeory maximum size will need to be increased on
  82 both Sun and Digital systems; the defaults are far too small for any useful
  83 work.
  84 </para>
  85 </sect1>
  86
  87 <sect1 id="WHAT_IS_PROVIDED">
  88 <title>WHAT IS PROVIDED</title>
  89
  90 <para>
  91 The basic capability provided is that of shared memory XImages.  This is
  92 essentially a version of the ximage interface where the actual image data
  93 is stored in a shared memory segment, and thus need not be moved through
  94 the Xlib interprocess communication channel.  For large images, use of this
  95 facility can result in some real performance increases.
  96 </para>
  97
  98 <para>
  99 Additionally, some implementations provided shared memory pixmaps.  These
 100 are 2 dimensional arrays of pixels in a format specified by the X server,
 101 where the image data is stored in the shared memory segment.  Through use of
 102 shared memory pixmaps, it is possible to change the contents of these
 103 pixmaps without using any Xlib routines at all.  Shared memory pixmaps can
 104 only be supported when the X server can use regular virtual memory for
 105 pixmap data; if the pixmaps are stored in some magic graphics hardware, your
 106 application will not be able to share them with the server.  Xdpyinfo(1)
 107 doesn't print this particular nugget of information.
 108 </para>
 109 </sect1>
 110
 111 <sect1 id="HOW_TO_USE_THE_SHARED_MEMORY_EXTENSION">
 112 <title>HOW TO USE THE SHARED MEMORY EXTENSION</title>
 113 <para>
 114 Code which uses the shared memory extension must include a number of header
 115 files:
 116 </para>
 117
 118 <literallayout class="monospaced">
 119 #include &lt;X11/Xlib.h&gt;          /* of course */
 120 #include &lt;sys/ipc.h&gt;
 121 #include &lt;sys/shm.h&gt;
 122 #include &lt;X11/extensions/XShm.h&gt;
 123 </literallayout>
 124
 125 <para>
 126 Of course, if the system you are building on does not support shared
 127 memory, the file XShm.h may not be present.  You may want to make
 128 liberal use of #ifdefs.
 129 </para>
 130
 131 <para>
 132 Any code which uses the shared memory extension should first check to see
 133 that the server provides the extension.  You could always be running over
 134 the net, or in some other environment where the extension will not work.
 135 To perform this check, call either
 136 </para>
 137
 138 <funcsynopsis>
 139 <funcprototype>
 140   <funcdef>Status <function>XShmQueryExtension</function></funcdef>
 141     <paramdef>Display <parameter>*display</parameter></paramdef>
 142 </funcprototype>
 143 </funcsynopsis>
 144
 145 <para>
 146 or
 147 </para>
 148
 149 <funcsynopsis>
 150 <funcprototype>
 151   <funcdef>Status <function>XShmQueryVersion</function></funcdef>
 152     <paramdef>Display <parameter>*display</parameter></paramdef>
 153     <paramdef>int <parameter>*major</parameter></paramdef>
 154     <paramdef>int <parameter>*minor</parameter></paramdef>
 155     <paramdef>Bool <parameter>*pixmaps</parameter></paramdef>
 156 </funcprototype>
 157 </funcsynopsis>
 158
 159 <para>
 160 Where "display" is, of course, the display on which you are running.  If
 161 the shared memory extension may be used, the return value from either
 162 function will be True; otherwise your program should operate using
 163 conventional Xlib calls.  When the extension is available,
 164 \fCXShmQueryVersion\fP also returns "major" and "minor" which are the
 165 version numbers of the extension implementation, and "pixmaps" which is
 166 True iff shared memory pixmaps are supported.
 167 </para>
 168 </sect1>
 169
 170 <sect1 id="USE_OF_SHARED_MEMORY_XIMAGES">
 171 <title>USE OF SHARED MEMORY XIMAGES</title>
 172 <para>
 173 The basic sequence of operations for shared memory XImages is as follows:
 174 </para>
 175
 176 <orderedlist>
 177   <listitem>
 178     <para>
 179 Create the shared memory XImage structure
 180     </para>
 181   </listitem>
 182   <listitem>
 183     <para>
 184 Create a shared memory segment to store the image data
 185     </para>
 186   </listitem>
 187   <listitem>
 188     <para>
 189 Inform the server about the shared memory segment
 190     </para>
 191   </listitem>
 192   <listitem>
 193     <para>
 194 Use the shared memory XImage, much like a normal one.
 195     </para>
 196   </listitem>
 197 </orderedlist>
 198
 199 <para>
 200 To create a shared memory XImage, use:
 201 </para>
 202
 203 <funcsynopsis>
 204 <funcprototype>
 205   <funcdef>XImage <function>*XShmCreateImage</function></funcdef>
 206     <paramdef>Display <parameter>*display</parameter></paramdef>
 207     <paramdef>Visual <parameter>*visual</parameter></paramdef>
 208     <paramdef>unsigned int <parameter>depth</parameter></paramdef>
 209     <paramdef>int <parameter>format</parameter></paramdef>
 210     <paramdef>char <parameter>*data</parameter></paramdef>
 211     <paramdef>XShmSegmentInfo <parameter>*shminfo</parameter></paramdef>
 212     <paramdef>unsigned int <parameter>width</parameter></paramdef>
 213     <paramdef>unsigned int <parameter>height</parameter></paramdef>
 214 </funcprototype>
 215 </funcsynopsis>
 216
 217 <para>
 218 Most of the arguments are the same as for XCreateImage; I will not go
 219 through them here.  Note, however, that there are no "offset", "bitmap_pad",
 220 or "bytes_per_line" arguments.  These quantities will be defined by the
 221 server itself, and your code needs to abide by them.  Unless you have already
 222 allocated the shared memory segment (see below), you should pass in NULL for
 223 the "data" pointer.
 224 </para>
 225
 226 <para>
 227 There is one additional argument: "shminfo", which is a pointer to a
 228 structure of type XShmSegmentInfo.  You must allocate one of these
 229 structures such that it will have a lifetime at least as long as that of
 230 the shared memory XImage.  There is no need to initialize this structure
 231 before the call to XShmCreateImage.
 232 </para>
 233
 234 <para>
 235 The return value, if all goes well, will be an XImage structure, which you
 236 can use for the subsequent steps.
 237 </para>
 238
 239 <para>
 240 The next step is to create the shared memory segment.  This is
 241 best done after the creation of the XImage, since you need to make use of
 242 the information in that XImage to know how much memory to allocate.  To
 243 create the segment, you need a call like:
 244 </para>
 245
 246
 247 <literallayout class="monospaced">
 248 shminfo.shmid = shmget (IPC_PRIVATE,
 249           image-&gt;bytes_per_line * image-&gt;height, IPC_CREAT|0777);
 250 </literallayout>
 251
 252 <para>
 253 (assuming that you have called your shared memory XImage "image").  You
 254 should, of course, follow the Rules and do error checking on all of these
 255 system calls.  Also, be sure to use the bytes_per_line field, not the width
 256 you used to create the XImage as they may well be different.
 257 </para>
 258
 259 <para>
 260 Note that the shared memory ID returned by the system is stored in the
 261 shminfo structure.  The server will need that ID to attach itself to the
 262 segment.
 263 </para>
 264
 265 <para>
 266 Also note that, on many systems for security reasons, the X server
 267 will only accept to attach to the shared memory segment if it's
 268 readable and writeable by "other". On systems where the X server is
 269 able to determine the uid of the X client over a local transport, the
 270 shared memory segment can be readable and writeable only by the uid of
 271 the client.
 272 </para>
 273
 274 <para>
 275 Next, attach this shared memory segment to your process:
 276 </para>
 277
 278 <para>
 279 shminfo.shmaddr = image-&gt;data = shmat (shminfo.shmid, 0, 0);
 280 </para>
 281
 282 <para>
 283 The address returned by shmat should be stored in *both* the XImage
 284 structure and the shminfo structure.
 285 </para>
 286
 287 <para>
 288 To finish filling in the shminfo structure, you need to decide how you want
 289 the server to attach to the shared memory segment, and set the "readOnly"
 290 field as follows.  Normally, you would code:
 291 </para>
 292 <para>
 293 shminfo.readOnly = False;
 294 </para>
 295
 296 <para>
 297 If you set it to True, the server will not be able to write to this
 298 segment, and thus XShmGetImage calls will fail.
 299 </para>
 300
 301 <para>
 302 Finally, tell the server to attach to your shared memory segment with:
 303 </para>
 304
 305 <literallayout class="monospaced">
 306 Status XShmAttach (display, shminfo);
 307 </literallayout>
 308
 309 <para>
 310 If all goes well, you will get a non-zero status back, and your XImage is
 311 ready for use.
 312 </para>
 313
 314 <para>
 315 To write a shared memory XImage into an X drawable, use XShmPutImage:
 316 </para>
 317
 318 <funcsynopsis>
 319 <funcprototype>
 320   <funcdef>Status <function>XShmPutImage </function></funcdef>
 321     <paramdef>Display <parameter>*display</parameter></paramdef>
 322     <paramdef>Drawable <parameter>d</parameter></paramdef>
 323     <paramdef>GC <parameter>gc</parameter></paramdef>
 324     <paramdef>XImage <parameter>*image</parameter></paramdef>
 325     <paramdef>int <parameter>src_x</parameter></paramdef>
 326     <paramdef>int <parameter>src_y</parameter></paramdef>
 327     <paramdef>int <parameter>dest_x</parameter></paramdef>
 328     <paramdef>int <parameter>dest_y</parameter></paramdef>
 329     <paramdef>unsigned int <parameter>width</parameter></paramdef>
 330     <paramdef>unsigned int <parameter>height</parameter></paramdef>
 331     <paramdef>bool <parameter>send_event</parameter></paramdef>
 332 </funcprototype>
 333 </funcsynopsis>
 334
 335 <para>
 336 The interface is identical to that of XPutImage, so I will spare my fingers
 337 and not repeat that documentation here.  There is one additional parameter,
 338 however, called "send_event".  If this parameter is passed as True, the
 339 server will generate a "completion" event when the image write is complete;
 340 thus your program can know when it is safe to begin manipulating the shared
 341 memory segment again.
 342 </para>
 343
 344 <para>
 345 The completion event has type XShmCompletionEvent, which is defined as the
 346 following:
 347 </para>
 348
 349 <literallayout class="monospaced">
 350 typedef struct {
 351     int type;              /* of event */
 352     unsigned long serial;  /* # of last request processed */
 353     Bool send_event;       /* true if came from a SendEvent request */
 354     Display *display;      /* Display the event was read from */
 355     Drawable drawable;     /* drawable of request */
 356     int major_code;        /* ShmReqCode */
 357     int minor_code;        /* X_ShmPutImage */
 358     ShmSeg shmseg;         /* the ShmSeg used in the request */
 359     unsigned long offset;  /* the offset into ShmSeg used */
 360 } XShmCompletionEvent;
 361 </literallayout>
 362
 363 <para>
 364 The event type value that will be used can be determined at run time with a
 365 line of the form:
 366 </para>
 367
 368 <para>
 369 int CompletionType = XShmGetEventBase (display) + ShmCompletion;
 370 </para>
 371
 372 <para>
 373 If you modify the shared memory segment before the arrival of the
 374 completion event, the results you see on the screen may be inconsistent.
 375 </para>
 376
 377 <para>
 378 To read image data into a shared memory XImage, use the following:
 379 </para>
 380
 381 <funcsynopsis>
 382 <funcprototype>
 383   <funcdef>Status <function>XShmGetImage </function></funcdef>
 384     <paramdef>Display <parameter>*display</parameter></paramdef>
 385     <paramdef>Drawable <parameter>d</parameter></paramdef>
 386     <paramdef>XImage <parameter>*image</parameter></paramdef>
 387     <paramdef>int <parameter>x</parameter></paramdef>
 388     <paramdef>int <parameter>y</parameter></paramdef>
 389     <paramdef>unsigned long <parameter>plane_mask</parameter></paramdef>
 390 </funcprototype>
 391 </funcsynopsis>
 392
 393 <para>
 394 Where "display" is the display of interest, "d" is the source drawable,
 395 "image" is the destination XImage, "x" and "y" are the offsets within
 396 "d", and "plane_mask" defines which planes are to be read.
 397 </para>
 398
 399 <para>
 400 To destroy a shared memory XImage, you should first instruct the server to
 401 detach from it, then destroy the segment itself, as follows:
 402 </para>
 403
 404 <literallayout class="monospaced">
 405 XShmDetach (display, shminfo);
 406 XDestroyImage (image);
 407 shmdt (shminfo.shmaddr);
 408 shmctl (shminfo.shmid, IPC_RMID, 0);
 409 </literallayout>
 410
 411 </sect1>
 412
 413 <sect1 id="USE_OF_SHARED_MEMORY_PIXMAPS">
 414 <title>USE OF SHARED MEMORY PIXMAPS</title>
 415 <para>
 416 Unlike X images, for which any image format is usable, the shared memory
 417 extension supports only a single format (i.e. XYPixmap or ZPixmap) for the
 418 data stored in a shared memory pixmap.  This format is independent of the
 419 depth of the image (for 1-bit pixmaps it doesn't really matter what this
 420 format is) and independent of the screen.  Use XShmPixmapFormat to get the
 421 format for the server:
 422 </para>
 423
 424 <funcsynopsis>
 425 <funcprototype>
 426   <funcdef>int <function>XShmPixmapFormat</function></funcdef>
 427     <paramdef>Display <parameter>*display</parameter></paramdef>
 428 </funcprototype>
 429 </funcsynopsis>
 430
 431 <para>
 432 If your application can deal with the server pixmap data format (including
 433 bits-per-pixel et al.), create a shared memory segment and "shminfo"
 434 structure in exactly the same way as is listed above for shared memory
 435 XImages.  While it is, not strictly necessary to create an XImage first,
 436 doing so incurs little overhead and will give you an appropriate
 437 bytes_per_line value to use.
 438 </para>
 439
 440 <para>
 441 Once you have your shminfo structure filled in, simply call:
 442 </para>
 443
 444 <funcsynopsis>
 445 <funcprototype>
 446   <funcdef>Pixmap <function>XShmCreatePixmap</function></funcdef>
 447     <paramdef>Display <parameter>*display</parameter></paramdef>
 448     <paramdef>Drawable <parameter>d</parameter></paramdef>
 449     <paramdef>char <parameter>*data</parameter></paramdef>
 450     <paramdef>XShmSegmentInfo <parameter>*shminfo</parameter></paramdef>
 451     <paramdef>unsigned int <parameter>width</parameter></paramdef>
 452     <paramdef>unsigned int <parameter>height</parameter></paramdef>
 453     <paramdef>unsigned int <parameter>depth</parameter></paramdef>
 454 </funcprototype>
 455 </funcsynopsis>
 456
 457 <para>
 458 The arguments are all the same as for XCreatePixmap, with two additions:
 459 "data" and "shminfo".  The second of the two is the same old shminfo
 460 structure that has been used before.  The first is the pointer to the shared
 461 memory segment, and should be the same as the shminfo.shmaddr field.  I am
 462 not sure why this is a separate parameter.
 463 </para>
 464
 465 <para>
 466 If everything works, you will get back a pixmap, which you can manipulate in
 467 all of the usual ways, with the added bonus of being able to tweak its
 468 contents directly through the shared memory segment.  Shared memory pixmaps
 469 are destroyed in the usual manner with XFreePixmap, though you should detach
 470 and destroy the shared memory segment itself as shown above.
 471 </para>
 472 </sect1>
 473 </chapter>
 474 </book>