1acquire_bitmap(3) Allegro manual acquire_bitmap(3)
2
6 acquire_bitmap - Locks the bitmap before drawing onto it. Allegro game
7 programming library.
8
10 #include <allegro.h>
11 void acquire_bitmap(BITMAP *bmp);
14
16 Acquires the specified video bitmap prior to drawing onto it. You never
17 need to call the function explicitly as it is low level, and will only
18 give you a speed up if you know what you are doing. Using it wrongly
19 may cause slowdown, or even lock up your program.
20 Note: You do never need to use acquire_bitmap on a memory bitmap, i.e.
22 a normal bitmap created with create_bitmap. It will simply do nothing
23 in that case.
24 It still can be useful, because e.g. under the current DirectDraw
26 driver of Allegro, most drawing functions need to lock a video bitmap
27 before drawing to it. But doing this is very slow, so you will get much
28 better performance if you acquire the screen just once at the start of
29 your main redraw function, then call multiple drawing operations which
30 need the bitmap locked, and only release it when done.
31 Multiple acquire calls may be nested, but you must make sure to match
33 up the acquire_bitmap and release_bitmap calls. Be warned that DirectX
34 and X11 programs activate a mutex lock whenever a surface is locked,
35 which prevents them from getting any input messages, so you must be
36 sure to release all your bitmaps before using any timer, keyboard, or
37 other non-graphics routines!
38 Note that if you are using hardware accelerated VRAM->VRAM functions,
40 you should not call acquire_bitmap(). Such functions need an unlocked
41 target bitmap under DirectX, so there is now just the opposite case
42 from before - if the bitmap is already locked with acquire_bitmap, the
43 drawing operation has to unlock it.
44 Note: For backwards compatibility, the unlocking behavior of such func‐
46 tions is permanent. That is, if you call acquire_bitmap first, then
47 call e.g. an accelerated blit, the DirectX bitmap will be unlocked
48 internally (it won't affect the nesting counter of acquire/release
49 calls).
50 There is no clear cross-platform way in this Allegro version to know
52 which drawing operations need a locked/unlocked state. For example a
53 normal rectfill most probably is accelerated under DirectX, and there‐
54 fore needs the screen unlocked, but an XOR rectfill, or one with blend‐
55 ing activated, most probably is not, and therefore locks the screen.
56 And while the DirectX driver will do automatic unlocking, there is no
57 such thing under X11, where the function is used to synchronize X11
58 calls from different threads. Your best bet is to never use
59 acquire_bitmap - changes are you are doing something in the wrong way
60 if you think you need it.
61 Warning: This function can be very dangerous to use, since the whole
63 program may get locked while the bitmap is locked. So the lock should
64 only be held for a short time, and you should not call anything but
65 drawing operations onto the locked video bitmap while a lock is in
66 place. Especially don't call things like show_mouse (or scare_mouse
67 which calls that) or readkey, since it will most likely deadlock your
68 entire program.
69
72 release_bitmap(3), acquire_screen(3), release_screen(3), ex3buf(3),
73 exaccel(3), expat(3), exquat(3), exscroll(3), exswitch(3), exupdate(3)
74Allegro version 4.4.3 acquire_bitmap(3)