1ALLEGRO_PIXEL_FORMAT(3)                                ALLEGRO_PIXEL_FORMAT(3)
2
3
4

NAME

6       ALLEGRO_PIXEL_FORMAT - Allegro 5 API
7

SYNOPSIS

9              #include <allegro5/allegro.h>
10
11              typedef enum ALLEGRO_PIXEL_FORMAT
12

DESCRIPTION

14       Pixel formats.  Each pixel format specifies the exact size and bit lay‐
15       out of a pixel in memory.  Components are specified from high  bits  to
16       low  bits,  so for example a fully opaque red pixel in ARGB_8888 format
17       is 0xFFFF0000.
18
19              Note:
20
21              The pixel format is independent of endianness.  That is, in  the
22              above example you can always get the red component with
23
24                     (pixel & 0x00ff0000) >> 16
25
26              But you can not rely on this code:
27
28                     *(pixel + 2)
29
30              It  will  return the red component on little endian systems, but
31              the green component on big endian systems.
32
33       Also note that Allegro's naming is different from OpenGL  naming  here,
34       where  a  format of GL_RGBA8 merely defines the component order and the
35       exact layout including endianness treatment  is  specified  separately.
36       Usually  GL_RGBA8  will correspond to ALLEGRO_PIXEL_ABGR_8888 though on
37       little endian systems, so care must be taken (note the reversal of RGBA
38       <-> ABGR).
39
40       The only exception to this ALLEGRO_PIXEL_FORMAT_ABGR_8888_LE which will
41       always have the components as 4 bytes corresponding to red, green, blue
42       and alpha, in this order, independent of the endianness.
43
44       Some  of  the  pixel formats represent compressed bitmap formats.  Com‐
45       pressed bitmaps take up less space in the GPU memory than bitmaps  with
46       regular  (uncompressed)  pixel  formats.   This smaller footprint means
47       that you can load more resources into GPU  memory,  and  they  will  be
48       drawn somewhat faster.  The compression is lossy, however, so it is not
49       appropriate for all graphical styles: it tends to work best for  images
50       with  smooth  color  gradations.  It is possible to compress bitmaps at
51       runtime by passing the appropriate  bitmap  format  in  al_set_new_bit‐
52       map_format and then creating, loading, cloning or converting a non-com‐
53       pressed bitmap.  This, however, is not recommended as  the  compression
54       quality  differs  between  different GPU drivers.  It is recommended to
55       compress these bitmaps ahead of time using external tools and then load
56       them compressed.
57
58       Unlike regular pixel formats, compressed pixel formats are not laid out
59       in memory one pixel row at a time.  Instead, the bitmap  is  subdivided
60       into rectangular blocks of pixels that are then laid out in block rows.
61       This means that regular locking functions cannot use  compressed  pixel
62       formats  as  the  destination format.  Instead, you can use the blocked
63       versions of the bitmap locking functions which do  support  these  for‐
64       mats.
65
66       It  is  not recommended to use compressed bitmaps as target bitmaps, as
67       that operation cannot be hardware accelerated.  Due to proprietary  al‐
68       gorithms  used,  it is typically impossible to create compressed memory
69       bitmaps.
70
71       · ALLEGRO_PIXEL_FORMAT_ANY - Let the driver choose a format.   This  is
72         the default format at program start.
73
74       · ALLEGRO_PIXEL_FORMAT_ANY_NO_ALPHA  -  Let  the driver choose a format
75         without alpha.
76
77       · ALLEGRO_PIXEL_FORMAT_ANY_WITH_ALPHA - Let the driver choose a  format
78         with alpha.
79
80       · ALLEGRO_PIXEL_FORMAT_ANY_15_NO_ALPHA - Let the driver choose a 15 bit
81         format without alpha.
82
83       · ALLEGRO_PIXEL_FORMAT_ANY_16_NO_ALPHA - Let the driver choose a 16 bit
84         format without alpha.
85
86       · ALLEGRO_PIXEL_FORMAT_ANY_16_WITH_ALPHA  -  Let the driver choose a 16
87         bit format with alpha.
88
89       · ALLEGRO_PIXEL_FORMAT_ANY_24_NO_ALPHA - Let the driver choose a 24 bit
90         format without alpha.
91
92       · ALLEGRO_PIXEL_FORMAT_ANY_32_NO_ALPHA - Let the driver choose a 32 bit
93         format without alpha.
94
95       · ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA - Let the driver choose  a  32
96         bit format with alpha.
97
98       · ALLEGRO_PIXEL_FORMAT_ARGB_8888 - 32 bit
99
100       · ALLEGRO_PIXEL_FORMAT_RGBA_8888 - 32 bit
101
102       · ALLEGRO_PIXEL_FORMAT_ARGB_4444 - 16 bit
103
104       · ALLEGRO_PIXEL_FORMAT_RGB_888 - 24 bit
105
106       · ALLEGRO_PIXEL_FORMAT_RGB_565 - 16 bit
107
108       · ALLEGRO_PIXEL_FORMAT_RGB_555 - 15 bit
109
110       · ALLEGRO_PIXEL_FORMAT_RGBA_5551 - 16 bit
111
112       · ALLEGRO_PIXEL_FORMAT_ARGB_1555 - 16 bit
113
114       · ALLEGRO_PIXEL_FORMAT_ABGR_8888 - 32 bit
115
116       · ALLEGRO_PIXEL_FORMAT_XBGR_8888 - 32 bit
117
118       · ALLEGRO_PIXEL_FORMAT_BGR_888 - 24 bit
119
120       · ALLEGRO_PIXEL_FORMAT_BGR_565 - 16 bit
121
122       · ALLEGRO_PIXEL_FORMAT_BGR_555 - 15 bit
123
124       · ALLEGRO_PIXEL_FORMAT_RGBX_8888 - 32 bit
125
126       · ALLEGRO_PIXEL_FORMAT_XRGB_8888 - 32 bit
127
128       · ALLEGRO_PIXEL_FORMAT_ABGR_F32 - 128 bit
129
130       · ALLEGRO_PIXEL_FORMAT_ABGR_8888_LE - Like the version without _LE, but
131         the component order is guaranteed to  be  red,  green,  blue,  alpha.
132         This  only makes a difference on big endian systems, on little endian
133         it is just an alias.
134
135       · ALLEGRO_PIXEL_FORMAT_RGBA_4444 - 16bit
136
137       · ALLEGRO_PIXEL_FORMAT_SINGLE_CHANNEL_8 - A single  8-bit  channel.   A
138         pixel value maps onto the red channel when displayed, but it is unde‐
139         fined how it maps onto green, blue and alpha channels.  When  drawing
140         to  bitmaps  of  this  format, only the red channel is taken into ac‐
141         count.  Allegro may have to use fallback methods to render to bitmaps
142         of this format.  This pixel format is mainly intended for storing the
143         color indices of an indexed (paletted) image, usually in  conjunction
144         with a pixel shader that maps indices to RGBA values.  Since 5.1.2.
145
146       · ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT1 - Compressed using the DXT1
147         compression algorithm.  Each 4x4 pixel block is encoded in 64  bytes,
148         resulting  in 6-8x compression ratio.  Only a single bit of alpha per
149         pixel is supported.  Since 5.1.9.
150
151       · ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT3 - Compressed using the DXT3
152         compression algorithm.  Each 4x4 pixel block is encoded in 128 bytes,
153         resulting in 4x compression ratio.  This format supports sharp  alpha
154         transitions.  Since 5.1.9.
155
156       · ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT5 - Compressed using the DXT5
157         compression algorithm.  Each 4x4 pixel block is encoded in 128 bytes,
158         resulting in 4x compression ratio.  This format supports smooth alpha
159         transitions.  Since 5.1.9.
160

SEE ALSO

162       al_set_new_bitmap_format(3), al_get_bitmap_format(3)
163
164
165
166Allegro reference manual                               ALLEGRO_PIXEL_FORMAT(3)
Impressum