framebuffer.adoc

The Framebuffer

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 (x_f,y_f) location. Blending is performed for each color sample covered by the fragment, rather than just once for each fragment.

Source and destination values are combined according to the blend operation, quadruplets of source and destination weighting factors determined by the blend factors, and a 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 Conversion from Normalized Fixed-Point to Floating-Point. Blending computations are treated as if carried out in floating-point, and basic blend operations are performed with a precision and dynamic range no lower than that used to represent destination components.

Note	Note Blending is only defined for floating-point, UNORM, SNORM, and sRGB formats. Within those formats, the implementation may only support blending on some subset of them. Which formats support blending is indicated by ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT.

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

The sname:VkPipelineColorBlendStateCreateInfo structure is defined as:

{generated}/api/structs/VkPipelineColorBlendStateCreateInfo.adoc

• pname:sType is the type of this structure.

• pname:pNext is NULL or a pointer to a structure extending this structure.

• pname:flags is reserved for future use.

• pname:logicOpEnable controls whether to apply Logical Operations.

• pname:logicOp selects which logical operation to apply.

• pname:attachmentCount is the number of slink:VkPipelineColorBlendAttachmentState elements in pname:pAttachments.

• pname:pAttachments is a pointer to an array of slink:VkPipelineColorBlendAttachmentState structures defining blend state for each color attachment.

• pname:blendConstants is a pointer to 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 blend factor.

Valid Usage

• If the pname:independentBlend feature is not enabled, all elements of pname:pAttachments must: be identical

• If the pname:logicOp feature is not enabled, pname:logicOpEnable must: be ename:VK_FALSE

• If pname:logicOpEnable is ename:VK_TRUE, pname:logicOp must: be a valid elink:VkLogicOp value

• If pname:attachmentCount is not 0, pname:pAttachments must: be a valid pointer to an array of pname:attachmentCount valid slink:VkPipelineColorBlendAttachmentState structures

{generated}/validity/structs/VkPipelineColorBlendStateCreateInfo.adoc

{generated}/api/flags/VkPipelineColorBlendStateCreateFlags.adoc

tname:VkPipelineColorBlendStateCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use.

The sname:VkPipelineColorBlendAttachmentState structure is defined as:

{generated}/api/structs/VkPipelineColorBlendAttachmentState.adoc

• 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 (S_r,S_g,S_b).

• pname:dstColorBlendFactor selects which blend factor is used to determine the destination factors (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 S_a.

• pname:dstAlphaBlendFactor selects which blend factor is used to determine the destination factor D_a.

• pname:alphaBlendOp selects which blend operation is used to calculate the alpha values to write to the color attachment.

• pname:colorWriteMask is a bitmask of elink:VkColorComponentFlagBits specifying which of the R, G, B, and/or A components are enabled for writing, as described for the Color Write Mask.

Valid Usage

• If the pname:dualSrcBlend feature is not enabled, pname:srcColorBlendFactor must: not be ename:VK_BLEND_FACTOR_SRC1_COLOR, ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, ename:VK_BLEND_FACTOR_SRC1_ALPHA, or ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

• If the pname:dualSrcBlend feature is not enabled, pname:dstColorBlendFactor must: not be ename:VK_BLEND_FACTOR_SRC1_COLOR, ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, ename:VK_BLEND_FACTOR_SRC1_ALPHA, or ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

• If the pname:dualSrcBlend feature is not enabled, pname:srcAlphaBlendFactor must: not be ename:VK_BLEND_FACTOR_SRC1_COLOR, ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, ename:VK_BLEND_FACTOR_SRC1_ALPHA, or ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

• If the pname:dualSrcBlend feature is not enabled, pname:dstAlphaBlendFactor must: not be ename:VK_BLEND_FACTOR_SRC1_COLOR, ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, ename:VK_BLEND_FACTOR_SRC1_ALPHA, or ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

{generated}/validity/structs/VkPipelineColorBlendAttachmentState.adoc

Blend Factors

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

{generated}/api/enums/VkBlendFactor.adoc

The semantics of the enum values are described in the table below:

Table 1. Blend Factors

elink:VkBlendFactor	RGB Blend Factors (Sr,Sg,Sb) or (Dr,Dg,Db)	Alpha Blend Factor (Sa or Da)
ename:VK_BLEND_FACTOR_ZERO	(0,0,0)	0
ename:VK_BLEND_FACTOR_ONE	(1,1,1)	1
ename:VK_BLEND_FACTOR_SRC_COLOR	(Rs0,Gs0,Bs0)	As0
ename:VK_BLEND_FACTOR_ONE_MINUS_SRC_COLOR	(1-Rs0,1-Gs0,1-Bs0)	1-As0
ename:VK_BLEND_FACTOR_DST_COLOR	(Rd,Gd,Bd)	Ad
ename:VK_BLEND_FACTOR_ONE_MINUS_DST_COLOR	(1-Rd,1-Gd,1-Bd)	1-Ad
ename:VK_BLEND_FACTOR_SRC_ALPHA	(As0,As0,As0)	As0
ename:VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA	(1-As0,1-As0,1-As0)	1-As0
ename:VK_BLEND_FACTOR_DST_ALPHA	(Ad,Ad,Ad)	Ad
ename:VK_BLEND_FACTOR_ONE_MINUS_DST_ALPHA	(1-Ad,1-Ad,1-Ad)	1-Ad
ename:VK_BLEND_FACTOR_CONSTANT_COLOR	(Rc,Gc,Bc)	Ac
ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR	(1-Rc,1-Gc,1-Bc)	1-Ac
ename:VK_BLEND_FACTOR_CONSTANT_ALPHA	(Ac,Ac,Ac)	Ac
ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA	(1-Ac,1-Ac,1-Ac)	1-Ac
ename:VK_BLEND_FACTOR_SRC_ALPHA_SATURATE	(f,f,f); f = min(As0,1-Ad)	1
ename:VK_BLEND_FACTOR_SRC1_COLOR	(Rs1,Gs1,Bs1)	As1
ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR	(1-Rs1,1-Gs1,1-Bs1)	1-As1
ename:VK_BLEND_FACTOR_SRC1_ALPHA	(As1,As1,As1)	As1
ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA	(1-As1,1-As1,1-As1)	1-As1

In this table, the following conventions are used:

• R_s0,G_s0,B_s0 and 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.

• R_s1,G_s1,B_s1 and 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.

• R_d,G_d,B_d and 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.

• R_c,G_c,B_c and A_c represent the blend constant R, G, B, and A components, respectively.

To dynamically set and change the blend constants, call:

{generated}/api/protos/vkCmdSetBlendConstants.adoc

• pname:commandBuffer is the command buffer into which the command will be recorded.

• pname:blendConstants is a pointer to an array of four values specifying the R_c, G_c, B_c, and A_c components of the blend constant color used in blending, depending on the blend factor.

This command sets blend constants for subsequent drawing commands when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the slink:VkPipelineColorBlendStateCreateInfo::pname:blendConstants values used to create the currently active pipeline.

{generated}/validity/protos/vkCmdSetBlendConstants.adoc

Dual-Source Blending

Blend factors that use the secondary color input (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 implementation 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 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 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.

Blend Operations

Once the source and destination blend factors have been selected, they along with the source and destination components are passed to the blending operations. RGB and alpha components can: use different operations. Possible values of elink:VkBlendOp, specifying the operations, are:

{generated}/api/enums/VkBlendOp.adoc

The semantics of the basic blend operations are described in the table below:

Table 2. Basic Blend Operations

elink:VkBlendOp	RGB Components	Alpha Component
ename:VK_BLEND_OP_ADD	R = Rs0 {times} Sr + Rd {times} Dr G = Gs0 {times} Sg + Gd {times} Dg B = Bs0 {times} Sb + Bd {times} Db	A = As0 {times} Sa + Ad {times} Da
ename:VK_BLEND_OP_SUBTRACT	R = Rs0 {times} Sr - Rd {times} Dr G = Gs0 {times} Sg - Gd {times} Dg B = Bs0 {times} Sb - Bd {times} Db	A = As0 {times} Sa - Ad {times} Da
ename:VK_BLEND_OP_REVERSE_SUBTRACT	R = Rd {times} Dr - Rs0 {times} Sr G = Gd {times} Dg - Gs0 {times} Sg B = Bd {times} Db - Bs0 {times} Sb	A = Ad {times} Da - As0 {times} Sa
ename:VK_BLEND_OP_MIN	R = min(Rs0,Rd) G = min(Gs0,Gd) B = min(Bs0,Bd)	A = min(As0,Ad)
ename:VK_BLEND_OP_MAX	R = max(Rs0,Rd) G = max(Gs0,Gd) B = max(Bs0,Bd)	A = max(As0,Ad)

In this table, the following conventions are used:

• R_s0, G_s0, B_s0 and A_s0 represent the first source color R, G, B, and A components, respectively.

• R_d, G_d, B_d and 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.

• S_r, S_g, S_b and S_a represent the source blend factor R, G, B, and A components, respectively.

• D_r, D_g, D_b and D_a represent the destination blend factor R, G, B, and A components, respectively.

The blending operation produces a new set of values R, G, B and A, which are written to the framebuffer attachment. If blending is not enabled for this attachment, then R, G, B and A are assigned R_s0, G_s0, B_s0 and 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 [0,1] or [-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.

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 “sRGB EOTF” 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 “sRGB EOTF ^-1” section of the Khronos Data Format Specification.

If the numeric format of a framebuffer color attachment is not sRGB encoded then the resulting 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. Writes are not performed to framebuffer color attachments greater than or equal to the sname:VkSubpassDescription::pname:colorAttachmentCount value.

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.

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:

{generated}/api/enums/VkLogicOp.adoc

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

• {lnot} is bitwise invert,

• {land} is bitwise and,

• {lor} is bitwise or,

• {oplus} is bitwise exclusive or,

• s is the fragment’s R_s0, G_s0, B_s0 or A_s0 component value for the fragment output corresponding to the color attachment being updated, and

• d is the color attachment’s R, G, B or A component value:

Table 3. Logical Operations

Mode	Operation
ename:VK_LOGIC_OP_CLEAR	0
ename:VK_LOGIC_OP_AND	s {land} d
ename:VK_LOGIC_OP_AND_REVERSE	s {land} {lnot} d
ename:VK_LOGIC_OP_COPY	s
ename:VK_LOGIC_OP_AND_INVERTED	{lnot} s {land} d
ename:VK_LOGIC_OP_NO_OP	d
ename:VK_LOGIC_OP_XOR	s {oplus} d
ename:VK_LOGIC_OP_OR	s {lor} d
ename:VK_LOGIC_OP_NOR	{lnot} (s {lor} d)
ename:VK_LOGIC_OP_EQUIVALENT	{lnot} (s {oplus} d)
ename:VK_LOGIC_OP_INVERT	{lnot} d
ename:VK_LOGIC_OP_OR_REVERSE	s {lor} {lnot} d
ename:VK_LOGIC_OP_COPY_INVERTED	{lnot} s
ename:VK_LOGIC_OP_OR_INVERTED	{lnot} s {lor} d
ename:VK_LOGIC_OP_NAND	{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 Blend Operations.

Color Write Mask

Bits which can: be set in slink:VkPipelineColorBlendAttachmentState::pname:colorWriteMask, determining whether the final color values R, G, B and A are written to the framebuffer attachment, are:

{generated}/api/enums/VkColorComponentFlagBits.adoc

• ename:VK_COLOR_COMPONENT_R_BIT specifies that the R value is written to the color attachment for the appropriate sample. Otherwise, the value in memory is unmodified.

• ename:VK_COLOR_COMPONENT_G_BIT specifies that the G value is written to the color attachment for the appropriate sample. Otherwise, the value in memory is unmodified.

• ename:VK_COLOR_COMPONENT_B_BIT specifies that the B value is written to the color attachment for the appropriate sample. Otherwise, the value in memory is unmodified.

• ename:VK_COLOR_COMPONENT_A_BIT specifies that the A value is written to the color attachment for the appropriate sample. Otherwise, the value in memory is unmodified.

The color write mask operation is applied regardless of whether blending is enabled.

{generated}/api/flags/VkColorComponentFlags.adoc

tname:VkColorComponentFlags is a bitmask type for setting a mask of zero or more elink:VkColorComponentFlagBits.