1ALLEGRO_PIXEL_FORMAT(3) ALLEGRO_PIXEL_FORMAT(3)
2
3
4
6 ALLEGRO_PIXEL_FORMAT - Allegro 5 API
7
9 #include <allegro5/allegro.h>
10
11 typedef enum ALLEGRO_PIXEL_FORMAT
12
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
162 al_set_new_bitmap_format(3), al_get_bitmap_format(3)
163
164
165
166Allegro reference manual ALLEGRO_PIXEL_FORMAT(3)