al_set_blender(3)

🌸 NAME 🌸

Okay so bestie, welcome to al_set_blender(3) from the Library Functions Manual — it's literally the Allegro 5 API function that sets your blending function, and she is ready to make your colors combine. 💅

✨ SYNOPSIS ✨

#include <allegro5/allegro.h>

void al_set_blender(int op, int src, int dst)

🎀 DESCRIPTION 🎀

Okay so al_set_blender sets the function to use for blending for the current thread. No cap. 🫶

Blending means the source and destination colors are combined in drawing operations. It's giving "two colors walk into a draw call" and honestly? Obsessed. 😭

Assume the source color (e.g. color of a rectangle to draw, or pixel of a bitmap to draw) is given as its red/green/blue/alpha components (if the bitmap has no alpha it always is assumed to be fully opaque, so 255 for 8-bit or 1.0 for floating point): s = s.r, s.g, s.b, s.a. And this color is drawn to a destination, which already has a color: d = d.r, d.g, d.b, d.a.

The conceptional formula used by Allegro to draw any pixel then depends on the op parameter, bestie:

• ALLEGRO_ADD — adding source and destination, the main character:

r = d.r * df.r + s.r * sf.r
g = d.g * df.g + s.g * sf.g
b = d.b * df.b + s.b * sf.b
a = d.a * df.a + s.a * sf.a

• ALLEGRO_DEST_MINUS_SRC — destination minus source, subtraction girlie:

r = d.r * df.r - s.r * sf.r
g = d.g * df.g - s.g * sf.g
b = d.b * df.b - s.b * sf.b
a = d.a * df.a - s.a * sf.a

• ALLEGRO_SRC_MINUS_DEST — source minus destination:

r = s.r * sf.r - d.r * df.r
g = s.g * sf.g - d.g * df.g
b = s.b * sf.b - d.b * df.b
a = s.a * sf.a - d.a * df.a

🦋 Valid factors for sf and df 🦋

Valid values for the factors sf and df passed to this function are as follows, where s is the source color, d the destination color and cc the color set with al_set_blend_color(3) (white by default).

• ALLEGRO_ZERO — zero, zero, zero, zero:

f = 0, 0, 0, 0

• ALLEGRO_ONE — one, one, one, one:

f = 1, 1, 1, 1

• ALLEGRO_ALPHA — the source alpha, all day:

f = s.a, s.a, s.a, s.a

• ALLEGRO_INVERSE_ALPHA — one minus the source alpha:

f = 1 - s.a, 1 - s.a, 1 - s.a, 1 - s.a

• ALLEGRO_SRC_COLOR — since 5.0.10, 5.1.0, it's giving source color:

f = s.r, s.g, s.b, s.a

• ALLEGRO_DEST_COLOR — since 5.0.10, 5.1.8, destination color energy:

f = d.r, d.g, d.b, d.a

• ALLEGRO_INVERSE_SRC_COLOR — since 5.0.10, 5.1.0, inverse source color:

f = 1 - s.r, 1 - s.g, 1 - s.b, 1 - s.a

• ALLEGRO_INVERSE_DEST_COLOR — since 5.0.10, 5.1.8, inverse destination color:

f = 1 - d.r, 1 - d.g, 1 - d.b, 1 - d.a

• ALLEGRO_CONST_COLOR — since 5.1.12, not supported on OpenGLES 1.0, and it uses the constant color:

f = cc.r, cc.g, cc.b, cc.a

• ALLEGRO_INVERSE_CONST_COLOR — since 5.1.12, not supported on OpenGLES 1.0, inverse constant color:

f = 1 - cc.r, 1 - cc.g, 1 - cc.b, 1 - cc.a

💖 Blending examples 💖

So for example, to restore the default of using premultiplied alpha blending, you would use:

al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_INVERSE_ALPHA);

As formula:

r = d.r * (1 - s.a) + s.r * 1
g = d.g * (1 - s.a) + s.g * 1
b = d.b * (1 - s.a) + s.b * 1
a = d.a * (1 - s.a) + s.a * 1

If you are using non-pre-multiplied alpha, you could use

al_set_blender(ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA);

Additive blending would be achieved with

al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_ONE);

Copying the source to the destination (including alpha) unmodified

al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_ZERO);

Multiplying source and destination components

al_set_blender(ALLEGRO_ADD, ALLEGRO_DEST_COLOR, ALLEGRO_ZERO)

Tinting the source (like al_draw_tinted_bitmap(3))

al_set_blender(ALLEGRO_ADD, ALLEGRO_CONST_COLOR, ALLEGRO_ONE);
al_set_blend_color(al_map_rgb(0, 96, 255)); /* nice Chrysler blue */

Averaging source and destination pixels

al_set_blender(ALLEGRO_ADD, ALLEGRO_CONST_COLOR, ALLEGRO_CONST_COLOR);
al_set_blend_color(al_map_rgba_f(0.5, 0.5, 0.5, 0.5));

As formula:

r = d.r * 0 + s.r * d.r
g = d.g * 0 + s.g * d.g
b = d.b * 0 + s.b * d.b
a = d.a * 0 + s.a * d.a

💜 SEE ALSO 💜

• al_set_separate_blender(3)
• al_set_blend_color(3)
• al_get_blender(3)

---

Okay bestie, that's the whole page! This was al_set_blender(3) from the Allegro reference manual — the footer has no date on it, so it's giving timeless manual energy forever. 💖