al_create_sub_bitmap(3alleg5)

✨ NAME ✨

al_create_sub_bitmap — the Allegro 5 API glow-up where you carve a lil baby bitmap out of a bigger one 💖 (this page lives in the Allegro 5 manual, bestie)

---

🌸 SYNOPSIS 🌸

#include <allegro5/allegro.h>

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

---

🦋 DESCRIPTION 🦋

okay so basically: this makes a sub-bitmap of the parent, sitting at the coordinates you give it and sized however you want. And what even IS a sub-bitmap? It's a bitmap that shares drawing memory with a bitmap that already existed (the parent 👑) — but it can have a totally different size and different clipping settings. same pixels, new vibe. it's giving remix.

Also, heads up: the sub-bitmap is allowed to originate off the parent bitmap or extend past it. boundaries? never heard of her.

There's a whole discussion about using sub-bitmaps of the backbuffer over in al_get_backbuffer(3alleg5) — go read it, it's important iykyk.

The parent bitmap's clipping rectangles? ignored. completely. the parent does not get a say.

If a sub-bitmap was not created, or just like, cannot be created, then NULL comes back. that's your sign it didn't work 💀

When you're done with the sub-bitmap you must call al_destroy_bitmap(3alleg5) on it to free up any resources allocated for it. yes really. do it. 🫶

⚠️ okay this part matters so listen up: destroying the parents of sub-bitmaps will not destroy the sub-bitmaps. instead, the sub-bitmaps become invalid and you should no longer use them for drawing — but they still must be destroyed with al_destroy_bitmap(3alleg5) anyway. rude, i know. aside from that, it does not matter whether you destroy a sub-bitmap before or after its parent. either order, no drama.

---

🌈 SEE ALSO 🌈

• al_create_bitmap(3alleg5)

---

that's the whole page, bestie — go forth and sub-bitmap responsibly 🎀✨ this was pulled straight from the Allegro reference manual, filed under al_create_sub_bitmap(3alleg5) 💅 slay 🦋