Bitmap routines

Summary
Creates a new bitmap using the bitmap format and flags for the current thread.
Destroys the given bitmap, freeing all resources used by it.
Load a bitmap from a file using the bitmap format and flags of the current thread.
Draws an unscaled, unrotated bitmap at the given position to the current target bitmap (see al_set_target_bitmap).
Draws a region of the given bitmap to the target bitmap.
Draws a scaled version of the given bitmap to the target bitmap.
Draws a rotated version of the given bitmap to the target bitmap.
Like al_draw_rotated_bitmap, but can also scale the bitmap.
Like al_lock_bitmap, but only locks a specific area of the bitmap.
Lock an entire bitmap for reading or writing.
Unlock a previously locked bitmap or bitmap region.
Convert the given mask color to an alpha channel in the bitmap.
Returns the width of a bitmap in pixels.
Returns the height of a bitmap in pixels.
Returns the pixel format of a bitmap.
Return the flags user to create the bitmap.
Creates a sub-bitmap of the parent, at the specified coordinates and of the specified size.
Clone a bitmap “exactly”, formats can be different.
Returns whether or not a bitmap is already locked.

Functions

al_create_bitmap

ALLEGRO_BITMAP *al_create_bitmap(int w,
int h)

Creates a new bitmap using the bitmap format and flags for the current thread.  Blitting between bitmaps of differing formats, or blitting between memory bitmaps and display bitmaps may be slow.

Unless you set the ALLEGRO_MEMORY_BITMAP flag, the bitmap is created for the current display.  Blitting to another display may be slow.

See Also: al_set_new_bitmap_format, al_set_new_bitmap_flags

al_destroy_bitmap

void al_destroy_bitmap(ALLEGRO_BITMAP *bitmap)

Destroys the given bitmap, freeing all resources used by it.  Does nothing if given the null pointer.

al_load_bitmap

ALLEGRO_BITMAP *al_load_bitmap(char const *filename)

Load a bitmap from a file using the bitmap format and flags of the current thread.

See Also: al_set_new_bitmap_format, al_set_new_bitmap_flags

al_draw_bitmap

void al_draw_bitmap(ALLEGRO_BITMAP *bitmap,
float dx,
float dy,
int flags)

Draws an unscaled, unrotated bitmap at the given position to the current target bitmap (see al_set_target_bitmap). flags can be a combination of:

ALLEGRO_FLIP_HORIZONTALflip the bitmap about the y-axis
ALLEGRO_FLIP_VERTICALflip the bitmap about the x-axis

al_draw_bitmap_region

void al_draw_bitmap_region(ALLEGRO_BITMAP *bitmap,
float sx,
float sy,
float sw,
float sh,
float dx,
float dy,
int flags)

Draws a region of the given bitmap to the target bitmap.

sxsource x
sysource y
swsource width (width of region to blit)
shsource height (height of region to blit)
dxdestination x
dydestination y
flagssame as for al_draw_bitmap

al_draw_scaled_bitmap

void al_draw_scaled_bitmap(ALLEGRO_BITMAP *bitmap,
float sx,
float sy,
float sw,
float sh,
float dx,
float dy,
float dw,
float dh,
int flags)

Draws a scaled version of the given bitmap to the target bitmap.

sxsource x
sysource y
swsource width
shsource height
dxdestination x
dydestination y
dwdestination width
dhdestination height
flagssame as for al_draw_bitmap

al_draw_rotated_bitmap

void al_draw_rotated_bitmap(ALLEGRO_BITMAP *bitmap,
float cx,
float cy,
float dx,
float dy,
float angle,
int flags)

Draws a rotated version of the given bitmap to the target bitmap.  The bitmap is rotated by ‘angle’ radians counter clockwise.

The point at cx/cy inside the bitmap will be drawn at dx/dy and the bitmap is rotated around this point.

cxcenter x
cycenter y
dxdestination x
dydestination y
angleangle by which to rotate
flagssame as for al_draw_bitmap

al_draw_rotated_scaled_bitmap

void al_draw_rotated_scaled_bitmap(ALLEGRO_BITMAP *bitmap,
float cx,
float cy,
float dx,
float dy,
float xscale,
float yscale,
float angle,
int flags)

Like al_draw_rotated_bitmap, but can also scale the bitmap.

The point at cx/cy in the bitmap will be drawn at dx/dy and the bitmap is rotated and scaled around this point.

cxcenter x
cycenter y
dxdestination x
dydestination y
xscalehow much to scale on the x-axis (e.g.  2 for twice the size)
yscalehow much to scale on the y-axis
angleangle by which to rotate
flagssame as for al_draw_bitmap

al_lock_bitmap_region

ALLEGRO_LOCKED_REGION *al_lock_bitmap_region(
   ALLEGRO_BITMAP *bitmap,
   int x,
   int y,
   int width,
   int height,
   ALLEGRO_LOCKED_REGION *locked_region,
   int flags
)

Like al_lock_bitmap, but only locks a specific area of the bitmap.  If the bitmap is a display bitmap, only that area of the texture will be updated when it is unlocked.  Locking only the region you indend to modify will be faster than locking the whole bitmap.

See Also: al_lock_bitmap

al_lock_bitmap

ALLEGRO_LOCKED_REGION *al_lock_bitmap(ALLEGRO_BITMAP *bitmap,
ALLEGRO_LOCKED_REGION *locked_region,
int flags)

Lock an entire bitmap for reading or writing.  If the bitmap is a display bitmap it will be updated from system memory after the bitmap is unlocked (unless locked read only). locked_region must point to an already allocated ALLEGRO_LOCKED_REGION structure.  Returns NULL if the bitmap cannot be locked, e.g. the bitmap was locked previously and not unlocked.

Flags are

ALLEGRO_LOCK_READONLYThe locked region will not be written to.  This can be faster if the bitmap is a video texture, as it can be discarded after the lock instead of uploaded back to the card.
ALLEGRO_LOCK_WRITEONLYThe locked region will not be read from.  This can be faster if the bitmap is a video texture, as no data need to be read from the video card.  You are required to fill in all pixels before unlocking the bitmap again, so be careful when using this flag.

al_unlock_bitmap

void al_unlock_bitmap(ALLEGRO_BITMAP *bitmap)

Unlock a previously locked bitmap or bitmap region.  If the bitmap is a display bitmap, the texture will be updated to match the system memory copy (unless it was locked read only).

al_convert_mask_to_alpha

void al_convert_mask_to_alpha(ALLEGRO_BITMAP *bitmap,
ALLEGRO_COLOR mask_color)

Convert the given mask color to an alpha channel in the bitmap.  Can be used to convert older 4.2-style bitmaps with magic pink to alpha-ready bitmaps.

al_get_bitmap_width

int al_get_bitmap_width(ALLEGRO_BITMAP *bitmap)

Returns the width of a bitmap in pixels.

al_get_bitmap_height

int al_get_bitmap_height(ALLEGRO_BITMAP *bitmap)

Returns the height of a bitmap in pixels.

al_get_bitmap_format

int al_get_bitmap_format(ALLEGRO_BITMAP *bitmap)

Returns the pixel format of a bitmap.

al_get_bitmap_flags

int al_get_bitmap_flags(ALLEGRO_BITMAP *bitmap)

Return the flags user to create the bitmap.

al_create_sub_bitmap

ALLEGRO_BITMAP *al_create_sub_bitmap(ALLEGRO_BITMAP *parent,
int x,
int y,
int w,
int h)

Creates a sub-bitmap of the parent, at the specified coordinates and of the specified size.  A sub-bitmap is a bitmap that shares drawing memory with a pre-existing (parent) bitmap, but possibly with a different size and clipping settings.

If the sub-bitmap does not lie completely inside the parent bitmap, then it is automatically clipped so that it does.

The parent bitmap’s clipping rectangles are ignored.

If a sub-bitmap was not or cannot be created then NULL is returned.

Note that destroying parents of sub-bitmaps will not destroy the sub-bitmaps; instead the sub-bitmaps become invalid and should no longer be used.

al_clone_bitmap

ALLEGRO_BITMAP *al_clone_bitmap(ALLEGRO_BITMAP *bitmap)

Clone a bitmap “exactly”, formats can be different.

XXX is this supposed to be public?  --pw

al_bitmap_is_locked

Returns whether or not a bitmap is already locked.

ALLEGRO_BITMAP *al_create_bitmap(int w,
int h)
Creates a new bitmap using the bitmap format and flags for the current thread.
void al_destroy_bitmap(ALLEGRO_BITMAP *bitmap)
Destroys the given bitmap, freeing all resources used by it.
ALLEGRO_BITMAP *al_load_bitmap(char const *filename)
Load a bitmap from a file using the bitmap format and flags of the current thread.
void al_draw_bitmap(ALLEGRO_BITMAP *bitmap,
float dx,
float dy,
int flags)
Draws an unscaled, unrotated bitmap at the given position to the current target bitmap (see al_set_target_bitmap).
void al_set_target_bitmap(ALLEGRO_BITMAP *bitmap)
Select the bitmap to which all subsequent drawing operations in the calling thread will draw.
void al_draw_bitmap_region(ALLEGRO_BITMAP *bitmap,
float sx,
float sy,
float sw,
float sh,
float dx,
float dy,
int flags)
Draws a region of the given bitmap to the target bitmap.
void al_draw_scaled_bitmap(ALLEGRO_BITMAP *bitmap,
float sx,
float sy,
float sw,
float sh,
float dx,
float dy,
float dw,
float dh,
int flags)
Draws a scaled version of the given bitmap to the target bitmap.
void al_draw_rotated_bitmap(ALLEGRO_BITMAP *bitmap,
float cx,
float cy,
float dx,
float dy,
float angle,
int flags)
Draws a rotated version of the given bitmap to the target bitmap.
void al_draw_rotated_scaled_bitmap(ALLEGRO_BITMAP *bitmap,
float cx,
float cy,
float dx,
float dy,
float xscale,
float yscale,
float angle,
int flags)
Like al_draw_rotated_bitmap, but can also scale the bitmap.
ALLEGRO_LOCKED_REGION *al_lock_bitmap_region(
   ALLEGRO_BITMAP *bitmap,
   int x,
   int y,
   int width,
   int height,
   ALLEGRO_LOCKED_REGION *locked_region,
   int flags
)
Like al_lock_bitmap, but only locks a specific area of the bitmap.
ALLEGRO_LOCKED_REGION *al_lock_bitmap(ALLEGRO_BITMAP *bitmap,
ALLEGRO_LOCKED_REGION *locked_region,
int flags)
Lock an entire bitmap for reading or writing.
void al_unlock_bitmap(ALLEGRO_BITMAP *bitmap)
Unlock a previously locked bitmap or bitmap region.
void al_convert_mask_to_alpha(ALLEGRO_BITMAP *bitmap,
ALLEGRO_COLOR mask_color)
Convert the given mask color to an alpha channel in the bitmap.
int al_get_bitmap_width(ALLEGRO_BITMAP *bitmap)
Returns the width of a bitmap in pixels.
int al_get_bitmap_height(ALLEGRO_BITMAP *bitmap)
Returns the height of a bitmap in pixels.
int al_get_bitmap_format(ALLEGRO_BITMAP *bitmap)
Returns the pixel format of a bitmap.
int al_get_bitmap_flags(ALLEGRO_BITMAP *bitmap)
Return the flags user to create the bitmap.
ALLEGRO_BITMAP *al_create_sub_bitmap(ALLEGRO_BITMAP *parent,
int x,
int y,
int w,
int h)
Creates a sub-bitmap of the parent, at the specified coordinates and of the specified size.
ALLEGRO_BITMAP *al_clone_bitmap(ALLEGRO_BITMAP *bitmap)
Clone a bitmap “exactly”, formats can be different.
void al_set_new_bitmap_format(int format)
Sets the pixel format for newly created bitmaps.
void al_set_new_bitmap_flags(int flags)
Sets the flags to use for newly created bitmaps.