ALLEGRO_PIXEL_FORMAT - Allegro 5 API
typedef enum ALLEGRO_PIXEL_FORMAT
Pixel formats. Each pixel format specifies the exact size and bit layout of a
pixel in memory. Components are specified from high bits to low bits, so for
example a fully opaque red pixel in ARGB_8888 format is 0xFFFF0000.
The pixel format is independent of endianness. That is, in the above example you
can always get the red component with
(pixel & 0x00ff0000) >> 16
But you can not
rely on this code:
*(pixel + 2)
It will return the red component on little endian systems, but the green
component on big endian systems.
Also note that Allegro's naming is different from OpenGL naming here, where a
format of GL_RGBA8 merely defines the component order and the exact layout
including endianness treatment is specified separately. Usually GL_RGBA8 will
correspond to ALLEGRO_PIXEL_ABGR_8888 though on little endian systems, so care
must be taken (note the reversal of RGBA <-> ABGR).
The only exception to this ALLEGRO_PIXEL_FORMAT_ABGR_8888_LE which will always
have the components as 4 bytes corresponding to red, green, blue and alpha, in
this order, independent of the endianness.
Some of the pixel formats represent compressed bitmap formats. Compressed
bitmaps take up less space in the GPU memory than bitmaps with regular
(uncompressed) pixel formats. This smaller footprint means that you can load
more resources into GPU memory, and they will be drawn somewhat faster. The
compression is lossy, however, so it is not appropriate for all graphical
styles: it tends to work best for images with smooth color gradations. It is
possible to compress bitmaps at runtime by passing the appropriate bitmap
format in al_set_new_bitmap_format and then creating, loading, cloning or
converting a non-compressed bitmap. This, however, is not recommended as the
compression quality differs between different GPU drivers. It is recommended
to compress these bitmaps ahead of time using external tools and then load
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.