XReadBitmapFile(3X)                           XReadBitmapFile(3X)



NAME
     XReadBitmapFile, XWriteBitmapFile,
     XCreatePixmapFromBitmapData,     XCreateBitmapFromData     -
     manipulate bitmaps

SYNOPSIS
     int XReadBitmapFile (display, d, filename,
     width-return, height-return, bitmap-return, x-hot-return,
     y-hot-return)

     Display *display;
     Drawable d;
     char *filename;
     unsigned int *width-return,*height-return;
     Pixmap *bitmap-return;
     int *x-hot-return, *y-hot-return;

     int XWriteBitmapFile (display, filename, bitmap,
     width, height, x-hot, y-hot)
     Display *display;
     char *filename;
     Pixmap bitmap;
     unsigned int width,height;
     int x-hot, y-hot;

     Pixmap XCreatePixmapFromBitmapData (display, d,
     bdata, width, height, fg, bg, depth)
     Display *display;
     Drawable d;
     char *bdata;
     unsigned int width, height;
     unsigned long fg, bg;
     unsigned int depth;

     Pixmap XCreateBitmapFromData (display, d, data, width,
     height)
     Display *display;
     Drawable d;
     char *data;
     unsigned int width,height;

DESCRIPTION
     The XReadBitmapFile function reads in a file containing a
     bitmap.  The ability to read other than the standard format
     is implementation-dependent.  If the file cannot be opened,
     XReadBitmapFile returns BitmapOpenFailed.  If the file can
     be opened but does not contain valid bitmap data, it returns
     BitmapFileInvalid.  If insufficient working storage is allo-
     cated, it returns BitmapNoMemory.  If the file is readable
     and valid, it returns BitmapSuccess.





November, 1990                                                  1

XReadBitmapFile(3X)                           XReadBitmapFile(3X)



     XReadBitmapFile returns the bitmap's height and width, as
     read from the file, in width-return and height-return.  It
     then creates a pixel map of the appropriate size, reads the
     bitmap data from the file into the pixel map, and assigns
     the pixel map to the caller's variable bitmap. The caller
     must free the bitmap using XFreePixmap when finished.  If
     filename-x-hot and filename-y-hot exist, XReadBitmapFile re-
     turns them in x-hot-return and y-hot-return; otherwise,
     XReadBitmapFile returns -1,-1.

     The XWriteBitmapFile function writes a bitmap out to a file
     in the X version 11 format.  If the file cannot be opened
     for writing, it returns BitmapOpenFailed.  If insufficient
     memory is allocated, XWriteBitmapFile returns Bitmap-
     NoMemory; otherwise, on no error, it returns BitmapSuccess.
     If x-hot and y-hot are not -1, -1, XWriteBitmapFile writes
     them out as the hotspot coordinates for the bitmap.

     The XCreatePixmapFromBitmapData function creates a pixel map
     of the given depth and then does a bitmap-format
     XPutImage of the data into it.  The depth must be supported
     by the screen of the specified drawable, or a BadMatch error
     results.

     The XCreateBitmapFromData function allows you to include in
     your C program a bitmap file that was written out by XWri-
     teBitmapFile (X version 11 format only) without reading in
     the bitmap file.  The following example creates a gray bit-
     map:

        #include "gray.bitmap"
        Pixmap bitmap;
        bitmap = XCreateBitmapFromData(display, window,
                        gray-bits, gray-width, gray-height);

     If insufficient working storage was allocated,
     XCreateBitmapFromData returns None.  It is your responsibil-
     ity to free the bitmap using XFreePixmap when finished.

   Arguments
     These functions accept the following arguments:

     bdata   Specifies the data in bitmap format.

     bitmap  Specifies the bitmap to be written.

     bitmap-return
             Returns the bitmap ID that is created.

     d       Specifies the drawable.

     data    Specifies the location of the bitmap data.



2                                                  November, 1990

XReadBitmapFile(3X)                           XReadBitmapFile(3X)



     depth   Specifies the depth of the pixel map.

     display Specifies the connection to the X server.

     fg, bg  Specify the foreground and background pixel values
             to be used.

     filename
             Specifies the filename to be used.  The format of
             the filename is specific to the operating system.

     width, height
             Specify the width and height.

     width-return, height-return
             Return the width and height values of the read in
             bitmap file.

     x-hot, y-hot
             Specify where to place the hot spot coordinates (or
             -1,-1 if none are present) in the file.

     x-hot-return, y-hot-return
             Return the hot spot coordinates.

ERRORS
     BadAlloc
             The server failed to allocate the requested resource
             or server memory.

     BadDrawable
             A value for a Drawable argument does not name a de-
             fined window or pixel map.

     BadMatch
             An InputOnly window is used as a drawable.

     The XReadBitmapFile function can generate BadAlloc and Bad-
     Drawable errors.

     The XWriteBitmapFile can generate BadDrawable and BadMatch
     errors.

     The XCreatePixmapFromBitmapData function can generate BadAl-
     loc and BadMatch errors.

     The XCreateBitmapFromData function can generate a
     BadAlloc error.

SEE ALSO
     XCreatePixmap(3X), XPutImage(3X)

     Xlib - C Language Interface



November, 1990                                                  3