al_lock_bitmap(3alleg5)

💖 al_lock_bitmap — Allegro 5 API 💖

okay bestie, this is al_lock_bitmap from the Allegro 5 API manual (yes the manual name goes right here, we're being ✨thorough✨). buckle up, it's lock o'clock 🔒

---

✨ SYNOPSIS ✨

#include <allegro5/allegro.h>

ALLEGRO_LOCKED_REGION *al_lock_bitmap(ALLEGRO_BITMAP *bitmap,
   int format, int flags)

---

🌸 DESCRIPTION 🌸

So like. You wanna lock a whole entire bitmap, right? For reading, or for writing, or both, whatever your little heart desires. That's what this does 💅

Here's the tea tho: if the bitmap is a display bitmap, it gets updated from system memory after the bitmap is unlocked (unless you locked it read only, obvs). And it returns NULL if the bitmap just... can't be locked. like when? when the bitmap was already locked previously and never got unlocked 😭. Also returns NULL if format is a compressed format. no compressed formats allowed, sorry babes.

Now. the flags. there are three of them and they are lowkey iconic:

• ALLEGRO_LOCK_READONLY — the locked region will not be written to. This can be faster if the bitmap is a video texture, because it can just be discarded after the lock instead of uploaded back to the card. so it's giving efficient ✨
• ALLEGRO_LOCK_WRITEONLY — the locked region will not be read from. This can be faster if the bitmap is a video texture, since no data needs to be read from the video card at all. BUT. bestie. listen. You are required to fill in all pixels before unlocking the bitmap again. all of them. every single one. so be careful when using this flag, fr fr 🙈
• ALLEGRO_LOCK_READWRITE — the locked region can be written to and read from. Use this flag if a partial number of pixels need to be written to, even if reading isn't needed. it's the safe one, the main character one 👑

---

format is the pixel format that the returned buffer will be in, okay? So if you wanna lock in the same format that the bitmap stores its data internally, you call with al_get_bitmap_format(bitmap) as the format, or you can just use ALLEGRO_PIXEL_FORMAT_ANY. Locking in the native format will usually be faster, ngl. And if the bitmap format is compressed, using ALLEGRO_PIXEL_FORMAT_ANY will choose an implementation defined non-compressed format. so it's got your back 🫶

---

Now, on some platforms, Allegro automatically backs up the contents of video bitmaps, because they may be occasionally lost (go read the discussion in al_create_bitmap(3alleg5)'s documentation if you wanna know more). So if you're completely recreating the bitmap contents often — like, e.g. every frame — then you will get much better performance by creating the target bitmap with the ALLEGRO_NO_PRESERVE_TEXTURE flag. do it. your framerate will thank you 🌈

Note: While a bitmap is locked, you can not use any drawing operations on it. the sole exception is al_put_pixel(3alleg5) and al_put_blended_pixel(3alleg5). that's it. that's the whole list. 💀

---

👀 SEE ALSO 👀

• ALLEGRO_LOCKED_REGION(3alleg5)
• ALLEGRO_PIXEL_FORMAT(3alleg5)
• al_unlock_bitmap(3alleg5)
• al_lock_bitmap_region(3alleg5)
• al_lock_bitmap_blocked(3alleg5)
• al_lock_bitmap_region_blocked(3alleg5)

---

and that's the whole page, bestie 💖 this was the Allegro reference manual's writeup of al_lock_bitmap(3alleg5) — go lock something responsibly, mwah 🎀🦋✨