home *** CD-ROM | disk | FTP | other *** search
/ ftp.cse.unsw.edu.au / 2014.06.ftp.cse.unsw.edu.au.tar / ftp.cse.unsw.edu.au / pub / doc / graphics / X11 / shared-memory.doc.Z / shared-memory.doc
Encoding:
Text File  |  1992-10-18  |  9.4 KB  |  243 lines
  1.            How the shared memory extension works
  2.                   Jonathan Corbet
  3.                Research Data Program
  4.          National Center for Atmospheric Research
  5.                corbet@ncar.ucar.edu
  6.  
  7.  
  8. This document briefly describes how the X11R4 shared memory extension works
  9. -- at least on my Sun 3 and 4 machines.  I have tried to make it accurate,
  10. but it would not surprise me if some errors remained.  If you find anything
  11. wrong, do let me know and I will incorporate the corrections.  Meanwhile,
  12. please take this document "as is" -- an improvement over what was there
  13. before, but certainly not the definitive word.
  14.  
  15.  
  16. REQUIREMENTS
  17.  
  18. The shared memory extension, as far as I know, is provided only in some
  19. versions of the MIT X11R4 implementation.  To be able to use this
  20. extension, your system must provide the SYSV shared memory primitives.
  21. There is not an mmap-based version of this extension.  To use shared memory
  22. on Sun systems, you must have built your kernel with SYSV shared memory
  23. enabled -- which is not the default configuration.
  24.  
  25.  
  26. WHAT IS PROVIDED
  27.  
  28. The basic capability provided is that of shared memory XImages.  This is
  29. essentially a version of the ximage interface where the actual image data
  30. is stored in a shared memory segment, and thus need not be moved through
  31. the Xlib interprocess communication channel.  For large images, use of this
  32. facility can result in some real performance increases.
  33.  
  34. Additionally, some implementations provided shared memory pixmaps.  These
  35. are simple pixmaps, where the image data is stored in the shared memory
  36. segment.  Through use of shared memory pixmaps, it is possible to change
  37. the contents of these pixmaps without using any Xlib routines at all.
  38. Apparently not all implementations provide shared memory pixmaps -- even
  39. some that provide the shared memory ximage interface.  The Sun X server
  40. does provide both.
  41.  
  42.  
  43. HOW TO USE THE SHARED MEMORY EXTENSION
  44.  
  45. Code which uses the shared memory extension must include a number of header
  46. files:
  47.  
  48.     # include <X11/Xlib.h>        /* of course */
  49.     # include <sys/ipc.h>
  50.     # include <sys/shm.h>
  51.     # include <X11/extensions/XShm.h>
  52.  
  53. Of course, if the system you are building on does not support shared
  54. memory, then the file XShm.h may not be present, so you may want to make
  55. liberal use of ifdefs.
  56.  
  57. Any code which uses the shared memory extension should first check to see
  58. that the server provides said extension.  You could always be running over
  59. the net, or in some other environment where the extension will not work.
  60. To perform this check, call:
  61.  
  62.     Status XShmQueryVersion (display, major, minor, pixmaps)
  63.     Display *display;
  64.     int *major, *minor;
  65.     Bool *pixmaps
  66.  
  67. Where "display" is, of course, the display on which you are running.  If
  68. the shared memory extension may be used, the return value will be True;
  69. otherwise your program should operate using conventional Xlib calls.  If
  70. the extension is available, "major" and "minor" will contain the version
  71. numbers of the extension implementation, and "pixmaps" will be True iff
  72. shared memory pixmaps are supported.
  73.  
  74.  
  75. USE OF SHARED MEMORY XIMAGES
  76.  
  77. The basic sequence of operations for shared memory XImages is as follows:
  78. (1) create the shared memory XImage structure, (2) create a shared memory
  79. segment to store the image data, (3) inform the server about the shared
  80. memory segment, (4) use the shared memory XImage, much like a normal one.
  81.  
  82. To create a shared memory XImage, use:
  83.  
  84.     XImage *XShmCreateImage (display, visual, depth, format, data, 
  85.         shminfo, width, height)
  86.     Display *display;
  87.     Visual *visual;
  88.     unsigned int depth, width, height;
  89.     int format;
  90.     char *data;
  91.     XShmSegmentInfo *shminfo;
  92.  
  93. Most of the arguments are the same as for XCreateImage -- I will not go
  94. through them here.  Note, however, that there are no "offset",
  95. "bitmap_pad", or "bytes_per_line" arguments.  These quantities will be
  96. defined by the server itself, and your code needs to abide by them.  Unless
  97. you have already allocated the shared memory segment (see below), you
  98. should pass in NULL for the "data" pointer.
  99.  
  100. There is one additional argument -- "shminfo", which is a pointer to a
  101. structure of type XShmSegmentInfo.  You must allocate one of these
  102. structures such that it will have a lifetime at least as long as that of
  103. the shared memory XImage.  There is no need to initialize this structure
  104. before the call to XShmCreateImage.
  105.  
  106. The return value, if all goes well, will be an XImage structure, which you
  107. can use for the subsequent steps.
  108.  
  109. The first of these steps is to create the shared memory segment.  This is
  110. best done after the creation of the XImage, since you need to make use of
  111. the information in that XImage to know how much memory to allocate.  To
  112. create the segment, you need a call like:
  113.  
  114.     shminfo.shmid = shmget (IPC_PRIVATE,
  115.             image->bytes_per_line * image->height, IPC_CREAT|0777);
  116.  
  117. (assuming that you have called your shared memory XImage "image").  You
  118. should, of course, follow the Rules and do error checking on all of these
  119. system calls.  Also, be sure to use the bytes_per_line field, not the width
  120. you used to create the XImage -- they may well be different.
  121.  
  122. Note that the shared memory ID returned by the system is stored in the
  123. shminfo structure -- the server will need that ID to attach itself to the
  124. segment.
  125.  
  126. Next, attach this shared memory segment to your process:
  127.  
  128.     shminfo.shmaddr = image->data = shmat (shminfo.shmid, 0, 0);
  129.  
  130. The address returned by shmat should be stored in *both* the XImage
  131. structure and the shminfo structure.
  132.  
  133. To finish filling in the shminfo structure, you need to decide how you want
  134. the server to attach to the shared memory segment, and set the "readOnly"
  135. field as follows.  Normally, you would code:
  136.  
  137.     shminfo.readOnly = False;
  138.  
  139. If you set it to True, the server will not be able to write to this
  140. segment, and thus XShmGetImage calls will fail.
  141.  
  142. Finally, tell the server to attach to your shared memory segment with:
  143.  
  144.     Status XShmAttach (display, shminfo);
  145.  
  146. If all goes well, you will get a true status back, and your XImage is ready
  147. for use.
  148.  
  149. To write a shared memory XImage into an X drawable, use XShmPutImage:
  150.  
  151.     Status XShmPutImage (display, d, gc, image, src_x, src_y, 
  152.         dest_x, dest_y, width, height, send_event)
  153.     Display *display;
  154.     Drawable d;
  155.     GC gc;
  156.     XImage *image;
  157.     int src_x, src_y, dest_x, dest_y;
  158.     unsigned int width, height;
  159.     bool send_event;
  160.  
  161. The interface is identical to that of XPutImage, so I will spare my fingers
  162. and not repeat that documentation here.  There is one additional parameter,
  163. however, called "send_event".  If this parameter is passed as True, the
  164. server will generate a "completion" event when the image write is complete;
  165. thus your program can know when it is safe to begin manipulating the shared
  166. memory segment again.
  167.  
  168. The completion event has type XShmCompletionEvent, which is defined as the
  169. following:
  170.  
  171.     typedef struct {
  172.         int    type;            /* of event */
  173.         unsigned long serial;   /* # of last request processed */
  174.         Bool send_event;        /* true if came from a SendEvent request */
  175.         Display *display;        /* Display the event was read from */
  176.         Drawable drawable;        /* drawable of request */
  177.         int major_code;        /* ShmReqCode */
  178.         int minor_code;        /* X_ShmPutImage */
  179.         ShmSeg shmseg;        /* the ShmSeg used in the request */
  180.         unsigned long offset;   /* the offset into ShmSeg used */
  181.     } XShmCompletionEvent;
  182.  
  183. The event type value that will be used can be determined at run time with a
  184. line of the form:
  185.  
  186.     int CompletionType = XShmGetEventBase (display) + ShmCompletion;
  187.  
  188. If you modify the shared memory segment before the arrival of the
  189. completion event, the results you see on the screen may be inconsistent.
  190.  
  191. To read image data into a shared memory XImage, use the following:
  192.  
  193.     Status XShmGetImage (display, d, image, x, y, plane_mask)
  194.     Display *display;
  195.     Drawable d;
  196.     XImage *image;
  197.     int x, y;
  198.     unsigned long plane_mask;
  199.  
  200. Where "display" is the display of interest, "d" is the source drawable,
  201. "image" is the destination XImage, "x" and "y" are the offsets within "d",
  202. and "plane_mask" defines which planes are to be read.
  203.  
  204. To destroy a shared memory XImage, you should first instruct the server to
  205. detach from it, then destroy the segment itself, as follows:
  206.  
  207.     XShmDetach (display, shminfo);
  208.     XDestroyImage (image);
  209.     shmdt (shminfo.shmaddr);
  210.     shmctl (shminfo.shmid, IPC_RMID, 0);
  211.  
  212.  
  213. USE OF SHARED MEMORY PIXMAPS
  214.  
  215. To create a shared memory pixmap, you must create a shared memory segment
  216. and "shminfo" structure in exactly the same way as is listed above for
  217. shared memory XImages.  While it is, as far as I can tell, not strictly
  218. necessary to create an XImage first, doing so incurs little overhead and
  219. will give you an appropriate bytes_per_line value to use.
  220.  
  221. Once you have your shminfo structure filled in, simply call:
  222.  
  223.     Pixmap XShmCreatePixmap (display, d, data, shminfo, width,
  224.             height, depth);
  225.     Display *display;
  226.     Drawable d;
  227.     char *data;
  228.     XShmSegmentInfo *shminfo;
  229.     unsigned int width, height, depth;
  230.  
  231. The arguments are all the same as for XCreatePixmap, with two additions:
  232. "data" and "shminfo".  The second of the two is the same old shminfo
  233. structure that has been used before; the first is the pointer to the shared
  234. memory segment, and should, I believe, be the same as the shminfo.shmaddr
  235. field.  I am not sure why this is a separate parameter.
  236.  
  237. If everything works, you will get back a pixmap, which you can manipulate
  238. in all of the usual ways, with the added bonus of being able to tweak its
  239. contents directly through the shared memory segment.  Shared memory pixmaps
  240. are destroyed in the usual manner with XFreePixmap, though you should
  241. probably detach and destroy the shared memory segment itself as shown
  242. above.
  243.