Re: [AD] acquire_bitmap weirdness

[Elias Pschernig <elias@xxxxxxxxxx>]

On Mon, 2006-01-02 at 16:29 -0800, Chris wrote:
> 
> Huh? Without the acquire/release_bitmap pair there, blit() would lock/unlock 
> the bitmap for every sprite shown, if it's a memory bitmap. By doing it 
> outside the loop, it only locks once, and would therefor be faster. If the 
> sources are video bitmaps and HW blitting is available, it'll lock once at 
> the acquire call, then unlock once at the first blit call, and stay unlocked.

Ok, so we probably should change the X11 driver to behave the same.

> > But what if code looks like this:
> >
> > acquire_bitmap(my_video_backbuffer);
> > blit(i->bitmap, my_video_bitmap, ...);
> > for (i = 0; i < 640 * 480; i++) {
> >     pupixel(my_video_bitmap...)
> > }
> > release_bitmap(my_video_backbuffer);
> >
> > Right now, this will be very slow, and if you move the blit one line up,
> > suddenly gets fast..
> 
> You sure? If the source is a memory bitmap, that's as fast as you'll get. 
> Instead of locking and unlocking once for the blit, and then locking again 
> for all the putpixels. If it's a video bitmap, it'll lock/unlock twice. It'll 
> lock at the acquire call, unlock at blit, lock at putpixel, and stay locked 
> untill release_bitmap.

I have no idea, and it's hard for me to follow the code (Why would
DirectX need "bank unwriting?" - I thought that's something only
existent in old VESA drivers..). So well, I would not be surprised by
either way.

> And you can't assume acquire/release is needed only on unaccelerated 
> functions. Under X it does a mutex lock to avoid Xlib async errors. The 
> "video" vtables call the X functions to draw to the window directly, for some 
> functions, and they may or not be accelerated.. but they still need to be 
> locked for the mutex. Without the explicit lock/unlock call outside all the 
> to-screen functions, that'd be a lot of mutex locks (very slow).

My tests show that I can draw about 5% more putpixel in a second with an
acquire_screen pair, than without.. with pthreads for 2.6 kernels, mutex
locks are mostly the function call overhead if the lock is not congested
(and only get very slow if a locked mutex is hit, and a syscall is
performed).

Anyway, I removed now all the examples and other things I apparently
don't know about from the patch..

-- 
Elias Pschernig

Index: docs/src/allegro._tx
===================================================================
--- docs/src/allegro._tx	(revision 5629)
+++ docs/src/allegro._tx	(working copy)
@@ -4972,23 +4972,53 @@
 @xref release_bitmap, acquire_screen, release_screen
 @eref ex3buf, exaccel, expat, exquat, exscroll, exswitch, exupdate
 @shortdesc Locks the bitmap before drawing onto it.
-   Locks the specified video memory bitmap prior to drawing onto it. This 
-   does not apply to memory bitmaps, and only affects some platforms 
-   (Windows needs it, DOS does not). These calls are not strictly required, 
-   because the drawing routines will automatically acquire the bitmap before 
-   accessing it, but locking a DirectDraw surface 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, and only release it when the drawing 
-   is completely finished. Multiple acquire calls may be nested, and the 
-   bitmap will only be truly released when the lock count returns to zero. 
-   Be warned that DirectX 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-&gtVRAM blits, you should
-   not call acquire_bitmap().
+   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-&gtVRAM 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 are accelerated or not, and which will do internal
+   locking/unlocking and whicn not. For example a normal rectfill most probably
+   is accelerated, but an XOR rectfill, or one with blending activated, most
+   probably is not. And while the DirectX driver will do automatic unlocking,
+   the X11 driver may not. Rule of dumb: Never us acquire_bitmap.
+
+   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
+   that will most likely deadlock your entire program.
+
 @@void @release_bitmap(BITMAP *bmp);
 @xref acquire_bitmap, acquire_screen, release_screen
 @eref ex3buf, exaccel, expat, exquat, exscroll, exswitch, exupdate