1// Copyright 2015-2021 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_KHR_shader_terminate_invocation[] 59 * code:OpTerminateInvocation 60endif::VK_KHR_shader_terminate_invocation[] 61ifdef::VK_EXT_shader_demote_to_helper_invocation[] 62 * code:OpDemoteToHelperInvocationEXT 63endif::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 the <<fragops-shader, fragment shader>> 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 the <<fragops-shader, fragment shader>> declares the 77code:EarlyFragmentTests execution mode, <<fragops-shader,fragment shading>> 78and <<fragops-covg, multisample coverage>> operations are instead performed 79after <<fragops-samplecount, sample counting>>. 80 81Once all fragment operations have completed, fragment shader outputs for 82covered color attachment samples pass through <<framebuffer, framebuffer 83operations>>. 84 85 86ifdef::VK_EXT_discard_rectangles[] 87[[fragops-discard-rectangles]] 88== Discard Rectangles Test 89 90The discard rectangle test compares the framebuffer coordinates 91[eq]#(x~f~,y~f~)# of each sample covered by a fragment against a set of 92_discard rectangles_. 93 94Each discard rectangle is defined by a slink:VkRect2D. 95These values are either set by the 96slink:VkPipelineDiscardRectangleStateCreateInfoEXT structure during pipeline 97creation, or dynamically by the flink:vkCmdSetDiscardRectangleEXT command. 98 99A given sample is considered inside a discard rectangle if the [eq]#x~f~# is 100in the range [eq]#[slink:VkRect2D::offset.x, slink:VkRect2D::offset.x {plus} 101slink:VkRect2D::extent.x)#, and [eq]#y~f~# is in the range 102[eq]#[slink:VkRect2D::offset.y, slink:VkRect2D::offset.y {plus} 103slink:VkRect2D::extent.y)#. 104If the test is set to be inclusive, samples that are not inside any of the 105discard rectangles will have their coverage set to `0`. 106If the test is set to be exclusive, samples that are inside any of the 107discard rectangles will have their coverage set to `0`. 108 109If no discard rectangles are specified, the coverage mask is unmodified by 110this operation. 111 112[open,refpage='VkPipelineDiscardRectangleStateCreateInfoEXT',desc='Structure specifying discard rectangle',type='structs'] 113-- 114The sname:VkPipelineDiscardRectangleStateCreateInfoEXT structure is defined 115as: 116 117include::{generated}/api/structs/VkPipelineDiscardRectangleStateCreateInfoEXT.txt[] 118 119 * pname:sType is the type of this structure. 120 * pname:pNext is `NULL` or a pointer to a structure extending this 121 structure. 122 * pname:flags is reserved for future use. 123 * pname:discardRectangleMode is a elink:VkDiscardRectangleModeEXT value 124 determining whether the discard rectangle test is inclusive or 125 exclusive. 126 * pname:discardRectangleCount is the number of discard rectangles to use. 127 * pname:pDiscardRectangles is a pointer to an array of slink:VkRect2D 128 structures defining discard rectangles. 129 130If the ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state is enabled 131for a pipeline, the pname:pDiscardRectangles member is ignored. 132 133When this structure is included in the pname:pNext chain of 134slink:VkGraphicsPipelineCreateInfo, it defines parameters of the discard 135rectangle test. 136If this structure is not included in the pname:pNext chain, it is equivalent 137to specifying this structure with a pname:discardRectangleCount of `0`. 138 139.Valid Usage 140**** 141 * [[VUID-VkPipelineDiscardRectangleStateCreateInfoEXT-discardRectangleCount-00582]] 142 pname:discardRectangleCount must: be less than or equal to 143 sname:VkPhysicalDeviceDiscardRectanglePropertiesEXT::pname:maxDiscardRectangles 144**** 145 146include::{generated}/validity/structs/VkPipelineDiscardRectangleStateCreateInfoEXT.txt[] 147-- 148 149[open,refpage='VkPipelineDiscardRectangleStateCreateFlagsEXT',desc='Reserved for future use',type='flags'] 150-- 151include::{generated}/api/flags/VkPipelineDiscardRectangleStateCreateFlagsEXT.txt[] 152 153tname:VkPipelineDiscardRectangleStateCreateFlagsEXT is a bitmask type for 154setting a mask, but is currently reserved for future use. 155-- 156 157[open,refpage='VkDiscardRectangleModeEXT',desc='Specify the discard rectangle mode',type='enums'] 158-- 159ename:VkDiscardRectangleModeEXT values are: 160 161include::{generated}/api/enums/VkDiscardRectangleModeEXT.txt[] 162 163 * ename:VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT specifies that the discard 164 rectangle test is inclusive. 165 * ename:VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT specifies that the discard 166 rectangle test is exclusive. 167-- 168 169[open,refpage='vkCmdSetDiscardRectangleEXT',desc='Set discard rectangles dynamically for a command buffer',type='protos'] 170-- 171To <<pipelines-dynamic-state, dynamically set>> the discard rectangles, 172call: 173 174include::{generated}/api/protos/vkCmdSetDiscardRectangleEXT.txt[] 175 176 * pname:commandBuffer is the command buffer into which the command will be 177 recorded. 178 * pname:firstDiscardRectangle is the index of the first discard rectangle 179 whose state is updated by the command. 180 * pname:discardRectangleCount is the number of discard rectangles whose 181 state are updated by the command. 182 * pname:pDiscardRectangles is a pointer to an array of slink:VkRect2D 183 structures specifying discard rectangles. 184 185The discard rectangle taken from element [eq]#i# of pname:pDiscardRectangles 186replace the current state for the discard rectangle at index 187[eq]#pname:firstDiscardRectangle {plus} i#, for [eq]#i# in [eq]#[0, 188pname:discardRectangleCount)#. 189 190This command sets the discard rectangles for subsequent drawing commands 191when the graphics pipeline is created with 192ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT set in 193slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 194Otherwise, this state is specified by the 195slink:VkPipelineDiscardRectangleStateCreateInfoEXT::pname:pDiscardRectangles 196values used to create the currently active pipeline. 197 198.Valid Usage 199**** 200 * [[VUID-vkCmdSetDiscardRectangleEXT-firstDiscardRectangle-00585]] 201 The sum of pname:firstDiscardRectangle and pname:discardRectangleCount 202 must: be less than or equal to 203 slink:VkPhysicalDeviceDiscardRectanglePropertiesEXT::pname:maxDiscardRectangles 204 * [[VUID-vkCmdSetDiscardRectangleEXT-x-00587]] 205 The pname:x and pname:y member of pname:offset in each slink:VkRect2D 206 element of pname:pDiscardRectangles must: be greater than or equal to 207 `0` 208 * [[VUID-vkCmdSetDiscardRectangleEXT-offset-00588]] 209 Evaluation of [eq]#(pname:offset.x {plus} pname:extent.width)# in each 210 slink:VkRect2D element of pname:pDiscardRectangles must: not cause a 211 signed integer addition overflow 212 * [[VUID-vkCmdSetDiscardRectangleEXT-offset-00589]] 213 Evaluation of [eq]#(pname:offset.y {plus} pname:extent.height)# in each 214 slink:VkRect2D element of pname:pDiscardRectangles must: not cause a 215 signed integer addition overflow 216ifdef::VK_NV_inherited_viewport_scissor[] 217 * [[VUID-vkCmdSetDiscardRectangleEXT-viewportScissor2D-04788]] 218 If this command is recorded in a secondary command buffer with 219 slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D 220 enabled, then this function must: not be called 221endif::VK_NV_inherited_viewport_scissor[] 222**** 223 224include::{generated}/validity/protos/vkCmdSetDiscardRectangleEXT.txt[] 225-- 226endif::VK_EXT_discard_rectangles[] 227 228 229[[fragops-scissor]] 230== Scissor Test 231 232The scissor test compares the framebuffer coordinates [eq]#(x~f~,y~f~)# of 233each sample covered by a fragment against a _scissor rectangle_ at the index 234equal to the fragment's <<interfaces-builtin-variables-viewportindex, 235code:ViewportIndex>>. 236 237Each scissor rectangle is defined by a slink:VkRect2D. 238These values are either set by the slink:VkPipelineViewportStateCreateInfo 239structure during pipeline creation, or dynamically by the 240flink:vkCmdSetScissor command. 241 242A given sample is considered inside a scissor rectangle if [eq]#x~f~# is in 243the range [eq]#[slink:VkRect2D::offset.x, slink:VkRect2D::offset.x {plus} 244slink:VkRect2D::extent.x)#, and [eq]#y~f~# is in the range 245[eq]#[slink:VkRect2D::offset.y, slink:VkRect2D::offset.y {plus} 246slink:VkRect2D::extent.y)#. 247Samples with coordinates outside the scissor rectangle at the corresponding 248code:ViewportIndex will have their coverage set to `0`. 249 250ifdef::VK_QCOM_render_pass_transform[] 251If a render pass transform is enabled, the (pname:offset.x and 252pname:offset.y) and (pname:extent.width and pname:extent.height) values are 253transformed as described in <<vertexpostproc-renderpass-transform, render 254pass transform>> before participating in the scissor test. 255endif::VK_QCOM_render_pass_transform[] 256 257[open,refpage='vkCmdSetScissor',desc='Set scissor rectangles dynamically for a command buffer',type='protos'] 258-- 259To <<pipelines-dynamic-state, dynamically set>> the scissor rectangles, 260call: 261 262include::{generated}/api/protos/vkCmdSetScissor.txt[] 263 264 * pname:commandBuffer is the command buffer into which the command will be 265 recorded. 266 * pname:firstScissor is the index of the first scissor whose state is 267 updated by the command. 268 * pname:scissorCount is the number of scissors whose rectangles are 269 updated by the command. 270 * pname:pScissors is a pointer to an array of slink:VkRect2D structures 271 defining scissor rectangles. 272 273The scissor rectangles taken from element [eq]#i# of pname:pScissors replace 274the current state for the scissor index [eq]#pname:firstScissor {plus} i#, 275for [eq]#i# in [eq]#[0, pname:scissorCount)#. 276 277This command sets the scissor rectangles for subsequent drawing commands 278when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_SCISSOR 279set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 280Otherwise, this state is specified by the 281slink:VkPipelineViewportStateCreateInfo::pname:pScissors values used to 282create the currently active pipeline. 283 284.Valid Usage 285**** 286 * [[VUID-vkCmdSetScissor-firstScissor-00592]] 287 The sum of pname:firstScissor and pname:scissorCount must: be between 288 `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive 289 * [[VUID-vkCmdSetScissor-firstScissor-00593]] 290 If the <<features-multiViewport,multiple viewports>> feature is not 291 enabled, pname:firstScissor must: be `0` 292 * [[VUID-vkCmdSetScissor-scissorCount-00594]] 293 If the <<features-multiViewport,multiple viewports>> feature is not 294 enabled, pname:scissorCount must: be `1` 295 * [[VUID-vkCmdSetScissor-x-00595]] 296 The pname:x and pname:y members of pname:offset member of any element of 297 pname:pScissors must: be greater than or equal to `0` 298 * [[VUID-vkCmdSetScissor-offset-00596]] 299 Evaluation of [eq]#(pname:offset.x {plus} pname:extent.width)# must: not 300 cause a signed integer addition overflow for any element of 301 pname:pScissors 302 * [[VUID-vkCmdSetScissor-offset-00597]] 303 Evaluation of [eq]#(pname:offset.y {plus} pname:extent.height)# must: 304 not cause a signed integer addition overflow for any element of 305 pname:pScissors 306ifdef::VK_NV_inherited_viewport_scissor[] 307 * [[VUID-vkCmdSetScissor-viewportScissor2D-04789]] 308 If this command is recorded in a secondary command buffer with 309 slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D 310 enabled, then this function must: not be called 311endif::VK_NV_inherited_viewport_scissor[] 312**** 313 314include::{generated}/validity/protos/vkCmdSetScissor.txt[] 315-- 316 317 318ifdef::VK_NV_scissor_exclusive[] 319[[fragops-exclusive-scissor]] 320== Exclusive Scissor Test 321 322The exclusive scissor test compares the framebuffer coordinates 323[eq]#(x~f~,y~f~)# of each sample covered by a fragment against an _exclusive 324scissor rectangle_ at the index equal to the fragment's 325<<interfaces-builtin-variables-viewportindex, code:ViewportIndex>>. 326 327Each exclusive scissor rectangle is defined by a slink:VkRect2D. 328These values are either set by the 329slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV structure during 330pipeline creation, or dynamically by the flink:vkCmdSetExclusiveScissorNV 331command. 332 333A given sample is considered inside an exclusive scissor rectangle if 334[eq]#x~f~# is in the range [eq]#[slink:VkRect2D::offset.x, 335slink:VkRect2D::offset.x {plus} slink:VkRect2D::extent.x)#, and [eq]#y~f~# 336is in the range [eq]#[slink:VkRect2D::offset.y, slink:VkRect2D::offset.y 337{plus} slink:VkRect2D::extent.y)#. 338Samples with coordinates inside the exclusive scissor rectangle at the 339corresponding code:ViewportIndex will have their coverage set to `0`. 340 341If no exclusive scissor rectangles are specified, the coverage mask is 342unmodified by this operation. 343 344[open,refpage='VkPipelineViewportExclusiveScissorStateCreateInfoNV',desc='Structure specifying parameters controlling exclusive scissor testing',type='structs'] 345-- 346The sname:VkPipelineViewportExclusiveScissorStateCreateInfoNV structure is 347defined as: 348 349include::{generated}/api/structs/VkPipelineViewportExclusiveScissorStateCreateInfoNV.txt[] 350 351 * pname:sType is the type of this structure. 352 * pname:pNext is `NULL` or a pointer to a structure extending this 353 structure. 354 * pname:exclusiveScissorCount is the number of exclusive scissor 355 rectangles. 356 * pname:pExclusiveScissors is a pointer to an array of slink:VkRect2D 357 structures defining exclusive scissor rectangles. 358 359If the ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV dynamic state is enabled 360for a pipeline, the pname:pExclusiveScissors member is ignored. 361 362When this structure is included in the pname:pNext chain of 363slink:VkGraphicsPipelineCreateInfo, it defines parameters of the exclusive 364scissor test. 365If this structure is not included in the pname:pNext chain, it is equivalent 366to specifying this structure with a pname:exclusiveScissorCount of `0`. 367 368.Valid Usage 369**** 370 * [[VUID-VkPipelineViewportExclusiveScissorStateCreateInfoNV-exclusiveScissorCount-02027]] 371 If the <<features-multiViewport,multiple viewports>> feature is not 372 enabled, pname:exclusiveScissorCount must: be `0` or `1` 373 * [[VUID-VkPipelineViewportExclusiveScissorStateCreateInfoNV-exclusiveScissorCount-02028]] 374 pname:exclusiveScissorCount must: be less than or equal to 375 sname:VkPhysicalDeviceLimits::pname:maxViewports 376 * [[VUID-VkPipelineViewportExclusiveScissorStateCreateInfoNV-exclusiveScissorCount-02029]] 377 pname:exclusiveScissorCount must: be `0` or greater than or equal to the 378 pname:viewportCount member of slink:VkPipelineViewportStateCreateInfo 379 380**** 381include::{generated}/validity/structs/VkPipelineViewportExclusiveScissorStateCreateInfoNV.txt[] 382-- 383 384[open,refpage='vkCmdSetExclusiveScissorNV',desc='Set exclusive scissor rectangles dynamically for a command buffer',type='protos'] 385-- 386To <<pipelines-dynamic-state, dynamically set>> the exclusive scissor 387rectangles, call: 388 389include::{generated}/api/protos/vkCmdSetExclusiveScissorNV.txt[] 390 391 * pname:commandBuffer is the command buffer into which the command will be 392 recorded. 393 * pname:firstExclusiveScissor is the index of the first exclusive scissor 394 rectangle whose state is updated by the command. 395 * pname:exclusiveScissorCount is the number of exclusive scissor 396 rectangles updated by the command. 397 * pname:pExclusiveScissors is a pointer to an array of slink:VkRect2D 398 structures defining exclusive scissor rectangles. 399 400The scissor rectangles taken from element [eq]#i# of 401pname:pExclusiveScissors replace the current state for the scissor index 402[eq]#pname:firstExclusiveScissor {plus} i#, for [eq]#i# in [eq]#[0, 403pname:exclusiveScissorCount)#. 404 405This command sets the exclusive scissor rectangles for subsequent drawing 406commands when the graphics pipeline is created with 407ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV set in 408slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 409Otherwise, this state is specified by the 410slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV::pname:pExclusiveScissors 411values used to create the currently active pipeline. 412 413.Valid Usage 414**** 415 * [[VUID-vkCmdSetExclusiveScissorNV-None-02031]] 416 The <<features-exclusiveScissor,exclusive scissor>> feature must: be 417 enabled 418 * [[VUID-vkCmdSetExclusiveScissorNV-firstExclusiveScissor-02034]] 419 The sum of pname:firstExclusiveScissor and pname:exclusiveScissorCount 420 must: be between `1` and 421 sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive 422 * [[VUID-vkCmdSetExclusiveScissorNV-firstExclusiveScissor-02035]] 423 If the <<features-multiViewport,multiple viewports>> feature is not 424 enabled, pname:firstExclusiveScissor must: be `0` 425 * [[VUID-vkCmdSetExclusiveScissorNV-exclusiveScissorCount-02036]] 426 If the <<features-multiViewport,multiple viewports>> feature is not 427 enabled, pname:exclusiveScissorCount must: be `1` 428 * [[VUID-vkCmdSetExclusiveScissorNV-x-02037]] 429 The pname:x and pname:y members of pname:offset in each member of 430 pname:pExclusiveScissors must: be greater than or equal to `0` 431 * [[VUID-vkCmdSetExclusiveScissorNV-offset-02038]] 432 Evaluation of [eq]#(pname:offset.x {plus} pname:extent.width)# for each 433 member of pname:pExclusiveScissors must: not cause a signed integer 434 addition overflow 435 * [[VUID-vkCmdSetExclusiveScissorNV-offset-02039]] 436 Evaluation of [eq]#(pname:offset.y {plus} pname:extent.height)# for each 437 member of pname:pExclusiveScissors must: not cause a signed integer 438 addition overflow 439**** 440 441include::{generated}/validity/protos/vkCmdSetExclusiveScissorNV.txt[] 442-- 443endif::VK_NV_scissor_exclusive[] 444 445 446[[fragops-samplemask]] 447== Sample Mask Test 448 449The sample mask test compares the <<primsrast-multisampling-coverage-mask, 450coverage mask>> for a fragment with the _sample mask_ defined by 451slink:VkPipelineMultisampleStateCreateInfo::pname:pSampleMask. 452 453Each bit of the coverage mask is associated with a sample index as described 454in the <<primsrast-multisampling-coverage-mask, rasterization chapter>>. 455If the bit in slink:VkPipelineMultisampleStateCreateInfo::pname:pSampleMask 456which is associated with that same sample index is set to `0`, the coverage 457mask bit is set to `0`. 458 459 460[[fragops-shader]] 461== Fragment Shading 462 463<<shaders-fragment, Fragment shaders>> are invoked for each fragment, or as 464<<shaders-helper-invocations, helper invocations>>. 465 466Most operations in the fragment shader are not performed in 467<<primsrast-order, rasterization order>>, with exceptions called out in the 468following sections. 469 470For fragment shaders invoked by fragments, the following rules apply: 471 472 * A fragment shader must: not be executed if a <<fragops, fragment 473 operation>> that executes before fragment shading discards the fragment. 474 * A fragment shader may: not be executed if: 475 ** An implementation determines that another fragment shader, invoked by a 476 subsequent primitive in <<drawing-primitive-order, primitive order>>, 477 overwrites all results computed by the shader (including writes to 478 storage resources). 479 ** Any other <<fragops, fragment operation>> discards the fragment, and 480 the shader does not write to any storage resources. 481 * Otherwise, at least one fragment shader must: be executed. 482 ** If <<primsrast-sampleshading,sample shading>> is enabled and multiple 483 invocations per fragment are required:, additional invocations must: be 484 executed as specified. 485ifdef::VK_NV_shading_rate_image[] 486 ** If a <<primsrast-shading-rate-image,shading rate image>> is used and 487 multiple invocations per fragment are required:, additional invocations 488 must: be executed as specified. 489endif::VK_NV_shading_rate_image[] 490 ** Each covered sample must: be included in at least one fragment shader 491 invocation. 492 493 494[NOTE] 495.Note 496==== 497Multiple fragment shader invocations may be executed for the same fragment 498for any number of implementation-dependent reasons. 499When there is more than one fragment shader invocation per fragment, the 500association of samples to invocations is implementation-dependent. 501Stores and atomics performed by these additional invocations have the normal 502effect. 503 504ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 505For example, if the subpass includes multiple views in its view mask, a 506fragment shader may be invoked separately for each view. 507endif::VK_VERSION_1_1,VK_KHR_multiview[] 508 509ifdef::VK_EXT_fragment_density_map[] 510Similarly, if the render pass has a fragment density map attachment, more 511than one fragment shader invocation may be invoked for each covered sample. 512Such additional invocations are only produced if 513sname:VkPhysicalDeviceFragmentDensityMapPropertiesEXT::pname:fragmentDensityInvocations 514is ename:VK_TRUE. 515Implementations may generate these additional fragment shader invocations in 516order to make transitions between fragment areas with different fragment 517densities more smooth. 518endif::VK_EXT_fragment_density_map[] 519==== 520 521 522[[fragops-shader-samplemask]] 523=== Sample Mask 524 525Reading from the <<interfaces-builtin-variables-samplemask, 526code:SampleMask>> built-in in the code:Input storage class will return the 527coverage mask for the current fragment as calculated by fragment operations 528that executed prior to fragment shading. 529 530If <<primsrast-sampleshading, sample shading>> is enabled, fragment shaders 531will only see values of `1` for samples being shaded - other bits will be 532`0`. 533 534Each bit of the coverage mask is associated with a sample index as described 535in the <<primsrast-multisampling-coverage-mask, rasterization chapter>>. 536If the bit in code:SampleMask which is associated with that same sample 537index is set to `0`, that coverage mask bit is set to `0`. 538 539Values written to the <<interfaces-builtin-variables-samplemask, 540code:SampleMask>> built-in in the code:Output storage class will be used by 541the <<fragops-covg, multisample coverage>> operation, with the same encoding 542as the input built-in. 543 544 545[[fragops-shader-depthreplacement]] 546=== Depth Replacement 547 548Writing to the <<interfaces-builtin-variables-fragdepth,code:FragDepth>> 549built-in will replace the fragment's calculated depth values for each sample 550in the input code:SampleMask. 551<<fragops-depth, Depth testing>> performed after the fragment shader for 552this fragment will use this new value as [eq]#z~f~#. 553 554 555ifdef::VK_EXT_shader_stencil_export[] 556[[fragops-shader-stencilrefreplacement]] 557=== Stencil Reference Replacement 558 559Writing to the 560<<interfaces-builtin-variables-fragdepth,code:FragStencilRefEXT>> built-in 561will replace the fragment's stencil reference value for each sample in the 562input code:SampleMask. 563<<fragops-stencil, Stencil testing>> performed after the fragment shader for 564this fragment will use this new value as [eq]#s~r~#. 565endif::VK_EXT_shader_stencil_export[] 566 567 568ifdef::VK_EXT_fragment_shader_interlock[] 569[[fragops-shader-interlock]] 570=== Interlocked Operations 571 572code:OpBeginInvocationInterlockEXT and code:OpEndInvocationInterlockEXT 573define a section of a fragment shader which imposes additional ordering 574constraints on operations performed within them. 575These operations are defined as _interlocked operations_. 576How interlocked operations are ordered against other fragment shader 577invocations depends on the specified execution modes. 578 579ifdef::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 580If the code:ShadingRateInterlockOrderedEXT execution mode is specified, any 581interlocked operations in a fragment shader must: happen before interlocked 582operations in fragment shader invocations that execute later in 583<<primsrast-order, rasterization order>> and cover at least one sample in 584the same fragment area, and must: happen after interlocked operations in a 585fragment shader that executes earlier in <<primsrast-order, rasterization 586order>> and cover at least one sample in the same fragment area. 587 588If the code:ShadingRateInterlockUnorderedEXT execution mode is specified, 589any interlocked operations in a fragment shader must: happen before or after 590interlocked operations in fragment shader invocations that execute earlier 591or later in <<primsrast-order, rasterization order>> and cover at least one 592sample in the same fragment area. 593endif::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 594 595If the code:PixelInterlockOrderedEXT execution mode is specified, any 596interlocked operations in a fragment shader must: happen before interlocked 597operations in fragment shader invocations that execute later in 598<<primsrast-order, rasterization order>> and cover at least one sample in 599the same pixel, and must: happen after interlocked operations in a fragment 600shader that executes earlier in <<primsrast-order, rasterization order>> and 601cover at least one sample in the same pixel. 602 603If the code:PixelInterlockUnorderedEXT execution mode is specified, any 604interlocked operations in a fragment shader must: happen before or after 605interlocked operations in fragment shader invocations that execute earlier 606or later in <<primsrast-order, rasterization order>> and cover at least one 607sample in the same pixel. 608 609If the code:SampleInterlockOrderedEXT execution mode is specified, any 610interlocked operations in a fragment shader must: happen before interlocked 611operations in fragment shader invocations that execute later in 612<<primsrast-order, rasterization order>> and cover at least one of the same 613samples, and must: happen after interlocked operations in a fragment shader 614that executes earlier in <<primsrast-order, rasterization order>> and cover 615at least one of the same samples. 616 617If the code:SampleInterlockUnorderedEXT execution mode is specified, any 618interlocked operations in a fragment shader must: happen before or after 619interlocked operations in fragment shader invocations that execute earlier 620or later in <<primsrast-order, rasterization order>> and cover at least one 621of the same samples. 622endif::VK_EXT_fragment_shader_interlock[] 623 624 625[[fragops-covg]] 626== Multisample Coverage 627 628If a fragment shader is active and its entry point's interface includes a 629built-in output variable decorated with code:SampleMask, 630ifdef::VK_NV_sample_mask_override_coverage[] 631but not code:OverrideCoverageNV, 632endif::VK_NV_sample_mask_override_coverage[] 633the coverage mask is code:ANDed with the bits of the code:SampleMask 634built-in to generate a new coverage mask. 635ifdef::VK_NV_sample_mask_override_coverage[] 636If the code:SampleMask built-in is also decorated with 637code:OverrideCoverageNV, the coverage mask is replaced with the mask bits 638set in the shader. 639endif::VK_NV_sample_mask_override_coverage[] 640If <<primsrast-sampleshading,sample shading>> is enabled, bits written to 641code:SampleMask corresponding to samples that are not being shaded by the 642fragment shader invocation are ignored. 643If no fragment shader is active, or if the active fragment shader does not 644include code:SampleMask in its interface, the coverage mask is not modified. 645 646Next, the fragment alpha value and coverage mask are modified based on the 647ifdef::VK_EXT_line_rasterization[] 648line coverage factor if the pname:lineRasterizationMode member of the 649slink:VkPipelineRasterizationStateCreateInfo structure is 650ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, and the 651endif::VK_EXT_line_rasterization[] 652pname:alphaToCoverageEnable and pname:alphaToOneEnable members of the 653slink:VkPipelineMultisampleStateCreateInfo structure. 654 655All alpha values in this section refer only to the alpha component of the 656fragment shader output that has a code:Location and code:Index decoration of 657zero (see the <<interfaces-fragmentoutput,Fragment Output Interface>> 658section). 659If that shader output has an integer or unsigned integer type, then these 660operations are skipped. 661 662ifdef::VK_EXT_line_rasterization[] 663If the pname:lineRasterizationMode member of the 664slink:VkPipelineRasterizationStateCreateInfo structure is 665ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT and the fragment 666came from a line segment, then the alpha value is replaced by multiplying it 667by the coverage factor for the fragment computed during 668<<primsrast-lines-smooth,smooth line rasterization>>. 669endif::VK_EXT_line_rasterization[] 670 671If pname:alphaToCoverageEnable is enabled, a temporary coverage mask is 672generated where each bit is determined by the fragment's alpha value, which 673is ANDed with the fragment coverage mask. 674 675No specific algorithm is specified for converting the alpha value to a 676temporary coverage mask. 677It is intended that the number of 1's in this value be proportional to the 678alpha value (clamped to [eq]#[0,1]#), with all 1's corresponding to a value 679of 1.0 and all 0's corresponding to 0.0. 680The algorithm may: be different at different framebuffer coordinates. 681 682[NOTE] 683.Note 684==== 685Using different algorithms at different framebuffer coordinates may: help to 686avoid artifacts caused by regular coverage sample locations. 687==== 688 689Finally, if pname:alphaToOneEnable is enabled, each alpha value is replaced 690by the maximum representable alpha value for fixed-point color attachments, 691or by 1.0 for floating-point attachments. 692Otherwise, the alpha values are not changed. 693 694 695[[fragops-ds-state]] 696== Depth and Stencil Operations 697 698Pipeline state controlling the <<fragops-dbt,depth bounds tests>>, 699<<fragops-stencil,stencil test>>, and <<fragops-depth,depth test>> is 700specified through the members of the 701sname:VkPipelineDepthStencilStateCreateInfo structure. 702 703[open,refpage='VkPipelineDepthStencilStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline depth stencil state',type='structs'] 704-- 705The sname:VkPipelineDepthStencilStateCreateInfo structure is defined as: 706 707include::{generated}/api/structs/VkPipelineDepthStencilStateCreateInfo.txt[] 708 709 * pname:sType is the type of this structure. 710 * pname:pNext is `NULL` or a pointer to a structure extending this 711 structure. 712ifndef::VK_ARM_rasterization_order_attachment_access[] 713 * pname:flags is reserved for future use. 714endif::VK_ARM_rasterization_order_attachment_access[] 715ifdef::VK_ARM_rasterization_order_attachment_access[] 716 * pname:flags is a bitmask of 717 elink:VkPipelineDepthStencilStateCreateFlagBits specifying additional 718 depth/stencil state information. 719endif::VK_ARM_rasterization_order_attachment_access[] 720 * pname:depthTestEnable controls whether <<fragops-depth,depth testing>> 721 is enabled. 722 * pname:depthWriteEnable controls whether <<fragops-depth-write,depth 723 writes>> are enabled when pname:depthTestEnable is ename:VK_TRUE. 724 Depth writes are always disabled when pname:depthTestEnable is 725 ename:VK_FALSE. 726 * pname:depthCompareOp is the comparison operator used in the 727 <<fragops-depth,depth test>>. 728 * pname:depthBoundsTestEnable controls whether <<fragops-dbt,depth bounds 729 testing>> is enabled. 730 * pname:stencilTestEnable controls whether <<fragops-stencil,stencil 731 testing>> is enabled. 732 * pname:front and pname:back control the parameters of the 733 <<fragops-stencil,stencil test>>. 734 * pname:minDepthBounds is the minimum depth bound used in the 735 <<fragops-dbt, depth bounds test>>. 736 * pname:maxDepthBounds is the maximum depth bound used in the 737 <<fragops-dbt, depth bounds test>>. 738 739.Valid Usage 740**** 741 * [[VUID-VkPipelineDepthStencilStateCreateInfo-depthBoundsTestEnable-00598]] 742 If the <<features-depthBounds,depth bounds testing>> feature is not 743 enabled, pname:depthBoundsTestEnable must: be ename:VK_FALSE 744ifdef::VK_KHR_portability_subset[] 745 * [[VUID-VkPipelineDepthStencilStateCreateInfo-separateStencilMaskRef-04453]] 746 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 747 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:separateStencilMaskRef 748 is ename:VK_FALSE, and the value of 749 slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable is 750 ename:VK_TRUE, and the value of 751 slink:VkPipelineRasterizationStateCreateInfo::pname:cullMode is 752 ename:VK_CULL_MODE_NONE, the value of pname:reference in each of the 753 slink:VkStencilOpState structs in pname:front and pname:back must: be 754 the same 755endif::VK_KHR_portability_subset[] 756ifdef::VK_ARM_rasterization_order_attachment_access[] 757 * [[VUID-VkPipelineDepthStencilStateCreateInfo-rasterizationOrderDepthAttachmentAccess-06463]] 758 If the <<features-rasterizationOrderDepthAttachmentAccess, 759 pname:rasterizationOrderDepthAttachmentAccess>> feature is not enabled, 760 pname:flags must: not include 761 ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM 762 * [[VUID-VkPipelineDepthStencilStateCreateInfo-rasterizationOrderStencilAttachmentAccess-06464]] 763 If the <<features-rasterizationOrderStencilAttachmentAccess, 764 pname:rasterizationOrderStencilAttachmentAccess>> feature is not 765 enabled, pname:flags must: not include 766 ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM 767endif::VK_ARM_rasterization_order_attachment_access[] 768**** 769 770include::{generated}/validity/structs/VkPipelineDepthStencilStateCreateInfo.txt[] 771-- 772 773[open,refpage='VkPipelineDepthStencilStateCreateFlags',desc='Bitmask of VkPipelineDepthStencilStateCreateFlagBits',type='flags'] 774-- 775 776ifndef::VK_ARM_rasterization_order_attachment_access[] 777tname:VkPipelineDepthStencilStateCreateFlags is a bitmask type for setting a 778mask, but is currently reserved for future use. 779endif::VK_ARM_rasterization_order_attachment_access[] 780ifdef::VK_ARM_rasterization_order_attachment_access[] 781tname:VkPipelineDepthStencilStateCreateFlags is a bitmask type for setting a 782mask of zero or more elink:VkPipelineDepthStencilStateCreateFlagBits. 783endif::VK_ARM_rasterization_order_attachment_access[] 784-- 785 786ifdef::VK_ARM_rasterization_order_attachment_access[] 787[open,refpage='VkPipelineDepthStencilStateCreateFlagBits',desc='Bitmask specifying additional depth/stencil state information.',type='enums'] 788-- 789 790Bits which can: be set in the 791slink:VkPipelineDepthStencilStateCreateInfo::pname:flags parameter are: 792 793include::{generated}/api/enums/VkPipelineDepthStencilStateCreateFlagBits.txt[] 794 795 * ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM 796 indicates that access to the depth aspects of depth/stencil and input 797 attachments will have implicit framebuffer-local memory dependencies. 798 See <<renderpass-feedbackloop, renderpass feedback loops>> for more 799 information. 800 * ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM 801 indicates that access to the stencil aspects of depth/stencil and input 802 attachments will have implicit framebuffer-local memory dependencies. 803 See <<renderpass-feedbackloop, renderpass feedback loops>> for more 804 information. 805-- 806endif::VK_ARM_rasterization_order_attachment_access[] 807 808 809[[fragops-dbt]] 810== Depth Bounds Test 811 812The depth bounds test compares the depth value [eq]#z~a~# in the 813depth/stencil attachment at each sample's framebuffer coordinates 814[eq]#(x~f~,y~f~)# and <<primsrast-multisampling-coverage-mask, sample 815index>> [eq]#i# against a set of _depth bounds_. 816 817The depth bounds are determined by two floating point values defining a 818minimum (pname:minDepthBounds) and maximum (pname:maxDepthBounds) depth 819value. 820These values are either set by the 821slink:VkPipelineDepthStencilStateCreateInfo structure during pipeline 822creation, or dynamically by 823ifdef::VK_EXT_extended_dynamic_state[] 824flink:vkCmdSetDepthBoundsTestEnableEXT and 825endif::VK_EXT_extended_dynamic_state[] 826flink:vkCmdSetDepthBounds. 827 828A given sample is considered within the depth bounds if [eq]#z~a~# is in the 829range [eq]#[pname:minDepthBounds,pname:maxDepthBounds]#. 830Samples with depth attachment values outside of the depth bounds will have 831their coverage set to `0`. 832 833If the depth bounds test is disabled, or if there is no depth attachment, 834the coverage mask is unmodified by this operation. 835 836ifdef::VK_EXT_extended_dynamic_state[] 837[open,refpage='vkCmdSetDepthBoundsTestEnableEXT',desc='Set depth bounds test enable dynamically for a command buffer',type='protos'] 838-- 839To <<pipelines-dynamic-state, dynamically enable or disable>> the depth 840bounds test, call: 841 842include::{generated}/api/protos/vkCmdSetDepthBoundsTestEnableEXT.txt[] 843 844 * pname:commandBuffer is the command buffer into which the command will be 845 recorded. 846 * pname:depthBoundsTestEnable specifies if the depth bounds test is 847 enabled. 848 849This command sets the depth bounds enable for subsequent drawing commands 850when the graphics pipeline is created with 851ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT set in 852slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 853Otherwise, this state is specified by the 854slink:VkPipelineDepthStencilStateCreateInfo::pname:depthBoundsTestEnable 855value used to create the currently active pipeline. 856 857.Valid Usage 858**** 859 * [[VUID-vkCmdSetDepthBoundsTestEnableEXT-None-03349]] 860 The <<features-extendedDynamicState, extendedDynamicState>> feature 861 must: be enabled 862**** 863 864include::{generated}/validity/protos/vkCmdSetDepthBoundsTestEnableEXT.txt[] 865-- 866endif::VK_EXT_extended_dynamic_state[] 867 868[open,refpage='vkCmdSetDepthBounds',desc='Set depth bounds range dynamically for a command buffer',type='protos'] 869-- 870To <<pipelines-dynamic-state, dynamically set>> the depth bounds range, 871call: 872 873include::{generated}/api/protos/vkCmdSetDepthBounds.txt[] 874 875 * pname:commandBuffer is the command buffer into which the command will be 876 recorded. 877 * pname:minDepthBounds is the minimum depth bound. 878 * pname:maxDepthBounds is the maximum depth bound. 879 880This command sets the depth bounds range for subsequent drawing commands 881when the graphics pipeline is created with 882ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS set in 883slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 884Otherwise, this state is specified by the 885slink:VkPipelineDepthStencilStateCreateInfo::pname:minDepthBounds and 886slink:VkPipelineDepthStencilStateCreateInfo::pname:maxDepthBounds values 887used to create the currently active pipeline. 888 889.Valid Usage 890**** 891ifdef::VK_EXT_depth_range_unrestricted[] 892 * [[VUID-vkCmdSetDepthBounds-minDepthBounds-00600]] 893 Unless the `apiext:VK_EXT_depth_range_unrestricted` extension is enabled 894 pname:minDepthBounds must: be between `0.0` and `1.0`, inclusive 895endif::VK_EXT_depth_range_unrestricted[] 896ifndef::VK_EXT_depth_range_unrestricted[] 897 * [[VUID-vkCmdSetDepthBounds-minDepthBounds-02508]] 898 pname:minDepthBounds must: be between `0.0` and `1.0`, inclusive 899endif::VK_EXT_depth_range_unrestricted[] 900ifdef::VK_EXT_depth_range_unrestricted[] 901 * [[VUID-vkCmdSetDepthBounds-maxDepthBounds-00601]] 902 Unless the `apiext:VK_EXT_depth_range_unrestricted` extension is enabled 903 pname:maxDepthBounds must: be between `0.0` and `1.0`, inclusive 904endif::VK_EXT_depth_range_unrestricted[] 905ifndef::VK_EXT_depth_range_unrestricted[] 906 * [[VUID-vkCmdSetDepthBounds-maxDepthBounds-02509]] 907 pname:maxDepthBounds must: be between `0.0` and `1.0`, inclusive 908endif::VK_EXT_depth_range_unrestricted[] 909**** 910 911include::{generated}/validity/protos/vkCmdSetDepthBounds.txt[] 912-- 913 914 915[[fragops-stencil]] 916== Stencil Test 917 918The stencil test compares the stencil attachment value [eq]#s~a~# in the 919depth/stencil attachment at each sample's framebuffer coordinates 920[eq]#(x~f~,y~f~)# and <<primsrast-multisampling-coverage-mask, sample 921index>> [eq]#i# against a _stencil reference value_. 922 923ifdef::VK_EXT_fragment_density_map[] 924If the render pass has a fragment density map attachment and the fragment 925covers multiple pixels, there is an implementation-dependent association of 926coverage samples to stencil attachment samples within the fragment. 927However, if all samples in the fragment are covered, and the stencil 928attachment value is updated as a result of this test, all stencil attachment 929samples will be updated. 930endif::VK_EXT_fragment_density_map[] 931 932If the stencil test is not enabled, as specified by 933ifdef::VK_EXT_extended_dynamic_state[] 934flink:vkCmdSetStencilTestEnableEXT or 935endif::VK_EXT_extended_dynamic_state[] 936slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable, or if 937there is no stencil attachment, the coverage mask is unmodified by this 938operation. 939 940The stencil test is controlled by one of two sets of stencil-related state, 941the front stencil state and the back stencil state. 942Stencil tests and writes use the back stencil state when processing 943fragments generated by <<primsrast-polygons-basic,back-facing>> 944<<primsrast-polygons,polygons>>, and the front stencil state when processing 945fragments generated by <<primsrast-polygons-basic,front-facing polygons>> or 946any other primitives. 947 948The comparison performed is based on the elink:VkCompareOp, compare mask 949[eq]#s~c~# , and stencil reference value [eq]#s~r~# of the relevant state 950set. 951The compare mask and stencil reference value are set by either the 952slink:VkPipelineDepthStencilStateCreateInfo structure during pipeline 953creation, or by the flink:vkCmdSetStencilCompareMask and 954flink:vkCmdSetStencilReference commands respectively. 955The compare operation is set by slink:VkStencilOpState::pname:compareOp 956during pipeline creation. 957 958The stencil reference and attachment values [eq]#s~r~# and [eq]#s~a~# are 959each independently combined with the compare mask [eq]#s~c~# using a logical 960code:AND operation to create masked reference and attachment values 961[eq]#s'~r~# and [eq]#s'~a~#. 962[eq]#s'~r~# and [eq]#s'~a~# are used as [eq]#A# and [eq]#B#, respectively, 963in the operation specified by elink:VkCompareOp. 964 965If the comparison evaluates to false, the coverage for the sample is set to 966`0`. 967 968A new stencil value [eq]#s~g~# is generated according to a stencil operation 969defined by elink:VkStencilOp parameters set by 970ifdef::VK_EXT_extended_dynamic_state[] 971flink:vkCmdSetStencilOpEXT or 972endif::VK_EXT_extended_dynamic_state[] 973slink:VkPipelineDepthStencilStateCreateInfo. 974If the stencil test fails, pname:failOp defines the stencil operation used. 975If the stencil test passes however, the stencil op used is based on the 976<<fragops-depth, depth test>> - if it passes, 977slink:VkPipelineDepthStencilStateCreateInfo::pname:passOp is used, otherwise 978slink:VkPipelineDepthStencilStateCreateInfo::pname:depthFailOp is used. 979 980The stencil attachment value [eq]#s~a~# is then updated with the generated 981stencil value [eq]#s~g~# according to the write mask [eq]#s~w~# defined by 982slink:VkPipelineDepthStencilStateCreateInfo::pname:writeMask as: 983 984 {empty}:: [eq]#s~a~ = (s~a~ & ¬s~w~) | (s~g~ & s~w~)# 985 986If there is no stencil attachment, no value is written. 987 988ifdef::VK_EXT_extended_dynamic_state[] 989 990[open,refpage='vkCmdSetStencilTestEnableEXT',desc='Set stencil test enable dynamically for a command buffer',type='protos'] 991-- 992To <<pipelines-dynamic-state, dynamically enable or disable>> the stencil 993test, call: 994 995include::{generated}/api/protos/vkCmdSetStencilTestEnableEXT.txt[] 996 997 * pname:commandBuffer is the command buffer into which the command will be 998 recorded. 999 * pname:stencilTestEnable specifies if the stencil test is enabled. 1000 1001This command sets the stencil test enable for subsequent drawing commands 1002when the graphics pipeline is created with 1003ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT set in 1004slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1005Otherwise, this state is specified by the 1006slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable value 1007used to create the currently active pipeline. 1008 1009.Valid Usage 1010**** 1011 * [[VUID-vkCmdSetStencilTestEnableEXT-None-03350]] 1012 The <<features-extendedDynamicState, extendedDynamicState>> feature 1013 must: be enabled 1014**** 1015 1016include::{generated}/validity/protos/vkCmdSetStencilTestEnableEXT.txt[] 1017-- 1018 1019[open,refpage='vkCmdSetStencilOpEXT',desc='Set stencil operation dynamically for a command buffer',type='protos'] 1020-- 1021To <<pipelines-dynamic-state, dynamically set>> the stencil operation, call: 1022 1023include::{generated}/api/protos/vkCmdSetStencilOpEXT.txt[] 1024 1025 * pname:commandBuffer is the command buffer into which the command will be 1026 recorded. 1027 * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying 1028 the set of stencil state for which to update the stencil operation. 1029 * pname:failOp is a elink:VkStencilOp value specifying the action 1030 performed on samples that fail the stencil test. 1031 * pname:passOp is a elink:VkStencilOp value specifying the action 1032 performed on samples that pass both the depth and stencil tests. 1033 * pname:depthFailOp is a elink:VkStencilOp value specifying the action 1034 performed on samples that pass the stencil test and fail the depth test. 1035 * pname:compareOp is a elink:VkCompareOp value specifying the comparison 1036 operator used in the stencil test. 1037 1038This command sets the stencil operation for subsequent drawing commands when 1039the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_OP_EXT 1040set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1041Otherwise, this state is specified by the corresponding 1042sname:VkPipelineDepthStencilStateCreateInfo::pname:failOp, pname:passOp, 1043pname:depthFailOp, and pname:compareOp values used to create the currently 1044active pipeline, for both front and back faces. 1045 1046.Valid Usage 1047**** 1048 * [[VUID-vkCmdSetStencilOpEXT-None-03351]] 1049 The <<features-extendedDynamicState, extendedDynamicState>> feature 1050 must: be enabled 1051**** 1052 1053include::{generated}/validity/protos/vkCmdSetStencilOpEXT.txt[] 1054-- 1055 1056endif::VK_EXT_extended_dynamic_state[] 1057 1058[open,refpage='VkStencilOpState',desc='Structure specifying stencil operation state',type='structs'] 1059-- 1060The sname:VkStencilOpState structure is defined as: 1061 1062include::{generated}/api/structs/VkStencilOpState.txt[] 1063 1064 * pname:failOp is a elink:VkStencilOp value specifying the action 1065 performed on samples that fail the stencil test. 1066 * pname:passOp is a elink:VkStencilOp value specifying the action 1067 performed on samples that pass both the depth and stencil tests. 1068 * pname:depthFailOp is a elink:VkStencilOp value specifying the action 1069 performed on samples that pass the stencil test and fail the depth test. 1070 * pname:compareOp is a elink:VkCompareOp value specifying the comparison 1071 operator used in the stencil test. 1072 * pname:compareMask selects the bits of the unsigned integer stencil 1073 values participating in the stencil test. 1074 * pname:writeMask selects the bits of the unsigned integer stencil values 1075 updated by the stencil test in the stencil framebuffer attachment. 1076 * pname:reference is an integer reference value that is used in the 1077 unsigned stencil comparison. 1078 1079include::{generated}/validity/structs/VkStencilOpState.txt[] 1080-- 1081 1082[open,refpage='vkCmdSetStencilCompareMask',desc='Set stencil compare mask dynamically for a command buffer',type='protos'] 1083-- 1084To <<pipelines-dynamic-state, dynamically set>> the stencil compare mask 1085call: 1086 1087include::{generated}/api/protos/vkCmdSetStencilCompareMask.txt[] 1088 1089 * pname:commandBuffer is the command buffer into which the command will be 1090 recorded. 1091 * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying 1092 the set of stencil state for which to update the compare mask. 1093 * pname:compareMask is the new value to use as the stencil compare mask. 1094 1095This command sets the stencil compare mask for subsequent drawing commands 1096when the graphics pipeline is created with 1097ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK set in 1098slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1099Otherwise, this state is specified by the 1100slink:VkPipelineDepthStencilStateCreateInfo::pname:compareMask value used to 1101create the currently active pipeline, for both front and back faces. 1102 1103include::{generated}/validity/protos/vkCmdSetStencilCompareMask.txt[] 1104-- 1105 1106[open,refpage='VkStencilFaceFlagBits',desc='Bitmask specifying sets of stencil state for which to update the compare mask',type='enums'] 1107-- 1108ename:VkStencilFaceFlagBits values are: 1109 1110include::{generated}/api/enums/VkStencilFaceFlagBits.txt[] 1111 1112 * ename:VK_STENCIL_FACE_FRONT_BIT specifies that only the front set of 1113 stencil state is updated. 1114 * ename:VK_STENCIL_FACE_BACK_BIT specifies that only the back set of 1115 stencil state is updated. 1116 * ename:VK_STENCIL_FACE_FRONT_AND_BACK is the combination of 1117 ename:VK_STENCIL_FACE_FRONT_BIT and ename:VK_STENCIL_FACE_BACK_BIT, and 1118 specifies that both sets of stencil state are updated. 1119 1120-- 1121 1122[open,refpage='VkStencilFaceFlags',desc='Bitmask of VkStencilFaceFlagBits',type='flags'] 1123-- 1124include::{generated}/api/flags/VkStencilFaceFlags.txt[] 1125 1126tname:VkStencilFaceFlags is a bitmask type for setting a mask of zero or 1127more elink:VkStencilFaceFlagBits. 1128-- 1129 1130[open,refpage='vkCmdSetStencilWriteMask',desc='Set stencil write mask dynamically for a command buffer',type='protos'] 1131-- 1132To <<pipelines-dynamic-state, dynamically set>> the stencil write mask, 1133call: 1134 1135include::{generated}/api/protos/vkCmdSetStencilWriteMask.txt[] 1136 1137 * pname:commandBuffer is the command buffer into which the command will be 1138 recorded. 1139 * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying 1140 the set of stencil state for which to update the write mask, as 1141 described above for flink:vkCmdSetStencilCompareMask. 1142 * pname:writeMask is the new value to use as the stencil write mask. 1143 1144This command sets the stencil write mask for subsequent drawing commands 1145when the graphics pipeline is created with 1146ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK set in 1147slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1148Otherwise, this state is specified by the 1149slink:VkPipelineDepthStencilStateCreateInfo::pname:writeMask value used to 1150create the currently active pipeline, for both front and back faces. 1151 1152include::{generated}/validity/protos/vkCmdSetStencilWriteMask.txt[] 1153-- 1154 1155[open,refpage='vkCmdSetStencilReference',desc='Set stencil reference value dynamically for a command buffer',type='protos'] 1156-- 1157To <<pipelines-dynamic-state, dynamically set>> the stencil reference value, 1158call: 1159 1160include::{generated}/api/protos/vkCmdSetStencilReference.txt[] 1161 1162 * pname:commandBuffer is the command buffer into which the command will be 1163 recorded. 1164 * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying 1165 the set of stencil state for which to update the reference value, as 1166 described above for flink:vkCmdSetStencilCompareMask. 1167 * pname:reference is the new value to use as the stencil reference value. 1168 1169This command sets the stencil reference value for subsequent drawing 1170commands when the graphics pipeline is created with 1171ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE set in 1172slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1173Otherwise, this state is specified by the 1174slink:VkPipelineDepthStencilStateCreateInfo::pname:reference value used to 1175create the currently active pipeline, for both front and back faces. 1176 1177include::{generated}/validity/protos/vkCmdSetStencilReference.txt[] 1178-- 1179 1180[open,refpage='VkCompareOp',desc='Stencil comparison function',type='enums'] 1181-- 1182Possible values of slink:VkStencilOpState::pname:compareOp, specifying the 1183stencil comparison function, are: 1184 1185include::{generated}/api/enums/VkCompareOp.txt[] 1186 1187 * ename:VK_COMPARE_OP_NEVER specifies that the test evaluates to false. 1188 * ename:VK_COMPARE_OP_LESS specifies that the test evaluates [eq]#A < B#. 1189 * ename:VK_COMPARE_OP_EQUAL specifies that the test evaluates [eq]#A = B#. 1190 * ename:VK_COMPARE_OP_LESS_OR_EQUAL specifies that the test evaluates 1191 [eq]#A {leq} B#. 1192 * ename:VK_COMPARE_OP_GREATER specifies that the test evaluates [eq]#A > 1193 B#. 1194 * ename:VK_COMPARE_OP_NOT_EQUAL specifies that the test evaluates [eq]#A 1195 {neq} B#. 1196 * ename:VK_COMPARE_OP_GREATER_OR_EQUAL specifies that the test evaluates 1197 [eq]#A {geq} B#. 1198 * ename:VK_COMPARE_OP_ALWAYS specifies that the test evaluates to true. 1199-- 1200 1201[open,refpage='VkStencilOp',desc='Stencil comparison function',type='enums'] 1202-- 1203Possible values of the pname:failOp, pname:passOp, and pname:depthFailOp 1204members of slink:VkStencilOpState, specifying what happens to the stored 1205stencil value if this or certain subsequent tests fail or pass, are: 1206 1207include::{generated}/api/enums/VkStencilOp.txt[] 1208 1209 * ename:VK_STENCIL_OP_KEEP keeps the current value. 1210 * ename:VK_STENCIL_OP_ZERO sets the value to 0. 1211 * ename:VK_STENCIL_OP_REPLACE sets the value to pname:reference. 1212 * ename:VK_STENCIL_OP_INCREMENT_AND_CLAMP increments the current value and 1213 clamps to the maximum representable unsigned value. 1214 * ename:VK_STENCIL_OP_DECREMENT_AND_CLAMP decrements the current value and 1215 clamps to 0. 1216 * ename:VK_STENCIL_OP_INVERT bitwise-inverts the current value. 1217 * ename:VK_STENCIL_OP_INCREMENT_AND_WRAP increments the current value and 1218 wraps to 0 when the maximum value would have been exceeded. 1219 * ename:VK_STENCIL_OP_DECREMENT_AND_WRAP decrements the current value and 1220 wraps to the maximum possible value when the value would go below 0. 1221 1222For purposes of increment and decrement, the stencil bits are considered as 1223an unsigned integer. 1224-- 1225 1226 1227[[fragops-depth]] 1228== Depth Test 1229 1230The depth test compares the depth value [eq]#z~a~# in the depth/stencil 1231attachment at each sample's framebuffer coordinates [eq]#(x~f~,y~f~)# and 1232<<primsrast-multisampling-coverage-mask, sample index>> [eq]#i# against the 1233sample's depth value [eq]#z~f~#. 1234If there is no depth attachment then the depth test is skipped. 1235 1236ifdef::VK_EXT_fragment_density_map[] 1237If the render pass has a fragment density map attachment and the fragment 1238covers multiple pixels, there is an implementation-dependent association of 1239rasterization samples to depth attachment samples within the fragment. 1240However, if all samples in the fragment are covered, and the depth 1241attachment value is updated as a result of this test, all depth attachment 1242samples will be updated. 1243endif::VK_EXT_fragment_density_map[] 1244 1245The depth test occurs in three stages, as detailed in the following 1246sections. 1247 1248=== Depth Clamping and Range Adjustment 1249 1250If slink:VkPipelineRasterizationStateCreateInfo::pname:depthClampEnable is 1251enabled, before the sample's [eq]#z~f~# is compared to [eq]#z~a~#, 1252[eq]#z~f~# is clamped to [eq]#[min(n,f),max(n,f)]#, where [eq]#n# and 1253[eq]#f# are the pname:minDepth and pname:maxDepth depth range values of the 1254viewport used by this fragment, respectively. 1255 1256If depth clamping is not enabled and [eq]#z~f~# is not in the range [eq]#[0, 12571]# 1258ifdef::VK_EXT_depth_range_unrestricted[] 1259and either apiext:VK_EXT_depth_range_unrestricted is not enabled, or the 1260depth attachment has a fixed-point format, 1261endif::VK_EXT_depth_range_unrestricted[] 1262then [eq]#z~f~# is undefined: following this step. 1263 1264 1265=== Depth Comparison 1266 1267If the depth test is not enabled, as specified by 1268ifdef::VK_EXT_extended_dynamic_state[] 1269flink:vkCmdSetDepthTestEnableEXT or 1270endif::VK_EXT_extended_dynamic_state[] 1271slink:VkPipelineDepthStencilStateCreateInfo::pname:depthTestEnable, then 1272this step is skipped. 1273 1274The comparison performed is based on the elink:VkCompareOp, set by 1275ifdef::VK_EXT_extended_dynamic_state[] 1276flink:vkCmdSetDepthCompareOpEXT or 1277endif::VK_EXT_extended_dynamic_state[] 1278slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp during 1279pipeline creation. 1280[eq]#z~f~# and [eq]#z~a~# are used as [eq]#A# and [eq]#B#, respectively, in 1281the operation specified by the elink:VkCompareOp. 1282 1283If the comparison evaluates to false, the coverage for the sample is set to 1284`0`. 1285 1286 1287[[fragops-depth-write]] 1288=== Depth Attachment Writes 1289 1290If depth writes are enabled, as specified by 1291ifdef::VK_EXT_extended_dynamic_state[] 1292flink:vkCmdSetDepthWriteEnableEXT or 1293endif::VK_EXT_extended_dynamic_state[] 1294slink:VkPipelineDepthStencilStateCreateInfo::pname:depthWriteEnable, and the 1295comparison evaluated to true, the depth attachment value [eq]#z~a~# is set 1296to the sample's depth value [eq]#z~f~#. 1297If there is no depth attachment, no value is written. 1298 1299 1300 1301ifdef::VK_EXT_extended_dynamic_state[] 1302[open,refpage='vkCmdSetDepthTestEnableEXT',desc='Set depth test enable dynamically for a command buffer',type='protos'] 1303-- 1304To <<pipelines-dynamic-state, dynamically enable or disable>> the depth 1305test, call: 1306 1307include::{generated}/api/protos/vkCmdSetDepthTestEnableEXT.txt[] 1308 1309 * pname:commandBuffer is the command buffer into which the command will be 1310 recorded. 1311 * pname:depthTestEnable specifies if the depth test is enabled. 1312 1313This command sets the depth test enable for subsequent drawing commands when 1314the graphics pipeline is created with 1315ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT set in 1316slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1317Otherwise, this state is specified by the 1318slink:VkPipelineDepthStencilStateCreateInfo::pname:depthTestEnable value 1319used to create the currently active pipeline. 1320 1321.Valid Usage 1322**** 1323 * [[VUID-vkCmdSetDepthTestEnableEXT-None-03352]] 1324 The <<features-extendedDynamicState, extendedDynamicState>> feature 1325 must: be enabled 1326**** 1327 1328include::{generated}/validity/protos/vkCmdSetDepthTestEnableEXT.txt[] 1329-- 1330 1331[open,refpage='vkCmdSetDepthCompareOpEXT',desc='Set depth comparison operator dynamically for a command buffer',type='protos'] 1332-- 1333To <<pipelines-dynamic-state, dynamically set>> the depth compare operator, 1334call: 1335 1336include::{generated}/api/protos/vkCmdSetDepthCompareOpEXT.txt[] 1337 1338 * pname:commandBuffer is the command buffer into which the command will be 1339 recorded. 1340 * pname:depthCompareOp specifies the depth comparison operator. 1341 1342This command sets the depth comparison operator for subsequent drawing 1343commands when the graphics pipeline is created with 1344ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT set in 1345slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1346Otherwise, this state is specified by the 1347slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp value used 1348to create the currently active pipeline. 1349 1350.Valid Usage 1351**** 1352 * [[VUID-vkCmdSetDepthCompareOpEXT-None-03353]] 1353 The <<features-extendedDynamicState, extendedDynamicState>> feature 1354 must: be enabled 1355**** 1356 1357include::{generated}/validity/protos/vkCmdSetDepthCompareOpEXT.txt[] 1358-- 1359 1360[open,refpage='vkCmdSetDepthWriteEnableEXT',desc='Set depth write enable dynamically for a command buffer',type='protos'] 1361-- 1362To <<pipelines-dynamic-state, dynamically set>> the depth write enable, 1363call: 1364 1365include::{generated}/api/protos/vkCmdSetDepthWriteEnableEXT.txt[] 1366 1367 * pname:commandBuffer is the command buffer into which the command will be 1368 recorded. 1369 * pname:depthWriteEnable specifies if depth writes are enabled. 1370 1371This command sets the depth write enable for subsequent drawing commands 1372when the graphics pipeline is created with 1373ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT set in 1374slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 1375Otherwise, this state is specified by the 1376slink:VkPipelineDepthStencilStateCreateInfo::pname:depthWriteEnable value 1377used to create the currently active pipeline. 1378 1379.Valid Usage 1380**** 1381 * [[VUID-vkCmdSetDepthWriteEnableEXT-None-03354]] 1382 The <<features-extendedDynamicState, extendedDynamicState>> feature 1383 must: be enabled 1384**** 1385 1386include::{generated}/validity/protos/vkCmdSetDepthWriteEnableEXT.txt[] 1387-- 1388endif::VK_EXT_extended_dynamic_state[] 1389 1390 1391ifdef::VK_NV_representative_fragment_test[] 1392[[fragops-rep-frag-test]] 1393== Representative Fragment Test 1394 1395The representative fragment test allows implementations to reduce the amount 1396of rasterization and fragment processing work performed for each point, 1397line, or triangle primitive. 1398For any primitive that produces one or more fragments that pass all prior 1399early fragment tests, the implementation may: choose one or more 1400"`representative`" fragments for processing and discard all other fragments. 1401For draw calls rendering multiple points, lines, or triangles arranged in 1402lists, strips, or fans, the representative fragment test is performed 1403independently for each of those primitives. 1404The set of fragments discarded by the representative fragment test is 1405implementation-dependent. 1406In some cases, the representative fragment test may not discard any 1407fragments for a given primitive. 1408 1409[open,refpage='VkPipelineRepresentativeFragmentTestStateCreateInfoNV',desc='Structure specifying representative fragment test',type='structs'] 1410-- 1411If the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo includes a 1412sname:VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure, then 1413that structure includes parameters controlling the representative fragment 1414test. 1415 1416The sname:VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure is 1417defined as: 1418 1419include::{generated}/api/structs/VkPipelineRepresentativeFragmentTestStateCreateInfoNV.txt[] 1420 1421 * pname:sType is the type of this structure. 1422 * pname:pNext is `NULL` or a pointer to a structure extending this 1423 structure. 1424 * pname:representativeFragmentTestEnable controls whether the 1425 representative fragment test is enabled. 1426 1427If this structure is not included in the pname:pNext chain, 1428pname:representativeFragmentTestEnable is considered to be ename:VK_FALSE, 1429and the representative fragment test is disabled. 1430 1431If the active fragment shader specifies the code:EarlyFragmentTests 1432execution mode, the representative fragment shader test has no effect, even 1433if enabled. 1434 1435include::{generated}/validity/structs/VkPipelineRepresentativeFragmentTestStateCreateInfoNV.txt[] 1436-- 1437 1438endif::VK_NV_representative_fragment_test[] 1439 1440 1441[[fragops-samplecount]] 1442== Sample Counting 1443 1444Occlusion queries use query pool entries to track the number of samples that 1445pass all the per-fragment tests. 1446The mechanism of collecting an occlusion query value is described in 1447<<queries-occlusion,Occlusion Queries>>. 1448 1449The occlusion query sample counter increments by one for each sample with a 1450coverage value of 1 in each fragment that survives all the per-fragment 1451tests, including scissor, 1452ifdef::VK_NV_scissor_exclusive[] 1453exclusive scissor, 1454endif::VK_NV_scissor_exclusive[] 1455sample mask, alpha to coverage, stencil, and depth tests. 1456 1457 1458ifdef::VK_NV_fragment_coverage_to_color[] 1459[[fragops-coverage-to-color]] 1460== Fragment Coverage To Color 1461 1462[open,refpage='VkPipelineCoverageToColorStateCreateInfoNV',desc='Structure specifying whether fragment coverage replaces a color',type='structs'] 1463-- 1464The sname:VkPipelineCoverageToColorStateCreateInfoNV structure is defined 1465as: 1466 1467include::{generated}/api/structs/VkPipelineCoverageToColorStateCreateInfoNV.txt[] 1468 1469 * pname:sType is the type of this structure. 1470 * pname:pNext is `NULL` or a pointer to a structure extending this 1471 structure. 1472 * pname:flags is reserved for future use. 1473 * pname:coverageToColorEnable controls whether the fragment coverage value 1474 replaces a fragment color output. 1475 * pname:coverageToColorLocation controls which fragment shader color 1476 output value is replaced. 1477 1478If the pname:pNext chain of slink:VkPipelineMultisampleStateCreateInfo 1479includes a sname:VkPipelineCoverageToColorStateCreateInfoNV structure, then 1480that structure controls whether the fragment coverage is substituted for a 1481fragment color output and, if so, which output is replaced. 1482 1483If pname:coverageToColorEnable is ename:VK_TRUE, the 1484<<primsrast-multisampling-coverage-mask, coverage mask>> replaces the first 1485component of the color value corresponding to the fragment shader output 1486location with code:Location equal to pname:coverageToColorLocation and 1487code:Index equal to zero. 1488If the color attachment format has fewer bits than the coverage mask, the 1489low bits of the sample coverage mask are taken without any clamping. 1490If the color attachment format has more bits than the coverage mask, the 1491high bits of the sample coverage mask are filled with zeros. 1492 1493If pname:coverageToColorEnable is ename:VK_FALSE, these operations are 1494skipped. 1495If this structure is not included in the pname:pNext chain, it is as if 1496pname:coverageToColorEnable is ename:VK_FALSE. 1497 1498.Valid Usage 1499**** 1500 * [[VUID-VkPipelineCoverageToColorStateCreateInfoNV-coverageToColorEnable-01404]] 1501 If pname:coverageToColorEnable is ename:VK_TRUE, then the render pass 1502 subpass indicated by 1503 slink:VkGraphicsPipelineCreateInfo::pname:renderPass and 1504 slink:VkGraphicsPipelineCreateInfo::pname:subpass must: have a color 1505 attachment at the location selected by pname:coverageToColorLocation, 1506 with a elink:VkFormat of ename:VK_FORMAT_R8_UINT, 1507 ename:VK_FORMAT_R8_SINT, ename:VK_FORMAT_R16_UINT, 1508 ename:VK_FORMAT_R16_SINT, ename:VK_FORMAT_R32_UINT, or 1509 ename:VK_FORMAT_R32_SINT 1510**** 1511 1512include::{generated}/validity/structs/VkPipelineCoverageToColorStateCreateInfoNV.txt[] 1513-- 1514 1515[open,refpage='VkPipelineCoverageToColorStateCreateFlagsNV',desc='Reserved for future use',type='flags'] 1516-- 1517include::{generated}/api/flags/VkPipelineCoverageToColorStateCreateFlagsNV.txt[] 1518 1519tname:VkPipelineCoverageToColorStateCreateFlagsNV is a bitmask type for 1520setting a mask, but is currently reserved for future use. 1521-- 1522endif::VK_NV_fragment_coverage_to_color[] 1523 1524 1525[[fragops-coverage-reduction]] 1526== Coverage Reduction 1527 1528Coverage reduction takes the coverage information for a fragment and 1529converts that to a boolean coverage value for each color sample in each 1530pixel covered by the fragment. 1531 1532 1533=== Pixel Coverage 1534 1535Coverage for each pixel is first extracted from the total fragment coverage 1536mask. 1537This consists of pname:rasterizationSamples unique coverage samples for each 1538pixel in the fragment area, each with a unique 1539<<primsrast-multisampling-coverage-mask, sample index>>. 1540If the fragment only contains a single pixel, coverage for the pixel is 1541equivalent to the fragment coverage. 1542 1543ifdef::VK_EXT_fragment_density_map[] 1544If the render pass has a fragment density map attachment and the fragment 1545covers multiple pixels, pixel coverage is generated in an 1546implementation-dependent manner. 1547If all samples in the fragment are covered, all samples will be covered in 1548each pixel coverage. 1549endif::VK_EXT_fragment_density_map[] 1550 1551ifdef::VK_NV_shading_rate_image[] 1552If a <<primsrast-shading-rate-image,shading rate image>> is used, and the 1553fragment covers multiple pixels, each pixel's coverage consists of the 1554coverage samples corresponding to that pixel, and each sample retains its 1555unique <<primsrast-multisampling-coverage-mask, sample index [eq]#i#>>. 1556endif::VK_NV_shading_rate_image[] 1557 1558ifdef::VK_KHR_fragment_shading_rate[] 1559If the <<primsrast-fragment-shading-rate, fragment shading rate>> is set, 1560and the fragment covers multiple pixels, each pixel's coverage consists of 1561the coverage samples with a <<primsrast-multisampling-coverage-mask-vrfs, 1562pixel index>> matching that pixel, and each sample retains its unique 1563<<primsrast-multisampling-coverage-mask, sample index [eq]#i#>>. 1564endif::VK_KHR_fragment_shading_rate[] 1565 1566=== Color Sample Coverage 1567 1568Once pixel coverage is determined, coverage for each individual color sample 1569corresponding to that pixel is determined. 1570 1571ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[If the] 1572ifndef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[The] 1573number of pname:rasterizationSamples is identical to the number of samples 1574in the color attachments. 1575A color sample is covered if the pixel coverage sample with the same 1576<<primsrast-multisampling-coverage-mask, sample index>> [eq]#i# is covered. 1577 1578ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[] 1579Otherwise, the coverage for each color sample is computed from the pixel 1580coverage as follows. 1581endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[] 1582 1583ifdef::VK_AMD_mixed_attachment_samples[] 1584If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, for 1585color samples present in the color attachments, a color sample is covered if 1586the pixel coverage sample with the same 1587<<primsrast-multisampling-coverage-mask, sample index>> [eq]#i# is covered; 1588additional pixel coverage samples are discarded. 1589endif::VK_AMD_mixed_attachment_samples[] 1590 1591ifdef::VK_NV_framebuffer_mixed_samples[] 1592 1593ifndef::VK_NV_coverage_reduction_mode[] 1594When the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, if 1595the pipeline's 1596slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples is 1597greater than the slink:VkAttachmentDescription::pname:samples of the color 1598attachments in the subpass, each color sample will be associated with an 1599implementation-dependent subset of samples in the pixel coverage. 1600If any of those associated samples are covered, the color sample is covered. 1601endif::VK_NV_coverage_reduction_mode[] 1602 1603ifdef::VK_NV_coverage_reduction_mode[] 1604When the `apiext:VK_NV_coverage_reduction_mode` extension is enabled, the 1605pipeline state controlling coverage reduction is specified through the 1606members of the sname:VkPipelineCoverageReductionStateCreateInfoNV structure. 1607 1608[open,refpage='VkPipelineCoverageReductionStateCreateInfoNV',desc='Structure specifying parameters controlling coverage reduction',type='structs'] 1609-- 1610The sname:VkPipelineCoverageReductionStateCreateInfoNV structure is defined 1611as: 1612 1613include::{generated}/api/structs/VkPipelineCoverageReductionStateCreateInfoNV.txt[] 1614 1615 * pname:sType is the type of this structure. 1616 * pname:pNext is `NULL` or a pointer to a structure extending this 1617 structure. 1618 * pname:flags is reserved for future use. 1619 * pname:coverageReductionMode is a elink:VkCoverageReductionModeNV value 1620 controlling how color sample coverage is generated from pixel coverage. 1621 1622If this structure is not included in the pname:pNext chain, or if the 1623extension is not enabled, the default coverage reduction mode is inferred as 1624follows: 1625 1626 * If the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, 1627 then it is as if the pname:coverageReductionMode is 1628 ename:VK_COVERAGE_REDUCTION_MODE_MERGE_NV. 1629 * If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, 1630 then it is as if the pname:coverageReductionMode is 1631 ename:VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV. 1632 * If both `apiext:VK_NV_framebuffer_mixed_samples` and 1633 `apiext:VK_AMD_mixed_attachment_samples` are enabled, then the default 1634 coverage reduction mode is implementation-dependent. 1635 1636include::{generated}/validity/structs/VkPipelineCoverageReductionStateCreateInfoNV.txt[] 1637-- 1638 1639[open,refpage='VkPipelineCoverageReductionStateCreateFlagsNV',desc='Reserved for future use',type='flags'] 1640-- 1641include::{generated}/api/flags/VkPipelineCoverageReductionStateCreateFlagsNV.txt[] 1642 1643tname:VkPipelineCoverageReductionStateCreateFlagsNV is a bitmask type for 1644setting a mask, but is currently reserved for future use. 1645-- 1646 1647[open,refpage='VkCoverageReductionModeNV',desc='Specify the coverage reduction mode',type='enums'] 1648-- 1649Possible values of 1650slink:VkPipelineCoverageReductionStateCreateInfoNV::pname:coverageReductionMode, 1651specifying how color sample coverage is generated from pixel coverage, are: 1652 1653include::{generated}/api/enums/VkCoverageReductionModeNV.txt[] 1654 1655 * ename:VK_COVERAGE_REDUCTION_MODE_MERGE_NV specifies that each color 1656 sample will be associated with an implementation-dependent subset of 1657 samples in the pixel coverage. 1658 If any of those associated samples are covered, the color sample is 1659 covered. 1660 * ename:VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV specifies that for color 1661 samples present in the color attachments, a color sample is covered if 1662 the pixel coverage sample with the same 1663 <<primsrast-multisampling-coverage-mask, sample index>> [eq]#i# is 1664 covered; other pixel coverage samples are discarded. 1665-- 1666 1667[open,refpage='vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV',desc='Query supported sample count combinations',type='protos'] 1668-- 1669To query the set of mixed sample combinations of coverage reduction mode, 1670rasterization samples and color, depth, stencil attachment sample counts 1671that are supported by a physical device, call: 1672 1673include::{generated}/api/protos/vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV.txt[] 1674 1675 * pname:physicalDevice is the physical device from which to query the set 1676 of combinations. 1677 * pname:pCombinationCount is a pointer to an integer related to the number 1678 of combinations available or queried, as described below. 1679 * pname:pCombinations is either `NULL` or a pointer to an array of 1680 slink:VkFramebufferMixedSamplesCombinationNV values, indicating the 1681 supported combinations of coverage reduction mode, rasterization 1682 samples, and color, depth, stencil attachment sample counts. 1683 1684If pname:pCombinations is `NULL`, then the number of supported combinations 1685for the given pname:physicalDevice is returned in pname:pCombinationCount. 1686Otherwise, pname:pCombinationCount must: point to a variable set by the user 1687to the number of elements in the pname:pCombinations array, and on return 1688the variable is overwritten with the number of values actually written to 1689pname:pCombinations. 1690If the value of pname:pCombinationCount is less than the number of 1691combinations supported for the given pname:physicalDevice, at most 1692pname:pCombinationCount values will be written to pname:pCombinations, and 1693ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to 1694indicate that not all the supported values were returned. 1695 1696include::{generated}/validity/protos/vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV.txt[] 1697-- 1698 1699[open,refpage='VkFramebufferMixedSamplesCombinationNV',desc='Structure specifying a supported sample count combination',type='structs'] 1700-- 1701The sname:VkFramebufferMixedSamplesCombinationNV structure is defined as: 1702 1703include::{generated}/api/structs/VkFramebufferMixedSamplesCombinationNV.txt[] 1704 1705 * pname:sType is the type of this structure. 1706 * pname:pNext is `NULL` or a pointer to a structure extending this 1707 structure. 1708 * pname:coverageReductionMode is a elink:VkCoverageReductionModeNV value 1709 specifying the coverage reduction mode. 1710 * pname:rasterizationSamples is a elink:VkSampleCountFlagBits specifying 1711 the number of rasterization samples in the supported combination. 1712 * pname:depthStencilSamples specifies the number of samples in the depth 1713 stencil attachment in the supported combination. 1714 A value of 0 indicates the combination does not have a depth stencil 1715 attachment. 1716 * pname:colorSamples specifies the number of color samples in a color 1717 attachment in the supported combination. 1718 A value of 0 indicates the combination does not have a color attachment. 1719 1720include::{generated}/validity/structs/VkFramebufferMixedSamplesCombinationNV.txt[] 1721-- 1722endif::VK_NV_coverage_reduction_mode[] 1723 1724 1725[[fragops-coverage-modulation]] 1726=== Coverage Modulation 1727 1728[open,refpage='VkPipelineCoverageModulationStateCreateInfoNV',desc='Structure specifying parameters controlling coverage modulation',type='structs'] 1729-- 1730As part of coverage reduction, fragment color values can: also be modulated 1731(multiplied) by a value that is a function of fraction of covered 1732rasterization samples associated with that color sample. 1733 1734Pipeline state controlling coverage modulation is specified through the 1735members of the sname:VkPipelineCoverageModulationStateCreateInfoNV 1736structure. 1737 1738The sname:VkPipelineCoverageModulationStateCreateInfoNV structure is defined 1739as: 1740 1741include::{generated}/api/structs/VkPipelineCoverageModulationStateCreateInfoNV.txt[] 1742 1743 * pname:sType is the type of this structure. 1744 * pname:pNext is `NULL` or a pointer to a structure extending this 1745 structure. 1746 * pname:flags is reserved for future use. 1747 * pname:coverageModulationMode is a elink:VkCoverageModulationModeNV value 1748 controlling which color components are modulated. 1749 * pname:coverageModulationTableEnable controls whether the modulation 1750 factor is looked up from a table in pname:pCoverageModulationTable. 1751 * pname:coverageModulationTableCount is the number of elements in 1752 pname:pCoverageModulationTable. 1753 * pname:pCoverageModulationTable is a table of modulation factors 1754 containing a value for each number of covered samples. 1755 1756If pname:coverageModulationTableEnable is ename:VK_FALSE, then for each 1757color sample the associated bits of the pixel coverage are counted and 1758divided by the number of associated bits to produce a modulation factor 1759[eq]#R# in the range [eq]#(0,1]# (a value of zero would have been killed due 1760to a color coverage of 0). 1761Specifically: 1762 1763 * [eq]#N# = value of pname:rasterizationSamples 1764 * [eq]#M# = value of slink:VkAttachmentDescription::pname:samples for any 1765 color attachments 1766 * [eq]#R = popcount(associated coverage bits) / (N / M)# 1767 1768If pname:coverageModulationTableEnable is ename:VK_TRUE, the value [eq]#R# 1769is computed using a programmable lookup table. 1770The lookup table has [eq]#N / M# elements, and the element of the table is 1771selected by: 1772 1773 * [eq]#R = pname:pCoverageModulationTable[popcount(associated coverage 1774 bits)-1]# 1775 1776Note that the table does not have an entry for [eq]#popcount(associated 1777coverage bits) = 0#, because such samples would have been killed. 1778 1779The values of pname:pCoverageModulationTable may: be rounded to an 1780implementation-dependent precision, which is at least as fine as [eq]#1 / 1781N#, and clamped to [eq]#[0,1]#. 1782 1783For each color attachment with a floating point or normalized color format, 1784each fragment output color value is replicated to [eq]#M# values which can: 1785each be modulated (multiplied) by that color sample's associated value of 1786[eq]#R#. 1787Which components are modulated is controlled by 1788pname:coverageModulationMode. 1789 1790If this structure is not included in the pname:pNext chain, it is as if 1791pname:coverageModulationMode is ename:VK_COVERAGE_MODULATION_MODE_NONE_NV. 1792 1793ifdef::VK_NV_coverage_reduction_mode[] 1794If the <<fragops-coverage-reduction, coverage reduction mode>> is 1795ename:VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV, each color sample is 1796associated with only a single coverage sample. 1797In this case, it is as if pname:coverageModulationMode is 1798ename:VK_COVERAGE_MODULATION_MODE_NONE_NV. 1799endif::VK_NV_coverage_reduction_mode[] 1800 1801.Valid Usage 1802**** 1803 * [[VUID-VkPipelineCoverageModulationStateCreateInfoNV-coverageModulationTableEnable-01405]] 1804 If pname:coverageModulationTableEnable is ename:VK_TRUE, 1805 pname:coverageModulationTableCount must: be equal to the number of 1806 rasterization samples divided by the number of color samples in the 1807 subpass 1808**** 1809 1810include::{generated}/validity/structs/VkPipelineCoverageModulationStateCreateInfoNV.txt[] 1811-- 1812 1813[open,refpage='VkPipelineCoverageModulationStateCreateFlagsNV',desc='Reserved for future use',type='flags'] 1814-- 1815include::{generated}/api/flags/VkPipelineCoverageModulationStateCreateFlagsNV.txt[] 1816 1817tname:VkPipelineCoverageModulationStateCreateFlagsNV is a bitmask type for 1818setting a mask, but is currently reserved for future use. 1819-- 1820 1821[open,refpage='VkCoverageModulationModeNV',desc='Specify the coverage modulation mode',type='enums'] 1822-- 1823Possible values of 1824slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationMode, 1825specifying which color components are modulated, are: 1826 1827include::{generated}/api/enums/VkCoverageModulationModeNV.txt[] 1828 1829 * ename:VK_COVERAGE_MODULATION_MODE_NONE_NV specifies that no components 1830 are multiplied by the modulation factor. 1831 * ename:VK_COVERAGE_MODULATION_MODE_RGB_NV specifies that the red, green, 1832 and blue components are multiplied by the modulation factor. 1833 * ename:VK_COVERAGE_MODULATION_MODE_ALPHA_NV specifies that the alpha 1834 component is multiplied by the modulation factor. 1835 * ename:VK_COVERAGE_MODULATION_MODE_RGBA_NV specifies that all components 1836 are multiplied by the modulation factor. 1837-- 1838 1839endif::VK_NV_framebuffer_mixed_samples[] 1840