1// Copyright 2015-2021 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[framebuffer]] 6= The Framebuffer 7 8 9[[framebuffer-blending]] 10== Blending 11 12Blending combines the incoming _source_ fragment's R, G, B, and A values 13with the _destination_ R, G, B, and A values of each sample stored in the 14framebuffer at the fragment's [eq]#(x~f~,y~f~)# location. 15Blending is performed for each color sample covered by the fragment, rather 16than just once for each fragment. 17 18Source and destination values are combined according to the 19<<framebuffer-blendoperations,blend operation>>, quadruplets of source and 20destination weighting factors determined by the <<framebuffer-blendfactors, 21blend factors>>, and a <<framebuffer-blendconstants,blend constant>>, to 22obtain a new set of R, G, B, and A values, as described below. 23 24Blending is computed and applied separately to each color attachment used by 25the subpass, with separate controls for each attachment. 26 27Prior to performing the blend operation, signed and unsigned normalized 28fixed-point color components undergo an implied conversion to floating-point 29as specified by <<fundamentals-fixedfpconv,Conversion from Normalized 30Fixed-Point to Floating-Point>>. 31Blending computations are treated as if carried out in floating-point, and 32basic blend operations are performed with a precision and dynamic range no 33lower than that used to represent destination components. 34ifdef::VK_EXT_blend_operation_advanced[] 35<<framebuffer-blend-advanced,Advanced blending operations>> are performed 36with a precision and dynamic range no lower than the smaller of that used to 37represent destination components or that used to represent 16-bit 38floating-point values. 39endif::VK_EXT_blend_operation_advanced[] 40 41[NOTE] 42.Note 43==== 44Blending is only defined for floating-point, UNORM, SNORM, and sRGB formats. 45Within those formats, the implementation may only support blending on some 46subset of them. 47Which formats support blending is indicated by 48ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT. 49==== 50 51The pipeline blend state is included in the 52sname:VkPipelineColorBlendStateCreateInfo structure during graphics pipeline 53creation: 54 55[open,refpage='VkPipelineColorBlendStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline color blend state',type='structs'] 56-- 57The sname:VkPipelineColorBlendStateCreateInfo structure is defined as: 58 59include::{generated}/api/structs/VkPipelineColorBlendStateCreateInfo.txt[] 60 61 * pname:sType is the type of this structure. 62 * pname:pNext is `NULL` or a pointer to a structure extending this 63 structure. 64ifndef::VK_ARM_rasterization_order_attachment_access[] 65 * pname:flags is reserved for future use. 66endif::VK_ARM_rasterization_order_attachment_access[] 67ifdef::VK_ARM_rasterization_order_attachment_access[] 68 * pname:flags is a bitmask of 69 elink:VkPipelineColorBlendStateCreateFlagBits specifying additional 70 color blending information. 71endif::VK_ARM_rasterization_order_attachment_access[] 72 * pname:logicOpEnable controls whether to apply <<framebuffer-logicop, 73 Logical Operations>>. 74 * pname:logicOp selects which logical operation to apply. 75 * pname:attachmentCount is the number of 76 sname:VkPipelineColorBlendAttachmentState elements in 77 pname:pAttachments. 78 * pname:pAttachments is a pointer to an array of per target attachment 79 states. 80 * pname:blendConstants is a pointer to an array of four values used as the 81 R, G, B, and A components of the blend constant that are used in 82 blending, depending on the <<framebuffer-blendfactors,blend factor>>. 83 84Each element of the pname:pAttachments array is a 85slink:VkPipelineColorBlendAttachmentState structure specifying per-target 86blending state for each individual color attachment. 87If the <<features-independentBlend,independent blending>> feature is not 88enabled on the device, all slink:VkPipelineColorBlendAttachmentState 89elements in the pname:pAttachments array must: be identical. 90 91The value of pname:attachmentCount must: be greater than the index of all 92color attachments that are not ename:VK_ATTACHMENT_UNUSED in 93sname:VkSubpassDescription::pname:pColorAttachments 94ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 95or sname:VkSubpassDescription2::pname:pColorAttachments 96endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 97for the subpass in which this pipeline is used. 98 99.Valid Usage 100**** 101 * [[VUID-VkPipelineColorBlendStateCreateInfo-pAttachments-00605]] 102 If the <<features-independentBlend,independent blending>> feature is not 103 enabled, all elements of pname:pAttachments must: be identical 104 * [[VUID-VkPipelineColorBlendStateCreateInfo-logicOpEnable-00606]] 105 If the <<features-logicOp,logic operations>> feature is not enabled, 106 pname:logicOpEnable must: be ename:VK_FALSE 107 * [[VUID-VkPipelineColorBlendStateCreateInfo-logicOpEnable-00607]] 108 If pname:logicOpEnable is ename:VK_TRUE, pname:logicOp must: be a valid 109 elink:VkLogicOp value 110ifdef::VK_ARM_rasterization_order_attachment_access[] 111 * [[VUID-VkPipelineColorBlendStateCreateInfo-rasterizationOrderColorAttachmentAccess-06465]] 112 If the <<features-rasterizationOrderColorAttachmentAccess, 113 pname:rasterizationOrderColorAttachmentAccess>> feature is not enabled, 114 pname:flags must: not include 115 ename:VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARM 116endif::VK_ARM_rasterization_order_attachment_access[] 117**** 118 119include::{generated}/validity/structs/VkPipelineColorBlendStateCreateInfo.txt[] 120-- 121 122[open,refpage='VkPipelineColorBlendStateCreateFlags',desc='Bitmask of VkPipelineColorBlendStateCreateFlagBits',type='flags'] 123-- 124include::{generated}/api/flags/VkPipelineColorBlendStateCreateFlags.txt[] 125 126ifndef::VK_ARM_rasterization_order_attachment_access[] 127tname:VkPipelineColorBlendStateCreateFlags is a bitmask type for setting a 128mask, but is currently reserved for future use. 129endif::VK_ARM_rasterization_order_attachment_access[] 130ifdef::VK_ARM_rasterization_order_attachment_access[] 131tname:VkPipelineColorBlendStateCreateFlags is a bitmask type for setting a 132mask of zero or more elink:VkPipelineColorBlendStateCreateFlagBits. 133endif::VK_ARM_rasterization_order_attachment_access[] 134-- 135 136ifdef::VK_ARM_rasterization_order_attachment_access[] 137[open,refpage='VkPipelineColorBlendStateCreateFlagBits',desc='Bitmask specifying additional parameters of an image',type='enums'] 138-- 139Bits which can: be set in the 140slink:VkPipelineColorBlendStateCreateInfo::pname:flags parameter are: 141 142include::{generated}/api/enums/VkPipelineColorBlendStateCreateFlagBits.txt[] 143 144 * ename:VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARM 145 indicates that access to color and input attachments will have implicit 146 framebuffer-local memory dependencies, allowing applications to express 147 custom blending operations in a fragment shader. 148 See <<renderpass-feedbackloop, renderpass feedback loops>> for more 149 information. 150-- 151endif::VK_ARM_rasterization_order_attachment_access[] 152 153[open,refpage='VkPipelineColorBlendAttachmentState',desc='Structure specifying a pipeline color blend attachment state',type='structs'] 154-- 155The sname:VkPipelineColorBlendAttachmentState structure is defined as: 156 157include::{generated}/api/structs/VkPipelineColorBlendAttachmentState.txt[] 158 159 * pname:blendEnable controls whether blending is enabled for the 160 corresponding color attachment. 161 If blending is not enabled, the source fragment's color for that 162 attachment is passed through unmodified. 163 * pname:srcColorBlendFactor selects which blend factor is used to 164 determine the source factors [eq]#(S~r~,S~g~,S~b~)#. 165 * pname:dstColorBlendFactor selects which blend factor is used to 166 determine the destination factors [eq]#(D~r~,D~g~,D~b~)#. 167 * pname:colorBlendOp selects which blend operation is used to calculate 168 the RGB values to write to the color attachment. 169 * pname:srcAlphaBlendFactor selects which blend factor is used to 170 determine the source factor [eq]#S~a~#. 171 * pname:dstAlphaBlendFactor selects which blend factor is used to 172 determine the destination factor [eq]#D~a~#. 173 * pname:alphaBlendOp selects which blend operation is use to calculate the 174 alpha values to write to the color attachment. 175 * pname:colorWriteMask is a bitmask of elink:VkColorComponentFlagBits 176 specifying which of the R, G, B, and/or A components are enabled for 177 writing, as described for the <<framebuffer-color-write-mask,Color Write 178 Mask>>. 179 180.Valid Usage 181**** 182 * [[VUID-VkPipelineColorBlendAttachmentState-srcColorBlendFactor-00608]] 183 If the <<features-dualSrcBlend,dual source blending>> feature is not 184 enabled, pname:srcColorBlendFactor must: not be 185 ename:VK_BLEND_FACTOR_SRC1_COLOR, 186 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 187 ename:VK_BLEND_FACTOR_SRC1_ALPHA, or 188 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA 189 * [[VUID-VkPipelineColorBlendAttachmentState-dstColorBlendFactor-00609]] 190 If the <<features-dualSrcBlend,dual source blending>> feature is not 191 enabled, pname:dstColorBlendFactor must: not be 192 ename:VK_BLEND_FACTOR_SRC1_COLOR, 193 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 194 ename:VK_BLEND_FACTOR_SRC1_ALPHA, or 195 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA 196 * [[VUID-VkPipelineColorBlendAttachmentState-srcAlphaBlendFactor-00610]] 197 If the <<features-dualSrcBlend,dual source blending>> feature is not 198 enabled, pname:srcAlphaBlendFactor must: not be 199 ename:VK_BLEND_FACTOR_SRC1_COLOR, 200 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 201 ename:VK_BLEND_FACTOR_SRC1_ALPHA, or 202 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA 203 * [[VUID-VkPipelineColorBlendAttachmentState-dstAlphaBlendFactor-00611]] 204 If the <<features-dualSrcBlend,dual source blending>> feature is not 205 enabled, pname:dstAlphaBlendFactor must: not be 206 ename:VK_BLEND_FACTOR_SRC1_COLOR, 207 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 208 ename:VK_BLEND_FACTOR_SRC1_ALPHA, or 209 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA 210ifdef::VK_EXT_blend_operation_advanced[] 211 * [[VUID-VkPipelineColorBlendAttachmentState-colorBlendOp-01406]] 212 If either of pname:colorBlendOp or pname:alphaBlendOp is an 213 <<framebuffer-blend-advanced,advanced blend operation>>, then 214 pname:colorBlendOp must: equal pname:alphaBlendOp 215 * [[VUID-VkPipelineColorBlendAttachmentState-advancedBlendIndependentBlend-01407]] 216 If 217 slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::pname:advancedBlendIndependentBlend 218 is ename:VK_FALSE and pname:colorBlendOp is an 219 <<framebuffer-blend-advanced,advanced blend operation>>, then 220 pname:colorBlendOp must: be the same for all attachments 221 * [[VUID-VkPipelineColorBlendAttachmentState-advancedBlendIndependentBlend-01408]] 222 If 223 slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::pname:advancedBlendIndependentBlend 224 is ename:VK_FALSE and pname:alphaBlendOp is an 225 <<framebuffer-blend-advanced,advanced blend operation>>, then 226 pname:alphaBlendOp must: be the same for all attachments 227 * [[VUID-VkPipelineColorBlendAttachmentState-advancedBlendAllOperations-01409]] 228 If 229 slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::pname:advancedBlendAllOperations 230 is ename:VK_FALSE, then pname:colorBlendOp must: not be 231 ename:VK_BLEND_OP_ZERO_EXT, ename:VK_BLEND_OP_SRC_EXT, 232 ename:VK_BLEND_OP_DST_EXT, ename:VK_BLEND_OP_SRC_OVER_EXT, 233 ename:VK_BLEND_OP_DST_OVER_EXT, ename:VK_BLEND_OP_SRC_IN_EXT, 234 ename:VK_BLEND_OP_DST_IN_EXT, ename:VK_BLEND_OP_SRC_OUT_EXT, 235 ename:VK_BLEND_OP_DST_OUT_EXT, ename:VK_BLEND_OP_SRC_ATOP_EXT, 236 ename:VK_BLEND_OP_DST_ATOP_EXT, ename:VK_BLEND_OP_XOR_EXT, 237 ename:VK_BLEND_OP_INVERT_EXT, ename:VK_BLEND_OP_INVERT_RGB_EXT, 238 ename:VK_BLEND_OP_LINEARDODGE_EXT, ename:VK_BLEND_OP_LINEARBURN_EXT, 239 ename:VK_BLEND_OP_VIVIDLIGHT_EXT, ename:VK_BLEND_OP_LINEARLIGHT_EXT, 240 ename:VK_BLEND_OP_PINLIGHT_EXT, ename:VK_BLEND_OP_HARDMIX_EXT, 241 ename:VK_BLEND_OP_PLUS_EXT, ename:VK_BLEND_OP_PLUS_CLAMPED_EXT, 242 ename:VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT, 243 ename:VK_BLEND_OP_PLUS_DARKER_EXT, ename:VK_BLEND_OP_MINUS_EXT, 244 ename:VK_BLEND_OP_MINUS_CLAMPED_EXT, ename:VK_BLEND_OP_CONTRAST_EXT, 245 ename:VK_BLEND_OP_INVERT_OVG_EXT, ename:VK_BLEND_OP_RED_EXT, 246 ename:VK_BLEND_OP_GREEN_EXT, or ename:VK_BLEND_OP_BLUE_EXT 247 * [[VUID-VkPipelineColorBlendAttachmentState-colorBlendOp-01410]] 248 If pname:colorBlendOp or pname:alphaBlendOp is an 249 <<framebuffer-blend-advanced,advanced blend operation>>, then 250 pname:colorAttachmentCount of the subpass this pipeline is compiled 251 against must: be less than or equal to 252 slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::pname:advancedBlendMaxColorAttachments 253endif::VK_EXT_blend_operation_advanced[] 254ifdef::VK_KHR_portability_subset[] 255 * [[VUID-VkPipelineColorBlendAttachmentState-constantAlphaColorBlendFactors-04454]] 256 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 257 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:constantAlphaColorBlendFactors 258 is ename:VK_FALSE, pname:srcColorBlendFactor must: not be 259 ename:VK_BLEND_FACTOR_CONSTANT_ALPHA or 260 ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA 261 * [[VUID-VkPipelineColorBlendAttachmentState-constantAlphaColorBlendFactors-04455]] 262 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 263 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:constantAlphaColorBlendFactors 264 is ename:VK_FALSE, pname:dstColorBlendFactor must: not be 265 ename:VK_BLEND_FACTOR_CONSTANT_ALPHA or 266 ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA 267endif::VK_KHR_portability_subset[] 268**** 269 270include::{generated}/validity/structs/VkPipelineColorBlendAttachmentState.txt[] 271-- 272 273 274[[framebuffer-blendfactors]] 275=== Blend Factors 276 277[open,refpage='VkBlendFactor',desc='Framebuffer blending factors',type='enums'] 278-- 279The source and destination color and alpha blending factors are selected 280from the enum: 281 282include::{generated}/api/enums/VkBlendFactor.txt[] 283 284The semantics of the enum values are described in the table below: 285 286.Blend Factors 287[width="100%",options="header",align="center",cols="59%,28%,13%"] 288|==== 289|elink:VkBlendFactor | RGB Blend Factors [eq]#(S~r~,S~g~,S~b~)# or [eq]#(D~r~,D~g~,D~b~)# | Alpha Blend Factor ([eq]#S~a~# or [eq]#D~a~#) 290|ename:VK_BLEND_FACTOR_ZERO | [eq]#(0,0,0)# | [eq]#0# 291|ename:VK_BLEND_FACTOR_ONE | [eq]#(1,1,1)# | [eq]#1# 292|ename:VK_BLEND_FACTOR_SRC_COLOR | [eq]#(R~s0~,G~s0~,B~s0~)# | [eq]#A~s0~# 293|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC_COLOR | [eq]#(1-R~s0~,1-G~s0~,1-B~s0~)# | [eq]#1-A~s0~# 294|ename:VK_BLEND_FACTOR_DST_COLOR | [eq]#(R~d~,G~d~,B~d~)# | [eq]#A~d~# 295|ename:VK_BLEND_FACTOR_ONE_MINUS_DST_COLOR | [eq]#(1-R~d~,1-G~d~,1-B~d~)# | [eq]#1-A~d~# 296|ename:VK_BLEND_FACTOR_SRC_ALPHA | [eq]#(A~s0~,A~s0~,A~s0~)# | [eq]#A~s0~# 297|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA | [eq]#(1-A~s0~,1-A~s0~,1-A~s0~)# | [eq]#1-A~s0~# 298|ename:VK_BLEND_FACTOR_DST_ALPHA | [eq]#(A~d~,A~d~,A~d~)# | [eq]#A~d~# 299|ename:VK_BLEND_FACTOR_ONE_MINUS_DST_ALPHA | [eq]#(1-A~d~,1-A~d~,1-A~d~)# | [eq]#1-A~d~# 300|ename:VK_BLEND_FACTOR_CONSTANT_COLOR | [eq]#(R~c~,G~c~,B~c~)# | [eq]#A~c~# 301|ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR | [eq]#(1-R~c~,1-G~c~,1-B~c~)# | [eq]#1-A~c~# 302|ename:VK_BLEND_FACTOR_CONSTANT_ALPHA | [eq]#(A~c~,A~c~,A~c~)# | [eq]#A~c~# 303|ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA | [eq]#(1-A~c~,1-A~c~,1-A~c~)# | [eq]#1-A~c~# 304|ename:VK_BLEND_FACTOR_SRC_ALPHA_SATURATE | [eq]#(f,f,f)#; [eq]#f = min(A~s0~,1-A~d~)# | [eq]#1# 305|ename:VK_BLEND_FACTOR_SRC1_COLOR | [eq]#(R~s1~,G~s1~,B~s1~)# | [eq]#A~s1~# 306|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR | [eq]#(1-R~s1~,1-G~s1~,1-B~s1~)# | [eq]#1-A~s1~# 307|ename:VK_BLEND_FACTOR_SRC1_ALPHA | [eq]#(A~s1~,A~s1~,A~s1~)# | [eq]#A~s1~# 308|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA | [eq]#(1-A~s1~,1-A~s1~,1-A~s1~)# | [eq]#1-A~s1~# 309|==== 310 311In this table, the following conventions are used: 312 313 * [eq]#R~s0~,G~s0~,B~s0~# and [eq]#A~s0~# represent the first source color 314 R, G, B, and A components, respectively, for the fragment output 315 location corresponding to the color attachment being blended. 316 * [eq]#R~s1~,G~s1~,B~s1~# and [eq]#A~s1~# represent the second source 317 color R, G, B, and A components, respectively, used in dual source 318 blending modes, for the fragment output location corresponding to the 319 color attachment being blended. 320 * [eq]#R~d~,G~d~,B~d~# and [eq]#A~d~# represent the R, G, B, and A 321 components of the destination color. 322 That is, the color currently in the corresponding color attachment for 323 this fragment/sample. 324 * [eq]#R~c~,G~c~,B~c~# and [eq]#A~c~# represent the blend constant R, G, 325 B, and A components, respectively. 326-- 327 328[open,refpage='vkCmdSetBlendConstants',desc='Set the values of blend constants',type='protos'] 329-- 330To <<pipelines-dynamic-state, dynamically set and change>> the blend 331constants, call: 332 333include::{generated}/api/protos/vkCmdSetBlendConstants.txt[] 334 335 * pname:commandBuffer is the command buffer into which the command will be 336 recorded. 337 * pname:blendConstants is a pointer to an array of four values specifying 338 the [eq]#R~c~#, [eq]#G~c~#, [eq]#B~c~#, and [eq]#A~c~# components of the 339 blend constant color used in blending, depending on the 340 <<framebuffer-blendfactors,blend factor>>. 341 342[[framebuffer-blendconstants]] 343This command sets blend constants for subsequent drawing commands when the 344graphics pipeline is created with ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS set 345in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 346Otherwise, this state is specified by the 347slink:VkPipelineColorBlendStateCreateInfo::pname:blendConstants values used 348to create the currently active pipeline. 349 350include::{generated}/validity/protos/vkCmdSetBlendConstants.txt[] 351-- 352 353 354[[framebuffer-dsb]] 355=== Dual-Source Blending 356 357Blend factors that use the secondary color input 358[eq]#(R~s1~,G~s1~,B~s1~,A~s1~)# (ename:VK_BLEND_FACTOR_SRC1_COLOR, 359ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 360ename:VK_BLEND_FACTOR_SRC1_ALPHA, and 361ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA) may: consume implementation 362resources that could otherwise be used for rendering to multiple color 363attachments. 364Therefore, the number of color attachments that can: be used in a 365framebuffer may: be lower when using dual-source blending. 366 367Dual-source blending is only supported if the 368<<features-dualSrcBlend,pname:dualSrcBlend>> feature is enabled. 369 370The maximum number of color attachments that can: be used in a subpass when 371using dual-source blending functions is implementation-dependent and is 372reported as the pname:maxFragmentDualSrcAttachments member of 373sname:VkPhysicalDeviceLimits. 374 375When using a fragment shader with dual-source blending functions, the color 376outputs are bound to the first and second inputs of the blender using the 377code:Index decoration, as described in <<interfaces-fragmentoutput,Fragment 378Output Interface>>. 379If the second color input to the blender is not written in the shader, or if 380no output is bound to the second input of a blender, the result of the 381blending operation is not defined. 382 383 384[[framebuffer-blendoperations]] 385=== Blend Operations 386 387[open,refpage='VkBlendOp',desc='Framebuffer blending operations',type='enums'] 388-- 389Once the source and destination blend factors have been selected, they along 390with the source and destination components are passed to the blending 391operations. 392RGB and alpha components can: use different operations. 393Possible values of elink:VkBlendOp, specifying the operations, are: 394 395include::{generated}/api/enums/VkBlendOp.txt[] 396 397<<< 398 399The semantics of the basic blend operations are described in the table 400below: 401 402.Basic Blend Operations 403[width="100%",cols="45%,30%,25%",options="header",align="center"] 404|==== 405|elink:VkBlendOp | RGB Components | Alpha Component 406 407|ename:VK_BLEND_OP_ADD 408| [eq]#R = R~s0~ {times} S~r~ {plus} R~d~ {times} D~r~# + 409 [eq]#G = G~s0~ {times} S~g~ {plus} G~d~ {times} D~g~# + 410 [eq]#B = B~s0~ {times} S~b~ {plus} B~d~ {times} D~b~# 411| [eq]#A = A~s0~ {times} S~a~ {plus} A~d~ {times} D~a~# 412 413|ename:VK_BLEND_OP_SUBTRACT 414| [eq]#R = R~s0~ {times} S~r~ - R~d~ {times} D~r~# + 415 [eq]#G = G~s0~ {times} S~g~ - G~d~ {times} D~g~# + 416 [eq]#B = B~s0~ {times} S~b~ - B~d~ {times} D~b~# 417| [eq]#A = A~s0~ {times} S~a~ - A~d~ {times} D~a~# 418 419|ename:VK_BLEND_OP_REVERSE_SUBTRACT 420| [eq]#R = R~d~ {times} D~r~ - R~s0~ {times} S~r~# + 421 [eq]#G = G~d~ {times} D~g~ - G~s0~ {times} S~g~# + 422 [eq]#B = B~d~ {times} D~b~ - B~s0~ {times} S~b~# 423| [eq]#A = A~d~ {times} D~a~ - A~s0~ {times} S~a~# 424 425|ename:VK_BLEND_OP_MIN 426| [eq]#R = min(R~s0~,R~d~)# + 427 [eq]#G = min(G~s0~,G~d~)# + 428 [eq]#B = min(B~s0~,B~d~)# 429| [eq]#A = min(A~s0~,A~d~)# 430 431|ename:VK_BLEND_OP_MAX 432| [eq]#R = max(R~s0~,R~d~)# + 433 [eq]#G = max(G~s0~,G~d~)# + 434 [eq]#B = max(B~s0~,B~d~)# 435| [eq]#A = max(A~s0~,A~d~)# 436|==== 437 438In this table, the following conventions are used: 439 440 * [eq]#R~s0~, G~s0~, B~s0~# and [eq]#A~s0~# represent the first source 441 color R, G, B, and A components, respectively. 442 * [eq]#R~d~, G~d~, B~d~# and [eq]#A~d~# represent the R, G, B, and A 443 components of the destination color. 444 That is, the color currently in the corresponding color attachment for 445 this fragment/sample. 446 * [eq]#S~r~, S~g~, S~b~# and [eq]#S~a~# represent the source blend factor 447 R, G, B, and A components, respectively. 448 * [eq]#D~r~, D~g~, D~b~# and [eq]#D~a~# represent the destination blend 449 factor R, G, B, and A components, respectively. 450 451The blending operation produces a new set of values [eq]#R, G, B# and 452[eq]#A#, which are written to the framebuffer attachment. 453If blending is not enabled for this attachment, then [eq]#R, G, B# and 454[eq]#A# are assigned [eq]#R~s0~, G~s0~, B~s0~# and [eq]#A~s0~#, 455respectively. 456 457If the color attachment is fixed-point, the components of the source and 458destination values and blend factors are each clamped to [eq]#[0,1]# or 459[eq]#[-1,1]# respectively for an unsigned normalized or signed normalized 460color attachment prior to evaluating the blend operations. 461If the color attachment is floating-point, no clamping occurs. 462-- 463 464If the numeric format of a framebuffer attachment uses sRGB encoding, the R, 465G, and B destination color values (after conversion from fixed-point to 466floating-point) are considered to be encoded for the sRGB color space and 467hence are linearized prior to their use in blending. 468Each R, G, and B component is converted from nonlinear to linear as 469described in the "`sRGB EOTF`" section of the <<data-format,Khronos Data 470Format Specification>>. 471If the format is not sRGB, no linearization is performed. 472 473If the numeric format of a framebuffer attachment uses sRGB encoding, then 474the final R, G and B values are converted into the nonlinear sRGB 475representation before being written to the framebuffer attachment as 476described in the "`sRGB EOTF^ -1^`" section of the Khronos Data Format 477Specification. 478 479If the numeric format of a framebuffer color attachment is not sRGB encoded 480then the resulting [eq]#c~s~# values for R, G and B are unmodified. 481The value of A is never sRGB encoded. 482That is, the alpha component is always stored in memory as linear. 483 484If the framebuffer color attachment is ename:VK_ATTACHMENT_UNUSED, no writes 485are performed through that attachment. 486Writes are not performed to framebuffer color attachments greater than or 487equal to the sname:VkSubpassDescription::pname:colorAttachmentCount 488ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 489or sname:VkSubpassDescription2::pname:colorAttachmentCount 490endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 491value. 492 493ifdef::VK_EXT_blend_operation_advanced[] 494include::{chapters}/VK_EXT_blend_operation_advanced/advanced_blend.txt[] 495endif::VK_EXT_blend_operation_advanced[] 496 497 498[[framebuffer-logicop]] 499== Logical Operations 500 501The application can: enable a _logical operation_ between the fragment's 502color values and the existing value in the framebuffer attachment. 503This logical operation is applied prior to updating the framebuffer 504attachment. 505Logical operations are applied only for signed and unsigned integer and 506normalized integer framebuffers. 507Logical operations are not applied to floating-point or sRGB format color 508attachments. 509 510[open,refpage='VkLogicOp',desc='Framebuffer logical operations',type='enums'] 511-- 512Logical operations are controlled by the pname:logicOpEnable and 513pname:logicOp members of slink:VkPipelineColorBlendStateCreateInfo. 514ifdef::VK_EXT_extended_dynamic_state2[] 515It can also be controlled by flink:vkCmdSetLogicOpEXT if graphics pipeline 516is created with ename:VK_DYNAMIC_STATE_LOGIC_OP_EXT set in 517slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 518endif::VK_EXT_extended_dynamic_state2[] 519If pname:logicOpEnable is ename:VK_TRUE, then a logical operation selected 520by pname:logicOp is applied between each color attachment and the fragment's 521corresponding output value, and blending of all attachments is treated as if 522it were disabled. 523Any attachments using color formats for which logical operations are not 524supported simply pass through the color values unmodified. 525The logical operation is applied independently for each of the red, green, 526blue, and alpha components. 527The pname:logicOp is selected from the following operations: 528 529include::{generated}/api/enums/VkLogicOp.txt[] 530 531<<< 532 533The logical operations supported by Vulkan are summarized in the following 534table in which 535 536 * [eq]#{lnot}# is bitwise invert, 537 * [eq]#{land}# is bitwise and, 538 * [eq]#{lor}# is bitwise or, 539 * [eq]#{oplus}# is bitwise exclusive or, 540 * [eq]#s# is the fragment's [eq]#R~s0~, G~s0~, B~s0~# or [eq]#A~s0~# 541 component value for the fragment output corresponding to the color 542 attachment being updated, and 543 * [eq]#d# is the color attachment's [eq]#R, G, B# or [eq]#A# component 544 value: 545 546.Logical Operations 547[width="75%",options="header",align="center"] 548|==== 549|Mode | Operation 550|ename:VK_LOGIC_OP_CLEAR | [eq]#0# 551|ename:VK_LOGIC_OP_AND | [eq]#s {land} d# 552|ename:VK_LOGIC_OP_AND_REVERSE | [eq]#s {land} {lnot} d# 553|ename:VK_LOGIC_OP_COPY | [eq]#s# 554|ename:VK_LOGIC_OP_AND_INVERTED | [eq]#{lnot} s {land} d# 555|ename:VK_LOGIC_OP_NO_OP | [eq]#d# 556|ename:VK_LOGIC_OP_XOR | [eq]#s {oplus} d# 557|ename:VK_LOGIC_OP_OR | [eq]#s {lor} d# 558|ename:VK_LOGIC_OP_NOR | [eq]#{lnot} (s {lor} d)# 559|ename:VK_LOGIC_OP_EQUIVALENT | [eq]#{lnot} (s {oplus} d)# 560|ename:VK_LOGIC_OP_INVERT | [eq]#{lnot} d# 561|ename:VK_LOGIC_OP_OR_REVERSE | [eq]#s {lor} {lnot} d# 562|ename:VK_LOGIC_OP_COPY_INVERTED | [eq]#{lnot} s# 563|ename:VK_LOGIC_OP_OR_INVERTED | [eq]#{lnot} s {lor} d# 564|ename:VK_LOGIC_OP_NAND | [eq]#{lnot} (s {land} d)# 565|ename:VK_LOGIC_OP_SET | all 1s 566|==== 567 568The result of the logical operation is then written to the color attachment 569as controlled by the component write mask, described in 570<<framebuffer-blendoperations,Blend Operations>>. 571-- 572 573ifdef::VK_EXT_extended_dynamic_state2[] 574[open,refpage='vkCmdSetLogicOpEXT',desc='Select which logical operation to apply for blend state dynamically for a command buffer',type='protos'] 575-- 576To <<pipelines-dynamic-state, dynamically set>> the logical operation to 577apply for blend state, call: 578 579include::{generated}/api/protos/vkCmdSetLogicOpEXT.txt[] 580 581 * pname:commandBuffer is the command buffer into which the command will be 582 recorded. 583 * pname:logicOp specifies the logical operation to apply for blend state. 584 585This command sets the logical operation for blend state for subsequent 586drawing commands when the graphics pipeline is created with 587ename:VK_DYNAMIC_STATE_LOGIC_OP_EXT set in 588slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 589Otherwise, this state is specified by the 590slink:VkPipelineColorBlendStateCreateInfo::pname:logicOp value used to 591create the currently active pipeline. 592 593.Valid Usage 594**** 595 * [[VUID-vkCmdSetLogicOpEXT-None-04867]] 596 The <<features-extendedDynamicState2LogicOp, 597 extendedDynamicState2LogicOp>> feature must: be enabled 598**** 599 600include::{generated}/validity/protos/vkCmdSetLogicOpEXT.txt[] 601-- 602endif::VK_EXT_extended_dynamic_state2[] 603 604 605[[framebuffer-color-write-mask]] 606== Color Write Mask 607 608[open,refpage='VkColorComponentFlagBits',desc='Bitmask controlling which components are written to the framebuffer',type='enums'] 609-- 610Bits which can: be set in 611slink:VkPipelineColorBlendAttachmentState::pname:colorWriteMask to determine 612whether the final color values [eq]#R, G, B# and [eq]#A# are written to the 613framebuffer attachment are: 614 615include::{generated}/api/enums/VkColorComponentFlagBits.txt[] 616 617 * ename:VK_COLOR_COMPONENT_R_BIT specifies that the [eq]#R# value is 618 written to the color attachment for the appropriate sample. 619 Otherwise, the value in memory is unmodified. 620 * ename:VK_COLOR_COMPONENT_G_BIT specifies that the [eq]#G# value is 621 written to the color attachment for the appropriate sample. 622 Otherwise, the value in memory is unmodified. 623 * ename:VK_COLOR_COMPONENT_B_BIT specifies that the [eq]#B# value is 624 written to the color attachment for the appropriate sample. 625 Otherwise, the value in memory is unmodified. 626 * ename:VK_COLOR_COMPONENT_A_BIT specifies that the [eq]#A# value is 627 written to the color attachment for the appropriate sample. 628 Otherwise, the value in memory is unmodified. 629 630The color write mask operation is applied regardless of whether blending is 631enabled. 632 633ifdef::VK_EXT_color_write_enable[] 634The color write mask operation is applied only if 635<<framebuffer-color-write-enable,Color Write Enable>> is enabled for the 636respective attachment. 637Otherwise the color write mask is ignored and writes to all components of 638the attachment are disabled. 639endif::VK_EXT_color_write_enable[] 640-- 641 642[open,refpage='VkColorComponentFlags',desc='Bitmask of VkColorComponentFlagBits',type='flags'] 643-- 644include::{generated}/api/flags/VkColorComponentFlags.txt[] 645 646tname:VkColorComponentFlags is a bitmask type for setting a mask of zero or 647more elink:VkColorComponentFlagBits. 648-- 649 650 651ifdef::VK_EXT_color_write_enable[] 652[[framebuffer-color-write-enable]] 653== Color Write Enable 654 655[open,refpage='VkPipelineColorWriteCreateInfoEXT',desc='Structure specifying color write state of a newly created pipeline',type='structs'] 656-- 657The sname:VkPipelineColorWriteCreateInfoEXT structure is defined as: 658 659include::{generated}/api/structs/VkPipelineColorWriteCreateInfoEXT.txt[] 660 661 * pname:sType is the type of this structure. 662 * pname:pNext is `NULL` or a pointer to a structure extending this 663 structure. 664 * pname:attachmentCount is the number of basetype:VkBool32 elements in 665 pname:pColorWriteEnables. 666 * pname:pColorWriteEnables is a pointer to an array of per target 667 attachment boolean values specifying whether color writes are enabled 668 for the given attachment. 669 670When this structure is included in the pname:pNext chain of 671slink:VkPipelineColorBlendStateCreateInfo, it defines per-attachment color 672write state. 673If this structure is not included in the pname:pNext chain, it is equivalent 674to specifying this structure with pname:attachmentCount equal to the 675pname:attachmentCount member of slink:VkPipelineColorBlendStateCreateInfo, 676and pname:pColorWriteEnables pointing to an array of as many ename:VK_TRUE 677values. 678 679If the <<features-colorWriteEnable,colorWriteEnable>> feature is not enabled 680on the device, all basetype:VkBool32 elements in the 681pname:pColorWriteEnables array must: be ename:VK_TRUE. 682 683Color Write Enable interacts with the <<framebuffer-color-write-mask,Color 684Write Mask>> as follows: 685 686 * If pname:colorWriteEnable is ename:VK_TRUE, writes to the attachment are 687 determined by the pname:colorWriteMask. 688 * If pname:colorWriteEnable is ename:VK_FALSE, the pname:colorWriteMask is 689 ignored and writes to all components of the attachment are disabled. 690 This is equivalent to specifying a pname:colorWriteMask of 0. 691 692.Valid Usage 693**** 694 * [[VUID-VkPipelineColorWriteCreateInfoEXT-pAttachments-04801]] 695 If the <<features-colorWriteEnable,colorWriteEnable>> feature is not 696 enabled, all elements of pname:pColorWriteEnables must: be ename:VK_TRUE 697 * [[VUID-VkPipelineColorWriteCreateInfoEXT-attachmentCount-04802]] 698 pname:attachmentCount must: be equal to the pname:attachmentCount member 699 of the sname:VkPipelineColorBlendStateCreateInfo structure specified 700 during pipeline creation 701**** 702 703include::{generated}/validity/structs/VkPipelineColorWriteCreateInfoEXT.txt[] 704-- 705 706[open,refpage='vkCmdSetColorWriteEnableEXT',desc='Enable or disable writes to a color attachment dynamically for a command buffer',type='protos'] 707-- 708To <<pipelines-dynamic-state, dynamically enable or disable>> writes to a 709color attachment, call: 710 711include::{generated}/api/protos/vkCmdSetColorWriteEnableEXT.txt[] 712 713 * pname:commandBuffer is the command buffer into which the command will be 714 recorded. 715 * pname:attachmentCount is the number of basetype:VkBool32 elements in 716 pname:pColorWriteEnables. 717 * pname:pColorWriteEnables is a pointer to an array of per target 718 attachment boolean values specifying whether color writes are enabled 719 for the given attachment. 720 721This command sets the color write enables for subsequent drawing commands 722when the graphics pipeline is created with 723ename:VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT set in 724slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 725Otherwise, this state is specified by the 726slink:VkPipelineColorWriteCreateInfoEXT::pname:pColorWriteEnables values 727used to create the currently active pipeline. 728 729.Valid Usage 730**** 731 * [[VUID-vkCmdSetColorWriteEnableEXT-None-04803]] 732 The <<features-colorWriteEnable, colorWriteEnable>> feature must: be 733 enabled 734 * [[VUID-vkCmdSetColorWriteEnableEXT-attachmentCount-04804]] 735 pname:attachmentCount must: be equal to the pname:attachmentCount member 736 of the sname:VkPipelineColorBlendStateCreateInfo structure specified 737 during pipeline creation 738**** 739 740include::{generated}/validity/protos/vkCmdSetColorWriteEnableEXT.txt[] 741-- 742endif::VK_EXT_color_write_enable[] 743