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

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_map_rgba(r * a / 255, g * a / 255, b * a / 255, a);
/* Draw the bitmap tinted red and half-transparent. */
al_draw_tinted_bitmap(bmp, c, 0, 0, 0);
~~~~

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

### API: al_map_rgba_f

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

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_map_rgba_f(r * a, g * a, b * a, a);
/* Draw the bitmap tinted red and half-transparent. */
al_draw_tinted_bitmap(bmp, c, 0, 0, 0);
~~~~

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

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

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

- *pixel_size* is the number of bytes used to represent a single pixel.

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.

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

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.

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.

See also: [ALLEGRO_PIXEL_FORMAT], [al_get_pixel_size]

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

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 it's data internally,
call with `al_get_bitmap_format(bitmap)` as the format or use
ALLEGRO_PIXEL_FORMAT_ANY. Locking in the native format will usually be faster.

> *Note:* While a bitmap is locked, you can not use any drawing operations
on it (with the sole exception of [al_put_pixel] and
[al_put_blended_pixel]).

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

### API: al_lock_bitmap_region

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

See also: [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 display 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]



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

See also: [al_set_new_bitmap_format], [al_set_new_bitmap_flags],
[al_clone_bitmap], [al_create_sub_bitmap],
[al_convert_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.

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.

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.

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.

If the bitmap has sub-bitmaps you also must call [al_convert_bitmap] on
all its sub-bitmaps. If the bitmap is a sub-bitmap you must also call
[al_convert_bitmap] on the parent.

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

Since: 5.1.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 targets 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 very unoptimised.

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.

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 Direct3D 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 its a temporary buffer, use this flag to tell Allegro
    not to attempt to preserve its contents. This can increase performance of
    your game or application, but there is a catch. See
    ALLEGRO_EVENT_DISPLAY_LOST for further information.

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



## 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_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]



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

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

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

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

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

* 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

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

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_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]



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

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.

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


## 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
    for each pixel. Only if it evaluates to true the pixel is written. Otherwise
    no subsequent processing (like depth test or blending) is performed.

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.

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]
