Graphics

Colors
Locking and pixel formats
Bitmap creation
Bitmap properties
Drawing operations
Blending modes
Clipping
- al_get_clipping_rectangle
- al_set_clipping_rectangle
Graphics utility functions
- al_convert_mask_to_alpha

Colors

ALLEGRO_COLOR

typedef struct ALLEGRO_COLOR ALLEGRO_COLOR;

An ALLEGRO_COLOR structure describes a color in a device independant way. Use al_map_rgb et al. and al_unmap_rgb et al. to translate from and to various color representations.

al_map_rgb

ALLEGRO_COLOR al_map_rgb(
   unsigned char r, unsigned char g, unsigned char b)

Convert r, g, b (ranging from 0-255) into an ALLEGRO_COLOR, using 255 for alpha.

al_map_rgb_f

ALLEGRO_COLOR al_map_rgb_f(float r, float g, float b)

Convert r, g, b, (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR, using 1.0f for alpha.

al_map_rgba

ALLEGRO_COLOR al_map_rgba(
   unsigned char r, unsigned char g, unsigned char b, unsigned char a)

Convert r, g, b, a (ranging from 0-255) into an ALLEGRO_COLOR.

al_map_rgba_f

ALLEGRO_COLOR al_map_rgba_f(float r, float g, float b, float a)

Convert r, g, b, a (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR.

al_unmap_rgb

void al_unmap_rgb(ALLEGRO_COLOR color,
   unsigned char *r, unsigned char *g, unsigned char *b)

Retrieves components of an ALLEGRO_COLOR, ignoring alpha Components will range from 0-255.

al_unmap_rgb_f

void al_unmap_rgb_f(ALLEGRO_COLOR color, float *r, float *g, float *b)

Retrieves components of an ALLEGRO_COLOR, ignoring alpha. Components will range from 0.0f-1.0f.

al_unmap_rgba

void al_unmap_rgba(ALLEGRO_COLOR color,
   unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a)

Retrieves components of an ALLEGRO_COLOR. Components will range from 0-255.

al_unmap_rgba_f

void al_unmap_rgba_f(ALLEGRO_COLOR color,
   float *r, float *g, float *b, float *a)

Retrieves components of an ALLEGRO_COLOR. Components will range from 0.0f-1.0f.

Locking and pixel formats

ALLEGRO_LOCKED_REGION

typedef struct ALLEGRO_LOCKED_REGION ALLEGRO_LOCKED_REGION;

Users who wish to manually edit or read from a bitmap are required to lock it first. The ALLEGRO_LOCKED_REGION structure represents the locked region of the bitmap. This call will work with any bitmap, including memory bitmaps.

typedef struct ALLEGRO_LOCKED_REGION {
        void *data; // the bitmap data
        int format; // the pixel format of the data
        int pitch;  // the size in bytes of a single line
                    // pitch may be greater than pixel_size*bitmap->w
                    // i.e. padded with extra bytes
}

ALLEGRO_PIXEL_FORMAT

typedef enum ALLEGRO_PIXEL_FORMAT

Pixel formats. Each pixel format specifies the exact size and bit layout of a pixel in memory. Components are specified from high bits to low bits, so for example a fully opaque red pixel in ARGB_8888 format is 0xFFFF0000.

Note:

The pixel format is independent of endianness. That is, in the above example you can always get the red component with

(pixel & 0x00ff0000) >> 16

But you can not rely on this code:

*(pixel + 2)

It will return the red component on little endian systems, but the green component on big endian systems.

Also note that Allegro's naming is different from OpenGL naming here, where a format of GL_RGBA8 merely defines the component order and the exact layout including endianness treatment is specified separately. Usually GL_RGBA8 will correspond to ALLEGRO_PIXEL_ABGR_8888 though on little endian systems, so care must be taken (note the reversal of RGBA <-> ABGR).

The only exception to this ALLEGRO_PIXEL_FORMAT_ABGR_8888_LE which will always have the components as 4 bytes corresponding to red, green, blue and alpha, in this order, independent of the endianness.

Format Notes
ALLEGRO_PIXEL_FORMAT_ANY	Let the driver choose a format. This is the default format at program start.
ALLEGRO_PIXEL_FORMAT_ANY_NO_ALPHA	Let the driver choose a format without alpha.
ALLEGRO_PIXEL_FORMAT_ANY_WITH_ALPHA	Let the driver choose a format with alpha.
ALLEGRO_PIXEL_FORMAT_ANY_15_NO_ALPHA	Let the driver choose a 15 bit format without alpha.
ALLEGRO_PIXEL_FORMAT_ANY_15_WITH_ALPHA	Let the driver choose a 15 bit format with alpha.
ALLEGRO_PIXEL_FORMAT_ANY_16_NO_ALPHA	Let the driver choose a 16 bit format without alpha.
ALLEGRO_PIXEL_FORMAT_ANY_16_WITH_ALPHA	Let the driver choose a 16 bit format with alpha.
ALLEGRO_PIXEL_FORMAT_ANY_24_NO_ALPHA	Let the driver choose a 24 bit format without alpha.
ALLEGRO_PIXEL_FORMAT_ANY_24_WITH_ALPHA	Let the driver choose a 24 bit format with alpha.
ALLEGRO_PIXEL_FORMAT_ANY_32_NO_ALPHA	Let the driver choose a 32 bit format without alpha.
ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA	Let the driver choose a 32 bit format with alpha.
ALLEGRO_PIXEL_FORMAT_ARGB_8888	32 bit
ALLEGRO_PIXEL_FORMAT_RGBA_8888	32 bit
ALLEGRO_PIXEL_FORMAT_ARGB_4444	16 bit
ALLEGRO_PIXEL_FORMAT_RGB_888	24 bit
ALLEGRO_PIXEL_FORMAT_RGB_565	16 bit
ALLEGRO_PIXEL_FORMAT_RGB_555	15 bit
ALLEGRO_PIXEL_FORMAT_RGBA_5551	16 bit
ALLEGRO_PIXEL_FORMAT_ARGB_1555	16 bit
ALLEGRO_PIXEL_FORMAT_ABGR_8888	32 bit
ALLEGRO_PIXEL_FORMAT_XBGR_8888	32 bit
ALLEGRO_PIXEL_FORMAT_BGR_888	24 bit
ALLEGRO_PIXEL_FORMAT_BGR_565	16 bit
ALLEGRO_PIXEL_FORMAT_BGR_555	15 bit
ALLEGRO_PIXEL_FORMAT_RGBX_8888	32 bit
ALLEGRO_PIXEL_FORMAT_XRGB_8888	32 bit
ALLEGRO_PIXEL_FORMAT_ABGR_F32	128 bit
ALLEGRO_PIXEL_FORMAT_ABGR_8888_LE	Like the version without _LE, but the component order is guaranteed to be red, green, blue, alpha. This only makes a difference on big endian systems, on little endian it is just an alias.

al_get_pixel_size

int al_get_pixel_size(int format)

Return the number of bytes that a pixel of the given format occupies.

al_get_pixel_format_bits

int al_get_pixel_format_bits(int format)

Return the number of bits that a pixel of the given format occupies.

al_lock_bitmap

ALLEGRO_LOCKED_REGION *al_lock_bitmap(ALLEGRO_BITMAP *bitmap, int format, 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). Returns NULL if the bitmap cannot be locked, e.g. the bitmap was locked previously and not unlocked.

Flags are:

ALLEGRO_LOCK_READONLY - The 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_WRITEONLY - The 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.
ALLEGRO_LOCK_READWRITE - The locked region can be written to and read from.

'format' indicates the pixel format that the returned buffer will be in. To lock in the same format as the bitmap stores it's data internally, call with al_get_bitmap_format(bitmap) as the format or use ALLEGRO_PIXEL_FORMAT_ANY. Locking in the native format will usually be faster.

Note:

While a bitmap is locked, you can not use any drawing operations on it (with the sole exception of al_put_pixel and al_draw_pixel).

al_lock_bitmap_region

ALLEGRO_LOCKED_REGION *al_lock_bitmap_region(ALLEGRO_BITMAP *bitmap,
    int x, int y,
    int width, int height,
        int format,
    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.

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).

Bitmap creation

ALLEGRO_BITMAP

typedef struct ALLEGRO_BITMAP ALLEGRO_BITMAP;

Abstract type representing a bitmap (2D image).

al_clone_bitmap

ALLEGRO_BITMAP *al_clone_bitmap(ALLEGRO_BITMAP *bitmap)

Clone a bitmap "exactly", formats can be different.

XXX document this better

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.

If a display bitmap is created, there may be limitations on the allowed dimensions. For example a DirectX or OpenGL backend usually has a maximum allowed texture size - so if bitmap creation fails for very large dimensions, you may want to re-try with a smaller 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_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_get_new_bitmap_flags

int al_get_new_bitmap_flags(void)

Returns the flags used for newly created bitmaps.

al_get_new_bitmap_format

int al_get_new_bitmap_format(void)

Returns the format used for newly created bitmaps.

al_set_new_bitmap_flags

void al_set_new_bitmap_flags(int flags)

Sets the flags to use for newly created bitmaps. Valid flags are:

ALLEGRO_MEMORY_BITMAP - Create a bitmap residing in system memory. Operations on, and with, memory bitmaps will not be hardware accelerated. However, direct pixel access can be relatively quick compared to video bitmaps, which depend on the display driver in use. Note: Allegro's software rendering routines are currently very unoptimised.
ALLEGRO_KEEP_BITMAP_FORMAT - Only used when loading bitmaps from disk files, forces the resulting ALLEGRO_BITMAP to use the same format as the file.
ALLEGRO_FORCE_LOCKING - When drawing to a bitmap with this flag set, always use pixel locking and draw to it using Allegro's software drawing primitives. This should never be used if you plan to draw to the bitmap using Allegro's graphics primitives as it would cause severe performance penalties. However if you know that the bitmap will only ever be accessed by locking it, no unneeded FBOs will be created for it in the OpenGL drivers.
ALLEGRO_NO_PRESERVE_TEXTURE - Normally, every effort is taken to preserve the contents of bitmaps since some drivers may forget them. This can take extra time. If you know it doesn't matter if a bitmap keeps its image, for example a temporary buffer, use this flag to tell Allegro not to attempt to preserve the contents of bitmaps created after this flag is set. This can lead to speed improvements in your program.
ALLEGRO_ALPHA_TEST - This is a driver hint only. It tells the graphics driver to do alpha testing instead of alpha blending on bitmaps created with this flag. Alpha testing is usually faster and preferred if your bitmaps have only one level of alpha (0). This flag is currently not widely implemented (i.e., only for memory bitmaps).

al_set_new_bitmap_format

void al_set_new_bitmap_format(int format)

Sets the pixel format for newly created bitmaps. The default format is 0 and means the display driver will choose the best format.

Bitmap properties

al_get_bitmap_flags

int al_get_bitmap_flags(ALLEGRO_BITMAP *bitmap)

Return the flags user to create the bitmap.

al_get_bitmap_format

int al_get_bitmap_format(ALLEGRO_BITMAP *bitmap)

Returns the pixel format of a bitmap.

al_get_bitmap_height

int al_get_bitmap_height(ALLEGRO_BITMAP *bitmap)

Returns the height of a bitmap in pixels.

al_get_bitmap_width

int al_get_bitmap_width(ALLEGRO_BITMAP *bitmap)

Returns the width of a bitmap in pixels.

al_get_pixel

ALLEGRO_COLOR al_get_pixel(ALLEGRO_BITMAP *bitmap, int x, int y)

Get a pixel's color value from the specified bitmap. This operation is slow on non-memory bitmaps. Consider locking the bitmap if you are going to use this function multiple times on the same bitmap.

al_is_bitmap_locked

bool al_is_bitmap_locked(ALLEGRO_BITMAP *bitmap)

Returns whether or not a bitmap is already locked.

al_is_compatible_bitmap

bool al_is_compatible_bitmap(ALLEGRO_BITMAP *bitmap)

D3D and OpenGL allow sharing a texture in a way so it can be used for multiple windows. Each ALLEGRO_BITMAP created with al_create_bitmap however is usually tied to a single ALLEGRO_DISPLAY. This function can be used to know if the bitmap is compatible with the current display, even if it is another display than the one it was created with. It returns true if the bitmap is compatible (things like a cached texture version can be used) and false otherwise (blitting in the current display will be slow).

The only time this function is useful is if you are using multiple windows and need accelerated blitting of the same bitmaps to both.

Returns true if the bitmap is compatible with the current display, false otherwise. If there is no current display, false is returned.

al_is_sub_bitmap

bool al_is_sub_bitmap(ALLEGRO_BITMAP *bitmap)

Returns true if the specified bitmap is a sub-bitmap, false otherwise.

Drawing operations

All drawing operations draw to the current "target bitmap" of the current thread. Initially, the target bitmap will be the backbuffer of the last display created in a thread.

al_clear_to_color

void al_clear_to_color(ALLEGRO_COLOR color)

Clear the complete target bitmap, but confined by the clipping rectangle.

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_HORIZONTAL - flip the bitmap about the y-axis
ALLEGRO_FLIP_VERTICAL - flip 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.

sx - source x
sy - source y
sw - source width (width of region to blit)
sh - source height (height of region to blit)
dx - destination x
dy - destination y
flags - same as for al_draw_bitmap

al_draw_pixel

void al_draw_pixel(float x, float y, ALLEGRO_COLOR color)

Draws a single pixel at x, y. This function, unlike al_put_pixel, does blending. This operation is slow on non-memory bitmaps. Consider locking the bitmap if you are going to use this function multiple times on the same bitmap.

x - destination x
y - destination y
color - color of the pixel

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 clockwise.

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

cx - center x
cy - center y
dx - destination x
dy - destination y
angle - angle by which to rotate
flags - same 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.

cx - center x
cy - center y
dx - destination x
dy - destination y
xscale - how much to scale on the x-axis (e.g. 2 for twice the size)
yscale - how much to scale on the y-axis
angle - angle by which to rotate
flags - same 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.

sx - source x
sy - source y
sw - source width
sh - source height
dx - destination x
dy - destination y
dw - destination width
dh - destination height
flags - same as for al_draw_bitmap

al_get_target_bitmap

ALLEGRO_BITMAP *al_get_target_bitmap(void)

Return the target bitmap of the current display.

al_put_pixel

void al_put_pixel(int x, int y, ALLEGRO_COLOR color)

Draw a single pixel on the target bitmap. This operation is slow on non-memory bitmaps. Consider locking the bitmap if you are going to use this function multiple times on the same bitmap.

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. Select the backbuffer (see al_get_backbuffer) to return to drawing to the screen normally.

OpenGL note:

Framebuffer objects (FBOs) allow OpenGL to directly draw to a bitmap, which is very fast. However, each created FBO needs additional resources, therefore an FBO is not automatically assigned to each non-memory bitmap when it is created (as is done with textures).

When using an OpenGL display, only if all of the following conditions are met an FBO will be created for the bitmap:

The GL_EXT_framebuffer_object OpenGL extension is available.
The bitmap is not a memory bitmap.
The bitmap is not currently locked.

Once created, the FBO is kept around until the bitmap is destroyed or you explicitely call al_remove_opengl_fbo on the bitmap.

In the following example, no FBO will be created:

lock = al_lock_bitmap(bitmap);
al_set_target_bitmap(bitmap);
al_put_pixel(x, y, color);
al_unlock_bitmap(bitmap);

The above allows using al_put_pixel on a locked bitmap without creating an FBO.

In this example an FBO is created however:

al_set_target_bitmap(bitmap);
al_draw_line(x1, y1, x2, y2, color);

And an OpenGL command will be used to directly draw the line into the bitmap's associated texture.

Blending modes

al_get_blender

void al_get_blender(int *src, int *dst, ALLEGRO_COLOR *color)

Returns the active blender for the current thread. You can pass NULL for values you are not interested in.

al_get_separate_blender

void al_get_separate_blender(int *src, int *dst, int *alpha_src,
   int *alpha_dst, ALLEGRO_COLOR *color)

Returns the active blender for the current thread. You can pass NULL for values you are not interested in.

al_set_blender

void al_set_blender(int src, int dst, ALLEGRO_COLOR color)

Sets the function to use for blending for the current thread.

Blending means, the source and destination colors are combined in drawing operations.

Assume, the source color (e.g. color of a rectangle to draw, or pixel of a bitmap to draw), is given as its red/green/blue/alpha components (if the bitmap has no alpha, it always is assumed to be fully opaque, so 255 for 8-bit or 1.0 for floating point): sr, sg, sb, sa. And this color is drawn to a destination, which already has a color: dr, dg, db, da.

Blending formula: The conceptional formula used by Allegro to draw any pixel then is

r = dr * dst + sr * src
g = dg * dst + sg * src
b = db * dst + sb * src
a = da * dst + sa * src

Blending functions: Valid values for and passed to this function are

ALLEGRO_ZERO - src, dst = 0
ALLEGRO_ONE - src, dst = 1
ALLEGRO_ALPHA - src, dst = sa
ALLEGRO_INVERSE_ALPHA - src, dst = 1 - sa

The color parameter specified the blend color, it is multipled with the source color before the above blending operation.

Blending examples: So for example, to restore the default of using alpha blending, you would use (pseudo code)

al_set_blender(ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA, {1, 1, 1, 1})

If in addition you want to draw half transparently

al_set_blender(ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA, {1, 1, 1, 0.5})

Additive blending would be achieved with

al_set_blender(ALLEGRO_ONE, ALLEGRO_ONE, {1, 1, 1, 1})

Copying the source to the destination (including alpha) unmodified

al_set_blender(ALLEGRO_ONE, ALLEGRO_ZERO, {1, 1, 1, 1})

al_set_separate_blender

void al_set_separate_blender(int src, int dst, int alpha_src,
   int alpha_dst, ALLEGRO_COLOR color)

Like al_set_blender, but allows specifying a separate blending operation for the alpha channel.

Clipping

al_get_clipping_rectangle

/* XXX this seems like it belongs in bitmap_new.c */
void al_get_clipping_rectangle(int *x, int *y, int *w, int *h)

Gets the clipping rectangle of the target bitmap.

al_set_clipping_rectangle

/* XXX this seems like it belongs in bitmap_new.c */
void al_set_clipping_rectangle(int x, int y, int width, int height)

Set the region of the target bitmap or display that pixels get clipped to. The default is to clip pixels to the entire bitmap.

Graphics utility functions

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.