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 (xf,yf) 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. Advanced blending operations are performed with a precision and dynamic range no lower than the smaller of that used to represent destination components or that used to represent 16-bit floating-point values.

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 VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT.

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

The VkPipelineColorBlendStateCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPipelineColorBlendStateCreateInfo {
    VkStructureType                               sType;
    const void*                                   pNext;
    VkPipelineColorBlendStateCreateFlags          flags;
    VkBool32                                      logicOpEnable;
    VkLogicOp                                     logicOp;
    uint32_t                                      attachmentCount;
    const VkPipelineColorBlendAttachmentState*    pAttachments;
    float                                         blendConstants[4];
} VkPipelineColorBlendStateCreateInfo;
  • sType is a VkStructureType value identifying this structure.

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

  • flags is a bitmask of VkPipelineColorBlendStateCreateFlagBits specifying additional color blending information.

  • logicOpEnable controls whether to apply Logical Operations.

  • logicOp selects which logical operation to apply.

  • attachmentCount is the number of VkPipelineColorBlendAttachmentState elements in pAttachments. It is ignored if the pipeline is created with VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT, VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT, and VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT dynamic states set, and either VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT set or advancedBlendCoherentOperations is not enabled on the device.

  • pAttachments is a pointer to an array of VkPipelineColorBlendAttachmentState structures defining blend state for each color attachment. It is ignored if the pipeline is created with VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT, VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT, and VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT dynamic states set, and either VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT set or advancedBlendCoherentOperations is not enabled on the device.

  • 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
  • VUID-VkPipelineColorBlendStateCreateInfo-pAttachments-00605
    If the independentBlend feature is not enabled, all elements of pAttachments must be identical

  • VUID-VkPipelineColorBlendStateCreateInfo-logicOpEnable-00606
    If the logicOp feature is not enabled, logicOpEnable must be VK_FALSE

  • VUID-VkPipelineColorBlendStateCreateInfo-logicOpEnable-00607
    If logicOpEnable is VK_TRUE, logicOp must be a valid VkLogicOp value

  • VUID-VkPipelineColorBlendStateCreateInfo-rasterizationOrderColorAttachmentAccess-06465
    If the rasterizationOrderColorAttachmentAccess feature is not enabled, flags must not include VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT

  • VUID-VkPipelineColorBlendStateCreateInfo-pAttachments-07353
    If attachmentCount is not 0 , and any of VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT, VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT, VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT, or VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT are not set, pAttachments must be a valid pointer to an array of attachmentCount valid VkPipelineColorBlendAttachmentState structures

Valid Usage (Implicit)
  • VUID-VkPipelineColorBlendStateCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_STATE_CREATE_INFO

  • VUID-VkPipelineColorBlendStateCreateInfo-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkPipelineColorBlendAdvancedStateCreateInfoEXT or VkPipelineColorWriteCreateInfoEXT

  • VUID-VkPipelineColorBlendStateCreateInfo-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkPipelineColorBlendStateCreateInfo-flags-parameter
    flags must be a valid combination of VkPipelineColorBlendStateCreateFlagBits values

  • VUID-VkPipelineColorBlendStateCreateInfo-pAttachments-parameter
    If attachmentCount is not 0, and pAttachments is not NULL, pAttachments must be a valid pointer to an array of attachmentCount valid VkPipelineColorBlendAttachmentState structures

// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineColorBlendStateCreateFlags;

VkPipelineColorBlendStateCreateFlags is a bitmask type for setting a mask of zero or more VkPipelineColorBlendStateCreateFlagBits.

Bits which can be set in the VkPipelineColorBlendStateCreateInfo::flags parameter are:

// Provided by VK_EXT_rasterization_order_attachment_access
typedef enum VkPipelineColorBlendStateCreateFlagBits {
  // Provided by VK_EXT_rasterization_order_attachment_access
    VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT = 0x00000001,
  // Provided by VK_ARM_rasterization_order_attachment_access
    VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARM = VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT,
} VkPipelineColorBlendStateCreateFlagBits;
  • VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT indicates that access to color and input attachments will have implicit framebuffer-local memory dependencies, allowing applications to express custom blending operations in a fragment shader.

When VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT is included in a pipeline, it forms a framebuffer-local memory dependency for each fragment generated by draw commands for that pipeline with the following scopes:

  • The first synchronization scope includes the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage executed by all previous fragments (as defined by primitive order) in the corresponding framebuffer regions including those generated by the same draw command.

  • The second synchronization scope includes the VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT pipeline stage executed by the generated fragment.

  • The first access scope includes all writes to color attachments.

  • The second access scope includes all reads from input attachments.

The VkPipelineColorBlendAttachmentState structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPipelineColorBlendAttachmentState {
    VkBool32                 blendEnable;
    VkBlendFactor            srcColorBlendFactor;
    VkBlendFactor            dstColorBlendFactor;
    VkBlendOp                colorBlendOp;
    VkBlendFactor            srcAlphaBlendFactor;
    VkBlendFactor            dstAlphaBlendFactor;
    VkBlendOp                alphaBlendOp;
    VkColorComponentFlags    colorWriteMask;
} VkPipelineColorBlendAttachmentState;
  • 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.

  • srcColorBlendFactor selects which blend factor is used to determine the source factors (Sr,Sg,Sb).

  • dstColorBlendFactor selects which blend factor is used to determine the destination factors (Dr,Dg,Db).

  • colorBlendOp selects which blend operation is used to calculate the RGB values to write to the color attachment.

  • srcAlphaBlendFactor selects which blend factor is used to determine the source factor Sa.

  • dstAlphaBlendFactor selects which blend factor is used to determine the destination factor Da.

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

  • colorWriteMask is a bitmask of 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
  • VUID-VkPipelineColorBlendAttachmentState-srcColorBlendFactor-00608
    If the dualSrcBlend feature is not enabled, srcColorBlendFactor must not be VK_BLEND_FACTOR_SRC1_COLOR, VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, VK_BLEND_FACTOR_SRC1_ALPHA, or VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

  • VUID-VkPipelineColorBlendAttachmentState-dstColorBlendFactor-00609
    If the dualSrcBlend feature is not enabled, dstColorBlendFactor must not be VK_BLEND_FACTOR_SRC1_COLOR, VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, VK_BLEND_FACTOR_SRC1_ALPHA, or VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

  • VUID-VkPipelineColorBlendAttachmentState-srcAlphaBlendFactor-00610
    If the dualSrcBlend feature is not enabled, srcAlphaBlendFactor must not be VK_BLEND_FACTOR_SRC1_COLOR, VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, VK_BLEND_FACTOR_SRC1_ALPHA, or VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

  • VUID-VkPipelineColorBlendAttachmentState-dstAlphaBlendFactor-00611
    If the dualSrcBlend feature is not enabled, dstAlphaBlendFactor must not be VK_BLEND_FACTOR_SRC1_COLOR, VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, VK_BLEND_FACTOR_SRC1_ALPHA, or VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

  • VUID-VkPipelineColorBlendAttachmentState-colorBlendOp-01406
    If either of colorBlendOp or alphaBlendOp is an advanced blend operation, then colorBlendOp must equal alphaBlendOp

  • VUID-VkPipelineColorBlendAttachmentState-advancedBlendIndependentBlend-01407
    If VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::advancedBlendIndependentBlend is VK_FALSE and colorBlendOp is an advanced blend operation, then colorBlendOp must be the same for all attachments

  • VUID-VkPipelineColorBlendAttachmentState-advancedBlendIndependentBlend-01408
    If VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::advancedBlendIndependentBlend is VK_FALSE and alphaBlendOp is an advanced blend operation, then alphaBlendOp must be the same for all attachments

  • VUID-VkPipelineColorBlendAttachmentState-advancedBlendAllOperations-01409
    If VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::advancedBlendAllOperations is VK_FALSE, then colorBlendOp must not be VK_BLEND_OP_ZERO_EXT, VK_BLEND_OP_SRC_EXT, VK_BLEND_OP_DST_EXT, VK_BLEND_OP_SRC_OVER_EXT, VK_BLEND_OP_DST_OVER_EXT, VK_BLEND_OP_SRC_IN_EXT, VK_BLEND_OP_DST_IN_EXT, VK_BLEND_OP_SRC_OUT_EXT, VK_BLEND_OP_DST_OUT_EXT, VK_BLEND_OP_SRC_ATOP_EXT, VK_BLEND_OP_DST_ATOP_EXT, VK_BLEND_OP_XOR_EXT, VK_BLEND_OP_INVERT_EXT, VK_BLEND_OP_INVERT_RGB_EXT, VK_BLEND_OP_LINEARDODGE_EXT, VK_BLEND_OP_LINEARBURN_EXT, VK_BLEND_OP_VIVIDLIGHT_EXT, VK_BLEND_OP_LINEARLIGHT_EXT, VK_BLEND_OP_PINLIGHT_EXT, VK_BLEND_OP_HARDMIX_EXT, VK_BLEND_OP_PLUS_EXT, VK_BLEND_OP_PLUS_CLAMPED_EXT, VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT, VK_BLEND_OP_PLUS_DARKER_EXT, VK_BLEND_OP_MINUS_EXT, VK_BLEND_OP_MINUS_CLAMPED_EXT, VK_BLEND_OP_CONTRAST_EXT, VK_BLEND_OP_INVERT_OVG_EXT, VK_BLEND_OP_RED_EXT, VK_BLEND_OP_GREEN_EXT, or VK_BLEND_OP_BLUE_EXT

  • VUID-VkPipelineColorBlendAttachmentState-colorBlendOp-01410
    If colorBlendOp or alphaBlendOp is an advanced blend operation, then colorAttachmentCount of the subpass this pipeline is compiled against must be less than or equal to VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::advancedBlendMaxColorAttachments

  • VUID-VkPipelineColorBlendAttachmentState-constantAlphaColorBlendFactors-04454
    If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::constantAlphaColorBlendFactors is VK_FALSE, srcColorBlendFactor must not be VK_BLEND_FACTOR_CONSTANT_ALPHA or VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA

  • VUID-VkPipelineColorBlendAttachmentState-constantAlphaColorBlendFactors-04455
    If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::constantAlphaColorBlendFactors is VK_FALSE, dstColorBlendFactor must not be VK_BLEND_FACTOR_CONSTANT_ALPHA or VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA

Valid Usage (Implicit)
  • VUID-VkPipelineColorBlendAttachmentState-srcColorBlendFactor-parameter
    srcColorBlendFactor must be a valid VkBlendFactor value

  • VUID-VkPipelineColorBlendAttachmentState-dstColorBlendFactor-parameter
    dstColorBlendFactor must be a valid VkBlendFactor value

  • VUID-VkPipelineColorBlendAttachmentState-colorBlendOp-parameter
    colorBlendOp must be a valid VkBlendOp value

  • VUID-VkPipelineColorBlendAttachmentState-srcAlphaBlendFactor-parameter
    srcAlphaBlendFactor must be a valid VkBlendFactor value

  • VUID-VkPipelineColorBlendAttachmentState-dstAlphaBlendFactor-parameter
    dstAlphaBlendFactor must be a valid VkBlendFactor value

  • VUID-VkPipelineColorBlendAttachmentState-alphaBlendOp-parameter
    alphaBlendOp must be a valid VkBlendOp value

  • VUID-VkPipelineColorBlendAttachmentState-colorWriteMask-parameter
    colorWriteMask must be a valid combination of VkColorComponentFlagBits values

To dynamically set blendEnable, call:

// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetColorBlendEnableEXT(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    firstAttachment,
    uint32_t                                    attachmentCount,
    const VkBool32*                             pColorBlendEnables);
  • commandBuffer is the command buffer into which the command will be recorded.

  • firstAttachment the first color attachment the color blending enable applies.

  • attachmentCount the number of color blending enables in the pColorBlendEnables array.

  • pColorBlendEnables an array of booleans to indicate whether color blending is enabled for the corresponding attachment.

This command sets the color blending enable of the specified color attachments for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineColorBlendAttachmentState::blendEnable values used to create the currently active pipeline.

Valid Usage
Valid Usage (Implicit)
  • VUID-vkCmdSetColorBlendEnableEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetColorBlendEnableEXT-pColorBlendEnables-parameter
    pColorBlendEnables must be a valid pointer to an array of attachmentCount VkBool32 values

  • VUID-vkCmdSetColorBlendEnableEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetColorBlendEnableEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetColorBlendEnableEXT-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdSetColorBlendEnableEXT-attachmentCount-arraylength
    attachmentCount must be greater than 0

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

To dynamically set color blend factors and operations, call:

// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetColorBlendEquationEXT(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    firstAttachment,
    uint32_t                                    attachmentCount,
    const VkColorBlendEquationEXT*              pColorBlendEquations);
  • commandBuffer is the command buffer into which the command will be recorded.

  • firstAttachment the first color attachment the color blend factors and operations apply to.

  • attachmentCount the number of VkColorBlendEquationEXT elements in the pColorBlendEquations array.

  • pColorBlendEquations an array of VkColorBlendEquationEXT structs that specify the color blend factors and operations for the corresponding attachments.

This command sets the color blending factors and operations of the specified attachments for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineColorBlendAttachmentState::srcColorBlendFactor, VkPipelineColorBlendAttachmentState::dstColorBlendFactor, VkPipelineColorBlendAttachmentState::colorBlendOp, VkPipelineColorBlendAttachmentState::srcAlphaBlendFactor, VkPipelineColorBlendAttachmentState::dstAlphaBlendFactor, and VkPipelineColorBlendAttachmentState::alphaBlendOp values used to create the currently active pipeline.

Valid Usage
Valid Usage (Implicit)
  • VUID-vkCmdSetColorBlendEquationEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetColorBlendEquationEXT-pColorBlendEquations-parameter
    pColorBlendEquations must be a valid pointer to an array of attachmentCount valid VkColorBlendEquationEXT structures

  • VUID-vkCmdSetColorBlendEquationEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetColorBlendEquationEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetColorBlendEquationEXT-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdSetColorBlendEquationEXT-attachmentCount-arraylength
    attachmentCount must be greater than 0

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

The VkColorBlendEquationEXT structure is defined as:

// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
typedef struct VkColorBlendEquationEXT {
    VkBlendFactor    srcColorBlendFactor;
    VkBlendFactor    dstColorBlendFactor;
    VkBlendOp        colorBlendOp;
    VkBlendFactor    srcAlphaBlendFactor;
    VkBlendFactor    dstAlphaBlendFactor;
    VkBlendOp        alphaBlendOp;
} VkColorBlendEquationEXT;
  • srcColorBlendFactor selects which blend factor is used to determine the source factors (Sr,Sg,Sb).

  • dstColorBlendFactor selects which blend factor is used to determine the destination factors (Dr,Dg,Db).

  • colorBlendOp selects which blend operation is used to calculate the RGB values to write to the color attachment.

  • srcAlphaBlendFactor selects which blend factor is used to determine the source factor Sa.

  • dstAlphaBlendFactor selects which blend factor is used to determine the destination factor Da.

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

Valid Usage
  • VUID-VkColorBlendEquationEXT-dualSrcBlend-07357
    If the dualSrcBlend feature is not enabled, srcColorBlendFactor must not be VK_BLEND_FACTOR_SRC1_COLOR, VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, VK_BLEND_FACTOR_SRC1_ALPHA, or VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

  • VUID-VkColorBlendEquationEXT-dualSrcBlend-07358
    If the dualSrcBlend feature is not enabled, dstColorBlendFactor must not be VK_BLEND_FACTOR_SRC1_COLOR, VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, VK_BLEND_FACTOR_SRC1_ALPHA, or VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

  • VUID-VkColorBlendEquationEXT-dualSrcBlend-07359
    If the dualSrcBlend feature is not enabled, srcAlphaBlendFactor must not be VK_BLEND_FACTOR_SRC1_COLOR, VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, VK_BLEND_FACTOR_SRC1_ALPHA, or VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

  • VUID-VkColorBlendEquationEXT-dualSrcBlend-07360
    If the dualSrcBlend feature is not enabled, dstAlphaBlendFactor must not be VK_BLEND_FACTOR_SRC1_COLOR, VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, VK_BLEND_FACTOR_SRC1_ALPHA, or VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

  • VUID-VkColorBlendEquationEXT-colorBlendOp-07361
    colorBlendOp and alphaBlendOp must not be VK_BLEND_OP_ZERO_EXT, VK_BLEND_OP_SRC_EXT, VK_BLEND_OP_DST_EXT, VK_BLEND_OP_SRC_OVER_EXT, VK_BLEND_OP_DST_OVER_EXT, VK_BLEND_OP_SRC_IN_EXT, VK_BLEND_OP_DST_IN_EXT, VK_BLEND_OP_SRC_OUT_EXT, VK_BLEND_OP_DST_OUT_EXT, VK_BLEND_OP_SRC_ATOP_EXT, VK_BLEND_OP_DST_ATOP_EXT, VK_BLEND_OP_XOR_EXT, VK_BLEND_OP_MULTIPLY_EXT, VK_BLEND_OP_SCREEN_EXT, VK_BLEND_OP_OVERLAY_EXT, VK_BLEND_OP_DARKEN_EXT, VK_BLEND_OP_LIGHTEN_EXT, VK_BLEND_OP_COLORDODGE_EXT, VK_BLEND_OP_COLORBURN_EXT, VK_BLEND_OP_HARDLIGHT_EXT, VK_BLEND_OP_SOFTLIGHT_EXT, VK_BLEND_OP_DIFFERENCE_EXT, VK_BLEND_OP_EXCLUSION_EXT, VK_BLEND_OP_INVERT_EXT, VK_BLEND_OP_INVERT_RGB_EXT, VK_BLEND_OP_LINEARDODGE_EXT, VK_BLEND_OP_LINEARBURN_EXT, VK_BLEND_OP_VIVIDLIGHT_EXT, VK_BLEND_OP_LINEARLIGHT_EXT, VK_BLEND_OP_PINLIGHT_EXT, VK_BLEND_OP_HARDMIX_EXT, VK_BLEND_OP_HSL_HUE_EXT, VK_BLEND_OP_HSL_SATURATION_EXT, VK_BLEND_OP_HSL_COLOR_EXT, VK_BLEND_OP_HSL_LUMINOSITY_EXT, VK_BLEND_OP_PLUS_EXT, VK_BLEND_OP_PLUS_CLAMPED_EXT, VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT, VK_BLEND_OP_PLUS_DARKER_EXT, VK_BLEND_OP_MINUS_EXT, VK_BLEND_OP_MINUS_CLAMPED_EXT, VK_BLEND_OP_CONTRAST_EXT, VK_BLEND_OP_INVERT_OVG_EXT, VK_BLEND_OP_RED_EXT, VK_BLEND_OP_GREEN_EXT, or VK_BLEND_OP_BLUE_EXT

  • VUID-VkColorBlendEquationEXT-constantAlphaColorBlendFactors-07362
    If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::constantAlphaColorBlendFactors is VK_FALSE, srcColorBlendFactor must not be VK_BLEND_FACTOR_CONSTANT_ALPHA or VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA

  • VUID-VkColorBlendEquationEXT-constantAlphaColorBlendFactors-07363
    If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::constantAlphaColorBlendFactors is VK_FALSE, dstColorBlendFactor must not be VK_BLEND_FACTOR_CONSTANT_ALPHA or VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA

Valid Usage (Implicit)
  • VUID-VkColorBlendEquationEXT-srcColorBlendFactor-parameter
    srcColorBlendFactor must be a valid VkBlendFactor value

  • VUID-VkColorBlendEquationEXT-dstColorBlendFactor-parameter
    dstColorBlendFactor must be a valid VkBlendFactor value

  • VUID-VkColorBlendEquationEXT-colorBlendOp-parameter
    colorBlendOp must be a valid VkBlendOp value

  • VUID-VkColorBlendEquationEXT-srcAlphaBlendFactor-parameter
    srcAlphaBlendFactor must be a valid VkBlendFactor value

  • VUID-VkColorBlendEquationEXT-dstAlphaBlendFactor-parameter
    dstAlphaBlendFactor must be a valid VkBlendFactor value

  • VUID-VkColorBlendEquationEXT-alphaBlendOp-parameter
    alphaBlendOp must be a valid VkBlendOp value

To dynamically set the color write masks, call:

// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetColorWriteMaskEXT(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    firstAttachment,
    uint32_t                                    attachmentCount,
    const VkColorComponentFlags*                pColorWriteMasks);
  • commandBuffer is the command buffer into which the command will be recorded.

  • firstAttachment the first color attachment the color write masks apply to.

  • attachmentCount the number of VkColorComponentFlags values in the pColorWriteMasks array.

  • pColorWriteMasks an array of VkColorComponentFlags values that specify the color write masks of the corresponding attachments.

This command sets the color write masks of the specified attachments for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineColorBlendAttachmentState::colorWriteMask values used to create the currently active pipeline.

Note

Formats with bits that are shared between components specified by VkColorComponentFlagBits, such as VK_FORMAT_E5B9G9R9_UFLOAT_PACK32, cannot have their channels individually masked by this functionality; either all components that share bits have to be enabled, or none of them.

Valid Usage
Valid Usage (Implicit)
  • VUID-vkCmdSetColorWriteMaskEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetColorWriteMaskEXT-pColorWriteMasks-parameter
    pColorWriteMasks must be a valid pointer to an array of attachmentCount valid combinations of VkColorComponentFlagBits values

  • VUID-vkCmdSetColorWriteMaskEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetColorWriteMaskEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetColorWriteMaskEXT-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdSetColorWriteMaskEXT-attachmentCount-arraylength
    attachmentCount must be greater than 0

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

Blend Factors

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

// Provided by VK_VERSION_1_0
typedef enum VkBlendFactor {
    VK_BLEND_FACTOR_ZERO = 0,
    VK_BLEND_FACTOR_ONE = 1,
    VK_BLEND_FACTOR_SRC_COLOR = 2,
    VK_BLEND_FACTOR_ONE_MINUS_SRC_COLOR = 3,
    VK_BLEND_FACTOR_DST_COLOR = 4,
    VK_BLEND_FACTOR_ONE_MINUS_DST_COLOR = 5,
    VK_BLEND_FACTOR_SRC_ALPHA = 6,
    VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA = 7,
    VK_BLEND_FACTOR_DST_ALPHA = 8,
    VK_BLEND_FACTOR_ONE_MINUS_DST_ALPHA = 9,
    VK_BLEND_FACTOR_CONSTANT_COLOR = 10,
    VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR = 11,
    VK_BLEND_FACTOR_CONSTANT_ALPHA = 12,
    VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA = 13,
    VK_BLEND_FACTOR_SRC_ALPHA_SATURATE = 14,
    VK_BLEND_FACTOR_SRC1_COLOR = 15,
    VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR = 16,
    VK_BLEND_FACTOR_SRC1_ALPHA = 17,
    VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA = 18,
} VkBlendFactor;

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

Table 1. Blend Factors
VkBlendFactor RGB Blend Factors (Sr,Sg,Sb) or (Dr,Dg,Db) Alpha Blend Factor (Sa or Da)

VK_BLEND_FACTOR_ZERO

(0,0,0)

0

VK_BLEND_FACTOR_ONE

(1,1,1)

1

VK_BLEND_FACTOR_SRC_COLOR

(Rs0,Gs0,Bs0)

As0

VK_BLEND_FACTOR_ONE_MINUS_SRC_COLOR

(1-Rs0,1-Gs0,1-Bs0)

1-As0

VK_BLEND_FACTOR_DST_COLOR

(Rd,Gd,Bd)

Ad

VK_BLEND_FACTOR_ONE_MINUS_DST_COLOR

(1-Rd,1-Gd,1-Bd)

1-Ad

VK_BLEND_FACTOR_SRC_ALPHA

(As0,As0,As0)

As0

VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA

(1-As0,1-As0,1-As0)

1-As0

VK_BLEND_FACTOR_DST_ALPHA

(Ad,Ad,Ad)

Ad

VK_BLEND_FACTOR_ONE_MINUS_DST_ALPHA

(1-Ad,1-Ad,1-Ad)

1-Ad

VK_BLEND_FACTOR_CONSTANT_COLOR

(Rc,Gc,Bc)

Ac

VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR

(1-Rc,1-Gc,1-Bc)

1-Ac

VK_BLEND_FACTOR_CONSTANT_ALPHA

(Ac,Ac,Ac)

Ac

VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA

(1-Ac,1-Ac,1-Ac)

1-Ac

VK_BLEND_FACTOR_SRC_ALPHA_SATURATE

(f,f,f); f = min(As0,1-Ad)

1

VK_BLEND_FACTOR_SRC1_COLOR

(Rs1,Gs1,Bs1)

As1

VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR

(1-Rs1,1-Gs1,1-Bs1)

1-As1

VK_BLEND_FACTOR_SRC1_ALPHA

(As1,As1,As1)

As1

VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA

(1-As1,1-As1,1-As1)

1-As1

In this table, the following conventions are used:

  • Rs0,Gs0,Bs0 and As0 represent the first source color R, G, B, and A components, respectively, for the fragment output location corresponding to the color attachment being blended.

  • Rs1,Gs1,Bs1 and As1 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.

  • Rd,Gd,Bd and Ad 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.

  • Rc,Gc,Bc and Ac represent the blend constant R, G, B, and A components, respectively.

To dynamically set and change the blend constants, call:

// Provided by VK_VERSION_1_0
void vkCmdSetBlendConstants(
    VkCommandBuffer                             commandBuffer,
    const float                                 blendConstants[4]);
  • commandBuffer is the command buffer into which the command will be recorded.

  • blendConstants is a pointer to an array of four values specifying the Rc, Gc, Bc, and Ac components of the blend constant color used in blending, depending on the blend factor.

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

Valid Usage (Implicit)
  • VUID-vkCmdSetBlendConstants-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetBlendConstants-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetBlendConstants-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetBlendConstants-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

Dual-Source Blending

Blend factors that use the secondary color input (Rs1,Gs1,Bs1,As1) (VK_BLEND_FACTOR_SRC1_COLOR, VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, VK_BLEND_FACTOR_SRC1_ALPHA, and 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 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 maxFragmentDualSrcAttachments member of VkPhysicalDeviceLimits.

Color outputs can be bound to the first and second inputs of the blender using the 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 value of the second input is undefined.

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 VkBlendOp, specifying the operations, are:

// Provided by VK_VERSION_1_0
typedef enum VkBlendOp {
    VK_BLEND_OP_ADD = 0,
    VK_BLEND_OP_SUBTRACT = 1,
    VK_BLEND_OP_REVERSE_SUBTRACT = 2,
    VK_BLEND_OP_MIN = 3,
    VK_BLEND_OP_MAX = 4,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_ZERO_EXT = 1000148000,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_SRC_EXT = 1000148001,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_DST_EXT = 1000148002,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_SRC_OVER_EXT = 1000148003,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_DST_OVER_EXT = 1000148004,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_SRC_IN_EXT = 1000148005,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_DST_IN_EXT = 1000148006,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_SRC_OUT_EXT = 1000148007,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_DST_OUT_EXT = 1000148008,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_SRC_ATOP_EXT = 1000148009,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_DST_ATOP_EXT = 1000148010,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_XOR_EXT = 1000148011,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_MULTIPLY_EXT = 1000148012,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_SCREEN_EXT = 1000148013,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_OVERLAY_EXT = 1000148014,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_DARKEN_EXT = 1000148015,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_LIGHTEN_EXT = 1000148016,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_COLORDODGE_EXT = 1000148017,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_COLORBURN_EXT = 1000148018,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_HARDLIGHT_EXT = 1000148019,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_SOFTLIGHT_EXT = 1000148020,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_DIFFERENCE_EXT = 1000148021,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_EXCLUSION_EXT = 1000148022,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_INVERT_EXT = 1000148023,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_INVERT_RGB_EXT = 1000148024,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_LINEARDODGE_EXT = 1000148025,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_LINEARBURN_EXT = 1000148026,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_VIVIDLIGHT_EXT = 1000148027,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_LINEARLIGHT_EXT = 1000148028,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_PINLIGHT_EXT = 1000148029,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_HARDMIX_EXT = 1000148030,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_HSL_HUE_EXT = 1000148031,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_HSL_SATURATION_EXT = 1000148032,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_HSL_COLOR_EXT = 1000148033,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_HSL_LUMINOSITY_EXT = 1000148034,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_PLUS_EXT = 1000148035,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_PLUS_CLAMPED_EXT = 1000148036,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT = 1000148037,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_PLUS_DARKER_EXT = 1000148038,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_MINUS_EXT = 1000148039,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_MINUS_CLAMPED_EXT = 1000148040,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_CONTRAST_EXT = 1000148041,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_INVERT_OVG_EXT = 1000148042,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_RED_EXT = 1000148043,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_GREEN_EXT = 1000148044,
  // Provided by VK_EXT_blend_operation_advanced
    VK_BLEND_OP_BLUE_EXT = 1000148045,
} VkBlendOp;

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

Table 2. Basic Blend Operations
VkBlendOp RGB Components Alpha Component

VK_BLEND_OP_ADD

R = Rs0 × Sr + Rd × Dr
G = Gs0 × Sg + Gd × Dg
B = Bs0 × Sb + Bd × Db

A = As0 × Sa + Ad × Da

VK_BLEND_OP_SUBTRACT

R = Rs0 × Sr - Rd × Dr
G = Gs0 × Sg - Gd × Dg
B = Bs0 × Sb - Bd × Db

A = As0 × Sa - Ad × Da

VK_BLEND_OP_REVERSE_SUBTRACT

R = Rd × Dr - Rs0 × Sr
G = Gd × Dg - Gs0 × Sg
B = Bd × Db - Bs0 × Sb

A = Ad × Da - As0 × Sa

VK_BLEND_OP_MIN

R = min(Rs0,Rd)
G = min(Gs0,Gd)
B = min(Bs0,Bd)

A = min(As0,Ad)

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:

  • Rs0, Gs0, Bs0 and As0 represent the first source color R, G, B, and A components, respectively.

  • Rd, Gd, Bd and Ad 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.

  • Sr, Sg, Sb and Sa represent the source blend factor R, G, B, and A components, respectively.

  • Dr, Dg, Db and Da 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 Rs0, Gs0, Bs0 and As0, 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 cs 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 VK_ATTACHMENT_UNUSED, no writes are performed through that attachment. Writes are not performed to framebuffer color attachments greater than or equal to the VkSubpassDescription::colorAttachmentCount or VkSubpassDescription2::colorAttachmentCount value.

Advanced Blend Operations

If the pNext chain of VkPipelineColorBlendStateCreateInfo includes a VkPipelineColorBlendAdvancedStateCreateInfoEXT structure, then that structure includes parameters that affect advanced blend operations.

The VkPipelineColorBlendAdvancedStateCreateInfoEXT structure is defined as:

// Provided by VK_EXT_blend_operation_advanced
typedef struct VkPipelineColorBlendAdvancedStateCreateInfoEXT {
    VkStructureType      sType;
    const void*          pNext;
    VkBool32             srcPremultiplied;
    VkBool32             dstPremultiplied;
    VkBlendOverlapEXT    blendOverlap;
} VkPipelineColorBlendAdvancedStateCreateInfoEXT;
  • sType is a VkStructureType value identifying this structure.

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

  • srcPremultiplied specifies whether the source color of the blend operation is treated as premultiplied.

  • dstPremultiplied specifies whether the destination color of the blend operation is treated as premultiplied.

  • blendOverlap is a VkBlendOverlapEXT value specifying how the source and destination sample’s coverage is correlated.

If this structure is not present, srcPremultiplied and dstPremultiplied are both considered to be VK_TRUE, and blendOverlap is considered to be VK_BLEND_OVERLAP_UNCORRELATED_EXT.

Valid Usage
  • VUID-VkPipelineColorBlendAdvancedStateCreateInfoEXT-srcPremultiplied-01424
    If the non-premultiplied source color property is not supported, srcPremultiplied must be VK_TRUE

  • VUID-VkPipelineColorBlendAdvancedStateCreateInfoEXT-dstPremultiplied-01425
    If the non-premultiplied destination color property is not supported, dstPremultiplied must be VK_TRUE

  • VUID-VkPipelineColorBlendAdvancedStateCreateInfoEXT-blendOverlap-01426
    If the correlated overlap property is not supported, blendOverlap must be VK_BLEND_OVERLAP_UNCORRELATED_EXT

Valid Usage (Implicit)
  • VUID-VkPipelineColorBlendAdvancedStateCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_ADVANCED_STATE_CREATE_INFO_EXT

  • VUID-VkPipelineColorBlendAdvancedStateCreateInfoEXT-blendOverlap-parameter
    blendOverlap must be a valid VkBlendOverlapEXT value

To dynamically set the advanced blend state, call:

// Provided by VK_EXT_blend_operation_advanced with VK_EXT_extended_dynamic_state3, VK_EXT_blend_operation_advanced with VK_EXT_shader_object
void vkCmdSetColorBlendAdvancedEXT(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    firstAttachment,
    uint32_t                                    attachmentCount,
    const VkColorBlendAdvancedEXT*              pColorBlendAdvanced);
  • commandBuffer is the command buffer into which the command will be recorded.

  • firstAttachment the first color attachment the advanced blend parameters apply to.

  • attachmentCount the number of VkColorBlendAdvancedEXT elements in the pColorBlendAdvanced array.

  • pColorBlendAdvanced an array of VkColorBlendAdvancedEXT structs that specify the advanced color blend parameters for the corresponding attachments.

This command sets the advanced blend operation parameters of the specified attachments for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineColorBlendAdvancedStateCreateInfoEXT::srcPremultiplied, VkPipelineColorBlendAdvancedStateCreateInfoEXT::dstPremultiplied, and VkPipelineColorBlendAdvancedStateCreateInfoEXT::blendOverlap values used to create the currently active pipeline.

Valid Usage
Valid Usage (Implicit)
  • VUID-vkCmdSetColorBlendAdvancedEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetColorBlendAdvancedEXT-pColorBlendAdvanced-parameter
    pColorBlendAdvanced must be a valid pointer to an array of attachmentCount valid VkColorBlendAdvancedEXT structures

  • VUID-vkCmdSetColorBlendAdvancedEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetColorBlendAdvancedEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetColorBlendAdvancedEXT-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdSetColorBlendAdvancedEXT-attachmentCount-arraylength
    attachmentCount must be greater than 0

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

The VkColorBlendAdvancedEXT structure is defined as:

// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
typedef struct VkColorBlendAdvancedEXT {
    VkBlendOp            advancedBlendOp;
    VkBool32             srcPremultiplied;
    VkBool32             dstPremultiplied;
    VkBlendOverlapEXT    blendOverlap;
    VkBool32             clampResults;
} VkColorBlendAdvancedEXT;
  • advancedBlendOp selects which blend operation is used to calculate the RGB values to write to the color attachment.

  • srcPremultiplied specifies whether the source color of the blend operation is treated as premultiplied.

  • dstPremultiplied specifies whether the destination color of the blend operation is treated as premultiplied.

  • blendOverlap is a VkBlendOverlapEXT value specifying how the source and destination sample’s coverage is correlated.

  • clampResults specifies the results must be clamped to the [0,1] range before writing to the attachment, which is useful when the attachment format is not normalized fixed-point.

Valid Usage
  • VUID-VkColorBlendAdvancedEXT-srcPremultiplied-07505
    If the non-premultiplied source color property is not supported, srcPremultiplied must be VK_TRUE

  • VUID-VkColorBlendAdvancedEXT-dstPremultiplied-07506
    If the non-premultiplied destination color property is not supported, dstPremultiplied must be VK_TRUE

  • VUID-VkColorBlendAdvancedEXT-blendOverlap-07507
    If the correlated overlap property is not supported, blendOverlap must be VK_BLEND_OVERLAP_UNCORRELATED_EXT

Valid Usage (Implicit)
  • VUID-VkColorBlendAdvancedEXT-advancedBlendOp-parameter
    advancedBlendOp must be a valid VkBlendOp value

  • VUID-VkColorBlendAdvancedEXT-blendOverlap-parameter
    blendOverlap must be a valid VkBlendOverlapEXT value

When using one of the operations in table f/X/Y/Z Advanced Blend Operations or Hue-Saturation-Luminosity Advanced Blend Operations, blending is performed according to the following equations:

where the function f and terms X, Y, and Z are specified in the table. The R, G, and B components of the source color used for blending are derived according to srcPremultiplied. If srcPremultiplied is set to VK_TRUE, the fragment color components are considered to have been premultiplied by the A component prior to blending. The base source color (Rs',Gs',Bs') is obtained by dividing through by the A component:

If srcPremultiplied is VK_FALSE, the fragment color components are used as the base color:

The R, G, and B components of the destination color used for blending are derived according to dstPremultiplied. If dstPremultiplied is set to VK_TRUE, the destination components are considered to have been premultiplied by the A component prior to blending. The base destination color (Rd',Gd',Bd') is obtained by dividing through by the A component:

If dstPremultiplied is VK_FALSE, the destination color components are used as the base color:

When blending using advanced blend operations, we expect that the R, G, and B components of premultiplied source and destination color inputs be stored as the product of non-premultiplied R, G, and B component values and the A component of the color. If any R, G, or B component of a premultiplied input color is non-zero and the A component is zero, the color is considered ill-formed, and the corresponding component of the blend result is undefined.

All of the advanced blend operation formulas in this chapter compute the result as a premultiplied color. If dstPremultiplied is VK_FALSE, that result color’s R, G, and B components are divided by the A component before being written to the framebuffer. If any R, G, or B component of the color is non-zero and the A component is zero, the result is considered ill-formed, and the corresponding component of the blend result is undefined. If all components are zero, that value is unchanged.

If the A component of any input or result color is less than zero, the color is considered ill-formed, and all components of the blend result are undefined.

The weighting functions p0, p1, and p2 are defined in table Advanced Blend Overlap Modes. In these functions, the A components of the source and destination colors are taken to indicate the portion of the pixel covered by the fragment (source) and the fragments previously accumulated in the pixel (destination). The functions p0, p1, and p2 approximate the relative portion of the pixel covered by the intersection of the source and destination, covered only by the source, and covered only by the destination, respectively.

Possible values of VkPipelineColorBlendAdvancedStateCreateInfoEXT::blendOverlap, specifying the blend overlap functions, are:

// Provided by VK_EXT_blend_operation_advanced
typedef enum VkBlendOverlapEXT {
    VK_BLEND_OVERLAP_UNCORRELATED_EXT = 0,
    VK_BLEND_OVERLAP_DISJOINT_EXT = 1,
    VK_BLEND_OVERLAP_CONJOINT_EXT = 2,
} VkBlendOverlapEXT;
  • VK_BLEND_OVERLAP_UNCORRELATED_EXT specifies that there is no correlation between the source and destination coverage.

  • VK_BLEND_OVERLAP_CONJOINT_EXT specifies that the source and destination coverage are considered to have maximal overlap.

  • VK_BLEND_OVERLAP_DISJOINT_EXT specifies that the source and destination coverage are considered to have minimal overlap.

Table 3. Advanced Blend Overlap Modes
Overlap Mode Weighting Equations

VK_BLEND_OVERLAP_UNCORRELATED_EXT

VK_BLEND_OVERLAP_CONJOINT_EXT

VK_BLEND_OVERLAP_DISJOINT_EXT

Table 4. f/X/Y/Z Advanced Blend Operations
Mode Blend Coefficients

VK_BLEND_OP_ZERO_EXT

VK_BLEND_OP_SRC_EXT

VK_BLEND_OP_DST_EXT

VK_BLEND_OP_SRC_OVER_EXT

VK_BLEND_OP_DST_OVER_EXT

VK_BLEND_OP_SRC_IN_EXT

VK_BLEND_OP_DST_IN_EXT

VK_BLEND_OP_SRC_OUT_EXT

VK_BLEND_OP_DST_OUT_EXT

VK_BLEND_OP_SRC_ATOP_EXT

VK_BLEND_OP_DST_ATOP_EXT

VK_BLEND_OP_XOR_EXT

VK_BLEND_OP_MULTIPLY_EXT

VK_BLEND_OP_SCREEN_EXT

VK_BLEND_OP_OVERLAY_EXT

VK_BLEND_OP_DARKEN_EXT

VK_BLEND_OP_LIGHTEN_EXT

VK_BLEND_OP_COLORDODGE_EXT

VK_BLEND_OP_COLORBURN_EXT

VK_BLEND_OP_HARDLIGHT_EXT

VK_BLEND_OP_SOFTLIGHT_EXT

VK_BLEND_OP_DIFFERENCE_EXT

VK_BLEND_OP_EXCLUSION_EXT

VK_BLEND_OP_INVERT_EXT

VK_BLEND_OP_INVERT_RGB_EXT

VK_BLEND_OP_LINEARDODGE_EXT

VK_BLEND_OP_LINEARBURN_EXT

VK_BLEND_OP_VIVIDLIGHT_EXT

VK_BLEND_OP_LINEARLIGHT_EXT

VK_BLEND_OP_PINLIGHT_EXT