load_bitmap(3alleg4)

✨ load_bitmap ✨

okay bestie, welcome to the Allegro manual — this one's load_bitmap(3alleg4) and it's literally the moment your game finally gets a face 🎀

🌸 NAME 🌸

load_bitmap — loads literally any supported bitmap from a file. It's the Allegro game programming library, and this function is the one that goes "here's your picture, queen" 💅

🦋 SYNOPSIS 🦋

#include <allegro.h>

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

💖 DESCRIPTION 💖

So basically it loads a bitmap from a file, periodt. The palette data goes into the second parameter, which should be an array of 256 RGB structures. Like, exactly 256, don't be weird about it.

Right now it supports BMP, LBM, PCX, and TGA files — and the way it figures out which one you handed it? The file extension. That's the vibe check it runs. 👑

Now listen up, because this part is important and it's giving gotcha energy:

If your file contains a truecolor image, you must set the video mode or call set_color_conversion() before loading it. No skipping this step, bestie, it will not work otherwise 😭

And when that happens, here's the tea: if the destination color depth is 8-bit, the palette gets generated by calling generate_optimized_palette() on the bitmap. Otherwise — different story — the returned palette gets generated by calling generate_332_palette().

The pal argument can be NULL 🫶 and in that case the palette data just... isn't returned. Simply not a thing that happens. 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. Little shortcut, love that for us.

🌈 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. Simple as that 💀

🚨 BESTIE. Remember that you are responsible for destroying the bitmap when you're finished with it, so you don't leak memory. That's on you. Nobody else is coming to clean up. destroy_bitmap() is right there, use it 🧚

👑 SEE ALSO 👑

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

Allegro version 4.4.3 🦋 — and this whole load_bitmap(3alleg4) moment was brought to you by the Allegro girlies. slay, go load a PCX, mwah 💖✨