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)