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)