1// Copyright 2015-2024 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 ** If a fragment shader statically computes the same values for different 769 framebuffer locations, and does not write to any storage resources, 770 multiple fragments may: be shaded by one fragment shader invocation. 771 This may: affect 772 ename:VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BIT 773 results, but must: otherwise not be visible behavior to applications. 774 * Otherwise, at least one fragment shader must: be executed. 775 ** If <<primsrast-sampleshading,sample shading>> is enabled and multiple 776 invocations per fragment are required:, additional invocations must: be 777 executed as specified. 778ifdef::VK_NV_shading_rate_image[] 779 ** If a <<primsrast-shading-rate-image,shading rate image>> is used and 780 multiple invocations per fragment are required:, additional invocations 781 must: be executed as specified. 782endif::VK_NV_shading_rate_image[] 783 ** Each covered sample must: be included in at least one fragment shader 784 invocation. 785 786If no fragment shader is included in the pipeline, no fragment shader is 787executed, and undefined: values may: be written to all color attachment 788outputs during this fragment operation. 789 790[NOTE] 791.Note 792==== 793Multiple fragment shader invocations may be executed for the same fragment 794for any number of implementation-dependent reasons. 795When there is more than one fragment shader invocation per fragment, the 796association of samples to invocations is implementation-dependent. 797Stores and atomics performed by these additional invocations have the normal 798effect. 799 800ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 801For example, if the subpass includes multiple views in its view mask, a 802fragment shader may be invoked separately for each view. 803endif::VK_VERSION_1_1,VK_KHR_multiview[] 804 805ifdef::VK_EXT_fragment_density_map[] 806Similarly, if the render pass has a fragment density map attachment, more 807than one fragment shader invocation may be invoked for each covered sample. 808Such additional invocations are only produced if 809sname:VkPhysicalDeviceFragmentDensityMapPropertiesEXT::pname:fragmentDensityInvocations 810is ename:VK_TRUE. 811Implementations may generate these additional fragment shader invocations in 812order to make transitions between fragment areas with different fragment 813densities more smooth. 814endif::VK_EXT_fragment_density_map[] 815==== 816 817 818[[fragops-shader-samplemask]] 819=== Sample Mask 820 821Reading from the <<interfaces-builtin-variables-samplemask, 822code:SampleMask>> built-in in the code:Input storage class will return the 823coverage mask for the current fragment as calculated by fragment operations 824that executed prior to fragment shading. 825 826If <<primsrast-sampleshading, sample shading>> is enabled, fragment shaders 827will only see values of `1` for samples being shaded - other bits will be 828`0`. 829 830Each bit of the coverage mask is associated with a sample index as described 831in the <<primsrast-multisampling-coverage-mask, rasterization chapter>>. 832If the bit in code:SampleMask which is associated with that same sample 833index is set to `0`, that coverage mask bit is set to `0`. 834 835Values written to the <<interfaces-builtin-variables-samplemask, 836code:SampleMask>> built-in in the code:Output storage class will be used by 837the <<fragops-covg, multisample coverage>> operation, with the same encoding 838as the input built-in. 839 840ifdef::VK_EXT_shader_tile_image[] 841[[fragops-shader-tileimage-reads]] 842=== Fragment Shader Tile Image Reads 843If the `apiext:VK_EXT_shader_tile_image` extension is enabled, 844implementations divide the framebuffer into a grid of tiles. 845A <<glossary-tile-image, tile image>> is a view of a framebuffer attachment 846tile for fragments with locations within the tile. 847 848Within a render pass instance initiated by flink:vkCmdBeginRenderingKHR, 849fragment shader invocations can: read the framebuffer color, depth, and 850stencil values at the fragment location via tile images. 851 852[NOTE] 853.Note 854==== 855Even though fragment shader invocation can only read from the corresponding 856fragment location, the abstraction of a tile image is introduced for the 857following reasons: 858 859 * Tile dimensions will be exposed in a future extension 860 * Future functionality such as executing compute dispatches within render 861 passes via tile shaders can leverage tile images. 862==== 863 864Enabling <<features-shaderTileImageColorReadAccess, 865shaderTileImageColorReadAccess>>, <<features-shaderTileImageDepthReadAccess, 866shaderTileImageDepthReadAccess>>, 867<<features-shaderTileImageStencilReadAccess, 868shaderTileImageStencilReadAccess>> enables fragment shader invocations to 869read from color, depth, and stencil, respectively. 870 871Color values are read from tile image variables with 872code:OpColorAttachmentReadEXT. 873Tile image variables are linked to specific color attachments using 874code:Location decoration. 875See <<interfaces-fragmenttileimage, Fragment Tile Image Interface>> for more 876details. 877 878Depth values are read with code:OpDepthAttachmentReadEXT. 879 880Stencil values are read with code:OpStencilAttachmentReadEXT. 881 882The sample to read is specified by a 883<<primsrast-multisampling-coverage-mask, sample index>> value specified as 884the code:Sample operand to code:OpColorAttachmentReadEXT, 885code:OpDepthAttachmentReadEXT, or code:OpStencilAttachmentReadEXT. 886 887If <<primsrast-sampleshading, sample shading>> is disabled, a fragment 888invocation can: read from all sample locations associated with the fragment 889regardless of the fragment's coverage. 890This functionality is supported for 891slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples > 1 892when 893slink:VkPhysicalDeviceShaderTileImagePropertiesEXT::pname:shaderTileImageReadSampleFromPixelRateInvocation 894is ename:VK_TRUE. 895 896If <<primsrast-sampleshading, sample shading>> is enabled, and 897pname:minSampleShading is 1.0, a fragment invocation must: only read from 898the <<primsrast-multisampling-coverageindex, coverage index>> sample. 899Tile image access must: not be used if the value of pname:minSampleShading 900is not 1.0. 901 902If the <<fragops-shader, fragment shader>> declares the 903code:EarlyFragmentTests execution mode, depth reads are allowed only if 904depth writes are disabled and stencil reads are allowed only if stencil 905writes are disabled. 906 907If 908slink:VkPhysicalDeviceShaderTileImagePropertiesEXT::pname:shaderTileImageReadFromHelperInvocation 909is ename:VK_FALSE, values read from helper invocations are undefined: 910otherwise the values read are subject to the coherency guarantees described 911below. 912 913code:OpDepthAttachmentReadEXT returns an undefined: value if no depth 914attachment is present. 915code:OpStencilAttachmentReadEXT returns an undefined: value if no stencil 916attachment is present. 917 918Tile image reads from color, depth and stencil attachments are said to be 919coherent when the accesses happen in raster order and without 920<<memory-model-access-data-race, data race>> with respect to accesses to the 921attachments from framebuffer-space pipeline stages. 922The samples which qualify for coherent access and the enabling conditions 923are described below. 924 925 * Let [eq]#Rc# be the set of components being read from an attachment 926 [eq]#A# in a draw call 927 * Let [eq]#Wc# be the set of components being written to [eq]#A# by the 928 draw call 929 930The samples which qualify for coherent tile image reads from an attachment 931[eq]#A# are: 932 933 * All samples in a pixel when [eq]#Rc# is disjoint with [eq]#Wc#. 934 * The samples with coverage in a fragment when [eq]#Rc# is not disjoint 935 with [eq]#Wc#. 936 The samples with coverage are determined by the coverage mask for the 937 fragment as calculated by fragment operations that executed prior to 938 fragment shading, including early fragment tests if enabled for the draw 939 call. 940 941A fragment shader can: declare code:NonCoherentColorAttachmentReadEXT, 942code:NonCoherentDepthAttachmentReadEXT, or 943code:NonCoherentStencilAttachmentReadEXT execution modes to enable 944non-coherent tile image reads which requires 945<<synchronization-pipeline-barriers-explicit-renderpass-tileimage, explicit 946tile image synchronization>> for the writes to an attachment to be made 947visible via tile image reads. 948 949When 950slink:VkPhysicalDeviceShaderTileImagePropertiesEXT::pname:shaderTileImageCoherentReadAccelerated 951is ename:VK_TRUE, the implementation prefers that coherent tile image reads 952are used, otherwise the implementation prefers that non-coherent tile image 953reads are used. 954 955[NOTE] 956.Note 957==== 958In practice, the most common tile image reads usage patterns fall under one 959of the following: 960 961 * Programmable blending - each fragment reads from a single sample 962 (SampleID) at its location. 963 Per-sample shading is typically enabled when multisampled rendertargets 964 are used. 965 * G-buffer generation and shading in one render pass - in the shading 966 phase a fragment reads from a single sample at its location. 967 * Programmable resolve - a fragment reads from all samples at its location 968 (per-sample shading is disabled). 969 This requires the use of a "full-screen triangle" instead of a rectangle 970 composed of two triangles in order to avoid data races along the shared 971 edge of the triangles. 972 * 1:1 texturing with LOD - in use cases such a deferred screen space 973 decals a fragment reads a single sample (SampleID) from depth buffer, 974 but requires being able to read from helper threads to derive the 975 texture LOD. 976 This use case is supported as long as the attachment components being 977 read are not overwritten by color, depth, or stencil attachment writes. 978 979All of the above use cases are supported by coherent tile image reads, but 980only the latter three are supported when non-coherent reads are used as 981there is no mechanism to synchronize non-coherent reads with writes within a 982draw call. 983==== 984 985endif::VK_EXT_shader_tile_image[] 986 987[[fragops-shader-depthreplacement]] 988=== Depth Replacement 989 990Writing to the <<interfaces-builtin-variables-fragdepth,code:FragDepth>> 991built-in will replace the fragment's calculated depth values for each sample 992in the input code:SampleMask. 993<<fragops-depth, Depth testing>> performed after the fragment shader for 994this fragment will use this new value as [eq]#z~f~#. 995 996 997ifdef::VK_EXT_shader_stencil_export[] 998[[fragops-shader-stencilrefreplacement]] 999=== Stencil Reference Replacement 1000 1001Writing to the 1002<<interfaces-builtin-variables-fragdepth,code:FragStencilRefEXT>> built-in 1003will replace the fragment's stencil reference value for each sample in the 1004input code:SampleMask. 1005<<fragops-stencil, Stencil testing>> performed after the fragment shader for 1006this fragment will use this new value as [eq]#s~r~#. 1007endif::VK_EXT_shader_stencil_export[] 1008 1009 1010ifdef::VK_EXT_fragment_shader_interlock[] 1011[[fragops-shader-interlock]] 1012=== Interlocked Operations 1013 1014code:OpBeginInvocationInterlockEXT and code:OpEndInvocationInterlockEXT 1015define a section of a fragment shader which imposes additional ordering 1016constraints on operations performed within them. 1017These operations are defined as _interlocked operations_. 1018How interlocked operations are ordered against other fragment shader 1019invocations depends on the specified execution modes. 1020 1021ifdef::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 1022If the code:ShadingRateInterlockOrderedEXT execution mode is specified, any 1023interlocked operations in a fragment shader must: happen before interlocked 1024operations in fragment shader invocations that execute later in 1025<<primsrast-order, rasterization order>> and cover at least one sample in 1026the same fragment area, and must: happen after interlocked operations in a 1027fragment shader that executes earlier in <<primsrast-order, rasterization 1028order>> and cover at least one sample in the same fragment area. 1029 1030If the code:ShadingRateInterlockUnorderedEXT execution mode is specified, 1031any interlocked operations in a fragment shader must: happen before or after 1032interlocked operations in fragment shader invocations that execute earlier 1033or later in <<primsrast-order, rasterization order>> and cover at least one 1034sample in the same fragment area. 1035endif::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 1036 1037If the code:PixelInterlockOrderedEXT execution mode is specified, any 1038interlocked operations in a fragment shader must: happen before interlocked 1039operations in fragment shader invocations that execute later in 1040<<primsrast-order, rasterization order>> and cover at least one sample in 1041the same pixel, and must: happen after interlocked operations in a fragment 1042shader that executes earlier in <<primsrast-order, rasterization order>> and 1043cover at least one sample in the same pixel. 1044 1045If the code:PixelInterlockUnorderedEXT execution mode is specified, any 1046interlocked operations in a fragment shader must: happen before or after 1047interlocked operations in fragment shader invocations that execute earlier 1048or later in <<primsrast-order, rasterization order>> and cover at least one 1049sample in the same pixel. 1050 1051If the code:SampleInterlockOrderedEXT execution mode is specified, any 1052interlocked operations in a fragment shader must: happen before interlocked 1053operations in fragment shader invocations that execute later in 1054<<primsrast-order, rasterization order>> and cover at least one of the same 1055samples, and must: happen after interlocked operations in a fragment shader 1056that executes earlier in <<primsrast-order, rasterization order>> and cover 1057at least one of the same samples. 1058 1059If the code:SampleInterlockUnorderedEXT execution mode is specified, any 1060interlocked operations in a fragment shader must: happen before or after 1061interlocked operations in fragment shader invocations that execute earlier 1062or later in <<primsrast-order, rasterization order>> and cover at least one 1063of the same samples. 1064endif::VK_EXT_fragment_shader_interlock[] 1065 1066 1067[[fragops-covg]] 1068== Multisample Coverage 1069 1070If a fragment shader is active and its entry point's interface includes a 1071built-in output variable decorated with code:SampleMask, 1072ifdef::VK_NV_sample_mask_override_coverage[] 1073but not code:OverrideCoverageNV, 1074endif::VK_NV_sample_mask_override_coverage[] 1075the coverage mask is code:ANDed with the bits of the code:SampleMask 1076built-in to generate a new coverage mask. 1077ifdef::VK_NV_sample_mask_override_coverage[] 1078If the code:SampleMask built-in is also decorated with 1079code:OverrideCoverageNV, the coverage mask is replaced with the mask bits 1080set in the shader. 1081endif::VK_NV_sample_mask_override_coverage[] 1082If <<primsrast-sampleshading,sample shading>> is enabled, bits written to 1083code:SampleMask corresponding to samples that are not being shaded by the 1084fragment shader invocation are ignored. 1085If no fragment shader is active, or if the active fragment shader does not 1086include code:SampleMask in its interface, the coverage mask is not modified. 1087 1088Next, the fragment alpha value and coverage mask are modified based on the 1089ifdef::VK_EXT_line_rasterization[] 1090line coverage factor if the pname:lineRasterizationMode member of the 1091slink:VkPipelineRasterizationStateCreateInfo structure is 1092ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, and the 1093endif::VK_EXT_line_rasterization[] 1094pname:alphaToCoverageEnable and pname:alphaToOneEnable members of the 1095slink:VkPipelineMultisampleStateCreateInfo structure. 1096 1097ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 1098 1099[open,refpage='vkCmdSetAlphaToCoverageEnableEXT',desc='Specify the alpha to coverage enable state dynamically for a command buffer',type='protos'] 1100-- 1101To <<pipelines-dynamic-state, dynamically set>> the 1102pname:alphaToCoverageEnable state, call: 1103 1104include::{generated}/api/protos/vkCmdSetAlphaToCoverageEnableEXT.adoc[] 1105 1106 * pname:commandBuffer is the command buffer into which the command will be 1107 recorded. 1108 * pname:alphaToCoverageEnable specifies the pname:alphaToCoverageEnable 1109 state. 1110 1111This command sets the pname:alphaToCoverageEnable state for subsequent 1112drawing commands 1113ifdef::VK_EXT_shader_object[] 1114ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 1115ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 1116endif::VK_EXT_shader_object[] 1117ifdef::VK_EXT_extended_dynamic_state3[] 1118when the graphics pipeline is created with 1119ename:VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT set in 1120slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1121endif::VK_EXT_extended_dynamic_state3[] 1122Otherwise, this state is specified by the 1123slink:VkPipelineMultisampleStateCreateInfo::pname:alphaToCoverageEnable 1124value used to create the currently active pipeline. 1125 1126:refpage: vkCmdSetAlphaToCoverageEnableEXT 1127:requiredfeature: extendedDynamicState3AlphaToCoverageEnable 1128 1129.Valid Usage 1130**** 1131include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 1132**** 1133 1134include::{generated}/validity/protos/vkCmdSetAlphaToCoverageEnableEXT.adoc[] 1135-- 1136 1137[open,refpage='vkCmdSetAlphaToOneEnableEXT',desc='Specify the alpha to one enable state dynamically for a command buffer',type='protos'] 1138-- 1139To <<pipelines-dynamic-state, dynamically set>> the pname:alphaToOneEnable 1140state, call: 1141 1142include::{generated}/api/protos/vkCmdSetAlphaToOneEnableEXT.adoc[] 1143 1144 * pname:commandBuffer is the command buffer into which the command will be 1145 recorded. 1146 * pname:alphaToOneEnable specifies the pname:alphaToOneEnable state. 1147 1148This command sets the pname:alphaToOneEnable state for subsequent drawing 1149commands 1150ifdef::VK_EXT_shader_object[] 1151ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 1152ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 1153endif::VK_EXT_shader_object[] 1154ifdef::VK_EXT_extended_dynamic_state3[] 1155when the graphics pipeline is created with 1156ename:VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT set in 1157slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1158endif::VK_EXT_extended_dynamic_state3[] 1159Otherwise, this state is specified by the 1160slink:VkPipelineMultisampleStateCreateInfo::pname:alphaToOneEnable value 1161used to create the currently active pipeline. 1162 1163:refpage: vkCmdSetAlphaToOneEnableEXT 1164:requiredfeature: extendedDynamicState3AlphaToOneEnable 1165 1166.Valid Usage 1167**** 1168include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 1169 * [[VUID-vkCmdSetAlphaToOneEnableEXT-alphaToOne-07607]] 1170 If the <<features-alphaToOne, pname:alphaToOne>> feature is not enabled, 1171 pname:alphaToOneEnable must: be ename:VK_FALSE 1172**** 1173 1174include::{generated}/validity/protos/vkCmdSetAlphaToOneEnableEXT.adoc[] 1175-- 1176 1177endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 1178 1179All alpha values in this section refer only to the alpha component of the 1180fragment shader output that has a code:Location and code:Index decoration of 1181zero (see the <<interfaces-fragmentoutput,Fragment Output Interface>> 1182section). 1183If that shader output has an integer or unsigned integer type, then these 1184operations are skipped. 1185 1186ifdef::VK_EXT_line_rasterization[] 1187If the pname:lineRasterizationMode member of the 1188slink:VkPipelineRasterizationStateCreateInfo structure is 1189ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT and the fragment 1190came from a line segment, then the alpha value is replaced by multiplying it 1191by the coverage factor for the fragment computed during 1192<<primsrast-lines-smooth,smooth line rasterization>>. 1193endif::VK_EXT_line_rasterization[] 1194 1195If pname:alphaToCoverageEnable is enabled, a temporary coverage mask is 1196generated where each bit is determined by the fragment's alpha value, which 1197is ANDed with the fragment coverage mask. 1198 1199No specific algorithm is specified for converting the alpha value to a 1200temporary coverage mask. 1201It is intended that the number of 1's in this value be proportional to the 1202alpha value (clamped to [eq]#[0,1]#), with all 1's corresponding to a value 1203of 1.0 and all 0's corresponding to 0.0. 1204The algorithm may: be different at different framebuffer coordinates. 1205 1206[NOTE] 1207.Note 1208==== 1209Using different algorithms at different framebuffer coordinates may: help to 1210avoid artifacts caused by regular coverage sample locations. 1211==== 1212 1213Finally, if pname:alphaToOneEnable is enabled, each alpha value is replaced 1214by the maximum representable alpha value for fixed-point color attachments, 1215or by 1.0 for floating-point attachments. 1216Otherwise, the alpha values are not changed. 1217 1218 1219[[fragops-ds-state]] 1220== Depth and Stencil Operations 1221 1222Pipeline state controlling the <<fragops-dbt,depth bounds tests>>, 1223<<fragops-stencil,stencil test>>, and <<fragops-depth,depth test>> is 1224specified through the members of the 1225sname:VkPipelineDepthStencilStateCreateInfo structure. 1226 1227[open,refpage='VkPipelineDepthStencilStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline depth stencil state',type='structs'] 1228-- 1229The sname:VkPipelineDepthStencilStateCreateInfo structure is defined as: 1230 1231include::{generated}/api/structs/VkPipelineDepthStencilStateCreateInfo.adoc[] 1232 1233 * pname:sType is a elink:VkStructureType value identifying this structure. 1234 * pname:pNext is `NULL` or a pointer to a structure extending this 1235 structure. 1236ifndef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1237 * pname:flags is reserved for future use. 1238endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1239ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1240 * pname:flags is a bitmask of 1241 elink:VkPipelineDepthStencilStateCreateFlagBits specifying additional 1242 depth/stencil state information. 1243endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1244 * pname:depthTestEnable controls whether <<fragops-depth,depth testing>> 1245 is enabled. 1246 * pname:depthWriteEnable controls whether <<fragops-depth-write,depth 1247 writes>> are enabled when pname:depthTestEnable is ename:VK_TRUE. 1248 Depth writes are always disabled when pname:depthTestEnable is 1249 ename:VK_FALSE. 1250 * pname:depthCompareOp is a elink:VkCompareOp value specifying the 1251 comparison operator to use in the <<fragops-depth-comparison, Depth 1252 Comparison>> step of the <<fragops-depth,depth test>>. 1253 * pname:depthBoundsTestEnable controls whether <<fragops-dbt,depth bounds 1254 testing>> is enabled. 1255 * pname:stencilTestEnable controls whether <<fragops-stencil,stencil 1256 testing>> is enabled. 1257 * pname:front and pname:back are slink:VkStencilOpState values controlling 1258 the corresponding parameters of the <<fragops-stencil,stencil test>>. 1259 * pname:minDepthBounds is the minimum depth bound used in the 1260 <<fragops-dbt, depth bounds test>>. 1261 * pname:maxDepthBounds is the maximum depth bound used in the 1262 <<fragops-dbt, depth bounds test>>. 1263 1264.Valid Usage 1265**** 1266 * [[VUID-VkPipelineDepthStencilStateCreateInfo-depthBoundsTestEnable-00598]] 1267 If the <<features-depthBounds, pname:depthBounds>> feature is not 1268 enabled, pname:depthBoundsTestEnable must: be ename:VK_FALSE 1269ifdef::VK_KHR_portability_subset[] 1270 * [[VUID-VkPipelineDepthStencilStateCreateInfo-separateStencilMaskRef-04453]] 1271 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 1272 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:separateStencilMaskRef 1273 is ename:VK_FALSE, and the value of 1274 slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable is 1275 ename:VK_TRUE, and the value of 1276 slink:VkPipelineRasterizationStateCreateInfo::pname:cullMode is 1277 ename:VK_CULL_MODE_NONE, the value of pname:reference in each of the 1278 slink:VkStencilOpState structs in pname:front and pname:back must: be 1279 the same 1280endif::VK_KHR_portability_subset[] 1281ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1282 * [[VUID-VkPipelineDepthStencilStateCreateInfo-rasterizationOrderDepthAttachmentAccess-06463]] 1283 If the <<features-rasterizationOrderDepthAttachmentAccess, 1284 pname:rasterizationOrderDepthAttachmentAccess>> feature is not enabled, 1285 pname:flags must: not include 1286 ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT 1287 * [[VUID-VkPipelineDepthStencilStateCreateInfo-rasterizationOrderStencilAttachmentAccess-06464]] 1288 If the <<features-rasterizationOrderStencilAttachmentAccess, 1289 pname:rasterizationOrderStencilAttachmentAccess>> feature is not 1290 enabled, pname:flags must: not include 1291 ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT 1292endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1293**** 1294 1295include::{generated}/validity/structs/VkPipelineDepthStencilStateCreateInfo.adoc[] 1296-- 1297 1298[open,refpage='VkPipelineDepthStencilStateCreateFlags',desc='Bitmask of VkPipelineDepthStencilStateCreateFlagBits',type='flags'] 1299-- 1300include::{generated}/api/flags/VkPipelineDepthStencilStateCreateFlags.adoc[] 1301 1302ifndef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1303tname:VkPipelineDepthStencilStateCreateFlags is a bitmask type for setting a 1304mask, but is currently reserved for future use. 1305endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1306ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1307tname:VkPipelineDepthStencilStateCreateFlags is a bitmask type for setting a 1308mask of zero or more elink:VkPipelineDepthStencilStateCreateFlagBits. 1309endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1310-- 1311 1312ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1313[open,refpage='VkPipelineDepthStencilStateCreateFlagBits',desc='Bitmask specifying additional depth/stencil state information.',type='enums'] 1314-- 1315Bits which can: be set in the 1316slink:VkPipelineDepthStencilStateCreateInfo::pname:flags parameter are: 1317 1318include::{generated}/api/enums/VkPipelineDepthStencilStateCreateFlagBits.adoc[] 1319 1320 * ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT 1321 indicates that access to the depth aspects of depth/stencil and input 1322 attachments will have implicit framebuffer-local memory dependencies. 1323 * ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT 1324 indicates that access to the stencil aspects of depth/stencil and input 1325 attachments will have implicit framebuffer-local memory dependencies. 1326 1327When 1328ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT 1329is included in a pipeline, it forms a framebuffer-local memory dependency 1330for each fragment generated by draw commands for that pipeline with the 1331following scopes: 1332 1333 * The first <<synchronization-dependencies-scopes, synchronization scope>> 1334 includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT and 1335 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed 1336 by all previous fragments (as defined by <<drawing-primitive-order, 1337 primitive order>>) in the corresponding 1338 <<synchronization-framebuffer-regions, framebuffer regions>> including 1339 those generated by the same draw command. 1340 * The second <<synchronization-dependencies-scopes, synchronization 1341 scope>> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT stage 1342 executed by the generated fragment. 1343 * The first <<synchronization-dependencies-access-scopes, access scope>> 1344 includes all writes to the depth aspect of depth/stencil attachments. 1345 * The second <<synchronization-dependencies-access-scopes, access scope>> 1346 includes all reads from the depth aspect of input attachments. 1347 1348When 1349ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT 1350is included in a pipeline, it forms a framebuffer-local memory dependency 1351for each fragment generated by draw commands for that pipeline with the 1352following scopes: 1353 1354 * The first <<synchronization-dependencies-scopes, synchronization scope>> 1355 includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT 1356 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed 1357 by all previous fragments (as defined by <<drawing-primitive-order, 1358 primitive order>>) in the corresponding 1359 <<synchronization-framebuffer-regions, framebuffer regions>> including 1360 those generated by the same draw command. 1361 * The second <<synchronization-dependencies-scopes, synchronization 1362 scope>> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT and 1363 ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed 1364 by the generated fragment. 1365 * The first <<synchronization-dependencies-access-scopes, access scope>> 1366 includes all writes to the stencil aspect of depth/stencil attachments. 1367 * The second <<synchronization-dependencies-access-scopes, access scope>> 1368 includes all reads from the stencil aspect of input attachments. 1369-- 1370endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] 1371 1372 1373[[fragops-dbt]] 1374== Depth Bounds Test 1375 1376The depth bounds test compares the depth value [eq]#z~a~# in the 1377depth/stencil attachment at each sample's framebuffer coordinates 1378[eq]#(x~f~,y~f~)# and <<primsrast-multisampling-coverage-mask, sample 1379index>> [eq]#i# against a set of _depth bounds_. 1380 1381The depth bounds are determined by two floating point values defining a 1382minimum (pname:minDepthBounds) and maximum (pname:maxDepthBounds) depth 1383value. 1384These values are either set by the 1385slink:VkPipelineDepthStencilStateCreateInfo structure during pipeline 1386creation, or dynamically by 1387ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1388flink:vkCmdSetDepthBoundsTestEnable and 1389endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1390flink:vkCmdSetDepthBounds. 1391 1392A given sample is considered within the depth bounds if [eq]#z~a~# is in the 1393range [eq]#[pname:minDepthBounds,pname:maxDepthBounds]#. 1394Samples with depth attachment values outside of the depth bounds will have 1395their coverage set to `0`. 1396 1397If the depth bounds test is disabled, or if there is no depth attachment, 1398the coverage mask is unmodified by this operation. 1399 1400ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1401[open,refpage='vkCmdSetDepthBoundsTestEnable',desc='Set depth bounds test enable dynamically for a command buffer',type='protos',alias='vkCmdSetDepthBoundsTestEnableEXT'] 1402-- 1403To <<pipelines-dynamic-state, dynamically enable or disable>> the depth 1404bounds test, call: 1405 1406ifdef::VK_VERSION_1_3[] 1407include::{generated}/api/protos/vkCmdSetDepthBoundsTestEnable.adoc[] 1408 1409ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 1410endif::VK_VERSION_1_3[] 1411 1412ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1413include::{generated}/api/protos/vkCmdSetDepthBoundsTestEnableEXT.adoc[] 1414endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1415 1416 * pname:commandBuffer is the command buffer into which the command will be 1417 recorded. 1418 * pname:depthBoundsTestEnable specifies if the depth bounds test is 1419 enabled. 1420 1421This command sets the depth bounds enable for subsequent drawing commands 1422ifdef::VK_EXT_shader_object[] 1423ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 1424ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 1425endif::VK_EXT_shader_object[] 1426ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1427when the graphics pipeline is created with 1428ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE set in 1429slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1430endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1431Otherwise, this state is specified by the 1432slink:VkPipelineDepthStencilStateCreateInfo::pname:depthBoundsTestEnable 1433value used to create the currently active pipeline. 1434 1435:refpage: vkCmdSetDepthBoundsTestEnable 1436 1437.Valid Usage 1438**** 1439include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 1440**** 1441 1442include::{generated}/validity/protos/vkCmdSetDepthBoundsTestEnable.adoc[] 1443-- 1444endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1445 1446[open,refpage='vkCmdSetDepthBounds',desc='Set depth bounds range dynamically for a command buffer',type='protos'] 1447-- 1448To <<pipelines-dynamic-state, dynamically set>> the depth bounds range, 1449call: 1450 1451include::{generated}/api/protos/vkCmdSetDepthBounds.adoc[] 1452 1453 * pname:commandBuffer is the command buffer into which the command will be 1454 recorded. 1455 * pname:minDepthBounds is the minimum depth bound. 1456 * pname:maxDepthBounds is the maximum depth bound. 1457 1458This command sets the depth bounds range for subsequent drawing commands 1459ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 1460when the graphics pipeline is created with 1461ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS set in 1462slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1463Otherwise, this state is specified by the 1464slink:VkPipelineDepthStencilStateCreateInfo::pname:minDepthBounds and 1465slink:VkPipelineDepthStencilStateCreateInfo::pname:maxDepthBounds values 1466used to create the currently active pipeline. 1467 1468.Valid Usage 1469**** 1470 * [[VUID-vkCmdSetDepthBounds-minDepthBounds-00600]] 1471ifdef::VK_EXT_depth_range_unrestricted[] 1472 If the `apiext:VK_EXT_depth_range_unrestricted` extension is not enabled 1473endif::VK_EXT_depth_range_unrestricted[] 1474 pname:minDepthBounds must: be between `0.0` and `1.0`, inclusive 1475 * [[VUID-vkCmdSetDepthBounds-maxDepthBounds-00601]] 1476ifdef::VK_EXT_depth_range_unrestricted[] 1477 If the `apiext:VK_EXT_depth_range_unrestricted` extension is not enabled 1478endif::VK_EXT_depth_range_unrestricted[] 1479 pname:maxDepthBounds must: be between `0.0` and `1.0`, inclusive 1480**** 1481 1482include::{generated}/validity/protos/vkCmdSetDepthBounds.adoc[] 1483-- 1484 1485 1486[[fragops-stencil]] 1487== Stencil Test 1488 1489The stencil test compares the stencil attachment value [eq]#s~a~# in the 1490depth/stencil attachment at each sample's framebuffer coordinates 1491[eq]#(x~f~,y~f~)# and <<primsrast-multisampling-coverage-mask, sample 1492index>> [eq]#i# against a _stencil reference value_. 1493 1494ifdef::VK_EXT_fragment_density_map[] 1495If the render pass has a fragment density map attachment and the fragment 1496covers multiple pixels, there is an implementation-dependent association of 1497coverage samples to stencil attachment samples within the fragment. 1498However, if all samples in the fragment are covered, and the stencil 1499attachment value is updated as a result of this test, all stencil attachment 1500samples will be updated. 1501endif::VK_EXT_fragment_density_map[] 1502 1503If the stencil test is not enabled, as specified by 1504ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1505flink:vkCmdSetStencilTestEnable or 1506endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1507slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable, or if 1508there is no stencil attachment, the coverage mask is unmodified by this 1509operation. 1510 1511The stencil test is controlled by one of two sets of stencil-related state, 1512the front stencil state and the back stencil state. 1513Stencil tests and writes use the back stencil state when processing 1514fragments generated by <<primsrast-polygons-basic,back-facing>> 1515<<primsrast-polygons,polygons>>, and the front stencil state when processing 1516fragments generated by <<primsrast-polygons-basic,front-facing polygons>> or 1517any other primitives. 1518 1519The comparison operation performed is determined by the elink:VkCompareOp 1520value set by 1521ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1522flink:vkCmdSetStencilOp::pname:compareOp, or by 1523endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1524slink:VkStencilOpState::pname:compareOp during pipeline creation. 1525 1526The compare mask [eq]#s~c~# and stencil reference value [eq]#s~r~# of the 1527front or the back stencil state set determine arguments of the comparison 1528operation. 1529[eq]#s~c~# is set by the slink:VkPipelineDepthStencilStateCreateInfo 1530structure during pipeline creation, or by the 1531flink:vkCmdSetStencilCompareMask command. 1532[eq]#s~r~# is set by slink:VkPipelineDepthStencilStateCreateInfo or by 1533flink:vkCmdSetStencilReference. 1534 1535[eq]#s~r~# and [eq]#s~a~# are each independently combined with [eq]#s~c~# 1536using a bitwise code:AND operation to create masked reference and attachment 1537values [eq]#s'~r~# and [eq]#s'~a~#. 1538[eq]#s'~r~# and [eq]#s'~a~# are used as the _reference_ and _test_ values, 1539respectively, in the operation specified by the elink:VkCompareOp. 1540 1541If the comparison evaluates to false, the coverage for the sample is set to 1542`0`. 1543 1544A new stencil value [eq]#s~g~# is generated according to a stencil operation 1545defined by elink:VkStencilOp parameters set by 1546ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1547flink:vkCmdSetStencilOp or 1548endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1549slink:VkPipelineDepthStencilStateCreateInfo. 1550If the stencil test fails, pname:failOp defines the stencil operation used. 1551If the stencil test passes however, the stencil op used is based on the 1552<<fragops-depth, depth test>> - if it passes, 1553slink:VkPipelineDepthStencilStateCreateInfo::pname:passOp is used, otherwise 1554slink:VkPipelineDepthStencilStateCreateInfo::pname:depthFailOp is used. 1555 1556The stencil attachment value [eq]#s~a~# is then updated with the generated 1557stencil value [eq]#s~g~# according to the write mask [eq]#s~w~# defined by 1558pname:writeMask in slink:VkPipelineDepthStencilStateCreateInfo::pname:front 1559and slink:VkPipelineDepthStencilStateCreateInfo::pname:back as: 1560 1561 {empty}:: [eq]#s~a~ = (s~a~ & ¬s~w~) | (s~g~ & s~w~)# 1562 1563ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1564[open,refpage='vkCmdSetStencilTestEnable',desc='Set stencil test enable dynamically for a command buffer',type='protos',alias='vkCmdSetStencilTestEnableEXT'] 1565-- 1566To <<pipelines-dynamic-state, dynamically enable or disable>> the stencil 1567test, call: 1568 1569ifdef::VK_VERSION_1_3[] 1570include::{generated}/api/protos/vkCmdSetStencilTestEnable.adoc[] 1571 1572ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 1573endif::VK_VERSION_1_3[] 1574 1575ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1576include::{generated}/api/protos/vkCmdSetStencilTestEnableEXT.adoc[] 1577endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1578 1579 * pname:commandBuffer is the command buffer into which the command will be 1580 recorded. 1581 * pname:stencilTestEnable specifies if the stencil test is enabled. 1582 1583This command sets the stencil test enable for subsequent drawing commands 1584ifdef::VK_EXT_shader_object[] 1585ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 1586ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 1587endif::VK_EXT_shader_object[] 1588ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1589when the graphics pipeline is created with 1590ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE set in 1591slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1592endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1593Otherwise, this state is specified by the 1594slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable value 1595used to create the currently active pipeline. 1596 1597:refpage: vkCmdSetStencilTestEnable 1598 1599.Valid Usage 1600**** 1601include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 1602**** 1603 1604include::{generated}/validity/protos/vkCmdSetStencilTestEnable.adoc[] 1605-- 1606 1607[open,refpage='vkCmdSetStencilOp',desc='Set stencil operation dynamically for a command buffer',type='protos',alias='vkCmdSetStencilOpEXT'] 1608-- 1609To <<pipelines-dynamic-state, dynamically set>> the stencil operation, call: 1610 1611ifdef::VK_VERSION_1_3[] 1612include::{generated}/api/protos/vkCmdSetStencilOp.adoc[] 1613 1614ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 1615endif::VK_VERSION_1_3[] 1616 1617ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1618include::{generated}/api/protos/vkCmdSetStencilOpEXT.adoc[] 1619endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1620 1621 * pname:commandBuffer is the command buffer into which the command will be 1622 recorded. 1623 * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying 1624 the set of stencil state for which to update the stencil operation. 1625 * pname:failOp is a elink:VkStencilOp value specifying the action 1626 performed on samples that fail the stencil test. 1627 * pname:passOp is a elink:VkStencilOp value specifying the action 1628 performed on samples that pass both the depth and stencil tests. 1629 * pname:depthFailOp is a elink:VkStencilOp value specifying the action 1630 performed on samples that pass the stencil test and fail the depth test. 1631 * pname:compareOp is a elink:VkCompareOp value specifying the comparison 1632 operator used in the stencil test. 1633 1634This command sets the stencil operation for subsequent drawing commands when 1635ifdef::VK_EXT_shader_object[] 1636ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 1637ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 1638endif::VK_EXT_shader_object[] 1639ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1640when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_OP 1641set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1642endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1643Otherwise, this state is specified by the corresponding 1644sname:VkPipelineDepthStencilStateCreateInfo::pname:failOp, pname:passOp, 1645pname:depthFailOp, and pname:compareOp values used to create the currently 1646active pipeline, for both front and back faces. 1647 1648:refpage: vkCmdSetStencilOp 1649 1650.Valid Usage 1651**** 1652include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 1653**** 1654 1655include::{generated}/validity/protos/vkCmdSetStencilOp.adoc[] 1656-- 1657endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1658 1659[open,refpage='VkStencilOpState',desc='Structure specifying stencil operation state',type='structs'] 1660-- 1661The sname:VkStencilOpState structure is defined as: 1662 1663include::{generated}/api/structs/VkStencilOpState.adoc[] 1664 1665 * pname:failOp is a elink:VkStencilOp value specifying the action 1666 performed on samples that fail the stencil test. 1667 * pname:passOp is a elink:VkStencilOp value specifying the action 1668 performed on samples that pass both the depth and stencil tests. 1669 * pname:depthFailOp is a elink:VkStencilOp value specifying the action 1670 performed on samples that pass the stencil test and fail the depth test. 1671 * pname:compareOp is a elink:VkCompareOp value specifying the comparison 1672 operator used in the stencil test. 1673 * pname:compareMask selects the bits of the unsigned integer stencil 1674 values participating in the stencil test. 1675 * pname:writeMask selects the bits of the unsigned integer stencil values 1676 updated by the stencil test in the stencil framebuffer attachment. 1677 * pname:reference is an integer stencil reference value that is used in 1678 the unsigned stencil comparison. 1679 1680include::{generated}/validity/structs/VkStencilOpState.adoc[] 1681-- 1682 1683[open,refpage='vkCmdSetStencilCompareMask',desc='Set stencil compare mask dynamically for a command buffer',type='protos'] 1684-- 1685To <<pipelines-dynamic-state, dynamically set>> the stencil compare mask, 1686call: 1687 1688include::{generated}/api/protos/vkCmdSetStencilCompareMask.adoc[] 1689 1690 * pname:commandBuffer is the command buffer into which the command will be 1691 recorded. 1692 * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying 1693 the set of stencil state for which to update the compare mask. 1694 * pname:compareMask is the new value to use as the stencil compare mask. 1695 1696This command sets the stencil compare mask for subsequent drawing commands 1697ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 1698when the graphics pipeline is created with 1699ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK set in 1700slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1701Otherwise, this state is specified by the 1702slink:VkStencilOpState::pname:compareMask value used to create the currently 1703active pipeline, for both front and back faces. 1704 1705include::{generated}/validity/protos/vkCmdSetStencilCompareMask.adoc[] 1706-- 1707 1708[open,refpage='VkStencilFaceFlagBits',desc='Bitmask specifying sets of stencil state for which to update the compare mask',type='enums'] 1709-- 1710ename:VkStencilFaceFlagBits values are: 1711 1712include::{generated}/api/enums/VkStencilFaceFlagBits.adoc[] 1713 1714 * ename:VK_STENCIL_FACE_FRONT_BIT specifies that only the front set of 1715 stencil state is updated. 1716 * ename:VK_STENCIL_FACE_BACK_BIT specifies that only the back set of 1717 stencil state is updated. 1718 * ename:VK_STENCIL_FACE_FRONT_AND_BACK is the combination of 1719 ename:VK_STENCIL_FACE_FRONT_BIT and ename:VK_STENCIL_FACE_BACK_BIT, and 1720 specifies that both sets of stencil state are updated. 1721 1722ifdef::VKSC_VERSION_1_0[] 1723ifdef::hidden[] 1724// tag::scremoved[] 1725 * elink:VkStencilFaceFlagBits (deprecated alias) 1726 ** etext:VK_STENCIL_FRONT_AND_BACK <<SCID-8>> 1727// end::scremoved[] 1728endif::hidden[] 1729endif::VKSC_VERSION_1_0[] 1730-- 1731 1732[open,refpage='VkStencilFaceFlags',desc='Bitmask of VkStencilFaceFlagBits',type='flags'] 1733-- 1734include::{generated}/api/flags/VkStencilFaceFlags.adoc[] 1735 1736tname:VkStencilFaceFlags is a bitmask type for setting a mask of zero or 1737more elink:VkStencilFaceFlagBits. 1738-- 1739 1740[open,refpage='vkCmdSetStencilWriteMask',desc='Set stencil write mask dynamically for a command buffer',type='protos'] 1741-- 1742To <<pipelines-dynamic-state, dynamically set>> the stencil write mask, 1743call: 1744 1745include::{generated}/api/protos/vkCmdSetStencilWriteMask.adoc[] 1746 1747 * pname:commandBuffer is the command buffer into which the command will be 1748 recorded. 1749 * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying 1750 the set of stencil state for which to update the write mask, as 1751 described above for flink:vkCmdSetStencilCompareMask. 1752 * pname:writeMask is the new value to use as the stencil write mask. 1753 1754This command sets the stencil write mask for subsequent drawing commands 1755ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 1756when the graphics pipeline is created with 1757ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK set in 1758slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1759Otherwise, this state is specified by the pname:writeMask value used to 1760create the currently active pipeline, for both 1761slink:VkPipelineDepthStencilStateCreateInfo::pname:front and 1762slink:VkPipelineDepthStencilStateCreateInfo::pname:back faces. 1763 1764include::{generated}/validity/protos/vkCmdSetStencilWriteMask.adoc[] 1765-- 1766 1767[open,refpage='vkCmdSetStencilReference',desc='Set stencil reference value dynamically for a command buffer',type='protos'] 1768-- 1769To <<pipelines-dynamic-state, dynamically set>> the stencil reference value, 1770call: 1771 1772include::{generated}/api/protos/vkCmdSetStencilReference.adoc[] 1773 1774 * pname:commandBuffer is the command buffer into which the command will be 1775 recorded. 1776 * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying 1777 the set of stencil state for which to update the reference value, as 1778 described above for flink:vkCmdSetStencilCompareMask. 1779 * pname:reference is the new value to use as the stencil reference value. 1780 1781This command sets the stencil reference value for subsequent drawing 1782commands 1783ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or] 1784when the graphics pipeline is created with 1785ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE set in 1786slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1787Otherwise, this state is specified by the 1788slink:VkPipelineDepthStencilStateCreateInfo::pname:reference value used to 1789create the currently active pipeline, for both front and back faces. 1790 1791include::{generated}/validity/protos/vkCmdSetStencilReference.adoc[] 1792-- 1793 1794[open,refpage='VkStencilOp',desc='Stencil comparison function',type='enums'] 1795-- 1796Possible values of the pname:failOp, pname:passOp, and pname:depthFailOp 1797members of slink:VkStencilOpState, specifying what happens to the stored 1798stencil value if this or certain subsequent tests fail or pass, are: 1799 1800include::{generated}/api/enums/VkStencilOp.adoc[] 1801 1802 * ename:VK_STENCIL_OP_KEEP keeps the current value. 1803 * ename:VK_STENCIL_OP_ZERO sets the value to 0. 1804 * ename:VK_STENCIL_OP_REPLACE sets the value to pname:reference. 1805 * ename:VK_STENCIL_OP_INCREMENT_AND_CLAMP increments the current value and 1806 clamps to the maximum representable unsigned value. 1807 * ename:VK_STENCIL_OP_DECREMENT_AND_CLAMP decrements the current value and 1808 clamps to 0. 1809 * ename:VK_STENCIL_OP_INVERT bitwise-inverts the current value. 1810 * ename:VK_STENCIL_OP_INCREMENT_AND_WRAP increments the current value and 1811 wraps to 0 when the maximum value would have been exceeded. 1812 * ename:VK_STENCIL_OP_DECREMENT_AND_WRAP decrements the current value and 1813 wraps to the maximum possible value when the value would go below 0. 1814 1815For purposes of increment and decrement, the stencil bits are considered as 1816an unsigned integer. 1817-- 1818 1819 1820[[fragops-depth]] 1821== Depth Test 1822 1823The depth test compares the depth value [eq]#z~a~# in the depth/stencil 1824attachment at each sample's framebuffer coordinates [eq]#(x~f~,y~f~)# and 1825<<primsrast-multisampling-coverage-mask, sample index>> [eq]#i# against the 1826sample's depth value [eq]#z~f~#. 1827If there is no depth attachment then the depth test is skipped. 1828 1829ifdef::VK_EXT_fragment_density_map[] 1830If the render pass has a fragment density map attachment and the fragment 1831covers multiple pixels, there is an implementation-dependent association of 1832rasterization samples to depth attachment samples within the fragment. 1833However, if all samples in the fragment are covered, and the depth 1834attachment value is updated as a result of this test, all depth attachment 1835samples will be updated. 1836endif::VK_EXT_fragment_density_map[] 1837 1838The depth test occurs in three stages, as detailed in the following 1839sections. 1840 1841 1842=== Depth Clamping and Range Adjustment 1843 1844If slink:VkPipelineRasterizationStateCreateInfo::pname:depthClampEnable is 1845enabled, [eq]#z~f~# is clamped to [eq]#[z~min~, z~max~]#, where [eq]#z~min~ 1846= min(n,f)#, [eq]#z~max~ = max(n,f)]#, and [eq]#n# and [eq]#f# are the 1847pname:minDepth and pname:maxDepth depth range values of the viewport used by 1848this fragment, respectively. 1849 1850ifdef::VK_EXT_depth_clamp_zero_one[] 1851If 1852slink:VkPhysicalDeviceDepthClampZeroOneFeaturesEXT::pname:depthClampZeroOne 1853is enabled: 1854 1855ifdef::VK_EXT_depth_range_unrestricted[] 1856 * If the depth attachment has a floating-point format and 1857 apiext:VK_EXT_depth_range_unrestricted is enabled then [eq]#z~f~# is 1858 unchanged. 1859 * Otherwise, [eq]#z~f~# is clamped to the range [eq]#[0, 1]#. 1860endif::VK_EXT_depth_range_unrestricted[] 1861ifndef::VK_EXT_depth_range_unrestricted[] 1862 * [eq]#z~f~# is clamped to the range [eq]#[0, 1]#. 1863endif::VK_EXT_depth_range_unrestricted[] 1864 1865Otherwise: 1866endif::VK_EXT_depth_clamp_zero_one[] 1867ifndef::VK_EXT_depth_clamp_zero_one[] 1868Following depth clamping: 1869endif::VK_EXT_depth_clamp_zero_one[] 1870 1871 * If [eq]#z~f~# is not in the range [eq]#[z~min~, z~max~]#, then 1872 [eq]#z~f~# is undefined: following this step. 1873ifdef::VK_EXT_depth_range_unrestricted[] 1874 * If the depth attachment has a fixed-point format and [eq]#z~f~# is not 1875 in the range [eq]#[0, 1]#, then [eq]#z~f~# is undefined: following this 1876 step. 1877endif::VK_EXT_depth_range_unrestricted[] 1878 1879 1880[[fragops-depth-comparison]] 1881=== Depth Comparison 1882 1883If the depth test is not enabled, as specified by 1884ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1885flink:vkCmdSetDepthTestEnable or 1886endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1887slink:VkPipelineDepthStencilStateCreateInfo::pname:depthTestEnable, then 1888this step is skipped. 1889 1890The comparison operation performed is determined by the elink:VkCompareOp 1891value set by 1892ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1893flink:vkCmdSetDepthCompareOp, or by 1894endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1895slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp during 1896pipeline creation. 1897[eq]#z~f~# and [eq]#z~a~# are used as the _reference_ and _test_ values, 1898respectively, in the operation specified by the elink:VkCompareOp. 1899 1900If the comparison evaluates to false, the coverage for the sample is set to 1901`0`. 1902 1903 1904[[fragops-depth-write]] 1905=== Depth Attachment Writes 1906 1907If depth writes are enabled, as specified by 1908ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1909flink:vkCmdSetDepthWriteEnable or 1910endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1911slink:VkPipelineDepthStencilStateCreateInfo::pname:depthWriteEnable, and the 1912comparison evaluated to true, the depth attachment value [eq]#z~a~# is set 1913to the sample's depth value [eq]#z~f~#. 1914If there is no depth attachment, no value is written. 1915 1916ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1917[open,refpage='vkCmdSetDepthTestEnable',desc='Set depth test enable dynamically for a command buffer',type='protos',alias='vkCmdSetDepthTestEnableEXT'] 1918-- 1919To <<pipelines-dynamic-state, dynamically enable or disable>> the depth 1920test, call: 1921 1922ifdef::VK_VERSION_1_3[] 1923include::{generated}/api/protos/vkCmdSetDepthTestEnable.adoc[] 1924 1925ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 1926endif::VK_VERSION_1_3[] 1927 1928ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1929include::{generated}/api/protos/vkCmdSetDepthTestEnableEXT.adoc[] 1930endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1931 1932 * pname:commandBuffer is the command buffer into which the command will be 1933 recorded. 1934 * pname:depthTestEnable specifies if the depth test is enabled. 1935 1936This command sets the depth test enable for subsequent drawing commands 1937ifdef::VK_EXT_shader_object[] 1938ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 1939ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 1940endif::VK_EXT_shader_object[] 1941ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1942when the graphics pipeline is created with 1943ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE set in 1944slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1945endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1946Otherwise, this state is specified by the 1947slink:VkPipelineDepthStencilStateCreateInfo::pname:depthTestEnable value 1948used to create the currently active pipeline. 1949 1950:refpage: vkCmdSetDepthTestEnable 1951 1952.Valid Usage 1953**** 1954include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 1955**** 1956 1957include::{generated}/validity/protos/vkCmdSetDepthTestEnable.adoc[] 1958-- 1959 1960[open,refpage='vkCmdSetDepthCompareOp',desc='Set depth comparison operator dynamically for a command buffer',type='protos',alias='vkCmdSetDepthCompareOpEXT'] 1961-- 1962To <<pipelines-dynamic-state, dynamically set>> the depth compare operator, 1963call: 1964 1965ifdef::VK_VERSION_1_3[] 1966include::{generated}/api/protos/vkCmdSetDepthCompareOp.adoc[] 1967 1968ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 1969endif::VK_VERSION_1_3[] 1970 1971ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1972include::{generated}/api/protos/vkCmdSetDepthCompareOpEXT.adoc[] 1973endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 1974 1975 * pname:commandBuffer is the command buffer into which the command will be 1976 recorded. 1977 * pname:depthCompareOp is a elink:VkCompareOp value specifying the 1978 comparison operator used for the <<fragops-depth-comparison, Depth 1979 Comparison>> step of the <<fragops-depth,depth test>>. 1980 1981This command sets the depth comparison operator for subsequent drawing 1982commands 1983ifdef::VK_EXT_shader_object[] 1984ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 1985ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 1986endif::VK_EXT_shader_object[] 1987ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1988when the graphics pipeline is created with 1989ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP set in 1990slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1991endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1992Otherwise, this state is specified by the 1993slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp value used 1994to create the currently active pipeline. 1995 1996:refpage: vkCmdSetDepthCompareOp 1997 1998.Valid Usage 1999**** 2000include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 2001**** 2002 2003 2004include::{generated}/validity/protos/vkCmdSetDepthCompareOp.adoc[] 2005-- 2006 2007[open,refpage='vkCmdSetDepthWriteEnable',desc='Set depth write enable dynamically for a command buffer',type='protos',alias='vkCmdSetDepthWriteEnableEXT'] 2008-- 2009To <<pipelines-dynamic-state, dynamically set>> the depth write enable, 2010call: 2011 2012ifdef::VK_VERSION_1_3[] 2013include::{generated}/api/protos/vkCmdSetDepthWriteEnable.adoc[] 2014 2015ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] 2016endif::VK_VERSION_1_3[] 2017 2018ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 2019include::{generated}/api/protos/vkCmdSetDepthWriteEnableEXT.adoc[] 2020endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 2021 2022 * pname:commandBuffer is the command buffer into which the command will be 2023 recorded. 2024 * pname:depthWriteEnable specifies if depth writes are enabled. 2025 2026This command sets the depth write enable for subsequent drawing commands 2027ifdef::VK_EXT_shader_object[] 2028ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or] 2029ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] 2030endif::VK_EXT_shader_object[] 2031ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 2032when the graphics pipeline is created with 2033ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE set in 2034slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2035endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 2036Otherwise, this state is specified by the 2037slink:VkPipelineDepthStencilStateCreateInfo::pname:depthWriteEnable value 2038used to create the currently active pipeline. 2039 2040:refpage: vkCmdSetDepthWriteEnable 2041 2042.Valid Usage 2043**** 2044include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] 2045**** 2046 2047include::{generated}/validity/protos/vkCmdSetDepthWriteEnable.adoc[] 2048-- 2049endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] 2050 2051 2052ifdef::VK_NV_representative_fragment_test[] 2053[[fragops-rep-frag-test]] 2054== Representative Fragment Test 2055 2056The representative fragment test allows implementations to reduce the amount 2057of rasterization and fragment processing work performed for each point, 2058line, or triangle primitive. 2059For any primitive that produces one or more fragments that pass all prior 2060early fragment tests, the implementation may: choose one or more 2061"`representative`" fragments for processing and discard all other fragments. 2062For draw calls rendering multiple points, lines, or triangles arranged in 2063lists, strips, or fans, the representative fragment test is performed 2064independently for each of those primitives. 2065The set of fragments discarded by the representative fragment test is 2066implementation-dependent. 2067In some cases, the representative fragment test may not discard any 2068fragments for a given primitive. 2069 2070[open,refpage='VkPipelineRepresentativeFragmentTestStateCreateInfoNV',desc='Structure specifying representative fragment test',type='structs'] 2071-- 2072If the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo includes a 2073sname:VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure, then 2074that structure includes parameters controlling the representative fragment 2075test. 2076 2077The sname:VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure is 2078defined as: 2079 2080include::{generated}/api/structs/VkPipelineRepresentativeFragmentTestStateCreateInfoNV.adoc[] 2081 2082 * pname:sType is a elink:VkStructureType value identifying this structure. 2083 * pname:pNext is `NULL` or a pointer to a structure extending this 2084 structure. 2085 * pname:representativeFragmentTestEnable controls whether the 2086 representative fragment test is enabled. 2087 2088If this structure is not included in the pname:pNext chain, 2089pname:representativeFragmentTestEnable is considered to be ename:VK_FALSE, 2090and the representative fragment test is disabled. 2091 2092If the active fragment shader does not specify the code:EarlyFragmentTests 2093execution mode, the representative fragment shader test has no effect, even 2094if enabled. 2095 2096include::{generated}/validity/structs/VkPipelineRepresentativeFragmentTestStateCreateInfoNV.adoc[] 2097-- 2098 2099ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2100 2101[open,refpage='vkCmdSetRepresentativeFragmentTestEnableNV',desc='Specify the representative fragment test enable dynamically for a command buffer',type='protos'] 2102-- 2103To <<pipelines-dynamic-state, dynamically set>> the 2104pname:representativeFragmentTestEnable state, call: 2105 2106include::{generated}/api/protos/vkCmdSetRepresentativeFragmentTestEnableNV.adoc[] 2107 2108 * pname:commandBuffer is the command buffer into which the command will be 2109 recorded. 2110 * pname:representativeFragmentTestEnable specifies the 2111 pname:representativeFragmentTestEnable state. 2112 2113This command sets the pname:representativeFragmentTestEnable state for 2114subsequent drawing commands 2115ifdef::VK_EXT_shader_object[] 2116ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2117ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2118endif::VK_EXT_shader_object[] 2119ifdef::VK_EXT_extended_dynamic_state3[] 2120when the graphics pipeline is created with 2121ename:VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV set in 2122slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2123endif::VK_EXT_extended_dynamic_state3[] 2124Otherwise, this state is specified by the 2125slink:VkPipelineRepresentativeFragmentTestStateCreateInfoNV::pname:representativeFragmentTestEnable 2126value used to create the currently active pipeline. 2127 2128:refpage: vkCmdSetRepresentativeFragmentTestEnableNV 2129:requiredfeature: extendedDynamicState3RepresentativeFragmentTestEnable 2130 2131.Valid Usage 2132**** 2133include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2134**** 2135 2136include::{generated}/validity/protos/vkCmdSetRepresentativeFragmentTestEnableNV.adoc[] 2137-- 2138 2139endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2140 2141endif::VK_NV_representative_fragment_test[] 2142 2143 2144[[fragops-samplecount]] 2145== Sample Counting 2146 2147Occlusion queries use query pool entries to track the number of samples that 2148pass all the per-fragment tests. 2149The mechanism of collecting an occlusion query value is described in 2150<<queries-occlusion,Occlusion Queries>>. 2151 2152The occlusion query sample counter increments by one for each sample with a 2153coverage value of 1 in each fragment that survives all the per-fragment 2154tests, including scissor, 2155ifdef::VK_NV_scissor_exclusive[] 2156exclusive scissor, 2157endif::VK_NV_scissor_exclusive[] 2158sample mask, alpha to coverage, stencil, and depth tests. 2159 2160 2161ifdef::VK_NV_fragment_coverage_to_color[] 2162[[fragops-coverage-to-color]] 2163== Fragment Coverage to Color 2164 2165[open,refpage='VkPipelineCoverageToColorStateCreateInfoNV',desc='Structure specifying whether fragment coverage replaces a color',type='structs'] 2166-- 2167The sname:VkPipelineCoverageToColorStateCreateInfoNV structure is defined 2168as: 2169 2170include::{generated}/api/structs/VkPipelineCoverageToColorStateCreateInfoNV.adoc[] 2171 2172 * pname:sType is a elink:VkStructureType value identifying this structure. 2173 * pname:pNext is `NULL` or a pointer to a structure extending this 2174 structure. 2175 * pname:flags is reserved for future use. 2176 * pname:coverageToColorEnable controls whether the fragment coverage value 2177 replaces a fragment color output. 2178 * pname:coverageToColorLocation controls which fragment shader color 2179 output value is replaced. 2180 2181If the pname:pNext chain of slink:VkPipelineMultisampleStateCreateInfo 2182includes a sname:VkPipelineCoverageToColorStateCreateInfoNV structure, then 2183that structure controls whether the fragment coverage is substituted for a 2184fragment color output and, if so, which output is replaced. 2185 2186If pname:coverageToColorEnable is ename:VK_TRUE, the 2187<<primsrast-multisampling-coverage-mask, coverage mask>> replaces the first 2188component of the color value corresponding to the fragment shader output 2189location with code:Location equal to pname:coverageToColorLocation and 2190code:Index equal to zero. 2191If the color attachment format has fewer bits than the coverage mask, the 2192low bits of the sample coverage mask are taken without any clamping. 2193If the color attachment format has more bits than the coverage mask, the 2194high bits of the sample coverage mask are filled with zeros. 2195 2196If pname:coverageToColorEnable is ename:VK_FALSE, these operations are 2197skipped. 2198If this structure is not included in the pname:pNext chain, it is as if 2199pname:coverageToColorEnable is ename:VK_FALSE. 2200 2201.Valid Usage 2202**** 2203 * [[VUID-VkPipelineCoverageToColorStateCreateInfoNV-coverageToColorEnable-01404]] 2204 If pname:coverageToColorEnable is ename:VK_TRUE, then the render pass 2205 subpass indicated by 2206 slink:VkGraphicsPipelineCreateInfo::pname:renderPass and 2207 slink:VkGraphicsPipelineCreateInfo::pname:subpass must: have a color 2208 attachment at the location selected by pname:coverageToColorLocation, 2209 with a elink:VkFormat of ename:VK_FORMAT_R8_UINT, 2210 ename:VK_FORMAT_R8_SINT, ename:VK_FORMAT_R16_UINT, 2211 ename:VK_FORMAT_R16_SINT, ename:VK_FORMAT_R32_UINT, or 2212 ename:VK_FORMAT_R32_SINT 2213**** 2214 2215include::{generated}/validity/structs/VkPipelineCoverageToColorStateCreateInfoNV.adoc[] 2216-- 2217 2218[open,refpage='VkPipelineCoverageToColorStateCreateFlagsNV',desc='Reserved for future use',type='flags'] 2219-- 2220include::{generated}/api/flags/VkPipelineCoverageToColorStateCreateFlagsNV.adoc[] 2221 2222tname:VkPipelineCoverageToColorStateCreateFlagsNV is a bitmask type for 2223setting a mask, but is currently reserved for future use. 2224-- 2225 2226ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2227 2228[open,refpage='vkCmdSetCoverageToColorEnableNV',desc='Specify the coverage to color enable state dynamically for a command buffer',type='protos'] 2229-- 2230To <<pipelines-dynamic-state, dynamically set>> the 2231pname:coverageToColorEnable state, call: 2232 2233include::{generated}/api/protos/vkCmdSetCoverageToColorEnableNV.adoc[] 2234 2235 * pname:commandBuffer is the command buffer into which the command will be 2236 recorded. 2237 * pname:coverageToColorEnable specifies the pname:coverageToColorEnable 2238 state. 2239 2240This command sets the pname:coverageToColorEnable state for subsequent 2241drawing commands 2242ifdef::VK_EXT_shader_object[] 2243ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2244ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2245endif::VK_EXT_shader_object[] 2246ifdef::VK_EXT_extended_dynamic_state3[] 2247when the graphics pipeline is created with 2248ename:VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV set in 2249slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2250endif::VK_EXT_extended_dynamic_state3[] 2251Otherwise, this state is specified by the 2252slink:VkPipelineCoverageToColorStateCreateInfoNV::pname:coverageToColorEnable 2253value used to create the currently active pipeline. 2254 2255:refpage: vkCmdSetCoverageToColorEnableNV 2256:requiredfeature: extendedDynamicState3CoverageToColorEnable 2257 2258.Valid Usage 2259**** 2260include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2261**** 2262 2263include::{generated}/validity/protos/vkCmdSetCoverageToColorEnableNV.adoc[] 2264-- 2265 2266[open,refpage='vkCmdSetCoverageToColorLocationNV',desc='Specify the coverage to color location dynamically for a command buffer',type='protos'] 2267-- 2268To <<pipelines-dynamic-state, dynamically set>> the 2269pname:coverageToColorLocation state, call: 2270 2271include::{generated}/api/protos/vkCmdSetCoverageToColorLocationNV.adoc[] 2272 2273 * pname:commandBuffer is the command buffer into which the command will be 2274 recorded. 2275 * pname:coverageToColorLocation specifies the 2276 pname:coverageToColorLocation state. 2277 2278This command sets the pname:coverageToColorLocation state for subsequent 2279drawing commands 2280ifdef::VK_EXT_shader_object[] 2281ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2282ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2283endif::VK_EXT_shader_object[] 2284ifdef::VK_EXT_extended_dynamic_state3[] 2285when the graphics pipeline is created with 2286ename:VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV set in 2287slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2288endif::VK_EXT_extended_dynamic_state3[] 2289Otherwise, this state is specified by the 2290slink:VkPipelineCoverageToColorStateCreateInfoNV::pname:coverageToColorLocation 2291value used to create the currently active pipeline. 2292 2293:refpage: vkCmdSetCoverageToColorLocationNV 2294:requiredfeature: extendedDynamicState3CoverageToColorLocation 2295 2296.Valid Usage 2297**** 2298include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2299**** 2300 2301include::{generated}/validity/protos/vkCmdSetCoverageToColorLocationNV.adoc[] 2302-- 2303 2304endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2305 2306endif::VK_NV_fragment_coverage_to_color[] 2307 2308 2309[[fragops-coverage-reduction]] 2310== Coverage Reduction 2311 2312Coverage reduction takes the coverage information for a fragment and 2313converts that to a boolean coverage value for each color sample in each 2314pixel covered by the fragment. 2315 2316 2317=== Pixel Coverage 2318 2319Coverage for each pixel is first extracted from the total fragment coverage 2320mask. 2321This consists of pname:rasterizationSamples unique coverage samples for each 2322pixel in the fragment area, each with a unique 2323<<primsrast-multisampling-coverage-mask, sample index>>. 2324If the fragment only contains a single pixel, coverage for the pixel is 2325equivalent to the fragment coverage. 2326 2327ifdef::VK_EXT_fragment_density_map[] 2328If the render pass has a fragment density map attachment and the fragment 2329covers multiple pixels, pixel coverage is generated in an 2330implementation-dependent manner. 2331If all samples in the fragment are covered, all samples will be covered in 2332each pixel coverage. 2333endif::VK_EXT_fragment_density_map[] 2334 2335ifdef::VK_NV_shading_rate_image[] 2336If a <<primsrast-shading-rate-image,shading rate image>> is used, and the 2337fragment covers multiple pixels, each pixel's coverage consists of the 2338coverage samples corresponding to that pixel, and each sample retains its 2339unique <<primsrast-multisampling-coverage-mask, sample index [eq]#i#>>. 2340endif::VK_NV_shading_rate_image[] 2341 2342ifdef::VK_KHR_fragment_shading_rate[] 2343If the <<primsrast-fragment-shading-rate, fragment shading rate>> is set, 2344and the fragment covers multiple pixels, each pixel's coverage consists of 2345the coverage samples with a <<primsrast-multisampling-coverage-mask-vrfs, 2346pixel index>> matching that pixel, and each sample retains its unique 2347<<primsrast-multisampling-coverage-mask, sample index [eq]#i#>>. 2348endif::VK_KHR_fragment_shading_rate[] 2349 2350 2351=== Color Sample Coverage 2352 2353Once pixel coverage is determined, coverage for each individual color sample 2354corresponding to that pixel is determined. 2355 2356ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[If the] 2357ifndef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[The] 2358number of pname:rasterizationSamples is identical to the number of samples 2359in the color 2360ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[attachments, a] 2361ifndef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[attachments. A] 2362color sample is covered if the pixel coverage sample with the same 2363<<primsrast-multisampling-coverage-mask, sample index>> [eq]#i# is covered. 2364 2365ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[] 2366Otherwise, the coverage for each color sample is computed from the pixel 2367coverage as follows. 2368endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[] 2369 2370ifdef::VK_AMD_mixed_attachment_samples[] 2371If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, for 2372color samples present in the color attachments, a color sample is covered if 2373the pixel coverage sample with the same 2374<<primsrast-multisampling-coverage-mask, sample index>> [eq]#i# is covered; 2375additional pixel coverage samples are discarded. 2376endif::VK_AMD_mixed_attachment_samples[] 2377 2378ifdef::VK_EXT_multisampled_render_to_single_sampled[] 2379If the pname:pNext chain of slink:VkSubpassDescription2 2380ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[or slink:VkRenderingInfo] 2381includes a slink:VkMultisampledRenderToSingleSampledInfoEXT structure with 2382the pname:multisampledRenderToSingleSampledEnable field equal to 2383ename:VK_TRUE, sample coverage is calculated as if the attachment has 2384slink:VkMultisampledRenderToSingleSampledInfoEXT::pname:rasterizationSamples 2385samples. 2386endif::VK_EXT_multisampled_render_to_single_sampled[] 2387 2388ifdef::VK_NV_framebuffer_mixed_samples[] 2389 2390ifndef::VK_NV_coverage_reduction_mode[] 2391When the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, if 2392the pipeline's 2393slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples is 2394greater than the slink:VkAttachmentDescription::pname:samples of the color 2395attachments in the subpass, each color sample will be associated with an 2396implementation-dependent subset of samples in the pixel coverage. 2397If any of those associated samples are covered, the color sample is covered. 2398endif::VK_NV_coverage_reduction_mode[] 2399 2400ifdef::VK_NV_coverage_reduction_mode[] 2401When the `apiext:VK_NV_coverage_reduction_mode` extension is enabled, the 2402pipeline state controlling coverage reduction is specified through the 2403members of the sname:VkPipelineCoverageReductionStateCreateInfoNV structure. 2404 2405[open,refpage='VkPipelineCoverageReductionStateCreateInfoNV',desc='Structure specifying parameters controlling coverage reduction',type='structs'] 2406-- 2407The sname:VkPipelineCoverageReductionStateCreateInfoNV structure is defined 2408as: 2409 2410include::{generated}/api/structs/VkPipelineCoverageReductionStateCreateInfoNV.adoc[] 2411 2412 * pname:sType is a elink:VkStructureType value identifying this structure. 2413 * pname:pNext is `NULL` or a pointer to a structure extending this 2414 structure. 2415 * pname:flags is reserved for future use. 2416 * pname:coverageReductionMode is a elink:VkCoverageReductionModeNV value 2417 controlling how color sample coverage is generated from pixel coverage. 2418 2419If this structure is not included in the pname:pNext chain, or if the 2420extension is not enabled, the default coverage reduction mode is inferred as 2421follows: 2422 2423 * If the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, 2424 then it is as if the pname:coverageReductionMode is 2425 ename:VK_COVERAGE_REDUCTION_MODE_MERGE_NV. 2426 * If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, 2427 then it is as if the pname:coverageReductionMode is 2428 ename:VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV. 2429 * If both `apiext:VK_NV_framebuffer_mixed_samples` and 2430 `apiext:VK_AMD_mixed_attachment_samples` are enabled, then the default 2431 coverage reduction mode is implementation-dependent. 2432 2433include::{generated}/validity/structs/VkPipelineCoverageReductionStateCreateInfoNV.adoc[] 2434-- 2435 2436[open,refpage='VkPipelineCoverageReductionStateCreateFlagsNV',desc='Reserved for future use',type='flags'] 2437-- 2438include::{generated}/api/flags/VkPipelineCoverageReductionStateCreateFlagsNV.adoc[] 2439 2440tname:VkPipelineCoverageReductionStateCreateFlagsNV is a bitmask type for 2441setting a mask, but is currently reserved for future use. 2442-- 2443 2444[open,refpage='VkCoverageReductionModeNV',desc='Specify the coverage reduction mode',type='enums'] 2445-- 2446Possible values of 2447slink:VkPipelineCoverageReductionStateCreateInfoNV::pname:coverageReductionMode, 2448specifying how color sample coverage is generated from pixel coverage, are: 2449 2450include::{generated}/api/enums/VkCoverageReductionModeNV.adoc[] 2451 2452 * ename:VK_COVERAGE_REDUCTION_MODE_MERGE_NV specifies that each color 2453 sample will be associated with an implementation-dependent subset of 2454 samples in the pixel coverage. 2455 If any of those associated samples are covered, the color sample is 2456 covered. 2457 * ename:VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV specifies that for color 2458 samples present in the color attachments, a color sample is covered if 2459 the pixel coverage sample with the same 2460 <<primsrast-multisampling-coverage-mask, sample index>> [eq]#i# is 2461 covered; other pixel coverage samples are discarded. 2462-- 2463 2464ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2465 2466[open,refpage='vkCmdSetCoverageReductionModeNV',desc='Specify the coverage reduction mode dynamically for a command buffer',type='protos'] 2467-- 2468To <<pipelines-dynamic-state, dynamically set>> the 2469pname:coverageReductionMode state, call: 2470 2471include::{generated}/api/protos/vkCmdSetCoverageReductionModeNV.adoc[] 2472 2473 * pname:commandBuffer is the command buffer into which the command will be 2474 recorded. 2475 * pname:coverageReductionMode specifies the pname:coverageReductionMode 2476 state. 2477 2478This command sets the pname:coverageReductionMode state for subsequent 2479drawing commands 2480ifdef::VK_EXT_shader_object[] 2481ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2482ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2483endif::VK_EXT_shader_object[] 2484ifdef::VK_EXT_extended_dynamic_state3[] 2485when the graphics pipeline is created with 2486ename:VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV set in 2487slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2488endif::VK_EXT_extended_dynamic_state3[] 2489Otherwise, this state is specified by the 2490slink:VkPipelineCoverageReductionStateCreateInfoNV::pname:coverageReductionMode 2491value used to create the currently active pipeline. 2492 2493:refpage: vkCmdSetCoverageReductionModeNV 2494:requiredfeature: extendedDynamicState3CoverageReductionMode 2495 2496.Valid Usage 2497**** 2498include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2499**** 2500 2501include::{generated}/validity/protos/vkCmdSetCoverageReductionModeNV.adoc[] 2502-- 2503 2504endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2505 2506[open,refpage='vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV',desc='Query supported sample count combinations',type='protos'] 2507-- 2508To query the set of mixed sample combinations of coverage reduction mode, 2509rasterization samples and color, depth, stencil attachment sample counts 2510that are supported by a physical device, call: 2511 2512include::{generated}/api/protos/vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV.adoc[] 2513 2514 * pname:physicalDevice is the physical device from which to query the set 2515 of combinations. 2516 * pname:pCombinationCount is a pointer to an integer related to the number 2517 of combinations available or queried, as described below. 2518 * pname:pCombinations is either `NULL` or a pointer to an array of 2519 slink:VkFramebufferMixedSamplesCombinationNV values, indicating the 2520 supported combinations of coverage reduction mode, rasterization 2521 samples, and color, depth, stencil attachment sample counts. 2522 2523If pname:pCombinations is `NULL`, then the number of supported combinations 2524for the given pname:physicalDevice is returned in pname:pCombinationCount. 2525Otherwise, pname:pCombinationCount must: point to a variable set by the user 2526to the number of elements in the pname:pCombinations array, and on return 2527the variable is overwritten with the number of values actually written to 2528pname:pCombinations. 2529If the value of pname:pCombinationCount is less than the number of 2530combinations supported for the given pname:physicalDevice, at most 2531pname:pCombinationCount values will be written to pname:pCombinations, and 2532ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to 2533indicate that not all the supported values were returned. 2534 2535include::{generated}/validity/protos/vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV.adoc[] 2536-- 2537 2538[open,refpage='VkFramebufferMixedSamplesCombinationNV',desc='Structure specifying a supported sample count combination',type='structs'] 2539-- 2540The sname:VkFramebufferMixedSamplesCombinationNV structure is defined as: 2541 2542include::{generated}/api/structs/VkFramebufferMixedSamplesCombinationNV.adoc[] 2543 2544 * pname:sType is a elink:VkStructureType value identifying this structure. 2545 * pname:pNext is `NULL` or a pointer to a structure extending this 2546 structure. 2547 * pname:coverageReductionMode is a elink:VkCoverageReductionModeNV value 2548 specifying the coverage reduction mode. 2549 * pname:rasterizationSamples is a elink:VkSampleCountFlagBits specifying 2550 the number of rasterization samples in the supported combination. 2551 * pname:depthStencilSamples specifies the number of samples in the depth 2552 stencil attachment in the supported combination. 2553 A value of 0 indicates the combination does not have a depth stencil 2554 attachment. 2555 * pname:colorSamples specifies the number of color samples in a color 2556 attachment in the supported combination. 2557 A value of 0 indicates the combination does not have a color attachment. 2558 2559include::{generated}/validity/structs/VkFramebufferMixedSamplesCombinationNV.adoc[] 2560-- 2561endif::VK_NV_coverage_reduction_mode[] 2562 2563 2564[[fragops-coverage-modulation]] 2565=== Coverage Modulation 2566 2567[open,refpage='VkPipelineCoverageModulationStateCreateInfoNV',desc='Structure specifying parameters controlling coverage modulation',type='structs'] 2568-- 2569As part of coverage reduction, fragment color values can: also be modulated 2570(multiplied) by a value that is a function of fraction of covered 2571rasterization samples associated with that color sample. 2572 2573Pipeline state controlling coverage modulation is specified through the 2574members of the sname:VkPipelineCoverageModulationStateCreateInfoNV 2575structure. 2576 2577The sname:VkPipelineCoverageModulationStateCreateInfoNV structure is defined 2578as: 2579 2580include::{generated}/api/structs/VkPipelineCoverageModulationStateCreateInfoNV.adoc[] 2581 2582 * pname:sType is a elink:VkStructureType value identifying this structure. 2583 * pname:pNext is `NULL` or a pointer to a structure extending this 2584 structure. 2585 * pname:flags is reserved for future use. 2586 * pname:coverageModulationMode is a elink:VkCoverageModulationModeNV value 2587 controlling which color components are modulated. 2588 * pname:coverageModulationTableEnable controls whether the modulation 2589 factor is looked up from a table in pname:pCoverageModulationTable. 2590 * pname:coverageModulationTableCount is the number of elements in 2591 pname:pCoverageModulationTable. 2592 * pname:pCoverageModulationTable is a table of modulation factors 2593 containing a value for each number of covered samples. 2594 2595If pname:coverageModulationTableEnable is ename:VK_FALSE, then for each 2596color sample the associated bits of the pixel coverage are counted and 2597divided by the number of associated bits to produce a modulation factor 2598[eq]#R# in the range [eq]#(0,1]# (a value of zero would have been killed due 2599to a color coverage of 0). 2600Specifically: 2601 2602 * [eq]#N# = value of pname:rasterizationSamples 2603 * [eq]#M# = value of slink:VkAttachmentDescription::pname:samples for any 2604 color attachments 2605 * [eq]#R = popcount(associated coverage bits) / (N / M)# 2606 2607If pname:coverageModulationTableEnable is ename:VK_TRUE, the value [eq]#R# 2608is computed using a programmable lookup table. 2609The lookup table has [eq]#N / M# elements, and the element of the table is 2610selected by: 2611 2612 * [eq]#R = pname:pCoverageModulationTable[popcount(associated coverage 2613 bits)-1]# 2614 2615Note that the table does not have an entry for [eq]#popcount(associated 2616coverage bits) = 0#, because such samples would have been killed. 2617 2618The values of pname:pCoverageModulationTable may: be rounded to an 2619implementation-dependent precision, which is at least as fine as [eq]#1 / 2620N#, and clamped to [eq]#[0,1]#. 2621 2622For each color attachment with a floating point or normalized color format, 2623each fragment output color value is replicated to [eq]#M# values which can: 2624each be modulated (multiplied) by that color sample's associated value of 2625[eq]#R#. 2626Which components are modulated is controlled by 2627pname:coverageModulationMode. 2628 2629If this structure is not included in the pname:pNext chain, it is as if 2630pname:coverageModulationMode is ename:VK_COVERAGE_MODULATION_MODE_NONE_NV. 2631 2632ifdef::VK_NV_coverage_reduction_mode[] 2633If the <<fragops-coverage-reduction, coverage reduction mode>> is 2634ename:VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV, each color sample is 2635associated with only a single coverage sample. 2636In this case, it is as if pname:coverageModulationMode is 2637ename:VK_COVERAGE_MODULATION_MODE_NONE_NV. 2638endif::VK_NV_coverage_reduction_mode[] 2639 2640.Valid Usage 2641**** 2642 * [[VUID-VkPipelineCoverageModulationStateCreateInfoNV-coverageModulationTableEnable-01405]] 2643 If pname:coverageModulationTableEnable is ename:VK_TRUE, 2644 pname:coverageModulationTableCount must: be equal to the number of 2645 rasterization samples divided by the number of color samples in the 2646 subpass 2647**** 2648 2649include::{generated}/validity/structs/VkPipelineCoverageModulationStateCreateInfoNV.adoc[] 2650-- 2651 2652[open,refpage='VkPipelineCoverageModulationStateCreateFlagsNV',desc='Reserved for future use',type='flags'] 2653-- 2654include::{generated}/api/flags/VkPipelineCoverageModulationStateCreateFlagsNV.adoc[] 2655 2656tname:VkPipelineCoverageModulationStateCreateFlagsNV is a bitmask type for 2657setting a mask, but is currently reserved for future use. 2658-- 2659 2660[open,refpage='VkCoverageModulationModeNV',desc='Specify the coverage modulation mode',type='enums'] 2661-- 2662Possible values of 2663slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationMode, 2664specifying which color components are modulated, are: 2665 2666include::{generated}/api/enums/VkCoverageModulationModeNV.adoc[] 2667 2668 * ename:VK_COVERAGE_MODULATION_MODE_NONE_NV specifies that no components 2669 are multiplied by the modulation factor. 2670 * ename:VK_COVERAGE_MODULATION_MODE_RGB_NV specifies that the red, green, 2671 and blue components are multiplied by the modulation factor. 2672 * ename:VK_COVERAGE_MODULATION_MODE_ALPHA_NV specifies that the alpha 2673 component is multiplied by the modulation factor. 2674 * ename:VK_COVERAGE_MODULATION_MODE_RGBA_NV specifies that all components 2675 are multiplied by the modulation factor. 2676-- 2677 2678ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2679 2680[open,refpage='vkCmdSetCoverageModulationModeNV',desc='Specify the coverage modulation mode dynamically for a command buffer',type='protos'] 2681-- 2682To <<pipelines-dynamic-state, dynamically set>> the 2683pname:coverageModulationMode state, call: 2684 2685include::{generated}/api/protos/vkCmdSetCoverageModulationModeNV.adoc[] 2686 2687 * pname:commandBuffer is the command buffer into which the command will be 2688 recorded. 2689 * pname:coverageModulationMode specifies the pname:coverageModulationMode 2690 state. 2691 2692This command sets the pname:coverageModulationMode state for subsequent 2693drawing commands 2694ifdef::VK_EXT_shader_object[] 2695ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2696ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2697endif::VK_EXT_shader_object[] 2698ifdef::VK_EXT_extended_dynamic_state3[] 2699the graphics pipeline is created with 2700ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV set in 2701slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2702endif::VK_EXT_extended_dynamic_state3[] 2703Otherwise, this state is specified by the 2704slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationMode 2705value used to create the currently active pipeline. 2706 2707:refpage: vkCmdSetCoverageModulationModeNV 2708:requiredfeature: extendedDynamicState3CoverageModulationMode 2709 2710.Valid Usage 2711**** 2712include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2713**** 2714 2715include::{generated}/validity/protos/vkCmdSetCoverageModulationModeNV.adoc[] 2716-- 2717 2718[open,refpage='vkCmdSetCoverageModulationTableEnableNV',desc='Specify the coverage modulation table enable state dynamically for a command buffer',type='protos'] 2719-- 2720To <<pipelines-dynamic-state, dynamically set>> the 2721pname:coverageModulationTableEnable state, call: 2722 2723include::{generated}/api/protos/vkCmdSetCoverageModulationTableEnableNV.adoc[] 2724 2725 * pname:commandBuffer is the command buffer into which the command will be 2726 recorded. 2727 * pname:coverageModulationTableEnable specifies the 2728 pname:coverageModulationTableEnable state. 2729 2730This command sets the pname:coverageModulationTableEnable state for 2731subsequent drawing commands 2732ifdef::VK_EXT_shader_object[] 2733ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2734ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2735endif::VK_EXT_shader_object[] 2736ifdef::VK_EXT_extended_dynamic_state3[] 2737when the graphics pipeline is created with 2738ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV set in 2739slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2740endif::VK_EXT_extended_dynamic_state3[] 2741Otherwise, this state is specified by the 2742slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationTableEnable 2743value used to create the currently active pipeline. 2744 2745:refpage: vkCmdSetCoverageModulationTableEnableNV 2746:requiredfeature: extendedDynamicState3CoverageModulationTableEnable 2747 2748.Valid Usage 2749**** 2750include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2751**** 2752 2753include::{generated}/validity/protos/vkCmdSetCoverageModulationTableEnableNV.adoc[] 2754-- 2755 2756[open,refpage='vkCmdSetCoverageModulationTableNV',desc='Specify the coverage modulation table dynamically for a command buffer',type='protos'] 2757-- 2758To <<pipelines-dynamic-state, dynamically set>> the 2759pname:pCoverageModulationTable state, call: 2760 2761include::{generated}/api/protos/vkCmdSetCoverageModulationTableNV.adoc[] 2762 2763 * pname:commandBuffer is the command buffer into which the command will be 2764 recorded. 2765 * pname:coverageModulationTableCount specifies the number of elements in 2766 pname:pCoverageModulationTable. 2767 * pname:pCoverageModulationTable specifies the table of modulation factors 2768 containing a value for each number of covered samples. 2769 2770This command sets the table of modulation factors for subsequent drawing 2771commands 2772ifdef::VK_EXT_shader_object[] 2773ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or] 2774ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] 2775endif::VK_EXT_shader_object[] 2776ifdef::VK_EXT_extended_dynamic_state3[] 2777when the graphics pipeline is created with 2778ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV set in 2779slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 2780endif::VK_EXT_extended_dynamic_state3[] 2781Otherwise, this state is specified by the 2782slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationTableCount, 2783and 2784slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:pCoverageModulationTable 2785values used to create the currently active pipeline. 2786 2787:refpage: vkCmdSetCoverageModulationTableNV 2788:requiredfeature: extendedDynamicState3CoverageModulationTable 2789 2790.Valid Usage 2791**** 2792include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] 2793**** 2794 2795include::{generated}/validity/protos/vkCmdSetCoverageModulationTableNV.adoc[] 2796-- 2797 2798endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] 2799 2800endif::VK_NV_framebuffer_mixed_samples[] 2801