1// Copyright 2015-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[fragops]] 6= Fragment Operations 7 8Fragments produced by rasterization go through a number of operations to 9determine whether or how values produced by fragment shading are written to 10the framebuffer. 11 12The following fragment operations adhere to <<primsrast-order,rasterization 13order>>, and are typically performed in this order: 14 15ifdef::VK_EXT_discard_rectangles[] 16 . <<fragops-discard-rectangles,Discard rectangles test>> 17endif::VK_EXT_discard_rectangles[] 18 . <<fragops-scissor,Scissor test>> 19ifdef::VK_NV_scissor_exclusive[] 20 . <<fragops-exclusive-scissor,Exclusive scissor test>> 21endif::VK_NV_scissor_exclusive[] 22 . <<fragops-samplemask,Sample mask test>> 23 . Certain <<fragops-shader,Fragment shading>> operations: 24 ** <<fragops-shader-samplemask, Sample Mask Accesses>> 25ifdef::VK_EXT_shader_tile_image[] 26 ** <<fragops-shader-tileimage-reads, Tile Image Reads>> 27endif::VK_EXT_shader_tile_image[] 28 ** <<fragops-shader-depthreplacement, Depth Replacement>> 29ifdef::VK_EXT_shader_stencil_export[] 30 ** <<fragops-shader-stencilrefreplacement, Stencil Reference Replacement>> 31endif::VK_EXT_shader_stencil_export[] 32ifdef::VK_EXT_fragment_shader_interlock[] 33 ** <<fragops-shader-interlock, Interlocked Operations>> 34endif::VK_EXT_fragment_shader_interlock[] 35 . <<fragops-covg, Multisample coverage>> 36 . <<fragops-dbt, Depth bounds test>> 37 . <<fragops-stencil, Stencil test>> 38 . <<fragops-depth, Depth test>> 39ifdef::VK_NV_representative_fragment_test[] 40 . <<fragops-rep-frag-test, Representative fragment test>> 41endif::VK_NV_representative_fragment_test[] 42 . <<fragops-samplecount, Sample counting>> 43ifdef::VK_NV_fragment_coverage_to_color[] 44 . <<fragops-coverage-to-color, Coverage to color>> 45endif::VK_NV_fragment_coverage_to_color[] 46 . <<fragops-coverage-reduction, Coverage reduction>> 47ifdef::VK_NV_framebuffer_mixed_samples[] 48 . <<fragops-coverage-modulation, Coverage modulation>> 49endif::VK_NV_framebuffer_mixed_samples[] 50 51The <<primsrast-multisampling-coverage-mask, coverage mask>> generated by 52rasterization describes the initial coverage of each sample covered by the 53fragment. 54Fragment operations will update the coverage mask to add or subtract 55coverage where appropriate. 56If a fragment operation results in all bits of the coverage mask being `0`, 57the fragment is discarded, and no further operations are performed. 58Fragments can also be programmatically discarded in a fragment shader by 59executing one of 60 61ifdef::VK_VERSION_1_3,VK_KHR_shader_terminate_invocation[] 62 * code:OpTerminateInvocation 63endif::VK_VERSION_1_3,VK_KHR_shader_terminate_invocation[] 64ifdef::VK_VERSION_1_3,VK_EXT_shader_demote_to_helper_invocation[] 65 * code:OpDemoteToHelperInvocationEXT 66endif::VK_VERSION_1_3,VK_EXT_shader_demote_to_helper_invocation[] 67 * code:OpKill. 68 69When one of the fragment operations in this chapter is described as 70"`replacing`" a fragment shader output, that output is replaced 71unconditionally, even if no fragment shader previously wrote to that output. 72 73ifdef::VK_EXT_post_depth_coverage[] 74If there is a <<fragops-shader, fragment shader>> and it declares the 75code:PostDepthCoverage execution mode, the <<fragops-samplemask, sample mask 76test>> is instead performed after the <<fragops-depth, depth test>>. 77endif::VK_EXT_post_depth_coverage[] 78 79ifdef::VK_KHR_maintenance5[] 80If 81sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:earlyFragmentMultisampleCoverageAfterSampleCounting 82is set to ename:VK_TRUE and there is a <<fragops-shader, fragment shader>> 83which declares the code:EarlyFragmentTests execution mode, <<fragops-shader, 84fragment shading>> and <<fragops-covg, multisample coverage>> operations 85must: be performed after <<fragops-samplecount, sample counting>>. 86 87Otherwise, if 88sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:earlyFragmentMultisampleCoverageAfterSampleCounting 89is set to ename:VK_FALSE and there is a <<fragops-shader, fragment shader>> 90which declares the code:EarlyFragmentTests execution mode, <<fragops-shader, 91fragment shading>> and <<fragops-covg, multisample coverage>> operations 92should: instead be performed after <<fragops-samplecount, sample counting>>, 93but may: be performed before <<fragops-samplecount, sample counting>>. 94 95If 96sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:earlyFragmentSampleMaskTestBeforeSampleCounting 97is set to ename:VK_TRUE and there is a <<fragops-shader, fragment shader>> 98which declares the code:EarlyFragmentTests execution mode 99<<fragops-samplemask, sample mask test>> operations must: follow the order 100of fragment operations from above. 101 102Otherwise, if 103sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:earlyFragmentSampleMaskTestBeforeSampleCounting 104is set to ename:VK_FALSE and there is a <<fragops-shader, fragment shader>> 105which declares the code:EarlyFragmentTests execution mode, 106<<fragops-samplemask, sample mask test>> operations should: follow the order 107of fragment operations from above but may: instead be performed after 108<<fragops-samplecount, sample counting>>. 109endif::VK_KHR_maintenance5[] 110ifndef::VK_KHR_maintenance5[] 111If there is a <<fragops-shader, fragment shader>> and it declares the 112code:EarlyFragmentTests execution mode, <<fragops-shader,fragment shading>> 113and <<fragops-covg, multisample coverage>> operations should: instead be 114performed after <<fragops-samplecount, sample counting>>, and 115<<fragops-samplemask,sample mask test>> may: instead be performed after 116<<fragops-samplecount, sample counting>>. 117endif::VK_KHR_maintenance5[] 118 119ifdef::VK_AMD_shader_early_and_late_fragment_tests[] 120If there is a <<fragops-shader, fragment shader>> which declares the 121code:EarlyAndLateFragmentTestsAMD execution mode, and it does not declare 122the code:DepthReplacing 123ifdef::VK_EXT_shader_stencil_export[] 124or code:StencilRefReplacingEXT 125endif::VK_EXT_shader_stencil_export[] 126execution mode, <<fragops-shader,fragment shading>> and <<fragops-covg, 127multisample coverage>> operations are instead be performed after 128<<fragops-samplecount, sample counting>>. 129 130ifdef::VK_EXT_shader_stencil_export[] 131For a pipeline with the following properties: 132 133 * a fragment shader is specified 134 * the fragment shader either specifies code:EarlyAndLateFragmentTestsAMD 135 or does not write to storage resources; 136 * the fragment shader specifies the code:StencilRefReplacingEXT execution 137 mode; 138 * either 139 ** the fragment shader specifies the code:StencilRefUnchangedFrontAMD 140 execution mode; 141 ** the fragment shader specifies the code:StencilRefLessFrontAMD execution 142 mode and the pipeline uses a 143 slink:VkPipelineDepthStencilStateCreateInfo::pname:front.compareOp of 144 ename:VK_COMPARE_OP_GREATER or ename:VK_COMPARE_OP_GREATER_OR_EQUAL; or 145 ** the fragment shader specifies the code:StencilRefGreaterFrontAMD 146 execution mode and the pipeline uses a 147 slink:VkPipelineDepthStencilStateCreateInfo::pname:front.compareOp of 148 ename:VK_COMPARE_OP_LESS or ename:VK_COMPARE_OP_LESS_OR_EQUAL; and 149 * either 150 ** the fragment shader specifies the code:StencilRefUnchangedBackAMD 151 execution mode; 152 ** the fragment shader specifies the code:StencilRefLessBackAMD execution 153 mode and the pipeline uses a 154 slink:VkPipelineDepthStencilStateCreateInfo::pname:back.compareOp of 155 ename:VK_COMPARE_OP_GREATER or ename:VK_COMPARE_OP_GREATER_OR_EQUAL; or 156 ** the fragment shader specifies the code:StencilRefGreaterBackAMD 157 execution mode and the pipeline uses a 158 slink:VkPipelineDepthStencilStateCreateInfo::pname:back.compareOp of 159 ename:VK_COMPARE_OP_LESS or ename:VK_COMPARE_OP_LESS_OR_EQUAL 160 161an additional <<fragops-stencil, stencil test>> may: be performed before 162<<fragops-shader, fragment shading>>, using the stencil reference value 163specified by 164slink:VkPipelineDepthStencilStateCreateInfo::pname:front.reference or 165slink:VkPipelineDepthStencilStateCreateInfo::pname:back.reference. 166endif::VK_EXT_shader_stencil_export[] 167endif::VK_AMD_shader_early_and_late_fragment_tests[] 168 169 170For a pipeline with the following properties: 171 172 * a fragment shader is specified 173 * the fragment shader 174ifdef::VK_AMD_shader_early_and_late_fragment_tests[] 175 either specifies code:EarlyAndLateFragmentTestsAMD or 176endif::VK_AMD_shader_early_and_late_fragment_tests[] 177 does not write to storage resources; 178 * the fragment shader specifies the code:DepthReplacing execution mode; 179 and 180 * either 181 ** the fragment shader specifies the code:DepthUnchanged execution mode; 182 ** the fragment shader specifies the code:DepthLess execution mode and the 183 pipeline uses a 184 slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp of 185 ename:VK_COMPARE_OP_GREATER or ename:VK_COMPARE_OP_GREATER_OR_EQUAL; or 186 ** the fragment shader specifies the code:DepthGreater execution mode and 187 the pipeline uses a 188 slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp of 189 ename:VK_COMPARE_OP_LESS or ename:VK_COMPARE_OP_LESS_OR_EQUAL 190 191the implementation may: perform <<fragops-dbt,depth bounds test>> before 192<<fragops-shader, fragment shading>> and perform an additional 193<<fragops-depth, depth test>> immediately after that using the interpolated 194depth value generated by rasterization. 195 196Once all fragment operations have completed, fragment shader outputs for 197covered color attachment samples pass through <<framebuffer, framebuffer 198operations>>. 199 200 201ifdef::VK_EXT_discard_rectangles[] 202[[fragops-discard-rectangles]] 203== Discard Rectangles Test 204 205The discard rectangle test compares the framebuffer coordinates 206[eq]#(x~f~,y~f~)# of each sample covered by a fragment against a set of 207_discard rectangles_. 208 209Each discard rectangle is defined by a slink:VkRect2D. 210These values are either set by the 211slink:VkPipelineDiscardRectangleStateCreateInfoEXT structure during pipeline 212creation, or dynamically by the flink:vkCmdSetDiscardRectangleEXT command. 213 214A given sample is considered inside a discard rectangle if the [eq]#x~f~# is 215in the range [eq]#[slink:VkRect2D::pname:offset.x, 216slink:VkRect2D::pname:offset.x {plus} slink:VkRect2D::pname:extent.x)#, and 217[eq]#y~f~# is in the range [eq]#[slink:VkRect2D::pname:offset.y, 218slink:VkRect2D::pname:offset.y {plus} slink:VkRect2D::pname:extent.y)#. 219If the test is set to be inclusive, samples that are not inside any of the 220discard rectangles will have their coverage set to `0`. 221If the test is set to be exclusive, samples that are inside any of the 222discard rectangles will have their coverage set to `0`. 223 224If no discard rectangles are specified, the coverage mask is unmodified by 225this operation. 226 227[open,refpage='VkPipelineDiscardRectangleStateCreateInfoEXT',desc='Structure specifying discard rectangle',type='structs'] 228-- 229The sname:VkPipelineDiscardRectangleStateCreateInfoEXT structure is defined 230as: 231 232include::{generated}/api/structs/VkPipelineDiscardRectangleStateCreateInfoEXT.adoc[] 233 234 * pname:sType is a elink:VkStructureType value identifying this structure. 235 * pname:pNext is `NULL` or a pointer to a structure extending this 236 structure. 237 * pname:flags is reserved for future use. 238 * pname:discardRectangleMode is a elink:VkDiscardRectangleModeEXT value 239 determining whether the discard rectangle test is inclusive or 240 exclusive. 241 * pname:discardRectangleCount is the number of discard rectangles to use. 242 * pname:pDiscardRectangles is a pointer to an array of slink:VkRect2D 243 structures defining discard rectangles. 244 245If the ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state is enabled 246for a pipeline, the pname:pDiscardRectangles member is ignored. 247If the ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT dynamic state is 248not enabled for the pipeline the presence of this structure in the 249slink:VkGraphicsPipelineCreateInfo chain, and a pname:discardRectangleCount 250greater than zero, implicitly enables discard rectangles in the pipeline, 251otherwise discard rectangles must: enabled or disabled by 252flink:vkCmdSetDiscardRectangleEnableEXT. 253If the ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT dynamic state is 254enabled for the pipeline, the pname:discardRectangleMode member is ignored, 255and the discard rectangle mode must: be set by 256flink:vkCmdSetDiscardRectangleModeEXT. 257 258When this structure is included in the pname:pNext chain of 259slink:VkGraphicsPipelineCreateInfo, it defines parameters of the discard 260rectangle test. 261If the ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state is not 262enabled, and this structure is not included in the pname:pNext chain, it is 263equivalent to specifying this structure with a pname:discardRectangleCount 264of `0`. 265 266.Valid Usage 267**** 268 * [[VUID-VkPipelineDiscardRectangleStateCreateInfoEXT-discardRectangleCount-00582]] 269 pname:discardRectangleCount must: be less than or equal to 270 sname:VkPhysicalDeviceDiscardRectanglePropertiesEXT::pname:maxDiscardRectangles 271**** 272 273include::{generated}/validity/structs/VkPipelineDiscardRectangleStateCreateInfoEXT.adoc[] 274-- 275 276[open,refpage='VkPipelineDiscardRectangleStateCreateFlagsEXT',desc='Reserved for future use',type='flags'] 277-- 278include::{generated}/api/flags/VkPipelineDiscardRectangleStateCreateFlagsEXT.adoc[] 279 280tname:VkPipelineDiscardRectangleStateCreateFlagsEXT is a bitmask type for 281setting a mask, but is currently reserved for future use. 282-- 283 284[open,refpage='VkDiscardRectangleModeEXT',desc='Specify the discard rectangle mode',type='enums'] 285-- 286ename:VkDiscardRectangleModeEXT values are: 287 288include::{generated}/api/enums/VkDiscardRectangleModeEXT.adoc[] 289 290 * ename:VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT specifies that the discard 291 rectangle test is inclusive. 292 * ename:VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT specifies that the discard 293 rectangle test is exclusive. 294-- 295 296[open,refpage='vkCmdSetDiscardRectangleEXT',desc='Set discard rectangles dynamically for a command buffer',type='protos'] 297-- 298To <<pipelines-dynamic-state, dynamically set>> the discard rectangles, 299call: 300 301include::{generated}/api/protos/vkCmdSetDiscardRectangleEXT.adoc[] 302 303 * pname:commandBuffer is the command buffer into which the command will be 304 recorded. 305 * pname:firstDiscardRectangle is the index of the first discard rectangle 306 whose state is updated by the command. 307 * pname:discardRectangleCount is the number of discard rectangles whose 308 state are updated by the command. 309 * pname:pDiscardRectangles is a pointer to an array of slink:VkRect2D 310 structures specifying discard rectangles. 311 312The discard rectangle taken from element [eq]#i# of pname:pDiscardRectangles 313replace the current state for the discard rectangle at index 314[eq]#pname:firstDiscardRectangle {plus} i#, for [eq]#i# in [eq]#[0, 315pname:discardRectangleCount)#. 316 317This command sets the discard rectangles for subsequent drawing commands 318ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 319when the graphics pipeline is created with 320ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT set in 321slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 322Otherwise, this state is specified by the 323slink:VkPipelineDiscardRectangleStateCreateInfoEXT::pname:pDiscardRectangles 324values used to create the currently active pipeline. 325 326.Valid Usage 327**** 328 * [[VUID-vkCmdSetDiscardRectangleEXT-firstDiscardRectangle-00585]] 329 The sum of pname:firstDiscardRectangle and pname:discardRectangleCount 330 must: be less than or equal to 331 slink:VkPhysicalDeviceDiscardRectanglePropertiesEXT::pname:maxDiscardRectangles 332 * [[VUID-vkCmdSetDiscardRectangleEXT-x-00587]] 333 The pname:x and pname:y member of pname:offset in each slink:VkRect2D 334 element of pname:pDiscardRectangles must: be greater than or equal to 335 `0` 336 * [[VUID-vkCmdSetDiscardRectangleEXT-offset-00588]] 337 Evaluation of [eq]#(pname:offset.x {plus} pname:extent.width)# in each 338 slink:VkRect2D element of pname:pDiscardRectangles must: not cause a 339 signed integer addition overflow 340 * [[VUID-vkCmdSetDiscardRectangleEXT-offset-00589]] 341 Evaluation of [eq]#(pname:offset.y {plus} pname:extent.height)# in each 342 slink:VkRect2D element of pname:pDiscardRectangles must: not cause a 343 signed integer addition overflow 344ifdef::VK_NV_inherited_viewport_scissor[] 345 * [[VUID-vkCmdSetDiscardRectangleEXT-viewportScissor2D-04788]] 346 If this command is recorded in a secondary command buffer with 347 slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D 348 enabled, then this function must: not be called 349endif::VK_NV_inherited_viewport_scissor[] 350**** 351 352include::{generated}/validity/protos/vkCmdSetDiscardRectangleEXT.adoc[] 353-- 354 355[open,refpage='vkCmdSetDiscardRectangleEnableEXT',desc='Enable discard rectangles dynamically for a command buffer',type='protos'] 356-- 357To <<pipelines-dynamic-state, dynamically set>> whether discard rectangles 358are enabled, call: 359 360include::{generated}/api/protos/vkCmdSetDiscardRectangleEnableEXT.adoc[] 361 362 * pname:commandBuffer is the command buffer into which the command will be 363 recorded. 364 * pname:discardRectangleEnable specifies whether discard rectangles are 365 enabled or not. 366 367This command sets the discard rectangle enable for subsequent drawing 368commands 369ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 370when the graphics pipeline is created with 371ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT set in 372slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 373Otherwise, this state is implied by the 374slink:VkPipelineDiscardRectangleStateCreateInfoEXT::pname:discardRectangleCount 375value used to create the currently active pipeline, where a non-zero 376pname:discardRectangleCount implicitly enables discard rectangles, otherwise 377they are disabled. 378 379.Valid Usage 380**** 381 * [[VUID-vkCmdSetDiscardRectangleEnableEXT-specVersion-07851]] 382 The `apiext:VK_EXT_discard_rectangles` extension must: be enabled, and 383 the implementation must: support at least pname:specVersion `2` of this 384 extension 385**** 386 387include::{generated}/validity/protos/vkCmdSetDiscardRectangleEnableEXT.adoc[] 388-- 389 390[open,refpage='vkCmdSetDiscardRectangleModeEXT',desc='Sets the discard rectangle mode dynamically for a command buffer',type='protos'] 391-- 392To <<pipelines-dynamic-state, dynamically set>> the discard rectangle mode, 393call: 394 395include::{generated}/api/protos/vkCmdSetDiscardRectangleModeEXT.adoc[] 396 397 * pname:commandBuffer is the command buffer into which the command will be 398 recorded. 399 * pname:discardRectangleMode specifies the discard rectangle mode for all 400 discard rectangles, either inclusive or exclusive. 401 402This command sets the discard rectangle mode for subsequent drawing commands 403ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 404when the graphics pipeline is created with 405ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT set in 406slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 407Otherwise, this state is specified by the 408slink:VkPipelineDiscardRectangleStateCreateInfoEXT::pname:discardRectangleMode 409value used to create the currently active pipeline. 410 411.Valid Usage 412**** 413 * [[VUID-vkCmdSetDiscardRectangleModeEXT-specVersion-07852]] 414 The `apiext:VK_EXT_discard_rectangles` extension must: be enabled, and 415 the implementation must: support at least pname:specVersion `2` of this 416 extension 417**** 418 419include::{generated}/validity/protos/vkCmdSetDiscardRectangleModeEXT.adoc[] 420-- 421 422endif::VK_EXT_discard_rectangles[] 423 424 425[[fragops-scissor]] 426== Scissor Test 427 428The scissor test compares the framebuffer coordinates [eq]#(x~f~,y~f~)# of 429each sample covered by a fragment against a _scissor rectangle_ at the index 430equal to the fragment's <<interfaces-builtin-variables-viewportindex, 431code:ViewportIndex>>. 432 433Each scissor rectangle is defined by a slink:VkRect2D. 434These values are either set by the slink:VkPipelineViewportStateCreateInfo 435structure during pipeline creation, or dynamically by the 436flink:vkCmdSetScissor command. 437 438A given sample is considered inside a scissor rectangle if [eq]#x~f~# is in 439the range [eq]#[slink:VkRect2D::pname:offset.x, 440slink:VkRect2D::pname:offset.x {plus} slink:VkRect2D::pname:extent.x)#, and 441[eq]#y~f~# is in the range [eq]#[slink:VkRect2D::pname:offset.y, 442slink:VkRect2D::pname:offset.y {plus} slink:VkRect2D::pname:extent.y)#. 443Samples with coordinates outside the scissor rectangle at the corresponding 444code:ViewportIndex will have their coverage set to `0`. 445 446ifdef::VK_QCOM_render_pass_transform[] 447If a render pass transform is enabled, the (pname:offset.x and 448pname:offset.y) and (pname:extent.width and pname:extent.height) values are 449transformed as described in <<vertexpostproc-renderpass-transform, render 450pass transform>> before participating in the scissor test. 451endif::VK_QCOM_render_pass_transform[] 452 453[open,refpage='vkCmdSetScissor',desc='Set scissor rectangles dynamically for a command buffer',type='protos'] 454-- 455To <<pipelines-dynamic-state, dynamically set>> the scissor rectangles, 456call: 457 458include::{generated}/api/protos/vkCmdSetScissor.adoc[] 459 460 * pname:commandBuffer is the command buffer into which the command will be 461 recorded. 462 * pname:firstScissor is the index of the first scissor whose state is 463 updated by the command. 464 * pname:scissorCount is the number of scissors whose rectangles are 465 updated by the command. 466 * pname:pScissors is a pointer to an array of slink:VkRect2D structures 467 defining scissor rectangles. 468 469The scissor rectangles taken from element [eq]#i# of pname:pScissors replace 470the current state for the scissor index [eq]#pname:firstScissor {plus} i#, 471for [eq]#i# in [eq]#[0, pname:scissorCount)#. 472 473This command sets the scissor rectangles for subsequent drawing commands 474ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 475when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_SCISSOR 476set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 477Otherwise, this state is specified by the 478slink:VkPipelineViewportStateCreateInfo::pname:pScissors values used to 479create the currently active pipeline. 480 481.Valid Usage 482**** 483 * [[VUID-vkCmdSetScissor-firstScissor-00592]] 484 The sum of pname:firstScissor and pname:scissorCount must: be between 485 `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive 486 * [[VUID-vkCmdSetScissor-firstScissor-00593]] 487 If the <<features-multiViewport, pname:multiViewport>> feature is not 488 enabled, pname:firstScissor must: be `0` 489 * [[VUID-vkCmdSetScissor-scissorCount-00594]] 490 If the <<features-multiViewport, pname:multiViewport>> feature is not 491 enabled, pname:scissorCount must: be `1` 492 * [[VUID-vkCmdSetScissor-x-00595]] 493 The pname:x and pname:y members of pname:offset member of any element of 494 pname:pScissors must: be greater than or equal to `0` 495 * [[VUID-vkCmdSetScissor-offset-00596]] 496 Evaluation of [eq]#(pname:offset.x {plus} pname:extent.width)# must: not 497 cause a signed integer addition overflow for any element of 498 pname:pScissors 499 * [[VUID-vkCmdSetScissor-offset-00597]] 500 Evaluation of [eq]#(pname:offset.y {plus} pname:extent.height)# must: 501 not cause a signed integer addition overflow for any element of 502 pname:pScissors 503ifdef::VK_NV_inherited_viewport_scissor[] 504 * [[VUID-vkCmdSetScissor-viewportScissor2D-04789]] 505 If this command is recorded in a secondary command buffer with 506 slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D 507 enabled, then this function must: not be called 508endif::VK_NV_inherited_viewport_scissor[] 509**** 510 511include::{generated}/validity/protos/vkCmdSetScissor.adoc[] 512-- 513 514 515ifdef::VK_NV_scissor_exclusive[] 516[[fragops-exclusive-scissor]] 517== Exclusive Scissor Test 518 519The exclusive scissor test compares the framebuffer coordinates 520[eq]#(x~f~,y~f~)# of each sample covered by a fragment against an _exclusive 521scissor rectangle_ at the index equal to the fragment's 522<<interfaces-builtin-variables-viewportindex, code:ViewportIndex>>. 523 524Each exclusive scissor rectangle is defined by a slink:VkRect2D. 525These values are either set by the 526slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV structure during 527pipeline creation, or dynamically by the flink:vkCmdSetExclusiveScissorNV 528command. 529 530A given sample is considered inside an exclusive scissor rectangle if 531[eq]#x~f~# is in the range [eq]#[slink:VkRect2D::pname:offset.x, 532slink:VkRect2D::pname:offset.x {plus} slink:VkRect2D::pname:extent.x)#, and 533[eq]#y~f~# is in the range [eq]#[slink:VkRect2D::pname:offset.y, 534slink:VkRect2D::pname:offset.y {plus} slink:VkRect2D::pname:extent.y)#. 535Samples with coordinates inside the exclusive scissor rectangle at the 536corresponding code:ViewportIndex will have their coverage set to `0`. 537 538If no exclusive scissor rectangles are specified, the coverage mask is 539unmodified by this operation. 540 541[open,refpage='VkPipelineViewportExclusiveScissorStateCreateInfoNV',desc='Structure specifying parameters controlling exclusive scissor testing',type='structs'] 542-- 543The sname:VkPipelineViewportExclusiveScissorStateCreateInfoNV structure is 544defined as: 545 546include::{generated}/api/structs/VkPipelineViewportExclusiveScissorStateCreateInfoNV.adoc[] 547 548 * pname:sType is a elink:VkStructureType value identifying this structure. 549 * pname:pNext is `NULL` or a pointer to a structure extending this 550 structure. 551 * pname:exclusiveScissorCount is the number of exclusive scissor 552 rectangles. 553 * pname:pExclusiveScissors is a pointer to an array of slink:VkRect2D 554 structures defining exclusive scissor rectangles. 555 556If the ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV dynamic state is enabled 557for a pipeline, the pname:pExclusiveScissors member is ignored. 558 559When this structure is included in the pname:pNext chain of 560slink:VkGraphicsPipelineCreateInfo, it defines parameters of the exclusive 561scissor test. 562If this structure is not included in the pname:pNext chain, it is equivalent 563to specifying this structure with a pname:exclusiveScissorCount of `0`. 564 565.Valid Usage 566**** 567 * [[VUID-VkPipelineViewportExclusiveScissorStateCreateInfoNV-exclusiveScissorCount-02027]] 568 If the <<features-multiViewport, pname:multiViewport>> feature is not 569 enabled, pname:exclusiveScissorCount must: be `0` or `1` 570 * [[VUID-VkPipelineViewportExclusiveScissorStateCreateInfoNV-exclusiveScissorCount-02028]] 571 pname:exclusiveScissorCount must: be less than or equal to 572 sname:VkPhysicalDeviceLimits::pname:maxViewports 573 * [[VUID-VkPipelineViewportExclusiveScissorStateCreateInfoNV-exclusiveScissorCount-02029]] 574 pname:exclusiveScissorCount must: be `0` or greater than or equal to the 575 pname:viewportCount member of slink:VkPipelineViewportStateCreateInfo 576 577**** 578include::{generated}/validity/structs/VkPipelineViewportExclusiveScissorStateCreateInfoNV.adoc[] 579-- 580 581[open,refpage='vkCmdSetExclusiveScissorNV',desc='Set exclusive scissor rectangles dynamically for a command buffer',type='protos'] 582-- 583To <<pipelines-dynamic-state, dynamically set>> the exclusive scissor 584rectangles, call: 585 586include::{generated}/api/protos/vkCmdSetExclusiveScissorNV.adoc[] 587 588 * pname:commandBuffer is the command buffer into which the command will be 589 recorded. 590 * pname:firstExclusiveScissor is the index of the first exclusive scissor 591 rectangle whose state is updated by the command. 592 * pname:exclusiveScissorCount is the number of exclusive scissor 593 rectangles updated by the command. 594 * pname:pExclusiveScissors is a pointer to an array of slink:VkRect2D 595 structures defining exclusive scissor rectangles. 596 597The scissor rectangles taken from element [eq]#i# of 598pname:pExclusiveScissors replace the current state for the scissor index 599[eq]#pname:firstExclusiveScissor {plus} i#, for [eq]#i# in [eq]#[0, 600pname:exclusiveScissorCount)#. 601 602This command sets the exclusive scissor rectangles for subsequent drawing 603commands 604ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 605when the graphics pipeline is created with 606ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV set in 607slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 608Otherwise, this state is specified by the 609slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV::pname:pExclusiveScissors 610values used to create the currently active pipeline. 611 612.Valid Usage 613**** 614 * [[VUID-vkCmdSetExclusiveScissorNV-None-02031]] 615 The <<features-exclusiveScissor, pname:exclusiveScissor>> feature must: 616 be enabled 617 * [[VUID-vkCmdSetExclusiveScissorNV-firstExclusiveScissor-02034]] 618 The sum of pname:firstExclusiveScissor and pname:exclusiveScissorCount 619 must: be between `1` and 620 sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive 621 * [[VUID-vkCmdSetExclusiveScissorNV-firstExclusiveScissor-02035]] 622 If the <<features-multiViewport, pname:multiViewport>> feature is not 623 enabled, pname:firstExclusiveScissor must: be `0` 624 * [[VUID-vkCmdSetExclusiveScissorNV-exclusiveScissorCount-02036]] 625 If the <<features-multiViewport, pname:multiViewport>> feature is not 626 enabled, pname:exclusiveScissorCount must: be `1` 627 * [[VUID-vkCmdSetExclusiveScissorNV-x-02037]] 628 The pname:x and pname:y members of pname:offset in each member of 629 pname:pExclusiveScissors must: be greater than or equal to `0` 630 * [[VUID-vkCmdSetExclusiveScissorNV-offset-02038]] 631 Evaluation of [eq]#(pname:offset.x {plus} pname:extent.width)# for each 632 member of pname:pExclusiveScissors must: not cause a signed integer 633 addition overflow 634 * [[VUID-vkCmdSetExclusiveScissorNV-offset-02039]] 635 Evaluation of [eq]#(pname:offset.y {plus} pname:extent.height)# for each 636 member of pname:pExclusiveScissors must: not cause a signed integer 637 addition overflow 638**** 639 640include::{generated}/validity/protos/vkCmdSetExclusiveScissorNV.adoc[] 641-- 642 643[open,refpage='vkCmdSetExclusiveScissorEnableNV',desc='Dynamically enable each exclusive scissor for a command buffer',type='protos'] 644-- 645To <<pipelines-dynamic-state, dynamically set>> whether an exclusive scissor 646is enabled or not, call: 647 648include::{generated}/api/protos/vkCmdSetExclusiveScissorEnableNV.adoc[] 649 650 * pname:commandBuffer is the command buffer into which the command will be 651 recorded. 652 * pname:firstExclusiveScissor is the index of the first exclusive scissor 653 rectangle whose state is updated by the command. 654 * pname:exclusiveScissorCount is the number of exclusive scissor 655 rectangles updated by the command. 656 * pname:pExclusiveScissorEnables is a pointer to an array of 657 basetype:VkBool32 values defining whether the exclusive scissor is 658 enabled. 659 660The exclusive scissor enables taken from element [eq]#i# of 661pname:pExclusiveScissorEnables replace the current state for the scissor 662index [eq]#pname:firstExclusiveScissor {plus} i#, for [eq]#i# in [eq]#[0, 663pname:exclusiveScissorCount)#. 664 665This command sets the exclusive scissor enable for subsequent drawing 666commands 667ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 668when the graphics pipeline is created with 669ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV set in 670slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 671Otherwise, this state is implied by the 672slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV::pname:exclusiveScissorCount 673value used to create the currently active pipeline, where all 674pname:exclusiveScissorCount exclusive scissors are implicitly enabled and 675the remainder up to sname:VkPhysicalDeviceLimits::pname:maxViewports are 676implicitly disabled. 677 678.Valid Usage 679**** 680 * [[VUID-vkCmdSetExclusiveScissorEnableNV-exclusiveScissor-07853]] 681 The <<features-exclusiveScissor, pname:exclusiveScissor>> feature must: 682 be enabled, and the implementation must: support at least 683 pname:specVersion `2` of the `apiext:VK_NV_scissor_exclusive` extension 684**** 685 686include::{generated}/validity/protos/vkCmdSetExclusiveScissorEnableNV.adoc[] 687-- 688endif::VK_NV_scissor_exclusive[] 689 690 691[[fragops-samplemask]] 692== Sample Mask Test 693 694The sample mask test compares the <<primsrast-multisampling-coverage-mask, 695coverage mask>> for a fragment with the _sample mask_ defined by 696slink:VkPipelineMultisampleStateCreateInfo::pname:pSampleMask. 697 698ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 699 700[open,refpage='vkCmdSetSampleMaskEXT',desc='Specify the sample mask dynamically for a command buffer',type='protos'] 701-- 702To <<pipelines-dynamic-state, dynamically set>> the sample mask, call: 703 704include::{generated}/api/protos/vkCmdSetSampleMaskEXT.adoc[] 705 706 * pname:commandBuffer is the command buffer into which the command will be 707 recorded. 708 * pname:samples specifies the number of sample bits in the 709 pname:pSampleMask. 710 * pname:pSampleMask is a pointer to an array of basetype:VkSampleMask 711 values, where the array size is based on the pname:samples parameter. 712 713This command sets the sample mask for subsequent drawing commands 714ifdef::VK_EXT_shader_object[] 715ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 716ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 717endif::VK_EXT_shader_object[] 718ifdef::VK_EXT_extended_dynamic_state3[] 719when the graphics pipeline is created with 720ename:VK_DYNAMIC_STATE_SAMPLE_MASK_EXT set in 721slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 722endif::VK_EXT_extended_dynamic_state3[] 723Otherwise, this state is specified by the 724slink:VkPipelineMultisampleStateCreateInfo::pname:pSampleMask value used to 725create the currently active pipeline. 726 727:refpage: vkCmdSetSampleMaskEXT 728:requiredfeature: extendedDynamicState3SampleMask 729 730.Valid Usage 731**** 732include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 733**** 734 735include::{generated}/validity/protos/vkCmdSetSampleMaskEXT.adoc[] 736-- 737 738endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 739 740Each bit of the coverage mask is associated with a sample index as described 741in the <<primsrast-multisampling-coverage-mask, rasterization chapter>>. 742If the bit in slink:VkPipelineMultisampleStateCreateInfo::pname:pSampleMask 743which is associated with that same sample index is set to `0`, the coverage 744mask bit is set to `0`. 745 746 747[[fragops-shader]] 748== Fragment Shading 749 750<<shaders-fragment, Fragment shaders>> are invoked for each fragment, or as 751<<shaders-helper-invocations, helper invocations>>. 752 753Most operations in the fragment shader are not performed in 754<<primsrast-order, rasterization order>>, with exceptions called out in the 755following sections. 756 757For fragment shaders invoked by fragments, the following rules apply: 758 759 * A fragment shader must: not be executed if a <<fragops, fragment 760 operation>> that executes before fragment shading discards the fragment. 761 * A fragment shader may: not be executed if: 762 ** An implementation determines that another fragment shader, invoked by a 763 subsequent primitive in <<drawing-primitive-order, primitive order>>, 764 overwrites all results computed by the shader (including writes to 765 storage resources). 766 ** Any other <<fragops, fragment operation>> discards the fragment, and 767 the shader does not write to any storage resources. 768 * Otherwise, at least one fragment shader must: be executed. 769 ** If <<primsrast-sampleshading,sample shading>> is enabled and multiple 770 invocations per fragment are required:, additional invocations must: be 771 executed as specified. 772ifdef::VK_NV_shading_rate_image[] 773 ** If a <<primsrast-shading-rate-image,shading rate image>> is used and 774 multiple invocations per fragment are required:, additional invocations 775 must: be executed as specified. 776endif::VK_NV_shading_rate_image[] 777 ** Each covered sample must: be included in at least one fragment shader 778 invocation. 779 780If no fragment shader is included in the pipeline, no fragment shader is 781executed, and undefined: values may: be written to all color attachment 782outputs during this fragment operation. 783 784[NOTE] 785.Note 786==== 787Multiple fragment shader invocations may be executed for the same fragment 788for any number of implementation-dependent reasons. 789When there is more than one fragment shader invocation per fragment, the 790association of samples to invocations is implementation-dependent. 791Stores and atomics performed by these additional invocations have the normal 792effect. 793 794ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 795For example, if the subpass includes multiple views in its view mask, a 796fragment shader may be invoked separately for each view. 797endif::VK_VERSION_1_1,VK_KHR_multiview[] 798 799ifdef::VK_EXT_fragment_density_map[] 800Similarly, if the render pass has a fragment density map attachment, more 801than one fragment shader invocation may be invoked for each covered sample. 802Such additional invocations are only produced if 803sname:VkPhysicalDeviceFragmentDensityMapPropertiesEXT::pname:fragmentDensityInvocations 804is ename:VK_TRUE. 805Implementations may generate these additional fragment shader invocations in 806order to make transitions between fragment areas with different fragment 807densities more smooth. 808endif::VK_EXT_fragment_density_map[] 809==== 810 811 812[[fragops-shader-samplemask]] 813=== Sample Mask 814 815Reading from the <<interfaces-builtin-variables-samplemask, 816code:SampleMask>> built-in in the code:Input storage class will return the 817coverage mask for the current fragment as calculated by fragment operations 818that executed prior to fragment shading. 819 820If <<primsrast-sampleshading, sample shading>> is enabled, fragment shaders 821will only see values of `1` for samples being shaded - other bits will be 822`0`. 823 824Each bit of the coverage mask is associated with a sample index as described 825in the <<primsrast-multisampling-coverage-mask, rasterization chapter>>. 826If the bit in code:SampleMask which is associated with that same sample 827index is set to `0`, that coverage mask bit is set to `0`. 828 829Values written to the <<interfaces-builtin-variables-samplemask, 830code:SampleMask>> built-in in the code:Output storage class will be used by 831the <<fragops-covg, multisample coverage>> operation, with the same encoding 832as the input built-in. 833 834ifdef::VK_EXT_shader_tile_image[] 835[[fragops-shader-tileimage-reads]] 836=== Fragment Shader Tile Image Reads 837If the `apiext:VK_EXT_shader_tile_image` extension is enabled, 838implementations divide the framebuffer into a grid of tiles. 839A <<glossary-tile-image, tile image>> is a view of a framebuffer attachment 840tile for fragments with locations within the tile. 841 842Within a render pass instance initiated by flink:vkCmdBeginRenderingKHR, 843fragment shader invocations can: read the framebuffer color, depth, and 844stencil values at the fragment location via tile images. 845 846[NOTE] 847.Note 848==== 849Even though fragment shader invocation can only read from the corresponding 850fragment location, the abstraction of a tile image is introduced for the 851following reasons: 852 853 * Tile dimensions will be exposed in a future extension 854 * Future functionality such as executing compute dispatches within render 855 passes via tile shaders can leverage tile images. 856==== 857 858Enabling <<features-shaderTileImageColorReadAccess, 859shaderTileImageColorReadAccess>>, <<features-shaderTileImageDepthReadAccess, 860shaderTileImageDepthReadAccess>>, 861<<features-shaderTileImageStencilReadAccess, 862shaderTileImageStencilReadAccess>> enables fragment shader invocations to 863read from color, depth, and stencil, respectively. 864 865Color values are read from tile image variables with 866code:OpColorAttachmentReadEXT. 867Tile image variables are linked to specific color attachments using 868code:Location decoration. 869See <<interfaces-fragmenttileimage, Fragment Tile Image Interface>> for more 870details. 871 872Depth values are read with code:OpDepthAttachmentReadEXT. 873 874Stencil values are read with code:OpStencilAttachmentReadEXT. 875 876The sample to read is specified by a 877<<primsrast-multisampling-coverage-mask, sample index>> value specified as 878the code:Sample operand to code:OpColorAttachmentReadEXT, 879code:OpDepthAttachmentReadEXT, or code:OpStencilAttachmentReadEXT. 880 881If <<primsrast-sampleshading, sample shading>> is disabled, a fragment 882invocation can: read from all sample locations associated with the fragment 883regardless of the fragment's coverage. 884This functionality is supported for 885slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples > 1 886when 887slink:VkPhysicalDeviceShaderTileImagePropertiesEXT::pname:shaderTileImageReadSampleFromPixelRateInvocation 888is ename:VK_TRUE. 889 890If <<primsrast-sampleshading, sample shading>> is enabled, and 891pname:minSampleShading is 1.0, a fragment invocation must: only read from 892the <<primsrast-multisampling-coverageindex, coverage index>> sample. 893Tile image access must: not be used if the value of pname:minSampleShading 894is not 1.0. 895 896If the <<fragops-shader, fragment shader>> declares the 897code:EarlyFragmentTests execution mode, depth reads are allowed only if 898depth writes are disabled and stencil reads are allowed only if stencil 899writes are disabled. 900 901If 902slink:VkPhysicalDeviceShaderTileImagePropertiesEXT::pname:shaderTileImageReadFromHelperInvocation 903is ename:VK_FALSE, values read from helper invocations are undefined: 904otherwise the values read are subject to the coherency guarantees described 905below. 906 907code:OpDepthAttachmentReadEXT returns an undefined: value if no depth 908attachment is present. 909code:OpStencilAttachmentReadEXT returns an undefined: value if no stencil 910attachment is present. 911 912Tile image reads from color, depth and stencil attachments are said to be 913coherent when the accesses happen in raster order and without 914<<memory-model-access-data-race, data race>> with respect to accesses to the 915attachments from framebuffer-space pipeline stages. 916The samples which qualify for coherent access and the enabling conditions 917are described below. 918 919 * Let [eq]#Rc# be the set of components being read from an attachment 920 [eq]#A# in a draw call 921 * Let [eq]#Wc# be the set of components being written to [eq]#A# by the 922 draw call 923 924The samples which qualify for coherent tile image reads from an attachment 925[eq]#A# are: 926 927 * All samples in a pixel when [eq]#Rc# is disjoint with [eq]#Wc#. 928 * The samples with coverage in a fragment when [eq]#Rc# is not disjoint 929 with [eq]#Wc#. 930 The samples with coverage are determined by the coverage mask for the 931 fragment as calculated by fragment operations that executed prior to 932 fragment shading, including early fragment tests if enabled for the draw 933 call. 934 935A fragment shader can: declare code:NonCoherentColorAttachmentReadEXT, 936code:NonCoherentDepthAttachmentReadEXT, or 937code:NonCoherentStencilAttachmentReadEXT execution modes to enable 938non-coherent tile image reads which requires 939<<synchronization-pipeline-barriers-explicit-renderpass-tileimage, explicit 940tile image synchronization>> for the writes to an attachment to be made 941visible via tile image reads. 942 943When 944slink:VkPhysicalDeviceShaderTileImagePropertiesEXT::pname:shaderTileImageCoherentReadAccelerated 945is ename:VK_TRUE, the implementation prefers that coherent tile image reads 946are used, otherwise the implementation prefers that non-coherent tile image 947reads are used. 948 949[NOTE] 950.Note 951==== 952In practice, the most common tile image reads usage patterns fall under one 953of the following: 954 955 * Programmable blending - each fragment reads from a single sample 956 (SampleID) at its location. 957 Per-sample shading is typically enabled when multisampled rendertargets 958 are used. 959 * G-buffer generation and shading in one render pass - in the shading 960 phase a fragment reads from a single sample at its location. 961 * Programmable resolve - a fragment reads from all samples at its location 962 (per-sample shading is disabled). 963 This requires the use of a "full-screen triangle" instead of a rectangle 964 composed of two triangles in order to avoid data races along the shared 965 edge of the triangles. 966 * 1:1 texturing with LOD - in use cases such a deferred screen space 967 decals a fragment reads a single sample (SampleID) from depth buffer, 968 but requires being able to read from helper threads to derive the 969 texture LOD. 970 This use case is supported as long as the attachment components being 971 read are not overwritten by color, depth, or stencil attachment writes. 972 973All of the above use cases are supported by coherent tile image reads, but 974only the latter three are supported when non-coherent reads are used as 975there is no mechanism to synchronize non-coherent reads with writes within a 976draw call. 977==== 978 979endif::VK_EXT_shader_tile_image[] 980 981[[fragops-shader-depthreplacement]] 982=== Depth Replacement 983 984Writing to the <<interfaces-builtin-variables-fragdepth,code:FragDepth>> 985built-in will replace the fragment's calculated depth values for each sample 986in the input code:SampleMask. 987<<fragops-depth, Depth testing>> performed after the fragment shader for 988this fragment will use this new value as [eq]#z~f~#. 989 990 991ifdef::VK_EXT_shader_stencil_export[] 992[[fragops-shader-stencilrefreplacement]] 993=== Stencil Reference Replacement 994 995Writing to the 996<<interfaces-builtin-variables-fragdepth,code:FragStencilRefEXT>> built-in 997will replace the fragment's stencil reference value for each sample in the 998input code:SampleMask. 999<<fragops-stencil, Stencil testing>> performed after the fragment shader for 1000this fragment will use this new value as [eq]#s~r~#. 1001endif::VK_EXT_shader_stencil_export[] 1002 1003 1004ifdef::VK_EXT_fragment_shader_interlock[] 1005[[fragops-shader-interlock]] 1006=== Interlocked Operations 1007 1008code:OpBeginInvocationInterlockEXT and code:OpEndInvocationInterlockEXT 1009define a section of a fragment shader which imposes additional ordering 1010constraints on operations performed within them. 1011These operations are defined as _interlocked operations_. 1012How interlocked operations are ordered against other fragment shader 1013invocations depends on the specified execution modes. 1014 1015ifdef::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 1016If the code:ShadingRateInterlockOrderedEXT execution mode is specified, any 1017interlocked operations in a fragment shader must: happen before interlocked 1018operations in fragment shader invocations that execute later in 1019<<primsrast-order, rasterization order>> and cover at least one sample in 1020the same fragment area, and must: happen after interlocked operations in a 1021fragment shader that executes earlier in <<primsrast-order, rasterization 1022order>> and cover at least one sample in the same fragment area. 1023 1024If the code:ShadingRateInterlockUnorderedEXT execution mode is specified, 1025any interlocked operations in a fragment shader must: happen before or after 1026interlocked operations in fragment shader invocations that execute earlier 1027or later in <<primsrast-order, rasterization order>> and cover at least one 1028sample in the same fragment area. 1029endif::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 1030 1031If the code:PixelInterlockOrderedEXT execution mode is specified, any 1032interlocked operations in a fragment shader must: happen before interlocked 1033operations in fragment shader invocations that execute later in 1034<<primsrast-order, rasterization order>> and cover at least one sample in 1035the same pixel, and must: happen after interlocked operations in a fragment 1036shader that executes earlier in <<primsrast-order, rasterization order>> and 1037cover at least one sample in the same pixel. 1038 1039If the code:PixelInterlockUnorderedEXT execution mode is specified, any 1040interlocked operations in a fragment shader must: happen before or after 1041interlocked operations in fragment shader invocations that execute earlier 1042or later in <<primsrast-order, rasterization order>> and cover at least one 1043sample in the same pixel. 1044 1045If the code:SampleInterlockOrderedEXT execution mode is specified, any 1046interlocked operations in a fragment shader must: happen before interlocked 1047operations in fragment shader invocations that execute later in 1048<<primsrast-order, rasterization order>> and cover at least one of the same 1049samples, and must: happen after interlocked operations in a fragment shader 1050that executes earlier in <<primsrast-order, rasterization order>> and cover 1051at least one of the same samples. 1052 1053If the code:SampleInterlockUnorderedEXT execution mode is specified, any 1054interlocked operations in a fragment shader must: happen before or after 1055interlocked operations in fragment shader invocations that execute earlier 1056or later in <<primsrast-order, rasterization order>> and cover at least one 1057of the same samples. 1058endif::VK_EXT_fragment_shader_interlock[] 1059 1060 1061[[fragops-covg]] 1062== Multisample Coverage 1063 1064If a fragment shader is active and its entry point's interface includes a 1065built-in output variable decorated with code:SampleMask, 1066ifdef::VK_NV_sample_mask_override_coverage[] 1067but not code:OverrideCoverageNV, 1068endif::VK_NV_sample_mask_override_coverage[] 1069the coverage mask is code:ANDed with the bits of the code:SampleMask 1070built-in to generate a new coverage mask. 1071ifdef::VK_NV_sample_mask_override_coverage[] 1072If the code:SampleMask built-in is also decorated with 1073code:OverrideCoverageNV, the coverage mask is replaced with the mask bits 1074set in the shader. 1075endif::VK_NV_sample_mask_override_coverage[] 1076If <<primsrast-sampleshading,sample shading>> is enabled, bits written to 1077code:SampleMask corresponding to samples that are not being shaded by the 1078fragment shader invocation are ignored. 1079If no fragment shader is active, or if the active fragment shader does not 1080include code:SampleMask in its interface, the coverage mask is not modified. 1081 1082Next, the fragment alpha value and coverage mask are modified based on the 1083ifdef::VK_EXT_line_rasterization[] 1084line coverage factor if the pname:lineRasterizationMode member of the 1085slink:VkPipelineRasterizationStateCreateInfo structure is 1086ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, and the 1087endif::VK_EXT_line_rasterization[] 1088pname:alphaToCoverageEnable and pname:alphaToOneEnable members of the 1089slink:VkPipelineMultisampleStateCreateInfo structure. 1090 1091ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 1092 1093[open,refpage='vkCmdSetAlphaToCoverageEnableEXT',desc='Specify the alpha to coverage enable state dynamically for a command buffer',type='protos'] 1094-- 1095To <<pipelines-dynamic-state, dynamically set>> the 1096pname:alphaToCoverageEnable state, call: 1097 1098include::{generated}/api/protos/vkCmdSetAlphaToCoverageEnableEXT.adoc[] 1099 1100 * pname:commandBuffer is the command buffer into which the command will be 1101 recorded. 1102 * pname:alphaToCoverageEnable specifies the pname:alphaToCoverageEnable 1103 state. 1104 1105This command sets the pname:alphaToCoverageEnable state for subsequent 1106drawing commands 1107ifdef::VK_EXT_shader_object[] 1108ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 1109ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 1110endif::VK_EXT_shader_object[] 1111ifdef::VK_EXT_extended_dynamic_state3[] 1112when the graphics pipeline is created with 1113ename:VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT set in 1114slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1115endif::VK_EXT_extended_dynamic_state3[] 1116Otherwise, this state is specified by the 1117slink:VkPipelineMultisampleStateCreateInfo::pname:alphaToCoverageEnable 1118value used to create the currently active pipeline. 1119 1120:refpage: vkCmdSetAlphaToCoverageEnableEXT 1121:requiredfeature: extendedDynamicState3AlphaToCoverageEnable 1122 1123.Valid Usage 1124**** 1125include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 1126**** 1127 1128include::{generated}/validity/protos/vkCmdSetAlphaToCoverageEnableEXT.adoc[] 1129-- 1130 1131[open,refpage='vkCmdSetAlphaToOneEnableEXT',desc='Specify the alpha to one enable state dynamically for a command buffer',type='protos'] 1132-- 1133To <<pipelines-dynamic-state, dynamically set>> the pname:alphaToOneEnable 1134state, call: 1135 1136include::{generated}/api/protos/vkCmdSetAlphaToOneEnableEXT.adoc[] 1137 1138 * pname:commandBuffer is the command buffer into which the command will be 1139 recorded. 1140 * pname:alphaToOneEnable specifies the pname:alphaToOneEnable state. 1141 1142This command sets the pname:alphaToOneEnable state for subsequent drawing 1143commands 1144ifdef::VK_EXT_shader_object[] 1145ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 1146ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 1147endif::VK_EXT_shader_object[] 1148ifdef::VK_EXT_extended_dynamic_state3[] 1149when the graphics pipeline is created with 1150ename:VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT set in 1151slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1152endif::VK_EXT_extended_dynamic_state3[] 1153Otherwise, this state is specified by the 1154slink:VkPipelineMultisampleStateCreateInfo::pname:alphaToOneEnable value 1155used to create the currently active pipeline. 1156 1157:refpage: vkCmdSetAlphaToOneEnableEXT 1158:requiredfeature: extendedDynamicState3AlphaToOneEnable 1159 1160.Valid Usage 1161**** 1162include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 1163 * [[VUID-vkCmdSetAlphaToOneEnableEXT-alphaToOne-07607]] 1164 If the <<features-alphaToOne, pname:alphaToOne>> feature is not enabled, 1165 pname:alphaToOneEnable must: be ename:VK_FALSE 1166**** 1167 1168include::{generated}/validity/protos/vkCmdSetAlphaToOneEnableEXT.adoc[] 1169-- 1170 1171endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 1172 1173All alpha values in this section refer only to the alpha component of the 1174fragment shader output that has a code:Location and code:Index decoration of 1175zero (see the <<interfaces-fragmentoutput,Fragment Output Interface>> 1176section). 1177If that shader output has an integer or unsigned integer type, then these 1178operations are skipped. 1179 1180ifdef::VK_EXT_line_rasterization[] 1181If the pname:lineRasterizationMode member of the 1182slink:VkPipelineRasterizationStateCreateInfo structure is 1183ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT and the fragment 1184came from a line segment, then the alpha value is replaced by multiplying it 1185by the coverage factor for the fragment computed during 1186<<primsrast-lines-smooth,smooth line rasterization>>. 1187endif::VK_EXT_line_rasterization[] 1188 1189If pname:alphaToCoverageEnable is enabled, a temporary coverage mask is 1190generated where each bit is determined by the fragment's alpha value, which 1191is ANDed with the fragment coverage mask. 1192 1193No specific algorithm is specified for converting the alpha value to a 1194temporary coverage mask. 1195It is intended that the number of 1's in this value be proportional to the 1196alpha value (clamped to [eq]#[0,1]#), with all 1's corresponding to a value 1197of 1.0 and all 0's corresponding to 0.0. 1198The algorithm may: be different at different framebuffer coordinates. 1199 1200[NOTE] 1201.Note 1202==== 1203Using different algorithms at different framebuffer coordinates may: help to 1204avoid artifacts caused by regular coverage sample locations. 1205==== 1206 1207Finally, if pname:alphaToOneEnable is enabled, each alpha value is replaced 1208by the maximum representable alpha value for fixed-point color attachments, 1209or by 1.0 for floating-point attachments. 1210Otherwise, the alpha values are not changed. 1211 1212 1213[[fragops-ds-state]] 1214== Depth and Stencil Operations 1215 1216Pipeline state controlling the <<fragops-dbt,depth bounds tests>>, 1217<<fragops-stencil,stencil test>>, and <<fragops-depth,depth test>> is 1218specified through the members of the 1219sname:VkPipelineDepthStencilStateCreateInfo structure. 1220 1221[open,refpage='VkPipelineDepthStencilStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline depth stencil state',type='structs'] 1222-- 1223The sname:VkPipelineDepthStencilStateCreateInfo structure is defined as: 1224 1225include::{generated}/api/structs/VkPipelineDepthStencilStateCreateInfo.adoc[] 1226 1227 * pname:sType is a elink:VkStructureType value identifying this structure. 1228 * pname:pNext is `NULL` or a pointer to a structure extending this 1229 structure. 1230ifndef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1231 * pname:flags is reserved for future use. 1232endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1233ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1234 * pname:flags is a bitmask of 1235 elink:VkPipelineDepthStencilStateCreateFlagBits specifying additional 1236 depth/stencil state information. 1237endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1238 * pname:depthTestEnable controls whether <<fragops-depth,depth testing>> 1239 is enabled. 1240 * pname:depthWriteEnable controls whether <<fragops-depth-write,depth 1241 writes>> are enabled when pname:depthTestEnable is ename:VK_TRUE. 1242 Depth writes are always disabled when pname:depthTestEnable is 1243 ename:VK_FALSE. 1244 * pname:depthCompareOp is a elink:VkCompareOp value specifying the 1245 comparison operator to use in the <<fragops-depth-comparison, Depth 1246 Comparison>> step of the <<fragops-depth,depth test>>. 1247 * pname:depthBoundsTestEnable controls whether <<fragops-dbt,depth bounds 1248 testing>> is enabled. 1249 * pname:stencilTestEnable controls whether <<fragops-stencil,stencil 1250 testing>> is enabled. 1251 * pname:front and pname:back are slink:VkStencilOpState values controlling 1252 the corresponding parameters of the <<fragops-stencil,stencil test>>. 1253 * pname:minDepthBounds is the minimum depth bound used in the 1254 <<fragops-dbt, depth bounds test>>. 1255 * pname:maxDepthBounds is the maximum depth bound used in the 1256 <<fragops-dbt, depth bounds test>>. 1257 1258.Valid Usage 1259**** 1260 * [[VUID-VkPipelineDepthStencilStateCreateInfo-depthBoundsTestEnable-00598]] 1261 If the <<features-depthBounds, pname:depthBounds>> feature is not 1262 enabled, pname:depthBoundsTestEnable must: be ename:VK_FALSE 1263ifdef::VK_KHR_portability_subset[] 1264 * [[VUID-VkPipelineDepthStencilStateCreateInfo-separateStencilMaskRef-04453]] 1265 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 1266 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:separateStencilMaskRef 1267 is ename:VK_FALSE, and the value of 1268 slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable is 1269 ename:VK_TRUE, and the value of 1270 slink:VkPipelineRasterizationStateCreateInfo::pname:cullMode is 1271 ename:VK_CULL_MODE_NONE, the value of pname:reference in each of the 1272 slink:VkStencilOpState structs in pname:front and pname:back must: be 1273 the same 1274endif::VK_KHR_portability_subset[] 1275ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1276 * [[VUID-VkPipelineDepthStencilStateCreateInfo-rasterizationOrderDepthAttachmentAccess-06463]] 1277 If the <<features-rasterizationOrderDepthAttachmentAccess, 1278 pname:rasterizationOrderDepthAttachmentAccess>> feature is not enabled, 1279 pname:flags must: not include 1280 ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT 1281 * [[VUID-VkPipelineDepthStencilStateCreateInfo-rasterizationOrderStencilAttachmentAccess-06464]] 1282 If the <<features-rasterizationOrderStencilAttachmentAccess, 1283 pname:rasterizationOrderStencilAttachmentAccess>> feature is not 1284 enabled, pname:flags must: not include 1285 ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT 1286endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1287**** 1288 1289include::{generated}/validity/structs/VkPipelineDepthStencilStateCreateInfo.adoc[] 1290-- 1291 1292[open,refpage='VkPipelineDepthStencilStateCreateFlags',desc='Bitmask of VkPipelineDepthStencilStateCreateFlagBits',type='flags'] 1293-- 1294include::{generated}/api/flags/VkPipelineDepthStencilStateCreateFlags.adoc[] 1295 1296ifndef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1297tname:VkPipelineDepthStencilStateCreateFlags is a bitmask type for setting a 1298mask, but is currently reserved for future use. 1299endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1300ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1301tname:VkPipelineDepthStencilStateCreateFlags is a bitmask type for setting a 1302mask of zero or more elink:VkPipelineDepthStencilStateCreateFlagBits. 1303endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1304-- 1305 1306ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1307[open,refpage='VkPipelineDepthStencilStateCreateFlagBits',desc='Bitmask specifying additional depth/stencil state information.',type='enums'] 1308-- 1309Bits which can: be set in the 1310slink:VkPipelineDepthStencilStateCreateInfo::pname:flags parameter are: 1311 1312include::{generated}/api/enums/VkPipelineDepthStencilStateCreateFlagBits.adoc[] 1313 1314 * ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT 1315 indicates that access to the depth aspects of depth/stencil and input 1316 attachments will have implicit framebuffer-local memory dependencies. 1317 * ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT 1318 indicates that access to the stencil aspects of depth/stencil and input 1319 attachments will have implicit framebuffer-local memory dependencies. 1320 1321When 1322ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT 1323is included in a pipeline, it forms a framebuffer-local memory dependency 1324for each fragment generated by draw commands for that pipeline with the 1325following scopes: 1326 1327 * The first <<synchronization-dependencies-scopes, synchronization scope>> 1328 includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT and 1329 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed 1330 by all previous fragments (as defined by <<drawing-primitive-order, 1331 primitive order>>) in the corresponding 1332 <<synchronization-framebuffer-regions, framebuffer regions>> including 1333 those generated by the same draw command. 1334 * The second <<synchronization-dependencies-scopes, synchronization 1335 scope>> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT stage 1336 executed by the generated fragment. 1337 * The first <<synchronization-dependencies-access-scopes, access scope>> 1338 includes all writes to the depth aspect of depth/stencil attachments. 1339 * The second <<synchronization-dependencies-access-scopes, access scope>> 1340 includes all reads from the depth aspect of input attachments. 1341 1342When 1343ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT 1344is included in a pipeline, it forms a framebuffer-local memory dependency 1345for each fragment generated by draw commands for that pipeline with the 1346following scopes: 1347 1348 * The first <<synchronization-dependencies-scopes, synchronization scope>> 1349 includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT 1350 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed 1351 by all previous fragments (as defined by <<drawing-primitive-order, 1352 primitive order>>) in the corresponding 1353 <<synchronization-framebuffer-regions, framebuffer regions>> including 1354 those generated by the same draw command. 1355 * The second <<synchronization-dependencies-scopes, synchronization 1356 scope>> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT and 1357 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed 1358 by the generated fragment. 1359 * The first <<synchronization-dependencies-access-scopes, access scope>> 1360 includes all writes to the stencil aspect of depth/stencil attachments. 1361 * The second <<synchronization-dependencies-access-scopes, access scope>> 1362 includes all reads from the stencil aspect of input attachments. 1363-- 1364endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1365 1366 1367[[fragops-dbt]] 1368== Depth Bounds Test 1369 1370The depth bounds test compares the depth value [eq]#z~a~# in the 1371depth/stencil attachment at each sample's framebuffer coordinates 1372[eq]#(x~f~,y~f~)# and <<primsrast-multisampling-coverage-mask, sample 1373index>> [eq]#i# against a set of _depth bounds_. 1374 1375The depth bounds are determined by two floating point values defining a 1376minimum (pname:minDepthBounds) and maximum (pname:maxDepthBounds) depth 1377value. 1378These values are either set by the 1379slink:VkPipelineDepthStencilStateCreateInfo structure during pipeline 1380creation, or dynamically by 1381ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1382flink:vkCmdSetDepthBoundsTestEnable and 1383endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1384flink:vkCmdSetDepthBounds. 1385 1386A given sample is considered within the depth bounds if [eq]#z~a~# is in the 1387range [eq]#[pname:minDepthBounds,pname:maxDepthBounds]#. 1388Samples with depth attachment values outside of the depth bounds will have 1389their coverage set to `0`. 1390 1391If the depth bounds test is disabled, or if there is no depth attachment, 1392the coverage mask is unmodified by this operation. 1393 1394ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1395[open,refpage='vkCmdSetDepthBoundsTestEnable',desc='Set depth bounds test enable dynamically for a command buffer',type='protos',alias='vkCmdSetDepthBoundsTestEnableEXT'] 1396-- 1397To <<pipelines-dynamic-state, dynamically enable or disable>> the depth 1398bounds test, call: 1399 1400ifdef::VK_VERSION_1_3[] 1401include::{generated}/api/protos/vkCmdSetDepthBoundsTestEnable.adoc[] 1402 1403ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 1404endif::VK_VERSION_1_3[] 1405 1406ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1407include::{generated}/api/protos/vkCmdSetDepthBoundsTestEnableEXT.adoc[] 1408endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1409 1410 * pname:commandBuffer is the command buffer into which the command will be 1411 recorded. 1412 * pname:depthBoundsTestEnable specifies if the depth bounds test is 1413 enabled. 1414 1415This command sets the depth bounds enable for subsequent drawing commands 1416ifdef::VK_EXT_shader_object[] 1417ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 1418ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 1419endif::VK_EXT_shader_object[] 1420ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1421when the graphics pipeline is created with 1422ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE set in 1423slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1424endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1425Otherwise, this state is specified by the 1426slink:VkPipelineDepthStencilStateCreateInfo::pname:depthBoundsTestEnable 1427value used to create the currently active pipeline. 1428 1429:refpage: vkCmdSetDepthBoundsTestEnable 1430 1431.Valid Usage 1432**** 1433include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 1434**** 1435 1436include::{generated}/validity/protos/vkCmdSetDepthBoundsTestEnable.adoc[] 1437-- 1438endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1439 1440[open,refpage='vkCmdSetDepthBounds',desc='Set depth bounds range dynamically for a command buffer',type='protos'] 1441-- 1442To <<pipelines-dynamic-state, dynamically set>> the depth bounds range, 1443call: 1444 1445include::{generated}/api/protos/vkCmdSetDepthBounds.adoc[] 1446 1447 * pname:commandBuffer is the command buffer into which the command will be 1448 recorded. 1449 * pname:minDepthBounds is the minimum depth bound. 1450 * pname:maxDepthBounds is the maximum depth bound. 1451 1452This command sets the depth bounds range for subsequent drawing commands 1453ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 1454when the graphics pipeline is created with 1455ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS set in 1456slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1457Otherwise, this state is specified by the 1458slink:VkPipelineDepthStencilStateCreateInfo::pname:minDepthBounds and 1459slink:VkPipelineDepthStencilStateCreateInfo::pname:maxDepthBounds values 1460used to create the currently active pipeline. 1461 1462.Valid Usage 1463**** 1464 * [[VUID-vkCmdSetDepthBounds-minDepthBounds-00600]] 1465ifdef::VK_EXT_depth_range_unrestricted[] 1466 If the `apiext:VK_EXT_depth_range_unrestricted` extension is not enabled 1467endif::VK_EXT_depth_range_unrestricted[] 1468 pname:minDepthBounds must: be between `0.0` and `1.0`, inclusive 1469 * [[VUID-vkCmdSetDepthBounds-maxDepthBounds-00601]] 1470ifdef::VK_EXT_depth_range_unrestricted[] 1471 If the `apiext:VK_EXT_depth_range_unrestricted` extension is not enabled 1472endif::VK_EXT_depth_range_unrestricted[] 1473 pname:maxDepthBounds must: be between `0.0` and `1.0`, inclusive 1474**** 1475 1476include::{generated}/validity/protos/vkCmdSetDepthBounds.adoc[] 1477-- 1478 1479 1480[[fragops-stencil]] 1481== Stencil Test 1482 1483The stencil test compares the stencil attachment value [eq]#s~a~# in the 1484depth/stencil attachment at each sample's framebuffer coordinates 1485[eq]#(x~f~,y~f~)# and <<primsrast-multisampling-coverage-mask, sample 1486index>> [eq]#i# against a _stencil reference value_. 1487 1488ifdef::VK_EXT_fragment_density_map[] 1489If the render pass has a fragment density map attachment and the fragment 1490covers multiple pixels, there is an implementation-dependent association of 1491coverage samples to stencil attachment samples within the fragment. 1492However, if all samples in the fragment are covered, and the stencil 1493attachment value is updated as a result of this test, all stencil attachment 1494samples will be updated. 1495endif::VK_EXT_fragment_density_map[] 1496 1497If the stencil test is not enabled, as specified by 1498ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1499flink:vkCmdSetStencilTestEnable or 1500endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1501slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable, or if 1502there is no stencil attachment, the coverage mask is unmodified by this 1503operation. 1504 1505The stencil test is controlled by one of two sets of stencil-related state, 1506the front stencil state and the back stencil state. 1507Stencil tests and writes use the back stencil state when processing 1508fragments generated by <<primsrast-polygons-basic,back-facing>> 1509<<primsrast-polygons,polygons>>, and the front stencil state when processing 1510fragments generated by <<primsrast-polygons-basic,front-facing polygons>> or 1511any other primitives. 1512 1513The comparison operation performed is determined by the elink:VkCompareOp 1514value set by 1515ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1516flink:vkCmdSetStencilOp::pname:compareOp, or by 1517endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1518slink:VkStencilOpState::pname:compareOp during pipeline creation. 1519 1520The compare mask [eq]#s~c~# and stencil reference value [eq]#s~r~# of the 1521front or the back stencil state set determine arguments of the comparison 1522operation. 1523[eq]#s~c~# is set by the slink:VkPipelineDepthStencilStateCreateInfo 1524structure during pipeline creation, or by the 1525flink:vkCmdSetStencilCompareMask command. 1526[eq]#s~r~# is set by slink:VkPipelineDepthStencilStateCreateInfo or by 1527flink:vkCmdSetStencilReference. 1528 1529[eq]#s~r~# and [eq]#s~a~# are each independently combined with [eq]#s~c~# 1530using a bitwise code:AND operation to create masked reference and attachment 1531values [eq]#s'~r~# and [eq]#s'~a~#. 1532[eq]#s'~r~# and [eq]#s'~a~# are used as the _reference_ and _test_ values, 1533respectively, in the operation specified by the elink:VkCompareOp. 1534 1535If the comparison evaluates to false, the coverage for the sample is set to 1536`0`. 1537 1538A new stencil value [eq]#s~g~# is generated according to a stencil operation 1539defined by elink:VkStencilOp parameters set by 1540ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1541flink:vkCmdSetStencilOp or 1542endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1543slink:VkPipelineDepthStencilStateCreateInfo. 1544If the stencil test fails, pname:failOp defines the stencil operation used. 1545If the stencil test passes however, the stencil op used is based on the 1546<<fragops-depth, depth test>> - if it passes, 1547slink:VkPipelineDepthStencilStateCreateInfo::pname:passOp is used, otherwise 1548slink:VkPipelineDepthStencilStateCreateInfo::pname:depthFailOp is used. 1549 1550The stencil attachment value [eq]#s~a~# is then updated with the generated 1551stencil value [eq]#s~g~# according to the write mask [eq]#s~w~# defined by 1552pname:writeMask in slink:VkPipelineDepthStencilStateCreateInfo::pname:front 1553and slink:VkPipelineDepthStencilStateCreateInfo::pname:back as: 1554 1555 {empty}:: [eq]#s~a~ = (s~a~ & ¬s~w~) | (s~g~ & s~w~)# 1556 1557ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1558[open,refpage='vkCmdSetStencilTestEnable',desc='Set stencil test enable dynamically for a command buffer',type='protos',alias='vkCmdSetStencilTestEnableEXT'] 1559-- 1560To <<pipelines-dynamic-state, dynamically enable or disable>> the stencil 1561test, call: 1562 1563ifdef::VK_VERSION_1_3[] 1564include::{generated}/api/protos/vkCmdSetStencilTestEnable.adoc[] 1565 1566ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 1567endif::VK_VERSION_1_3[] 1568 1569ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1570include::{generated}/api/protos/vkCmdSetStencilTestEnableEXT.adoc[] 1571endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1572 1573 * pname:commandBuffer is the command buffer into which the command will be 1574 recorded. 1575 * pname:stencilTestEnable specifies if the stencil test is enabled. 1576 1577This command sets the stencil test enable for subsequent drawing commands 1578ifdef::VK_EXT_shader_object[] 1579ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 1580ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 1581endif::VK_EXT_shader_object[] 1582ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1583when the graphics pipeline is created with 1584ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE set in 1585slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1586endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1587Otherwise, this state is specified by the 1588slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable value 1589used to create the currently active pipeline. 1590 1591:refpage: vkCmdSetStencilTestEnable 1592 1593.Valid Usage 1594**** 1595include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 1596**** 1597 1598include::{generated}/validity/protos/vkCmdSetStencilTestEnable.adoc[] 1599-- 1600 1601[open,refpage='vkCmdSetStencilOp',desc='Set stencil operation dynamically for a command buffer',type='protos',alias='vkCmdSetStencilOpEXT'] 1602-- 1603To <<pipelines-dynamic-state, dynamically set>> the stencil operation, call: 1604 1605ifdef::VK_VERSION_1_3[] 1606include::{generated}/api/protos/vkCmdSetStencilOp.adoc[] 1607 1608ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 1609endif::VK_VERSION_1_3[] 1610 1611ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1612include::{generated}/api/protos/vkCmdSetStencilOpEXT.adoc[] 1613endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1614 1615 * pname:commandBuffer is the command buffer into which the command will be 1616 recorded. 1617 * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying 1618 the set of stencil state for which to update the stencil operation. 1619 * pname:failOp is a elink:VkStencilOp value specifying the action 1620 performed on samples that fail the stencil test. 1621 * pname:passOp is a elink:VkStencilOp value specifying the action 1622 performed on samples that pass both the depth and stencil tests. 1623 * pname:depthFailOp is a elink:VkStencilOp value specifying the action 1624 performed on samples that pass the stencil test and fail the depth test. 1625 * pname:compareOp is a elink:VkCompareOp value specifying the comparison 1626 operator used in the stencil test. 1627 1628This command sets the stencil operation for subsequent drawing commands when 1629ifdef::VK_EXT_shader_object[] 1630ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 1631ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 1632endif::VK_EXT_shader_object[] 1633ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1634when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_OP 1635set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1636endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1637Otherwise, this state is specified by the corresponding 1638sname:VkPipelineDepthStencilStateCreateInfo::pname:failOp, pname:passOp, 1639pname:depthFailOp, and pname:compareOp values used to create the currently 1640active pipeline, for both front and back faces. 1641 1642:refpage: vkCmdSetStencilOp 1643 1644.Valid Usage 1645**** 1646include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 1647**** 1648 1649include::{generated}/validity/protos/vkCmdSetStencilOp.adoc[] 1650-- 1651endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1652 1653[open,refpage='VkStencilOpState',desc='Structure specifying stencil operation state',type='structs'] 1654-- 1655The sname:VkStencilOpState structure is defined as: 1656 1657include::{generated}/api/structs/VkStencilOpState.adoc[] 1658 1659 * pname:failOp is a elink:VkStencilOp value specifying the action 1660 performed on samples that fail the stencil test. 1661 * pname:passOp is a elink:VkStencilOp value specifying the action 1662 performed on samples that pass both the depth and stencil tests. 1663 * pname:depthFailOp is a elink:VkStencilOp value specifying the action 1664 performed on samples that pass the stencil test and fail the depth test. 1665 * pname:compareOp is a elink:VkCompareOp value specifying the comparison 1666 operator used in the stencil test. 1667 * pname:compareMask selects the bits of the unsigned integer stencil 1668 values participating in the stencil test. 1669 * pname:writeMask selects the bits of the unsigned integer stencil values 1670 updated by the stencil test in the stencil framebuffer attachment. 1671 * pname:reference is an integer stencil reference value that is used in 1672 the unsigned stencil comparison. 1673 1674include::{generated}/validity/structs/VkStencilOpState.adoc[] 1675-- 1676 1677[open,refpage='vkCmdSetStencilCompareMask',desc='Set stencil compare mask dynamically for a command buffer',type='protos'] 1678-- 1679To <<pipelines-dynamic-state, dynamically set>> the stencil compare mask, 1680call: 1681 1682include::{generated}/api/protos/vkCmdSetStencilCompareMask.adoc[] 1683 1684 * pname:commandBuffer is the command buffer into which the command will be 1685 recorded. 1686 * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying 1687 the set of stencil state for which to update the compare mask. 1688 * pname:compareMask is the new value to use as the stencil compare mask. 1689 1690This command sets the stencil compare mask for subsequent drawing commands 1691ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 1692when the graphics pipeline is created with 1693ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK set in 1694slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1695Otherwise, this state is specified by the 1696slink:VkStencilOpState::pname:compareMask value used to create the currently 1697active pipeline, for both front and back faces. 1698 1699include::{generated}/validity/protos/vkCmdSetStencilCompareMask.adoc[] 1700-- 1701 1702[open,refpage='VkStencilFaceFlagBits',desc='Bitmask specifying sets of stencil state for which to update the compare mask',type='enums'] 1703-- 1704ename:VkStencilFaceFlagBits values are: 1705 1706include::{generated}/api/enums/VkStencilFaceFlagBits.adoc[] 1707 1708 * ename:VK_STENCIL_FACE_FRONT_BIT specifies that only the front set of 1709 stencil state is updated. 1710 * ename:VK_STENCIL_FACE_BACK_BIT specifies that only the back set of 1711 stencil state is updated. 1712 * ename:VK_STENCIL_FACE_FRONT_AND_BACK is the combination of 1713 ename:VK_STENCIL_FACE_FRONT_BIT and ename:VK_STENCIL_FACE_BACK_BIT, and 1714 specifies that both sets of stencil state are updated. 1715 1716ifdef::VKSC_VERSION_1_0[] 1717ifdef::hidden[] 1718// tag::scremoved[] 1719 * elink:VkStencilFaceFlagBits (deprecated alias) 1720 ** etext:VK_STENCIL_FRONT_AND_BACK <<SCID-8>> 1721// end::scremoved[] 1722endif::hidden[] 1723endif::VKSC_VERSION_1_0[] 1724-- 1725 1726[open,refpage='VkStencilFaceFlags',desc='Bitmask of VkStencilFaceFlagBits',type='flags'] 1727-- 1728include::{generated}/api/flags/VkStencilFaceFlags.adoc[] 1729 1730tname:VkStencilFaceFlags is a bitmask type for setting a mask of zero or 1731more elink:VkStencilFaceFlagBits. 1732-- 1733 1734[open,refpage='vkCmdSetStencilWriteMask',desc='Set stencil write mask dynamically for a command buffer',type='protos'] 1735-- 1736To <<pipelines-dynamic-state, dynamically set>> the stencil write mask, 1737call: 1738 1739include::{generated}/api/protos/vkCmdSetStencilWriteMask.adoc[] 1740 1741 * pname:commandBuffer is the command buffer into which the command will be 1742 recorded. 1743 * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying 1744 the set of stencil state for which to update the write mask, as 1745 described above for flink:vkCmdSetStencilCompareMask. 1746 * pname:writeMask is the new value to use as the stencil write mask. 1747 1748This command sets the stencil write mask for subsequent drawing commands 1749ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 1750when the graphics pipeline is created with 1751ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK set in 1752slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1753Otherwise, this state is specified by the pname:writeMask value used to 1754create the currently active pipeline, for both 1755slink:VkPipelineDepthStencilStateCreateInfo::pname:front and 1756slink:VkPipelineDepthStencilStateCreateInfo::pname:back faces. 1757 1758include::{generated}/validity/protos/vkCmdSetStencilWriteMask.adoc[] 1759-- 1760 1761[open,refpage='vkCmdSetStencilReference',desc='Set stencil reference value dynamically for a command buffer',type='protos'] 1762-- 1763To <<pipelines-dynamic-state, dynamically set>> the stencil reference value, 1764call: 1765 1766include::{generated}/api/protos/vkCmdSetStencilReference.adoc[] 1767 1768 * pname:commandBuffer is the command buffer into which the command will be 1769 recorded. 1770 * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying 1771 the set of stencil state for which to update the reference value, as 1772 described above for flink:vkCmdSetStencilCompareMask. 1773 * pname:reference is the new value to use as the stencil reference value. 1774 1775This command sets the stencil reference value for subsequent drawing 1776commands 1777ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 1778when the graphics pipeline is created with 1779ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE set in 1780slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1781Otherwise, this state is specified by the 1782slink:VkPipelineDepthStencilStateCreateInfo::pname:reference value used to 1783create the currently active pipeline, for both front and back faces. 1784 1785include::{generated}/validity/protos/vkCmdSetStencilReference.adoc[] 1786-- 1787 1788[open,refpage='VkStencilOp',desc='Stencil comparison function',type='enums'] 1789-- 1790Possible values of the pname:failOp, pname:passOp, and pname:depthFailOp 1791members of slink:VkStencilOpState, specifying what happens to the stored 1792stencil value if this or certain subsequent tests fail or pass, are: 1793 1794include::{generated}/api/enums/VkStencilOp.adoc[] 1795 1796 * ename:VK_STENCIL_OP_KEEP keeps the current value. 1797 * ename:VK_STENCIL_OP_ZERO sets the value to 0. 1798 * ename:VK_STENCIL_OP_REPLACE sets the value to pname:reference. 1799 * ename:VK_STENCIL_OP_INCREMENT_AND_CLAMP increments the current value and 1800 clamps to the maximum representable unsigned value. 1801 * ename:VK_STENCIL_OP_DECREMENT_AND_CLAMP decrements the current value and 1802 clamps to 0. 1803 * ename:VK_STENCIL_OP_INVERT bitwise-inverts the current value. 1804 * ename:VK_STENCIL_OP_INCREMENT_AND_WRAP increments the current value and 1805 wraps to 0 when the maximum value would have been exceeded. 1806 * ename:VK_STENCIL_OP_DECREMENT_AND_WRAP decrements the current value and 1807 wraps to the maximum possible value when the value would go below 0. 1808 1809For purposes of increment and decrement, the stencil bits are considered as 1810an unsigned integer. 1811-- 1812 1813 1814[[fragops-depth]] 1815== Depth Test 1816 1817The depth test compares the depth value [eq]#z~a~# in the depth/stencil 1818attachment at each sample's framebuffer coordinates [eq]#(x~f~,y~f~)# and 1819<<primsrast-multisampling-coverage-mask, sample index>> [eq]#i# against the 1820sample's depth value [eq]#z~f~#. 1821If there is no depth attachment then the depth test is skipped. 1822 1823ifdef::VK_EXT_fragment_density_map[] 1824If the render pass has a fragment density map attachment and the fragment 1825covers multiple pixels, there is an implementation-dependent association of 1826rasterization samples to depth attachment samples within the fragment. 1827However, if all samples in the fragment are covered, and the depth 1828attachment value is updated as a result of this test, all depth attachment 1829samples will be updated. 1830endif::VK_EXT_fragment_density_map[] 1831 1832The depth test occurs in three stages, as detailed in the following 1833sections. 1834 1835 1836=== Depth Clamping and Range Adjustment 1837 1838If slink:VkPipelineRasterizationStateCreateInfo::pname:depthClampEnable is 1839enabled, [eq]#z~f~# is clamped to [eq]#[z~min~, z~max~]#, where [eq]#z~min~ 1840= min(n,f)#, [eq]#z~max~ = max(n,f)]#, and [eq]#n# and [eq]#f# are the 1841pname:minDepth and pname:maxDepth depth range values of the viewport used by 1842this fragment, respectively. 1843 1844ifdef::VK_EXT_depth_clamp_zero_one[] 1845If 1846slink:VkPhysicalDeviceDepthClampZeroOneFeaturesEXT::pname:depthClampZeroOne 1847is enabled: 1848 1849ifdef::VK_EXT_depth_range_unrestricted[] 1850 * If the depth attachment has a floating-point format and 1851 apiext:VK_EXT_depth_range_unrestricted is enabled then [eq]#z~f~# is 1852 unchanged. 1853 * Otherwise, [eq]#z~f~# is clamped to the range [eq]#[0, 1]#. 1854endif::VK_EXT_depth_range_unrestricted[] 1855ifndef::VK_EXT_depth_range_unrestricted[] 1856 * [eq]#z~f~# is clamped to the range [eq]#[0, 1]#. 1857endif::VK_EXT_depth_range_unrestricted[] 1858 1859Otherwise: 1860endif::VK_EXT_depth_clamp_zero_one[] 1861ifndef::VK_EXT_depth_clamp_zero_one[] 1862Following depth clamping: 1863endif::VK_EXT_depth_clamp_zero_one[] 1864 1865 * If [eq]#z~f~# is not in the range [eq]#[z~min~, z~max~]#, then 1866 [eq]#z~f~# is undefined: following this step. 1867ifdef::VK_EXT_depth_range_unrestricted[] 1868 * If the depth attachment has a fixed-point format and [eq]#z~f~# is not 1869 in the range [eq]#[0, 1]#, then [eq]#z~f~# is undefined: following this 1870 step. 1871endif::VK_EXT_depth_range_unrestricted[] 1872 1873 1874[[fragops-depth-comparison]] 1875=== Depth Comparison 1876 1877If the depth test is not enabled, as specified by 1878ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1879flink:vkCmdSetDepthTestEnable or 1880endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1881slink:VkPipelineDepthStencilStateCreateInfo::pname:depthTestEnable, then 1882this step is skipped. 1883 1884The comparison operation performed is determined by the elink:VkCompareOp 1885value set by 1886ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1887flink:vkCmdSetDepthCompareOp, or by 1888endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1889slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp during 1890pipeline creation. 1891[eq]#z~f~# and [eq]#z~a~# are used as the _reference_ and _test_ values, 1892respectively, in the operation specified by the elink:VkCompareOp. 1893 1894If the comparison evaluates to false, the coverage for the sample is set to 1895`0`. 1896 1897 1898[[fragops-depth-write]] 1899=== Depth Attachment Writes 1900 1901If depth writes are enabled, as specified by 1902ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1903flink:vkCmdSetDepthWriteEnable or 1904endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1905slink:VkPipelineDepthStencilStateCreateInfo::pname:depthWriteEnable, and the 1906comparison evaluated to true, the depth attachment value [eq]#z~a~# is set 1907to the sample's depth value [eq]#z~f~#. 1908If there is no depth attachment, no value is written. 1909 1910ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1911[open,refpage='vkCmdSetDepthTestEnable',desc='Set depth test enable dynamically for a command buffer',type='protos',alias='vkCmdSetDepthTestEnableEXT'] 1912-- 1913To <<pipelines-dynamic-state, dynamically enable or disable>> the depth 1914test, call: 1915 1916ifdef::VK_VERSION_1_3[] 1917include::{generated}/api/protos/vkCmdSetDepthTestEnable.adoc[] 1918 1919ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 1920endif::VK_VERSION_1_3[] 1921 1922ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1923include::{generated}/api/protos/vkCmdSetDepthTestEnableEXT.adoc[] 1924endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1925 1926 * pname:commandBuffer is the command buffer into which the command will be 1927 recorded. 1928 * pname:depthTestEnable specifies if the depth test is enabled. 1929 1930This command sets the depth test enable for subsequent drawing commands 1931ifdef::VK_EXT_shader_object[] 1932ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 1933ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 1934endif::VK_EXT_shader_object[] 1935ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1936when the graphics pipeline is created with 1937ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE set in 1938slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1939endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1940Otherwise, this state is specified by the 1941slink:VkPipelineDepthStencilStateCreateInfo::pname:depthTestEnable value 1942used to create the currently active pipeline. 1943 1944:refpage: vkCmdSetDepthTestEnable 1945 1946.Valid Usage 1947**** 1948include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 1949**** 1950 1951include::{generated}/validity/protos/vkCmdSetDepthTestEnable.adoc[] 1952-- 1953 1954[open,refpage='vkCmdSetDepthCompareOp',desc='Set depth comparison operator dynamically for a command buffer',type='protos',alias='vkCmdSetDepthCompareOpEXT'] 1955-- 1956To <<pipelines-dynamic-state, dynamically set>> the depth compare operator, 1957call: 1958 1959ifdef::VK_VERSION_1_3[] 1960include::{generated}/api/protos/vkCmdSetDepthCompareOp.adoc[] 1961 1962ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 1963endif::VK_VERSION_1_3[] 1964 1965ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1966include::{generated}/api/protos/vkCmdSetDepthCompareOpEXT.adoc[] 1967endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1968 1969 * pname:commandBuffer is the command buffer into which the command will be 1970 recorded. 1971 * pname:depthCompareOp is a elink:VkCompareOp value specifying the 1972 comparison operator used for the <<fragops-depth-comparison, Depth 1973 Comparison>> step of the <<fragops-depth,depth test>>. 1974 1975This command sets the depth comparison operator for subsequent drawing 1976commands 1977ifdef::VK_EXT_shader_object[] 1978ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 1979ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 1980endif::VK_EXT_shader_object[] 1981ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1982when the graphics pipeline is created with 1983ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP set in 1984slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1985endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1986Otherwise, this state is specified by the 1987slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp value used 1988to create the currently active pipeline. 1989 1990:refpage: vkCmdSetDepthCompareOp 1991 1992.Valid Usage 1993**** 1994include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 1995**** 1996 1997 1998include::{generated}/validity/protos/vkCmdSetDepthCompareOp.adoc[] 1999-- 2000 2001[open,refpage='vkCmdSetDepthWriteEnable',desc='Set depth write enable dynamically for a command buffer',type='protos',alias='vkCmdSetDepthWriteEnableEXT'] 2002-- 2003To <<pipelines-dynamic-state, dynamically set>> the depth write enable, 2004call: 2005 2006ifdef::VK_VERSION_1_3[] 2007include::{generated}/api/protos/vkCmdSetDepthWriteEnable.adoc[] 2008 2009ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 2010endif::VK_VERSION_1_3[] 2011 2012ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 2013include::{generated}/api/protos/vkCmdSetDepthWriteEnableEXT.adoc[] 2014endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 2015 2016 * pname:commandBuffer is the command buffer into which the command will be 2017 recorded. 2018 * pname:depthWriteEnable specifies if depth writes are enabled. 2019 2020This command sets the depth write enable for subsequent drawing commands 2021ifdef::VK_EXT_shader_object[] 2022ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 2023ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 2024endif::VK_EXT_shader_object[] 2025ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 2026when the graphics pipeline is created with 2027ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE set in 2028slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2029endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 2030Otherwise, this state is specified by the 2031slink:VkPipelineDepthStencilStateCreateInfo::pname:depthWriteEnable value 2032used to create the currently active pipeline. 2033 2034:refpage: vkCmdSetDepthWriteEnable 2035 2036.Valid Usage 2037**** 2038include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 2039**** 2040 2041include::{generated}/validity/protos/vkCmdSetDepthWriteEnable.adoc[] 2042-- 2043endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 2044 2045 2046ifdef::VK_NV_representative_fragment_test[] 2047[[fragops-rep-frag-test]] 2048== Representative Fragment Test 2049 2050The representative fragment test allows implementations to reduce the amount 2051of rasterization and fragment processing work performed for each point, 2052line, or triangle primitive. 2053For any primitive that produces one or more fragments that pass all prior 2054early fragment tests, the implementation may: choose one or more 2055"`representative`" fragments for processing and discard all other fragments. 2056For draw calls rendering multiple points, lines, or triangles arranged in 2057lists, strips, or fans, the representative fragment test is performed 2058independently for each of those primitives. 2059The set of fragments discarded by the representative fragment test is 2060implementation-dependent. 2061In some cases, the representative fragment test may not discard any 2062fragments for a given primitive. 2063 2064[open,refpage='VkPipelineRepresentativeFragmentTestStateCreateInfoNV',desc='Structure specifying representative fragment test',type='structs'] 2065-- 2066If the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo includes a 2067sname:VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure, then 2068that structure includes parameters controlling the representative fragment 2069test. 2070 2071The sname:VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure is 2072defined as: 2073 2074include::{generated}/api/structs/VkPipelineRepresentativeFragmentTestStateCreateInfoNV.adoc[] 2075 2076 * pname:sType is a elink:VkStructureType value identifying this structure. 2077 * pname:pNext is `NULL` or a pointer to a structure extending this 2078 structure. 2079 * pname:representativeFragmentTestEnable controls whether the 2080 representative fragment test is enabled. 2081 2082If this structure is not included in the pname:pNext chain, 2083pname:representativeFragmentTestEnable is considered to be ename:VK_FALSE, 2084and the representative fragment test is disabled. 2085 2086If the active fragment shader does not specify the code:EarlyFragmentTests 2087execution mode, the representative fragment shader test has no effect, even 2088if enabled. 2089 2090include::{generated}/validity/structs/VkPipelineRepresentativeFragmentTestStateCreateInfoNV.adoc[] 2091-- 2092 2093ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2094 2095[open,refpage='vkCmdSetRepresentativeFragmentTestEnableNV',desc='Specify the representative fragment test enable dynamically for a command buffer',type='protos'] 2096-- 2097To <<pipelines-dynamic-state, dynamically set>> the 2098pname:representativeFragmentTestEnable state, call: 2099 2100include::{generated}/api/protos/vkCmdSetRepresentativeFragmentTestEnableNV.adoc[] 2101 2102 * pname:commandBuffer is the command buffer into which the command will be 2103 recorded. 2104 * pname:representativeFragmentTestEnable specifies the 2105 pname:representativeFragmentTestEnable state. 2106 2107This command sets the pname:representativeFragmentTestEnable state for 2108subsequent drawing commands 2109ifdef::VK_EXT_shader_object[] 2110ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2111ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2112endif::VK_EXT_shader_object[] 2113ifdef::VK_EXT_extended_dynamic_state3[] 2114when the graphics pipeline is created with 2115ename:VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV set in 2116slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2117endif::VK_EXT_extended_dynamic_state3[] 2118Otherwise, this state is specified by the 2119slink:VkPipelineRepresentativeFragmentTestStateCreateInfoNV::pname:representativeFragmentTestEnable 2120value used to create the currently active pipeline. 2121 2122:refpage: vkCmdSetRepresentativeFragmentTestEnableNV 2123:requiredfeature: extendedDynamicState3RepresentativeFragmentTestEnable 2124 2125.Valid Usage 2126**** 2127include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2128**** 2129 2130include::{generated}/validity/protos/vkCmdSetRepresentativeFragmentTestEnableNV.adoc[] 2131-- 2132 2133endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2134 2135endif::VK_NV_representative_fragment_test[] 2136 2137 2138[[fragops-samplecount]] 2139== Sample Counting 2140 2141Occlusion queries use query pool entries to track the number of samples that 2142pass all the per-fragment tests. 2143The mechanism of collecting an occlusion query value is described in 2144<<queries-occlusion,Occlusion Queries>>. 2145 2146The occlusion query sample counter increments by one for each sample with a 2147coverage value of 1 in each fragment that survives all the per-fragment 2148tests, including scissor, 2149ifdef::VK_NV_scissor_exclusive[] 2150exclusive scissor, 2151endif::VK_NV_scissor_exclusive[] 2152sample mask, alpha to coverage, stencil, and depth tests. 2153 2154 2155ifdef::VK_NV_fragment_coverage_to_color[] 2156[[fragops-coverage-to-color]] 2157== Fragment Coverage to Color 2158 2159[open,refpage='VkPipelineCoverageToColorStateCreateInfoNV',desc='Structure specifying whether fragment coverage replaces a color',type='structs'] 2160-- 2161The sname:VkPipelineCoverageToColorStateCreateInfoNV structure is defined 2162as: 2163 2164include::{generated}/api/structs/VkPipelineCoverageToColorStateCreateInfoNV.adoc[] 2165 2166 * pname:sType is a elink:VkStructureType value identifying this structure. 2167 * pname:pNext is `NULL` or a pointer to a structure extending this 2168 structure. 2169 * pname:flags is reserved for future use. 2170 * pname:coverageToColorEnable controls whether the fragment coverage value 2171 replaces a fragment color output. 2172 * pname:coverageToColorLocation controls which fragment shader color 2173 output value is replaced. 2174 2175If the pname:pNext chain of slink:VkPipelineMultisampleStateCreateInfo 2176includes a sname:VkPipelineCoverageToColorStateCreateInfoNV structure, then 2177that structure controls whether the fragment coverage is substituted for a 2178fragment color output and, if so, which output is replaced. 2179 2180If pname:coverageToColorEnable is ename:VK_TRUE, the 2181<<primsrast-multisampling-coverage-mask, coverage mask>> replaces the first 2182component of the color value corresponding to the fragment shader output 2183location with code:Location equal to pname:coverageToColorLocation and 2184code:Index equal to zero. 2185If the color attachment format has fewer bits than the coverage mask, the 2186low bits of the sample coverage mask are taken without any clamping. 2187If the color attachment format has more bits than the coverage mask, the 2188high bits of the sample coverage mask are filled with zeros. 2189 2190If pname:coverageToColorEnable is ename:VK_FALSE, these operations are 2191skipped. 2192If this structure is not included in the pname:pNext chain, it is as if 2193pname:coverageToColorEnable is ename:VK_FALSE. 2194 2195.Valid Usage 2196**** 2197 * [[VUID-VkPipelineCoverageToColorStateCreateInfoNV-coverageToColorEnable-01404]] 2198 If pname:coverageToColorEnable is ename:VK_TRUE, then the render pass 2199 subpass indicated by 2200 slink:VkGraphicsPipelineCreateInfo::pname:renderPass and 2201 slink:VkGraphicsPipelineCreateInfo::pname:subpass must: have a color 2202 attachment at the location selected by pname:coverageToColorLocation, 2203 with a elink:VkFormat of ename:VK_FORMAT_R8_UINT, 2204 ename:VK_FORMAT_R8_SINT, ename:VK_FORMAT_R16_UINT, 2205 ename:VK_FORMAT_R16_SINT, ename:VK_FORMAT_R32_UINT, or 2206 ename:VK_FORMAT_R32_SINT 2207**** 2208 2209include::{generated}/validity/structs/VkPipelineCoverageToColorStateCreateInfoNV.adoc[] 2210-- 2211 2212[open,refpage='VkPipelineCoverageToColorStateCreateFlagsNV',desc='Reserved for future use',type='flags'] 2213-- 2214include::{generated}/api/flags/VkPipelineCoverageToColorStateCreateFlagsNV.adoc[] 2215 2216tname:VkPipelineCoverageToColorStateCreateFlagsNV is a bitmask type for 2217setting a mask, but is currently reserved for future use. 2218-- 2219 2220ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2221 2222[open,refpage='vkCmdSetCoverageToColorEnableNV',desc='Specify the coverage to color enable state dynamically for a command buffer',type='protos'] 2223-- 2224To <<pipelines-dynamic-state, dynamically set>> the 2225pname:coverageToColorEnable state, call: 2226 2227include::{generated}/api/protos/vkCmdSetCoverageToColorEnableNV.adoc[] 2228 2229 * pname:commandBuffer is the command buffer into which the command will be 2230 recorded. 2231 * pname:coverageToColorEnable specifies the pname:coverageToColorEnable 2232 state. 2233 2234This command sets the pname:coverageToColorEnable state for subsequent 2235drawing commands 2236ifdef::VK_EXT_shader_object[] 2237ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2238ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2239endif::VK_EXT_shader_object[] 2240ifdef::VK_EXT_extended_dynamic_state3[] 2241when the graphics pipeline is created with 2242ename:VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV set in 2243slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2244endif::VK_EXT_extended_dynamic_state3[] 2245Otherwise, this state is specified by the 2246slink:VkPipelineCoverageToColorStateCreateInfoNV::pname:coverageToColorEnable 2247value used to create the currently active pipeline. 2248 2249:refpage: vkCmdSetCoverageToColorEnableNV 2250:requiredfeature: extendedDynamicState3CoverageToColorEnable 2251 2252.Valid Usage 2253**** 2254include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2255**** 2256 2257include::{generated}/validity/protos/vkCmdSetCoverageToColorEnableNV.adoc[] 2258-- 2259 2260[open,refpage='vkCmdSetCoverageToColorLocationNV',desc='Specify the coverage to color location dynamically for a command buffer',type='protos'] 2261-- 2262To <<pipelines-dynamic-state, dynamically set>> the 2263pname:coverageToColorLocation state, call: 2264 2265include::{generated}/api/protos/vkCmdSetCoverageToColorLocationNV.adoc[] 2266 2267 * pname:commandBuffer is the command buffer into which the command will be 2268 recorded. 2269 * pname:coverageToColorLocation specifies the 2270 pname:coverageToColorLocation state. 2271 2272This command sets the pname:coverageToColorLocation state for subsequent 2273drawing commands 2274ifdef::VK_EXT_shader_object[] 2275ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2276ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2277endif::VK_EXT_shader_object[] 2278ifdef::VK_EXT_extended_dynamic_state3[] 2279when the graphics pipeline is created with 2280ename:VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV set in 2281slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2282endif::VK_EXT_extended_dynamic_state3[] 2283Otherwise, this state is specified by the 2284slink:VkPipelineCoverageToColorStateCreateInfoNV::pname:coverageToColorLocation 2285value used to create the currently active pipeline. 2286 2287:refpage: vkCmdSetCoverageToColorLocationNV 2288:requiredfeature: extendedDynamicState3CoverageToColorLocation 2289 2290.Valid Usage 2291**** 2292include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2293**** 2294 2295include::{generated}/validity/protos/vkCmdSetCoverageToColorLocationNV.adoc[] 2296-- 2297 2298endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2299 2300endif::VK_NV_fragment_coverage_to_color[] 2301 2302 2303[[fragops-coverage-reduction]] 2304== Coverage Reduction 2305 2306Coverage reduction takes the coverage information for a fragment and 2307converts that to a boolean coverage value for each color sample in each 2308pixel covered by the fragment. 2309 2310 2311=== Pixel Coverage 2312 2313Coverage for each pixel is first extracted from the total fragment coverage 2314mask. 2315This consists of pname:rasterizationSamples unique coverage samples for each 2316pixel in the fragment area, each with a unique 2317<<primsrast-multisampling-coverage-mask, sample index>>. 2318If the fragment only contains a single pixel, coverage for the pixel is 2319equivalent to the fragment coverage. 2320 2321ifdef::VK_EXT_fragment_density_map[] 2322If the render pass has a fragment density map attachment and the fragment 2323covers multiple pixels, pixel coverage is generated in an 2324implementation-dependent manner. 2325If all samples in the fragment are covered, all samples will be covered in 2326each pixel coverage. 2327endif::VK_EXT_fragment_density_map[] 2328 2329ifdef::VK_NV_shading_rate_image[] 2330If a <<primsrast-shading-rate-image,shading rate image>> is used, and the 2331fragment covers multiple pixels, each pixel's coverage consists of the 2332coverage samples corresponding to that pixel, and each sample retains its 2333unique <<primsrast-multisampling-coverage-mask, sample index [eq]#i#>>. 2334endif::VK_NV_shading_rate_image[] 2335 2336ifdef::VK_KHR_fragment_shading_rate[] 2337If the <<primsrast-fragment-shading-rate, fragment shading rate>> is set, 2338and the fragment covers multiple pixels, each pixel's coverage consists of 2339the coverage samples with a <<primsrast-multisampling-coverage-mask-vrfs, 2340pixel index>> matching that pixel, and each sample retains its unique 2341<<primsrast-multisampling-coverage-mask, sample index [eq]#i#>>. 2342endif::VK_KHR_fragment_shading_rate[] 2343 2344 2345=== Color Sample Coverage 2346 2347Once pixel coverage is determined, coverage for each individual color sample 2348corresponding to that pixel is determined. 2349 2350ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[If the] 2351ifndef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[The] 2352number of pname:rasterizationSamples is identical to the number of samples 2353in the color 2354ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[attachments, a] 2355ifndef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[attachments. A] 2356color sample is covered if the pixel coverage sample with the same 2357<<primsrast-multisampling-coverage-mask, sample index>> [eq]#i# is covered. 2358 2359ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[] 2360Otherwise, the coverage for each color sample is computed from the pixel 2361coverage as follows. 2362endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[] 2363 2364ifdef::VK_AMD_mixed_attachment_samples[] 2365If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, for 2366color samples present in the color attachments, a color sample is covered if 2367the pixel coverage sample with the same 2368<<primsrast-multisampling-coverage-mask, sample index>> [eq]#i# is covered; 2369additional pixel coverage samples are discarded. 2370endif::VK_AMD_mixed_attachment_samples[] 2371 2372ifdef::VK_EXT_multisampled_render_to_single_sampled[] 2373If the pname:pNext chain of slink:VkSubpassDescription2 2374ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[or slink:VkRenderingInfo] 2375includes a slink:VkMultisampledRenderToSingleSampledInfoEXT structure with 2376the pname:multisampledRenderToSingleSampledEnable field equal to 2377ename:VK_TRUE, sample coverage is calculated as if the attachment has 2378slink:VkMultisampledRenderToSingleSampledInfoEXT::pname:rasterizationSamples 2379samples. 2380endif::VK_EXT_multisampled_render_to_single_sampled[] 2381 2382ifdef::VK_NV_framebuffer_mixed_samples[] 2383 2384ifndef::VK_NV_coverage_reduction_mode[] 2385When the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, if 2386the pipeline's 2387slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples is 2388greater than the slink:VkAttachmentDescription::pname:samples of the color 2389attachments in the subpass, each color sample will be associated with an 2390implementation-dependent subset of samples in the pixel coverage. 2391If any of those associated samples are covered, the color sample is covered. 2392endif::VK_NV_coverage_reduction_mode[] 2393 2394ifdef::VK_NV_coverage_reduction_mode[] 2395When the `apiext:VK_NV_coverage_reduction_mode` extension is enabled, the 2396pipeline state controlling coverage reduction is specified through the 2397members of the sname:VkPipelineCoverageReductionStateCreateInfoNV structure. 2398 2399[open,refpage='VkPipelineCoverageReductionStateCreateInfoNV',desc='Structure specifying parameters controlling coverage reduction',type='structs'] 2400-- 2401The sname:VkPipelineCoverageReductionStateCreateInfoNV structure is defined 2402as: 2403 2404include::{generated}/api/structs/VkPipelineCoverageReductionStateCreateInfoNV.adoc[] 2405 2406 * pname:sType is a elink:VkStructureType value identifying this structure. 2407 * pname:pNext is `NULL` or a pointer to a structure extending this 2408 structure. 2409 * pname:flags is reserved for future use. 2410 * pname:coverageReductionMode is a elink:VkCoverageReductionModeNV value 2411 controlling how color sample coverage is generated from pixel coverage. 2412 2413If this structure is not included in the pname:pNext chain, or if the 2414extension is not enabled, the default coverage reduction mode is inferred as 2415follows: 2416 2417 * If the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, 2418 then it is as if the pname:coverageReductionMode is 2419 ename:VK_COVERAGE_REDUCTION_MODE_MERGE_NV. 2420 * If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, 2421 then it is as if the pname:coverageReductionMode is 2422 ename:VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV. 2423 * If both `apiext:VK_NV_framebuffer_mixed_samples` and 2424 `apiext:VK_AMD_mixed_attachment_samples` are enabled, then the default 2425 coverage reduction mode is implementation-dependent. 2426 2427include::{generated}/validity/structs/VkPipelineCoverageReductionStateCreateInfoNV.adoc[] 2428-- 2429 2430[open,refpage='VkPipelineCoverageReductionStateCreateFlagsNV',desc='Reserved for future use',type='flags'] 2431-- 2432include::{generated}/api/flags/VkPipelineCoverageReductionStateCreateFlagsNV.adoc[] 2433 2434tname:VkPipelineCoverageReductionStateCreateFlagsNV is a bitmask type for 2435setting a mask, but is currently reserved for future use. 2436-- 2437 2438[open,refpage='VkCoverageReductionModeNV',desc='Specify the coverage reduction mode',type='enums'] 2439-- 2440Possible values of 2441slink:VkPipelineCoverageReductionStateCreateInfoNV::pname:coverageReductionMode, 2442specifying how color sample coverage is generated from pixel coverage, are: 2443 2444include::{generated}/api/enums/VkCoverageReductionModeNV.adoc[] 2445 2446 * ename:VK_COVERAGE_REDUCTION_MODE_MERGE_NV specifies that each color 2447 sample will be associated with an implementation-dependent subset of 2448 samples in the pixel coverage. 2449 If any of those associated samples are covered, the color sample is 2450 covered. 2451 * ename:VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV specifies that for color 2452 samples present in the color attachments, a color sample is covered if 2453 the pixel coverage sample with the same 2454 <<primsrast-multisampling-coverage-mask, sample index>> [eq]#i# is 2455 covered; other pixel coverage samples are discarded. 2456-- 2457 2458ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2459 2460[open,refpage='vkCmdSetCoverageReductionModeNV',desc='Specify the coverage reduction mode dynamically for a command buffer',type='protos'] 2461-- 2462To <<pipelines-dynamic-state, dynamically set>> the 2463pname:coverageReductionMode state, call: 2464 2465include::{generated}/api/protos/vkCmdSetCoverageReductionModeNV.adoc[] 2466 2467 * pname:commandBuffer is the command buffer into which the command will be 2468 recorded. 2469 * pname:coverageReductionMode specifies the pname:coverageReductionMode 2470 state. 2471 2472This command sets the pname:coverageReductionMode state for subsequent 2473drawing commands 2474ifdef::VK_EXT_shader_object[] 2475ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2476ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2477endif::VK_EXT_shader_object[] 2478ifdef::VK_EXT_extended_dynamic_state3[] 2479when the graphics pipeline is created with 2480ename:VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV set in 2481slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2482endif::VK_EXT_extended_dynamic_state3[] 2483Otherwise, this state is specified by the 2484slink:VkPipelineCoverageReductionStateCreateInfoNV::pname:coverageReductionMode 2485value used to create the currently active pipeline. 2486 2487:refpage: vkCmdSetCoverageReductionModeNV 2488:requiredfeature: extendedDynamicState3CoverageReductionMode 2489 2490.Valid Usage 2491**** 2492include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2493**** 2494 2495include::{generated}/validity/protos/vkCmdSetCoverageReductionModeNV.adoc[] 2496-- 2497 2498endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2499 2500[open,refpage='vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV',desc='Query supported sample count combinations',type='protos'] 2501-- 2502To query the set of mixed sample combinations of coverage reduction mode, 2503rasterization samples and color, depth, stencil attachment sample counts 2504that are supported by a physical device, call: 2505 2506include::{generated}/api/protos/vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV.adoc[] 2507 2508 * pname:physicalDevice is the physical device from which to query the set 2509 of combinations. 2510 * pname:pCombinationCount is a pointer to an integer related to the number 2511 of combinations available or queried, as described below. 2512 * pname:pCombinations is either `NULL` or a pointer to an array of 2513 slink:VkFramebufferMixedSamplesCombinationNV values, indicating the 2514 supported combinations of coverage reduction mode, rasterization 2515 samples, and color, depth, stencil attachment sample counts. 2516 2517If pname:pCombinations is `NULL`, then the number of supported combinations 2518for the given pname:physicalDevice is returned in pname:pCombinationCount. 2519Otherwise, pname:pCombinationCount must: point to a variable set by the user 2520to the number of elements in the pname:pCombinations array, and on return 2521the variable is overwritten with the number of values actually written to 2522pname:pCombinations. 2523If the value of pname:pCombinationCount is less than the number of 2524combinations supported for the given pname:physicalDevice, at most 2525pname:pCombinationCount values will be written to pname:pCombinations, and 2526ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to 2527indicate that not all the supported values were returned. 2528 2529include::{generated}/validity/protos/vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV.adoc[] 2530-- 2531 2532[open,refpage='VkFramebufferMixedSamplesCombinationNV',desc='Structure specifying a supported sample count combination',type='structs'] 2533-- 2534The sname:VkFramebufferMixedSamplesCombinationNV structure is defined as: 2535 2536include::{generated}/api/structs/VkFramebufferMixedSamplesCombinationNV.adoc[] 2537 2538 * pname:sType is a elink:VkStructureType value identifying this structure. 2539 * pname:pNext is `NULL` or a pointer to a structure extending this 2540 structure. 2541 * pname:coverageReductionMode is a elink:VkCoverageReductionModeNV value 2542 specifying the coverage reduction mode. 2543 * pname:rasterizationSamples is a elink:VkSampleCountFlagBits specifying 2544 the number of rasterization samples in the supported combination. 2545 * pname:depthStencilSamples specifies the number of samples in the depth 2546 stencil attachment in the supported combination. 2547 A value of 0 indicates the combination does not have a depth stencil 2548 attachment. 2549 * pname:colorSamples specifies the number of color samples in a color 2550 attachment in the supported combination. 2551 A value of 0 indicates the combination does not have a color attachment. 2552 2553include::{generated}/validity/structs/VkFramebufferMixedSamplesCombinationNV.adoc[] 2554-- 2555endif::VK_NV_coverage_reduction_mode[] 2556 2557 2558[[fragops-coverage-modulation]] 2559=== Coverage Modulation 2560 2561[open,refpage='VkPipelineCoverageModulationStateCreateInfoNV',desc='Structure specifying parameters controlling coverage modulation',type='structs'] 2562-- 2563As part of coverage reduction, fragment color values can: also be modulated 2564(multiplied) by a value that is a function of fraction of covered 2565rasterization samples associated with that color sample. 2566 2567Pipeline state controlling coverage modulation is specified through the 2568members of the sname:VkPipelineCoverageModulationStateCreateInfoNV 2569structure. 2570 2571The sname:VkPipelineCoverageModulationStateCreateInfoNV structure is defined 2572as: 2573 2574include::{generated}/api/structs/VkPipelineCoverageModulationStateCreateInfoNV.adoc[] 2575 2576 * pname:sType is a elink:VkStructureType value identifying this structure. 2577 * pname:pNext is `NULL` or a pointer to a structure extending this 2578 structure. 2579 * pname:flags is reserved for future use. 2580 * pname:coverageModulationMode is a elink:VkCoverageModulationModeNV value 2581 controlling which color components are modulated. 2582 * pname:coverageModulationTableEnable controls whether the modulation 2583 factor is looked up from a table in pname:pCoverageModulationTable. 2584 * pname:coverageModulationTableCount is the number of elements in 2585 pname:pCoverageModulationTable. 2586 * pname:pCoverageModulationTable is a table of modulation factors 2587 containing a value for each number of covered samples. 2588 2589If pname:coverageModulationTableEnable is ename:VK_FALSE, then for each 2590color sample the associated bits of the pixel coverage are counted and 2591divided by the number of associated bits to produce a modulation factor 2592[eq]#R# in the range [eq]#(0,1]# (a value of zero would have been killed due 2593to a color coverage of 0). 2594Specifically: 2595 2596 * [eq]#N# = value of pname:rasterizationSamples 2597 * [eq]#M# = value of slink:VkAttachmentDescription::pname:samples for any 2598 color attachments 2599 * [eq]#R = popcount(associated coverage bits) / (N / M)# 2600 2601If pname:coverageModulationTableEnable is ename:VK_TRUE, the value [eq]#R# 2602is computed using a programmable lookup table. 2603The lookup table has [eq]#N / M# elements, and the element of the table is 2604selected by: 2605 2606 * [eq]#R = pname:pCoverageModulationTable[popcount(associated coverage 2607 bits)-1]# 2608 2609Note that the table does not have an entry for [eq]#popcount(associated 2610coverage bits) = 0#, because such samples would have been killed. 2611 2612The values of pname:pCoverageModulationTable may: be rounded to an 2613implementation-dependent precision, which is at least as fine as [eq]#1 / 2614N#, and clamped to [eq]#[0,1]#. 2615 2616For each color attachment with a floating point or normalized color format, 2617each fragment output color value is replicated to [eq]#M# values which can: 2618each be modulated (multiplied) by that color sample's associated value of 2619[eq]#R#. 2620Which components are modulated is controlled by 2621pname:coverageModulationMode. 2622 2623If this structure is not included in the pname:pNext chain, it is as if 2624pname:coverageModulationMode is ename:VK_COVERAGE_MODULATION_MODE_NONE_NV. 2625 2626ifdef::VK_NV_coverage_reduction_mode[] 2627If the <<fragops-coverage-reduction, coverage reduction mode>> is 2628ename:VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV, each color sample is 2629associated with only a single coverage sample. 2630In this case, it is as if pname:coverageModulationMode is 2631ename:VK_COVERAGE_MODULATION_MODE_NONE_NV. 2632endif::VK_NV_coverage_reduction_mode[] 2633 2634.Valid Usage 2635**** 2636 * [[VUID-VkPipelineCoverageModulationStateCreateInfoNV-coverageModulationTableEnable-01405]] 2637 If pname:coverageModulationTableEnable is ename:VK_TRUE, 2638 pname:coverageModulationTableCount must: be equal to the number of 2639 rasterization samples divided by the number of color samples in the 2640 subpass 2641**** 2642 2643include::{generated}/validity/structs/VkPipelineCoverageModulationStateCreateInfoNV.adoc[] 2644-- 2645 2646[open,refpage='VkPipelineCoverageModulationStateCreateFlagsNV',desc='Reserved for future use',type='flags'] 2647-- 2648include::{generated}/api/flags/VkPipelineCoverageModulationStateCreateFlagsNV.adoc[] 2649 2650tname:VkPipelineCoverageModulationStateCreateFlagsNV is a bitmask type for 2651setting a mask, but is currently reserved for future use. 2652-- 2653 2654[open,refpage='VkCoverageModulationModeNV',desc='Specify the coverage modulation mode',type='enums'] 2655-- 2656Possible values of 2657slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationMode, 2658specifying which color components are modulated, are: 2659 2660include::{generated}/api/enums/VkCoverageModulationModeNV.adoc[] 2661 2662 * ename:VK_COVERAGE_MODULATION_MODE_NONE_NV specifies that no components 2663 are multiplied by the modulation factor. 2664 * ename:VK_COVERAGE_MODULATION_MODE_RGB_NV specifies that the red, green, 2665 and blue components are multiplied by the modulation factor. 2666 * ename:VK_COVERAGE_MODULATION_MODE_ALPHA_NV specifies that the alpha 2667 component is multiplied by the modulation factor. 2668 * ename:VK_COVERAGE_MODULATION_MODE_RGBA_NV specifies that all components 2669 are multiplied by the modulation factor. 2670-- 2671 2672ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2673 2674[open,refpage='vkCmdSetCoverageModulationModeNV',desc='Specify the coverage modulation mode dynamically for a command buffer',type='protos'] 2675-- 2676To <<pipelines-dynamic-state, dynamically set>> the 2677pname:coverageModulationMode state, call: 2678 2679include::{generated}/api/protos/vkCmdSetCoverageModulationModeNV.adoc[] 2680 2681 * pname:commandBuffer is the command buffer into which the command will be 2682 recorded. 2683 * pname:coverageModulationMode specifies the pname:coverageModulationMode 2684 state. 2685 2686This command sets the pname:coverageModulationMode state for subsequent 2687drawing commands 2688ifdef::VK_EXT_shader_object[] 2689ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2690ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2691endif::VK_EXT_shader_object[] 2692ifdef::VK_EXT_extended_dynamic_state3[] 2693the graphics pipeline is created with 2694ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV set in 2695slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2696endif::VK_EXT_extended_dynamic_state3[] 2697Otherwise, this state is specified by the 2698slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationMode 2699value used to create the currently active pipeline. 2700 2701:refpage: vkCmdSetCoverageModulationModeNV 2702:requiredfeature: extendedDynamicState3CoverageModulationMode 2703 2704.Valid Usage 2705**** 2706include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2707**** 2708 2709include::{generated}/validity/protos/vkCmdSetCoverageModulationModeNV.adoc[] 2710-- 2711 2712[open,refpage='vkCmdSetCoverageModulationTableEnableNV',desc='Specify the coverage modulation table enable state dynamically for a command buffer',type='protos'] 2713-- 2714To <<pipelines-dynamic-state, dynamically set>> the 2715pname:coverageModulationTableEnable state, call: 2716 2717include::{generated}/api/protos/vkCmdSetCoverageModulationTableEnableNV.adoc[] 2718 2719 * pname:commandBuffer is the command buffer into which the command will be 2720 recorded. 2721 * pname:coverageModulationTableEnable specifies the 2722 pname:coverageModulationTableEnable state. 2723 2724This command sets the pname:coverageModulationTableEnable state for 2725subsequent drawing commands 2726ifdef::VK_EXT_shader_object[] 2727ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2728ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2729endif::VK_EXT_shader_object[] 2730ifdef::VK_EXT_extended_dynamic_state3[] 2731when the graphics pipeline is created with 2732ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV set in 2733slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2734endif::VK_EXT_extended_dynamic_state3[] 2735Otherwise, this state is specified by the 2736slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationTableEnable 2737value used to create the currently active pipeline. 2738 2739:refpage: vkCmdSetCoverageModulationTableEnableNV 2740:requiredfeature: extendedDynamicState3CoverageModulationTableEnable 2741 2742.Valid Usage 2743**** 2744include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2745**** 2746 2747include::{generated}/validity/protos/vkCmdSetCoverageModulationTableEnableNV.adoc[] 2748-- 2749 2750[open,refpage='vkCmdSetCoverageModulationTableNV',desc='Specify the coverage modulation table dynamically for a command buffer',type='protos'] 2751-- 2752To <<pipelines-dynamic-state, dynamically set>> the 2753pname:pCoverageModulationTable state, call: 2754 2755include::{generated}/api/protos/vkCmdSetCoverageModulationTableNV.adoc[] 2756 2757 * pname:commandBuffer is the command buffer into which the command will be 2758 recorded. 2759 * pname:coverageModulationTableCount specifies the number of elements in 2760 pname:pCoverageModulationTable. 2761 * pname:pCoverageModulationTable specifies the table of modulation factors 2762 containing a value for each number of covered samples. 2763 2764This command sets the table of modulation factors for subsequent drawing 2765commands 2766ifdef::VK_EXT_shader_object[] 2767ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2768ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2769endif::VK_EXT_shader_object[] 2770ifdef::VK_EXT_extended_dynamic_state3[] 2771when the graphics pipeline is created with 2772ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV set in 2773slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2774endif::VK_EXT_extended_dynamic_state3[] 2775Otherwise, this state is specified by the 2776slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationTableCount, 2777and 2778slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:pCoverageModulationTable 2779values used to create the currently active pipeline. 2780 2781:refpage: vkCmdSetCoverageModulationTableNV 2782:requiredfeature: extendedDynamicState3CoverageModulationTable 2783 2784.Valid Usage 2785**** 2786include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2787**** 2788 2789include::{generated}/validity/protos/vkCmdSetCoverageModulationTableNV.adoc[] 2790-- 2791 2792endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2793 2794endif::VK_NV_framebuffer_mixed_samples[] 2795