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