al_create_sub_bitmap(3)

💖 NAME 💖

okay so this is the al_create_sub_bitmap(3) page from the Library Functions Manual, and the function is al_create_sub_bitmap — Allegro 5 API energy, no cap. 💅✨

🌸 SYNOPSIS 🌸

bestie, here’s the exact spell to cast:

#include <allegro5/allegro.h>

ALLEGRO_BITMAP *al_create_sub_bitmap(ALLEGRO_BITMAP *parent,
   int x, int y, int w, int h)

🦋 DESCRIPTION 🦋

okay so al_create_sub_bitmap creates a sub-bitmap of the parent, at the coordinates you specify and with the size you specify. It’s giving “baby bitmap, same drawing memory” — a sub-bitmap is a bitmap that shares drawing memory with a pre-existing parent bitmap, but it can possibly have a different size and clipping settings. 👑

• The sub-bitmap may originate off or extend past the parent bitmap. yes, it can be extra like that. 💅
• go read the discussion in al_get_backbuffer(3) about using sub-bitmaps of the backbuffer, iykyk.
• the parent bitmap’s clipping rectangles are ignored. not invited to the group chat. 🚫

If a sub-bitmap was not or cannot be created, then NULL is returned. that’s the vibe check failing, bestie. 😭

When you’re done using the sub-bitmap, you must call al_destroy_bitmap(3) on it to free any resources allocated for it. no ghosting your cleanup duties, periodt. 🧹✨

⚠️ big note, bestie: destroying parents of sub-bitmaps will not destroy the sub-bitmaps. instead, the sub-bitmaps become invalid and should no longer be used for drawing — they still must be destroyed with al_destroy_bitmap(3) however. it does not matter whether you destroy a sub-bitmap before or after its parent otherwise. so like… destroy responsibly, okay? 💀🫶

✨ SEE ALSO ✨

you’ll also wanna peek at al_create_bitmap(3) — it’s the related icon, fr fr. 🌈

---

cute sign-off: this page is signed by the Allegro reference manual, with al_create_sub_bitmap(3) riding alongside — bye bestie, go make some sub-bitmaps! 💖🎀🦋