1al_load_bitmap_flags(3)                                al_load_bitmap_flags(3)
2
3
4

NAME

6       al_load_bitmap_flags - Allegro 5 API
7

SYNOPSIS

9              #include <allegro5/allegro.h>
10
11              ALLEGRO_BITMAP *al_load_bitmap_flags(const char *filename, int flags)
12

DESCRIPTION

14       Loads an image file into a new ALLEGRO_BITMAP(3).  The file type is de‐
15       termined by the extension, except if the file has no extension in which
16       case al_identify_bitmap(3) is used instead.
17
18       Returns NULL on error.
19
20       The flags parameter may be a combination of the following constants:
21
22       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
27                     r = get_float_byte();
28                     g = get_float_byte();
29                     b = get_float_byte();
30                     a = get_float_byte();
31
32                     r = r * a;
33                     g = g * a;
34                     b = b * a;
35
36                     set_image_pixel(x, y, r, g, b, a);
37
38              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
45              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
50                     r = get_float_byte();
51                     g = get_float_byte();
52                     b = get_float_byte();
53                     a = get_float_byte();
54
55                     set_image_pixel(x, y, r, g, b, a);
56
57              To  draw  such  an image using regular alpha blending, you would
58              use   al_set_blender(ALLEGRO_ADD,   ALLEGRO_ALPHA,   ALLEGRO_IN‐
59              VERSE_ALPHA) to set the correct blender.  This has some caveats.
60              First, as mentioned above, drawing such an image can  result  in
61              less  accurate color blending (when drawing an image with linear
62              filtering on, the edges will be darker  than  they  should  be).
63              Second,  the behaviour is somewhat confusing, which is explained
64              in the example below.
65
66                     // 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
83              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
87                     a = da * dst + sa * src
88
89              Expands to:
90
91                     result_a = dst_a * (1-0.5) + 0.5 * 0.5
92
93              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
98       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
102       ALLEGRO_KEEP_BITMAP_FORMAT
103              Force the resulting ALLEGRO_BITMAP(3) to use the same format  as
104              the file.
105
106              This is not yet honoured.
107
108              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

SINCE

113       5.1.0
114

SEE ALSO

116       al_load_bitmap(3)
117
118
119
120Allegro reference manual                               al_load_bitmap_flags(3)
Impressum