next up previous contents
Next: Regions Up: Miscellaneous Routines Previous: Keyboard Control


A display may support multiple screens, each having several different visual types supported at different depths. To cope with this, the following routines and structures are used.

typedef struct {                 /*       MASKS                 */
  Visual *visual;                /*    VisualNoMask             */
  VisualID visualid;             /*    VisualIDMask             */
  int screen;                    /*    VisualScreenMask         */
  int depth;                     /*    VisualDepthMask          */
  int class;                     /*    VisualClassMask          */
  int red_mask;                  /*    VisualRedMaskMask        */
  int green_mask;                /*    VisualGreenMaskMask      */
  int blue_mask;                 /*    VisualBlueMaskMask       */
  int colormap_size;             /*    VisualColormapSizeMask   */
  int bits_per_rgb;              /*    VisualBitsPerRGBMask     */
} XVisualInfo;                   /*    VisualAllMask            */

typedef struct _XImage {
    int width, height;          /* size of image */
    int xoffset;                /* number of pixels offset in X direction */
    int format;                 /* Bitmap, XYPixmap, ZPixmap */
    char *data;                 /* pointer to image data */
    int byte_order;             /* data byte order, LSBFirst, MSBFirst */
    int bitmap_unit;            /* quant. of scanline 8, 16, 32 */
    int bitmap_bit_order;       /* LeastSignificant, MostSignificant */
    int bitmap_pad;             /* 8, 16, 32 either XY or ZFormat */
    int depth;                  /* depth of image */
    int bytes_per_line;         /* accelarator to next line */
    int bits_per_pixel;         /* bits per pixel (ZFormat) */
    unsigned long red_mask;     /* bits in Z arrangment */
    unsigned long green_mask;
    unsigned long blue_mask;
    char *obdata;               /* hook for the object routines to hang on */
    struct funcs {              /* image manipulation routines */
        struct _XImage *(*create_image)();
        int (*destroy_image)();        
        unsigned long (*get_pixel)();  
        int (*put_pixel)();            
        struct _XImage *(*sub_image)();
        int (*add_pixel)();
        } f;
} XImage;
Drawables are stored in the server. An image is stored on the client machine. The XImage structure contains all the data corresponding to the drawable. Once you know the format of the data within the image, you can manipulate the data using bit-arithmetic.

There is a standard format for coding bitmap data which is used in some of the routines which follow. The bits are stored in scan-line order starting at the top left hand corner bit which is stored in the least significant position in the first memory word being used. Each line begins on a 16 bit boundary and is padded to a 16 bit boundary at the right hand end. The lines follow each other from top to bottom.

There are two standard formats for pixmaps, XY and Z. In XY format the bitmaps in the pixmap occur one after another with the most significant bit plane first. In Z format the pixels are stored individually and come in the same order as the bits in a bitmap. If the hardware supports 2 to 8 bit planes then each pixel is stored in one byte; if the hardware is 9 to 16 planes the pixels have a 16 bit word each. Z format may not be used with black and white display hardware.

   To create an XImage structure use
XImage *XCreateImage(display,visual,depth,format,offset,data,width,height,
   int xpad; /*8, 16, 32 */
   char * data;
   int bytes_per_line; /* if 0, then data assumed contiguous */
To fill this image with data, use
XImage *XGetImage(display,d,x,y,width,height,plane_mask,format);
   XImage *image;
   int src_x,src_y; /* offset from top-left of image */
To combine an image in memory with a rectangle of a drawable on your display, use
   XImage *image;
   int src_x,src_y; /* offset from top-left of image */
To copy part of an existing image to a new one and create an XImage, use
XImage *XSubImage(ximage,x,y,width,height)
You can manipulate the data directly or use
long XGetPixel(ximage,x,y)
int XPutPixel(ximage,x,y,pixel)
int XAddPixel(ximage, value) /* This adds (int) value to each pixel*/

Tim Love
Mon Mar 11 17:03:18 GMT 1996