Allegro Manual: Loading image files

# Loading image files

- get_color_conversion — Returns the current color conversion mode.
- load_bitmap — Loads any supported bitmap from a file.
- load_bmp — Loads a BMP bitmap from a file.
- load_bmp_pf — Packfile version of load_bmp.
- load_lbm — Loads an LBM bitmap from a file.
- load_pcx — Loads a PCX bitmap from a file.
- load_pcx_pf — Packfile version of load_pcx.
- load_tga — Loads a TGA bitmap from a file.
- load_tga_pf — Packfile version of load_tga.
- register_bitmap_file_type — Registers custom bitmap loading/saving functions.
- save_bitmap — Saves a bitmap into any supported file format.
- save_bmp — Saves a bitmap into a BMP file.
- save_bmp_pf — Packfile version of save_bmp.
- save_pcx — Saves a bitmap into a PCX file.
- save_pcx_pf — Packfile version of save_pcx.
- save_tga — Saves a bitmap into a TGA file.
- save_tga_pf — Packfile version of save_tga.
- set_color_conversion — Tells Allegro how to convert images during loading time.

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(const char *filename, RGB *pal);
Loads a bitmap from a file. The palette data will be stored in the second parameter, which should be an array of 256 RGB structures. 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. In this case, if the destination color depth is 8-bit, the palette will be generated by calling generate_optimized_palette() on the bitmap; otherwise, the returned palette will be generated by calling generate_332_palette().

The pal argument may be NULL. In this case, the palette data are simply not returned. Additionally, if the file is a truecolor image and the destination color depth is 8-bit, the color conversion process will use the current palette instead of generating an optimized one.

Example:

>           BITMAP *bmp;
>           PALETTE palette;
>           ...
>           bmp = load_bitmap("image.pcx", palette);
>           if (!bmp)
>              abort_on_error("Couldn't load image.pcx!");
>           ...
>           destroy_bitmap(bmp);

Return value: Returns a pointer to the bitmap or NULL on error. Remember that you are responsible for destroying the bitmap when you are finished with it to avoid memory leaks.

> See also: load_bmp, load_lbm, load_pcx, load_tga, destroy_bitmap, save_bitmap, register_bitmap_file_type, set_color_depth, set_color_conversion, generate_optimized_palette, generate_332_palette.

> Examples using this: exaccel, exalpha, exbitmap, exblend, exconfig, exlights, exshade, extrans, exxfade.

BITMAP *load_bmp(const char *filename, RGB *pal);
Loads an 8-bit, 16-bit, 24-bit or 32-bit Windows or OS/2 BMP file.

Return value: Returns a pointer to the bitmap or NULL on error. Remember that you are responsible for destroying the bitmap when you are finished with it to avoid memory leaks.

> See also: load_bitmap, load_bmp_pf.

BITMAP *load_bmp_pf(PACKFILE *f, RGB *pal);
A version of load_bmp() which reads from a packfile. Example:

>           PACKFILE *packfile;
>           BITMAP *bmp;

>           packfile = pack_fopen("mybitmap.bmp", F_READ);
>           if (!packfile)
>              abort_on_error("Couldn't open mybitmap.bmp");

>           bmp = load_bmp_pf(packfile, pal);
>           if (!bmp)
>              abort_on_error("Error loading mybitmap.bmp");

Return value: Returns a pointer to the bitmap or NULL on error. Remember that you are responsible for destroying the bitmap when you are finished with it to avoid memory leaks.

> See also: load_bmp.

> Examples using this: expackf.

BITMAP *load_lbm(const char *filename, RGB *pal);
Loads a 256-color IFF ILBM/PBM file.

Return value: Returns a pointer to the bitmap or NULL on error. Remember that you are responsible for destroying the bitmap when you are finished with it to avoid memory leaks.

> See also: load_bitmap.

BITMAP *load_pcx(const char *filename, RGB *pal);
Loads a 256-color or 24-bit truecolor PCX file.

Return value: Returns a pointer to the bitmap or NULL on error. Remember that you are responsible for destroying the bitmap when you are finished with it to avoid memory leaks.

> See also: load_bitmap.

> Examples using this: expackf, exscale.

BITMAP *load_pcx_pf(PACKFILE *f, RGB *pal);
A version of load_pcx() which reads from a packfile. Example:

>           PACKFILE *packfile;
>           BITMAP *bmp;

>           packfile = pack_fopen("mybitmap.pcx", F_READ);
>           if (!packfile)
>              abort_on_error("Couldn't open mybitmap.pcx");

>           bmp = load_bmp_pf(packfile, pal);
>           if (!bmp)
>              abort_on_error("Error loading mybitmap.pcx");

Return value: Returns a pointer to the bitmap or NULL on error. Remember that you are responsible for destroying the bitmap when you are finished with it to avoid memory leaks.

> See also: load_pcx.

> Examples using this: expackf.

BITMAP *load_tga(const char *filename, RGB *pal);
Loads a 256-color, 15-bit hicolor, 24-bit truecolor, or 32-bit truecolor+alpha TGA file.

Return value: Returns a pointer to the bitmap or NULL on error. Remember that you are responsible for destroying the bitmap when you are finished with it to avoid memory leaks.

> See also: load_bitmap.

BITMAP *load_tga_pf(PACKFILE *f, RGB *pal);
A version of load_tga() which reads from a packfile. Example:

>           PACKFILE *packfile;
>           BITMAP *bmp;

>           packfile = pack_fopen("mybitmap.tga", F_READ);
>           if (!packfile)
>              abort_on_error("Couldn't open mybitmap.tga");

>           bmp = load_bmp_pf(packfile, pal);
>           if (!bmp)
>              abort_on_error("Error loading mybitmap.tga");

Return value: Returns a pointer to the bitmap or NULL on error. Remember that you are responsible for destroying the bitmap when you are finished with it to avoid memory leaks.

> See also: load_tga.

> Examples using this: expackf.

int save_bitmap(const char *filename, BITMAP *bmp, const RGB *pal);
Writes a bitmap into a file, using the specified palette, which should be an array of 256 RGB structures. The output format is determined from the filename extension: at present this function supports BMP, PCX and TGA formats.

Two things to watch out for: on some video cards it may be faster to copy the screen to a memory bitmap and save the latter, and 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);

Return value: Returns non-zero on error.

> See also: save_bmp, save_pcx, save_tga, load_bitmap, register_bitmap_file_type.

int save_bmp(const char *filename, BITMAP *bmp, const RGB *pal);
Writes a bitmap into a 256-color or 24-bit truecolor BMP file.

Return value: Returns non-zero on error.

> See also: save_bitmap.

int save_bmp_pf(PACKFILE *f, BITMAP *bmp, RGB *pal);
A version of save_bmp which writes to a packfile.

> See also: save_bmp.

> Examples using this: expackf.

int save_pcx(const char *filename, BITMAP *bmp, const RGB *pal);
Writes a bitmap into a 256-color or 24-bit truecolor PCX file.

Return value: Returns non-zero on error.

> See also: save_bitmap.

int save_pcx_pf(PACKFILE *f, BITMAP *bmp, RGB *pal);
A version of save_pcx which writes to a packfile.

> See also: save_pcx.

int save_tga(const char *filename, BITMAP *bmp, const RGB *pal);
Writes a bitmap into a 256-color, 15-bit hicolor, 24-bit truecolor, or 32-bit truecolor+alpha TGA file.

Return value: Returns non-zero on error.

> See also: save_bitmap.

int save_tga_pf(PACKFILE *f, BITMAP *bmp, RGB *pal);
A version of save_tga which writes to a packfile.

> See also: save_tga.

> Examples using this: expackf.

void register_bitmap_file_type(const char *ext, BITMAP *(*load)(const char *filename, RGB *pal), int (*save)(const char *filename, BITMAP *bmp, const 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). The functions you supply must follow the same prototype as load_bitmap() and save_bitmap(). Example:

>           BITMAP *load_dump(const char *filename, RGB *pal)
>           {
>              ...
>           }

>           int save_dump(const char *filename, BITMAP *bmp, const RGB *pal)
>           {
>              ...
>           }

>              register_bitmap_file_type("dump", load_dump, save_dump);

> See also: load_bitmap, save_bitmap.

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-bit to 15-bit
>           COLORCONV_8_TO_16             // expand 8-bit to 16-bit
>           COLORCONV_8_TO_24             // expand 8-bit to 24-bit
>           COLORCONV_8_TO_32             // expand 8-bit to 32-bit
>           COLORCONV_15_TO_8             // reduce 15-bit to 8-bit
>           COLORCONV_15_TO_16            // expand 15-bit to 16-bit
>           COLORCONV_15_TO_24            // expand 15-bit to 24-bit
>           COLORCONV_15_TO_32            // expand 15-bit to 32-bit
>           COLORCONV_16_TO_8             // reduce 16-bit to 8-bit
>           COLORCONV_16_TO_15            // reduce 16-bit to 15-bit
>           COLORCONV_16_TO_24            // expand 16-bit to 24-bit
>           COLORCONV_16_TO_32            // expand 16-bit to 32-bit
>           COLORCONV_24_TO_8             // reduce 24-bit to 8-bit
>           COLORCONV_24_TO_15            // reduce 24-bit to 15-bit
>           COLORCONV_24_TO_16            // reduce 24-bit to 16-bit
>           COLORCONV_24_TO_32            // expand 24-bit to 32-bit
>           COLORCONV_32_TO_8             // reduce 32-bit RGB to 8-bit
>           COLORCONV_32_TO_15            // reduce 32-bit RGB to 15-bit
>           COLORCONV_32_TO_16            // reduce 32-bit RGB to 16-bit
>           COLORCONV_32_TO_24            // reduce 32-bit RGB to 24-bit
>           COLORCONV_32A_TO_8            // reduce 32-bit RGBA to 8-bit
>           COLORCONV_32A_TO_15           // reduce 32-bit RGBA to 15-bit
>           COLORCONV_32A_TO_16           // reduce 32-bit RGBA to 16-bit
>           COLORCONV_32A_TO_24           // reduce 32-bit RGBA to 24-bit
>           COLORCONV_DITHER_PAL          // dither when reducing to 8-bit
>           COLORCONV_DITHER_HI           // dither when reducing to
>                                         // hicolor
>           COLORCONV_KEEP_TRANS          // keep original transparency

For convenience, the following macros can be used to select common combinations of these flags:

>           COLORCONV_EXPAND_256          // expand 256-color to hi/truecolor
>           COLORCONV_REDUCE_TO_256       // reduce hi/truecolor to 256-color
>           COLORCONV_EXPAND_15_TO_16     // expand 15-bit hicolor to 16-bit
>           COLORCONV_REDUCE_16_TO_15     // reduce 16-bit hicolor to 15-bit
>           COLORCONV_EXPAND_HI_TO_TRUE   // expand 15/16-bit to 24/32-bit
>           COLORCONV_REDUCE_TRUE_TO_HI   // reduce 24/32-bit to 15/16-bit
>           COLORCONV_24_EQUALS_32        // convert between 24- and 32-bit
>           COLORCONV_TOTAL               // everything to current format
>           COLORCONV_PARTIAL             // convert 15 <-> 16-bit and
>                                         // 24 <-> 32-bit
>           COLORCONV_MOST                // all but hi/truecolor <-> 256
>           COLORCONV_DITHER              // dither during all color reductions
>           COLORCONV_KEEP_ALPHA          // convert everything to current format
>                                         // unless it would lose alpha information

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.

If you intend using converted bitmaps with functions like masked_blit() or draw_sprite(), you should specify the COLORCONV_KEEP_TRANS flag. It will ensure that the masked areas in the bitmap before and after the conversion stay exactly the same, by mapping transparent colors to each other and adjusting colors which would be converted to the transparent color otherwise. It affects every blit() operation between distinct pixel formats and every automatic conversion.

> See also: set_color_depth, load_bitmap, load_datafile, fixup_datafile, makecol15_dither, get_color_conversion.

> Examples using this: exalpha, exblend, exdata, exexedat, exlights, exxfade.

int get_color_conversion();
Returns the current color conversion mode.

> See also: set_color_conversion.

Back to contents