XReadBitmapFile(XS)      X Version 11 (Release 5)        XReadBitmapFile(XS)
                                6 January 1993


 Name

    XReadBitmapFile - manipulate bitmaps

 Syntax


    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, data, width, height, fg, bg,
                                       depth)
          Display *display;
          Drawable d;
          char *data;
          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;


 Arguments


    bitmap         Specifies the bitmap.

    bitmapreturn  Returns the bitmap that is created.

    d              Specifies the drawable that indicates the screen.

    data           Specifies the data in bitmap format.

    data           Specifies the location of the bitmap data.

    depth          Specifies the depth of the pixmap.

    display        Specifies the connection to the X server.

    fg
    bg             Specify the foreground and background pixel values to use.

    filename       Specifies the file name to use.  The format of the file
                   name is operating-system dependent.

    width
    height         Specify the width and height.

    widthreturn
    heightreturn  Return the width and height values of the read in bitmap
                   file.

    xhot
    yhot          Specify where to place the hotspot coordinates (or -1,-1
                   if none are present) in the file.

    xhotreturn
    yhotreturn   Return the hotspot coordinates.

 Description

    The XReadBitmapFile function reads in a file containing a bitmap.  The
    file is parsed in the encoding of the current locale.  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 allocated, it
    returns BitmapNoMemory.  If the file is readable and valid, it returns
    BitmapSuccess.

    XReadBitmapFile returns the bitmap's height and width, as read from the
    file, to widthreturn and heightreturn.  It then creates a pixmap of the
    appropriate size, reads the bitmap data from the file into the pixmap,
    and assigns the pixmap to the caller's variable bitmap.  The caller must
    free the bitmap using XFreePixmap when finished.  If namexhot and
    nameyhot exist, XReadBitmapFile returns them to xhotreturn and
    yhotreturn; otherwise, it returns -1,-1.

    XReadBitmapFile can generate ``BadAlloc'' and ``BadDrawable'' errors.

    The XWriteBitmapFile function writes a bitmap out to a file in the X ver-
    sion 11 format.  The file is written in the encoding of the current
    locale.  If the file cannot be opened for writing, it returns BitmapOpen-
    Failed.  If insufficient memory is allocated, XWriteBitmapFile returns
    BitmapNoMemory; otherwise, on no error, it returns BitmapSuccess.  If
    xhot and yhot are not -1, -1, XWriteBitmapFile writes them out as the
    hotspot coordinates for the bitmap.

    XWriteBitmapFile can generate ``BadDrawable'' and ``BadMatch'' errors.

    The XCreatePixmapFromBitmapData function creates a pixmap 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.

    XCreatePixmapFromBitmapData can generate ``BadAlloc'' and ``BadMatch''
    errors.

    The XCreateBitmapFromData function allows you to include in your C pro-
    gram (using #include) a bitmap file that was written out by XWriteBitmap-
    File (X version 11 format only) without reading in the bitmap file.  The
    following example creates a gray bitmap:

    #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 responsibility to free the bitmap using
    XFreePixmap when finished.

    XCreateBitmapFromData can generate a ``BadAlloc'' error.

 Diagnostics


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

    ``BadDrawable''
                   A value for a Drawable argument does not name a defined
                   Window or Pixmap.

    ``BadMatch''   An InputOnly window is used as a Drawable.

 See also

    XCreatePixmap(XS), XPutImage(XS)
    Xlib - C Language X Interface