Re: [AD] Program hangs

[Elias Pschernig <elias@xxxxxxxxxx>]

On Tue, 2005-09-13 at 16:19 +0200, Elias Pschernig wrote:
> Yes, you can't call show_mouse while the screen is acquired.
> 

But since this comes up relatively often, I guess our docs are simply
wrong. Attached patch describes better what it does, and also warns
about its use. I think most uses of it aren't necessary at all.. but the
current docs are like "use this to make your program faster", so that's
expected :P

-- 
Elias Pschernig

Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.362
diff -u -p -r1.362 allegro._tx
--- docs/src/allegro._tx	28 Aug 2005 05:08:47 -0000	1.362
+++ docs/src/allegro._tx	13 Sep 2005 14:29:20 -0000
@@ -4870,22 +4911,71 @@ Allegro supports several different types
 @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!
-   
+   Acquires the specified video memory bitmap prior to drawing onto it. You do
+   never need to call this function, it is very low level, and only will give
+   you a speed up if you know what you are doing. Using it wrongly, you may slow
+   down your program, or do worse things.
+
+   It still can be useful, because e.g. under DirectDraw, locking a video
+   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().
+   not call acquire_bitmap() under DirectDraw.
+
+   Here an example where it may be useful to use acquire_bitmap:
+
+   <codeblock>
+   acquire_bitmap(page);
+   for (i = 0; i < 10000; i++)
+      putpixel(x[i], y[i], color[i]);
+   release_bitmap(page);
+   <endblock>
+
+   In the above case, without the acquire/release pair Allegro might lock and
+   unlock the video bitmap after every call to putpixel. But now, it will only
+   do it once.
+
+   An example *how it is used wrong*:
+
+   <codeblock>
+   acquire_bitmap(page);
+   for (i = 0; i < 10000; i++)
+       draw_sprite(page, sprite[i], x[i], y[i]);
+   release_bitmap(page);
+   <endblock>
+
+   Accelerated sprites normally can only be drawn to a not acquired video
+   bitmap, so instead of speeding up the above, acquire_bitmap slows it down to
+   a crawl - since Allegro now needs to un-acquire the page for every sprite.
+
+   Another example:
+
+   <codeblock>
+   acquire_bitmap(page);
+   for (i = 0; i < 10; i++)
+       circlefill(page, x[i], y[i], x[i + 1], y[i + 1], color[i]);
+   release_bitmap(page);
+   <endblock>
+
+   The circlefill function acquires the destination on its own before plotting
+   all the single pixels, so it may be pointless to acquire it manually. And it
+   may use accelerates filling, in which case the video bitmap should not be
+   acquired at all, like in the previous example.
+
+   And be warned again: 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, since that will most likely deadlock your
+   entire program.
+
 
 @@void @release_bitmap(BITMAP *bmp);
 @xref acquire_bitmap, acquire_screen, release_screen