Provided by: allegro5-doc_5.2.3.0-1_all bug

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.

SEE ALSO

       al_set_new_bitmap_format(3alleg5), al_get_bitmap_format(3alleg5)