Graphics routines

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

Colors

ALLEGRO_COLOR

typedef struct ALLEGRO_COLOR ALLEGRO_COLOR;

Source Code

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

Examples:

al_map_rgb

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

Source Code

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

This function can be called before Allegro is initialized.

Examples:

al_map_rgb_f

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

Source Code

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

This function can be called before Allegro is initialized.

Examples:

al_map_rgba

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

Source Code

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

This function can be called before Allegro is initialized.

Examples:

al_premul_rgba

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

Source Code

This is a shortcut for al_map_rgba(r * a / 255, g * a / 255, b * a / 255, a).

By default Allegro uses pre-multiplied alpha for transparent blending of bitmaps and primitives (see al_load_bitmap_flags for a discussion of that feature). This means that if you want to tint a bitmap or primitive to be transparent you need to multiply the color components by the alpha components when you pass them to this function. For example:

int r = 255;
int g = 0;
int b = 0;
int a = 127;
ALLEGRO_COLOR c = al_premul_rgba(r, g, b, a);
/* Draw the bitmap tinted red and half-transparent. */
al_draw_tinted_bitmap(bmp, c, 0, 0, 0);

This function can be called before Allegro is initialized.

Since: 5.1.12

al_map_rgba_f

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

Source Code

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

This function can be called before Allegro is initialized.

Examples:

al_premul_rgba_f

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

Source Code

This is a shortcut for al_map_rgba_f(r * a, g * a, b * a, a).

float r = 1;
float g = 0;
float b = 0;
float a = 0.5;
ALLEGRO_COLOR c = al_premul_rgba_f(r, g, b, a);
/* Draw the bitmap tinted red and half-transparent. */
al_draw_tinted_bitmap(bmp, c, 0, 0, 0);

This function can be called before Allegro is initialized.

Since: 5.1.12

al_unmap_rgb

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

Source Code

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

This function can be called before Allegro is initialized.

Examples:

al_unmap_rgb_f

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

Source Code

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

This function can be called before Allegro is initialized.

Examples:

al_unmap_rgba

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

Source Code

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

This function can be called before Allegro is initialized.

Examples:

al_unmap_rgba_f

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

Source Code

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

This function can be called before Allegro is initialized.

Examples:

Locking and pixel formats

ALLEGRO_LOCKED_REGION

typedef struct ALLEGRO_LOCKED_REGION ALLEGRO_LOCKED_REGION;

Source Code

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;
   int format;
   int pitch;
   int pixel_size;
} ALLEGRO_LOCKED_REGION;

data points to the leftmost pixel of the first row (row 0) of the locked region. For blocked formats, this points to the leftmost block of the first row of blocks.
format indicates the pixel format of the data.
pitch gives the size in bytes of a single row (also known as the stride). The pitch may be greater than width * pixel_size due to padding; this is not uncommon. It is also not uncommon for the pitch to be negative (the bitmap may be upside down). For blocked formats, ‘row’ refers to the row of blocks, not of pixels.
pixel_size is the number of bytes used to represent a single block of pixels for the pixel format of this locked region. For most formats (and historically, this used to be true for all formats), this is just the size of a single pixel, but for blocked pixel formats this value is different.

Examples:

ALLEGRO_PIXEL_FORMAT

typedef enum ALLEGRO_PIXEL_FORMAT

Source Code

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.

Some of the pixel formats represent compressed bitmap formats. Compressed bitmaps take up less space in the GPU memory than bitmaps with regular (uncompressed) pixel formats. This smaller footprint means that you can load more resources into GPU memory, and they will be drawn somewhat faster. The compression is lossy, however, so it is not appropriate for all graphical styles: it tends to work best for images with smooth color gradations. It is possible to compress bitmaps at runtime by passing the appropriate bitmap format in al_set_new_bitmap_format and then creating, loading, cloning or converting a non-compressed bitmap. This, however, is not recommended as the compression quality differs between different GPU drivers. It is recommended to compress these bitmaps ahead of time using external tools and then load them compressed.

Unlike regular pixel formats, compressed pixel formats are not laid out in memory one pixel row at a time. Instead, the bitmap is subdivided into rectangular blocks of pixels that are then laid out in block rows. This means that regular locking functions cannot use compressed pixel formats as the destination format. Instead, you can use the blocked versions of the bitmap locking functions which do support these formats.

It is not recommended to use compressed bitmaps as target bitmaps, as that operation cannot be hardware accelerated. Due to proprietary algorithms used, it is typically impossible to create compressed memory bitmaps.

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_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_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.
ALLEGRO_PIXEL_FORMAT_RGBA_4444 - 16bit
ALLEGRO_PIXEL_FORMAT_SINGLE_CHANNEL_8 - A single 8-bit channel. A pixel value maps onto the red channel when displayed, but it is undefined how it maps onto green, blue and alpha channels. When drawing to bitmaps of this format, only the red channel is taken into account. Allegro may have to use fallback methods to render to bitmaps of this format. This pixel format is mainly intended for storing the color indices of an indexed (paletted) image, usually in conjunction with a pixel shader that maps indices to RGBA values. Since 5.1.2.
ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT1 - Compressed using the DXT1 compression algorithm. Each 4x4 pixel block is encoded in 64 bytes, resulting in 6-8x compression ratio. Only a single bit of alpha per pixel is supported. Since 5.1.9.
ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT3 - Compressed using the DXT3 compression algorithm. Each 4x4 pixel block is encoded in 128 bytes, resulting in 4x compression ratio. This format supports sharp alpha transitions. Since 5.1.9.
ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT5 - Compressed using the DXT5 compression algorithm. Each 4x4 pixel block is encoded in 128 bytes, resulting in 4x compression ratio. This format supports smooth alpha transitions. Since 5.1.9.

Examples:

al_get_pixel_size

int al_get_pixel_size(int format)

Source Code

Return the number of bytes that a pixel of the given format occupies. For blocked pixel formats (e.g. compressed formats), this returns 0.

al_get_pixel_format_bits

int al_get_pixel_format_bits(int format)

Source Code

Return the number of bits that a pixel of the given format occupies. For blocked pixel formats (e.g. compressed formats), this returns 0.

al_get_pixel_block_size

int al_get_pixel_block_size(int format)

Source Code

Return the number of bytes that a block of pixels with this format occupies.

Since: 5.1.9.

al_get_pixel_block_width

int al_get_pixel_block_width(int format)

Source Code

Return the width of the the pixel block for this format.

Since: 5.1.9.

Examples:

ex_compressed.c

al_get_pixel_block_height

int al_get_pixel_block_height(int format)

Source Code

Return the height of the the pixel block for this format.

Since: 5.1.9.

Examples:

ex_compressed.c

al_lock_bitmap

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

Source Code

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. This function also returns NULL if the format is a compressed format.

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. Use this flag if a partial number of pixels need to be written to, even if reading is not needed.

format indicates the pixel format that the returned buffer will be in. To lock in the same format as the bitmap stores its 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. If the bitmap format is compressed, using ALLEGRO_PIXEL_FORMAT_ANY will choose an implementation defined non-compressed format.

On some platforms, Allegro automatically backs up the contents of video bitmaps because they may be occasionally lost (see discussion in al_create_bitmap’s documentation). If you’re completely recreating the bitmap contents often (e.g. every frame) then you will get much better performance by creating the target bitmap with ALLEGRO_NO_PRESERVE_TEXTURE flag.

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

Examples:

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)

Source Code

Like al_lock_bitmap, but only locks a specific area of the bitmap. If the bitmap is a video 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.

Note: Using the ALLEGRO_LOCK_WRITEONLY with a blocked pixel format (i.e. formats for which al_get_pixel_block_width or al_get_pixel_block_height do not return 1) requires you to have the region be aligned to the block width for optimal performance. If it is not, then the function will have to lock the region with the ALLEGRO_LOCK_READWRITE instead in order to pad this region with valid data.

Examples:

al_unlock_bitmap

void al_unlock_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

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

Examples:

al_lock_bitmap_blocked

ALLEGRO_LOCKED_REGION *al_lock_bitmap_blocked(ALLEGRO_BITMAP *bitmap,
   int flags)

Source Code

Like al_lock_bitmap, but allows locking bitmaps with a blocked pixel format (i.e. a format for which al_get_pixel_block_width or al_get_pixel_block_height do not return 1) in that format. To that end, this function also does not allow format conversion. For bitmap formats with a block size of 1, this function is identical to calling al_lock_bitmap(bmp, al_get_bitmap_format(bmp), flags).

Note: Currently there are no drawing functions that work when the bitmap is locked with a compressed format. al_get_pixel will also not work.

Since: 5.1.9

al_lock_bitmap_region_blocked

ALLEGRO_LOCKED_REGION *al_lock_bitmap_region_blocked(ALLEGRO_BITMAP *bitmap,
   int x_block, int y_block, int width_block, int height_block, int flags)

Source Code

Like al_lock_bitmap_blocked, but allows locking a sub-region, for performance. Unlike al_lock_bitmap_region the region specified in terms of blocks and not pixels.

Since: 5.1.9

Examples:

ex_compressed.c

Bitmap creation

ALLEGRO_BITMAP

typedef struct ALLEGRO_BITMAP ALLEGRO_BITMAP;

Source Code

Abstract type representing a bitmap (2D image).

Examples:

al_create_bitmap

ALLEGRO_BITMAP *al_create_bitmap(int w, int h)

Source Code

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. Some platforms also dictate a minimum texture size, which is relevant if you plan to use this bitmap with the primitives addon. If you try to create a bitmap smaller than this, this call will not fail but the returned bitmap will be a section of a larger bitmap with the minimum size. The minimum size that will work on all platforms is 32 by 32. There is an experimental switch to turns this padding off by editing the system configuration (see min_bitmap_size key in al_get_system_config).

Some platforms do not directly support display bitmaps whose dimensions are not powers of two. Allegro handles this by creating a larger bitmap that has dimensions that are powers of two and then returning a section of that bitmap with the dimensions you requested. This can be relevant if you plan to use this bitmap with the primitives addon but shouldn’t be an issue otherwise.

If you create a bitmap without ALLEGRO_MEMORY_BITMAP set but there is no current display, a temporary memory bitmap will be created instead. You can later convert all such bitmap to video bitmap and assign to a display by calling al_convert_memory_bitmaps.

On some platforms the contents of video bitmaps may be lost when your application loses focus. Allegro has an internal mechanism to restore the contents of these video bitmaps, but it is not foolproof (sometimes bitmap contents can get lost permanently) and has performance implications. If you are using a bitmap as an intermediate buffer this mechanism may be wasteful. In this case, if you do not want Allegro to manage the bitmap contents for you, you can disable this mechanism by creating the bitmap with the ALLEGRO_NO_PRESERVE_TEXTURE flag. The bitmap contents are lost when you get the ALLEGRO_EVENT_DISPLAY_LOST and ALLEGRO_EVENT_DISPLAY_HALT_DRAWING and a should be restored when you get the ALLEGRO_EVENT_DISPLAY_FOUND and when you call al_acknowledge_drawing_resume (after ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING event). You can use those events to implement your own bitmap content restoration mechanism if Allegro’s does not work well enough for you (for example, you can reload them all from disk).

Note: The contents of a newly created bitmap are undefined - you need to clear the bitmap or make sure all pixels get overwritten before drawing it.

When you are done with using the bitmap you must call al_destroy_bitmap on it to free any resources allocated for it.

Examples:

al_create_sub_bitmap

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

Source Code

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.

The sub-bitmap may originate off or extend past the parent bitmap.

See the discussion in al_get_backbuffer about using sub-bitmaps of the backbuffer.

The parent bitmap’s clipping rectangles are ignored.

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

When you are done with using the sub-bitmap you must call al_destroy_bitmap on it to free any resources allocated for it.

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 for drawing - they still must be destroyed with al_destroy_bitmap however. It does not matter whether you destroy a sub-bitmap before or after its parent otherwise.

al_clone_bitmap

ALLEGRO_BITMAP *al_clone_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

Create a new bitmap with al_create_bitmap, and copy the pixel data from the old bitmap across. The newly created bitmap will be created with the current new bitmap flags, and not the ones that were used to create the original bitmap. If the new bitmap is a memory bitmap, its projection bitmap is reset to be orthographic.

Examples:

al_convert_bitmap

void al_convert_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

Converts the bitmap to the current bitmap flags and format. The bitmap will be as if it was created anew with al_create_bitmap but retain its contents. All of this bitmap’s sub-bitmaps are also converted. If the new bitmap type is memory, then the bitmap’s projection bitmap is reset to be orthographic.

If this bitmap is a sub-bitmap, then it, its parent and all the sibling sub-bitmaps are also converted.

Since: 5.1.0

Examples:

ex_loading_thread.c

al_convert_memory_bitmaps

void al_convert_memory_bitmaps(void)

Source Code

If you create a bitmap when there is no current display (for example because you have not called al_create_display in the current thread) and are using the ALLEGRO_CONVERT_BITMAP bitmap flag (which is set by default) then the bitmap will be created successfully, but as a memory bitmap. This function converts all such bitmaps to proper video bitmaps belonging to the current display.

Note that video bitmaps get automatically converted back to memory bitmaps when the last display is destroyed.

This operation will preserve all bitmap flags except ALLEGRO_VIDEO_BITMAP and ALLEGRO_MEMORY_BITMAP.

Since: 5.2.0

al_destroy_bitmap

void al_destroy_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

Destroys the given bitmap, freeing all resources used by it. This function does nothing if the bitmap argument is NULL.

As a convenience, if the calling thread is currently targeting the bitmap then the bitmap will be untargeted first. The new target bitmap is unspecified. (since: 5.0.10, 5.1.6)

Otherwise, it is an error to destroy a bitmap while it (or a sub-bitmap) is the target bitmap of any thread.

al_get_new_bitmap_flags

int al_get_new_bitmap_flags(void)

Source Code

Returns the flags used for newly created bitmaps.

al_get_new_bitmap_format

int al_get_new_bitmap_format(void)

Source Code

Returns the format used for newly created bitmaps.

al_set_new_bitmap_flags

void al_set_new_bitmap_flags(int flags)

Source Code

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 somewhat unoptimised.

Note: Combining ALLEGRO_VIDEO_BITMAP and ALLEGRO_MEMORY_BITMAP flags is invalid.

ALLEGRO_VIDEO_BITMAP

Creates a bitmap that resides in the video card memory. These types of bitmaps receive the greatest benefit from hardware acceleration.

Note: Creating a video bitmap will fail if there is no current display or the current display driver cannot create the bitmap. The latter will happen if for example the format or dimensions are not supported.

Note: Bitmaps created with this flag will be converted to memory bitmaps when the last display is destroyed. In most cases it is therefore easier to use the ALLEGRO_CONVERT_BITMAP flag instead.

Note: Combining ALLEGRO_VIDEO_BITMAP and ALLEGRO_MEMORY_BITMAP flags is invalid.

ALLEGRO_CONVERT_BITMAP

This is the default. It will try to create a video bitmap and if that fails create a memory bitmap. Bitmaps created with this flag when there is no active display will be converted to video bitmaps next time a display is created. They also will remain video bitmaps if the last display is destroyed and then another is created again. Since 5.1.0.

Note: You can combine this flag with ALLEGRO_MEMORY_BITMAP or ALLEGRO_VIDEO_BITMAP to force the initial type (and fail in the latter case if no video bitmap can be created) - but usually neither of those combinations is very useful.

You can use the display option ALLEGRO_AUTO_CONVERT_BITMAPS to control which displays will try to auto-convert bitmaps.

ALLEGRO_FORCE_LOCKING

Does nothing since 5.1.8. Kept for backwards compatibility only.

ALLEGRO_NO_PRESERVE_TEXTURE

Normally, every effort is taken to preserve the contents of bitmaps, since some platforms may forget them. This can take extra processing time. If you know it doesn’t matter if a bitmap keeps its pixel data, for example when it’s a temporary buffer, use this flag to tell Allegro not to attempt to preserve its contents.

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

ALLEGRO_MIN_LINEAR

When drawing a scaled down version of the bitmap, use linear filtering. This usually looks better. You can also combine it with the MIPMAP flag for even better quality.

ALLEGRO_MAG_LINEAR

When drawing a magnified version of a bitmap, use linear filtering. This will cause the picture to get blurry instead of creating a big rectangle for each pixel. It depends on how you want things to look like whether you want to use this or not.

ALLEGRO_MIPMAP

This can only be used for bitmaps whose width and height is a power of two. In that case, it will generate mipmaps and use them when drawing scaled down versions. For example if the bitmap is 64x64, then extra bitmaps of sizes 32x32, 16x16, 8x8, 4x4, 2x2 and 1x1 will be created always containing a scaled down version of the original.

Examples:

al_add_new_bitmap_flag

void al_add_new_bitmap_flag(int flag)

Source Code

A convenience function which does the same as

al_set_new_bitmap_flags(al_get_new_bitmap_flags() | flag);

Examples:

ex_blend2.cpp

al_set_new_bitmap_format

void al_set_new_bitmap_format(int format)

Source Code

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

Examples:

al_set_new_bitmap_depth

void al_set_new_bitmap_depth(int depth)
SETTER(new_bitmap_depth, depth)

Source Code

Sets the depthbuffer depth used by newly created bitmaps (on the current thread) if they are used with al_set_target_bitmap. 0 means no depth-buffer will be created when drawing into the bitmap, which is the default.

Since: 5.2.1

Unstable API: This is an experimental feature and currently only works for the OpenGL backend.

Examples:

ex_depth_target.c

al_get_new_bitmap_depth

int al_get_new_bitmap_depth(void)
GETTER(new_bitmap_depth, 0)

Source Code

Returns the value currently set with al_set_new_bitmap_depth on the current thread or 0 if none was set.

Since: 5.2.1

Unstable API: This is an experimental feature and currently only works for the OpenGL backend.

al_set_new_bitmap_samples

void al_set_new_bitmap_samples(int samples)
SETTER(new_bitmap_samples, samples)

Source Code

Sets the multi-sampling samples used by newly created bitmaps (on the current thread) if they are used with al_set_target_bitmap. 0 means multi-sampling will not be used when drawing into the bitmap, which is the default. 1 means multi-sampling will be used but only using a single sample per pixel (so usually there will be no visual difference to not using multi-sampling at all).

Note: Some platforms have restrictions on when the multi-sampling buffer for a bitmap is realized, i.e. down-scaled back to the actual bitmap dimensions. This may only happen after a call to al_set_target_bitmap. So for example:

al_set_target_bitmap(multisample);
al_clear_to_color(blue);
al_draw_line(0, 0, 100, 100, red, 1);
al_lock_bitmap(multisample, ...)
// ERROR: the contents of the bitmap will be undefined

al_set_target_bitmap(backbuffer);
al_lock_bitmap(multisample, ...)
// CORRECT: at this point, the bitmap contents are updated and
// there will be an anti-aliased line in it.

Since: 5.2.1

Unstable API: This is an experimental feature and currently only works for the OpenGL backend.

Examples:

al_get_new_bitmap_samples

int al_get_new_bitmap_samples(void)
GETTER(new_bitmap_samples, 0)

Source Code

Returns the value currently set with al_set_new_bitmap_samples on the current thread or 0 if none was set.

Since: 5.2.1

Unstable API: This is an experimental feature and currently only works for the OpenGL backend.

al_set_new_bitmap_wrap

void al_set_new_bitmap_wrap(ALLEGRO_BITMAP_WRAP u, ALLEGRO_BITMAP_WRAP v)

Source Code

Sets the texture wrapping settings for newly created bitmaps (on the current thread). Typically you take advantage of this feature either via the primitives addon (see al_draw_prim and others) or via custom shaders (see ALLEGRO_SHADER).

Note: In the context of custom shaders, Direct3D and OpenGL have different granularities for controlling this setting. Direct3D sets wrapping setting for each sampler separately, while OpenGL sets it per-texture. This interacts particularly poorly with the primitives addon which (for backwards compatibility) alters the wrapping setting. To minimize this issue, use a wrapping setting that’s not ALLEGRO_BITMAP_WRAP_DEFAULT.

Since: 5.2.8

Unstable API: This is an experimental feature.

al_get_new_bitmap_wrap

Source Code

Returns the value currently set with al_set_new_bitmap_wrap on the current thread.

Since: 5.2.8

Unstable API: This is an experimental feature.

ALLEGRO_BITMAP_WRAP

typedef enum ALLEGRO_BITMAP_WRAP {

Source Code

Controls the how the pixel color is determined from a texture querying the texture coordinates are outside the usual bounds.

ALLEGRO_BITMAP_WRAP_DEFAULT - The default behavior. This corresponds to ALLEGRO_BITMAP_WRAP_REPEAT when using the primitives addon and ALLEGRO_BITMAP_WRAP_CLAMP otherwise.
ALLEGRO_BITMAP_WRAP_REPEAT - The texture coordinates get shifted to the opposite edge that they go past.
ALLEGRO_BITMAP_WRAP_CLAMP - The texture coordinates get clamped to the edges that they go past.
ALLEGRO_BITMAP_WRAP_MIRROR - The texture coordinates get mirrored across the edges that they go past.

Examples:

Bitmap properties

al_get_bitmap_flags

int al_get_bitmap_flags(ALLEGRO_BITMAP *bitmap)

Source Code

Return the flags used to create the bitmap.

al_get_bitmap_format

int al_get_bitmap_format(ALLEGRO_BITMAP *bitmap)

Source Code

Returns the pixel format of a bitmap.

Examples:

al_get_bitmap_height

int al_get_bitmap_height(ALLEGRO_BITMAP *bitmap)

Source Code

Returns the height of a bitmap in pixels.

Examples:

al_get_bitmap_width

int al_get_bitmap_width(ALLEGRO_BITMAP *bitmap)

Source Code

Returns the width of a bitmap in pixels.

Examples:

al_get_bitmap_depth

int al_get_bitmap_depth(ALLEGRO_BITMAP *bitmap)

Source Code

Return the depthbuffer depth used by this bitmap if it is used with al_set_target_bitmap.

Since: 5.2.1

Unstable API: This is an experimental feature and currently only works for the OpenGL backend.

al_get_bitmap_samples

int al_get_bitmap_samples(ALLEGRO_BITMAP *bitmap)

Source Code

Return the multi-sampling samples used by this bitmap if it is used with al_set_target_bitmap.

Since: 5.2.1

Unstable API: This is an experimental feature and currently only works for the OpenGL backend.

al_get_pixel

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

Source Code

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.

Examples:

al_is_bitmap_locked

bool al_is_bitmap_locked(ALLEGRO_BITMAP *bitmap)

Source Code

Returns whether or not a bitmap is already locked.

al_is_compatible_bitmap

bool al_is_compatible_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

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 given display, even if it is a different display to 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)

Source Code

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

al_get_parent_bitmap

ALLEGRO_BITMAP *al_get_parent_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

Returns the bitmap this bitmap is a sub-bitmap of. Returns NULL if this bitmap is not a sub-bitmap. This function always returns the real bitmap, and never a sub-bitmap. This might NOT match what was passed to al_create_sub_bitmap. Consider this code, for instance:

ALLEGRO_BITMAP* a = al_create_bitmap(512, 512);
ALLEGRO_BITMAP* b = al_create_sub_bitmap(a, 128, 128, 256, 256);
ALLEGRO_BITMAP* c = al_create_sub_bitmap(b, 64, 64, 128, 128);
ASSERT(al_get_parent_bitmap(b) == a && al_get_parent_bitmap(c) == a);

The assertion will pass because only a is a real bitmap, and both b and c are its sub-bitmaps.

Since: 5.0.6, 5.1.2

al_get_bitmap_x

int al_get_bitmap_x(ALLEGRO_BITMAP *bitmap)

Source Code

For a sub-bitmap, return it’s x position within the parent.

Since: 5.1.12

Examples:

ex_reparent.c

al_get_bitmap_y

int al_get_bitmap_y(ALLEGRO_BITMAP *bitmap)

Source Code

For a sub-bitmap, return it’s y position within the parent.

Since: 5.1.12

Examples:

ex_reparent.c

al_reparent_bitmap

void al_reparent_bitmap(ALLEGRO_BITMAP *bitmap, ALLEGRO_BITMAP *parent,
   int x, int y, int w, int h)

Source Code

For a sub-bitmap, changes the parent, position and size. This is the same as destroying the bitmap and re-creating it with al_create_sub_bitmap - except the bitmap pointer stays the same. This has many uses, for example an animation player could return a single bitmap which can just be re-parented to different animation frames without having to re-draw the contents. Or a sprite atlas could re-arrange its sprites without having to invalidate all existing bitmaps.

Since: 5.1.12

Examples:

al_get_bitmap_blender

void al_get_bitmap_blender(int *op, int *src, int *dst)

Source Code

Returns the current blender being used by the target bitmap. You can pass NULL for values you are not interested in.

Since: 5.2.5

Unstable API: New API.

al_get_separate_bitmap_blender

void al_get_separate_bitmap_blender(int *op, int *src, int *dst, int *alpha_op, int *alpha_src, int *alpha_dst)

Source Code

Returns the current blender being used by the target bitmap. You can pass NULL for values you are not interested in.

Since: 5.2.5

Unstable API: New API.

al_get_bitmap_blend_color

ALLEGRO_COLOR al_get_bitmap_blend_color(void)

Source Code

Returns the color currently used for constant color blending on the target bitmap.

Since: 5.2.5

Unstable API: New API.

al_set_bitmap_blender

void al_set_bitmap_blender(int op, int src, int dest)

Source Code

Sets the function to use for blending when rendering to the target bitmap. If no blender is set for a given bitmap at draw time, the values set for al_set_blender/al_set_separate_blender are used instead.

To use separate functions for chroma (RGB) and alpha channels, use al_set_separate_bitmap_blender.

See al_set_blender for more information about how blending works.

Since: 5.2.5

Unstable API: New API.

Examples:

ex_blend_target.c

al_set_separate_bitmap_blender

void al_set_separate_bitmap_blender(int op, int src, int dst, int alpha_op, int alpha_src, int alpha_dst)

Source Code

Like al_set_bitmap_blender, but allows specifying a separate blending operation for the alpha channel. This is useful if your target bitmap also has an alpha channel and the two alpha channels need to be combined in a different way than the color components.

Since: 5.2.5

Unstable API: New API.

al_set_bitmap_blend_color

void al_set_bitmap_blend_color(ALLEGRO_COLOR col)

Source Code

Sets the color to use for ALLEGRO_CONST_COLOR or ALLEGRO_INVERSE_CONST_COLOR blend operations.

Since: 5.2.5

Unstable API: New API.

Examples:

ex_blend_target.c

al_reset_bitmap_blender

void al_reset_bitmap_blender(void)

Source Code

Resets the blender for this bitmap to the default. After resetting the bitmap blender, the values set for al_set_bitmap_blender/al_set_separate_bitmap_blender will be used instead.

Since: 5.2.5

Unstable API: New API.

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)

Source Code

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

Examples:

al_clear_depth_buffer

void al_clear_depth_buffer(float z)

Source Code

Clear the depth buffer (confined by the clipping rectangle) to the given value. A depth buffer is only available if it was requested with al_set_new_display_option and the requirement could be met by the al_create_display call creating the current display. Operations involving the depth buffer are also affected by al_set_render_state.

For example, if ALLEGRO_DEPTH_FUNCTION is set to ALLEGRO_RENDER_LESS then depth buffer value of 1 represents infinite distance, and thus is a good value to use when clearing the depth buffer.

Since: 5.1.2

Examples:

al_draw_bitmap

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

Source Code

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

Note: The current target bitmap must be a different bitmap. Drawing a bitmap to itself (or to a sub-bitmap of itself) or drawing a sub-bitmap to its parent (or another sub-bitmap of its parent) are not currently supported. To copy part of a bitmap into the same bitmap simply use a temporary bitmap instead.

Note: The backbuffer (or a sub-bitmap thereof) can not be transformed, blended or tinted. If you need to draw the backbuffer draw it to a temporary bitmap first with no active transformation (except translation). Blending and tinting settings/parameters will be ignored. This does not apply when drawing into a memory bitmap.

Examples:

al_draw_tinted_bitmap

void al_draw_tinted_bitmap(ALLEGRO_BITMAP *bitmap, ALLEGRO_COLOR tint,
   float dx, float dy, int flags)

Source Code

Like al_draw_bitmap but multiplies all colors in the bitmap with the given color. For example:

al_draw_tinted_bitmap(bitmap, al_map_rgba_f(0.5, 0.5, 0.5, 0.5), x, y, 0);

The above will draw the bitmap 50% transparently (r/g/b values need to be pre-multiplied with the alpha component with the default blend mode).

al_draw_tinted_bitmap(bitmap, al_map_rgba_f(1, 0, 0, 1), x, y, 0);

The above will only draw the red component of the bitmap.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

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)

Source Code

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

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

Examples:

al_draw_tinted_bitmap_region

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

Source Code

Like al_draw_bitmap_region but multiplies all colors in the bitmap with the given color.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_tinted_bitmap

Examples:

al_draw_pixel

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

Source Code

Draws a single pixel at x, y. This function, unlike al_put_pixel, does blending and, unlike al_put_blended_pixel, respects the transformations (that is, the pixel’s position is transformed, but its size is unaffected - it remains a pixel). This function can be slow if called often; if you need to draw a lot of pixels consider using al_draw_prim with ALLEGRO_PRIM_POINT_LIST from the primitives addon.

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

Note: This function may not draw exactly where you expect it to. See the pixel-precise output section on the primitives addon documentation for details on how to control exactly where the pixel is drawn.

al_draw_rotated_bitmap

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

Source Code

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 relative to the upper left corner of the bitmap will be drawn at dx/dy and the bitmap is rotated around this point. If cx,cy is 0,0 the bitmap will rotate around its upper left corner.

cx - center x (relative to the bitmap)
cy - center y (relative to the bitmap)
dx - destination x
dy - destination y
angle - angle by which to rotate (radians)
flags - same as for al_draw_bitmap

Example

float w = al_get_bitmap_width(bitmap);
float h = al_get_bitmap_height(bitmap);
al_draw_rotated_bitmap(bitmap, w / 2, h / 2, x, y, ALLEGRO_PI / 2, 0);

The above code draws the bitmap centered on x/y and rotates it 90° clockwise.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

Examples:

al_draw_tinted_rotated_bitmap

void al_draw_tinted_rotated_bitmap(ALLEGRO_BITMAP *bitmap,
   ALLEGRO_COLOR tint,
   float cx, float cy, float dx, float dy, float angle, int flags)

Source Code

Like al_draw_rotated_bitmap but multiplies all colors in the bitmap with the given color.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_tinted_bitmap

Examples:

ex_blend2.cpp

al_draw_scaled_rotated_bitmap

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

Source Code

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 (radians)
flags - same as for al_draw_bitmap

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

Examples:

al_draw_tinted_scaled_rotated_bitmap

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

Source Code

Like al_draw_scaled_rotated_bitmap but multiplies all colors in the bitmap with the given color.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_tinted_bitmap

Examples:

al_draw_tinted_scaled_rotated_bitmap_region

void al_draw_tinted_scaled_rotated_bitmap_region(ALLEGRO_BITMAP *bitmap,
   float sx, float sy, float sw, float sh,
   ALLEGRO_COLOR tint,
   float cx, float cy, float dx, float dy, float xscale, float yscale,
   float angle, int flags)

Source Code

Like al_draw_tinted_scaled_rotated_bitmap but you specify an area within the bitmap to be drawn.

You can get the same effect with a sub bitmap:

al_draw_tinted_scaled_rotated_bitmap(bitmap, sx, sy, sw, sh, tint,
    cx, cy, dx, dy, xscale, yscale, angle, flags);

/* This draws the same: */
sub_bitmap = al_create_sub_bitmap(bitmap, sx, sy, sw, sh);
al_draw_tinted_scaled_rotated_bitmap(sub_bitmap, tint, cx, cy,
    dx, dy, xscale, yscale, angle, flags);

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

Since: 5.0.6, 5.1.0

See also: al_draw_tinted_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)

Source Code

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

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

Examples:

al_draw_tinted_scaled_bitmap

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

Source Code

Like al_draw_scaled_bitmap but multiplies all colors in the bitmap with the given color.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_tinted_bitmap

Examples:

al_get_target_bitmap

ALLEGRO_BITMAP *al_get_target_bitmap(void)

Source Code

Return the target bitmap of the calling thread.

al_put_pixel

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

Source Code

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. This function is not affected by the transformations or the color blenders.

Examples:

al_put_blended_pixel

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

Source Code

Like al_put_pixel, but the pixel color is blended using the current blenders before being drawn.

Target bitmap

al_set_target_bitmap

void al_set_target_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

This function selects the bitmap to which all subsequent drawing operations in the calling thread will draw to. To return to drawing to a display, set the backbuffer of the display as the target bitmap, using al_get_backbuffer. As a convenience, you may also use al_set_target_backbuffer.

Each allegro bitmap maintains two transformation matrices associated with it for drawing onto the bitmap. There is a view matrix and a projection matrix. When you call al_set_target_bitmap, these will be made current for the bitmap, affecting global OpenGL and DirectX states depending on the driver in use.

Each video bitmap is tied to a display. When a video bitmap is set to as the target bitmap, the display that the bitmap belongs to is automatically made “current” for the calling thread (if it is not current already). Then drawing other bitmaps which are tied to the same display can be hardware accelerated.

A single display cannot be current for multiple threads simultaneously. If you need to release a display, so it is not current for the calling thread, call al_set_target_bitmap(NULL);

Setting a memory bitmap as the target bitmap will not change which display is current for the calling thread.

OpenGL note:

Framebuffer objects (FBOs) allow OpenGL to directly draw to a bitmap, which is very fast. When using an OpenGL display, if all of the following conditions are met an FBO will be created for use with the bitmap:

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

In Allegro 5.0.0, you had to be careful as an FBO would be kept around until the bitmap is destroyed or you explicitly called al_remove_opengl_fbo on the bitmap, wasting resources. In newer versions, FBOs will be freed automatically when the bitmap is no longer the target bitmap, unless you have called al_get_opengl_fbo to retrieve the FBO id.

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, 0);

An OpenGL command will be used to directly draw the line into the bitmap’s associated texture.

Examples:

al_set_target_backbuffer

void al_set_target_backbuffer(ALLEGRO_DISPLAY *display)

Source Code

Same as al_set_target_bitmap(al_get_backbuffer(display));

Examples:

al_get_current_display

ALLEGRO_DISPLAY *al_get_current_display(void)

Source Code

Return the display that is “current” for the calling thread, or NULL if there is none.

Blending modes

al_get_blender

void al_get_blender(int *op, int *src, int *dst)

Source Code

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 *op, int *src, int *dst,
   int *alpha_op, int *alpha_src, int *alpha_dst)

Source Code

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

al_get_blend_color

ALLEGRO_COLOR al_get_blend_color(void)

Source Code

Returns the color currently used for constant color blending (white by default).

Since: 5.1.12

al_set_blender

void al_set_blender(int op, int src, int dst)

Source Code

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): s = s.r, s.g, s.b, s.a. And this color is drawn to a destination, which already has a color: d = d.r, d.g, d.b, d.a.

The conceptional formula used by Allegro to draw any pixel then depends on the op parameter:

ALLEGRO_ADD

   r = d.r * df.r + s.r * sf.r
   g = d.g * df.g + s.g * sf.g
   b = d.b * df.b + s.b * sf.b
   a = d.a * df.a + s.a * sf.a

ALLEGRO_DEST_MINUS_SRC

   r = d.r * df.r - s.r * sf.r
   g = d.g * df.g - s.g * sf.g
   b = d.b * df.b - s.b * sf.b
   a = d.a * df.a - s.a * sf.a

ALLEGRO_SRC_MINUS_DEST

   r = s.r * sf.r - d.r * df.r
   g = s.g * sf.g - d.g * df.g
   b = s.b * sf.b - d.b * df.b
   a = s.a * sf.a - d.a * df.a

Valid values for the factors sf and df passed to this function are as follows, where s is the source color, d the destination color and cc the color set with al_set_blend_color (white by default)

ALLEGRO_ZERO
```
   f = 0, 0, 0, 0
```
ALLEGRO_ONE
```
   f = 1, 1, 1, 1
```
ALLEGRO_ALPHA
```
   f = s.a, s.a, s.a, s.a
```

ALLEGRO_INVERSE_ALPHA

   f = 1 - s.a, 1 - s.a, 1 - s.a, 1 - s.a

ALLEGRO_SRC_COLOR (since: 5.0.10, 5.1.0)
```
   f = s.r, s.g, s.b, s.a
```
ALLEGRO_DEST_COLOR (since: 5.0.10, 5.1.8)
```
   f = d.r, d.g, d.b, d.a
```
ALLEGRO_INVERSE_SRC_COLOR (since: 5.0.10, 5.1.0)
```
   f = 1 - s.r, 1 - s.g, 1 - s.b, 1 - s.a
```
ALLEGRO_INVERSE_DEST_COLOR (since: 5.0.10, 5.1.8)
```
   f = 1 - d.r, 1 - d.g, 1 - d.b, 1 - d.a
```
ALLEGRO_CONST_COLOR (since: 5.1.12, not supported on OpenGLES 1.0)
```
   f = cc.r, cc.g, cc.b, cc.a
```
ALLEGRO_INVERSE_CONST_COLOR (since: 5.1.12, not supported on OpenGLES 1.0)
```
   f = 1 - cc.r, 1 - cc.g, 1 - cc.b, 1 - cc.a
```

Blending examples:

So for example, to restore the default of using premultiplied alpha blending, you would use:

al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_INVERSE_ALPHA);

As formula:

r = d.r * (1 - s.a) + s.r * 1
g = d.g * (1 - s.a) + s.g * 1
b = d.b * (1 - s.a) + s.b * 1
a = d.a * (1 - s.a) + s.a * 1

If you are using non-pre-multiplied alpha, you could use

al_set_blender(ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA);

Additive blending would be achieved with

al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_ONE);

Copying the source to the destination (including alpha) unmodified

al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_ZERO);

Multiplying source and destination components

al_set_blender(ALLEGRO_ADD, ALLEGRO_DEST_COLOR, ALLEGRO_ZERO)

Tinting the source (like al_draw_tinted_bitmap)

al_set_blender(ALLEGRO_ADD, ALLEGRO_CONST_COLOR, ALLEGRO_ONE);
al_set_blend_color(al_map_rgb(0, 96, 255)); /* nice Chrysler blue */

Averaging source and destination pixels

al_set_blender(ALLEGRO_ADD, ALLEGRO_CONST_COLOR, ALLEGRO_CONST_COLOR);
al_set_blend_color(al_map_rgba_f(0.5, 0.5, 0.5, 0.5));

As formula:

r = d.r * 0 + s.r * d.r
g = d.g * 0 + s.g * d.g
b = d.b * 0 + s.b * d.b
a = d.a * 0 + s.a * d.a

Examples:

al_set_separate_blender

void al_set_separate_blender(int op, int src, int dst,
   int alpha_op, int alpha_src, int alpha_dst)

Source Code

Like al_set_blender, but allows specifying a separate blending operation for the alpha channel. This is useful if your target bitmap also has an alpha channel and the two alpha channels need to be combined in a different way than the color components.

Examples:

al_set_blend_color

void al_set_blend_color(ALLEGRO_COLOR color)

Source Code

Sets the color to use for blending when using the ALLEGRO_CONST_COLOR or ALLEGRO_INVERSE_CONST_COLOR blend functions. See al_set_blender for more information.

Since: 5.1.12

Examples:

ex_blend2.cpp

Clipping

al_get_clipping_rectangle

void al_get_clipping_rectangle(int *x, int *y, int *w, int *h)

Source Code

Gets the clipping rectangle of the target bitmap.

al_set_clipping_rectangle

void al_set_clipping_rectangle(int x, int y, int width, int height)

Source Code

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

Examples:

al_reset_clipping_rectangle

void al_reset_clipping_rectangle(void)

Source Code

Equivalent to calling `al_set_clipping_rectangle(0, 0, w, h)’ where w and h are the width and height of the target bitmap respectively.

Does nothing if there is no target bitmap.

Graphics utility functions

al_convert_mask_to_alpha

void al_convert_mask_to_alpha(ALLEGRO_BITMAP *bitmap, ALLEGRO_COLOR mask_color)

Source Code

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.

Deferred drawing

al_hold_bitmap_drawing

void al_hold_bitmap_drawing(bool hold)

Source Code

Enables or disables deferred bitmap drawing. This allows for efficient drawing of many bitmaps that share a parent bitmap, such as sub-bitmaps from a tilesheet or simply identical bitmaps. Drawing bitmaps that do not share a parent is less efficient, so it is advisable to stagger bitmap drawing calls such that the parent bitmap is the same for large number of those calls. While deferred bitmap drawing is enabled, the only functions that can be used are the bitmap drawing functions and font drawing functions. Changing the state such as the blending modes will result in undefined behaviour. One exception to this rule are the non-projection transformations. It is possible to set a new transformation while the drawing is held.

No drawing is guaranteed to take place until you disable the hold. Thus, the idiom of this function’s usage is to enable the deferred bitmap drawing, draw as many bitmaps as possible, taking care to stagger bitmaps that share parent bitmaps, and then disable deferred drawing. As mentioned above, this function also works with bitmap and truetype fonts, so if multiple lines of text need to be drawn, this function can speed things up.

al_is_bitmap_drawing_held

bool al_is_bitmap_drawing_held(void)

Source Code

Returns whether the deferred bitmap drawing mode is turned on or off.

Image I/O

al_register_bitmap_loader

bool al_register_bitmap_loader(const char *extension,
   ALLEGRO_BITMAP *(*loader)(const char *filename, int flags))

Source Code

Register a handler for al_load_bitmap. The given function will be used to handle the loading of bitmaps files with the given extension.

The extension should include the leading dot (‘.’) character. It will be matched case-insensitively.

The loader argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn’t exist.

al_register_bitmap_saver

bool al_register_bitmap_saver(const char *extension,
   bool (*saver)(const char *filename, ALLEGRO_BITMAP *bmp))

Source Code

Register a handler for al_save_bitmap. The given function will be used to handle the saving of bitmaps files with the given extension.

The extension should include the leading dot (‘.’) character. It will be matched case-insensitively.

The saver argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn’t exist.

al_register_bitmap_loader_f

bool al_register_bitmap_loader_f(const char *extension,
   ALLEGRO_BITMAP *(*fs_loader)(ALLEGRO_FILE *fp, int flags))

Source Code

Register a handler for al_load_bitmap_f. The given function will be used to handle the loading of bitmaps files with the given extension.

The extension should include the leading dot (‘.’) character. It will be matched case-insensitively.

The fs_loader argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn’t exist.

al_register_bitmap_saver_f

bool al_register_bitmap_saver_f(const char *extension,
   bool (*fs_saver)(ALLEGRO_FILE *fp, ALLEGRO_BITMAP *bmp))

Source Code

Register a handler for al_save_bitmap_f. The given function will be used to handle the saving of bitmaps files with the given extension.

The extension should include the leading dot (‘.’) character. It will be matched case-insensitively.

The saver_f argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn’t exist.

al_load_bitmap

ALLEGRO_BITMAP *al_load_bitmap(const char *filename)

Source Code

Loads an image file into a new ALLEGRO_BITMAP. The file type is determined by al_identify_bitmap, using the extension as a fallback in case identification is not possible.

Returns NULL on error.

This is the same as calling al_load_bitmap_flags with a flags parameter of 0.

Note: the core Allegro library does not support any image file formats by default. You must use the allegro_image addon, or register your own format handler.

Examples:

al_load_bitmap_flags

ALLEGRO_BITMAP *al_load_bitmap_flags(const char *filename, int flags)

Source Code

Loads an image file into a new ALLEGRO_BITMAP. The file type is determined by al_identify_bitmap, using the extension as a fallback in case identification is not possible.

Returns NULL on error.

The flags parameter may be a combination of the following constants:

ALLEGRO_NO_PREMULTIPLIED_ALPHA

By default, Allegro pre-multiplies the alpha channel of an image with the images color data when it loads it. Typically that would look something like this:

r = get_float_byte();
g = get_float_byte();
b = get_float_byte();
a = get_float_byte();

r = r * a;
g = g * a;
b = b * a;

set_image_pixel(x, y, r, g, b, a);

The reason for this can be seen in the Allegro example ex_premulalpha, ie, using pre-multiplied alpha gives more accurate color results in some cases. To use alpha blending with images loaded with pre-multiplied alpha, you would use the default blending mode, which is set with al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_INVERSE_ALPHA).

The ALLEGRO_NO_PREMULTIPLIED_ALPHA flag being set will ensure that images are not loaded with alpha pre-multiplied, but are loaded with color values direct from the image. That looks like this:

r = get_float_byte();
g = get_float_byte();
b = get_float_byte();
a = get_float_byte();

set_image_pixel(x, y, r, g, b, a);

To draw such an image using regular alpha blending, you would use al_set_blender(ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA) to set the correct blender. This has some caveats. First, as mentioned above, drawing such an image can result in less accurate color blending (when drawing an image with linear filtering on, the edges will be darker than they should be). Second, the behaviour is somewhat confusing, which is explained in the example below.

// Load and create bitmaps with an alpha channel
al_set_new_bitmap_format(ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA);
// Load some bitmap with alpha in it
bmp = al_load_bitmap("some_alpha_bitmap.png");
// We will draw to this buffer and then draw this buffer to the screen
tmp_buffer = al_create_bitmap(SCREEN_W, SCREEN_H);
// Set the buffer as the target and clear it
al_set_target_bitmap(tmp_buffer);
al_clear_to_color(al_map_rgba_f(0, 0, 0, 1));
// Draw the bitmap to the temporary buffer
al_draw_bitmap(bmp, 0, 0, 0);
// Finally, draw the buffer to the screen
// The output will look incorrect (may take close inspection
// depending on the bitmap -- it may also be very obvious)
al_set_target_bitmap(al_get_backbuffer(display));
al_draw_bitmap(tmp_buffer, 0, 0, 0);

To explain further, if you have a pixel with 0.5 alpha, and you’re using (ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA) for blending, the formula is:

a = da * dst + sa * src

Expands to:

result_a = dst_a * (1-0.5) + 0.5 * 0.5

So if you draw the image to the temporary buffer, it is blended once resulting in 0.75 alpha, then drawn again to the screen, blended in the same way, resulting in a pixel has 0.1875 as an alpha value.

ALLEGRO_KEEP_INDEX

Load the palette indices of 8-bit .bmp and .pcx files instead of the rgb colors. Since 5.1.0.

ALLEGRO_KEEP_BITMAP_FORMAT

Force the resulting ALLEGRO_BITMAP to use the same format as the file.

This is not yet honoured.

Note: the core Allegro library does not support any image file formats by default. You must use the allegro_image addon, or register your own format handler.

Since: 5.1.0

al_load_bitmap_f

ALLEGRO_BITMAP *al_load_bitmap_f(ALLEGRO_FILE *fp, const char *ident)

Source Code

Loads an image from an ALLEGRO_FILE stream into a new ALLEGRO_BITMAP. The file type is determined by al_identify_bitmap_f. If identification is not possible, the passed ‘ident’ parameter, which is a file name extension including the leading dot, is used as a fallback, if it is not NULL.

This is the same as calling al_load_bitmap_flags_f with 0 for the flags parameter.

Returns NULL on error. The file remains open afterwards.

Note: the core Allegro library does not support any image file formats by default. You must use the allegro_image addon, or register your own format handler.

Examples:

al_load_bitmap_flags_f

ALLEGRO_BITMAP *al_load_bitmap_flags_f(ALLEGRO_FILE *fp,
   const char *ident, int flags)

Source Code

The flags parameter is the same as for al_load_bitmap_flags.

Returns NULL on error. The file remains open afterwards.

Note: the core Allegro library does not support any image file formats by default. You must use the allegro_image addon, or register your own format handler.

Since: 5.1.0

al_save_bitmap

bool al_save_bitmap(const char *filename, ALLEGRO_BITMAP *bitmap)

Source Code

Saves an ALLEGRO_BITMAP to an image file. The file type is determined by the extension.

Returns true on success, false on error.

Note: the core Allegro library does not support any image file formats by default. You must use the allegro_image addon, or register your own format handler.

Examples:

al_save_bitmap_f

bool al_save_bitmap_f(ALLEGRO_FILE *fp, const char *ident,
   ALLEGRO_BITMAP *bitmap)

Source Code

Saves an ALLEGRO_BITMAP to an ALLEGRO_FILE stream. The file type is determined by the passed ‘ident’ parameter, which is a file name extension including the leading dot.

Returns true on success, false on error. The file remains open afterwards.

Note: the core Allegro library does not support any image file formats by default. You must use the allegro_image addon, or register your own format handler.

al_register_bitmap_identifier

bool al_register_bitmap_identifier(const char *extension,
   bool (*identifier)(ALLEGRO_FILE *f))

Source Code

Register an identify handler for al_identify_bitmap. The given function will be used to detect files for the given extension. It will be called with a single argument of type ALLEGRO_FILE which is a file handle opened for reading and located at the first byte of the file. The handler should try to read as few bytes as possible to safely determine if the given file contents correspond to the type with the extension and return true in that case, false otherwise. The file handle must not be closed but there is no need to reset it to the beginning.

The extension should include the leading dot (‘.’) character. It will be matched case-insensitively.

The identifier argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn’t exist.

Since: 5.1.12

al_identify_bitmap

char const *al_identify_bitmap(char const *filename)

Source Code

This works exactly as al_identify_bitmap_f but you specify the filename of the file for which to detect the type and not a file handle. The extension, if any, of the passed filename is not taken into account - only the file contents.

Since: 5.1.12

al_identify_bitmap_f

char const *al_identify_bitmap_f(ALLEGRO_FILE *fp)

Source Code

Tries to guess the bitmap file type of the open ALLEGRO_FILE by reading the first few bytes. By default Allegro cannot recognize any file types, but calling al_init_image_addon will add detection of (some of) the types it can read. You can also use al_register_bitmap_identifier to add identification for custom file types.

Returns a pointer to a static string with a file extension for the type, including the leading dot. For example “.png” or “.jpg”. Returns NULL if the bitmap type cannot be determined.

Since: 5.1.12

Render State

ALLEGRO_RENDER_STATE

typedef enum ALLEGRO_RENDER_STATE {

Source Code

Possible render states which can be set with al_set_render_state:

ALLEGRO_ALPHA_TEST: If this is set to 1, the values of ALLEGRO_ALPHA_FUNCTION and ALLEGRO_ALPHA_TEST_VALUE define a comparison function which is performed on the alpha component of each pixel. Only if it evaluates to true the pixel is written. Otherwise no subsequent processing (like depth test or blending) is performed. This can be very useful, for example if a depth buffer is used but you do not want fully transparent pixels to modify it.
ALLEGRO_ALPHA_FUNCTION: One of ALLEGRO_RENDER_FUNCTION, only used when ALLEGRO_ALPHA_TEST is 1.
ALLEGRO_ALPHA_TEST_VALUE: Only used when ALLEGRO_ALPHA_TEST is 1. Should be a value of 0 - 255.
ALLEGRO_WRITE_MASK: This determines how the framebuffer and depthbuffer are updated whenever a pixel is written (in case alpha and/or depth testing is enabled: after all such enabled tests succeed). Depth values are only written if ALLEGRO_DEPTH_TEST is 1, in addition to the write mask flag being set.
ALLEGRO_DEPTH_TEST: If this is set to 1, compare the depth value of any newly written pixels with the depth value already in the buffer, according to ALLEGRO_DEPTH_FUNCTION. Allegro primitives with no explicit z coordinate will write a value of 0 into the depth buffer.
ALLEGRO_DEPTH_FUNCTION: One of ALLEGRO_RENDER_FUNCTION, only used when ALLEGRO_DEPTH_TEST is 1.

Since: 5.1.2

ALLEGRO_RENDER_FUNCTION

typedef enum ALLEGRO_RENDER_FUNCTION {

Source Code

Possible functions are:

ALLEGRO_RENDER_NEVER
ALLEGRO_RENDER_ALWAYS
ALLEGRO_RENDER_LESS
ALLEGRO_RENDER_EQUAL
ALLEGRO_RENDER_LESS_EQUAL
ALLEGRO_RENDER_GREATER
ALLEGRO_RENDER_NOT_EQUAL
ALLEGRO_RENDER_GREATER_EQUAL

Since: 5.1.2

ALLEGRO_WRITE_MASK_FLAGS

typedef enum ALLEGRO_WRITE_MASK_FLAGS {

Source Code

Each enabled bit means the corresponding value is written, a disabled bit means it is not.

ALLEGRO_MASK_RED
ALLEGRO_MASK_GREEN
ALLEGRO_MASK_BLUE
ALLEGRO_MASK_ALPHA
ALLEGRO_MASK_DEPTH
ALLEGRO_MASK_RGB - Same as RED | GREEN | BLUE.
ALLEGRO_MASK_RGBA - Same as RGB | ALPHA.

Since: 5.1.2

al_set_render_state

void al_set_render_state(ALLEGRO_RENDER_STATE state, int value)

Source Code

Set one of several render attributes; see ALLEGRO_RENDER_STATE for details.

This function does nothing if the target bitmap is a memory bitmap.

Since: 5.1.2

Examples:

al_backup_dirty_bitmap

void al_backup_dirty_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

On some platforms, notably Windows Direct3D and Android, textures may be lost at any time for events such as display resize or switching out of the app. On those platforms, bitmaps created without the ALLEGRO_NO_PRESERVE_TEXTURE flag automatically get backed up to system memory every time al_flip_display is called.

This function gives you more control over when your bitmaps get backed up. By calling this function after modifying a bitmap, you can make sure the bitmap is backed up right away instead of during the next flip.

Since: 5.2.1

Unstable API: This API is new and subject to refinement.

al_backup_dirty_bitmaps

void al_backup_dirty_bitmaps(ALLEGRO_DISPLAY *display)

Source Code

Backs up all of a display’s bitmaps to system memory.

Since: 5.2.1

Unstable API: This API is new and subject to refinement.