XCreateImage(3X)                                 XCreateImage(3X)



NAME
     XCreateImage, XGetPixel, XPutPixel, XSubImage, XAddPixel,
     XDestroyImage - create and manage image structures

SYNOPSIS
     XImage *XCreateImage (display, visual, depth, format,
     offset, data, width, height, bitmap-pad, bytes-per-line)
     Display *display;
     Visual *visual;
     unsigned int depth;
     int format;
     int offset;
     char *data;
     unsigned int width;
     unsigned int height;
     int bitmap-pad;
     int bytes-per-line;

     unsigned long XGetPixel (ximage, x, y)
     XImage *ximage;
     int x;
     int y;

     int XPutPixel (ximage, x, y,pixel)
     XImage *ximage;
     int x;
     int y;
     unsigned long pixel;

     XImage *XSubImage (ximage, x, y, subimage-width,
     subimage-height)
     XImage *ximage;
     int x;
     int y;
     unsigned int subimage-width;
     unsigned int subimage-height;

     int XAddPixel (ximage, value)
     XImage *ximage;
     int value;

     int DestroyImage (ximage)
     XImage *ximage;

DESCRIPTION
     The XCreateImage function allocates the memory needed for an
     XImage structure for the specified display but does not al-
     locate space for the image itself.  Rather, it initializes
     the structure byte-order, bit-order, and bitmap-unit values
     from the display and returns a pointer to the XImage struc-
     ture.  The red, green, and blue mask values are defined for
     Z format images only and are derived from the Visual struc-



November, 1990                                                  1

XCreateImage(3X)                                 XCreateImage(3X)



     ture passed in.  Other values also are passed in.  The
     offset argument permits the rapid displaying of the image
     without requiring each scanline to be shifted into position.
     If you pass 0 in bytes-per-line, Xlib assumes that the scan-
     lines are contiguous in memory and calculates the value of
     bytes-per-line itself.

     Note that when the image is created using XCreateImage,
     XGetImage, or XSubImage, the destroy procedure that the
     XDestroyImage function calls frees both the image structure
     and the data pointed to by the image structure.

     The basic functions used to get a pixel, set a pixel, create
     a subimage, and add a constant offset to a Z format image
     are defined in the image object.  The functions in this sec-
     tion are really macro invocations of the functions in the
     image object and are defined in <X11/Xutil.h>.

     The XGetPixel function returns the specified pixel from the
     named image. The pixel value is returned in normalized for-
     mat (that is, the least-significant byte of the long is the
     least-significant byte of the pixel). The image must contain
     the x and y coordinates.

     The XPutPixel function overwrites the pixel in the named im-
     age with the specified pixel value.  The input pixel value
     must be in normalized format (that is, the least-significant
     byte of the long is the least-significant byte of the pix-
     el).  The image must contain the x and y coordinates.

     The XSubImage function creates a new image that is a subsec-
     tion of an existing one.  It allocates the memory necessary
     for the XImage structure and returns a pointer to the new
     image. The data is copied from the source image, and the im-
     age must contain the rectangle defined by x, y, subimage-
     width, and subimage-height.

     The XAddPixel function adds a constant value to every pixel
     in an image.  It is useful when you have a base pixel value
     from allocating color resources and need to manipulate the
     image to that form.

     The XDestroyImage function deallocates the memory associated
     with the XImage structure.

   Arguments
     These functions accept the following arguments:

     bytes-per-line
             Specifies the number of bytes in the client image
             between the start of one scanline and the start of
             the next.  If you pass a zero value, Xlib assumes



2                                                  November, 1990

XCreateImage(3X)                                 XCreateImage(3X)



             that the scanlines are contiguous in memory and cal-
             culates the value of bytes-per-line itself.

     data    Specifies a pointer to the image data.

     depth   Specifies the depth of the image.

     display Specifies the connection to the X server.

     format  Specifies the format for the image.  One of the fol-
             lowing constants can be passed:  XYBitmap, XYPixmap,
             or ZPixmap.

     height  Specifies the height (in pixels) of the image.

     offset  Specifies the number of pixels to ignore at the be-
             ginning of the scanline.  This permits the rapid
             displaying of the image without requiring each scan-
             line to be shifted into position.

     pixel   Specifies the new pixel value.

     subimage-height
             Specifies the height (in pixels) of the new subim-
             age.

     subimage-width
             Specifies the width (in pixels) of the new subimage.

     value   Specifies the constant value to be added.

     visual  Specifies a pointer to the visual.

     width   Specifies the width (in pixels) of the image.

     ximage  Specifies a pointer to the image.

     bitmap-pad
             Specifies the quantum of a scanline.  In other
             words, the start of one scanline is separated in
             client memory from the start of the next scanline by
             an integer multiple of this many bits.  You must
             pass one of these values: 8, 16, or 32.

     x, y    Specify the x and y coordinates.

SEE ALSO
     XPutImage(3X)

     Xlib - C Language Interface






November, 1990                                                  3