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================== ========================= 38Operation Equation 39================== ========================= 40``CLEAR`` :math:`0` 41``NOR`` :math:`\lnot(s \lor d)` 42``AND_INVERTED`` :math:`\lnot s \land d` 43``COPY_INVERTED`` :math:`\lnot s` 44``AND_REVERSE`` :math:`s \land \lnot d` 45``INVERT`` :math:`\lnot d` 46``XOR`` :math:`s \oplus d` 47``NAND`` :math:`\lnot(s \land d)` 48``AND`` :math:`s \land d` 49``EQUIV`` :math:`\lnot(s \oplus d)` 50``NOOP`` :math:`d` 51``OR_INVERTED`` :math:`\lnot s \lor d` 52``COPY`` :math:`s` 53``OR_REVERSE`` :math:`s \lor \lnot d` 54``OR`` :math:`s \lor d` 55``SET`` :math:`1` 56================== ========================= 57 58.. note:: 59 The logical operation names and definitions match those of the OpenGL API, 60 and are similar to the ROP2 and ROP3 definitions of GDI. This is 61 intentional, to ease transitions to Gallium. 62 63Members 64------- 65 66These members affect all render targets. 67 68dither 69 Whether dithering is enabled. 70 71 .. note:: 72 Dithering is completely implementation-dependent. It may be ignored by 73 drivers for any reason, and some render targets may always or never be 74 dithered depending on their format or usage flags. 75 76logicop_enable 77 Whether the blender should perform a logicop instead of blending. 78logicop_func 79 The logicop to use. One of ``PIPE_LOGICOP``. 80independent_blend_enable 81 If enabled, blend state is different for each render target, and 82 for each render target set in the respective member of the rt array. 83 If disabled, blend state is the same for all render targets, and only 84 the first member of the rt array contains valid data. 85rt 86 Contains the per-rendertarget blend state. 87alpha_to_coverage 88 If enabled, the fragment's alpha value is used to override the fragment's 89 coverage mask. The coverage mask will be all zeros if the alpha value is 90 zero. The coverage mask will be all ones if the alpha value is one. 91 Otherwise, the number of bits set in the coverage mask will be proportional 92 to the alpha value. Note that this step happens regardless of whether 93 multisample is enabled or the destination buffer is multisampled. 94alpha_to_one 95 If enabled, the fragment's alpha value will be set to one. As with 96 alpha_to_coverage, this step happens regardless of whether multisample 97 is enabled or the destination buffer is multisampled. 98max_rt 99 The index of the max render target (irrespective of whether independent 100 blend is enabled), i.e. the number of MRTs minus one. This is provided 101 so that the driver can avoid the overhead of programming unused MRTs. 102 103 104Per-rendertarget Members 105------------------------ 106 107blend_enable 108 If blending is enabled, perform a blend calculation according to blend 109 functions and source/destination factors. Otherwise, the incoming fragment 110 color gets passed unmodified (but colormask still applies). 111rgb_func 112 The blend function to use for RGB channels. One of PIPE_BLEND. 113rgb_src_factor 114 The blend source factor to use for RGB channels. One of PIPE_BLENDFACTOR. 115rgb_dst_factor 116 The blend destination factor to use for RGB channels. One of PIPE_BLENDFACTOR. 117alpha_func 118 The blend function to use for the alpha channel. One of PIPE_BLEND. 119alpha_src_factor 120 The blend source factor to use for the alpha channel. One of PIPE_BLENDFACTOR. 121alpha_dst_factor 122 The blend destination factor to use for alpha channel. One of PIPE_BLENDFACTOR. 123colormask 124 Bitmask of which channels to write. Combination of PIPE_MASK bits. 125