acquire_bitmap

acquire_bitmap(3alleg4)          Allegro manual          acquire_bitmap(3alleg4)



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)