diff options
Diffstat (limited to 'src/gallium/docs/cso/blend.rst')
| -rw-r--r-- | src/gallium/docs/cso/blend.rst | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/src/gallium/docs/cso/blend.rst b/src/gallium/docs/cso/blend.rst new file mode 100644 index 0000000000..7316e5c71c --- /dev/null +++ b/src/gallium/docs/cso/blend.rst @@ -0,0 +1,124 @@ +.. _blend: + +Blend +===== + +This state controls blending of the final fragments into the target rendering +buffers. + +Blend Factors +------------- + +The blend factors largely follow the same pattern as their counterparts +in other modern and legacy drawing APIs. + +Dual source blend factors are supported for up to 1 MRT, although +you can advertise > 1 MRT, the stack cannot handle them for a few reasons. +There is no definition on how the 1D array of shader outputs should be mapped +to something that would be a 2D array (location, index). No current hardware +exposes > 1 MRT, and we should revisit this issue if anyone ever does. + +Logical Operations +------------------ + +Logical operations, also known as logicops, lops, or rops, are supported. +Only two-operand logicops are available. When logicops are enabled, all other +blend state is ignored, including per-render-target state, so logicops are +performed on all render targets. + +.. warning:: + The blend_enable flag is ignored for all render targets when logical + operations are enabled. + +For a source component `s` and destination component `d`, the logical +operations are defined as taking the bits of each channel of each component, +and performing one of the following operations per-channel: + +* ``CLEAR``: 0 +* ``NOR``: :math:`\lnot(s \lor d)` +* ``AND_INVERTED``: :math:`\lnot s \land d` +* ``COPY_INVERTED``: :math:`\lnot s` +* ``AND_REVERSE``: :math:`s \land \lnot d` +* ``INVERT``: :math:`\lnot d` +* ``XOR``: :math:`s \oplus d` +* ``NAND``: :math:`\lnot(s \land d)` +* ``AND``: :math:`s \land d` +* ``EQUIV``: :math:`\lnot(s \oplus d)` +* ``NOOP``: :math:`d` +* ``OR_INVERTED``: :math:`\lnot s \lor d` +* ``COPY``: :math:`s` +* ``OR_REVERSE``: :math:`s \lor \lnot d` +* ``OR``: :math:`s \lor d` +* ``SET``: 1 + +.. note:: + The logical operation names and definitions match those of the OpenGL API, + and are similar to the ROP2 and ROP3 definitions of GDI. This is + intentional, to ease transitions to Gallium. + +Members +------- + +These members affect all render targets. + +dither +%%%%%% + +Whether dithering is enabled. + +.. note:: + Dithering is completely implementation-dependent. It may be ignored by + drivers for any reason, and some render targets may always or never be + dithered depending on their format or usage flags. + +logicop_enable +%%%%%%%%%%%%%% + +Whether the blender should perform a logicop instead of blending. + +logicop_func +%%%%%%%%%%%% + +The logicop to use. One of ``PIPE_LOGICOP``. + +independent_blend_enable + If enabled, blend state is different for each render target, and + for each render target set in the respective member of the rt array. + If disabled, blend state is the same for all render targets, and only + the first member of the rt array contains valid data. +rt + Contains the per-rendertarget blend state. +alpha_to_coverage + If enabled, the fragment's alpha value is used to override the fragment's + coverage mask. The coverage mask will be all zeros if the alpha value is + zero. The coverage mask will be all ones if the alpha value is one. + Otherwise, the number of bits set in the coverage mask will be proportional + to the alpha value. Note that this step happens regardless of whether + multisample is enabled or the destination buffer is multisampled. +alpha_to_one + If enabled, the fragment's alpha value will be set to one. As with + alpha_to_coverage, this step happens regardless of whether multisample + is enabled or the destination buffer is multisampled. + + +Per-rendertarget Members +------------------------ + +blend_enable + If blending is enabled, perform a blend calculation according to blend + functions and source/destination factors. Otherwise, the incoming fragment + color gets passed unmodified (but colormask still applies). +rgb_func + The blend function to use for rgb channels. One of PIPE_BLEND. +rgb_src_factor + The blend source factor to use for rgb channels. One of PIPE_BLENDFACTOR. +rgb_dst_factor + The blend destination factor to use for rgb channels. One of PIPE_BLENDFACTOR. +alpha_func + The blend function to use for the alpha channel. One of PIPE_BLEND. +alpha_src_factor + The blend source factor to use for the alpha channel. One of PIPE_BLENDFACTOR. +alpha_dst_factor + The blend destination factor to use for alpha channel. One of PIPE_BLENDFACTOR. +colormask + Bitmask of which channels to write. Combination of PIPE_MASK bits. |