1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
.TH "ALLEGRO_PIXEL_FORMAT" "3" "" "Allegro reference manual" ""
.SH NAME
.PP
ALLEGRO_PIXEL_FORMAT \- Allegro 5 API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <allegro5/allegro.h>
typedef\ enum\ ALLEGRO_PIXEL_FORMAT
\f[]
.fi
.SH DESCRIPTION
.PP
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.
.RS
.PP
\f[I]Note:\f[]
.PP
The pixel format is independent of endianness.
That is, in the above example you can always get the red component with
.IP
.nf
\f[C]
(pixel\ &\ 0x00ff0000)\ >>\ 16
\f[]
.fi
.PP
But you can \f[I]not\f[] rely on this code:
.IP
.nf
\f[C]
*(pixel\ +\ 2)
\f[]
.fi
.PP
It will return the red component on little endian systems, but the green
component on big endian systems.
.RE
.PP
Also note that Allegro\[aq]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).
.PP
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.
.PP
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 \f[C]al_set_new_bitmap_format\f[] 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.
.PP
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.
.PP
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.
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ANY \- Let the driver choose a format.
This is the default format at program start.
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ANY_NO_ALPHA \- Let the driver choose a format
without alpha.
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ANY_WITH_ALPHA \- Let the driver choose a format
with alpha.
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ANY_15_NO_ALPHA \- Let the driver choose a 15 bit
format without alpha.
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ANY_16_NO_ALPHA \- Let the driver choose a 16 bit
format without alpha.
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ANY_16_WITH_ALPHA \- Let the driver choose a 16 bit
format with alpha.
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ANY_24_NO_ALPHA \- Let the driver choose a 24 bit
format without alpha.
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ANY_32_NO_ALPHA \- Let the driver choose a 32 bit
format without alpha.
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA \- Let the driver choose a 32 bit
format with alpha.
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ARGB_8888 \- 32 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_RGBA_8888 \- 32 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ARGB_4444 \- 16 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_RGB_888 \- 24 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_RGB_565 \- 16 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_RGB_555 \- 15 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_RGBA_5551 \- 16 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ARGB_1555 \- 16 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ABGR_8888 \- 32 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_XBGR_8888 \- 32 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_BGR_888 \- 24 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_BGR_565 \- 16 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_BGR_555 \- 15 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_RGBX_8888 \- 32 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_XRGB_8888 \- 32 bit
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_ABGR_F32 \- 128 bit
.IP \[bu] 2
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.
.IP \[bu] 2
ALLEGRO_PIXEL_FORMAT_RGBA_4444 \- 16bit
.IP \[bu] 2
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.
.IP \[bu] 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.
.IP \[bu] 2
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.
.IP \[bu] 2
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.
.SH SEE ALSO
.PP
al_set_new_bitmap_format(3), al_get_bitmap_format(3)
|
