Once you have selected a graphics mode, you can draw things onto the display
via the `screen' bitmap. All the Allegro graphics routines draw onto BITMAP
structures, which are areas of memory containing rectangular images, stored
as packed byte arrays (in 8-bit modes one byte per pixel, in 15- and 16-bit
modes two bytes per pixel, in 24-bit modes 3 bytes per pixel and in 32-bit
modes 4 bytes per pixel). You can create and manipulate bitmaps in system
RAM, or you can write to the special `screen' bitmap which represents the
video memory in your graphics card.
Read chapter "Direct access to video memory" for information on how to get
direct access to the image memory in a bitmap.
Allegro supports several different types of bitmaps:
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(), so you should never
attempt to destroy it yourself.
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
Sub-bitmaps. These share image memory with a parent bitmap (which can be
the screen, a video or system bitmap, 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).
Warning: Make sure not to destroy a bitmap before all of its sub-bitmaps,
otherwise bad things will happen when you try to access one of these
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
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().