Warning: when using truecolor images, you should always set the graphics mode before loading any bitmap data! Otherwise the pixel format (RGB or BGR) will not be known, so the file may be converted wrongly.
BITMAP *load_bitmap(char *filename, RGB *pal);
Loads a bitmap from a file, returning a pointer to a bitmap and storing
the palette data in the specified location, which should be an array of
256 RGB structures. You are responsible for destroying the bitmap when
you are finished with it. Returns NULL on error. At present this function
supports BMP, LBM, PCX, and TGA files, determining the type from the file
extension. If the file contains a truecolor image, you must set the video
mode or call set_color_conversion() before loading it.
BITMAP *load_bmp(char *filename, RGB *pal);
Loads a 256 color or 24 bit truecolor Windows or OS/2 BMP file.
BITMAP *load_lbm(char *filename, RGB *pal);
Loads a 256 color IFF ILBM/PBM file.
BITMAP *load_pcx(char *filename, RGB *pal);
Loads a 256 color or 24 bit truecolor PCX file.
BITMAP *load_tga(char *filename, RGB *pal);
Loads a 256 color, 15 bit hicolor, 24 bit truecolor, or 32 bit
truecolor+alpha TGA file.
int save_bitmap(char *filename, BITMAP *bmp, RGB *pal);
Writes a bitmap into a file, using the specified palette, which should be
an array of 256 RGB structures. Returns non-zero on error. The output
format is determined from the filename extension: at present this
function supports BMP, PCX and TGA formats. One thing to watch out for:
if you use this to dump the screen into a file you may end up with an
image much larger than you were expecting, because Allegro often creates
virtual screens larger than the visible screen. You can get around this
by using a sub-bitmap to specify which part of the screen to save, eg:
BITMAP *bmp;
PALETTE pal;
get_palette(pal);
bmp = create_sub_bitmap(screen, 0, 0, SCREEN_W, SCREEN_H);
save_bitmap("dump.pcx", bmp, pal);
destroy_bitmap(bmp);
int save_bmp(char *filename, BITMAP *bmp, RGB *pal);
int save_pcx(char *filename, BITMAP *bmp, RGB *pal);
Writes a bitmap into a 256 color or 24 bit truecolor PCX file.
int save_tga(char *filename, BITMAP *bmp, RGB *pal);
Writes a bitmap into a 256 color, 15 bit hicolor, 24 bit truecolor, or 32
bit truecolor+alpha TGA file.
void register_bitmap_file_type(char *ext,
BITMAP *(*load)(char *filename, RGB *pal),
int (*save)(char *filename, BITMAP *bmp, RGB *pal));
Informs the load_bitmap() and save_bitmap() functions of a new file type,
providing routines to read and write images in this format (either
function may be NULL).
void set_color_conversion(int mode);
Specifies how to convert images between the various color depths when
reading graphics from external bitmap files or datafiles. The mode is a
bitmask specifying which types of conversion are allowed. If the
appropriate bit is set, data will be converted into the current pixel
format (selected by calling the set_color_depth() function), otherwise it
will be left in the same format as the disk file, leaving you to convert
it manually before the graphic can be displayed. The default mode is
total conversion, so that all images will be loaded in the appropriate
format for the current video mode. Valid bit flags are:
COLORCONV_NONE // disable all format conversions
COLORCONV_8_TO_15 // expand 8 bits to 15 bits
COLORCONV_8_TO_16 // expand 8 bits to 16 bits
COLORCONV_8_TO_24 // expand 8 bits to 24 bits
COLORCONV_8_TO_32 // expand 8 bits to 32 bits
COLORCONV_15_TO_8 // reduce 15 bits to 8 bits
COLORCONV_15_TO_16 // expand 15 bits to 16 bits
COLORCONV_15_TO_24 // expand 15 bits to 24 bits
COLORCONV_15_TO_32 // expand 15 bits to 32 bits
COLORCONV_16_TO_8 // reduce 16 bits to 8 bits
COLORCONV_16_TO_15 // reduce 16 bits to 15 bits
COLORCONV_16_TO_24 // expand 16 bits to 24 bits
COLORCONV_16_TO_32 // expand 16 bits to 32 bits
COLORCONV_24_TO_8 // reduce 24 bits to 8 bits
COLORCONV_24_TO_15 // reduce 24 bits to 15 bits
COLORCONV_24_TO_16 // reduce 24 bits to 16 bits
COLORCONV_24_TO_32 // expand 24 bits to 32 bits
COLORCONV_32_TO_8 // reduce 32 bit RGB to 8 bits
COLORCONV_32_TO_15 // reduce 32 bit RGB to 15 bits
COLORCONV_32_TO_16 // reduce 32 bit RGB to 16 bits
COLORCONV_32_TO_24 // reduce 32 bit RGB to 24 bits
COLORCONV_32A_TO_8 // reduce 32 bit RGBA to 8 bits
COLORCONV_32A_TO_15 // reduce 32 bit RGBA to 15 bits
COLORCONV_32A_TO_16 // reduce 32 bit RGBA to 16 bits
COLORCONV_32A_TO_24 // reduce 32 bit RGBA to 24 bits
COLORCONV_DITHER_PAL // dither when reducing to 8 bit
COLORCONV_DITHER_HI // dither when reducing to hicolor
For convenience, the following macros can be used to select common
combinations of these flags:
COLORCONV_EXPAND_256 // expand 256 colors to hi/truecolor
COLORCONV_REDUCE_TO_256 // reduce hi/truecolor to 256 colors
COLORCONV_EXPAND_15_TO_16 // expand 15 bit hicolor to 16 bits
COLORCONV_REDUCE_16_TO_15 // reduce 16 bit hicolor to 15 bits
COLORCONV_EXPAND_HI_TO_TRUE // expand 15/16 bits to 24/32 bits
COLORCONV_REDUCE_TRUE_TO_HI // reduce 24/32 bits to 15/16 bits
COLORCONV_24_EQUALS_32 // convert between 24 and 32 bits
COLORCONV_TOTAL // everything to current format
COLORCONV_PARTIAL // convert 15 <-> 16 and 24 <-> 32
COLORCONV_MOST // all but hi/truecolor <-> 256
COLORCONV_DITHER // dither during all color reductions
If you enable the COLORCONV_DITHER flag, dithering will be performed
whenever truecolor graphics are converted into a hicolor or paletted
format, including by the blit() function, and any automatic conversions
that take place while reading graphics from disk. This can produce much
better looking results, but is obviously slower than a direct conversion.