Bitmaps

OBJECTS

  typedef drawing  bitmap;

FUNCTIONS

  bitmap newbitmap(int width, int height, int depth);
  bitmap imagetobitmap(image img);
  bitmap loadbitmap(char *name);
  bitmap createbitmap(int width, int height, int depth, byte data[]);
  void   del(bitmap b);

  rect   getrect(bitmap b);			/* size of bitmap */
  int    getwidth(bitmap b);			/* pixel width */
  int    getheight(bitmap b);			/* pixel height */
  int    getdepth(bitmap b);			/* bit-depth */

  void   setbitmapdata(bitmap b, byte data[]);	/* change bitmap */
  void   getbitmapdata(bitmap b, byte data[]);	/* peek into bitmap */

NOTES

A bitmap holds a rectangular pixel-image in offscreen memory. Bitmaps are very fast to copy to the screen are used to store prepared images for quick display. A bitmap is also a drawing which means that a bitmap can be drawn into, and also used as a source of pixels.

The newbitmap function creates and returns a white-filled bitmap with the specified pixel width and height. A bitmap always has a zero origin in its top-left corner. The depth specified in the function call determines how many bits-per-pixel the image is to store. A depth of 1 is a black and white bitmap. Depths of 2, 4, 8, 16 and 32 are other possiblities, but these may exceed the screen depth. Specifying a depth of zero will create a bitmap with the same depth as the screen. The function returns NULL if it cannot succeed.

The imagetobitmap function creates a new bitmap which contains the data from the image. It uses the current drawing destination when deciding how to map the image's colours onto pixel values in the bitmap. This function is efficient, but does no dithering. Transparent pixels in the source image are mapped to the background colour of the current drawing destination.

The loadbitmap function will attempt to load a bitmap from a file, or from the application's resources. It will return NULL if it cannot do so.

The createbitmap function will create a bitmap which will be filled with the data contained in the array specified. The arrangement of bits in the data array is platform specific, however it is guaranteed that the number of bits in each row of data is rounded up to the nearest whole byte, and that for black and white bitmaps, a zero bit represents black and a one bit represents white. The function returns NULL if it fails. (Note that images provide a better way of storing bitmap data.)

The del function releases the memory used by a bitmap.

The getrect function returns a rectangle representing the size of the specified bitmap. The x and y co-ordinates will contain zero, but the width and height co-ordinates will contain the width and height of the bitmap.

The getwidth and getheight functions just return the required bitmap dimension in pixels.

The getdepth function returns the depth of the specified bitmap. It will be either 1, 2, 4, 8, 16, 24 or 32.

The setbitmapdata function changes the contents of a bitmap to the data specified, while getbitmapdata extracts information from the bitmap into the supplied array. The arrangement of bits is platform specific, but is the same arrangement as for the createbitmap function.

(NB: in Python, the byte arrays should be replaced by lists of integers, and the getbitmapdata function returns a list instead of requiring one to be passed as a parameter.)