home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / extensions / mit-shm.ms < prev    next >
Encoding:
Text File  |  1991-07-30  |  11.7 KB  |  338 lines

  1. .\" Use -ms
  2. .de Cs
  3. .IP
  4. .nf
  5. .ft C
  6. ..
  7. .de Ce
  8. .ft P
  9. .fi
  10. ..
  11. .de Bu
  12. .br
  13. .ti +.5i
  14. .ie \\n(.$ \\$1
  15. .el \\(bu
  16. ..
  17. .EH ''''
  18. .OH ''''
  19. .EF ''''
  20. .OF ''''
  21. .ps 10
  22. .nr PS 10
  23. \&
  24. .TL
  25. \s+2\fBMIT-SHM\(emThe MIT Shared Memory Extension\fP\s-2
  26. .sp
  27. How the shared memory extension works
  28. .AU
  29. Jonathan Corbet
  30. .AI
  31. Atmospheric Technology Division
  32. National Center for Atmospheric Research
  33. corbet@ncar.ucar.edu
  34. .sp
  35. Formatted and edited for release 5 by
  36. .AU
  37. Keith Packard
  38. .AI
  39. MIT X Consortium
  40. .ps 9
  41. .nr PS 9
  42. .sp 8
  43. .AB
  44. This document briefly describes how to use the MIT-SHM shared memory
  45. extension.  I have tried to make it accurate, but it would not surprise me
  46. if some errors remained.  If you find anything wrong, do let me know and I
  47. will incorporate the corrections.  Meanwhile, please take this document ``as
  48. is''\(eman improvement over what was there before, but certainly not the
  49. definitive word.
  50. .AE
  51. .LP
  52. .DS C
  53. Copyright \(co 1991 by the Massachusetts Institute of Technology
  54. .DE
  55. .sp 2
  56. .LP
  57. Permission to use, copy, modify, and distribute this documentation for any
  58. purpose and without fee is hereby granted, provided that the above copyright
  59. notice and this permission notice appear in all copies.  MIT makes no
  60. representations about the suitability for any purpose of the information in
  61. this document.  This documentation is provided ``as is'' without express or
  62. implied warranty.
  63. .ps 10
  64. .nr PS 10
  65. .bp 1
  66. .de PT
  67. .tl ''MIT Shared Memory Extension''
  68. ..
  69. .de BT
  70. .tl ''\fB % \fP''
  71. ..
  72. .NH 1
  73. REQUIREMENTS
  74. .LP
  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. .NH 1
  85. WHAT IS PROVIDED
  86. .LP
  87. The basic capability provided is that of shared memory XImages.  This is
  88. essentially a version of the ximage interface where the actual image data
  89. is stored in a shared memory segment, and thus need not be moved through
  90. the Xlib interprocess communication channel.  For large images, use of this
  91. facility can result in some real performance increases.
  92. .LP
  93. Additionally, some implementations provided shared memory pixmaps.  These
  94. are 2 dimensional arrays of pixels in a format specified by the X server,
  95. where the image data is stored in the shared memory segment.  Through use of
  96. shared memory pixmaps, it is possible to change the contents of these
  97. pixmaps without using any Xlib routines at all.  Shared memory pixmaps can
  98. only be supported when the X server can use regular virtual memory for
  99. pixmap data; if the pixmaps are stored in some magic graphics hardware, your
  100. application will not be able to share them with the server.  Xdpyinfo(1)
  101. doesn't print this particular nugget of information.
  102. .NH 1
  103. HOW TO USE THE SHARED MEMORY EXTENSION
  104. .LP
  105. Code which uses the shared memory extension must include a number of header
  106. files:
  107. .Cs
  108. # include <X11/Xlib.h>        /* of course */
  109. # include <sys/ipc.h>
  110. # include <sys/shm.h>
  111. # include <X11/extensions/XShm.h>
  112. .Ce
  113. .LP
  114. Of course, if the system you are building on does not support shared
  115. memory, the file XShm.h may not be present.  You may want to make
  116. liberal use of #ifdefs.
  117. .LP
  118. Any code which uses the shared memory extension should first check to see
  119. that the server provides the extension.  You could always be running over
  120. the net, or in some other environment where the extension will not work.
  121. To perform this check, call either
  122. .Cs
  123. Status XShmQueryExtension (display)
  124.         Display *display
  125. .Ce
  126. .LP
  127. or
  128. .Cs
  129. Status XShmQueryVersion (display, major, minor, pixmaps)
  130.         Display *display;
  131.         int *major, *minor;
  132.         Bool *pixmaps
  133. .Ce
  134. .LP
  135. Where ``display'' is, of course, the display on which you are running.  If
  136. the shared memory extension may be used, the return value from either
  137. function will be True; otherwise your program should operate using
  138. conventional Xlib calls.  When the extension is available,
  139. \fCXShmQueryVersion\fP also returns ``major'' and ``minor'' which are the
  140. version numbers of the extension implementation, and ``pixmaps'' which is
  141. True iff shared memory pixmaps are supported.
  142. .NH 1
  143. USE OF SHARED MEMORY XIMAGES
  144. .LP
  145. The basic sequence of operations for shared memory XImages is as follows:
  146. .LP
  147. .Bu "1 \-"
  148. Create the shared memory XImage structure
  149. .Bu "2 \-"
  150. Create a shared memory segment to store the image data
  151. .Bu "3 \-"
  152. Inform the server about the shared memory segment
  153. .Bu "4 \-"
  154. Use the shared memory XImage, much like a normal one.
  155. .LP
  156. To create a shared memory XImage, use:
  157. .Cs
  158. XImage *XShmCreateImage (display, visual, depth, format, data, 
  159.                          shminfo, width, height)
  160.         Display *display;
  161.         Visual *visual;
  162.         unsigned int depth, width, height;
  163.         int format;
  164.         char *data;
  165.         XShmSegmentInfo *shminfo;
  166. .Ce
  167. .LP
  168. Most of the arguments are the same as for XCreateImage; I will not go
  169. through them here.  Note, however, that there are no ``offset'', ``bitmap_pad'',
  170. or ``bytes_per_line'' arguments.  These quantities will be defined by the
  171. server itself, and your code needs to abide by them.  Unless you have already
  172. allocated the shared memory segment (see below), you should pass in NULL for
  173. the ``data'' pointer.
  174. .LP
  175. There is one additional argument: ``shminfo'', which is a pointer to a
  176. structure of type XShmSegmentInfo.  You must allocate one of these
  177. structures such that it will have a lifetime at least as long as that of
  178. the shared memory XImage.  There is no need to initialize this structure
  179. before the call to XShmCreateImage.
  180. .LP
  181. The return value, if all goes well, will be an XImage structure, which you
  182. can use for the subsequent steps.
  183. .LP
  184. The next step is to create the shared memory segment.  This is
  185. best done after the creation of the XImage, since you need to make use of
  186. the information in that XImage to know how much memory to allocate.  To
  187. create the segment, you need a call like:
  188. .Cs
  189. shminfo.shmid = shmget (IPC_PRIVATE,
  190.         image->bytes_per_line * image->height, IPC_CREAT|0777);
  191. .Ce
  192. .LP
  193. (assuming that you have called your shared memory XImage ``image'').  You
  194. should, of course, follow the Rules and do error checking on all of these
  195. system calls.  Also, be sure to use the bytes_per_line field, not the width
  196. you used to create the XImage as they may well be different.
  197. .LP
  198. Note that the shared memory ID returned by the system is stored in the
  199. shminfo structure.  The server will need that ID to attach itself to the
  200. segment.
  201. .LP
  202. Next, attach this shared memory segment to your process:
  203. .Cs
  204. shminfo.shmaddr = image->data = shmat (shminfo.shmid, 0, 0);
  205. .Ce
  206. .LP
  207. The address returned by shmat should be stored in *both* the XImage
  208. structure and the shminfo structure.
  209. .LP
  210. To finish filling in the shminfo structure, you need to decide how you want
  211. the server to attach to the shared memory segment, and set the ``readOnly''
  212. field as follows.  Normally, you would code:
  213. .Cs
  214. shminfo.readOnly = False;
  215. .Ce
  216. .LP
  217. If you set it to True, the server will not be able to write to this
  218. segment, and thus XShmGetImage calls will fail.
  219. .LP
  220. Finally, tell the server to attach to your shared memory segment with:
  221. .Cs
  222. Status XShmAttach (display, shminfo);
  223. .Ce
  224. .LP
  225. If all goes well, you will get a non-zero status back, and your XImage is
  226. ready for use.
  227. .LP
  228. To write a shared memory XImage into an X drawable, use XShmPutImage:
  229. .Cs
  230. Status XShmPutImage (display, d, gc, image, src_x, src_y, 
  231.                      dest_x, dest_y, width, height, send_event)
  232.         Display *display;
  233.         Drawable d;
  234.         GC gc;
  235.         XImage *image;
  236.         int src_x, src_y, dest_x, dest_y;
  237.         unsigned int width, height;
  238.         bool send_event;
  239. .Ce
  240. .LP
  241. The interface is identical to that of XPutImage, so I will spare my fingers
  242. and not repeat that documentation here.  There is one additional parameter,
  243. however, called ``send_event''.  If this parameter is passed as True, the
  244. server will generate a ``completion'' event when the image write is complete;
  245. thus your program can know when it is safe to begin manipulating the shared
  246. memory segment again.
  247. .LP
  248. The completion event has type XShmCompletionEvent, which is defined as the
  249. following:
  250. .Cs
  251. typedef struct {
  252.     int    type;            /* of event */
  253.     unsigned long serial;   /* # of last request processed */
  254.     Bool send_event;        /* true if came from a SendEvent request */
  255.     Display *display;        /* Display the event was read from */
  256.     Drawable drawable;        /* drawable of request */
  257.     int major_code;        /* ShmReqCode */
  258.     int minor_code;        /* X_ShmPutImage */
  259.     ShmSeg shmseg;        /* the ShmSeg used in the request */
  260.     unsigned long offset;   /* the offset into ShmSeg used */
  261. } XShmCompletionEvent;
  262. .Ce
  263. .LP
  264. The event type value that will be used can be determined at run time with a
  265. line of the form:
  266. .Cs
  267. int CompletionType = XShmGetEventBase (display) + ShmCompletion;
  268. .Ce
  269. .LP
  270. If you modify the shared memory segment before the arrival of the
  271. completion event, the results you see on the screen may be inconsistent.
  272. .LP
  273. To read image data into a shared memory XImage, use the following:
  274. .Cs
  275. Status XShmGetImage (display, d, image, x, y, plane_mask)
  276.     Display *display;
  277.     Drawable d;
  278.     XImage *image;
  279.     int x, y;
  280.     unsigned long plane_mask;
  281. .Ce
  282. .LP
  283. Where ``display'' is the display of interest, ``d'' is the source drawable,
  284. ``image'' is the destination XImage, ``x'' and ``y'' are the offsets within
  285. ``d'', and ``plane_mask'' defines which planes are to be read.
  286. .LP
  287. To destroy a shared memory XImage, you should first instruct the server to
  288. detach from it, then destroy the segment itself, as follows:
  289. .Cs
  290. XShmDetach (display, shminfo);
  291. XDestroyImage (image);
  292. shmdt (shminfo.shmaddr);
  293. shmctl (shminfo.shmid, IPC_RMID, 0);
  294. .Ce
  295. .NH 1
  296. USE OF SHARED MEMORY PIXMAPS
  297. .LP
  298. Unlike X images, for which any image format is usable, the shared memory
  299. extension supports only a single format (i.e. XYPixmap or ZPixmap) for the
  300. data stored in a shared memory pixmap.  This format is independent of the
  301. depth of the image (for 1-bit pixmaps it doesn't really matter what this
  302. format is) and independent of the screen.  Use XShmPixmapFormat to get the
  303. format for the server:
  304. .Cs
  305. int XShmPixmapFormat (display)
  306.         Display *display;
  307. .Ce
  308. .LP
  309. If your application can deal with the server pixmap data format (including
  310. bits-per-pixel et al.), create a shared memory segment and ``shminfo''
  311. structure in exactly the same way as is listed above for shared memory
  312. XImages.  While it is, not strictly necessary to create an XImage first,
  313. doing so incurs little overhead and will give you an appropriate
  314. bytes_per_line value to use.
  315. .LP
  316. Once you have your shminfo structure filled in, simply call:
  317. .Cs
  318. Pixmap XShmCreatePixmap (display, d, data, shminfo, width,
  319.                          height, depth);
  320.         Display *display;
  321.         Drawable d;
  322.         char *data;
  323.         XShmSegmentInfo *shminfo;
  324.         unsigned int width, height, depth;
  325. .Ce
  326. .LP
  327. The arguments are all the same as for XCreatePixmap, with two additions:
  328. ``data'' and ``shminfo''.  The second of the two is the same old shminfo
  329. structure that has been used before.  The first is the pointer to the shared
  330. memory segment, and should be the same as the shminfo.shmaddr field.  I am
  331. not sure why this is a separate parameter.
  332. .LP
  333. If everything works, you will get back a pixmap, which you can manipulate in
  334. all of the usual ways, with the added bonus of being able to tweak its
  335. contents directly through the shared memory segment.  Shared memory pixmaps
  336. are destroyed in the usual manner with XFreePixmap, though you should detach
  337. and destroy the shared memory segment itself as shown above.
  338.