.\" Automatically generated by Pandoc 1.19.2.4
.\"
.TH "al_set_blender" "3" "" "Allegro reference manual" ""
.hy
.SH NAME
.PP
al_set_blender \- Allegro 5 API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <allegro5/allegro.h>

void\ al_set_blender(int\ op,\ int\ src,\ int\ dst)
\f[]
.fi
.SH DESCRIPTION
.PP
Sets the function to use for blending for the current thread.
.PP
Blending means, the source and destination colors are combined in
drawing operations.
.PP
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): \f[I]s = s.r, s.g, s.b, s.a\f[].
And this color is drawn to a destination, which already has a color:
\f[I]d = d.r, d.g, d.b, d.a\f[].
.PP
The conceptional formula used by Allegro to draw any pixel then depends
on the \f[C]op\f[] parameter:
.IP \[bu] 2
ALLEGRO_ADD
.RS 2
.IP
.nf
\f[C]
\ 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
\f[]
.fi
.RE
.IP \[bu] 2
ALLEGRO_DEST_MINUS_SRC
.RS 2
.IP
.nf
\f[C]
\ 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
\f[]
.fi
.RE
.IP \[bu] 2
ALLEGRO_SRC_MINUS_DEST
.RS 2
.IP
.nf
\f[C]
\ 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
\f[]
.fi
.RE
.PP
Valid values for the factors \f[C]sf\f[] and \f[C]df\f[] passed to this
function are as follows, where \f[C]s\f[] is the source color,
\f[C]d\f[] the destination color and \f[C]cc\f[] the color set with
al_set_blend_color(3) (white by default)
.IP \[bu] 2
ALLEGRO_ZERO
.RS 2
.IP
.nf
\f[C]
\ f\ =\ 0,\ 0,\ 0,\ 0
\f[]
.fi
.RE
.IP \[bu] 2
ALLEGRO_ONE
.RS 2
.IP
.nf
\f[C]
\ f\ =\ 1,\ 1,\ 1,\ 1
\f[]
.fi
.RE
.IP \[bu] 2
ALLEGRO_ALPHA
.RS 2
.IP
.nf
\f[C]
\ f\ =\ s.a,\ s.a,\ s.a,\ s.a
\f[]
.fi
.RE
.IP \[bu] 2
ALLEGRO_INVERSE_ALPHA
.RS 2
.IP
.nf
\f[C]
\ f\ =\ 1\ \-\ s.a,\ 1\ \-\ s.a,\ 1\ \-\ s.a,\ 1\ \-\ s.a
\f[]
.fi
.RE
.IP \[bu] 2
ALLEGRO_SRC_COLOR (since: 5.0.10, 5.1.0)
.RS 2
.IP
.nf
\f[C]
\ f\ =\ s.r,\ s.g,\ s.b,\ s.a
\f[]
.fi
.RE
.IP \[bu] 2
ALLEGRO_DEST_COLOR (since: 5.0.10, 5.1.8)
.RS 2
.IP
.nf
\f[C]
\ f\ =\ d.r,\ d.g,\ d.b,\ d.a
\f[]
.fi
.RE
.IP \[bu] 2
ALLEGRO_INVERSE_SRC_COLOR (since: 5.0.10, 5.1.0)
.RS 2
.IP
.nf
\f[C]
\ f\ =\ 1\ \-\ s.r,\ 1\ \-\ s.g,\ 1\ \-\ s.b,\ 1\ \-\ s.a
\f[]
.fi
.RE
.IP \[bu] 2
ALLEGRO_INVERSE_DEST_COLOR (since: 5.0.10, 5.1.8)
.RS 2
.IP
.nf
\f[C]
\ f\ =\ 1\ \-\ d.r,\ 1\ \-\ d.g,\ 1\ \-\ d.b,\ 1\ \-\ d.a
\f[]
.fi
.RE
.IP \[bu] 2
ALLEGRO_CONST_COLOR (since: 5.1.12, not supported on OpenGLES 1.0)
.RS 2
.IP
.nf
\f[C]
\ f\ =\ cc.r,\ cc.g,\ cc.b,\ cc.a
\f[]
.fi
.RE
.IP \[bu] 2
ALLEGRO_INVERSE_CONST_COLOR (since: 5.1.12, not supported on OpenGLES
1.0)
.RS 2
.IP
.nf
\f[C]
\ f\ =\ 1\ \-\ cc.r,\ 1\ \-\ cc.g,\ 1\ \-\ cc.b,\ 1\ \-\ cc.a
\f[]
.fi
.RE
.PP
Blending examples:
.PP
So for example, to restore the default of using premultiplied alpha
blending, you would use:
.IP
.nf
\f[C]
al_set_blender(ALLEGRO_ADD,\ ALLEGRO_ONE,\ ALLEGRO_INVERSE_ALPHA);
\f[]
.fi
.PP
As formula:
.IP
.nf
\f[C]
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
\f[]
.fi
.PP
If you are using non\-pre\-multiplied alpha, you could use
.IP
.nf
\f[C]
al_set_blender(ALLEGRO_ADD,\ ALLEGRO_ALPHA,\ ALLEGRO_INVERSE_ALPHA);
\f[]
.fi
.PP
Additive blending would be achieved with
.IP
.nf
\f[C]
al_set_blender(ALLEGRO_ADD,\ ALLEGRO_ONE,\ ALLEGRO_ONE);
\f[]
.fi
.PP
Copying the source to the destination (including alpha) unmodified
.IP
.nf
\f[C]
al_set_blender(ALLEGRO_ADD,\ ALLEGRO_ONE,\ ALLEGRO_ZERO);
\f[]
.fi
.PP
Multiplying source and destination components
.IP
.nf
\f[C]
al_set_blender(ALLEGRO_ADD,\ ALLEGRO_DEST_COLOR,\ ALLEGRO_ZERO)
\f[]
.fi
.PP
Tinting the source (like al_draw_tinted_bitmap(3))
.IP
.nf
\f[C]
al_set_blender(ALLEGRO_ADD,\ ALLEGRO_CONST_COLOR,\ ALLEGRO_ONE);
al_set_blend_color(al_map_rgb(0,\ 96,\ 255));\ /*\ nice\ Chrysler\ blue\ */
\f[]
.fi
.PP
Averaging source and destination pixels
.IP
.nf
\f[C]
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));
\f[]
.fi
.PP
As formula:
.IP
.nf
\f[C]
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
\f[]
.fi
.SH SEE ALSO
.PP
al_set_separate_blender(3), al_set_blend_color(3), al_get_blender(3)