Vulkan-Docs/doc/specs/vulkan/chapters/framebuffer.txt

// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html

[[framebuffer]]
= The Framebuffer


[[framebuffer-blending]]
== Blending

Blending combines the incoming ``source'' fragment's R, G, B, and A values
with the ``destination'' R, G, B, and A values of each sample stored in the
framebuffer at the fragment's latexmath:[$(x_f,y_f)$] location. Blending is
performed for each pixel sample, rather than just once for each fragment.

Source and destination values are combined according to the
<<framebuffer-blendoperations,blend operation>>, quadruplets of source and
destination weighting factors determined by the <<framebuffer-blendfactors,
blend factors>>, and a <<framebuffer-blendconstants,blend constant>>,
to obtain a new set of R, G, B, and A values, as described below.

Blending is computed and applied separately to each color attachment used by
the subpass, with separate controls for each attachment.

Prior to performing the blend operation, signed and unsigned normalized
fixed-point color components undergo an implied conversion to floating-point
as specified by <<fundamentals-fixedfpconv,Conversion
from Normalized Fixed-Point to Floating-Point>>. Blending
computations are treated as if carried out in floating-point, and will be
performed with a precision and dynamic range no lower than that used to
represent destination components.

Blending applies only to fixed-point and floating-point color attachments.
If the color attachment has an integer format, blending is not applied.

The pipeline blend state is included in the
sname:VkPipelineColorBlendStateCreateInfo structure during graphics pipeline
creation:

// refBegin VkPipelineColorBlendStateCreateInfo - Structure specifying parameters of a newly created pipeline color blend state

The sname:VkPipelineColorBlendStateCreateInfo structure is defined as:

include::../api/structs/VkPipelineColorBlendStateCreateInfo.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:flags is reserved for future use.
  * pname:logicOpEnable controls whether to apply <<framebuffer-logicop,
    Logical Operations>>.
  * pname:logicOp selects which logical operation to apply.
  * pname:attachmentCount is the number of
    sname:VkPipelineColorBlendAttachmentState elements in
    pname:pAttachments. This value must: equal the
    pname:colorAttachmentCount for the subpass in which this pipeline is
    used.
  * pname:pAttachments: is a pointer to array of per target attachment states.
  * pname:blendConstants is an array of four values used as the R, G, B, and
    A components of the blend constant that are used in blending, depending
    on the <<framebuffer-blendfactors,blend factor>>.

Each element of the pname:pAttachments array is a
slink:VkPipelineColorBlendAttachmentState structure specifying per-target
blending state for each individual color attachment. If the
<<features-features-independentBlend,independent blending>> feature is not
enabled on the device, all slink:VkPipelineColorBlendAttachmentState
elements in the pname:pAttachments array must: be identical.

include::../validity/structs/VkPipelineColorBlendStateCreateInfo.txt[]

// refBegin VkPipelineColorBlendAttachmentState - Structure specifying a pipeline color blend attachment state

The sname:VkPipelineColorBlendAttachmentState structure is defined as:

include::../api/structs/VkPipelineColorBlendAttachmentState.txt[]

  * pname:blendEnable controls whether blending is enabled for the
    corresponding color attachment. If blending is not enabled, the source
    fragment's color for that attachment is passed through unmodified.
  * pname:srcColorBlendFactor selects which blend factor is used to
    determine the source factors latexmath:[$S_r,S_g,S_b$].
  * pname:dstColorBlendFactor selects which blend factor is used to
    determine the destination factors latexmath:[$D_r,D_g,D_b$].
  * pname:colorBlendOp selects which blend operation is used to calculate
    the RGB values to write to the color attachment.
  * pname:srcAlphaBlendFactor selects which blend factor is used to
    determine the source factor latexmath:[$S_a$].
  * pname:dstAlphaBlendFactor selects which blend factor is used to
    determine the destination factor latexmath:[$D_a$].
  * pname:alphaBlendOp selects which blend operation is use to calculate the
    alpha values to write to the color attachment.
  * pname:colorWriteMask is a bitmask selecting which of the R, G, B,
    and/or A components are enabled for writing, as described later in this
    chapter.

include::../validity/structs/VkPipelineColorBlendAttachmentState.txt[]


[[framebuffer-blendfactors]]
=== Blend Factors

// refBegin VkBlendFactor framebuffer blending factors

The source and destination color and alpha blending factors are selected
from the enum:

include::../api/enums/VkBlendFactor.txt[]

The semantics of each enum value is described in the table below:

.Blend Factors
[width="100%",options="header",align="center",cols="59%,28%,13%"]
|========================================
|VkBlendFactor                                  | RGB Blend Factors (latexmath:[$S_r,S_g,S_b$]) or (latexmath:[$D_r,D_g,D_b$]) | Alpha Blend Factor (latexmath:[$S_a$] or latexmath:[$D_a$])
|ename:VK_BLEND_FACTOR_ZERO                     | latexmath:[$(0,0,0)$]                           | latexmath:[$0$]
|ename:VK_BLEND_FACTOR_ONE                      | latexmath:[$(1,1,1)$]                           | latexmath:[$1$]
|ename:VK_BLEND_FACTOR_SRC_COLOR                | latexmath:[$(R_{s0},G_{s0},B_{s0})$]            | latexmath:[$A_{s0}$]
|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC_COLOR      | latexmath:[$(1-R_{s0},1-G_{s0},1-B_{s0})$]      | latexmath:[$1-A_{s0}$]
|ename:VK_BLEND_FACTOR_DST_COLOR                | latexmath:[$(R_d,G_d,B_d)$]                     | latexmath:[$A_d$]
|ename:VK_BLEND_FACTOR_ONE_MINUS_DST_COLOR      | latexmath:[$(1-R_d,1-G_d,1-B_d)$]               | latexmath:[$1-A_d$]
|ename:VK_BLEND_FACTOR_SRC_ALPHA                | latexmath:[$(A_{s0},A_{s0},A_{s0})$]            | latexmath:[$A_{s0}$]
|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA      | latexmath:[$(1-A_{s0},1-A_{s0},1-A_{s0})$]      | latexmath:[$1-A_{s0}$]
|ename:VK_BLEND_FACTOR_DST_ALPHA                | latexmath:[$(A_d,A_d,A_d)$]                     | latexmath:[$A_d$]
|ename:VK_BLEND_FACTOR_ONE_MINUS_DST_ALPHA      | latexmath:[$(1-A_d,1-A_d,1-A_d)$]               | latexmath:[$1-A_d$]
|ename:VK_BLEND_FACTOR_CONSTANT_COLOR           | latexmath:[$(R_c,G_c,B_c)$]                     | latexmath:[$A_c$]
|ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR | latexmath:[$(1-R_c,1-G_c,1-B_c)$]               | latexmath:[$1-A_c$]
|ename:VK_BLEND_FACTOR_CONSTANT_ALPHA           | latexmath:[$(A_c,A_c,A_c)$]                     | latexmath:[$A_c$]
|ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA | latexmath:[$(1-A_c,1-A_c,1-A_c)$]               | latexmath:[$1-A_c$]
|ename:VK_BLEND_FACTOR_SRC_ALPHA_SATURATE       | latexmath:[$(f,f,f); f=\min(A_{s0},1-A_d)$]     | latexmath:[$1$]
|ename:VK_BLEND_FACTOR_SRC1_COLOR               | latexmath:[$(R_{s1},G_{s1},B_{s1})$]            | latexmath:[$A_{s1}$]
|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR     | latexmath:[$(1-R_{s1},1-G_{s1},1-B_{s1})$]      | latexmath:[$1-A_{s1}$]
|ename:VK_BLEND_FACTOR_SRC1_ALPHA               | latexmath:[$(A_{s1},A_{s1},A_{s1})$]            | latexmath:[$A_{s1}$]
|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA     | latexmath:[$(1-A_{s1},1-A_{s1},1-A_{s1})$]      | latexmath:[$1-A_{s1}$]
|========================================

In this table, the following conventions are used:

  - latexmath:[$R_{s0},G_{s0},B_{s0}$] and latexmath:[$A_{s0}$] represent
    the first source color R, G, B, and A components, respectively, for the
    fragment output location corresponding to the color attachment being
    blended.
  - latexmath:[$R_{s1},G_{s1},B_{s1}$] and latexmath:[$A_{s1}$] represent
    the second source color R, G, B, and A components, respectively, used in
    dual source blending modes, for the fragment output location
    corresponding to the color attachment being blended.
  - latexmath:[$R_d,G_d,B_d$] and latexmath:[$A_d$] represent the R, G, B,
    and A components of the destination color. That is, the color currently
    in the corresponding color attachment for this fragment/sample.
  - latexmath:[$R_c,G_c,B_c$] and latexmath:[$A_c$] represent the blend
    constant R, G, B, and A components, respectively.

// refEnd VkBlendFactor

[[framebuffer-blendconstants]]
If the pipeline state object is created without the
ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS dynamic state enabled then the
``blend constant'' latexmath:[$(R_c,G_c,B_c,A_c)$] is specified via the
pname:blendConstants member of slink:VkPipelineColorBlendStateCreateInfo.

// refBegin vkCmdSetBlendConstants Set the values of blend constants.

Otherwise, to dynamically set and change the blend constant, call:

include::../api/protos/vkCmdSetBlendConstants.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:blendConstants is an array of four values specifying the R, G, B,
    and A components of the blend constant color used in blending, depending
    on the <<framebuffer-blendfactors,blend factor>>.

include::../validity/protos/vkCmdSetBlendConstants.txt[]


[[framebuffer-dsb]]
=== Dual-Source Blending

Blend factors that use the secondary color input
latexmath:[$(R_{s1},G_{s1},B_{s1},A_{s1})$]
(ename:VK_BLEND_FACTOR_SRC1_COLOR,
ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR,
ename:VK_BLEND_FACTOR_SRC1_ALPHA, and
ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA) may: consume hardware resources
that could otherwise be used for rendering to multiple color attachments.
Therefore, the number of color attachments that can: be used in a
framebuffer may: be lower when using dual-source blending.

Dual-source blending is only supported if the
<<features-features-dualSrcBlend,pname:dualSrcBlend>> feature is enabled.

The maximum number of color attachments that can: be used in a subpass when
using dual-source blending functions is implementation-dependent and is
reported as the pname:maxFragmentDualSrcAttachments member of
sname:VkPhysicalDeviceLimits.

When using a fragment shader with dual-source blending functions, the color
outputs are bound to the first and second inputs of the blender using the
code:Index decoration, as described in <<interfaces-fragmentoutput,Fragment
Output Interface>>. If the second color input to the blender is not
written in the shader, or if no output is bound to the second input of a
blender, the result of the blending operation is not defined.


[[framebuffer-blendoperations]]
=== Blend Operations

// refBegin VkBlendOp framebuffer blending operations

Once the source and destination blend factors have been selected, they along
with the source and destination components are passed to the blending
operation. The blending operations are selected from the following enum,
with RGB and alpha components potentially using different blend operations:

include::../api/enums/VkBlendOp.txt[]

<<<

The semantics of each enum value is described in the table below:

.Blend Operations
[width="100%",cols="45%,30%,25%",options="header",align="center"]
|==========================================
|VkBlendOp                                   | RGB Components                    | Alpha Component

|ename:VK_BLEND_OP_ADD
| latexmath:[$R=R_{s0}\times S_r+R_d\times D_r$] +
  latexmath:[$G=G_{s0}\times S_g+G_d\times D_g$] +
  latexmath:[$B=B_{s0}\times S_b+B_d\times D_b$]
| latexmath:[$A=A_{s0}\times S_a+A_d\times D_a$]

|ename:VK_BLEND_OP_SUBTRACT
| latexmath:[$R=R_{s0}\times S_r-R_d\times D_r$] +
  latexmath:[$G=G_{s0}\times S_g-G_d\times D_g$] +
  latexmath:[$B=B_{s0}\times S_b-B_d\times D_b$]
| latexmath:[$A=A_{s0}\times S_a-A_d\times D_a$]

|ename:VK_BLEND_OP_REVERSE_SUBTRACT
| latexmath:[$R=R_d\times D_r-R_{s0}\times S_r$] +
  latexmath:[$G=G_d\times D_g-G_{s0}\times S_g$] +
  latexmath:[$B=B_d\times D_b-B_{s0}\times S_b$]
| latexmath:[$A=A_d\times D_a-A_{s0}\times S_a$]

|ename:VK_BLEND_OP_MIN
| latexmath:[$R=\min(R_{s0},R_d)$] +
  latexmath:[$G=\min(G_{s0},G_d)$] +
  latexmath:[$B=\min(B_{s0},B_d)$]
| latexmath:[$A=\min(A_{s0},A_d)$]

|ename:VK_BLEND_OP_MAX
| latexmath:[$R=\max(R_{s0},R_d)$] +
  latexmath:[$G=\max(G_{s0},G_d)$] +
  latexmath:[$B=\max(B_{s0},B_d)$]
| latexmath:[$A=\max(A_{s0},A_d)$]
|==========================================

In this table, the following conventions are used:

  - latexmath:[$R_{s0},G_{s0},B_{s0}$] and latexmath:[$A_{s0}$] represent
    the first source color R, G, B, and A components, respectively.
  - latexmath:[$R_d,G_d,B_d$] and latexmath:[$A_d$] represent the R, G, B,
    and A components of the destination color. That is, the color currently
    in the corresponding color attachment for this fragment/sample.
  - latexmath:[$S_r,S_g,S_b$] and latexmath:[$S_a$] represent the source
    blend factor R, G, B, and A components, respectively.
  - latexmath:[$D_r,D_g,D_b$] and latexmath:[$D_a$] represent the
    destination blend factor R, G, B, and A components, respectively.

The blending operation produces a new set of values latexmath:[$R, G,
B$] and latexmath:[$A$], which are written to the framebuffer attachment. If
blending is not enabled for this attachment, then latexmath:[$R, G, B$] and
latexmath:[$A$] are assigned
latexmath:[$R_{s0},G_{s0},B_{s0}$] and latexmath:[$A_{s0}$], respectively.

If the color attachment is fixed-point, the components of the source and
destination values and blend factors are each clamped to
latexmath:[$[0,1\]$] or latexmath:[$[-1,1\]$] respectively for an unsigned
normalized or signed normalized color attachment prior to evaluating the
blend operations. If the color attachment is floating-point, no clamping
occurs.

// refEnd VkBlendOp

// refBegin VkColorComponentFlagBits - Bitmask controlling which components are written to the framebuffer

The pname:colorWriteMask member of slink:VkPipelineColorBlendAttachmentState
determines whether the final color values latexmath:[$R, G, B$] and
latexmath:[$A$] are written to the framebuffer attachment.
pname:colorWriteMask is any combination of the following bits:

include::../api/enums/VkColorComponentFlagBits.txt[]

If ename:VK_COLOR_COMPONENT_R_BIT is set, then the latexmath:[$R$] value is
written to color attachment for the appropriate sample, otherwise the value
in memory is unmodified. The ename:VK_COLOR_COMPONENT_G_BIT,
ename:VK_COLOR_COMPONENT_B_BIT, and ename:VK_COLOR_COMPONENT_A_BIT bits
similarly control writing of the latexmath:[$G, B,$] and latexmath:[$A$]
values. The pname:colorWriteMask is applied regardless of whether blending
is enabled.

// refEnd VkColorComponentFlagBits

If the numeric format of a framebuffer attachment uses sRGB encoding, the R,
G, and B destination color values (after conversion from fixed-point to
floating-point) are considered to be encoded for the sRGB color space and
hence are linearized prior to their use in blending. Each R, G, and B
component is converted from nonlinear to linear as described in the
``KHR_DF_TRANSFER_SRGB'' section of the Khronos Data Format Specification.
If the format is not sRGB, no linearization is performed.

If the numeric format of a framebuffer attachment uses sRGB encoding, then
the final R, G and B values are converted into the nonlinear sRGB
representation before being written to the framebuffer attachment as
described in the ``KHR_DF_TRANSFER_SRGB'' section of the Khronos Data
Format Specification.

If the framebuffer color attachment numeric format is not sRGB encoded then
the resulting latexmath:[$c_s$] values for R, G and B are unmodified. The
value of A is never sRGB encoded. That is, the alpha component is always
stored in memory as linear.

If the framebuffer color attachment is ename:VK_ATTACHMENT_UNUSED, no writes
are performed through that attachment. Framebuffer color attachments greater
than or equal to sname:VkSubpassDescription::pname:colorAttachmentCount
perform no writes.


[[framebuffer-logicop]]
== Logical Operations

The application can: enable a _logical operation_ between the fragment's
color values and the existing value in the framebuffer attachment. This
logical operation is applied prior to updating the framebuffer attachment.
Logical operations are applied only for signed and unsigned integer and
normalized integer framebuffers. Logical operations are not applied to
floating-point or sRGB format color attachments.

// refBegin VkLogicOp framebuffer logical operations

Logical operations are controlled by the pname:logicOpEnable and
pname:logicOp members of slink:VkPipelineColorBlendStateCreateInfo. If
pname:logicOpEnable is ename:VK_TRUE, then a logical operation selected by
pname:logicOp is applied between each color attachment and the fragment's
corresponding output value, and blending of all attachments is treated as if
it were disabled. Any attachments using color formats for which logical
operations are not supported simply pass through the color values
unmodified. The logical operation is applied independently for each of the
red, green, blue, and alpha components. The pname:logicOp is selected from
the following operations:

include::../api/enums/VkLogicOp.txt[]

<<<

The logical operations supported by Vulkan are summarized in the
following table in which

  * latexmath:[$\lnot$] is bitwise invert,
  * latexmath:[$\land$] is bitwise and,
  * latexmath:[$\lor$] is bitwise or,
  * latexmath:[$\oplus$] is bitwise exclusive or,
  * latexmath:[$s$] is the fragment's latexmath:[$R_{s0}, G_{s0}, B_{s0}$]
    or latexmath:[$A_{s0}$] component value for the fragment output
    corresponding to the color attachment being updated, and
  * latexmath:[$d$] is the color attachment's latexmath:[$R, G, B$] or
    latexmath:[$A$] component value:

.Logical Operations
[width="75%",options="header",align="center"]
|==========================================
|Mode                            | Operation
|ename:VK_LOGIC_OP_CLEAR         | latexmath:[$0$]
|ename:VK_LOGIC_OP_AND           | latexmath:[$s \land d$]
|ename:VK_LOGIC_OP_AND_REVERSE   | latexmath:[$s \land \lnot d$]
|ename:VK_LOGIC_OP_COPY          | latexmath:[$s$]
|ename:VK_LOGIC_OP_AND_INVERTED  | latexmath:[$\lnot s \land d$]
|ename:VK_LOGIC_OP_NO_OP         | latexmath:[$d$]
|ename:VK_LOGIC_OP_XOR           | latexmath:[$s \oplus d$]
|ename:VK_LOGIC_OP_OR            | latexmath:[$s \lor d$]
|ename:VK_LOGIC_OP_NOR           | latexmath:[$\lnot (s \lor d)$]
|ename:VK_LOGIC_OP_EQUIVALENT    | latexmath:[$\lnot (s \oplus d)$]
|ename:VK_LOGIC_OP_INVERT        | latexmath:[$\lnot d$]
|ename:VK_LOGIC_OP_OR_REVERSE    | latexmath:[$s \lor \lnot d$]
|ename:VK_LOGIC_OP_COPY_INVERTED | latexmath:[$\lnot s$]
|ename:VK_LOGIC_OP_OR_INVERTED   | latexmath:[$\lnot s \lor d$]
|ename:VK_LOGIC_OP_NAND          | latexmath:[$\lnot (s \land d)$]
|ename:VK_LOGIC_OP_SET           | all 1s
|==========================================

The result of the logical operation is then written to the color attachment
as controlled by the component write mask, described in
<<framebuffer-blendoperations,Blend Operations>>.

// refEnd VkLogicOp