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)

Allegro                                           version 4.4.3                          acquire_bitmap(3alleg4)