1al_load_bitmap_flags(3) al_load_bitmap_flags(3)
2
6 al_load_bitmap_flags - Allegro 5 API
7
9 #include <allegro5/allegro.h>
10 ALLEGRO_BITMAP *al_load_bitmap_flags(const char *filename, int flags)
12
14 Loads an image file into a new ALLEGRO_BITMAP(3). The file type is
15 determined by the extension, except if the file has no extension in
16 which case al_identify_bitmap(3) is used instead.
17 Returns NULL on error.
19 The flags parameter may be a combination of the following constants:
21 ALLEGRO_NO_PREMULTIPLIED_ALPHA
23 By default, Allegro pre-multiplies the alpha channel of an image
24 with the images color data when it loads it. Typically that
25 would look something like this:
26 r = get_float_byte();
28 g = get_float_byte();
29 b = get_float_byte();
30 a = get_float_byte();
31 r = r * a;
33 g = g * a;
34 b = b * a;
35 set_image_pixel(x, y, r, g, b, a);
37 The reason for this can be seen in the Allegro example ex_premu‐
39 lalpha, ie, using pre-multiplied alpha gives more accurate color
40 results in some cases. To use alpha blending with images loaded
41 with pre-multiplied alpha, you would use the default blending
42 mode, which is set with al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE,
43 ALLEGRO_INVERSE_ALPHA).
44 The ALLEGRO_NO_PREMULTIPLIED_ALPHA flag being set will ensure
46 that images are not loaded with alpha pre-multiplied, but are
47 loaded with color values direct from the image. That looks like
48 this:
49 r = get_float_byte();
51 g = get_float_byte();
52 b = get_float_byte();
53 a = get_float_byte();
54 set_image_pixel(x, y, r, g, b, a);
56 To draw such an image using regular alpha blending, you would
58 use al_set_blender(ALLEGRO_ADD, ALLEGRO_ALPHA, ALLE‐
59 GRO_INVERSE_ALPHA) to set the correct blender. This has some
60 caveats. First, as mentioned above, drawing such an image can
61 result in less accurate color blending (when drawing an image
62 with linear filtering on, the edges will be darker than they
63 should be). Second, the behaviour is somewhat confusing, which
64 is explained in the example below.
65 // Load and create bitmaps with an alpha channel
67 al_set_new_bitmap_format(ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA);
68 // Load some bitmap with alpha in it
69 bmp = al_load_bitmap("some_alpha_bitmap.png");
70 // We will draw to this buffer and then draw this buffer to the screen
71 tmp_buffer = al_create_bitmap(SCREEN_W, SCREEN_H);
72 // Set the buffer as the target and clear it
73 al_set_target_bitmap(tmp_buffer);
74 al_clear_to_color(al_map_rgba_f(0, 0, 0, 1));
75 // Draw the bitmap to the temporary buffer
76 al_draw_bitmap(bmp, 0, 0, 0);
77 // Finally, draw the buffer to the screen
78 // The output will look incorrect (may take close inspection
79 // depending on the bitmap -- it may also be very obvious)
80 al_set_target_bitmap(al_get_backbuffer(display));
81 al_draw_bitmap(tmp_buffer, 0, 0, 0);
82 To explain further, if you have a pixel with 0.5 alpha, and
84 you're using (ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA)
85 for blending, the formula is:
86 a = da * dst + sa * src
88 Expands to:
90 result_a = dst_a * (1-0.5) + 0.5 * 0.5
92 So if you draw the image to the temporary buffer, it is blended
94 once resulting in 0.75 alpha, then drawn again to the screen,
95 blended in the same way, resulting in a pixel has 0.1875 as an
96 alpha value.
97 ALLEGRO_KEEP_INDEX
99 Load the palette indices of 8-bit .bmp and .pcx files instead of
100 the rgb colors. Since 5.1.0.
101 ALLEGRO_KEEP_BITMAP_FORMAT
103 Force the resulting ALLEGRO_BITMAP(3) to use the same format as
104 the file.
105 This is not yet honoured.
107 Note: the core Allegro library does not support any image file
109 formats by default. You must use the allegro_image addon, or
110 register your own format handler.
111
113 5.1.0
114
116 al_load_bitmap(3)
117Allegro reference manual al_load_bitmap_flags(3)