Bitmap objects

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 grabber datafile.
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 sub-bitmaps.
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().
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().

screen - Global pointer to the screen hardware video memory.
SCREEN_W
SCREEN_H - Global define to obtain the size of the screen.
VIRTUAL_W
VIRTUAL_H - Global define to obtain the virtual size of the screen.
create_bitmap - Creates a memory bitmap.
create_bitmap_ex - Creates a memory bitmap specifying color depth.
create_sub_bitmap - Creates a memory sub bitmap.
create_video_bitmap - Creates a video memory bitmap.
create_system_bitmap - Creates a system memory bitmap.
destroy_bitmap - Destroys any type of created bitmap.
lock_bitmap - Locks the memory used by a bitmap.
bitmap_color_depth - Returns the color depth of the specified bitmap.
bitmap_mask_color - Returns the mask color of the specified bitmap.
is_same_bitmap - Tells if two bitmaps describe the same drawing surface.
is_planar_bitmap - Tells if a bitmap is a planar screen bitmap.
is_linear_bitmap - Tells if a bitmap is linear.
is_memory_bitmap - Tells if a bitmap is a memory bitmap.
is_screen_bitmap - Tells if a bitmap is the screen bitmap or sub bitmap.
is_video_bitmap - Tells if a bitmap is a screen bitmap, video memory or sub bitmap.
is_system_bitmap - Tells if a bitmap is a system bitmap or sub bitmap.
is_sub_bitmap - Tells if a bitmap is a sub bitmap.
acquire_bitmap - Locks the bitmap before drawing onto it.
release_bitmap - Releases a previously locked bitmap.
acquire_screen - Shortcut of acquire_bitmap(screen);
release_screen - Shortcut of release_bitmap(screen);
set_clip_rect - Sets the clipping rectangle of a bitmap.
get_clip_rect - Returns the clipping rectangle of a bitmap.
add_clip_rect - Intersects a bitmap's clipping rectangle with the given area.
set_clip_state - Turns on or off the clipping of a bitmap.
get_clip_state - Tells if clipping is on for a bitmap.
is_inside_bitmap - Tells if a point is inside a bitmap.

Allegro Manual

API

Bitmap objects