Images

OBJECTS

  typedef imagedata *       image;
  typedef struct imagedata  imagedata;

  struct imagedata {
    int    depth;	/* depth will be 8 or 32 */
    int    width;	/* image width in pixels */
    int    height;	/* image height in pixels */
    int    cmapsize;	/* size of cmap array, may be zero */
    rgb *  cmap;	/* an array of rgb, may be null */
    byte * pixels;	/* an array of bytes or rgb values */
  };

FUNCTIONS

  image   newimage(int width, int height, int depth);
  image   copyimage(image img);			/* create new copy */
  image   loadimage(char *filename);		/* load image file */
  void    saveimage(image img, char *filename);	/* save to file */
  void    del(image img);			/* destroy image */

  void    setpalette(image img, int length, rgb cmap[]);
  void    setpixels(image img, byte pixels[]);

  rect    getrect(image img);		/* size of image */
  int     getdepth(image img);		/* 8 (uses palette) or 32 */
  int     getwidth(image img);		/* pixel width of image */
  int     getheight(image img);		/* pixel height of image */
  int     getpalettesize(image img);	/* cmap size */
  rgb *   getpalette(image img);	/* cmap is array of rgb */
  byte *  getpixels(image img);		/* array of byte or rgb */

  image   scaleimage(image img, rect dr, rect sr);	/* crop/scale image */
  image   convert32to8(image img);	/* return new 8-bit image */
  image   convert8to32(image img);	/* return new 32-bit image */
  void    sortpalette(image img);	/* optimise existing image */

  void    drawimage(image img, rect dr, rect sr);	/* draw image */
  void    drawmonochrome(image img, rect dr, rect sr);	/* black and white */
  void    drawgreyscale(image img, rect dr, rect sr);	/* draw 'greyed' */
  void    drawgrayscale(image img, rect dr, rect sr);	/* draw 'grayed' */
  void    drawdarker(image img, rect dr, rect sr);	/* draw 'darkened' */
  void    drawbrighter(image img, rect dr, rect sr);	/* draw 'brightened' */

NOTES

An image is a platform-independent representation of a picture. It is a more general representation than a bitmap, but a bitmap is much faster to copy onto the screen. For this reason, images and bitmaps are often used in conjunction to produce good effects. (Unlike a bitmap, you cannot draw into an image using the drawing operations. Copy the image into a bitmap first if you wish to draw onto it.)

The newimage function allocates memory for an image of the given width, height and depth. The depth paramater can only be 8 or 32. All other image depths are deliberately not supported. The function returns NULL if there is insufficient memory to create the pixel array.

An image of depth 8 uses the cmap array to store a colour palette. The pixels array will be an array of (width * height) bytes, each byte an index into the cmap palette. By contrast, an image of depth 32 will have no cmap table, cmapsize will be zero and the pixels array will instead point to (width * height) rgb values.

An image can store transparency information, either using a Transparent entry in the colour palette of an 8-bit image, or by having Transparent pixels in a 32-bit image.

The copyimage function will make a completely new copy of an image, or return NULL if there is insufficient memory.

The loadimage function will attempt to load an image file into memory, returning NULL on failure. Currently only the GIF file format is supported, and a special C-code compatible image format, suitable for #inclusion into program source code.

The saveimage function saves an image to disk using the given filename. If the filename ends in the letters ".gif", the file will be in GIF format. If it ends with ".h", the file will be stored into a C-code compatible format. Other file formats may be added in future.

The del function deallocates an image from memory. Images can occupy a lot of memory, particularly if they have a large area or are in 32-bit direct-colour format.

The setpalette function can be used to set or change an image's use of colours. This will not change the data in the pixels array, it will simply change what the pixel values in an 8-bit image mean. This function will have no effect on a 32-bit image.

Use of setpixels will change the data within an image. The pixels array parameter must be an array of (width * height) bytes or rgb values, depending on whether it is an 8-bit or 32-bit image respectively.

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

The getdepth function returns the depth of the image. It will either by 8 or 32.

Use getwidth or getheight to find the dimensions of an image in pixels.

The getpalettesize function will return the number of entries in an image's colour palette, which will be zero if the image has a depth of 32 bits. The getpalette function returns the colour palette from an image. It will be an array of cmapsize rgb values.

Use getpixels to obtain a pointer to the actual pixels used in an image. There is no need to free any array returned by getpixels or by getpalette; these functions simply return the actual pointers in a convenient fashion.

The scaleimage function produces a new image which is cropped and/or scaled. The pixels from the source image which correspond to the source rectangle sr are scaled to fit the destination rectangle dr. The resultant image will have the same width and height as the destination rectangle. The x and y values from the destination rectangle are ignored.

The convert32to8 function creates a new 8-bit image from a 32-bit image, or returns NULL if there is insufficient memory. It tries a fast conversion algorithm first, and resorts to a slower algorithm if that doesn't work.

The convert8to32 function creates a new 32-bit image from an 8-bit image, or returns NULL if there is not enough memory. It uses a very fast, simple algorithm.

The sortpalette function modifies an existing 8-bit image to optimise its colour palette so that redundant entries are discarded, and the most common colours are placed at the top of the palette. This may change the cmapsize and cmap fields in the image. This function has no effect on 32-bit images.

Use drawimage to draw an image into the given rectangle on the current destination drawing. If the destination rectangle is smaller or larger than the source rectangle, the source pixels will be scaled to fit.

The drawmonochrome function draws an image so that it appears black and white. The drawgreyscale function draws an image in five levels of grey, and is exactly the same as drawgrayscale. This can be used to provide a 'disabled button' effect. By constrast, drawdarker draws an image so that it looks darkened, as if seen through dark glass. This can be used to provided a 'clicked button' effect. The drawbrighter function draws a lighter image.