1// Copyright 2015-2023 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.adoc[] 60 61 * pname:sType is a elink:VkStructureType value identifying this structure. 62 * pname:pNext is `NULL` or a pointer to a structure extending this 63 structure. 64ifndef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 65 * pname:flags is reserved for future use. 66endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 67ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 68 * pname:flags is a bitmask of 69 elink:VkPipelineColorBlendStateCreateFlagBits specifying additional 70 color blending information. 71endif::VK_EXT_rasterization_order_attachment_access,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 slink:VkPipelineColorBlendAttachmentState elements in 77 pname:pAttachments. 78ifdef::VK_EXT_extended_dynamic_state3[] 79 It is ignored if the pipeline is created with 80 ename:VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT, 81 ename:VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT, and 82 ename:VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT dynamic states set, and 83 either ename:VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT set or 84 <<features-advancedBlendCoherentOperations,advancedBlendCoherentOperations>> 85 is not enabled on the device. 86endif::VK_EXT_extended_dynamic_state3[] 87 * pname:pAttachments is a pointer to an array of 88 slink:VkPipelineColorBlendAttachmentState structures defining blend 89 state for each color attachment. 90ifdef::VK_EXT_extended_dynamic_state3[] 91 It is ignored if the pipeline is created with 92 ename:VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT, 93 ename:VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT, and 94 ename:VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT dynamic states set, and 95 either ename:VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT set or 96 <<features-advancedBlendCoherentOperations,advancedBlendCoherentOperations>> 97 is not enabled on the device. 98endif::VK_EXT_extended_dynamic_state3[] 99 * pname:blendConstants is a pointer to an array of four values used as the 100 R, G, B, and A components of the blend constant that are used in 101 blending, depending on the <<framebuffer-blendfactors,blend factor>>. 102 103.Valid Usage 104**** 105 * [[VUID-VkPipelineColorBlendStateCreateInfo-pAttachments-00605]] 106 If the <<features-independentBlend, pname:independentBlend>> feature is 107 not enabled, all elements of pname:pAttachments must: be identical 108 * [[VUID-VkPipelineColorBlendStateCreateInfo-logicOpEnable-00606]] 109 If the <<features-logicOp, pname:logicOp>> feature is not enabled, 110 pname:logicOpEnable must: be ename:VK_FALSE 111 * [[VUID-VkPipelineColorBlendStateCreateInfo-logicOpEnable-00607]] 112 If pname:logicOpEnable is ename:VK_TRUE, pname:logicOp must: be a valid 113 elink:VkLogicOp value 114ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 115 * [[VUID-VkPipelineColorBlendStateCreateInfo-rasterizationOrderColorAttachmentAccess-06465]] 116 If the <<features-rasterizationOrderColorAttachmentAccess, 117 pname:rasterizationOrderColorAttachmentAccess>> feature is not enabled, 118 pname:flags must: not include 119 ename:VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT 120endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 121 * [[VUID-VkPipelineColorBlendStateCreateInfo-pAttachments-07353]] 122 If pname:attachmentCount is not `0` 123ifdef::VK_EXT_extended_dynamic_state3[] 124 , and any of ename:VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT, 125 ename:VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT, 126 ename:VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT, or 127 ename:VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT are not set, 128endif::VK_EXT_extended_dynamic_state3[] 129 pname:pAttachments must: be a valid pointer to an array of 130 pname:attachmentCount valid slink:VkPipelineColorBlendAttachmentState 131 structures 132**** 133 134include::{generated}/validity/structs/VkPipelineColorBlendStateCreateInfo.adoc[] 135-- 136 137[open,refpage='VkPipelineColorBlendStateCreateFlags',desc='Bitmask of VkPipelineColorBlendStateCreateFlagBits',type='flags'] 138-- 139include::{generated}/api/flags/VkPipelineColorBlendStateCreateFlags.adoc[] 140 141ifndef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 142tname:VkPipelineColorBlendStateCreateFlags is a bitmask type for setting a 143mask, but is currently reserved for future use. 144endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 145ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 146tname:VkPipelineColorBlendStateCreateFlags is a bitmask type for setting a 147mask of zero or more elink:VkPipelineColorBlendStateCreateFlagBits. 148endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 149-- 150 151ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 152[open,refpage='VkPipelineColorBlendStateCreateFlagBits',desc='Bitmask specifying additional parameters of an image',type='enums'] 153-- 154Bits which can: be set in the 155slink:VkPipelineColorBlendStateCreateInfo::pname:flags parameter are: 156 157include::{generated}/api/enums/VkPipelineColorBlendStateCreateFlagBits.adoc[] 158 159 * ename:VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT 160 indicates that access to color and input attachments will have implicit 161 framebuffer-local memory dependencies, allowing applications to express 162 custom blending operations in a fragment shader. 163 164When 165ename:VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_EXT 166is included in a pipeline, it forms a framebuffer-local memory dependency 167for each fragment generated by draw commands for that pipeline with the 168following scopes: 169 170 * The first <<synchronization-dependencies-scopes, synchronization scope>> 171 includes the ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT 172 pipeline stage executed by all previous fragments (as defined by 173 <<drawing-primitive-order, primitive order>>) in the corresponding 174 <<synchronization-framebuffer-regions, framebuffer regions>> including 175 those generated by the same draw command. 176 * The second <<synchronization-dependencies-scopes, synchronization 177 scope>> includes the ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT 178 pipeline stage executed by the generated fragment. 179 * The first <<synchronization-dependencies-access-scopes, access scope>> 180 includes all writes to color attachments. 181 * The second <<synchronization-dependencies-access-scopes, access scope>> 182 includes all reads from input attachments. 183-- 184endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 185 186[open,refpage='VkPipelineColorBlendAttachmentState',desc='Structure specifying a pipeline color blend attachment state',type='structs'] 187-- 188The sname:VkPipelineColorBlendAttachmentState structure is defined as: 189 190include::{generated}/api/structs/VkPipelineColorBlendAttachmentState.adoc[] 191 192 * pname:blendEnable controls whether blending is enabled for the 193 corresponding color attachment. 194 If blending is not enabled, the source fragment's color for that 195 attachment is passed through unmodified. 196 * pname:srcColorBlendFactor selects which blend factor is used to 197 determine the source factors [eq]#(S~r~,S~g~,S~b~)#. 198 * pname:dstColorBlendFactor selects which blend factor is used to 199 determine the destination factors [eq]#(D~r~,D~g~,D~b~)#. 200 * pname:colorBlendOp selects which blend operation is used to calculate 201 the RGB values to write to the color attachment. 202 * pname:srcAlphaBlendFactor selects which blend factor is used to 203 determine the source factor [eq]#S~a~#. 204 * pname:dstAlphaBlendFactor selects which blend factor is used to 205 determine the destination factor [eq]#D~a~#. 206 * pname:alphaBlendOp selects which blend operation is used to calculate 207 the alpha values to write to the color attachment. 208 * pname:colorWriteMask is a bitmask of elink:VkColorComponentFlagBits 209 specifying which of the R, G, B, and/or A components are enabled for 210 writing, as described for the <<framebuffer-color-write-mask,Color Write 211 Mask>>. 212 213.Valid Usage 214**** 215 * [[VUID-VkPipelineColorBlendAttachmentState-srcColorBlendFactor-00608]] 216 If the <<features-dualSrcBlend, pname:dualSrcBlend>> feature is not 217 enabled, pname:srcColorBlendFactor must: not be 218 ename:VK_BLEND_FACTOR_SRC1_COLOR, 219 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 220 ename:VK_BLEND_FACTOR_SRC1_ALPHA, or 221 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA 222 * [[VUID-VkPipelineColorBlendAttachmentState-dstColorBlendFactor-00609]] 223 If the <<features-dualSrcBlend, pname:dualSrcBlend>> feature is not 224 enabled, pname:dstColorBlendFactor must: not be 225 ename:VK_BLEND_FACTOR_SRC1_COLOR, 226 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 227 ename:VK_BLEND_FACTOR_SRC1_ALPHA, or 228 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA 229 * [[VUID-VkPipelineColorBlendAttachmentState-srcAlphaBlendFactor-00610]] 230 If the <<features-dualSrcBlend, pname:dualSrcBlend>> feature is not 231 enabled, pname:srcAlphaBlendFactor must: not be 232 ename:VK_BLEND_FACTOR_SRC1_COLOR, 233 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 234 ename:VK_BLEND_FACTOR_SRC1_ALPHA, or 235 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA 236 * [[VUID-VkPipelineColorBlendAttachmentState-dstAlphaBlendFactor-00611]] 237 If the <<features-dualSrcBlend, pname:dualSrcBlend>> feature is not 238 enabled, pname:dstAlphaBlendFactor must: not be 239 ename:VK_BLEND_FACTOR_SRC1_COLOR, 240 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 241 ename:VK_BLEND_FACTOR_SRC1_ALPHA, or 242 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA 243ifdef::VK_EXT_blend_operation_advanced[] 244 * [[VUID-VkPipelineColorBlendAttachmentState-colorBlendOp-01406]] 245 If either of pname:colorBlendOp or pname:alphaBlendOp is an 246 <<framebuffer-blend-advanced,advanced blend operation>>, then 247 pname:colorBlendOp must: equal pname:alphaBlendOp 248 * [[VUID-VkPipelineColorBlendAttachmentState-advancedBlendIndependentBlend-01407]] 249 If 250 slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::pname:advancedBlendIndependentBlend 251 is ename:VK_FALSE and pname:colorBlendOp is an 252 <<framebuffer-blend-advanced,advanced blend operation>>, then 253 pname:colorBlendOp must: be the same for all attachments 254 * [[VUID-VkPipelineColorBlendAttachmentState-advancedBlendIndependentBlend-01408]] 255 If 256 slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::pname:advancedBlendIndependentBlend 257 is ename:VK_FALSE and pname:alphaBlendOp is an 258 <<framebuffer-blend-advanced,advanced blend operation>>, then 259 pname:alphaBlendOp must: be the same for all attachments 260 * [[VUID-VkPipelineColorBlendAttachmentState-advancedBlendAllOperations-01409]] 261 If 262 slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::pname:advancedBlendAllOperations 263 is ename:VK_FALSE, then pname:colorBlendOp must: not be 264 ename:VK_BLEND_OP_ZERO_EXT, ename:VK_BLEND_OP_SRC_EXT, 265 ename:VK_BLEND_OP_DST_EXT, ename:VK_BLEND_OP_SRC_OVER_EXT, 266 ename:VK_BLEND_OP_DST_OVER_EXT, ename:VK_BLEND_OP_SRC_IN_EXT, 267 ename:VK_BLEND_OP_DST_IN_EXT, ename:VK_BLEND_OP_SRC_OUT_EXT, 268 ename:VK_BLEND_OP_DST_OUT_EXT, ename:VK_BLEND_OP_SRC_ATOP_EXT, 269 ename:VK_BLEND_OP_DST_ATOP_EXT, ename:VK_BLEND_OP_XOR_EXT, 270 ename:VK_BLEND_OP_INVERT_EXT, ename:VK_BLEND_OP_INVERT_RGB_EXT, 271 ename:VK_BLEND_OP_LINEARDODGE_EXT, ename:VK_BLEND_OP_LINEARBURN_EXT, 272 ename:VK_BLEND_OP_VIVIDLIGHT_EXT, ename:VK_BLEND_OP_LINEARLIGHT_EXT, 273 ename:VK_BLEND_OP_PINLIGHT_EXT, ename:VK_BLEND_OP_HARDMIX_EXT, 274 ename:VK_BLEND_OP_PLUS_EXT, ename:VK_BLEND_OP_PLUS_CLAMPED_EXT, 275 ename:VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT, 276 ename:VK_BLEND_OP_PLUS_DARKER_EXT, ename:VK_BLEND_OP_MINUS_EXT, 277 ename:VK_BLEND_OP_MINUS_CLAMPED_EXT, ename:VK_BLEND_OP_CONTRAST_EXT, 278 ename:VK_BLEND_OP_INVERT_OVG_EXT, ename:VK_BLEND_OP_RED_EXT, 279 ename:VK_BLEND_OP_GREEN_EXT, or ename:VK_BLEND_OP_BLUE_EXT 280 * [[VUID-VkPipelineColorBlendAttachmentState-colorBlendOp-01410]] 281 If pname:colorBlendOp or pname:alphaBlendOp is an 282 <<framebuffer-blend-advanced,advanced blend operation>>, then 283 pname:colorAttachmentCount of the subpass this pipeline is compiled 284 against must: be less than or equal to 285 slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::pname:advancedBlendMaxColorAttachments 286endif::VK_EXT_blend_operation_advanced[] 287ifdef::VK_KHR_portability_subset[] 288 * [[VUID-VkPipelineColorBlendAttachmentState-constantAlphaColorBlendFactors-04454]] 289 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 290 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:constantAlphaColorBlendFactors 291 is ename:VK_FALSE, pname:srcColorBlendFactor must: not be 292 ename:VK_BLEND_FACTOR_CONSTANT_ALPHA or 293 ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA 294 * [[VUID-VkPipelineColorBlendAttachmentState-constantAlphaColorBlendFactors-04455]] 295 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 296 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:constantAlphaColorBlendFactors 297 is ename:VK_FALSE, pname:dstColorBlendFactor must: not be 298 ename:VK_BLEND_FACTOR_CONSTANT_ALPHA or 299 ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA 300endif::VK_KHR_portability_subset[] 301**** 302 303include::{generated}/validity/structs/VkPipelineColorBlendAttachmentState.adoc[] 304-- 305 306ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 307 308[open,refpage='vkCmdSetColorBlendEnableEXT',desc='Specify the pname:blendEnable for each attachment dynamically for a command buffer',type='protos'] 309-- 310To <<pipelines-dynamic-state, dynamically set>> pname:blendEnable, call: 311 312include::{generated}/api/protos/vkCmdSetColorBlendEnableEXT.adoc[] 313 314 * pname:commandBuffer is the command buffer into which the command will be 315 recorded. 316 * pname:firstAttachment the first color attachment the color blending 317 enable applies. 318 * pname:attachmentCount the number of color blending enables in the 319 pname:pColorBlendEnables array. 320 * pname:pColorBlendEnables an array of booleans to indicate whether color 321 blending is enabled for the corresponding attachment. 322 323This command sets the color blending enable of the specified color 324attachments for subsequent drawing commands 325ifdef::VK_EXT_shader_object[] 326ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 327ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 328endif::VK_EXT_shader_object[] 329ifdef::VK_EXT_extended_dynamic_state3[] 330when the graphics pipeline is created with 331ename:VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT set in 332slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 333endif::VK_EXT_extended_dynamic_state3[] 334Otherwise, this state is specified by the 335slink:VkPipelineColorBlendAttachmentState::pname:blendEnable values used to 336create the currently active pipeline. 337 338:refpage: vkCmdSetColorBlendEnableEXT 339:requiredfeature: extendedDynamicState3ColorBlendEnable 340 341.Valid Usage 342**** 343include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 344**** 345 346include::{generated}/validity/protos/vkCmdSetColorBlendEnableEXT.adoc[] 347-- 348 349[open,refpage='vkCmdSetColorBlendEquationEXT',desc='Specify the blend factors and operations dynamically for a command buffer',type='protos'] 350-- 351To <<pipelines-dynamic-state, dynamically set>> color blend factors and 352operations, call: 353 354include::{generated}/api/protos/vkCmdSetColorBlendEquationEXT.adoc[] 355 356 * pname:commandBuffer is the command buffer into which the command will be 357 recorded. 358 * pname:firstAttachment the first color attachment the color blend factors 359 and operations apply to. 360 * pname:attachmentCount the number of slink:VkColorBlendEquationEXT 361 elements in the pname:pColorBlendEquations array. 362 * pname:pColorBlendEquations an array of slink:VkColorBlendEquationEXT 363 structs that specify the color blend factors and operations for the 364 corresponding attachments. 365 366This command sets the color blending factors and operations of the specified 367attachments for subsequent drawing commands 368ifdef::VK_EXT_shader_object[] 369ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 370ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 371endif::VK_EXT_shader_object[] 372ifdef::VK_EXT_extended_dynamic_state3[] 373when the graphics pipeline is created with 374ename:VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT set in 375slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 376endif::VK_EXT_extended_dynamic_state3[] 377Otherwise, this state is specified by the 378slink:VkPipelineColorBlendAttachmentState::pname:srcColorBlendFactor, 379slink:VkPipelineColorBlendAttachmentState::pname:dstColorBlendFactor, 380slink:VkPipelineColorBlendAttachmentState::pname:colorBlendOp, 381slink:VkPipelineColorBlendAttachmentState::pname:srcAlphaBlendFactor, 382slink:VkPipelineColorBlendAttachmentState::pname:dstAlphaBlendFactor, and 383slink:VkPipelineColorBlendAttachmentState::pname:alphaBlendOp values used to 384create the currently active pipeline. 385 386:refpage: vkCmdSetColorBlendEquationEXT 387:requiredfeature: extendedDynamicState3ColorBlendEquation 388 389.Valid Usage 390**** 391include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 392**** 393 394include::{generated}/validity/protos/vkCmdSetColorBlendEquationEXT.adoc[] 395-- 396 397[open,refpage='VkColorBlendEquationEXT',desc='Structure specifying the color blend factors and operations for an attachment',type='structs'] 398-- 399The sname:VkColorBlendEquationEXT structure is defined as: 400 401include::{generated}/api/structs/VkColorBlendEquationEXT.adoc[] 402 403 * pname:srcColorBlendFactor selects which blend factor is used to 404 determine the source factors [eq]#(S~r~,S~g~,S~b~)#. 405 * pname:dstColorBlendFactor selects which blend factor is used to 406 determine the destination factors [eq]#(D~r~,D~g~,D~b~)#. 407 * pname:colorBlendOp selects which blend operation is used to calculate 408 the RGB values to write to the color attachment. 409 * pname:srcAlphaBlendFactor selects which blend factor is used to 410 determine the source factor [eq]#S~a~#. 411 * pname:dstAlphaBlendFactor selects which blend factor is used to 412 determine the destination factor [eq]#D~a~#. 413 * pname:alphaBlendOp selects which blend operation is use to calculate the 414 alpha values to write to the color attachment. 415 416.Valid Usage 417**** 418 * [[VUID-VkColorBlendEquationEXT-dualSrcBlend-07357]] 419 If the <<features-dualSrcBlend, pname:dualSrcBlend>> feature is not 420 enabled, pname:srcColorBlendFactor must: not be 421 ename:VK_BLEND_FACTOR_SRC1_COLOR, 422 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 423 ename:VK_BLEND_FACTOR_SRC1_ALPHA, or 424 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA 425 * [[VUID-VkColorBlendEquationEXT-dualSrcBlend-07358]] 426 If the <<features-dualSrcBlend, pname:dualSrcBlend>> feature is not 427 enabled, pname:dstColorBlendFactor must: not be 428 ename:VK_BLEND_FACTOR_SRC1_COLOR, 429 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 430 ename:VK_BLEND_FACTOR_SRC1_ALPHA, or 431 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA 432 * [[VUID-VkColorBlendEquationEXT-dualSrcBlend-07359]] 433 If the <<features-dualSrcBlend, pname:dualSrcBlend>> feature is not 434 enabled, pname:srcAlphaBlendFactor must: not be 435 ename:VK_BLEND_FACTOR_SRC1_COLOR, 436 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 437 ename:VK_BLEND_FACTOR_SRC1_ALPHA, or 438 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA 439 * [[VUID-VkColorBlendEquationEXT-dualSrcBlend-07360]] 440 If the <<features-dualSrcBlend, pname:dualSrcBlend>> feature is not 441 enabled, pname:dstAlphaBlendFactor must: not be 442 ename:VK_BLEND_FACTOR_SRC1_COLOR, 443 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 444 ename:VK_BLEND_FACTOR_SRC1_ALPHA, or 445 ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA 446ifdef::VK_EXT_blend_operation_advanced[] 447 * [[VUID-VkColorBlendEquationEXT-colorBlendOp-07361]] 448 pname:colorBlendOp and pname:alphaBlendOp must: not be 449 ename:VK_BLEND_OP_ZERO_EXT, ename:VK_BLEND_OP_SRC_EXT, 450 ename:VK_BLEND_OP_DST_EXT, ename:VK_BLEND_OP_SRC_OVER_EXT, 451 ename:VK_BLEND_OP_DST_OVER_EXT, ename:VK_BLEND_OP_SRC_IN_EXT, 452 ename:VK_BLEND_OP_DST_IN_EXT, ename:VK_BLEND_OP_SRC_OUT_EXT, 453 ename:VK_BLEND_OP_DST_OUT_EXT, ename:VK_BLEND_OP_SRC_ATOP_EXT, 454 ename:VK_BLEND_OP_DST_ATOP_EXT, ename:VK_BLEND_OP_XOR_EXT, 455 ename:VK_BLEND_OP_MULTIPLY_EXT, ename:VK_BLEND_OP_SCREEN_EXT, 456 ename:VK_BLEND_OP_OVERLAY_EXT, ename:VK_BLEND_OP_DARKEN_EXT, 457 ename:VK_BLEND_OP_LIGHTEN_EXT, ename:VK_BLEND_OP_COLORDODGE_EXT, 458 ename:VK_BLEND_OP_COLORBURN_EXT, ename:VK_BLEND_OP_HARDLIGHT_EXT, 459 ename:VK_BLEND_OP_SOFTLIGHT_EXT, ename:VK_BLEND_OP_DIFFERENCE_EXT, 460 ename:VK_BLEND_OP_EXCLUSION_EXT, ename:VK_BLEND_OP_INVERT_EXT, 461 ename:VK_BLEND_OP_INVERT_RGB_EXT, ename:VK_BLEND_OP_LINEARDODGE_EXT, 462 ename:VK_BLEND_OP_LINEARBURN_EXT, ename:VK_BLEND_OP_VIVIDLIGHT_EXT, 463 ename:VK_BLEND_OP_LINEARLIGHT_EXT, ename:VK_BLEND_OP_PINLIGHT_EXT, 464 ename:VK_BLEND_OP_HARDMIX_EXT, ename:VK_BLEND_OP_HSL_HUE_EXT, 465 ename:VK_BLEND_OP_HSL_SATURATION_EXT, ename:VK_BLEND_OP_HSL_COLOR_EXT, 466 ename:VK_BLEND_OP_HSL_LUMINOSITY_EXT, ename:VK_BLEND_OP_PLUS_EXT, 467 ename:VK_BLEND_OP_PLUS_CLAMPED_EXT, 468 ename:VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT, 469 ename:VK_BLEND_OP_PLUS_DARKER_EXT, ename:VK_BLEND_OP_MINUS_EXT, 470 ename:VK_BLEND_OP_MINUS_CLAMPED_EXT, ename:VK_BLEND_OP_CONTRAST_EXT, 471 ename:VK_BLEND_OP_INVERT_OVG_EXT, ename:VK_BLEND_OP_RED_EXT, 472 ename:VK_BLEND_OP_GREEN_EXT, or ename:VK_BLEND_OP_BLUE_EXT 473endif::VK_EXT_blend_operation_advanced[] 474ifdef::VK_KHR_portability_subset[] 475 * [[VUID-VkColorBlendEquationEXT-constantAlphaColorBlendFactors-07362]] 476 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 477 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:constantAlphaColorBlendFactors 478 is ename:VK_FALSE, pname:srcColorBlendFactor must: not be 479 ename:VK_BLEND_FACTOR_CONSTANT_ALPHA or 480 ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA 481 * [[VUID-VkColorBlendEquationEXT-constantAlphaColorBlendFactors-07363]] 482 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 483 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:constantAlphaColorBlendFactors 484 is ename:VK_FALSE, pname:dstColorBlendFactor must: not be 485 ename:VK_BLEND_FACTOR_CONSTANT_ALPHA or 486 ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA 487endif::VK_KHR_portability_subset[] 488**** 489 490include::{generated}/validity/structs/VkColorBlendEquationEXT.adoc[] 491-- 492 493[open,refpage='vkCmdSetColorWriteMaskEXT',desc='Specify the color write masks for each attachment dynamically for a command buffer',type='protos'] 494-- 495To <<pipelines-dynamic-state, dynamically set>> the color write masks, call: 496 497include::{generated}/api/protos/vkCmdSetColorWriteMaskEXT.adoc[] 498 499 * pname:commandBuffer is the command buffer into which the command will be 500 recorded. 501 * pname:firstAttachment the first color attachment the color write masks 502 apply to. 503 * pname:attachmentCount the number of tlink:VkColorComponentFlags values 504 in the pname:pColorWriteMasks array. 505 * pname:pColorWriteMasks an array of tlink:VkColorComponentFlags values 506 that specify the color write masks of the corresponding attachments. 507 508This command sets the color write masks of the specified attachments for 509subsequent drawing commands 510ifdef::VK_EXT_shader_object[] 511ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 512ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 513endif::VK_EXT_shader_object[] 514ifdef::VK_EXT_extended_dynamic_state3[] 515when the graphics pipeline is created with 516ename:VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT set in 517slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 518endif::VK_EXT_extended_dynamic_state3[] 519Otherwise, this state is specified by the 520slink:VkPipelineColorBlendAttachmentState::pname:colorWriteMask values used 521to create the currently active pipeline. 522 523[NOTE] 524.Note 525==== 526Formats with bits that are shared between components specified by 527elink:VkColorComponentFlagBits, such as 528ename:VK_FORMAT_E5B9G9R9_UFLOAT_PACK32, cannot have their channels 529individually masked by this functionality; either all components that share 530bits have to be enabled, or none of them. 531==== 532 533:refpage: vkCmdSetColorWriteMaskEXT 534:requiredfeature: extendedDynamicState3ColorWriteMask 535 536.Valid Usage 537**** 538include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 539**** 540 541include::{generated}/validity/protos/vkCmdSetColorWriteMaskEXT.adoc[] 542-- 543 544endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 545 546 547[[framebuffer-blendfactors]] 548=== Blend Factors 549 550[open,refpage='VkBlendFactor',desc='Framebuffer blending factors',type='enums'] 551-- 552The source and destination color and alpha blending factors are selected 553from the enum: 554 555include::{generated}/api/enums/VkBlendFactor.adoc[] 556 557The semantics of the enum values are described in the table below: 558 559.Blend Factors 560[width="100%",options="header",align="center",cols="59%,28%,13%"] 561|==== 562|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~#) 563|ename:VK_BLEND_FACTOR_ZERO | [eq]#(0,0,0)# | [eq]#0# 564|ename:VK_BLEND_FACTOR_ONE | [eq]#(1,1,1)# | [eq]#1# 565|ename:VK_BLEND_FACTOR_SRC_COLOR | [eq]#(R~s0~,G~s0~,B~s0~)# | [eq]#A~s0~# 566|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC_COLOR | [eq]#(1-R~s0~,1-G~s0~,1-B~s0~)# | [eq]#1-A~s0~# 567|ename:VK_BLEND_FACTOR_DST_COLOR | [eq]#(R~d~,G~d~,B~d~)# | [eq]#A~d~# 568|ename:VK_BLEND_FACTOR_ONE_MINUS_DST_COLOR | [eq]#(1-R~d~,1-G~d~,1-B~d~)# | [eq]#1-A~d~# 569|ename:VK_BLEND_FACTOR_SRC_ALPHA | [eq]#(A~s0~,A~s0~,A~s0~)# | [eq]#A~s0~# 570|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA | [eq]#(1-A~s0~,1-A~s0~,1-A~s0~)# | [eq]#1-A~s0~# 571|ename:VK_BLEND_FACTOR_DST_ALPHA | [eq]#(A~d~,A~d~,A~d~)# | [eq]#A~d~# 572|ename:VK_BLEND_FACTOR_ONE_MINUS_DST_ALPHA | [eq]#(1-A~d~,1-A~d~,1-A~d~)# | [eq]#1-A~d~# 573|ename:VK_BLEND_FACTOR_CONSTANT_COLOR | [eq]#(R~c~,G~c~,B~c~)# | [eq]#A~c~# 574|ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR | [eq]#(1-R~c~,1-G~c~,1-B~c~)# | [eq]#1-A~c~# 575|ename:VK_BLEND_FACTOR_CONSTANT_ALPHA | [eq]#(A~c~,A~c~,A~c~)# | [eq]#A~c~# 576|ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA | [eq]#(1-A~c~,1-A~c~,1-A~c~)# | [eq]#1-A~c~# 577|ename:VK_BLEND_FACTOR_SRC_ALPHA_SATURATE | [eq]#(f,f,f)#; [eq]#f = min(A~s0~,1-A~d~)# | [eq]#1# 578|ename:VK_BLEND_FACTOR_SRC1_COLOR | [eq]#(R~s1~,G~s1~,B~s1~)# | [eq]#A~s1~# 579|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR | [eq]#(1-R~s1~,1-G~s1~,1-B~s1~)# | [eq]#1-A~s1~# 580|ename:VK_BLEND_FACTOR_SRC1_ALPHA | [eq]#(A~s1~,A~s1~,A~s1~)# | [eq]#A~s1~# 581|ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA | [eq]#(1-A~s1~,1-A~s1~,1-A~s1~)# | [eq]#1-A~s1~# 582|==== 583 584In this table, the following conventions are used: 585 586 * [eq]#R~s0~,G~s0~,B~s0~# and [eq]#A~s0~# represent the first source color 587 R, G, B, and A components, respectively, for the fragment output 588 location corresponding to the color attachment being blended. 589 * [eq]#R~s1~,G~s1~,B~s1~# and [eq]#A~s1~# represent the second source 590 color R, G, B, and A components, respectively, used in dual source 591 blending modes, for the fragment output location corresponding to the 592 color attachment being blended. 593 * [eq]#R~d~,G~d~,B~d~# and [eq]#A~d~# represent the R, G, B, and A 594 components of the destination color. 595 That is, the color currently in the corresponding color attachment for 596 this fragment/sample. 597 * [eq]#R~c~,G~c~,B~c~# and [eq]#A~c~# represent the blend constant R, G, 598 B, and A components, respectively. 599-- 600 601[open,refpage='vkCmdSetBlendConstants',desc='Set the values of blend constants',type='protos'] 602-- 603To <<pipelines-dynamic-state, dynamically set and change>> the blend 604constants, call: 605 606include::{generated}/api/protos/vkCmdSetBlendConstants.adoc[] 607 608 * pname:commandBuffer is the command buffer into which the command will be 609 recorded. 610 * pname:blendConstants is a pointer to an array of four values specifying 611 the [eq]#R~c~#, [eq]#G~c~#, [eq]#B~c~#, and [eq]#A~c~# components of the 612 blend constant color used in blending, depending on the 613 <<framebuffer-blendfactors,blend factor>>. 614 615[[framebuffer-blendconstants]] 616This command sets blend constants for subsequent drawing commands when 617ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 618the graphics pipeline is created with ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS 619set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 620Otherwise, this state is specified by the 621slink:VkPipelineColorBlendStateCreateInfo::pname:blendConstants values used 622to create the currently active pipeline. 623 624include::{generated}/validity/protos/vkCmdSetBlendConstants.adoc[] 625-- 626 627 628[[framebuffer-dsb]] 629=== Dual-Source Blending 630 631Blend factors that use the secondary color input 632[eq]#(R~s1~,G~s1~,B~s1~,A~s1~)# (ename:VK_BLEND_FACTOR_SRC1_COLOR, 633ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, 634ename:VK_BLEND_FACTOR_SRC1_ALPHA, and 635ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA) may: consume implementation 636resources that could otherwise be used for rendering to multiple color 637attachments. 638Therefore, the number of color attachments that can: be used in a 639framebuffer may: be lower when using dual-source blending. 640 641Dual-source blending is only supported if the <<features-dualSrcBlend, 642pname:dualSrcBlend>> feature is enabled. 643 644The maximum number of color attachments that can: be used in a subpass when 645using dual-source blending functions is implementation-dependent and is 646reported as the pname:maxFragmentDualSrcAttachments member of 647sname:VkPhysicalDeviceLimits. 648 649Color outputs can: be bound to the first and second inputs of the blender 650using the code:Index decoration, as described in 651<<interfaces-fragmentoutput,Fragment Output Interface>>. 652If the second color input to the blender is not written in the shader, or if 653no output is bound to the second input of a blender, the value of the second 654input is undefined:. 655 656 657[[framebuffer-blendoperations]] 658=== Blend Operations 659 660[open,refpage='VkBlendOp',desc='Framebuffer blending operations',type='enums'] 661-- 662Once the source and destination blend factors have been selected, they along 663with the source and destination components are passed to the blending 664operations. 665RGB and alpha components can: use different operations. 666Possible values of elink:VkBlendOp, specifying the operations, are: 667 668include::{generated}/api/enums/VkBlendOp.adoc[] 669 670<<< 671 672The semantics of the basic blend operations are described in the table 673below: 674 675.Basic Blend Operations 676[width="100%",cols="45%,30%,25%",options="header",align="center"] 677|==== 678|elink:VkBlendOp | RGB Components | Alpha Component 679 680|ename:VK_BLEND_OP_ADD 681| [eq]#R = R~s0~ {times} S~r~ {plus} R~d~ {times} D~r~# + 682 [eq]#G = G~s0~ {times} S~g~ {plus} G~d~ {times} D~g~# + 683 [eq]#B = B~s0~ {times} S~b~ {plus} B~d~ {times} D~b~# 684| [eq]#A = A~s0~ {times} S~a~ {plus} A~d~ {times} D~a~# 685 686|ename:VK_BLEND_OP_SUBTRACT 687| [eq]#R = R~s0~ {times} S~r~ - R~d~ {times} D~r~# + 688 [eq]#G = G~s0~ {times} S~g~ - G~d~ {times} D~g~# + 689 [eq]#B = B~s0~ {times} S~b~ - B~d~ {times} D~b~# 690| [eq]#A = A~s0~ {times} S~a~ - A~d~ {times} D~a~# 691 692|ename:VK_BLEND_OP_REVERSE_SUBTRACT 693| [eq]#R = R~d~ {times} D~r~ - R~s0~ {times} S~r~# + 694 [eq]#G = G~d~ {times} D~g~ - G~s0~ {times} S~g~# + 695 [eq]#B = B~d~ {times} D~b~ - B~s0~ {times} S~b~# 696| [eq]#A = A~d~ {times} D~a~ - A~s0~ {times} S~a~# 697 698|ename:VK_BLEND_OP_MIN 699| [eq]#R = min(R~s0~,R~d~)# + 700 [eq]#G = min(G~s0~,G~d~)# + 701 [eq]#B = min(B~s0~,B~d~)# 702| [eq]#A = min(A~s0~,A~d~)# 703 704|ename:VK_BLEND_OP_MAX 705| [eq]#R = max(R~s0~,R~d~)# + 706 [eq]#G = max(G~s0~,G~d~)# + 707 [eq]#B = max(B~s0~,B~d~)# 708| [eq]#A = max(A~s0~,A~d~)# 709|==== 710 711In this table, the following conventions are used: 712 713 * [eq]#R~s0~, G~s0~, B~s0~# and [eq]#A~s0~# represent the first source 714 color R, G, B, and A components, respectively. 715 * [eq]#R~d~, G~d~, B~d~# and [eq]#A~d~# represent the R, G, B, and A 716 components of the destination color. 717 That is, the color currently in the corresponding color attachment for 718 this fragment/sample. 719 * [eq]#S~r~, S~g~, S~b~# and [eq]#S~a~# represent the source blend factor 720 R, G, B, and A components, respectively. 721 * [eq]#D~r~, D~g~, D~b~# and [eq]#D~a~# represent the destination blend 722 factor R, G, B, and A components, respectively. 723 724The blending operation produces a new set of values [eq]#R, G, B# and 725[eq]#A#, which are written to the framebuffer attachment. 726If blending is not enabled for this attachment, then [eq]#R, G, B# and 727[eq]#A# are assigned [eq]#R~s0~, G~s0~, B~s0~# and [eq]#A~s0~#, 728respectively. 729 730If the color attachment is fixed-point, the components of the source and 731destination values and blend factors are each clamped to [eq]#[0,1]# or 732[eq]#[-1,1]# respectively for an unsigned normalized or signed normalized 733color attachment prior to evaluating the blend operations. 734If the color attachment is floating-point, no clamping occurs. 735-- 736 737If the <<formats-numericformat, numeric format>> of a framebuffer attachment 738uses sRGB encoding, the R, G, and B destination color values (after 739conversion from fixed-point to floating-point) are considered to be encoded 740for the sRGB color space and hence are linearized prior to their use in 741blending. 742Each R, G, and B component is converted from nonlinear to linear as 743described in the "`sRGB EOTF`" section of the <<data-format,Khronos Data 744Format Specification>>. 745If the format is not sRGB, no linearization is performed. 746 747If the <<formats-numericformat, numeric format>> of a framebuffer attachment 748uses sRGB encoding, then the final R, G and B values are converted into the 749nonlinear sRGB representation before being written to the framebuffer 750attachment as described in the "`sRGB EOTF^ -1^`" section of the 751Khronos Data Format Specification. 752 753If the <<formats-numericformat, numeric format>> of a framebuffer color 754attachment is not sRGB encoded then the resulting [eq]#c~s~# values for R, G 755and B are unmodified. 756The value of A is never sRGB encoded. 757That is, the alpha component is always stored in memory as linear. 758 759If the framebuffer color attachment is ename:VK_ATTACHMENT_UNUSED, no writes 760are performed through that attachment. 761Writes are not performed to framebuffer color attachments greater than or 762equal to the sname:VkSubpassDescription::pname:colorAttachmentCount 763ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 764or sname:VkSubpassDescription2::pname:colorAttachmentCount 765endif::VK_VERSION_1_2,VK_KHR_create_renderpass2[] 766value. 767 768ifdef::VK_EXT_blend_operation_advanced[] 769include::{chapters}/VK_EXT_blend_operation_advanced/advanced_blend.adoc[] 770endif::VK_EXT_blend_operation_advanced[] 771 772 773[[framebuffer-logicop]] 774== Logical Operations 775 776The application can: enable a _logical operation_ between the fragment's 777color values and the existing value in the framebuffer attachment. 778This logical operation is applied prior to updating the framebuffer 779attachment. 780Logical operations are applied only for signed and unsigned integer and 781normalized integer framebuffers. 782Logical operations are not applied to floating-point or sRGB format color 783attachments. 784 785[open,refpage='VkLogicOp',desc='Framebuffer logical operations',type='enums'] 786-- 787Logical operations are controlled by the pname:logicOpEnable and 788pname:logicOp members of slink:VkPipelineColorBlendStateCreateInfo. 789ifdef::VK_EXT_extended_dynamic_state3[] 790The pname:logicOpEnable state can also be controlled by 791flink:vkCmdSetLogicOpEnableEXT if graphics pipeline is created with 792ename:VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT set in 793slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 794endif::VK_EXT_extended_dynamic_state3[] 795ifdef::VK_EXT_extended_dynamic_state2[] 796The pname:logicOp state can also be controlled by flink:vkCmdSetLogicOpEXT 797if graphics pipeline is created with ename:VK_DYNAMIC_STATE_LOGIC_OP_EXT set 798in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 799endif::VK_EXT_extended_dynamic_state2[] 800If pname:logicOpEnable is ename:VK_TRUE, then a logical operation selected 801by pname:logicOp is applied between each color attachment and the fragment's 802corresponding output value, and blending of all attachments is treated as if 803it were disabled. 804Any attachments using color formats for which logical operations are not 805supported simply pass through the color values unmodified. 806The logical operation is applied independently for each of the red, green, 807blue, and alpha components. 808The pname:logicOp is selected from the following operations: 809 810include::{generated}/api/enums/VkLogicOp.adoc[] 811 812<<< 813 814The logical operations supported by Vulkan are summarized in the following 815table in which 816 817 * [eq]#{lnot}# is bitwise invert, 818 * [eq]#{land}# is bitwise and, 819 * [eq]#{lor}# is bitwise or, 820 * [eq]#{oplus}# is bitwise exclusive or, 821 * [eq]#s# is the fragment's [eq]#R~s0~, G~s0~, B~s0~# or [eq]#A~s0~# 822 component value for the fragment output corresponding to the color 823 attachment being updated, and 824 * [eq]#d# is the color attachment's [eq]#R, G, B# or [eq]#A# component 825 value: 826 827.Logical Operations 828[width="75%",options="header",align="center"] 829|==== 830|Mode | Operation 831|ename:VK_LOGIC_OP_CLEAR | [eq]#0# 832|ename:VK_LOGIC_OP_AND | [eq]#s {land} d# 833|ename:VK_LOGIC_OP_AND_REVERSE | [eq]#s {land} {lnot} d# 834|ename:VK_LOGIC_OP_COPY | [eq]#s# 835|ename:VK_LOGIC_OP_AND_INVERTED | [eq]#{lnot} s {land} d# 836|ename:VK_LOGIC_OP_NO_OP | [eq]#d# 837|ename:VK_LOGIC_OP_XOR | [eq]#s {oplus} d# 838|ename:VK_LOGIC_OP_OR | [eq]#s {lor} d# 839|ename:VK_LOGIC_OP_NOR | [eq]#{lnot} (s {lor} d)# 840|ename:VK_LOGIC_OP_EQUIVALENT | [eq]#{lnot} (s {oplus} d)# 841|ename:VK_LOGIC_OP_INVERT | [eq]#{lnot} d# 842|ename:VK_LOGIC_OP_OR_REVERSE | [eq]#s {lor} {lnot} d# 843|ename:VK_LOGIC_OP_COPY_INVERTED | [eq]#{lnot} s# 844|ename:VK_LOGIC_OP_OR_INVERTED | [eq]#{lnot} s {lor} d# 845|ename:VK_LOGIC_OP_NAND | [eq]#{lnot} (s {land} d)# 846|ename:VK_LOGIC_OP_SET | all 1s 847|==== 848 849The result of the logical operation is then written to the color attachment 850as controlled by the component write mask, described in 851<<framebuffer-blendoperations,Blend Operations>>. 852-- 853 854ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 855[open,refpage='vkCmdSetLogicOpEnableEXT',desc='Specify dynamically whether logical operations are enabled for a command buffer',type='protos'] 856-- 857To <<pipelines-dynamic-state, dynamically set>> whether logical operations 858are enabled, call: 859 860include::{generated}/api/protos/vkCmdSetLogicOpEnableEXT.adoc[] 861 862 * pname:commandBuffer is the command buffer into which the command will be 863 recorded. 864 * pname:logicOpEnable specifies whether logical operations are enabled. 865 866This command sets whether logical operations are enabled for subsequent 867drawing commands 868ifdef::VK_EXT_shader_object[] 869ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 870ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 871endif::VK_EXT_shader_object[] 872ifdef::VK_EXT_extended_dynamic_state3[] 873when the graphics pipeline is created with 874ename:VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT set in 875slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 876endif::VK_EXT_extended_dynamic_state3[] 877Otherwise, this state is specified by the 878slink:VkPipelineColorBlendStateCreateInfo::pname:logicOpEnable value used to 879create the currently active pipeline. 880 881:refpage: vkCmdSetLogicOpEnableEXT 882:requiredfeature: extendedDynamicState3LogicOpEnable 883 884.Valid Usage 885**** 886include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 887**** 888 889include::{generated}/validity/protos/vkCmdSetLogicOpEnableEXT.adoc[] 890-- 891endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 892 893ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] 894[open,refpage='vkCmdSetLogicOpEXT',desc='Select which logical operation to apply for blend state dynamically for a command buffer',type='protos'] 895-- 896To <<pipelines-dynamic-state, dynamically set>> the logical operation to 897apply for blend state, call: 898 899include::{generated}/api/protos/vkCmdSetLogicOpEXT.adoc[] 900 901 * pname:commandBuffer is the command buffer into which the command will be 902 recorded. 903 * pname:logicOp specifies the logical operation to apply for blend state. 904 905This command sets the logical operation for blend state for subsequent 906drawing commands 907ifdef::VK_EXT_shader_object[] 908ifdef::VK_EXT_extended_dynamic_state2[when drawing using <<shaders-objects, shader objects>>, or] 909ifndef::VK_EXT_extended_dynamic_state2[when drawing using <<shaders-objects, shader objects>>.] 910endif::VK_EXT_shader_object[] 911ifdef::VK_EXT_extended_dynamic_state2[] 912when the graphics pipeline is created with 913ename:VK_DYNAMIC_STATE_LOGIC_OP_EXT set in 914slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 915endif::VK_EXT_extended_dynamic_state2[] 916Otherwise, this state is specified by the 917slink:VkPipelineColorBlendStateCreateInfo::pname:logicOp value used to 918create the currently active pipeline. 919 920:refpage: vkCmdSetLogicOpEXT 921:requiredfeature: extendedDynamicState2LogicOp 922 923.Valid Usage 924**** 925include::{chapters}/commonvalidity/dynamic_state2_optional_feature_common.adoc[] 926**** 927 928include::{generated}/validity/protos/vkCmdSetLogicOpEXT.adoc[] 929-- 930endif::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] 931 932 933[[framebuffer-color-write-mask]] 934== Color Write Mask 935 936[open,refpage='VkColorComponentFlagBits',desc='Bitmask controlling which components are written to the framebuffer',type='enums'] 937-- 938Bits which can: be set in 939slink:VkPipelineColorBlendAttachmentState::pname:colorWriteMask, determining 940whether the final color values [eq]#R, G, B# and [eq]#A# are written to the 941framebuffer attachment, are: 942 943include::{generated}/api/enums/VkColorComponentFlagBits.adoc[] 944 945 * ename:VK_COLOR_COMPONENT_R_BIT specifies that the [eq]#R# value is 946 written to the color attachment for the appropriate sample. 947 Otherwise, the value in memory is unmodified. 948 * ename:VK_COLOR_COMPONENT_G_BIT specifies that the [eq]#G# value is 949 written to the color attachment for the appropriate sample. 950 Otherwise, the value in memory is unmodified. 951 * ename:VK_COLOR_COMPONENT_B_BIT specifies that the [eq]#B# value is 952 written to the color attachment for the appropriate sample. 953 Otherwise, the value in memory is unmodified. 954 * ename:VK_COLOR_COMPONENT_A_BIT specifies that the [eq]#A# value is 955 written to the color attachment for the appropriate sample. 956 Otherwise, the value in memory is unmodified. 957 958The color write mask operation is applied regardless of whether blending is 959enabled. 960 961ifdef::VK_EXT_color_write_enable[] 962The color write mask operation is applied only if 963<<framebuffer-color-write-enable,Color Write Enable>> is enabled for the 964respective attachment. 965Otherwise the color write mask is ignored and writes to all components of 966the attachment are disabled. 967endif::VK_EXT_color_write_enable[] 968-- 969 970[open,refpage='VkColorComponentFlags',desc='Bitmask of VkColorComponentFlagBits',type='flags'] 971-- 972include::{generated}/api/flags/VkColorComponentFlags.adoc[] 973 974tname:VkColorComponentFlags is a bitmask type for setting a mask of zero or 975more elink:VkColorComponentFlagBits. 976-- 977 978 979ifdef::VK_EXT_color_write_enable[] 980[[framebuffer-color-write-enable]] 981== Color Write Enable 982 983[open,refpage='VkPipelineColorWriteCreateInfoEXT',desc='Structure specifying color write state of a newly created pipeline',type='structs'] 984-- 985The sname:VkPipelineColorWriteCreateInfoEXT structure is defined as: 986 987include::{generated}/api/structs/VkPipelineColorWriteCreateInfoEXT.adoc[] 988 989 * pname:sType is a elink:VkStructureType value identifying this structure. 990 * pname:pNext is `NULL` or a pointer to a structure extending this 991 structure. 992 * pname:attachmentCount is the number of basetype:VkBool32 elements in 993 pname:pColorWriteEnables. 994 * pname:pColorWriteEnables is a pointer to an array of per target 995 attachment boolean values specifying whether color writes are enabled 996 for the given attachment. 997 998When this structure is included in the pname:pNext chain of 999slink:VkPipelineColorBlendStateCreateInfo, it defines per-attachment color 1000write state. 1001If this structure is not included in the pname:pNext chain, it is equivalent 1002to specifying this structure with pname:attachmentCount equal to the 1003pname:attachmentCount member of slink:VkPipelineColorBlendStateCreateInfo, 1004and pname:pColorWriteEnables pointing to an array of as many ename:VK_TRUE 1005values. 1006 1007If the <<features-colorWriteEnable, pname:colorWriteEnable>> feature is not 1008enabled on the device, all basetype:VkBool32 elements in the 1009pname:pColorWriteEnables array must: be ename:VK_TRUE. 1010 1011Color Write Enable interacts with the <<framebuffer-color-write-mask,Color 1012Write Mask>> as follows: 1013 1014 * If pname:colorWriteEnable is ename:VK_TRUE, writes to the attachment are 1015 determined by the pname:colorWriteMask. 1016 * If pname:colorWriteEnable is ename:VK_FALSE, the pname:colorWriteMask is 1017 ignored and writes to all components of the attachment are disabled. 1018 This is equivalent to specifying a pname:colorWriteMask of 0. 1019 1020.Valid Usage 1021**** 1022 * [[VUID-VkPipelineColorWriteCreateInfoEXT-pAttachments-04801]] 1023 If the <<features-colorWriteEnable, pname:colorWriteEnable>> feature is 1024 not enabled, all elements of pname:pColorWriteEnables must: be 1025 ename:VK_TRUE 1026 * [[VUID-VkPipelineColorWriteCreateInfoEXT-attachmentCount-07608]] 1027ifdef::VK_EXT_extended_dynamic_state3[] 1028 If the pipeline is being created with 1029 ename:VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT, 1030 ename:VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT, 1031 ename:VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT, or 1032 ename:VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT dynamic states not set, 1033endif::VK_EXT_extended_dynamic_state3[] 1034 pname:attachmentCount must: be equal to the pname:attachmentCount member 1035 of the sname:VkPipelineColorBlendStateCreateInfo structure specified 1036 during pipeline creation 1037 * [[VUID-VkPipelineColorWriteCreateInfoEXT-attachmentCount-06655]] 1038 pname:attachmentCount must: be less than or equal to the 1039 pname:maxColorAttachments member of sname:VkPhysicalDeviceLimits 1040**** 1041 1042include::{generated}/validity/structs/VkPipelineColorWriteCreateInfoEXT.adoc[] 1043-- 1044 1045[open,refpage='vkCmdSetColorWriteEnableEXT',desc='Enable or disable writes to a color attachment dynamically for a command buffer',type='protos'] 1046-- 1047To <<pipelines-dynamic-state, dynamically enable or disable>> writes to a 1048color attachment, call: 1049 1050include::{generated}/api/protos/vkCmdSetColorWriteEnableEXT.adoc[] 1051 1052 * pname:commandBuffer is the command buffer into which the command will be 1053 recorded. 1054 * pname:attachmentCount is the number of basetype:VkBool32 elements in 1055 pname:pColorWriteEnables. 1056 * pname:pColorWriteEnables is a pointer to an array of per target 1057 attachment boolean values specifying whether color writes are enabled 1058 for the given attachment. 1059 1060This command sets the color write enables for subsequent drawing commands 1061ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 1062when the graphics pipeline is created with 1063ename:VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT set in 1064slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1065Otherwise, this state is specified by the 1066slink:VkPipelineColorWriteCreateInfoEXT::pname:pColorWriteEnables values 1067used to create the currently active pipeline. 1068 1069.Valid Usage 1070**** 1071 * [[VUID-vkCmdSetColorWriteEnableEXT-None-04803]] 1072 The <<features-colorWriteEnable, pname:colorWriteEnable>> feature must: 1073 be enabled 1074 * [[VUID-vkCmdSetColorWriteEnableEXT-attachmentCount-06656]] 1075 pname:attachmentCount must: be less than or equal to the 1076 pname:maxColorAttachments member of sname:VkPhysicalDeviceLimits 1077**** 1078 1079include::{generated}/validity/protos/vkCmdSetColorWriteEnableEXT.adoc[] 1080-- 1081endif::VK_EXT_color_write_enable[] 1082 1083 1084ifdef::VK_QCOM_tile_properties[] 1085[[framebuffer-queries]] 1086== Framebuffer Query Instructions 1087 1088[open,refpage='vkGetFramebufferTilePropertiesQCOM',desc='Get tile properties from the attachments in framebuffer',type='protos'] 1089-- 1090To query the tile properties from the attachments in framebuffer, call: 1091 1092include::{generated}/api/protos/vkGetFramebufferTilePropertiesQCOM.adoc[] 1093 1094 * pname:device is a logical device associated with the framebuffer. 1095 * pname:framebuffer is a handle of the framebuffer to query. 1096 * pname:pPropertiesCount is a pointer to an integer related to the number 1097 of tile properties available or queried, as described below. 1098 * pname:pProperties is either `NULL` or a pointer to an array of 1099 slink:VkTilePropertiesQCOM structures. 1100 1101If pname:pProperties is `NULL`, then the number of tile properties available 1102is returned in pname:pPropertiesCount. 1103Otherwise, pname:pPropertiesCount must: point to a variable set by the user 1104to the number of elements in the pname:pProperties array, and on return the 1105variable is overwritten with the number of properties actually written to 1106pname:pProperties. 1107If pname:pPropertiesCount is less than the number of tile properties 1108available, at most pname:pPropertiesCount structures will be written, and 1109ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to 1110indicate that not all the available properties were returned. 1111 1112The number of tile properties available is determined by the number of 1113merged subpasses, and each tile property is associated with a merged 1114subpass. 1115There will be at most as many properties as there are subpasses within the 1116render pass. 1117To obtain the tile properties for a given merged subpass, the `pProperties` 1118array can be indexed using the `postMergeIndex` value provided in 1119slink:VkRenderPassSubpassFeedbackInfoEXT. 1120 1121include::{generated}/validity/protos/vkGetFramebufferTilePropertiesQCOM.adoc[] 1122-- 1123endif::VK_QCOM_tile_properties[] 1124