NAME¶
acquire_bitmap - Locks the bitmap before drawing onto it. Allegro game
programming library.
SYNOPSIS¶
#include <allegro.h>
void acquire_bitmap(BITMAP *bmp);
DESCRIPTION¶
Acquires the specified video bitmap prior to drawing onto it. You never need to
call the function explicitly as it is low level, and 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.
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.
It still can be useful, because e.g. 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.
Multiple acquire calls may be nested, but you must make sure to match up the
acquire_bitmap and release_bitmap calls. Be warned that 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!
Note that 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.
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).
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 - changes are you are doing something in the wrong
way if you think you need it.
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.
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)