ALLEGRO_LOCKED_REGION(3alleg5)

✨ ALLEGRO_LOCKED_REGION ✨

okay bestie so this is a page from the Allegro 5 API reference manual, and it's all about ALLEGRO_LOCKED_REGION 💖 pull up a chair, this one's short and sweet but lowkey important.

---

🌸 SYNOPSIS 🌸

#include <allegro5/allegro.h>

typedef struct ALLEGRO_LOCKED_REGION ALLEGRO_LOCKED_REGION;

---

🎀 DESCRIPTION 🎀

so here's the vibe: if you wanna manually edit or read from a bitmap, you literally have to lock it first. no skipping that step, bestie, it's giving non-negotiable 💅

The ALLEGRO_LOCKED_REGION structure is what represents the locked region of the bitmap. and the slay part? this call will work with any bitmap, including memory bitmaps. every single one. periodt. 👑

typedef struct ALLEGRO_LOCKED_REGION {
   void *data;
   int format;
   int pitch;
   int pixel_size;
} ALLEGRO_LOCKED_REGION;

now let's break down the members, one by one, because they all matter:

• data — this points to the leftmost pixel of the first row (row 0) of the locked region. and heads up for the blocked formats girlies: for those, it points to the leftmost block of the first row of blocks. not a pixel. a block. iykyk 🧚
• format — tells you the pixel format of the data. that's it, that's the whole job 🎀
• pitch — this one's the size in bytes of a single row (you might also hear it called the stride). and listen, the pitch can totally be greater than width * pixel_size because of padding — and ngl that's not uncommon at all. it's also not uncommon for the pitch to be negative, because your bitmap might just be upside down 🙃 (iconic behaviour honestly). and for blocked formats? row means the row of blocks, not of pixels. don't get it twisted.
• pixel_size — the number of bytes used to represent a single block of pixels for the pixel format of this locked region. for most formats this is just the size of a single pixel — and historically, that used to be true for all formats, fr fr — but for blocked pixel formats this value is different. so yeah, check before you assume bestie 💀

lowkey reminder: the pitch being bigger than width * pixel_size is normal, and a negative pitch is normal too. not a bug, just the vibe. don't panic 🫶

---

🦋 SEE ALSO 🦋

• al_lock_bitmap(3alleg5)
• al_lock_bitmap_region(3alleg5)
• al_unlock_bitmap(3alleg5)
• ALLEGRO_PIXEL_FORMAT(3alleg5)

---

and that's the whole page, bestie!! go forth and lock those bitmaps responsibly 💜 this was from the Allegro reference manual, ALLEGRO_LOCKED_REGION(3alleg5), mwah 😭✨