al_hold_bitmap_drawing(3alleg5)

💖 al_hold_bitmap_drawing 💖

okay bestie, welcome to the Allegro 5 API corner of the Allegro reference manual, where we make pixels go brrr. this one's about al_hold_bitmap_drawing, and honestly? it's giving "quiet little function, unhinged amounts of power" energy. 🎀

---

✨ NAME ✨

al_hold_bitmap_drawing — the Allegro 5 API function that lets you hold your bitmap drawing so it all goes down at once 🔥

---

🌸 SYNOPSIS 🌸

#include <allegro5/allegro.h>

void al_hold_bitmap_drawing(bool hold)

---

💅 DESCRIPTION 💅

so basically this function turns deferred bitmap drawing on or off, and the whole point of it is efficiency. like, if you're drawing a ton of bitmaps that all share the same parent bitmap — think sub-bitmaps pulled out of a tilesheet, or just a bunch of identical bitmaps — this is how you make that fast. 🦋

now, a lil reality check: drawing bitmaps that do not share a parent? lowkey less efficient. so the move is to stagger your bitmap drawing calls in a way that the parent bitmap stays the same across a big ol' batch of them. keep the fam together, yk? 👑

⚠️ while deferred bitmap drawing is enabled, the only functions you're allowed to use are the bitmap drawing functions and the font drawing functions. that's it. that's the list.

and it gets spicier: if you go changing state — stuff like the blending modes — while this is held? undefined behaviour. not "probably fine", not "eh, it'll work out", just straight-up undefined. do not do it, bestie, i'm begging 😭

one exception to that rule though, and it's iconic: the non-projection transformations. you can set a new transformation while the drawing is held. slay. ✨

also super important — and this is the part people sleep on — no drawing is guaranteed to take place until you disable the hold. none. zero. it's all just vibing in the queue until you let it go. so the classic idiom of this function's usage is:

1. enable the deferred bitmap drawing
2. draw as many bitmaps as you possibly can, taking care to stagger the ones that share parent bitmaps
3. disable deferred drawing

and then everything actually happens. periodt. 💅

bonus: as mentioned above, this function also works with bitmap fonts and truetype fonts, so if you've got multiple lines of text to draw, this function can speed things up too. text girlies, you're included. 📝💖

---

👀 SEE ALSO 👀

• al_is_bitmap_drawing_held(3alleg5) — the lil check-in function, so you can ask "are we holding rn?" 🫶

---

and that's the whole page, bestie! Allegro reference manual, al_hold_bitmap_drawing, out. go forth and batch your bitmaps responsibly 💜✨🎀