NAME

       al_set_blender - Allegro 5 API

SYNOPSIS

              #include <allegro5/allegro.h>

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

DESCRIPTION

       Sets the function to use for blending for the current thread.

       Blending means, the source and destination colors are combined in drawing operations.

       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:

       • ALLEGRO_ADD

                 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

                 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

                 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 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(3alleg5) (white by default)

       • ALLEGRO_ZERO

                 f = 0, 0, 0, 0

       • ALLEGRO_ONE

                 f = 1, 1, 1, 1

       • ALLEGRO_ALPHA

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

       • ALLEGRO_INVERSE_ALPHA

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

       • ALLEGRO_SRC_COLOR (since: 5.0.10, 5.1.0)

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

       • ALLEGRO_DEST_COLOR (since: 5.0.10, 5.1.8)

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

       • ALLEGRO_INVERSE_SRC_COLOR (since: 5.0.10, 5.1.0)

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

       • ALLEGRO_INVERSE_DEST_COLOR (since: 5.0.10, 5.1.8)

                 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)

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

       • ALLEGRO_INVERSE_CONST_COLOR (since: 5.1.12, not supported on OpenGLES 1.0)

                 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(3alleg5))

              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(3alleg5), al_set_blend_color(3alleg5), al_get_blender(3alleg5)