Museum

 XShm(Xext)        X Version 11 (Release 5) 6 January 1993         XShm(Xext)


 Name

    XShm - shared memory extensions

 Syntax


    #include <X11/Xlib.h>
    #include <sys/ipc.h>
    #include <sys/shm.h>
    #include <X11/extensions/XShm.h>

    Status XShmAttach (display, shminfo)
        Display *display;
        XShmSegmentInfo *shminfo;

    XImage XShmCreateImage (display, visual, depth, format, data, shminfo,
                            width, height)
        Display *display;
        Visual *visual;
        int format;
        char *data;
        XShmSegmentInfo *shminfo;
        unsigned int width, height, depth;

    Pixmap XShmCreatePixmap (display, drawable, data, shminfo, width, height,
                             depth)
        Display *display;
        Drawable drawable;
        char *data;
        XShmSegmentInfo *shminfo;
        unsigned int width, height, depth;

    Status XShmDetach (display, shminfo)
        Display *display;
        XShmSegmentInfo *shminfo;

    int XShmGetEventBase (display)
        Display *display;

    Status XShmGetImage (display, drawable, image, x, y, plane_mask)
        Display *display;
        Drawable drawable;
        XImage *image;
        int x, y;
        unsigned long plane_mask;

    int XShmPixmapFormat (display)
        Display *display;


    Status XShmPutImage (display, drawable, gc, image, src_x, src_y, dest_x,
                         dest_y, width, height, send_event)
        Display *display;
        Drawable drawable;
        GC gc;
        XImage *image;
        int src_x, src_y, dest_x, dest_y;
        unsigned int width, height;
        Boolean send_event;

    Status XShmQueryExtension (display)
        Display *display;

    Status XShmQueryVersion (display, major, minor, pixmaps)
        Display *display;
        int *major, *minor;
        Boolean *pixmaps;


 Arguments


    data         Specifies a pointer to the image data.

    depth        Specifies the depth of the image.

    destx
    desty       Specifies the x and y coordinates, which are relative to the
                 origin of the drawable and are coordinates of the subimage.

    display      Specifies X server connection.

    drawable     Specifies the drawable.

    format       Specifies the format of the image (XYBitmap, XYPixmap, ZPix-
                 map).

    gc           Specifies the GC.

    height       Specifies the height of the image, in pixels.

    image        Specifies the image you want combined with the shape.

    major        Indicates major version number for the shared memory exten-
                 sion.

    minor        Indicates minor version number for the shared memory exten-
                 sion.

    planemask   Indicates which planes are to be read.

    pixmaps      Indicates whether or not shared memory pixmaps are sup-
                 ported.

    sendevent   Indicates whether or not a completion event should occur
                 when the image write is complete.

    shminfo      Specifies a pointer to the XShmSegmentInfo structure.

    srcx        Specifies the offset in X from the left edge of the image
                 defined by the XImage data structure.

    srcy        Specifies the offset in Y from the top edge of the image
                 defined by the XImage data structure.

    visual       Specifies a pointer to the visual.

    width        Specifies the width of the image, in pixels.

 Description

    The XShmPutImage function combines an image in memory with a shape of the
    specified drawable.  If XYBitmap format is used, the depth must be one,
    or a ``BadMatch'' error results.  The foreground pixel in the GC defines
    the source for the one bits in the image, and the background pixel
    defines the source for the zero bits.  For XYPixmap and ZPixmap, the
    depth must match the depth of the drawable, or a ``BadMatch''  error
    results.

    The XShmCreateImage function allocates the memory needed for an XImage
    structure for the specified display but does not allocate space for the
    image itself.

    The XShmGetImage function reads image data into a shared memory XImage
    where display is the display of interest, drawable is the source draw-
    able, image is the destination XImage, x and y are offsets within the
    drawable, and planemask defines which planes are to be read.

    The XShmQueryExtension function checks to see if the shared memory exten-
    sions are available for the specified display.

    The XShmQueryVersion function returns the version numbers of the exten-
    sion implementation.  Shared memory pixmaps are supported if the pixmaps
    argument returns true.

    The XShmAttach function tells the server to attach to your shared memory
    segment.  If all goes well, you will get a non-zero status, back and your
    XImage is ready for use.

    The XShmDetach function tells the server to detach from your shared mem-
    ory segment.

    The XShmPixmapFormat function gets the format for the server.  If your
    application can deal with the server pixmap data format,  a shared memory
    segent and shminfo structure are created.

    The XShmCreatePixmap function points to a pixmap which you can manipulate
    in all of the usual ways, with the added bonus of being able to edit its
    contents directly through the shared memory segment.

    The XShmGetEventBase function gets the completion event value.

 Structures


    typedef struct {
        int type;              /* type of event */
        unsigned long serial;  /* number of last request processed by server */
        Boolean send_event;    /* True if event came from a SendEvent request */
        Display *display;      /* Display the event was read from */
        Drawable drawable;     /* drawable of request */
        int major_code;        /* ShmReqCode */
        int minor_code;        /* X_ShmPutImage */
        ShmSeg shmseg;         /* the ShmSeg used in the request */
        unsigned long offset;  /* the offset into ShmSeg used */
    } XShmCompletionEvent;


 See also

    Xlib - C Language X Interface