bionic (3) ALLEGRO_PIXEL_FORMAT.3alleg5.gz

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)