1acquire_bitmap(3)               Allegro manual               acquire_bitmap(3)
2
3
4

NAME

6       acquire_bitmap  - Locks the bitmap before drawing onto it. Allegro game
7       programming library.
8

SYNOPSIS

10       #include <allegro.h>
11
12
13       void acquire_bitmap(BITMAP *bmp);
14

DESCRIPTION

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
21       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
25       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
32       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
39       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
45       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
51       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
62       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
70

SEE ALSO

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)
74
75
76
77Allegro                          version 4.4.3               acquire_bitmap(3)
Impressum