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
|
.TH "al_load_bitmap_flags" "3" "" "Allegro reference manual" ""
.SH NAME
.PP
al_load_bitmap_flags \- Allegro 5 API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <allegro5/allegro.h>
ALLEGRO_BITMAP\ *al_load_bitmap_flags(const\ char\ *filename,\ int\ flags)
\f[]
.fi
.SH DESCRIPTION
.PP
Loads an image file into a new ALLEGRO_BITMAP(3).
The file type is determined by the extension, except if the file has no
extension in which case al_identify_bitmap(3) is used instead.
.PP
Returns NULL on error.
.PP
The flags parameter may be a combination of the following constants:
.TP
.B ALLEGRO_NO_PREMULTIPLIED_ALPHA
By default, Allegro pre\-multiplies the alpha channel of an image with
the images color data when it loads it.
Typically that would look something like this:
.RS
.IP
.nf
\f[C]
r\ =\ get_float_byte();
g\ =\ get_float_byte();
b\ =\ get_float_byte();
a\ =\ get_float_byte();
r\ =\ r\ *\ a;
g\ =\ g\ *\ a;
b\ =\ b\ *\ a;
set_image_pixel(x,\ y,\ r,\ g,\ b,\ a);
\f[]
.fi
.PP
The reason for this can be seen in the Allegro example ex_premulalpha,
ie, using pre\-multiplied alpha gives more accurate color results in
some cases.
To use alpha blending with images loaded with pre\-multiplied alpha, you
would use the default blending mode, which is set with
al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_INVERSE_ALPHA).
.PP
The ALLEGRO_NO_PREMULTIPLIED_ALPHA flag being set will ensure that
images are not loaded with alpha pre\-multiplied, but are loaded with
color values direct from the image.
That looks like this:
.IP
.nf
\f[C]
r\ =\ get_float_byte();
g\ =\ get_float_byte();
b\ =\ get_float_byte();
a\ =\ get_float_byte();
set_image_pixel(x,\ y,\ r,\ g,\ b,\ a);
\f[]
.fi
.PP
To draw such an image using regular alpha blending, you would use
al_set_blender(ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA) to set
the correct blender.
This has some caveats.
First, as mentioned above, drawing such an image can result in less
accurate color blending (when drawing an image with linear filtering on,
the edges will be darker than they should be).
Second, the behaviour is somewhat confusing, which is explained in the
example below.
.IP
.nf
\f[C]
//\ Load\ and\ create\ bitmaps\ with\ an\ alpha\ channel
al_set_new_bitmap_format(ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA);
//\ Load\ some\ bitmap\ with\ alpha\ in\ it
bmp\ =\ al_load_bitmap("some_alpha_bitmap.png");
//\ We\ will\ draw\ to\ this\ buffer\ and\ then\ draw\ this\ buffer\ to\ the\ screen
tmp_buffer\ =\ al_create_bitmap(SCREEN_W,\ SCREEN_H);
//\ Set\ the\ buffer\ as\ the\ target\ and\ clear\ it
al_set_target_bitmap(tmp_buffer);
al_clear_to_color(al_map_rgba_f(0,\ 0,\ 0,\ 1));
//\ Draw\ the\ bitmap\ to\ the\ temporary\ buffer
al_draw_bitmap(bmp,\ 0,\ 0,\ 0);
//\ Finally,\ draw\ the\ buffer\ to\ the\ screen
//\ The\ output\ will\ look\ incorrect\ (may\ take\ close\ inspection
//\ depending\ on\ the\ bitmap\ \-\-\ it\ may\ also\ be\ very\ obvious)
al_set_target_bitmap(al_get_backbuffer(display));
al_draw_bitmap(tmp_buffer,\ 0,\ 0,\ 0);
\f[]
.fi
.PP
To explain further, if you have a pixel with 0.5 alpha, and you\[aq]re
using (ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA) for blending,
the formula is:
.IP
.nf
\f[C]
a\ =\ da\ *\ dst\ +\ sa\ *\ src
\f[]
.fi
.PP
Expands to:
.IP
.nf
\f[C]
result_a\ =\ dst_a\ *\ (1\-0.5)\ +\ 0.5\ *\ 0.5
\f[]
.fi
.PP
So if you draw the image to the temporary buffer, it is blended once
resulting in 0.75 alpha, then drawn again to the screen, blended in the
same way, resulting in a pixel has 0.1875 as an alpha value.
.RE
.TP
.B ALLEGRO_KEEP_INDEX
Load the palette indices of 8\-bit .bmp and .pcx files instead of the
rgb colors.
Since 5.1.0.
.RS
.RE
.TP
.B ALLEGRO_KEEP_BITMAP_FORMAT
Force the resulting ALLEGRO_BITMAP(3) to use the same format as the
file.
.RS
.PP
\f[I]This is not yet honoured.\f[]
.RE
.RS
.PP
\f[I]Note:\f[] the core Allegro library does not support any image file
formats by default.
You must use the allegro_image addon, or register your own format
handler.
.RE
.SH SINCE
.PP
5.1.0
.SH SEE ALSO
.PP
al_load_bitmap(3)
|
