Re: [AD] crash.. destroy_bitmap( a system bitmap );

[Eric Botcazou <ebotcazou@xxxxxxxxxx>]

> destroy_bitmap()   crashes  when  its a system bitmap; and you have
> returned to text mode.. ie set_gfx_mode(TEXT)
> the  gfx_driver  ptr is NULL.

Well-known pitfall. There is an ASSERT in the code on mainline.

> if normal procedure is to destroy system bitmaps before returning to text
> mode,  can that be documented somewhere near the
>
> \allegro\docs\html\alleg009.html#destroy_bitmap
>
> current text says "Destroys a memory bitmap, sub-bitmap, video memory
> bitmap, or system bitmap when you are finished with it. "
>
> maybe changed to "Destroys a memory bitmap, sub-bitmap, video memory
> bitmap, or system bitmap when you are finished with it, system bitmaps
> must be destroyed before changing screen driver."

The docs in the CVS repository contain:

Allegro supports several different types of bitmaps:
<ul><li>
     The screen bitmap, which represents the hardware video memory.
     Ultimately you have to draw onto this in order for your image to be 
     visible. It is destroyed by any subsequent calls to set_gfx_mode().
<li>
     Memory bitmaps, which are located in system RAM and can be used to
     store graphics or as temporary drawing spaces for double buffered 
     systems. These can be obtained by calling create_bitmap(), load_pcx(), 
     or by loading a grabber datafile.
<li>
     Sub-bitmaps. These share image memory with a parent bitmap (which
     can be the screen, a memory bitmap, or another sub-bitmap), so drawing 
     onto them will also change their parent. They can be of any size and 
     located anywhere within the parent bitmap, and can have their own 
     clipping rectangles, so they are a useful way of dividing a bitmap into 
     several smaller units, eg. splitting a large virtual screen into 
     multiple sections (see examples/exscroll.c).
<li>
     Video memory bitmaps. These are created by the create_video_bitmap()
     function, and are usually implemented as sub-bitmaps of the screen 
     object. They must be destroyed by destroy_bitmap() before any subsequent
     calls to set_gfx_mode().
<li>
     System bitmaps. These are created by the create_system_bitmap()
     function, and are a sort of halfway house between memory and video 
     bitmaps. They live in system memory, so you aren't limited by the 
     amount of video ram in your card, but they are stored in a 
     platform-specific format that may enable better hardware acceleration 
     than is possible with a normal memory bitmap (see the 
     GFX_HW_SYS_TO_VRAM_BLIT and GFX_HW_SYS_TO_VRAM_BLIT_MASKED flags in 
     gfx_capabilities). System bitmaps must be accessed in the same way as 
     video bitmaps, using the bank switch functions and bmp_write*() macros. 
     Not every platform implements this type of bitmap: if they aren't 
     available, create_system_bitmap() will function identically to 
     create_bitmap(). They must be destroyed by destroy_bitmap() before any
     subsequent calls to set_gfx_mode().
</ul>


I've commited the attached patch on mainline and branch. Thanks for pointing 
this out.

-- 
Eric Botcazou

Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.195
diff -u -r1.195 allegro._tx
--- docs/src/allegro._tx	4 Nov 2003 09:38:26 -0000	1.195
+++ docs/src/allegro._tx	6 Nov 2003 12:20:06 -0000
@@ -3571,7 +3571,8 @@
 @xref create_bitmap, load_bitmap
 @eref Available Allegro examples
    Destroys a memory bitmap, sub-bitmap, video memory bitmap, or system 
-   bitmap when you are finished with it.
+   bitmap when you are finished with it. See above for the restrictions
+   as to when you are allowed to destroy the various types of bitmaps.
 
 @@void @lock_bitmap(BITMAP *bitmap);
    Under DOS, locks all the memory used by a bitmap. You don't normally need