al_load_bitmap_flags(3alleg5)

🎀 NAME 🎀

okay so al_load_bitmap_flags — it's an Allegro 5 API function (that's the 3alleg5 manual bestie, iykyk) and it loads an image file into a shiny new ALLEGRO_BITMAP, except you get to pass flags and control the whole vibe. 💅

---

✨ SYNOPSIS ✨

#include <allegro5/allegro.h>

ALLEGRO_BITMAP *al_load_bitmap_flags(const char *filename, int flags)

---

🦋 DESCRIPTION 🦋

So it loads an image file into a brand new ALLEGRO_BITMAP(3alleg5). 🖼️ The file type is determined by al_identify_bitmap(3alleg5), and it uses the extension as a fallback in case identification is not possible. detective energy with a backup plan, honestly iconic.

Returns NULL on error. 😭

The flags parameter may be a combination of the following constants — and bestie, there are layers to this:

• ALLEGRO_NO_PREMULTIPLIED_ALPHA — By default, Allegro pre-multiplies the alpha channel of an image with the image's color data when it loads it. Typically that would look something like this:

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);

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).

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:

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);

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.

// 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);

To explain further, if you have a pixel with 0.5 alpha, and you're using (ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA) for blending, the formula is:

a = da * dst + sa * src

Expands to:

result_a = dst_a * (1-0.5) + 0.5 * 0.5

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. math ate that, fr fr.

• ALLEGRO_KEEP_INDEX — Load the palette indices of 8-bit .bmp and .pcx files instead of the rgb colors. Since 5.1.0. 🎨
• ALLEGRO_KEEP_BITMAP_FORMAT — Force the resulting ALLEGRO_BITMAP(3alleg5) to use the same format as the file.

This is not yet honoured. 🙈

Note: 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. this one's important bestie, don't skip it!!

---

⭐ SINCE ⭐

5.1.0

---

👑 SEE ALSO 👑

al_load_bitmap(3alleg5)

---

and that's the whole page bestie!! 🌸 this lil beauty lives in the Allegro reference manual, filed under al_load_bitmap_flags(3alleg5) — go off, load those bitmaps, and remember: pre-multiplied alpha is a lifestyle. 💖✨🎀🦋