acquire_bitmap(3alleg4)

✨ acquire_bitmap — the "lock the bitmap before you draw on it" era 💅

okay bestie so this is a page from the Allegro manual — the Allegro game programming library — and we're talking about acquire_bitmap. it's giving low-level, it's giving "you probably don't need this", and honestly? she's a little dangerous. let's get into it 🎀

🌸 NAME 🌸

acquire_bitmap — locks the bitmap before drawing onto it. Allegro game programming library. periodt.

🦋 SYNOPSIS 🦋

#include <allegro.h>

void acquire_bitmap(BITMAP *bmp);

💖 DESCRIPTION 💖

So acquire_bitmap acquires the specified video bitmap before you draw onto it. And like — you literally never need to call this function explicitly?? it's low level, and it will only give you a speed up if you know what you are doing. Using it wrongly may cause slowdown, or even lock up your program. not cute. 💀

Note: you do never need to use acquire_bitmap on a memory bitmap, i.e. a normal bitmap created with create_bitmap. It will simply do nothing in that case. nothing. zero. nada. 🙈

But bestie, it still can be useful, because — for example — under the current DirectDraw driver of Allegro, most drawing functions need to lock a video bitmap before drawing to it. But doing this is very slow 😭 so you will get much better performance if you acquire the screen just once at the start of your main redraw function, then call multiple drawing operations which need the bitmap locked, and only release it when done. like, one big lock, many draws, one release. main character energy only.

Multiple acquire calls may be nested, but you must make sure to match up the acquire_bitmap and release_bitmap calls. And be warned: DirectX and X11 programs activate a mutex lock whenever a surface is locked, which prevents them from getting any input messages 😱 so you must be sure to release all your bitmaps before using any timer, keyboard, or other non-graphics routines! fr fr, do not skip this.

Note: if you are using hardware accelerated VRAM->VRAM functions, you should not call acquire_bitmap(). Such functions need an unlocked target bitmap under DirectX, so there is now just the opposite case from before — if the bitmap is already locked with acquire_bitmap, the drawing operation has to unlock it. the plot twist nobody asked for ✨

Note: For backwards compatibility, the unlocking behavior of such functions is permanent. That is, if you call acquire_bitmap first, then call e.g. an accelerated blit, the DirectX bitmap will be unlocked internally (it won't affect the nesting counter of acquire/release calls). so the nesting counter stays unbothered, she's fine. 💅

There is no clear cross-platform way in this Allegro version to know which drawing operations need a locked/unlocked state. For example a normal rectfill most probably is accelerated under DirectX, and therefore needs the screen unlocked, but an XOR rectfill, or one with blending activated, most probably is not, and therefore locks the screen. And while the DirectX driver will do automatic unlocking, there is no such thing under X11, where the function is used to synchronize X11 calls from different threads. Your best bet is to never use acquire_bitmap — chances are you are doing something in the wrong way if you think you need it. yeah. she said what she said. 😭

Warning: This function can be very dangerous to use, since the whole program may get locked while the bitmap is locked. So the lock should only be held for a short time, and you should not call anything but drawing operations onto the locked video bitmap while a lock is in place. Especially don't call things like show_mouse (or scare_mouse which calls that) or readkey, since it will most likely deadlock your entire program. 💀 not the deadlock. please. do not.

👑 SEE ALSO 👑

• release_bitmap(3alleg4)
• acquire_screen(3alleg4)
• release_screen(3alleg4)
• ex3buf(3alleg4)
• exaccel(3alleg4)
• expat(3alleg4)
• exquat(3alleg4)
• exscroll(3alleg4)
• exswitch(3alleg4)
• exupdate(3alleg4)

and that's the whole page, bestie 🫶 this was Allegro, version 4.4.3, and it's the acquire_bitmap(3alleg4) manual page — go forth, lock responsibly, and honestly? just don't use it. slay. 🎀✨