load_bitmap(3)

✨ load_bitmap(3) — NAME ✨

load_bitmap — bestie, this one loads any supported bitmap straight out of a file 💖 It's part of the Allegro game programming library, and yes it's giving iconic.

🌈 SYNOPSIS 🌈

#include <allegro.h>

BITMAP *load_bitmap(const char *filename, RGB *pal);

🎀 DESCRIPTION 🎀

okay so. You hand it a file, it hands you a bitmap. That's the whole vibe. ✨

The palette data gets dropped into the second parameter, and heads up — that thing needs to be an array of 256 RGB structures, no cap. Right now this function supports BMP, LBM, PCX, and TGA files, and it figures out which one you meant by peeking at the file extension. iykyk 🔍

⚠️ IMPORTANT — if the file is a truecolor image, you must set the video mode or call set_color_conversion() before you load it. Not optional, bestie, this is the rule. 💅

So in that truecolor case: if the destination color depth is 8-bit, the palette gets generated by calling generate_optimized_palette() on the bitmap. Otherwise (any other depth), the returned palette is generated by calling generate_332_palette(). Two different paths, two different functions, don't mix them up 🫶

Now the cute part: pal is allowed to be NULL. When that happens, the palette data just... doesn't come back to you. It's simply not returned, periodt. And 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. Sneaky but true. 🌸

Example time, slay:

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. And bestie, listen — you are responsible for destroying the bitmap when you're done with it, otherwise you get memory leaks and that's not the main character energy we're going for 😭 destroy_bitmap() is right there, use her.

💜 SEE ALSO 💜

• load_bmp(3)
• load_lbm(3)
• load_pcx(3)
• load_tga(3)
• destroy_bitmap(3)
• save_bitmap(3)
• register_bitmap_file_type(3)
• set_color_depth(3)
• set_color_conversion(3)
• generate_optimized_palette(3)
• generate_332_palette(3)

and that's the whole page, angel 💅 this one shipped with Allegro version 4.4.3 — go load some bitmaps and hydrate, ily 🫶✨