Re: [AD] Program hangs

[Elias Pschernig <elias@xxxxxxxxxx>]

Thanks, I fixed everything you mentioned, and also fixed a missing
parameter in the first example, mentioned readkey additionally to
show_mouse, and maybe something else.. new version attached.

-- 
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 22:54:46 -0000
@@ -4870,23 +4911,75 @@ 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 
+   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.
+
+   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().
 
+   Here is an example where it may be useful to use acquire_bitmap:
+
+   <codeblock>
+   acquire_bitmap(page);
+   for (i = 0; i < 10000; i++)
+      putpixel(page, 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 of *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 if the sprites are video bitmaps themselves - 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, since
+   the acquiring may take less time than drawing the circle. And even if not,
+   with only 10 circles, you probably don't save a lot. Also, circlefill may use
+   accelerated 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 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