al_hold_bitmap_drawing(3)

okay so bestie, this is al_hold_bitmap_drawing(3) straight out of the Library Functions Manual — yes, the Allegro 5 API one ✨💅

💖 NAME 💖

al_hold_bitmap_drawing — Allegro 5 API. That's the function, that's the vibe, no cap.

🌸 SYNOPSIS 🌸

#include <allegro5/allegro.h>

void al_hold_bitmap_drawing(bool hold)

🦋 DESCRIPTION 🦋

okay so al_hold_bitmap_drawing enables or disables deferred bitmap drawing, based on hold. This is the move when you want efficient drawing of many bitmaps that share a parent bitmap — like sub-bitmaps from a tilesheet, or just identical bitmaps. It's giving batch-drawing main character energy 🔥.

Drawing bitmaps that do not share a parent is less efficient, so it's advisable to stagger bitmap drawing calls such that the parent bitmap is the same for large number of those calls. iykyk, group your faves together.

While deferred bitmap drawing is enabled, the only functions you can use are the bitmap drawing functions and font drawing functions. Changing the state — like the blending modes — will result in undefined behaviour 😭. One exception to this rule are the non-projection transformations. It is possible to set a new transformation while the drawing is held. slay for that one exception, honestly.

🚨 No drawing is guaranteed to take place until you disable the hold. Like, none. Do not come for the screen if it hasn't shown up yet, bestie.

Thus, the idiom of this function's usage is to enable the deferred bitmap drawing, draw as many bitmaps as possible, taking care to stagger bitmaps that share parent bitmaps, and then disable deferred drawing. That's the whole flow 🫶.

As mentioned above, this function also works with bitmap and truetype fonts, so if multiple lines of text need to be drawn, this function can speed things up. Text girlies stay winning 💖.

🎀 SEE ALSO 🎀

• al_is_bitmap_drawing_held(3) — the related one, bestie 🦋

source/version: Allegro reference manual (Allegro 5 API); date: not printed in this footer, bestie 💖 — mwah 💋