Ubuntu Manpage: ALLEGRO_PIXEL_FORMAT

NAME

       ALLEGRO_PIXEL_FORMAT - Allegro 5 API

SYNOPSIS

              #include <allegro5/allegro.h>

              typedef enum ALLEGRO_PIXEL_FORMAT

DESCRIPTION

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

Note:

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

(pixel & 0x00ff0000) >> 16

But you can not rely on this code:

*(pixel + 2)

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

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

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

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

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

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

• ALLEGRO_PIXEL_FORMAT_ANY - Let the driver choose a format. This is the default format
at program start.

• ALLEGRO_PIXEL_FORMAT_ANY_NO_ALPHA - Let the driver choose a format without alpha.

• ALLEGRO_PIXEL_FORMAT_ANY_WITH_ALPHA - Let the driver choose a format with alpha.

• ALLEGRO_PIXEL_FORMAT_ANY_15_NO_ALPHA - Let the driver choose a 15 bit format without
alpha.

• ALLEGRO_PIXEL_FORMAT_ANY_16_NO_ALPHA - Let the driver choose a 16 bit format without
alpha.

• ALLEGRO_PIXEL_FORMAT_ANY_16_WITH_ALPHA - Let the driver choose a 16 bit format with
alpha.

• ALLEGRO_PIXEL_FORMAT_ANY_24_NO_ALPHA - Let the driver choose a 24 bit format without
alpha.

• ALLEGRO_PIXEL_FORMAT_ANY_32_NO_ALPHA - Let the driver choose a 32 bit format without
alpha.

• ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA - Let the driver choose a 32 bit format with
alpha.

• ALLEGRO_PIXEL_FORMAT_ARGB_8888 - 32 bit

• ALLEGRO_PIXEL_FORMAT_RGBA_8888 - 32 bit

• ALLEGRO_PIXEL_FORMAT_ARGB_4444 - 16 bit

• ALLEGRO_PIXEL_FORMAT_RGB_888 - 24 bit

• ALLEGRO_PIXEL_FORMAT_RGB_565 - 16 bit

• ALLEGRO_PIXEL_FORMAT_RGB_555 - 15 bit

• ALLEGRO_PIXEL_FORMAT_RGBA_5551 - 16 bit

• ALLEGRO_PIXEL_FORMAT_ARGB_1555 - 16 bit

• ALLEGRO_PIXEL_FORMAT_ABGR_8888 - 32 bit

• ALLEGRO_PIXEL_FORMAT_XBGR_8888 - 32 bit

• ALLEGRO_PIXEL_FORMAT_BGR_888 - 24 bit

• ALLEGRO_PIXEL_FORMAT_BGR_565 - 16 bit

• ALLEGRO_PIXEL_FORMAT_BGR_555 - 15 bit

• ALLEGRO_PIXEL_FORMAT_RGBX_8888 - 32 bit

• ALLEGRO_PIXEL_FORMAT_XRGB_8888 - 32 bit

• ALLEGRO_PIXEL_FORMAT_ABGR_F32 - 128 bit

• ALLEGRO_PIXEL_FORMAT_ABGR_8888_LE - Like the version without _LE, but the component
order is guaranteed to be red, green, blue, alpha. This only makes a difference on big
endian systems, on little endian it is just an alias.

• ALLEGRO_PIXEL_FORMAT_RGBA_4444 - 16bit

• ALLEGRO_PIXEL_FORMAT_SINGLE_CHANNEL_8 - A single 8-bit channel. A pixel value maps onto
the red channel when displayed, but it is undefined how it maps onto green, blue and
alpha channels. When drawing to bitmaps of this format, only the red channel is taken
into account. Allegro may have to use fallback methods to render to bitmaps of this
format. This pixel format is mainly intended for storing the color indices of an
indexed (paletted) image, usually in conjunction with a pixel shader that maps indices
to RGBA values. Since 5.1.2.

• ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT1 - Compressed using the DXT1 compression
algorithm. Each 4x4 pixel block is encoded in 64 bytes, resulting in 6-8x compression
ratio. Only a single bit of alpha per pixel is supported. Since 5.1.9.

• ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT3 - Compressed using the DXT3 compression
algorithm. Each 4x4 pixel block is encoded in 128 bytes, resulting in 4x compression
ratio. This format supports sharp alpha transitions. Since 5.1.9.

• ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT5 - Compressed using the DXT5 compression
algorithm. Each 4x4 pixel block is encoded in 128 bytes, resulting in 4x compression
ratio. This format supports smooth alpha transitions. Since 5.1.9.

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO