Home | History | Annotate | Download | only in cso
      1 .. _blend:
      2 
      3 Blend
      4 =====
      5 
      6 This state controls blending of the final fragments into the target rendering
      7 buffers.
      8 
      9 Blend Factors
     10 -------------
     11 
     12 The blend factors largely follow the same pattern as their counterparts
     13 in other modern and legacy drawing APIs.
     14 
     15 Dual source blend factors are supported for up to 1 MRT, although
     16 you can advertise > 1 MRT, the stack cannot handle them for a few reasons.
     17 There is no definition on how the 1D array of shader outputs should be mapped
     18 to something that would be a 2D array (location, index). No current hardware
     19 exposes > 1 MRT, and we should revisit this issue if anyone ever does.
     20 
     21 Logical Operations
     22 ------------------
     23 
     24 Logical operations, also known as logicops, lops, or rops, are supported.
     25 Only two-operand logicops are available. When logicops are enabled, all other
     26 blend state is ignored, including per-render-target state, so logicops are
     27 performed 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 
     33 For a source component `s` and destination component `d`, the logical
     34 operations are defined as taking the bits of each channel of each component,
     35 and 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 
     59 Members
     60 -------
     61 
     62 These members affect all render targets.
     63 
     64 dither
     65 %%%%%%
     66 
     67 Whether 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 
     74 logicop_enable
     75 %%%%%%%%%%%%%%
     76 
     77 Whether the blender should perform a logicop instead of blending.
     78 
     79 logicop_func
     80 %%%%%%%%%%%%
     81 
     82 The logicop to use. One of ``PIPE_LOGICOP``.
     83 
     84 independent_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.
     89 rt
     90    Contains the per-rendertarget blend state.
     91 
     92 Per-rendertarget Members
     93 ------------------------
     94 
     95 blend_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).
     99 rgb_func
    100    The blend function to use for rgb channels. One of PIPE_BLEND.
    101 rgb_src_factor
    102    The blend source factor to use for rgb channels. One of PIPE_BLENDFACTOR.
    103 rgb_dst_factor
    104    The blend destination factor to use for rgb channels. One of PIPE_BLENDFACTOR.
    105 alpha_func
    106    The blend function to use for the alpha channel. One of PIPE_BLEND.
    107 alpha_src_factor
    108    The blend source factor to use for the alpha channel. One of PIPE_BLENDFACTOR.
    109 alpha_dst_factor
    110    The blend destination factor to use for alpha channel. One of PIPE_BLENDFACTOR.
    111 colormask
    112    Bitmask of which channels to write. Combination of PIPE_MASK bits.
    113