• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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