1.. _blend:
2
3Blend
4=====
5
6This state controls blending of the final fragments into the target rendering
7buffers.
8
9Blend Factors
10-------------
11
12The blend factors largely follow the same pattern as their counterparts
13in other modern and legacy drawing APIs.
14
15Dual source blend factors are supported for up to 1 MRT, although
16you can advertise > 1 MRT, the stack cannot handle them for a few reasons.
17There is no definition on how the 1D array of shader outputs should be mapped
18to something that would be a 2D array (location, index). No current hardware
19exposes > 1 MRT, and we should revisit this issue if anyone ever does.
20
21Logical Operations
22------------------
23
24Logical operations, also known as logicops, lops, or rops, are supported.
25Only two-operand logicops are available. When logicops are enabled, all other
26blend state is ignored, including per-render-target state, so logicops are
27performed on all render targets.
28
29.. warning::
30   The blend_enable flag is ignored for all render targets when logical
31   operations are enabled.
32
33For a source component `s` and destination component `d`, the logical
34operations are defined as taking the bits of each channel of each component,
35and performing one of the following operations per-channel:
36
37* ``CLEAR``: 0
38* ``NOR``: :math:`\lnot(s \lor d)`
39* ``AND_INVERTED``: :math:`\lnot s \land d`
40* ``COPY_INVERTED``: :math:`\lnot s`
41* ``AND_REVERSE``: :math:`s \land \lnot d`
42* ``INVERT``: :math:`\lnot d`
43* ``XOR``: :math:`s \oplus d`
44* ``NAND``: :math:`\lnot(s \land d)`
45* ``AND``: :math:`s \land d`
46* ``EQUIV``: :math:`\lnot(s \oplus d)`
47* ``NOOP``: :math:`d`
48* ``OR_INVERTED``: :math:`\lnot s \lor d`
49* ``COPY``: :math:`s`
50* ``OR_REVERSE``: :math:`s \lor \lnot d`
51* ``OR``: :math:`s \lor d`
52* ``SET``: 1
53
54.. note::
55   The logical operation names and definitions match those of the OpenGL API,
56   and are similar to the ROP2 and ROP3 definitions of GDI. This is
57   intentional, to ease transitions to Gallium.
58
59Members
60-------
61
62These members affect all render targets.
63
64dither
65%%%%%%
66
67Whether dithering is enabled.
68
69.. note::
70   Dithering is completely implementation-dependent. It may be ignored by
71   drivers for any reason, and some render targets may always or never be
72   dithered depending on their format or usage flags.
73
74logicop_enable
75%%%%%%%%%%%%%%
76
77Whether the blender should perform a logicop instead of blending.
78
79logicop_func
80%%%%%%%%%%%%
81
82The logicop to use. One of ``PIPE_LOGICOP``.
83
84independent_blend_enable
85   If enabled, blend state is different for each render target, and
86   for each render target set in the respective member of the rt array.
87   If disabled, blend state is the same for all render targets, and only
88   the first member of the rt array contains valid data.
89rt
90   Contains the per-rendertarget blend state.
91
92Per-rendertarget Members
93------------------------
94
95blend_enable
96   If blending is enabled, perform a blend calculation according to blend
97   functions and source/destination factors. Otherwise, the incoming fragment
98   color gets passed unmodified (but colormask still applies).
99rgb_func
100   The blend function to use for rgb channels. One of PIPE_BLEND.
101rgb_src_factor
102   The blend source factor to use for rgb channels. One of PIPE_BLENDFACTOR.
103rgb_dst_factor
104   The blend destination factor to use for rgb channels. One of PIPE_BLENDFACTOR.
105alpha_func
106   The blend function to use for the alpha channel. One of PIPE_BLEND.
107alpha_src_factor
108   The blend source factor to use for the alpha channel. One of PIPE_BLENDFACTOR.
109alpha_dst_factor
110   The blend destination factor to use for alpha channel. One of PIPE_BLENDFACTOR.
111colormask
112   Bitmask of which channels to write. Combination of PIPE_MASK bits.
113