# Graphics routines

These functions are declared in the main Allegro header file:

~~~~c
 #include <allegro5/allegro.h>
~~~~

## Colors

### API: ALLEGRO_COLOR

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.

### API: al_map_rgb

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

See also: [al_map_rgba], [al_map_rgba_f], [al_map_rgb_f]

### API: al_map_rgb_f

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

See also: [al_map_rgba], [al_map_rgb], [al_map_rgba_f]

### API: al_map_rgba

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

See also: [al_map_rgb], [al_premul_rgba], [al_map_rgb_f]

### API: al_premul_rgba

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:

~~~~c
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);
~~~~

Since: 5.1.12

See also: [al_map_rgba], [al_premul_rgba_f]

### API: al_map_rgba_f

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

See also: [al_map_rgba], [al_premul_rgba_f], [al_map_rgb_f]

### API: al_premul_rgba_f

This is a shortcut for [al_map_rgba_f]\(r * a, g * a, b * a, 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:

~~~~c
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);
~~~~

Since: 5.1.12

See also: [al_map_rgba_f], [al_premul_rgba]

### API: al_unmap_rgb

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

See also: [al_unmap_rgba], [al_unmap_rgba_f], [al_unmap_rgb_f]

### API: al_unmap_rgb_f

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

See also: [al_unmap_rgba], [al_unmap_rgb], [al_unmap_rgba_f]

### API: al_unmap_rgba

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

See also: [al_unmap_rgb], [al_unmap_rgba_f], [al_unmap_rgb_f]

### API: al_unmap_rgba_f

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

See also: [al_unmap_rgba], [al_unmap_rgb], [al_unmap_rgb_f]



## Locking and pixel formats

### API: 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.

~~~~c
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.

See also: [al_lock_bitmap], [al_lock_bitmap_region], [al_unlock_bitmap],
[ALLEGRO_PIXEL_FORMAT]

### API: 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
>
> ~~~~c
> (pixel & 0x00ff0000) >> 16
> ~~~~
>
> But you can *not* rely on this code:
>
> ~~~~c
> *(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.

See also: [al_set_new_bitmap_format], [al_get_bitmap_format]

### API: al_get_pixel_size

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

See also: [ALLEGRO_PIXEL_FORMAT], [al_get_pixel_format_bits]

### API: al_get_pixel_format_bits

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

See also: [ALLEGRO_PIXEL_FORMAT], [al_get_pixel_size]

### API: al_get_pixel_block_size

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

Since: 5.1.9.

See also: [ALLEGRO_PIXEL_FORMAT], [al_get_pixel_block_width], [al_get_pixel_block_height]

### API: al_get_pixel_block_width

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

Since: 5.1.9.

See also: [ALLEGRO_PIXEL_FORMAT], [al_get_pixel_block_size], [al_get_pixel_block_height]

### API: al_get_pixel_block_height

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

Since: 5.1.9.

See also: [ALLEGRO_PIXEL_FORMAT], [al_get_pixel_block_size], [al_get_pixel_block_width]

### API: al_lock_bitmap

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

See also: [ALLEGRO_LOCKED_REGION], [ALLEGRO_PIXEL_FORMAT],
[al_unlock_bitmap], [al_lock_bitmap_region], [al_lock_bitmap_blocked],
[al_lock_bitmap_region_blocked]

### API: al_lock_bitmap_region

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.

See also: [ALLEGRO_LOCKED_REGION], [ALLEGRO_PIXEL_FORMAT], [al_unlock_bitmap]

### API: al_unlock_bitmap

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

See also: [al_lock_bitmap], [al_lock_bitmap_region], [al_lock_bitmap_blocked],
[al_lock_bitmap_region_blocked]

### API: al_lock_bitmap_blocked

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

See also: [al_lock_bitmap], [al_lock_bitmap_region_blocked]

### API: al_lock_bitmap_region_blocked

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

See also: [al_lock_bitmap_region], [al_lock_bitmap_blocked]

## Bitmap creation

### API: ALLEGRO_BITMAP

Abstract type representing a bitmap (2D image).

### API: al_create_bitmap

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.

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.

See also: [al_set_new_bitmap_format], [al_set_new_bitmap_flags],
[al_clone_bitmap], [al_create_sub_bitmap],
[al_convert_memory_bitmaps], [al_destroy_bitmap]

### API: al_create_sub_bitmap

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.

See also: [al_create_bitmap]

### API: al_clone_bitmap

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.

See also: [al_create_bitmap], [al_set_new_bitmap_format],
[al_set_new_bitmap_flags], [al_convert_bitmap]

### API: al_convert_bitmap

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

See also: [al_create_bitmap], [al_set_new_bitmap_format],
[al_set_new_bitmap_flags], [al_clone_bitmap]

### API: al_convert_memory_bitmaps

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

See also: [al_convert_bitmap], [al_create_bitmap]

### API: al_destroy_bitmap

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.

See also: [al_create_bitmap]

### API: al_get_new_bitmap_flags

Returns the flags used for newly created bitmaps.

See also: [al_set_new_bitmap_flags]

### API: al_get_new_bitmap_format

Returns the format used for newly created bitmaps.

See also: [ALLEGRO_PIXEL_FORMAT], [al_set_new_bitmap_format]

### API: al_set_new_bitmap_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 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.

See also: [al_get_new_bitmap_flags], [al_get_bitmap_flags]

### API: al_add_new_bitmap_flag

A convenience function which does the same as

~~~~c
al_set_new_bitmap_flags(al_get_new_bitmap_flags() | flag);
~~~~

See also: [al_set_new_bitmap_flags], [al_get_new_bitmap_flags], [al_get_bitmap_flags]

### API: al_set_new_bitmap_format

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.

See also: [ALLEGRO_PIXEL_FORMAT], [al_get_new_bitmap_format],
[al_get_bitmap_format]

### API: al_set_new_bitmap_depth

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.

### API: al_get_new_bitmap_depth

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.

### API: al_set_new_bitmap_samples

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.

### API: al_get_new_bitmap_samples

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.

## Bitmap properties

### API: al_get_bitmap_flags

Return the flags used to create the bitmap.

See also: [al_set_new_bitmap_flags]

### API: al_get_bitmap_format

Returns the pixel format of a bitmap.

See also: [ALLEGRO_PIXEL_FORMAT], [al_set_new_bitmap_flags]

### API: al_get_bitmap_height

Returns the height of a bitmap in pixels.

### API: al_get_bitmap_width

Returns the width of a bitmap in pixels.

### API: al_get_bitmap_depth

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.

### API: al_get_bitmap_samples

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.

### API: al_get_pixel

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.

See also: [ALLEGRO_COLOR], [al_put_pixel], [al_lock_bitmap]

### API: al_is_bitmap_locked

Returns whether or not a bitmap is already locked.

See also: [al_lock_bitmap], [al_lock_bitmap_region], [al_unlock_bitmap]

### API: al_is_compatible_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 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.

### API: al_is_sub_bitmap

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

See also: [al_create_sub_bitmap], [al_get_parent_bitmap]

### API: al_get_parent_bitmap

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:

~~~~c
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

See also: [al_create_sub_bitmap], [al_is_sub_bitmap]

### API: al_get_bitmap_x

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

See also: [al_create_sub_bitmap], [al_get_parent_bitmap], [al_get_bitmap_y]

Since: 5.1.12

### API: al_get_bitmap_y

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

See also: [al_create_sub_bitmap], [al_get_parent_bitmap], [al_get_bitmap_x]

Since: 5.1.12

### API: al_reparent_bitmap

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.

See also: [al_create_sub_bitmap], [al_get_parent_bitmap]

Since: 5.1.12

### API: al_get_bitmap_blender

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.

See also: [al_set_bitmap_blender], [al_get_separate_bitmap_blender]

### API: al_get_separate_bitmap_blender

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.

See also: [al_set_separate_bitmap_blender], [al_get_bitmap_blender]

### API: al_get_bitmap_blend_color

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

Since: 5.2.5

> *[Unstable API]:* New API.

See also: [al_set_bitmap_blend_color]

### API: al_set_bitmap_blender

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.

See also: [al_set_separate_bitmap_blender], [al_reset_bitmap_blender]

Since: 5.2.5

> *[Unstable API]:* New API.

### API: al_set_separate_bitmap_blender

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.

See also: [al_set_bitmap_blender], [al_reset_bitmap_blender]

### API: al_set_bitmap_blend_color

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

Since: 5.2.5

> *[Unstable API]:* New API.

See also: [al_set_bitmap_blender], [al_reset_bitmap_blender]

### API: al_reset_bitmap_blender

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.

See also: [al_set_bitmap_blender]

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

### API: al_clear_to_color

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

See also: [ALLEGRO_COLOR], [al_set_clipping_rectangle], [al_clear_depth_buffer]

### API: al_clear_depth_buffer

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

See also: [al_clear_to_color], [al_set_clipping_rectangle],
[al_set_render_state], [al_set_new_display_option]

### API: al_draw_bitmap

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.

See also: [al_draw_bitmap_region], [al_draw_scaled_bitmap],
[al_draw_rotated_bitmap], [al_draw_scaled_rotated_bitmap]

### API: al_draw_tinted_bitmap

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

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

~~~~c
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.

See also: [al_draw_bitmap]

### API: al_draw_bitmap_region

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.

See also: [al_draw_bitmap], [al_draw_scaled_bitmap],
[al_draw_rotated_bitmap], [al_draw_scaled_rotated_bitmap]

### API: al_draw_tinted_bitmap_region

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]

### API: al_draw_pixel

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
<a href="primitives.html#pixel-precise-output">pixel-precise output section</a> on the
primitives addon documentation for details on how to control exactly where the
pixel is drawn. 

See also: [ALLEGRO_COLOR], [al_put_pixel]

### API: al_draw_rotated_bitmap

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

~~~~c
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.

See also: [al_draw_bitmap], [al_draw_bitmap_region],
[al_draw_scaled_bitmap], [al_draw_scaled_rotated_bitmap]

### API: al_draw_tinted_rotated_bitmap

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]

### API: al_draw_scaled_rotated_bitmap

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.

See also: [al_draw_bitmap], [al_draw_bitmap_region], [al_draw_scaled_bitmap],
[al_draw_rotated_bitmap]

### API: al_draw_tinted_scaled_rotated_bitmap

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]

### API: al_draw_tinted_scaled_rotated_bitmap_region

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:

~~~~c
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]

### API: al_draw_scaled_bitmap

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.

See also: [al_draw_bitmap], [al_draw_bitmap_region], [al_draw_rotated_bitmap],
[al_draw_scaled_rotated_bitmap],

### API: al_draw_tinted_scaled_bitmap

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]

### API: al_get_target_bitmap

Return the target bitmap of the calling thread.

See also: [al_set_target_bitmap]

### API: al_put_pixel

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.

See also: [ALLEGRO_COLOR], [al_get_pixel], [al_put_blended_pixel], [al_lock_bitmap]

### API: al_put_blended_pixel

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

See also: [ALLEGRO_COLOR], [al_put_pixel]

## Target bitmap

### API: al_set_target_bitmap

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.

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.

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:

~~~~c
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:

~~~~c
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.

See also: [al_get_target_bitmap], [al_set_target_backbuffer]

### API: al_set_target_backbuffer

Same as `al_set_target_bitmap(al_get_backbuffer(display));`

See also: [al_set_target_bitmap], [al_get_backbuffer]

### API: al_get_current_display

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

See also: [al_set_target_bitmap]



## Blending modes

### API: al_get_blender

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

See also: [al_set_blender], [al_get_separate_blender]

### API: al_get_separate_blender

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

See also: [al_set_separate_blender], [al_get_blender]

### API: al_get_blend_color

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

See also: [al_set_blend_color], [al_set_blender]

Since: 5.1.12

### API: al_set_blender

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:

~~~~c
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

~~~~c
al_set_blender(ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA);
~~~~

Additive blending would be achieved with

~~~~c
al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_ONE);
~~~~

Copying the source to the destination (including alpha) unmodified

~~~~c
al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_ZERO);
~~~~

Multiplying source and destination components

~~~~c
al_set_blender(ALLEGRO_ADD, ALLEGRO_DEST_COLOR, ALLEGRO_ZERO)
~~~~

Tinting the source (like [al_draw_tinted_bitmap])

~~~~c
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

~~~~c
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

See also: [al_set_separate_blender], [al_set_blend_color], [al_get_blender]

### API: al_set_separate_blender

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.

See also: [al_set_blender], [al_get_blender], [al_get_separate_blender]

### API: al_set_blend_color

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.

See also: [al_set_blender], [al_get_blend_color]

Since: 5.1.12


## Clipping

### API: al_get_clipping_rectangle

Gets the clipping rectangle of the target bitmap.

See also: [al_set_clipping_rectangle]

### API: al_set_clipping_rectangle

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

See also: [al_get_clipping_rectangle], [al_reset_clipping_rectangle]

### API: al_reset_clipping_rectangle

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.

See also: [al_set_clipping_rectangle]

Since: 5.0.6, 5.1.0



## Graphics utility functions

### API: al_convert_mask_to_alpha

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.

See also: [ALLEGRO_COLOR]

## Deferred drawing

### API: al_hold_bitmap_drawing

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.

See also: [al_is_bitmap_drawing_held]

### API: al_is_bitmap_drawing_held

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

See also: [al_hold_bitmap_drawing]



## Image I/O

### API: al_register_bitmap_loader

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.

See also: [al_register_bitmap_saver], [al_register_bitmap_loader_f]

### API: al_register_bitmap_saver

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.

See also: [al_register_bitmap_loader], [al_register_bitmap_saver_f]

### API: al_register_bitmap_loader_f

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.

See also: [al_register_bitmap_loader]

### API: al_register_bitmap_saver_f

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.

See also: [al_register_bitmap_saver]

### API: al_load_bitmap

Loads an image file into a new [ALLEGRO_BITMAP].
The file type is determined by the extension, except if the file has
no extension in which case [al_identify_bitmap] is used instead.

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.

See also: [al_load_bitmap_flags], [al_load_bitmap_f],
[al_register_bitmap_loader], [al_set_new_bitmap_format],
[al_set_new_bitmap_flags], [al_init_image_addon]

### API: al_load_bitmap_flags

Loads an image file into a new [ALLEGRO_BITMAP].
The file type is determined by the extension, except if the file has
no extension in which case [al_identify_bitmap] is used instead.

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:

    ~~~~c
    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:

    ~~~~c
    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.

    ~~~~c
    // 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

See also: [al_load_bitmap]

### API: al_load_bitmap_f

Loads an image from an [ALLEGRO_FILE] stream into a new [ALLEGRO_BITMAP].
The file type is determined by the passed 'ident' parameter, which is a file
name extension including the leading dot. If (and only if) 'ident' is
NULL, the file type is determined with [al_identify_bitmap_f] instead.

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.

See also: [al_load_bitmap_flags_f], [al_load_bitmap],
[al_register_bitmap_loader_f], [al_init_image_addon]

### API: al_load_bitmap_flags_f

Loads an image from an [ALLEGRO_FILE] stream into a new [ALLEGRO_BITMAP].
The file type is determined by the passed 'ident' parameter, which is a file
name extension including the leading dot. If (and only if) 'ident' is
NULL, the file type is determined with [al_identify_bitmap_f] instead.

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

See also: [al_load_bitmap_f], [al_load_bitmap_flags]

### API: al_save_bitmap

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.

See also: [al_save_bitmap_f], [al_register_bitmap_saver], [al_init_image_addon]

### API: al_save_bitmap_f

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.

See also: [al_save_bitmap], [al_register_bitmap_saver_f], [al_init_image_addon]

### API: al_register_bitmap_identifier

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

See also: [al_identify_bitmap]

### API: al_identify_bitmap

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

See also: [al_init_image_addon], [al_identify_bitmap_f],
[al_register_bitmap_identifier]

### API: al_identify_bitmap_f

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

See also: [al_init_image_addon], [al_identify_bitmap],
[al_register_bitmap_identifier]

## Render State

### API: ALLEGRO_RENDER_STATE

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

See also: [al_set_render_state], [ALLEGRO_RENDER_FUNCTION],
[ALLEGRO_WRITE_MASK_FLAGS]

### API: ALLEGRO_RENDER_FUNCTION

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

See also: [al_set_render_state]

### API: ALLEGRO_WRITE_MASK_FLAGS

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

See also: [al_set_render_state]

### API: al_set_render_state

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

See also: [ALLEGRO_RENDER_STATE], [ALLEGRO_RENDER_FUNCTION],
[ALLEGRO_WRITE_MASK_FLAGS]


### API: al_backup_dirty_bitmap

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.

See also: [al_backup_dirty_bitmaps], [al_create_bitmap]


### API: al_backup_dirty_bitmaps

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.

See also: [al_backup_dirty_bitmap]

