path: root/chapters/primsrast.adoc

// Copyright 2015-2023 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[primsrast]]
= Rasterization

Rasterization is the process by which a primitive is converted to a
two-dimensional image.
Each discrete location of this image contains associated data such as depth,
color, or other attributes.

Rasterizing a primitive begins by determining which squares of an integer
grid in framebuffer coordinates are occupied by the primitive, and assigning
one or more depth values to each such square.
This process is described below for points, lines, and polygons.

A grid square, including its [eq]#(x,y)# framebuffer coordinates, [eq]#z#
(depth), and associated data added by fragment shaders, is called a
fragment.
A fragment is located by its upper left corner, which lies on integer grid
coordinates.

Rasterization operations also refer to a fragment's sample locations, which
are offset by fractional values from its upper left corner.
The rasterization rules for points, lines, and triangles involve testing
whether each sample location is inside the primitive.
Fragments need not actually be square, and rasterization rules are not
affected by the aspect ratio of fragments.
Display of non-square grids, however, will cause rasterized points and line
segments to appear fatter in one direction than the other.

We assume that fragments are square, since it simplifies antialiasing and
texturing.
After rasterization, fragments are processed by <<fragops, fragment
operations>>.

Several factors affect rasterization, including the members of
slink:VkPipelineRasterizationStateCreateInfo and
slink:VkPipelineMultisampleStateCreateInfo.

[open,refpage='VkPipelineRasterizationStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline rasterization state',type='structs']
--
The sname:VkPipelineRasterizationStateCreateInfo structure is defined as:

include::{generated}/api/structs/VkPipelineRasterizationStateCreateInfo.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is reserved for future use.
  * pname:depthClampEnable controls whether to clamp the fragment's depth
    values as described in <<fragops-depth,Depth Test>>.
ifdef::VK_EXT_depth_clip_enable[]
    If the pipeline is not created with
    slink:VkPipelineRasterizationDepthClipStateCreateInfoEXT present then
    enabling depth clamp will also disable clipping primitives to the z
    planes of the frustrum as described in <<vertexpostproc-clipping,
    Primitive Clipping>>.
    Otherwise depth clipping is controlled by the state set in
    slink:VkPipelineRasterizationDepthClipStateCreateInfoEXT.
endif::VK_EXT_depth_clip_enable[]
ifndef::VK_EXT_depth_clip_enable[]
    Enabling depth clamp will also disable clipping primitives to the z
    planes of the frustrum as described in <<vertexpostproc-clipping,
    Primitive Clipping>>.
endif::VK_EXT_depth_clip_enable[]
  * pname:rasterizerDiscardEnable controls whether primitives are discarded
    immediately before the rasterization stage.
  * pname:polygonMode is the triangle rendering mode.
    See elink:VkPolygonMode.
  * pname:cullMode is the triangle facing direction used for primitive
    culling.
    See elink:VkCullModeFlagBits.
  * pname:frontFace is a elink:VkFrontFace value specifying the front-facing
    triangle orientation to be used for culling.
  * pname:depthBiasEnable controls whether to bias fragment depth values.
  * pname:depthBiasConstantFactor is a scalar factor controlling the
    constant depth value added to each fragment.
  * pname:depthBiasClamp is the maximum (or minimum) depth bias of a
    fragment.
  * pname:depthBiasSlopeFactor is a scalar factor applied to a fragment's
    slope in depth bias calculations.
  * pname:lineWidth is the width of rasterized line segments.

ifdef::VK_AMD_rasterization_order[]
The application can: also add a
sname:VkPipelineRasterizationStateRasterizationOrderAMD structure to the
pname:pNext chain of a slink:VkPipelineRasterizationStateCreateInfo
structure.
This structure enables selecting the rasterization order to use when
rendering with the corresponding graphics pipeline as described in
<<primsrast-order, Rasterization Order>>.
endif::VK_AMD_rasterization_order[]

.Valid Usage
****
  * [[VUID-VkPipelineRasterizationStateCreateInfo-depthClampEnable-00782]]
    If the <<features-depthClamp, pname:depthClamp>> feature is not enabled,
    pname:depthClampEnable must: be ename:VK_FALSE
  * [[VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-01507]]
    If the <<features-fillModeNonSolid, pname:fillModeNonSolid>> feature is
    not enabled, pname:polygonMode must: be ename:VK_POLYGON_MODE_FILL
ifdef::VK_NV_fill_rectangle[or ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV]
ifdef::VK_NV_fill_rectangle[]
  * [[VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-01414]]
    If the `apiext:VK_NV_fill_rectangle` extension is not enabled,
    pname:polygonMode must: not be ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV
endif::VK_NV_fill_rectangle[]
ifdef::VK_KHR_portability_subset[]
  * [[VUID-VkPipelineRasterizationStateCreateInfo-pointPolygons-04458]]
    If the `apiext:VK_KHR_portability_subset` extension is enabled, and
    slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:pointPolygons
    is ename:VK_FALSE, and pname:rasterizerDiscardEnable is ename:VK_FALSE,
    pname:polygonMode must: not be ename:VK_POLYGON_MODE_POINT
endif::VK_KHR_portability_subset[]
****

include::{generated}/validity/structs/VkPipelineRasterizationStateCreateInfo.adoc[]
--

[open,refpage='VkPipelineRasterizationStateCreateFlags',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkPipelineRasterizationStateCreateFlags.adoc[]

tname:VkPipelineRasterizationStateCreateFlags is a bitmask type for setting
a mask, but is currently reserved for future use.
--

ifdef::VK_EXT_depth_clip_enable[]
[open,refpage='VkPipelineRasterizationDepthClipStateCreateInfoEXT',desc='Structure specifying depth clipping state',type='structs']
--
If the pname:pNext chain of slink:VkPipelineRasterizationStateCreateInfo
includes a sname:VkPipelineRasterizationDepthClipStateCreateInfoEXT
structure, then that structure controls whether depth clipping is enabled or
disabled.

The sname:VkPipelineRasterizationDepthClipStateCreateInfoEXT structure is
defined as:

include::{generated}/api/structs/VkPipelineRasterizationDepthClipStateCreateInfoEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is reserved for future use.
  * pname:depthClipEnable controls whether depth clipping is enabled as
    described in <<vertexpostproc-clipping, Primitive Clipping>>.

include::{generated}/validity/structs/VkPipelineRasterizationDepthClipStateCreateInfoEXT.adoc[]
--

[open,refpage='VkPipelineRasterizationDepthClipStateCreateFlagsEXT',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkPipelineRasterizationDepthClipStateCreateFlagsEXT.adoc[]

tname:VkPipelineRasterizationDepthClipStateCreateFlagsEXT is a bitmask type
for setting a mask, but is currently reserved for future use.
--
endif::VK_EXT_depth_clip_enable[]

[open,refpage='VkPipelineMultisampleStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline multisample state',type='structs']
--
The sname:VkPipelineMultisampleStateCreateInfo structure is defined as:

include::{generated}/api/structs/VkPipelineMultisampleStateCreateInfo.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is reserved for future use.
  * pname:rasterizationSamples is a elink:VkSampleCountFlagBits value
    specifying the number of samples used in rasterization.
ifdef::VK_EXT_extended_dynamic_state3[]
    This value is ignored for the purposes of setting the number of samples
    used in rasterization if the pipeline is created with the
    ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT dynamic state set, but
    if ename:VK_DYNAMIC_STATE_SAMPLE_MASK_EXT dynamic state is not set, it
    is still used to define the size of the pname:pSampleMask array as
    described below.
endif::VK_EXT_extended_dynamic_state3[]
  * pname:sampleShadingEnable can: be used to enable
    <<primsrast-sampleshading,Sample Shading>>.
  * pname:minSampleShading specifies a minimum fraction of sample shading if
    pname:sampleShadingEnable is set to ename:VK_TRUE.
  * pname:pSampleMask is a pointer to an array of basetype:VkSampleMask
    values used in the <<fragops-samplemask,sample mask test>>.
  * pname:alphaToCoverageEnable controls whether a temporary coverage value
    is generated based on the alpha component of the fragment's first color
    output as specified in the <<fragops-covg,Multisample Coverage>>
    section.
  * pname:alphaToOneEnable controls whether the alpha component of the
    fragment's first color output is replaced with one as described in
    <<fragops-covg,Multisample Coverage>>.

Each bit in the sample mask is associated with a unique
<<primsrast-multisampling-coverage-mask, sample index>> as defined for the
<<primsrast-multisampling-coverage-mask, coverage mask>>.
Each bit [eq]#b# for mask word [eq]#w# in the sample mask corresponds to
sample index [eq]#i#, where [eq]#i = 32 {times} w {plus} b#.
pname:pSampleMask has a length equal to [eq]#{lceil}
pname:rasterizationSamples / 32 {rceil}# words.

If pname:pSampleMask is `NULL`, it is treated as if the mask has all bits
set to `1`.

.Valid Usage
****
  * [[VUID-VkPipelineMultisampleStateCreateInfo-sampleShadingEnable-00784]]
    If the <<features-sampleRateShading, pname:sampleRateShading>> feature
    is not enabled, pname:sampleShadingEnable must: be ename:VK_FALSE
  * [[VUID-VkPipelineMultisampleStateCreateInfo-alphaToOneEnable-00785]]
    If the <<features-alphaToOne, pname:alphaToOne>> feature is not enabled,
    pname:alphaToOneEnable must: be ename:VK_FALSE
  * [[VUID-VkPipelineMultisampleStateCreateInfo-minSampleShading-00786]]
    pname:minSampleShading must: be in the range [eq]#[0,1]#
ifdef::VK_NV_framebuffer_mixed_samples[]
  * [[VUID-VkPipelineMultisampleStateCreateInfo-rasterizationSamples-01415]]
    If the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled,
    and if the subpass has any color attachments and
    pname:rasterizationSamples is greater than the number of color samples,
    then pname:sampleShadingEnable must: be ename:VK_FALSE
endif::VK_NV_framebuffer_mixed_samples[]
****

include::{generated}/validity/structs/VkPipelineMultisampleStateCreateInfo.adoc[]
--

[open,refpage='VkPipelineMultisampleStateCreateFlags',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkPipelineMultisampleStateCreateFlags.adoc[]

tname:VkPipelineMultisampleStateCreateFlags is a bitmask type for setting a
mask, but is currently reserved for future use.
--

[open,refpage='VkSampleMask',desc='Mask of sample coverage information',type='basetypes',xrefs='VkPipelineMultisampleStateCreateInfo']
--
The elements of the sample mask array are of type basetype:VkSampleMask,
each representing 32 bits of coverage information:

include::{generated}/api/basetypes/VkSampleMask.adoc[]
--

Rasterization only generates fragments which cover one or more pixels inside
the framebuffer.
Pixels outside the framebuffer are never considered covered in the fragment.
Fragments which would be produced by application of any of the primitive
rasterization rules described below but which lie outside the framebuffer
are not produced, nor are they processed by any later stage of the pipeline,
including any of the <<fragops, fragment operations>>.

Surviving fragments are processed by fragment shaders.
Fragment shaders determine associated data for fragments, and can: also
modify or replace their assigned depth values.


[[primsrast-discard]]
== Discarding Primitives Before Rasterization

Primitives are discarded before rasterization if the
pname:rasterizerDiscardEnable member of
slink:VkPipelineRasterizationStateCreateInfo is enabled.
When enabled, primitives are discarded after they are processed by the last
active shader stage in the pipeline before rasterization.

ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[]
[open,refpage='vkCmdSetRasterizerDiscardEnable',desc='Control whether primitives are discarded before the rasterization stage dynamically for a command buffer',type='protos',alias='vkCmdSetRasterizerDiscardEnableEXT']
--
To <<pipelines-dynamic-state, dynamically enable>> whether primitives are
discarded before the rasterization stage, call:

ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkCmdSetRasterizerDiscardEnable.adoc[]

ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[or the equivalent command]
endif::VK_VERSION_1_3[]

ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[]
include::{generated}/api/protos/vkCmdSetRasterizerDiscardEnableEXT.adoc[]
endif::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:rasterizerDiscardEnable controls whether primitives are discarded
    immediately before the rasterization stage.

This command sets the discard enable for subsequent drawing commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[]
Otherwise, this state is specified by the
slink:VkPipelineRasterizationStateCreateInfo::pname:rasterizerDiscardEnable
value used to create the currently active pipeline.

:refpage: vkCmdSetRasterizerDiscardEnable

.Valid Usage
****
include::{chapters}/commonvalidity/dynamic_state2_feature_common.adoc[]
****

include::{generated}/validity/protos/vkCmdSetRasterizerDiscardEnable.adoc[]
--
endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[]


ifdef::VK_EXT_transform_feedback[]
[[primsrast-stream]]
== Controlling the Vertex Stream Used for Rasterization

By default vertex data output from the last
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> are directed to vertex stream zero.
Geometry shaders can: emit primitives to multiple independent vertex
streams.
Each vertex emitted by the geometry shader is directed at one of the vertex
streams.
As vertices are received on each vertex stream, they are arranged into
primitives of the type specified by the geometry shader output primitive
type.
The shading language instructions code:OpEndPrimitive and
code:OpEndStreamPrimitive can: be used to end the primitive being assembled
on a given vertex stream and start a new empty primitive of the same type.
An implementation supports up to
sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams
streams, which is at least 1.
The individual streams are numbered 0 through
pname:maxTransformFeedbackStreams minus 1.
There is no requirement on the order of the streams to which vertices are
emitted, and the number of vertices emitted to each vertex stream can: be
completely independent, subject only to the
sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreamDataSize
and
sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBufferDataSize
limits.
The primitives output from all vertex streams are passed to the transform
feedback stage to be captured to transform feedback buffers in the manner
specified by the last
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>> shader's code:XfbBuffer, code:XfbStride, and code:Offsets
decorations on the output interface variables in the graphics pipeline.
To use a vertex stream other than zero, or to use multiple streams, the
code:GeometryStreams capability must: be specified.

By default, the primitives output from vertex stream zero are rasterized.
If the implementation supports the
slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackRasterizationStreamSelect
property it is possible to rasterize a vertex stream other than zero.

By default, geometry shaders that emit vertices to multiple vertex streams
are limited to using only the code:OutputPoints output primitive type.
If the implementation supports the
slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackStreamsLinesTriangles
property it is possible to emit code:OutputLineStrip or
code:OutputTriangleStrip in addition to code:OutputPoints.

[open,refpage='VkPipelineRasterizationStateStreamCreateInfoEXT',desc='Structure defining the geometry stream used for rasterization',type='structs']
--
The vertex stream used for rasterization is specified by adding a
sname:VkPipelineRasterizationStateStreamCreateInfoEXT structure to the
pname:pNext chain of a slink:VkPipelineRasterizationStateCreateInfo
structure.

The sname:VkPipelineRasterizationStateStreamCreateInfoEXT structure is
defined as:

include::{generated}/api/structs/VkPipelineRasterizationStateStreamCreateInfoEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is reserved for future use.
  * pname:rasterizationStream is the vertex stream selected for
    rasterization.

If this structure is not present, pname:rasterizationStream is assumed to be
zero.

.Valid Usage
****
  * [[VUID-VkPipelineRasterizationStateStreamCreateInfoEXT-geometryStreams-02324]]
    sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:geometryStreams
    must: be enabled
  * [[VUID-VkPipelineRasterizationStateStreamCreateInfoEXT-rasterizationStream-02325]]
    pname:rasterizationStream must: be less than
    slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams
  * [[VUID-VkPipelineRasterizationStateStreamCreateInfoEXT-rasterizationStream-02326]]
    pname:rasterizationStream must: be zero if
    sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackRasterizationStreamSelect
    is ename:VK_FALSE
****

include::{generated}/validity/structs/VkPipelineRasterizationStateStreamCreateInfoEXT.adoc[]
--

[open,refpage='VkPipelineRasterizationStateStreamCreateFlagsEXT',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkPipelineRasterizationStateStreamCreateFlagsEXT.adoc[]

tname:VkPipelineRasterizationStateStreamCreateFlagsEXT is a bitmask type for
setting a mask, but is currently reserved for future use.
--

ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]
[open,refpage='vkCmdSetRasterizationStreamEXT',desc='Specify the rasterization stream dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the
pname:rasterizationStream state, call:

include::{generated}/api/protos/vkCmdSetRasterizationStreamEXT.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:rasterizationStream specifies the pname:rasterizationStream state.

This command sets the pname:rasterizationStream state for subsequent drawing
commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_EXT_extended_dynamic_state3[]
Otherwise, this state is specified by the
slink:VkPipelineRasterizationStateStreamCreateInfoEXT::pname:rasterizationStream
value used to create the currently active pipeline.

.Valid Usage
****
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetRasterizationStreamEXT-None-08550]]
    Either the <<features-extendedDynamicState3RasterizationStream,
    pname:extendedDynamicState3RasterizationStream>> feature or the
    <<features-shaderObject, pname:shaderObject>> feature or both must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
ifndef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetRasterizationStreamEXT-None-08551]]
    The <<features-shaderObject, pname:shaderObject>> feature must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
endif::VK_EXT_shader_object[]
ifndef::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetRasterizationStreamEXT-extendedDynamicState3RasterizationStream-07410]]
    The <<features-extendedDynamicState3RasterizationStream,
    pname:extendedDynamicState3RasterizationStream>> feature must: be
    enabled
endif::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetRasterizationStreamEXT-transformFeedback-07411]]
    The <<features-transformFeedback, pname:transformFeedback>> feature
    must: be enabled
  * [[VUID-vkCmdSetRasterizationStreamEXT-rasterizationStream-07412]]
    pname:rasterizationStream must: be less than
    slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams
  * [[VUID-vkCmdSetRasterizationStreamEXT-rasterizationStream-07413]]
    pname:rasterizationStream must: be zero if
    sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackRasterizationStreamSelect
    is ename:VK_FALSE
****

include::{generated}/validity/protos/vkCmdSetRasterizationStreamEXT.adoc[]
--
endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]
endif::VK_EXT_transform_feedback[]


[[primsrast-order]]
== Rasterization Order

Within a subpass of a <<renderpass,render pass instance>>, for a given
(x,y,layer,sample) sample location, the following operations are guaranteed
to execute in _rasterization order_, for each separate primitive that
includes that sample location:

  . <<fragops, Fragment operations>>, in the order defined
  . <<framebuffer-blending, Blending>>, <<framebuffer-logicop, logic
    operations>>, and color writes

Execution of these operations for each primitive in a subpass occurs in
ifndef::VK_AMD_rasterization_order[]
<<drawing-primitive-order, primitive order>>.
endif::VK_AMD_rasterization_order[]
ifdef::VK_AMD_rasterization_order[]
an order determined by the application.

[open,refpage='VkPipelineRasterizationStateRasterizationOrderAMD',desc='Structure defining rasterization order for a graphics pipeline',type='structs']
--
The rasterization order to use for a graphics pipeline is specified by
adding a sname:VkPipelineRasterizationStateRasterizationOrderAMD structure
to the pname:pNext chain of a slink:VkPipelineRasterizationStateCreateInfo
structure.

The sname:VkPipelineRasterizationStateRasterizationOrderAMD structure is
defined as:

include::{generated}/api/structs/VkPipelineRasterizationStateRasterizationOrderAMD.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:rasterizationOrder is a elink:VkRasterizationOrderAMD value
    specifying the primitive rasterization order to use.

include::{generated}/validity/structs/VkPipelineRasterizationStateRasterizationOrderAMD.adoc[]

If the `apiext:VK_AMD_rasterization_order` device extension is not enabled
or the application does not request a particular rasterization order through
specifying a sname:VkPipelineRasterizationStateRasterizationOrderAMD
structure then the rasterization order used by the graphics pipeline
defaults to ename:VK_RASTERIZATION_ORDER_STRICT_AMD.
--

[open,refpage='VkRasterizationOrderAMD',desc='Specify rasterization order for a graphics pipeline',type='enums']
--
Possible values of
slink:VkPipelineRasterizationStateRasterizationOrderAMD::pname:rasterizationOrder,
specifying the primitive rasterization order, are:

include::{generated}/api/enums/VkRasterizationOrderAMD.adoc[]

  * ename:VK_RASTERIZATION_ORDER_STRICT_AMD specifies that operations for
    each primitive in a subpass must: occur in <<drawing-primitive-order,
    primitive order>>.
  * ename:VK_RASTERIZATION_ORDER_RELAXED_AMD specifies that operations for
    each primitive in a subpass may: not occur in <<drawing-primitive-order,
    primitive order>>.
--
endif::VK_AMD_rasterization_order[]


[[primsrast-multisampling]]
== Multisampling

Multisampling is a mechanism to antialias all Vulkan primitives: points,
lines, and polygons.
The technique is to sample all primitives multiple times at each pixel.
Each sample in each framebuffer attachment has storage for a color, depth,
and/or stencil value, such that per-fragment operations apply to each sample
independently.
The color sample values can: be later _resolved_ to a single color (see
<<copies-resolve,Resolving Multisample Images>> and the <<renderpass,Render
Pass>> chapter for more details on how to resolve multisample images to
non-multisample images).

Vulkan defines rasterization rules for single-sample modes in a way that is
equivalent to a multisample mode with a single sample in the center of each
fragment.

Each fragment includes a <<primsrast-multisampling-coverage-mask, coverage
mask>> with a single bit for each sample in the fragment, and a number of
depth values and associated data for each sample.

It is understood that each pixel has pname:rasterizationSamples locations
associated with it.
These locations are exact positions, rather than regions or areas, and each
is referred to as a sample point.
The sample points associated with a pixel must: be located inside or on the
boundary of the unit square that is considered to bound the pixel.
Furthermore, the relative locations of sample points may: be identical for
each pixel in the framebuffer, or they may: differ.

ifdef::VK_EXT_fragment_density_map[]
If the render pass has a fragment density map attachment, each fragment only
has pname:rasterizationSamples locations associated with it regardless of
how many pixels are covered in the fragment area.
Fragment sample locations are defined as if the fragment had an area of
[eq]#(1,1)# and its sample points must: be located within these bounds.
Their actual location in the framebuffer is calculated by scaling the sample
location by the fragment area.
Attachments with storage for multiple samples per pixel are located at the
pixel sample locations.
Otherwise, the fragment's sample locations are generally used for evaluation
of associated data and fragment operations.
endif::VK_EXT_fragment_density_map[]

If the current pipeline includes a fragment shader with one or more
variables in its interface decorated with code:Sample and code:Input, the
data associated with those variables will be assigned independently for each
sample.
The values for each sample must: be evaluated at the location of the sample.
The data associated with any other variables not decorated with code:Sample
and code:Input need not be evaluated independently for each sample.

[[primsrast-multisampling-coverage-mask]]
A _coverage mask_ is generated for each fragment, based on which samples
within that fragment are determined to be within the area of the primitive
that generated the fragment.

Single pixel fragments
ifdef::VK_EXT_fragment_density_map[]
and multi-pixel fragments defined by a
<<renderpass-fragmentdensitymapattachment, fragment density map>>
endif::VK_EXT_fragment_density_map[]
have one set of samples.
ifdef::VK_NV_shading_rate_image[]
Multi-pixel fragments defined by a <<primsrast-shading-rate-image, shading
rate image>> have one set of samples per pixel.
endif::VK_NV_shading_rate_image[]
ifdef::VK_KHR_fragment_shading_rate[]
Multi-pixel fragments defined by setting the
<<primsrast-fragment-shading-rate, fragment shading rate>> have one set of
samples per pixel.
endif::VK_KHR_fragment_shading_rate[]
Each set of samples has a number of samples determined by
slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples.
Each sample in a set is assigned a unique _sample index_ [eq]#i# in the
range [eq]#[0, pname:rasterizationSamples)#.

ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]
[open,refpage='vkCmdSetRasterizationSamplesEXT',desc='Specify the rasterization samples dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the
pname:rasterizationSamples, call:

include::{generated}/api/protos/vkCmdSetRasterizationSamplesEXT.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:rasterizationSamples specifies pname:rasterizationSamples.

This command sets the pname:rasterizationSamples for subsequent drawing
commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_EXT_extended_dynamic_state3[]
Otherwise, this state is specified by the
slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples value
used to create the currently active pipeline.

.Valid Usage
****
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetRasterizationSamplesEXT-None-08552]]
    Either the <<features-extendedDynamicState3RasterizationSamples,
    pname:extendedDynamicState3RasterizationSamples>> feature or the
    <<features-shaderObject, pname:shaderObject>> feature or both must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
ifndef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetRasterizationSamplesEXT-None-08553]]
    The <<features-shaderObject, pname:shaderObject>> feature must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
endif::VK_EXT_shader_object[]
ifndef::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetRasterizationSamplesEXT-extendedDynamicState3RasterizationSamples-07414]]
    The <<features-extendedDynamicState3RasterizationSamples,
    pname:extendedDynamicState3RasterizationSamples>> feature must: be
    enabled
endif::VK_EXT_shader_object[]
****

include::{generated}/validity/protos/vkCmdSetRasterizationSamplesEXT.adoc[]
--
endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]

[[primsrast-multisampling-coverageindex]]
Each sample in a fragment is also assigned a unique _coverage index_ [eq]#j#
in the range [eq]#[0, n {times} pname:rasterizationSamples)#, where [eq]#n#
is the number of sets in the fragment.
If the fragment contains a single set of samples, the _coverage index_ is
always equal to the _sample index_.
ifdef::VK_NV_shading_rate_image[]
If a <<primsrast-shading-rate-image,shading rate image>> is used and a
fragment covers multiple pixels, the coverage index is determined as defined
by slink:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV or
flink:vkCmdSetCoarseSampleOrderNV.
endif::VK_NV_shading_rate_image[]

ifdef::VK_KHR_fragment_shading_rate[]
[[primsrast-multisampling-coverage-mask-vrfs]]
If the <<primsrast-fragment-shading-rate, fragment shading rate>> is set,
the coverage index [eq]#j# is determined as a function of the _pixel index_
[eq]#p#, the _sample index_ [eq]#i#, and the number of rasterization samples
[eq]#r# as:

  {empty}:: [eq]#j = i + r {times} ((f~w~ {times} f~h~) - 1 - p)#

where the pixel index [eq]#p# is determined as a function of the pixel's
framebuffer location [eq]#(x,y)# and the fragment size [eq]#(f~w~,f~h~)#:

  {empty}:: [eq]#p~x~ = x % f~w~#
  {empty}:: [eq]#p~y~ = y % f~h~#
  {empty}:: [eq]#p = p~x~ + (p~y~ {times} f~w~)#

The table below illustrates the pixel index for multi-pixel fragments:

.Pixel indices - 1 wide
[align="center"]
|====
| 1x1 | 1x2 | 1x4

.>| image:{images}/pixel_index_1x1.svg[pdfwidth=90pt,opts="{imageopts}"]
.>| image:{images}/pixel_index_1x2.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
.>| image:{images}/pixel_index_1x4.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
|====

.Pixel indices - 2 wide
[align="center"]
|====
| 2x1 | 2x2 | 2x4

.>| image:{images}/pixel_index_2x1.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
.>| image:{images}/pixel_index_2x2.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
.>| image:{images}/pixel_index_2x4.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
|====

.Pixel indices - 4 wide
[align="center"]
|====
| 4x1 | 4x2 | 4x4

.>| image:{images}/pixel_index_4x1.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
.>| image:{images}/pixel_index_4x2.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
.>| image:{images}/pixel_index_4x4.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
|====
endif::VK_KHR_fragment_shading_rate[]

The coverage mask includes [eq]#B# bits packed into [eq]#W# words, defined
as:

  {empty}:: [eq]#B = n {times} pname:rasterizationSamples#
  {empty}:: [eq]#W = {lceil}B/32{rceil}#

Bit [eq]#b# in coverage mask word [eq]#w# is `1` if the sample with coverage
index [eq]#j = 32{times}w + b# is covered, and `0` otherwise.

If the pname:standardSampleLocations member of slink:VkPhysicalDeviceLimits
is ename:VK_TRUE, then the sample counts ename:VK_SAMPLE_COUNT_1_BIT,
ename:VK_SAMPLE_COUNT_2_BIT, ename:VK_SAMPLE_COUNT_4_BIT,
ename:VK_SAMPLE_COUNT_8_BIT, and ename:VK_SAMPLE_COUNT_16_BIT have sample
locations as listed in the following table, with the [eq]##i##th entry in
the table corresponding to sample index [eq]#i#.
ename:VK_SAMPLE_COUNT_32_BIT and ename:VK_SAMPLE_COUNT_64_BIT do not have
standard sample locations.
Locations are defined relative to an origin in the upper left corner of the
fragment.

<<<

.Standard sample locations
[options="header",align="center"]
|====
| Sample count 2+| Sample Locations
|ename:VK_SAMPLE_COUNT_1_BIT
    | [eq]#(0.5,0.5)#
    | image:{images}/sample_count_1.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
|ename:VK_SAMPLE_COUNT_2_BIT
    | [eq]#(0.75,0.75)# +
      [eq]#(0.25,0.25)#
    | image:{images}/sample_count_2.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
|ename:VK_SAMPLE_COUNT_4_BIT
    | [eq]#(0.375, 0.125)# +
      [eq]#(0.875, 0.375)# +
      [eq]#(0.125, 0.625)# +
      [eq]#(0.625, 0.875)#
    | image:{images}/sample_count_4.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
|ename:VK_SAMPLE_COUNT_8_BIT
    | [eq]#(0.5625, 0.3125)# +
      [eq]#(0.4375, 0.6875)# +
      [eq]#(0.8125, 0.5625)# +
      [eq]#(0.3125, 0.1875)# +
      [eq]#(0.1875, 0.8125)# +
      [eq]#(0.0625, 0.4375)# +
      [eq]#(0.6875, 0.9375)# +
      [eq]#(0.9375, 0.0625)#
    | image:{images}/sample_count_8.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
|ename:VK_SAMPLE_COUNT_16_BIT
    | [eq]#(0.5625, 0.5625)# +
      [eq]#(0.4375, 0.3125)# +
      [eq]#(0.3125, 0.625)# +
      [eq]#(0.75,   0.4375)# +
      [eq]#(0.1875, 0.375)# +
      [eq]#(0.625,  0.8125)# +
      [eq]#(0.8125, 0.6875)# +
      [eq]#(0.6875, 0.1875)# +
      [eq]#(0.375,  0.875)# +
      [eq]#(0.5,    0.0625)# +
      [eq]#(0.25,   0.125)# +
      [eq]#(0.125,  0.75)# +
      [eq]#(0.0,    0.5)# +
      [eq]#(0.9375, 0.25)# +
      [eq]#(0.875,  0.9375)# +
      [eq]#(0.0625, 0.0)#
    | image:{images}/sample_count_16.svg[pdfwidth=90pt,align="center",opts="{imageopts}"]
|====

ifdef::VK_AMD_shader_fragment_mask[]
Color images created with multiple samples per pixel use a compression
technique where there are two arrays of data associated with each pixel.
The first array contains one element per sample where each element stores an
index to the second array defining the _fragment mask_ of the pixel.
The second array contains one element per _color fragment_ and each element
stores a unique color value in the format of the image.
With this compression technique it is not always necessary to actually use
unique storage locations for each color sample: when multiple samples share
the same color value the fragment mask may: have two samples referring to
the same color fragment.
The number of color fragments is determined by the pname:samples member of
the slink:VkImageCreateInfo structure used to create the image.
The `apiext:VK_AMD_shader_fragment_mask` device extension provides shader
instructions enabling the application to get direct access to the fragment
mask and the individual color fragment values.

[[vk-amd-shader-fragment-mask-diagram]]
image::{images}/fragment_mask.svg[align="center",title="Fragment Mask",align="center",opts="{imageopts}"]

endif::VK_AMD_shader_fragment_mask[]


ifdef::VK_EXT_sample_locations[]
[[primsrast-samplelocations]]
== Custom Sample Locations

[open,refpage='VkPipelineSampleLocationsStateCreateInfoEXT',desc='Structure specifying sample locations for a pipeline',type='structs']
--
Applications can: also control the sample locations used for rasterization.

If the pname:pNext chain of the slink:VkPipelineMultisampleStateCreateInfo
structure specified at pipeline creation time includes a
sname:VkPipelineSampleLocationsStateCreateInfoEXT structure, then that
structure controls the sample locations used when rasterizing primitives
with the pipeline.

The sname:VkPipelineSampleLocationsStateCreateInfoEXT structure is defined
as:

include::{generated}/api/structs/VkPipelineSampleLocationsStateCreateInfoEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:sampleLocationsEnable controls whether custom sample locations are
    used.
    If pname:sampleLocationsEnable is ename:VK_FALSE, the default sample
    locations are used and the values specified in pname:sampleLocationsInfo
    are ignored.
  * pname:sampleLocationsInfo is the sample locations to use during
    rasterization if pname:sampleLocationsEnable is ename:VK_TRUE and the
    graphics pipeline is not created with
    ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT.

include::{generated}/validity/structs/VkPipelineSampleLocationsStateCreateInfoEXT.adoc[]
--

[open,refpage='VkSampleLocationsInfoEXT',desc='Structure specifying a set of sample locations',type='structs']
--
The sname:VkSampleLocationsInfoEXT structure is defined as:

include::{generated}/api/structs/VkSampleLocationsInfoEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:sampleLocationsPerPixel is a elink:VkSampleCountFlagBits value
    specifying the number of sample locations per pixel.
  * pname:sampleLocationGridSize is the size of the sample location grid to
    select custom sample locations for.
  * pname:sampleLocationsCount is the number of sample locations in
    pname:pSampleLocations.
  * pname:pSampleLocations is a pointer to an array of
    pname:sampleLocationsCount slink:VkSampleLocationEXT structures.

This structure can: be used either to specify the sample locations to be
used for rendering or to specify the set of sample locations an image
subresource has been last rendered with for the purposes of layout
transitions of depth/stencil images created with
ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT.

The sample locations in pname:pSampleLocations specify
pname:sampleLocationsPerPixel number of sample locations for each pixel in
the grid of the size specified in pname:sampleLocationGridSize.
The sample location for sample [eq]#i# at the pixel grid location
[eq]#(x,y)# is taken from [eq]#pname:pSampleLocations[(x {plus} y {times}
pname:sampleLocationGridSize.width) {times} pname:sampleLocationsPerPixel
{plus} i]#.

ifdef::VK_EXT_fragment_density_map[]
If the render pass has a fragment density map, the implementation will
choose the sample locations for the fragment and the contents of
pname:pSampleLocations may: be ignored.
endif::VK_EXT_fragment_density_map[]

.Valid Usage
****
  * [[VUID-VkSampleLocationsInfoEXT-sampleLocationsPerPixel-01526]]
    pname:sampleLocationsPerPixel must: be a bit value that is set in
    slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:sampleLocationSampleCounts
  * [[VUID-VkSampleLocationsInfoEXT-sampleLocationsCount-01527]]
    pname:sampleLocationsCount must: equal
    [eq]#pname:sampleLocationsPerPixel {times}
    pname:sampleLocationGridSize.width {times}
    pname:sampleLocationGridSize.height#
****

include::{generated}/validity/structs/VkSampleLocationsInfoEXT.adoc[]
--

[open,refpage='VkSampleLocationEXT',desc='Structure specifying the coordinates of a sample location',type='structs']
--
The sname:VkSampleLocationEXT structure is defined as:

include::{generated}/api/structs/VkSampleLocationEXT.adoc[]

  * pname:x is the horizontal coordinate of the sample's location.
  * pname:y is the vertical coordinate of the sample's location.

The domain space of the sample location coordinates has an upper-left origin
within the pixel in framebuffer space.

The values specified in a sname:VkSampleLocationEXT structure are always
clamped to the implementation-dependent sample location coordinate range
[eq]#[pname:sampleLocationCoordinateRange[0],pname:sampleLocationCoordinateRange[1]]#
that can: be queried using
slink:VkPhysicalDeviceSampleLocationsPropertiesEXT.

include::{generated}/validity/structs/VkSampleLocationEXT.adoc[]
--

ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]

[open,refpage='vkCmdSetSampleLocationsEnableEXT',desc='Specify the samples locations enable state dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the
pname:sampleLocationsEnable state, call:

include::{generated}/api/protos/vkCmdSetSampleLocationsEnableEXT.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:sampleLocationsEnable specifies the pname:sampleLocationsEnable
    state.

This command sets the pname:sampleLocationsEnable state for subsequent
drawing commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_EXT_extended_dynamic_state3[]
Otherwise, this state is specified by the
slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable
value used to create the currently active pipeline.

.Valid Usage
****
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetSampleLocationsEnableEXT-None-08554]]
    Either the <<features-extendedDynamicState3SampleLocationsEnable,
    pname:extendedDynamicState3SampleLocationsEnable>> feature or the
    <<features-shaderObject, pname:shaderObject>> feature or both must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
ifndef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetSampleLocationsEnableEXT-None-08555]]
    The <<features-shaderObject, pname:shaderObject>> feature must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
endif::VK_EXT_shader_object[]
ifndef::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetSampleLocationsEnableEXT-extendedDynamicState3SampleLocationsEnable-07415]]
    The <<features-extendedDynamicState3SampleLocationsEnable,
    pname:extendedDynamicState3SampleLocationsEnable>> feature must: be
    enabled
endif::VK_EXT_shader_object[]
****

include::{generated}/validity/protos/vkCmdSetSampleLocationsEnableEXT.adoc[]
--

endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]

[open,refpage='vkCmdSetSampleLocationsEXT',desc='Set sample locations dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the sample locations used
for rasterization, call:

include::{generated}/api/protos/vkCmdSetSampleLocationsEXT.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pSampleLocationsInfo is the sample locations state to set.

This command sets the custom sample locations for subsequent drawing
commands
ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates, and when the
slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable
property of the bound graphics pipeline is ename:VK_TRUE.
Otherwise, this state is specified by the
slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsInfo
values used to create the currently active pipeline.

.Valid Usage
****
  * [[VUID-vkCmdSetSampleLocationsEXT-variableSampleLocations-01530]]
    If
    slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations
    is ename:VK_FALSE then the current render pass must: have been begun by
    specifying a slink:VkRenderPassSampleLocationsBeginInfoEXT structure
    whose pname:pPostSubpassSampleLocations member contains an element with
    a pname:subpassIndex matching the current subpass index and the
    pname:sampleLocationsInfo member of that element must: match the sample
    locations state pointed to by pname:pSampleLocationsInfo
****

include::{generated}/validity/protos/vkCmdSetSampleLocationsEXT.adoc[]
--
endif::VK_EXT_sample_locations[]


ifdef::VK_KHR_fragment_shading_rate[]
[[primsrast-fragment-shading-rate]]
== Fragment Shading Rates

The features advertised by
slink:VkPhysicalDeviceFragmentShadingRateFeaturesKHR allow an application to
control the <<glossary-shading-rate, shading rate>> of a given fragment
shader invocation.

The fragment shading rate strongly interacts with <<primsrast-multisampling,
Multisampling>>, and the set of available rates for an implementation may:
be restricted by sample rate.

[open,refpage='vkGetPhysicalDeviceFragmentShadingRatesKHR',desc='Get available shading rates for a physical device',type='protos']
--
:refpage: vkGetPhysicalDeviceFragmentShadingRatesKHR

To query available shading rates, call:

include::{generated}/api/protos/vkGetPhysicalDeviceFragmentShadingRatesKHR.adoc[]

  * pname:physicalDevice is the handle to the physical device whose
    properties will be queried.
  * pname:pFragmentShadingRateCount is a pointer to an integer related to
    the number of fragment shading rates available or queried, as described
    below.
  * pname:pFragmentShadingRates is either `NULL` or a pointer to an array of
    slink:VkPhysicalDeviceFragmentShadingRateKHR structures.

If pname:pFragmentShadingRates is `NULL`, then the number of fragment
shading rates available is returned in pname:pFragmentShadingRateCount.
Otherwise, pname:pFragmentShadingRateCount must: point to a variable set by
the user to the number of elements in the pname:pFragmentShadingRates array,
and on return the variable is overwritten with the number of structures
actually written to pname:pFragmentShadingRates.
If pname:pFragmentShadingRateCount is less than the number of fragment
shading rates available, at most pname:pFragmentShadingRateCount structures
will be written, and ename:VK_INCOMPLETE will be returned instead of
ename:VK_SUCCESS, to indicate that not all the available fragment shading
rates were returned.

The returned array of fragment shading rates must: be ordered from largest
pname:fragmentSize.width value to smallest, and each set of fragment shading
rates with the same pname:fragmentSize.width value must: be ordered from
largest pname:fragmentSize.height to smallest.
Any two entries in the array must: not have the same pname:fragmentSize
values.

For any entry in the array, the following rules also apply:

  * The value of pname:fragmentSize.width must: be less than or equal to
    <<limits-maxFragmentSize, pname:maxFragmentSize.width>>.
  * The value of pname:fragmentSize.width must: be greater than or equal to
    `1`.
  * The value of pname:fragmentSize.width must: be a power-of-two.
  * The value of pname:fragmentSize.height must: be less than or equal to
    <<limits-maxFragmentSize, pname:maxFragmentSize.height>>.
  * The value of pname:fragmentSize.height must: be greater than or equal to
    `1`.
  * The value of pname:fragmentSize.height must: be a power-of-two.
  * The highest sample count in pname:sampleCounts must: be less than or
    equal to <<limits-maxFragmentShadingRateRasterizationSamples,
    pname:maxFragmentShadingRateRasterizationSamples>>.
  * The product of pname:fragmentSize.width, pname:fragmentSize.height, and
    the highest sample count in pname:sampleCounts must: be less than or
    equal to <<limits-maxFragmentShadingRateCoverageSamples,
    pname:maxFragmentShadingRateCoverageSamples>>.

Implementations must: support at least the following shading rates:

[options="autowidth"]
|===
| pname:sampleCounts | pname:fragmentSize

| ename:VK_SAMPLE_COUNT_1_BIT \| ename:VK_SAMPLE_COUNT_4_BIT | {2,2}
| ename:VK_SAMPLE_COUNT_1_BIT \| ename:VK_SAMPLE_COUNT_4_BIT | {2,1}
| ~0                                                         | {1,1}
|===

If <<limits-framebufferColorSampleCounts,
pname:framebufferColorSampleCounts>>, includes ename:VK_SAMPLE_COUNT_2_BIT,
the required rates must: also include ename:VK_SAMPLE_COUNT_2_BIT.

[NOTE]
.Note
====
Including the {1,1} fragment size is done for completeness; it has no actual
effect on the support of rendering without setting the fragment size.
All sample counts
ifdef::VK_QCOM_render_pass_transform[]
and render pass transforms
endif::VK_QCOM_render_pass_transform[]
are supported for this rate.
====

ifdef::VK_QCOM_render_pass_transform[]
The returned set of fragment shading rates must: be returned in the native
(rotated) coordinate system.
For rasterization using render pass pname:transform not equal to
ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, the application must: transform
the returned fragment shading rates into the current (unrotated) coordinate
system to get the supported rates for that transform.

[NOTE]
.Note
====
For example, consider an implementation returning support for 4x2, but not
2x4 in the set of supported fragment shading rates.
This means that for transforms ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
and ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR, 2x4 is a supported rate,
but 4x2 is an unsupported rate.
====
endif::VK_QCOM_render_pass_transform[]

include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]

include::{generated}/validity/protos/vkGetPhysicalDeviceFragmentShadingRatesKHR.adoc[]
--

[open,refpage='VkPhysicalDeviceFragmentShadingRateKHR',desc='Structure returning information about sample count specific additional multisampling capabilities',type='structs']
--
The sname:VkPhysicalDeviceFragmentShadingRateKHR structure is defined as

include::{generated}/api/structs/VkPhysicalDeviceFragmentShadingRateKHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:sampleCounts is a bitmask of sample counts for which the shading
    rate described by pname:fragmentSize is supported.
  * pname:fragmentSize is a slink:VkExtent2D describing the width and height
    of a supported shading rate.

include::{generated}/validity/structs/VkPhysicalDeviceFragmentShadingRateKHR.adoc[]
--

Fragment shading rates can: be set at three points, with the three rates
combined to determine the final shading rate.


[[primsrast-fragment-shading-rate-pipeline]]
=== Pipeline Fragment Shading Rate

The _pipeline fragment shading rate_ can: be set on a per-draw basis by
either setting the rate in a graphics pipeline, or dynamically via
flink:vkCmdSetFragmentShadingRateKHR.

[open,refpage='VkPipelineFragmentShadingRateStateCreateInfoKHR',desc='Structure specifying parameters controlling the fragment shading rate',type='structs']
--
The sname:VkPipelineFragmentShadingRateStateCreateInfoKHR structure is
defined as:

include::{generated}/api/structs/VkPipelineFragmentShadingRateStateCreateInfoKHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:fragmentSize specifies a slink:VkExtent2D structure containing the
    fragment size used to define the pipeline fragment shading rate for
    drawing commands using this pipeline.
  * pname:combinerOps specifies a elink:VkFragmentShadingRateCombinerOpKHR
    value determining how the
    <<primsrast-fragment-shading-rate-pipeline,pipeline>>,
    <<primsrast-fragment-shading-rate-primitive,primitive>>, and
    <<primsrast-fragment-shading-rate-attachment,attachment shading rates>>
    are <<primsrast-fragment-shading-rate-combining,combined>> for fragments
    generated by drawing commands using the created pipeline.

If the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo includes a
sname:VkPipelineFragmentShadingRateStateCreateInfoKHR structure, then that
structure includes parameters controlling the pipeline fragment shading
rate.

If this structure is not present, pname:fragmentSize is considered to be
equal to [eq]#(1,1)#, and both elements of pname:combinerOps are considered
to be equal to ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR.

include::{generated}/validity/structs/VkPipelineFragmentShadingRateStateCreateInfoKHR.adoc[]
--

[open,refpage='vkCmdSetFragmentShadingRateKHR',desc='Set pipeline fragment shading rate and combiner operation dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the pipeline fragment
shading rate and combiner operation, call:

include::{generated}/api/protos/vkCmdSetFragmentShadingRateKHR.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pFragmentSize specifies the pipeline fragment shading rate for
    subsequent drawing commands.
  * pname:combinerOps specifies a elink:VkFragmentShadingRateCombinerOpKHR
    determining how the
    <<primsrast-fragment-shading-rate-pipeline,pipeline>>,
    <<primsrast-fragment-shading-rate-primitive,primitive>>, and
    <<primsrast-fragment-shading-rate-attachment,attachment shading rates>>
    are <<primsrast-fragment-shading-rate-combining,combined>> for fragments
    generated by subsequent drawing commands.

This command sets the pipeline fragment shading rate and combiner operation
for subsequent drawing commands
ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
Otherwise, this state is specified by the
slink:VkPipelineFragmentShadingRateStateCreateInfoKHR values used to create
the currently active pipeline.

.Valid Usage
****
  * [[VUID-vkCmdSetFragmentShadingRateKHR-pipelineFragmentShadingRate-04507]]
    If <<features-pipelineFragmentShadingRate,
    pname:pipelineFragmentShadingRate>> is not enabled,
    pname:pFragmentSize->width must: be `1`
  * [[VUID-vkCmdSetFragmentShadingRateKHR-pipelineFragmentShadingRate-04508]]
    If <<features-pipelineFragmentShadingRate,
    pname:pipelineFragmentShadingRate>> is not enabled,
    pname:pFragmentSize->height must: be `1`
  * [[VUID-vkCmdSetFragmentShadingRateKHR-pipelineFragmentShadingRate-04509]]
    One of <<features-pipelineFragmentShadingRate,
    pname:pipelineFragmentShadingRate>>,
    <<features-primitiveFragmentShadingRate,
    pname:primitiveFragmentShadingRate>>, or
    <<features-attachmentFragmentShadingRate,
    pname:attachmentFragmentShadingRate>> must: be enabled
  * [[VUID-vkCmdSetFragmentShadingRateKHR-primitiveFragmentShadingRate-04510]]
    If the <<features-primitiveFragmentShadingRate,
    pname:primitiveFragmentShadingRate>> feature is not enabled,
    pname:combinerOps[0] must: be
    ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR
  * [[VUID-vkCmdSetFragmentShadingRateKHR-attachmentFragmentShadingRate-04511]]
    If the <<features-attachmentFragmentShadingRate,
    pname:attachmentFragmentShadingRate>> feature is not enabled,
    pname:combinerOps[1] must: be
    ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR
  * [[VUID-vkCmdSetFragmentShadingRateKHR-fragmentSizeNonTrivialCombinerOps-04512]]
    If the <<limits-fragmentShadingRateNonTrivialCombinerOps,
    pname:fragmentSizeNonTrivialCombinerOps>> limit is not supported,
    elements of pname:combinerOps must: be either
    ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or
    ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR
  * [[VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04513]]
    pname:pFragmentSize->width must: be greater than or equal to `1`
  * [[VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04514]]
    pname:pFragmentSize->height must: be greater than or equal to `1`
  * [[VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04515]]
    pname:pFragmentSize->width must: be a power-of-two value
  * [[VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04516]]
    pname:pFragmentSize->height must: be a power-of-two value
  * [[VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04517]]
    pname:pFragmentSize->width must: be less than or equal to `4`
  * [[VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04518]]
    pname:pFragmentSize->height must: be less than or equal to `4`
****

include::{generated}/validity/protos/vkCmdSetFragmentShadingRateKHR.adoc[]
--


[[primsrast-fragment-shading-rate-primitive]]
=== Primitive Fragment Shading Rate

The _primitive fragment shading rate_ can: be set via the
<<interfaces-builtin-variables-primitiveshadingrate,
code:PrimitiveShadingRateKHR>> built-in in the last active
<<pipelines-graphics-subsets-pre-rasterization,pre-rasterization shader
stage>>.
ifdef::VK_EXT_mesh_shader[]
If the last <<pipelines-graphics-subsets-pre-rasterization,pre-rasterization
shader stage>> is using the code:MeshEXT {ExecutionModel}, the rate
associated with a given primitive is sourced from the value written to the
per-primitive code:PrimitiveShadingRateKHR.
Otherwise the
endif::VK_EXT_mesh_shader[]
ifndef::VK_EXT_mesh_shader[The]
rate associated with a given primitive is sourced from the value written to
code:PrimitiveShadingRateKHR by that primitive's
<<vertexpostproc-flatshading,provoking vertex>>.


[[primsrast-fragment-shading-rate-attachment]]
=== Attachment Fragment Shading Rate

The _attachment shading rate_ can: be set by including
slink:VkFragmentShadingRateAttachmentInfoKHR in a subpass to define a
_fragment shading rate attachment_.
Each pixel in the framebuffer is assigned an attachment fragment shading
rate by the corresponding texel in the fragment shading rate attachment,
according to:

  {empty}:: [eq]#x' = floor(x / region~x~)#
  {empty}:: [eq]#y' = floor(y / region~y~)#

where [eq]#x'# and [eq]#y'# are the coordinates of a texel in the fragment
shading rate attachment, [eq]#x# and [eq]#y# are the coordinates of the
pixel in the framebuffer, and [eq]#region~x~# and [eq]#region~y~# are the
size of the region each texel corresponds to, as defined by the
pname:shadingRateAttachmentTexelSize member of
slink:VkFragmentShadingRateAttachmentInfoKHR.

If <<VkRenderPassMultiviewCreateInfo, multiview is enabled>> and the shading
rate attachment has multiple layers, the shading rate attachment texel is
selected from the layer determined by the
<<interfaces-builtin-variables-viewindex,code:ViewIndex>> built-in.
If <<VkRenderPassMultiviewCreateInfo, multiview is disabled>>, and both the
shading rate attachment and the framebuffer have multiple layers, the
shading rate attachment texel is selected from the layer determined by the
<<interfaces-builtin-variables-layer,code:Layer>> built-in.
Otherwise, the texel is unconditionally selected from the first layer of the
attachment.

The fragment size is encoded into the first component of the identified
texel as follows:

  {empty}:: [eq]#size~w~ = 2^((texel / 4) & 3)^#
  {empty}:: [eq]#size~h~ = 2^(texel & 3)^#

where [eq]#texel# is the value in the first component of the identified
texel, and [eq]#size~w~# and [eq]#size~h~# are the width and height of the
fragment size, decoded from the texel.

If no fragment shading rate attachment is specified, this size is calculated
as [eq]#size~w~ = size~h~ = 1#.
Applications must: not specify a width or height greater than 4 by this
method.

The _Fragment Shading Rate_ enumeration in SPIR-V adheres to the above
encoding.


[[primsrast-fragment-shading-rate-combining]]
=== Combining the Fragment Shading Rates

The final rate ([eq]#C~xy~'#) used for fragment shading must: be one of the
rates returned by flink:vkGetPhysicalDeviceFragmentShadingRatesKHR for the
sample count
ifdef::VK_QCOM_render_pass_transform[]
and render pass transform
endif::VK_QCOM_render_pass_transform[]
used by rasterization.

If any of the following conditions are met, [eq]#C~xy~'# must: be set to
[eq]#{1,1}#:

  * If <<primsrast-sampleshading,Sample Shading>> is enabled.
  * The <<limits-fragmentShadingRateWithSampleMask,
    pname:fragmentShadingRateWithSampleMask>> limit is not supported, and
    slink:VkPipelineMultisampleStateCreateInfo::pname:pSampleMask contains a
    zero value in any bit used by fragment operations.
  * The <<limits-fragmentShadingRateWithShaderSampleMask,
    pname:fragmentShadingRateWithShaderSampleMask>> is not supported, and
    the fragment shader has code:SampleMask in the input or output
    interface.
  * The <<limits-fragmentShadingRateWithShaderDepthStencilWrites,
    pname:fragmentShadingRateWithShaderDepthStencilWrites>> limit is not
    supported, and the fragment shader declares the code:FragDepth
ifdef::VK_EXT_shader_stencil_export[]
    or code:FragStencilRefEXT
endif::VK_EXT_shader_stencil_export[]
    built-in.
ifdef::VK_EXT_conservative_rasterization[]
  * The <<limits-fragmentShadingRateWithConservativeRasterization,
    pname:fragmentShadingRateWithConservativeRasterization>> limit is not
    supported, and
    slink:VkPipelineRasterizationConservativeStateCreateInfoEXT::pname:conservativeRasterizationMode
    is not ename:VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT.
endif::VK_EXT_conservative_rasterization[]
ifdef::VK_EXT_fragment_shader_interlock[]
  * The <<limits-fragmentShadingRateWithFragmentShaderInterlock,
    pname:fragmentShadingRateWithFragmentShaderInterlock>> limit is not
    supported, and the fragment shader declares any of the
    <<fragops-shader-interlock, fragment shader interlock>> execution modes.
endif::VK_EXT_fragment_shader_interlock[]
ifdef::VK_EXT_sample_locations[]
  * The <<limits-fragmentShadingRateWithCustomSampleLocations,
    pname:fragmentShadingRateWithCustomSampleLocations>> limit is not
    supported, and
    slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable
    is ename:VK_TRUE.
endif::VK_EXT_sample_locations[]
ifdef::VK_EXT_shader_tile_image[]
  * The fragment shader declares any of the
    code:TileImageColorReadAccessEXT, code:TileImageDepthReadAccessEXT, or
    code:TileImageStencilReadAccessEXT capabilities.
endif::VK_EXT_shader_tile_image[]

Otherwise, each of the specified shading rates are combined and then used to
derive the value of [eq]#C~xy~'#.
As there are three ways to specify shading rates, two combiner operations
are specified - between the
<<primsrast-fragment-shading-rate-pipeline,pipeline>> and
<<primsrast-fragment-shading-rate-primitive,primitive>> shading rates, and
between the result of that and the
<<primsrast-fragment-shading-rate-attachment,attachment shading rate>>.

[open,refpage='VkFragmentShadingRateCombinerOpKHR',desc='Control how fragment shading rates are combined',type='enums']
--
The equation used for each combiner operation is defined by
ename:VkFragmentShadingRateCombinerOpKHR:

include::{generated}/api/enums/VkFragmentShadingRateCombinerOpKHR.adoc[]

  * ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR specifies a combiner
    operation of [eq]#combine(A~xy~,B~xy~) = A~xy~#.
  * ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR specifies a
    combiner operation of [eq]#combine(A~xy~,B~xy~) = B~xy~#.
  * ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR specifies a combiner
    operation of [eq]#combine(A~xy~,B~xy~) = min(A~xy~,B~xy~)#.
  * ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR specifies a combiner
    operation of [eq]#combine(A~xy~,B~xy~) = max(A~xy~,B~xy~)#.
  * ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR specifies a combiner
    operation of [eq]#combine(A~xy~,B~xy~) = A~xy~*B~xy~#.

where [eq]#combine(A~xy~,B~xy~)# is the combine operation, and [eq]#A~xy~#
and [eq]#B~xy~# are the inputs to the operation.

If <<limits-fragmentShadingRateStrictMultiplyCombiner,
pname:fragmentShadingRateStrictMultiplyCombiner>> is ename:VK_FALSE, using
ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR with values of 1 for both
A and B in the same dimension results in the value 2 being produced for that
dimension.
See the definition of <<limits-fragmentShadingRateStrictMultiplyCombiner,
pname:fragmentShadingRateStrictMultiplyCombiner>> for more information.

These operations are performed in a component-wise fashion.
--

This is used to generate a combined fragment area using the equation:

  {empty}:: [eq]#C~xy~ = combine(A~xy~,B~xy~)#

where [eq]#C~xy~# is the combined fragment area result, and [eq]#A~xy~# and
[eq]#B~xy~# are the fragment areas of the fragment shading rates being
combined.

Two combine operations are performed, first with [eq]#A~xy~# equal to the
<<primsrast-fragment-shading-rate-pipeline,pipeline fragment shading rate>>
and [eq]#B~xy~# equal to the <<primsrast-fragment-shading-rate-primitive,
primitive fragment shading rate>>, with the [eq]#combine()# operation
selected by combinerOps[0].
A second combination is then performed, with [eq]#A~xy~# equal to the result
of the first combination and [eq]#B~xy~# equal to the
<<primsrast-fragment-shading-rate-attachment, attachment fragment shading
rate>>, with the [eq]#combine()# operation selected by combinerOps[1].
The result of the second combination is used as the final fragment shading
rate, reported via the <<interfaces-builtin-variables-primitiveshadingrate,
code:ShadingRateKHR built-in>>.

Implementations should: clamp the inputs to the combiner operations
[eq]#A~xy~# and [eq]#B~xy~#, and must: clamp the result of the second
combiner operation.

A fragment shading rate [eq]#R~xy~# representing any of [eq]#A~xy~#,
[eq]#B~xy~# or [eq]#C~xy~# is clamped as follows.
If [eq]#R~xy~# is one of the rates returned by
flink:vkGetPhysicalDeviceFragmentShadingRatesKHR for the sample count
ifdef::VK_QCOM_render_pass_transform[]
and render pass transform
endif::VK_QCOM_render_pass_transform[]
used by rasterization, the clamped shading rate [eq]#R~xy~'# is [eq]#R~xy~#.
Otherwise, the clamped shading rate is selected from the rates returned by
flink:vkGetPhysicalDeviceFragmentShadingRatesKHR for the sample count
ifdef::VK_QCOM_render_pass_transform[]
and render pass transform
endif::VK_QCOM_render_pass_transform[]
used by rasterization.
From this list of supported rates, the following steps are applied in order,
to select a single value:

  . Keep only rates where [eq]#R~x~' {leq} R~x~# and [eq]#R~y~' {leq} R~y~#.
  ** Implementations may: also keep rates where [eq]#R~x~' {leq} R~y~# and
     [eq]#R~y~' {leq} R~x~#.
  . Keep only rates with the highest area ([eq]#R~x~' {times} R~y~'#).
  . Keep only rates with the lowest aspect ratio ([eq]#R~x~' {plus} R~y~'#).
  . In cases where a wide (e.g. 4x1) and tall (e.g. 1x4) rate remain, the
    implementation may: choose either rate.
    However, it must: choose this rate consistently for the same shading
    rates,
ifdef::VK_QCOM_render_pass_transform[]
    render pass transform,
endif::VK_QCOM_render_pass_transform[]
    and combiner operations for the lifetime of the slink:VkDevice.
endif::VK_KHR_fragment_shading_rate[]


ifdef::VK_NV_fragment_shading_rate_enums[]
=== Extended Fragment Shading Rates

The features advertised by
slink:VkPhysicalDeviceFragmentShadingRateEnumsFeaturesNV provide support for
additional fragment shading rates beyond those specifying one fragment
shader invocation covering all pixels in a fragment whose size is indicated
by the fragment shading rate.

[open,refpage='VkFragmentShadingRateNV',desc='Enumeration with fragment shading rates',type='enums']
--
If the pname:fragmentShadingRateEnums feature is enabled, fragment shading
rates may be specified using the elink:VkFragmentShadingRateNV enumerated
type defined as:

include::{generated}/api/enums/VkFragmentShadingRateNV.adoc[]

  * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NV specifies a
    fragment size of 1x1 pixels.
  * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_1X2_PIXELS_NV specifies
    a fragment size of 1x2 pixels.
  * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_2X1_PIXELS_NV specifies
    a fragment size of 2x1 pixels.
  * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_2X2_PIXELS_NV specifies
    a fragment size of 2x2 pixels.
  * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_2X4_PIXELS_NV specifies
    a fragment size of 2x4 pixels.
  * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_4X2_PIXELS_NV specifies
    a fragment size of 4x2 pixels.
  * ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_4X4_PIXELS_NV specifies
    a fragment size of 4x4 pixels.
  * ename:VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NV specifies a
    fragment size of 1x1 pixels, with two fragment shader invocations per
    fragment.
  * ename:VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NV specifies a
    fragment size of 1x1 pixels, with four fragment shader invocations per
    fragment.
  * ename:VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NV specifies a
    fragment size of 1x1 pixels, with eight fragment shader invocations per
    fragment.
  * ename:VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NV specifies a
    fragment size of 1x1 pixels, with sixteen fragment shader invocations
    per fragment.
  * ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV specifies that any
    portions of a primitive that use that shading rate should be discarded
    without invoking any fragment shader.

To use the shading rates
ename:VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NV,
ename:VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NV,
ename:VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NV, and
ename:VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NV as a pipeline,
primitive, or attachment shading rate, the
pname:supersampleFragmentShadingRates feature must: be enabled.
To use the shading rate ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV as
a pipeline, primitive, or attachment shading rate, the
pname:noInvocationFragmentShadingRates feature must: be enabled.
--

When using fragment shading rate enums, the pipeline fragment shading rate
can: be set on a per-draw basis by either setting the rate in a graphics
pipeline, or dynamically via flink:vkCmdSetFragmentShadingRateEnumNV.

[open,refpage='VkPipelineFragmentShadingRateEnumStateCreateInfoNV',desc='Structure specifying parameters controlling the fragment shading rate using rate enums',type='structs']
--
The sname:VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure is
defined as:

include::{generated}/api/structs/VkPipelineFragmentShadingRateEnumStateCreateInfoNV.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:shadingRateType specifies a elink:VkFragmentShadingRateTypeNV
    value indicating whether fragment shading rates are specified using
    fragment sizes or elink:VkFragmentShadingRateNV enums.
  * pname:shadingRate specifies a elink:VkFragmentShadingRateNV value
    indicating the pipeline fragment shading rate.
  * pname:combinerOps specifies elink:VkFragmentShadingRateCombinerOpKHR
    values determining how the
    <<primsrast-fragment-shading-rate-pipeline,pipeline>>,
    <<primsrast-fragment-shading-rate-primitive,primitive>>, and
    <<primsrast-fragment-shading-rate-attachment,attachment shading rates>>
    are <<primsrast-fragment-shading-rate-combining,combined>> for fragments
    generated by drawing commands using the created pipeline.

If the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo includes a
sname:VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure, then
that structure includes parameters controlling the pipeline fragment shading
rate.

If this structure is not present, pname:shadingRateType is considered to be
equal to ename:VK_FRAGMENT_SHADING_RATE_TYPE_FRAGMENT_SIZE_NV,
pname:shadingRate is considered to be equal to
ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NV, and both elements
of pname:combinerOps are considered to be equal to
ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR.

include::{generated}/validity/structs/VkPipelineFragmentShadingRateEnumStateCreateInfoNV.adoc[]
--

[open,refpage='VkFragmentShadingRateTypeNV',desc='Enumeration with fragment shading rate types',type='enums']
--
The elink:VkFragmentShadingRateTypeNV enumerated type specifies whether a
graphics pipeline gets its pipeline fragment shading rates and combiners
from the slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure
or the slink:VkPipelineFragmentShadingRateStateCreateInfoKHR structure.

include::{generated}/api/enums/VkFragmentShadingRateTypeNV.adoc[]

  * ename:VK_FRAGMENT_SHADING_RATE_TYPE_FRAGMENT_SIZE_NV specifies that a
    graphics pipeline should obtain its pipeline fragment shading rate and
    shading rate combiner state from the
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR structure and that
    any state specified by the
    slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure
    should be ignored.
  * ename:VK_FRAGMENT_SHADING_RATE_TYPE_ENUMS_NV specifies that a graphics
    pipeline should obtain its pipeline fragment shading rate and shading
    rate combiner state from the
    slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV structure and
    that any state specified by the
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR structure should
    be ignored.
--

[open,refpage='vkCmdSetFragmentShadingRateEnumNV',desc='Set pipeline fragment shading rate dynamically for a command buffer using enums',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the pipeline fragment
shading rate and combiner operation, call:

include::{generated}/api/protos/vkCmdSetFragmentShadingRateEnumNV.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:shadingRate specifies a elink:VkFragmentShadingRateNV enum
    indicating the pipeline fragment shading rate for subsequent drawing
    commands.
  * pname:combinerOps specifies a elink:VkFragmentShadingRateCombinerOpKHR
    determining how the
    <<primsrast-fragment-shading-rate-pipeline,pipeline>>,
    <<primsrast-fragment-shading-rate-primitive,primitive>>, and
    <<primsrast-fragment-shading-rate-attachment,attachment shading rates>>
    are <<primsrast-fragment-shading-rate-combining,combined>> for fragments
    generated by subsequent drawing commands.

This command sets the pipeline fragment shading rate and combiner operation
for subsequent drawing commands
ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
Otherwise, this state is specified by the
slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV values used to
create the currently active pipeline.

[NOTE]
.Note
====
This command allows specifying additional shading rates beyond those
supported by flink:vkCmdSetFragmentShadingRateKHR.
For more information, refer to the
`apiext:VK_NV_fragment_shading_rate_enums` appendix.
====

.Valid Usage
****
  * [[VUID-vkCmdSetFragmentShadingRateEnumNV-pipelineFragmentShadingRate-04576]]
    If <<features-pipelineFragmentShadingRate,
    pname:pipelineFragmentShadingRate>> is not enabled, pname:shadingRate
    must: be ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NV
  * [[VUID-vkCmdSetFragmentShadingRateEnumNV-supersampleFragmentShadingRates-04577]]
    If <<features-supersampleFragmentShadingRates,
    pname:supersampleFragmentShadingRates>> is not enabled,
    pname:shadingRate must: not be
    ename:VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NV,
    ename:VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NV,
    ename:VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NV, or
    ename:VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NV
  * [[VUID-vkCmdSetFragmentShadingRateEnumNV-noInvocationFragmentShadingRates-04578]]
    If <<features-noInvocationFragmentShadingRates,
    pname:noInvocationFragmentShadingRates>> is not enabled,
    pname:shadingRate must: not be
    ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV
  * [[VUID-vkCmdSetFragmentShadingRateEnumNV-fragmentShadingRateEnums-04579]]
    The <<features-fragmentShadingRateEnums,
    pname:fragmentShadingRateEnums>> feature must: be enabled
  * [[VUID-vkCmdSetFragmentShadingRateEnumNV-pipelineFragmentShadingRate-04580]]
    One of the <<features-pipelineFragmentShadingRate,
    pname:pipelineFragmentShadingRate>>,
    <<features-primitiveFragmentShadingRate,
    pname:primitiveFragmentShadingRate>>, or
    <<features-attachmentFragmentShadingRate,
    pname:attachmentFragmentShadingRate>> features must: be enabled
  * [[VUID-vkCmdSetFragmentShadingRateEnumNV-primitiveFragmentShadingRate-04581]]
    If the <<features-primitiveFragmentShadingRate,
    pname:primitiveFragmentShadingRate>> feature is not enabled,
    pname:combinerOps[0] must: be
    ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR
  * [[VUID-vkCmdSetFragmentShadingRateEnumNV-attachmentFragmentShadingRate-04582]]
    If the <<features-attachmentFragmentShadingRate,
    pname:attachmentFragmentShadingRate>> feature is not enabled,
    pname:combinerOps[1] must: be
    ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR
  * [[VUID-vkCmdSetFragmentShadingRateEnumNV-fragmentSizeNonTrivialCombinerOps-04583]]
    If the <<limits-fragmentShadingRateNonTrivialCombinerOps,
    pname:fragmentSizeNonTrivialCombinerOps>> limit is not supported,
    elements of pname:combinerOps must: be either
    ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or
    ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR
****

include::{generated}/validity/protos/vkCmdSetFragmentShadingRateEnumNV.adoc[]
--

When the <<features-supersampleFragmentShadingRates,
pname:supersampleFragmentShadingRates>> or
<<features-noInvocationFragmentShadingRates,
pname:noInvocationFragmentShadingRates>> features are enabled, the behavior
of the <<primsrast-fragment-shading-rate-combining,shading rate combiner
operations>> is extended to support the shading rates enabled by those
features.
Primitive and attachment shading rate values are interpreted as
elink:VkFragmentShadingRateNV values and the behavior of the combiners is
modified as follows:

  * For ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR,
    ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR, and
    ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR, if either
    [eq]#A~xy~# or [eq]#B~xy~# is
    ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV,
    [eq]#combine(A~xy~,B~xy~)# produces a shading rate of
    ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV, regardless of the
    other input shading rate.
  * For ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR,
    [eq]#combine(A~xy~,B~xy~)# produces a shading rate whose fragment size
    is the smaller of the fragment sizes of [eq]#A~xy~# and [eq]#B~xy~# and
    whose invocation count is the larger of the invocation counts of
    [eq]#A~xy~# and [eq]#B~xy~#.
  * For ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR,
    [eq]#combine(A~xy~,B~xy~)# produces a shading rate whose fragment size
    is the larger of the fragment sizes of [eq]#A~xy~# and [eq]#B~xy~# and
    whose invocation count is the smaller of the invocation counts of
    [eq]#A~xy~# and [eq]#B~xy~#.
  * For ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR,
    [eq]#combine(A~xy~,B~xy~)# produces a shading rate whose fragment size
    and invocation count is the product of the fragment sizes and invocation
    counts, respectively, of [eq]#A~xy~# and [eq]#B~xy~#.
    If the resulting shading rate has both multiple pixels and multiple
    invocations per fragment, an implementation may: adjust the shading rate
    by reducing both the pixel and invocation counts.

If the final shading rate from the combiners is
ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV, no fragments will be
generated for any portion of a primitive using that shading rate.

If the final shading rate from the combiners specifies multiple fragment
shader invocations per fragment, the fragment will be processed with
multiple unique samples as in <<primsrast-sampleshading, sample shading>>,
where the total number the total number of invocations is taken from the
shading rate and then clamped to pname:rasterizationSamples and
<<limits-maxFragmentShadingRateInvocationCount,
pname:maxFragmentShadingRateInvocationCount>>.

endif::VK_NV_fragment_shading_rate_enums[]


ifdef::VK_NV_shading_rate_image[]
[[primsrast-shading-rate-image]]
== Shading Rate Image

The <<features-shadingRateImage, pname:shadingRateImage>> feature allows
pipelines to use a <<glossary-shading-rate-image,shading rate image>> to
control the <<glossary-fragment-area, fragment area>> and the minimum number
of fragment shader invocations launched for each fragment.
When the shading rate image is enabled, the rasterizer determines a base
<<glossary-shading-rate,shading rate>> for each region of the framebuffer
covered by a primitive by fetching a value from the shading rate image and
translating it to a shading rate using a per-viewport shading rate palette.
This base shading rate is then adjusted to derive a final shading rate.
The final shading rate specifies the fragment area and fragment shader
invocation count to use for fragments generated in the region.

[open,refpage='VkPipelineViewportShadingRateImageStateCreateInfoNV',desc='Structure specifying parameters controlling shading rate image usage',type='structs']
--
If the pname:pNext chain of slink:VkPipelineViewportStateCreateInfo includes
a sname:VkPipelineViewportShadingRateImageStateCreateInfoNV structure, then
that structure includes parameters controlling the shading rate.

The sname:VkPipelineViewportShadingRateImageStateCreateInfoNV structure is
defined as:

include::{generated}/api/structs/VkPipelineViewportShadingRateImageStateCreateInfoNV.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:shadingRateImageEnable specifies whether shading rate image and
    palettes are used during rasterization.
  * pname:viewportCount specifies the number of per-viewport palettes used
    to translate values stored in shading rate images.
  * pname:pShadingRatePalettes is a pointer to an array of
    slink:VkShadingRatePaletteNV structures defining the palette for each
    viewport.
    If the shading rate palette state is dynamic, this member is ignored.

If this structure is not present, pname:shadingRateImageEnable is considered
to be ename:VK_FALSE, and the shading rate image and palettes are not used.

.Valid Usage
****
  * [[VUID-VkPipelineViewportShadingRateImageStateCreateInfoNV-viewportCount-02054]]
    If the <<features-multiViewport, pname:multiViewport>> feature is not
    enabled, pname:viewportCount must: be `0` or `1`
  * [[VUID-VkPipelineViewportShadingRateImageStateCreateInfoNV-viewportCount-02055]]
    pname:viewportCount must: be less than or equal to
    sname:VkPhysicalDeviceLimits::pname:maxViewports
  * [[VUID-VkPipelineViewportShadingRateImageStateCreateInfoNV-shadingRateImageEnable-02056]]
    If pname:shadingRateImageEnable is ename:VK_TRUE, pname:viewportCount
    must: be greater or equal to the pname:viewportCount member of
    slink:VkPipelineViewportStateCreateInfo
****
include::{generated}/validity/structs/VkPipelineViewportShadingRateImageStateCreateInfoNV.adoc[]
--

[open,refpage='vkCmdBindShadingRateImageNV',desc='Bind a shading rate image on a command buffer',type='protos']
--
When shading rate image usage is enabled in the bound pipeline, the pipeline
uses a shading rate image specified by the command:

include::{generated}/api/protos/vkCmdBindShadingRateImageNV.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:imageView is an image view handle specifying the shading rate
    image.
    pname:imageView may: be set to dlink:VK_NULL_HANDLE, which is equivalent
    to specifying a view of an image filled with zero values.
  * pname:imageLayout is the layout that the image subresources accessible
    from pname:imageView will be in when the shading rate image is accessed.

.Valid Usage
****
  * [[VUID-vkCmdBindShadingRateImageNV-None-02058]]
    The <<features-shadingRateImage, pname:shadingRateImage>> feature must:
    be enabled
  * [[VUID-vkCmdBindShadingRateImageNV-imageView-02059]]
    If pname:imageView is not dlink:VK_NULL_HANDLE, it must: be a valid
    slink:VkImageView handle of type ename:VK_IMAGE_VIEW_TYPE_2D or
    ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY
  * [[VUID-vkCmdBindShadingRateImageNV-imageView-02060]]
    If pname:imageView is not dlink:VK_NULL_HANDLE, it must: have a format
    of ename:VK_FORMAT_R8_UINT
  * [[VUID-vkCmdBindShadingRateImageNV-imageView-02061]]
    If pname:imageView is not dlink:VK_NULL_HANDLE, it must: have been
    created with a pname:usage value including
    ename:VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV
  * [[VUID-vkCmdBindShadingRateImageNV-imageView-02062]]
    If pname:imageView is not dlink:VK_NULL_HANDLE, pname:imageLayout must:
    match the actual elink:VkImageLayout of each subresource accessible from
    pname:imageView at the time the subresource is accessed
  * [[VUID-vkCmdBindShadingRateImageNV-imageLayout-02063]]
    If pname:imageView is not dlink:VK_NULL_HANDLE, pname:imageLayout must:
    be ename:VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV or
    ename:VK_IMAGE_LAYOUT_GENERAL
****

include::{generated}/validity/protos/vkCmdBindShadingRateImageNV.adoc[]
--

When the shading rate image is enabled in the current pipeline, rasterizing
a primitive covering the pixel with coordinates (_x_,_y_) will fetch a
shading rate index value from the shading rate image bound by
fname:vkCmdBindShadingRateImageNV.
If the shading rate image view has a type of ename:VK_IMAGE_VIEW_TYPE_2D,
the lookup will use texel coordinates (_u_,_v_) where latexmath:[u =
\left\lfloor \frac{x}{twidth} \right\rfloor], latexmath:[v = \left\lfloor
\frac{y}{theight} \right\rfloor], and latexmath:[twidth] and
latexmath:[theight] are the width and height of the implementation-dependent
<<limits-shadingRateTexelSize, shading rate texel size>>.
If the shading rate image view has a type of
ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, the lookup will use texel coordinates
(_u_,_v_) to extract a texel from the layer _l_, where _l_ is the layer of
the framebuffer being rendered to.
If _l_ is greater than or equal to the number of layers in the image view,
layer zero will be used.

If the bound shading rate image view is not dlink:VK_NULL_HANDLE and
contains a texel with coordinates (_u_,_v_) in layer _l_ (if applicable),
the single unsigned integer component for that texel will be used as the
shading rate index.
If the (_u_,_v_) coordinate is outside the extents of the subresource used
by the shading rate image view, or if the image view is
dlink:VK_NULL_HANDLE, the shading rate index is zero.
If the shading rate image view has multiple mipmap levels, the base level
identified by sname:VkImageSubresourceRange::pname:baseMipLevel will be
used.

A shading rate index is mapped to a base shading rate using a lookup table
called the shading rate image palette.
There is a separate palette for each viewport.
The number of entries in each palette is given by the
implementation-dependent <<limits-shadingRatePaletteSize, shading rate image
palette size>>.

ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]
[open,refpage='vkCmdSetShadingRateImageEnableNV',desc='Specify the shading rate image enable state dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the
pname:shadingRateImageEnable state, call:

include::{generated}/api/protos/vkCmdSetShadingRateImageEnableNV.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:shadingRateImageEnable specifies the pname:shadingRateImageEnable
    state.

This command sets the pname:shadingRateImageEnable state for subsequent
drawing commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_EXT_extended_dynamic_state3[]
Otherwise, this state is specified by the
slink:VkPipelineViewportShadingRateImageStateCreateInfoNV::pname:shadingRateImageEnable
value used to create the currently active pipeline.

.Valid Usage
****
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetShadingRateImageEnableNV-None-08556]]
    Either the <<features-extendedDynamicState3ShadingRateImageEnable,
    pname:extendedDynamicState3ShadingRateImageEnable>> feature or the
    <<features-shaderObject, pname:shaderObject>> feature or both must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
ifndef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetShadingRateImageEnableNV-None-08557]]
    The <<features-shaderObject, pname:shaderObject>> feature must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
endif::VK_EXT_shader_object[]
ifndef::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetShadingRateImageEnableNV-extendedDynamicState3ShadingRateImageEnable-07416]]
    The <<features-extendedDynamicState3ShadingRateImageEnable,
    pname:extendedDynamicState3ShadingRateImageEnable>> feature must: be
    enabled
endif::VK_EXT_shader_object[]
****

include::{generated}/validity/protos/vkCmdSetShadingRateImageEnableNV.adoc[]
--
endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]

[open,refpage='vkCmdSetViewportShadingRatePaletteNV',desc='Set shading rate image palettes dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the per-viewport shading
rate image palettes, call:

include::{generated}/api/protos/vkCmdSetViewportShadingRatePaletteNV.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:firstViewport is the index of the first viewport whose shading
    rate palette is updated by the command.
  * pname:viewportCount is the number of viewports whose shading rate
    palettes are updated by the command.
  * pname:pShadingRatePalettes is a pointer to an array of
    slink:VkShadingRatePaletteNV structures defining the palette for each
    viewport.

This command sets the per-viewport shading rate image palettes for
subsequent drawing commands
ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
Otherwise, this state is specified by the
slink:VkPipelineViewportShadingRateImageStateCreateInfoNV::pname:pShadingRatePalettes
values used to create the currently active pipeline.

.Valid Usage
****
  * [[VUID-vkCmdSetViewportShadingRatePaletteNV-None-02064]]
    The <<features-shadingRateImage, pname:shadingRateImage>> feature must:
    be enabled
  * [[VUID-vkCmdSetViewportShadingRatePaletteNV-firstViewport-02067]]
    The sum of pname:firstViewport and pname:viewportCount must: be between
    `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive
  * [[VUID-vkCmdSetViewportShadingRatePaletteNV-firstViewport-02068]]
    If the <<features-multiViewport, pname:multiViewport>> feature is not
    enabled, pname:firstViewport must: be `0`
  * [[VUID-vkCmdSetViewportShadingRatePaletteNV-viewportCount-02069]]
    If the <<features-multiViewport, pname:multiViewport>> feature is not
    enabled, pname:viewportCount must: be `1`
****

include::{generated}/validity/protos/vkCmdSetViewportShadingRatePaletteNV.adoc[]
--

[open,refpage='VkShadingRatePaletteNV',desc='Structure specifying a single shading rate palette',type='structs']
--
The sname:VkShadingRatePaletteNV structure specifies to contents of a single
shading rate image palette and is defined as:

include::{generated}/api/structs/VkShadingRatePaletteNV.adoc[]

  * pname:shadingRatePaletteEntryCount specifies the number of entries in
    the shading rate image palette.
  * pname:pShadingRatePaletteEntries is a pointer to an array of
    elink:VkShadingRatePaletteEntryNV enums defining the shading rate for
    each palette entry.

.Valid Usage
****
  * [[VUID-VkShadingRatePaletteNV-shadingRatePaletteEntryCount-02071]]
    pname:shadingRatePaletteEntryCount must: be between `1` and
    sname:VkPhysicalDeviceShadingRateImagePropertiesNV::pname:shadingRatePaletteSize,
    inclusive

****
include::{generated}/validity/structs/VkShadingRatePaletteNV.adoc[]
--

To determine the base shading rate image, a shading rate index _i_ is mapped
to array element _i_ in the array pname:pShadingRatePaletteEntries for the
palette corresponding to the viewport used for the fragment.
If _i_ is greater than or equal to the palette size
pname:shadingRatePaletteEntryCount, the base shading rate is undefined:.

[open,refpage='VkShadingRatePaletteEntryNV',desc='Shading rate image palette entry types',type='enums']
--
The supported shading rate image palette entries are defined by
elink:VkShadingRatePaletteEntryNV:

include::{generated}/api/enums/VkShadingRatePaletteEntryNV.adoc[]

The following table indicates the width and height (in pixels) of each
fragment generated using the indicated shading rate, as well as the maximum
number of fragment shader invocations launched for each fragment.
When processing regions of a primitive that have a shading rate of
ename:VK_SHADING_RATE_PALETTE_ENTRY_NO_INVOCATIONS_NV, no fragments will be
generated in that region.

[options="header"]
|====
| Shading Rate | Width | Height | Invocations
| ename:VK_SHADING_RATE_PALETTE_ENTRY_NO_INVOCATIONS_NV                 | 0 | 0 | 0
| ename:VK_SHADING_RATE_PALETTE_ENTRY_16_INVOCATIONS_PER_PIXEL_NV       | 1 | 1 | 16
| ename:VK_SHADING_RATE_PALETTE_ENTRY_8_INVOCATIONS_PER_PIXEL_NV        | 1 | 1 | 8
| ename:VK_SHADING_RATE_PALETTE_ENTRY_4_INVOCATIONS_PER_PIXEL_NV        | 1 | 1 | 4
| ename:VK_SHADING_RATE_PALETTE_ENTRY_2_INVOCATIONS_PER_PIXEL_NV        | 1 | 1 | 2
| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_PIXEL_NV         | 1 | 1 | 1
| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_2X1_PIXELS_NV    | 2 | 1 | 1
| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_1X2_PIXELS_NV    | 1 | 2 | 1
| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_2X2_PIXELS_NV    | 2 | 2 | 1
| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_4X2_PIXELS_NV    | 4 | 2 | 1
| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_2X4_PIXELS_NV    | 2 | 4 | 1
| ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_4X4_PIXELS_NV    | 4 | 4 | 1
|====
--

When the shading rate image is disabled, a shading rate of
ename:VK_SHADING_RATE_PALETTE_ENTRY_1_INVOCATION_PER_PIXEL_NV will be used
as the base shading rate.

Once a base shading rate has been established, it is adjusted to produce a
final shading rate.
First, if the base shading rate uses multiple pixels for each fragment, the
implementation may: reduce the fragment area to ensure that the total number
of coverage samples for all pixels in a fragment does not exceed
<<limits-shadingRateMaxCoarseSamples, an implementation-dependent maximum>>.

If <<primsrast-sampleshading, sample shading>> is active in the current
pipeline and would result in processing _n_ (_n_ > 1) unique samples per
fragment when the shading rate image is disabled, the shading rate is
adjusted in an implementation-dependent manner to increase the number of
fragment shader invocations spawned by the primitive.
If the shading rate indicates _fs_ pixels per fragment and _fs_ is greater
than _n_, the fragment area is adjusted so each fragment has approximately
latexmath:[fs \over n] pixels.
Otherwise, if the shading rate indicates _ipf_ invocations per fragment, the
fragment area will be adjusted to a single pixel with approximately
latexmath:[ipf \times n \over fs] invocations per fragment.

If sample shading occurs due to the use of a fragment shader input variable
decorated with code:SampleId or code:SamplePosition, the shading rate is
ignored.
Each fragment will have a single pixel and will spawn up to
pname:rasterizationSamples fragment shader invocations, as when using
<<primsrast-sampleshading, sample shading>> without a shading rate image.

Finally, if the shading rate specifies multiple fragment shader invocations
per fragment, the total number of invocations in the shading rate is clamped
to be no larger than pname:rasterizationSamples.

When the final shading rate for a primitive covering pixel (_x_,_y_) has a
fragment area of latexmath:[fw \times fh], the fragment for that pixel will
cover all pixels with coordinates (_x_',_y_') that satisfy the equations:

[latexmath]
+++++++++++++++++++
\begin{aligned}
\left\lfloor \frac{x}{fw} \right\rfloor = \left\lfloor \frac{x'}{fw} \right\rfloor
\end{aligned}
+++++++++++++++++++
[latexmath]
+++++++++++++++++++
\begin{aligned}
\left\lfloor \frac{y}{fh} \right\rfloor = \left\lfloor \frac{y'}{fh} \right\rfloor
\end{aligned}
+++++++++++++++++++

This combined fragment is considered to have multiple coverage samples; the
total number of samples in this fragment is given by latexmath:[samples = fw
\times fh \times rs] where _rs_ indicates the value of
sname:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples
specified at pipeline creation time.
The set of coverage samples in the fragment is the union of the per-pixel
coverage samples in each of the fragment's pixels The location and order of
coverage samples within each pixel in the combined fragment are assigned as
described in
ifndef::VK_EXT_sample_locations[]
<<primsrast-multisampling, Multisampling>>.
endif::VK_EXT_sample_locations[]
ifdef::VK_EXT_sample_locations[]
<<primsrast-multisampling, Multisampling>> and <<primsrast-samplelocations,
Custom Sample Locations>>.
endif::VK_EXT_sample_locations[]
Each coverage sample in the set of pixels belonging to the combined fragment
is assigned a unique <<primsrast-multisampling-coverage-mask, coverage
index>> in the range [0,_samples_-1].
If the <<features-shadingRateCoarseSampleOrder,
pname:shadingRateCoarseSampleOrder>> feature is supported, the order of
coverage samples can: be specified for each combination of fragment area and
coverage sample count.
If this feature is not supported, the sample order is
implementation-dependent.

[open,refpage='VkPipelineViewportCoarseSampleOrderStateCreateInfoNV',desc='Structure specifying parameters controlling sample order in coarse fragments',type='structs']
--
If the pname:pNext chain of slink:VkPipelineViewportStateCreateInfo includes
a sname:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV structure, then
that structure includes parameters controlling the order of coverage samples
in fragments larger than one pixel.

The sname:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV structure is
defined as:

include::{generated}/api/structs/VkPipelineViewportCoarseSampleOrderStateCreateInfoNV.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:sampleOrderType specifies the mechanism used to order coverage
    samples in fragments larger than one pixel.
  * pname:customSampleOrderCount specifies the number of custom sample
    orderings to use when ordering coverage samples.
  * pname:pCustomSampleOrders is a pointer to an array of
    pname:customSampleOrderCount slink:VkCoarseSampleOrderCustomNV
    structures, each structure specifying the coverage sample order for a
    single combination of fragment area and coverage sample count.

If this structure is not present, pname:sampleOrderType is considered to be
ename:VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV.

If pname:sampleOrderType is ename:VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV, the
coverage sample order used for any combination of fragment area and coverage
sample count not enumerated in pname:pCustomSampleOrders will be identical
to that used for ename:VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV.

If the pipeline was created with
ename:VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV, the contents of this
structure (if present) are ignored, and the coverage sample order is instead
specified by flink:vkCmdSetCoarseSampleOrderNV.

.Valid Usage
****
  * [[VUID-VkPipelineViewportCoarseSampleOrderStateCreateInfoNV-sampleOrderType-02072]]
    If pname:sampleOrderType is not
    ename:VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV,
    pname:customSamplerOrderCount must: be `0`
  * [[VUID-VkPipelineViewportCoarseSampleOrderStateCreateInfoNV-pCustomSampleOrders-02234]]
    The array pname:pCustomSampleOrders must: not contain two structures
    with matching values for both the pname:shadingRate and
    pname:sampleCount members
****
include::{generated}/validity/structs/VkPipelineViewportCoarseSampleOrderStateCreateInfoNV.adoc[]
--

[open,refpage='VkCoarseSampleOrderTypeNV',desc='Shading rate image sample ordering types',type='enums']
--
The type elink:VkCoarseSampleOrderTypeNV specifies the technique used to
order coverage samples in fragments larger than one pixel, and is defined
as:

include::{generated}/api/enums/VkCoarseSampleOrderTypeNV.adoc[]

  * ename:VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV specifies that coverage
    samples will be ordered in an implementation-dependent manner.
  * ename:VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV specifies that coverage
    samples will be ordered according to the array of custom orderings
    provided in either the pname:pCustomSampleOrders member of
    sname:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV or the
    pname:pCustomSampleOrders member of flink:vkCmdSetCoarseSampleOrderNV.
  * ename:VK_COARSE_SAMPLE_ORDER_TYPE_PIXEL_MAJOR_NV specifies that coverage
    samples will be ordered sequentially, sorted first by pixel coordinate
    (in row-major order) and then by
    <<primsrast-multisampling-coverage-mask, sample index>>.
  * ename:VK_COARSE_SAMPLE_ORDER_TYPE_SAMPLE_MAJOR_NV specifies that
    coverage samples will be ordered sequentially, sorted first by
    <<primsrast-multisampling-coverage-mask, sample index>> and then by
    pixel coordinate (in row-major order).
--

When using a coarse sample order of
ename:VK_COARSE_SAMPLE_ORDER_TYPE_PIXEL_MAJOR_NV for a fragment with an
upper-left corner of latexmath:[(fx,fy)] with a width of latexmath:[fw
\times fh] and latexmath:[fsc] samples per pixel,
<<primsrast-multisampling-coverage-mask, coverage index>> latexmath:[cs] of
the fragment will be assigned to <<primsrast-multisampling-coverage-mask,
sample index>> latexmath:[fs] of pixel latexmath:[(px,py)] as follows:

[latexmath]
+++++++++++++++++++
\begin{aligned}
px = & fx + (\left\lfloor {cs \over fsc} \right\rfloor \text{ \% } fw) \\
py = & fy + \left\lfloor {cs \over {fsc \times fw}} \right\rfloor \\
fs = & cs \text{ \% } fsc
\end{aligned}
+++++++++++++++++++

When using a coarse sample order of
ename:VK_COARSE_SAMPLE_ORDER_TYPE_SAMPLE_MAJOR_NV,
<<primsrast-multisampling-coverage-mask, coverage index>> latexmath:[cs]
will be assigned as follows:

[latexmath]
+++++++++++++++++++
\begin{aligned}
px = & fx + cs \text{ \% } fw \\
py = & (fy + \left\lfloor {cs \over fw} \right\rfloor \text{ \% } fh) \\
fs = & \left\lfloor {cs \over {fw \times fh}} \right\rfloor
\end{aligned}
+++++++++++++++++++

[open,refpage='VkCoarseSampleOrderCustomNV',desc='Structure specifying parameters controlling shading rate image usage',type='structs']
--
The sname:VkCoarseSampleOrderCustomNV structure is defined as:

include::{generated}/api/structs/VkCoarseSampleOrderCustomNV.adoc[]

  * pname:shadingRate is a shading rate palette entry that identifies the
    fragment width and height for the combination of fragment area and
    per-pixel coverage sample count to control.
  * pname:sampleCount identifies the per-pixel coverage sample count for the
    combination of fragment area and coverage sample count to control.
  * pname:sampleLocationCount specifies the number of sample locations in
    the custom ordering.
  * pname:pSampleLocations is a pointer to an array of
    slink:VkCoarseSampleLocationNV structures specifying the location of
    each sample in the custom ordering.

The sname:VkCoarseSampleOrderCustomNV structure is used with a coverage
sample ordering type of ename:VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV to
specify the order of coverage samples for one combination of fragment width,
fragment height, and coverage sample count.

When using a custom sample ordering, element _j_ in pname:pSampleLocations
specifies a specific pixel location and
<<primsrast-multisampling-coverage-mask, sample index>> that corresponds to
<<primsrast-multisampling-coverage-mask, coverage index>> _j_ in the
multi-pixel fragment.

.Valid Usage
****
  * [[VUID-VkCoarseSampleOrderCustomNV-shadingRate-02073]]
    pname:shadingRate must: be a shading rate that generates fragments with
    more than one pixel
  * [[VUID-VkCoarseSampleOrderCustomNV-sampleCount-02074]]
    pname:sampleCount must: correspond to a sample count enumerated in
    tlink:VkSampleCountFlags whose corresponding bit is set in
    slink:VkPhysicalDeviceLimits::pname:framebufferNoAttachmentsSampleCounts
  * [[VUID-VkCoarseSampleOrderCustomNV-sampleLocationCount-02075]]
    pname:sampleLocationCount must: be equal to the product of
    pname:sampleCount, the fragment width for pname:shadingRate, and the
    fragment height for pname:shadingRate
  * [[VUID-VkCoarseSampleOrderCustomNV-sampleLocationCount-02076]]
    pname:sampleLocationCount must: be less than or equal to the value of
    sname:VkPhysicalDeviceShadingRateImagePropertiesNV::pname:shadingRateMaxCoarseSamples
  * [[VUID-VkCoarseSampleOrderCustomNV-pSampleLocations-02077]]
    The array pname:pSampleLocations must: contain exactly one entry for
    every combination of valid values for pname:pixelX, pname:pixelY, and
    pname:sample in the structure slink:VkCoarseSampleOrderCustomNV
****
include::{generated}/validity/structs/VkCoarseSampleOrderCustomNV.adoc[]
--

[open,refpage='VkCoarseSampleLocationNV',desc='Structure specifying parameters controlling shading rate image usage',type='structs']
--
The sname:VkCoarseSampleLocationNV structure identifies a specific pixel and
<<primsrast-multisampling-coverage-mask, sample index>> for one of the
coverage samples in a fragment that is larger than one pixel.
This structure is defined as:

include::{generated}/api/structs/VkCoarseSampleLocationNV.adoc[]

  * pname:pixelX is added to the x coordinate of the upper-leftmost pixel of
    each fragment to identify the pixel containing the coverage sample.
  * pname:pixelY is added to the y coordinate of the upper-leftmost pixel of
    each fragment to identify the pixel containing the coverage sample.
  * pname:sample is the number of the coverage sample in the pixel
    identified by pname:pixelX and pname:pixelY.

.Valid Usage
****
  * [[VUID-VkCoarseSampleLocationNV-pixelX-02078]]
    pname:pixelX must: be less than the width (in pixels) of the fragment
  * [[VUID-VkCoarseSampleLocationNV-pixelY-02079]]
    pname:pixelY must: be less than the height (in pixels) of the fragment
  * [[VUID-VkCoarseSampleLocationNV-sample-02080]]
    pname:sample must: be less than the number of coverage samples in each
    pixel belonging to the fragment
****

include::{generated}/validity/structs/VkCoarseSampleLocationNV.adoc[]
--

[open,refpage='vkCmdSetCoarseSampleOrderNV',desc='Set order of coverage samples for coarse fragments dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the order of coverage
samples in fragments larger than one pixel, call:

include::{generated}/api/protos/vkCmdSetCoarseSampleOrderNV.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:sampleOrderType specifies the mechanism used to order coverage
    samples in fragments larger than one pixel.
  * pname:customSampleOrderCount specifies the number of custom sample
    orderings to use when ordering coverage samples.
  * pname:pCustomSampleOrders is a pointer to an array of
    slink:VkCoarseSampleOrderCustomNV structures, each structure specifying
    the coverage sample order for a single combination of fragment area and
    coverage sample count.

If pname:sampleOrderType is ename:VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV, the
coverage sample order used for any combination of fragment area and coverage
sample count not enumerated in pname:pCustomSampleOrders will be identical
to that used for ename:VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV.

This command sets the order of coverage samples for subsequent drawing
commands
ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
Otherwise, this state is specified by the
slink:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV values used to
create the currently active pipeline.

.Valid Usage
****
  * [[VUID-vkCmdSetCoarseSampleOrderNV-sampleOrderType-02081]]
    If pname:sampleOrderType is not
    ename:VK_COARSE_SAMPLE_ORDER_TYPE_CUSTOM_NV,
    pname:customSamplerOrderCount must: be `0`
  * [[VUID-vkCmdSetCoarseSampleOrderNV-pCustomSampleOrders-02235]]
    The array pname:pCustomSampleOrders must: not contain two structures
    with matching values for both the pname:shadingRate and
    pname:sampleCount members
****

include::{generated}/validity/protos/vkCmdSetCoarseSampleOrderNV.adoc[]
--

If the final shading rate for a primitive covering pixel (_x_,_y_) results
in _n_ invocations per pixel (_n_ > 1), _n_ separate fragment shader
invocations will be generated for the fragment.
Each coverage sample in the fragment will be assigned to one of the _n_
fragment shader invocations in an implementation-dependent manner.
The outputs from the <<interfaces-fragmentoutput, fragment output
interface>> of each shader invocation will be broadcast to all of the
framebuffer samples associated with the invocation.
If none of the coverage samples associated with a fragment shader invocation
is covered by a primitive, the implementation may: discard the fragment
shader invocation for those samples.

If the final shading rate for a primitive covering pixel (_x_,_y_) results
in a fragment containing multiple pixels, a single set of fragment shader
invocations will be generated for all pixels in the combined fragment.
Outputs from the <<interfaces-fragmentoutput, fragment output interface>>
will be broadcast to all covered framebuffer samples belonging to the
fragment.
If the fragment shader executes code discarding the fragment, none of the
samples of the fragment will be updated.

endif::VK_NV_shading_rate_image[]


[[primsrast-sampleshading]]
== Sample Shading

Sample shading can: be used to specify a minimum number of unique samples to
process for each fragment.
If sample shading is enabled, an implementation must: invoke the fragment
shader at least [eq]#max({lceil}
slink:VkPipelineMultisampleStateCreateInfo::pname:minSampleShading {times}
slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples
{rceil}, 1)# times per fragment.
If slink:VkPipelineMultisampleStateCreateInfo::pname:sampleShadingEnable is
set to ename:VK_TRUE, sample shading is enabled.

If a fragment shader entry point <<shaders-staticuse, statically uses>> an
input variable decorated with a code:BuiltIn of code:SampleId or
code:SamplePosition, sample shading is enabled and a value of `1.0` is used
instead of pname:minSampleShading.
If a fragment shader entry point <<shaders-staticuse, statically uses>> an
input variable decorated with code:Sample, sample shading may: be enabled
and a value of `1.0` will be used instead of pname:minSampleShading if it
is.
ifdef::VK_AMD_mixed_attachment_samples[]
If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled and the
subpass uses color attachments, the pname:samples value used to create each
color attachment is used instead of pname:rasterizationSamples.
endif::VK_AMD_mixed_attachment_samples[]

[NOTE]
.Note
====
If a shader decorates an input variable with code:Sample and that value
meaningfully impacts the output of a shader, sample shading will be enabled
to ensure that the input is in fact interpolated per-sample.
This is inherent to the specification and not spelled out here - if an
application simply declares such a variable it is implementation-defined
whether sample shading is enabled or not.
It is possible to see the effects of this by using atomics in the shader or
using a pipeline statistics query to query the number of fragment
invocations, even if the shader itself does not use any per-sample
variables.
====

If there are fewer fragment invocations than <<fragops,covered samples>>,
implementations may: include those samples in fragment shader invocations in
any manner as long as covered samples are all shaded at least once, and each
invocation that is not a <<shaders-helper-invocations, helper invocation>>
covers at least one sample.

ifdef::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[]
[[primsrast-barycentric]]
== Barycentric Interpolation

When the pname:fragmentShaderBarycentric feature is enabled, the
code:PerVertexKHR <<shaders-interpolation-decorations, interpolation
decoration>> can: be used with fragment shader inputs to indicate that the
decorated inputs do not have associated data in the fragment.
Such inputs can: only be accessed in a fragment shader using an array index
whose value (0, 1, or 2) identifies one of the vertices of the primitive
that produced the fragment.
Reads of per-vertex values for missing vertices, such as the third vertex of
a line primitive, will return values from the valid vertex with the highest
index.
This means that the per-vertex values of indices 1 and 2 for point
primitives will be equal to those of index 0, and the per-vertex values of
index 2 for line primitives will be equal to those of index 1.

ifndef::VK_NV_mesh_shader,VK_EXT_mesh_shader[]
When <<tessellation, tessellation>> and <<geometry, geometry shading>>
endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[]
ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[]
When <<tessellation, tessellation>>, <<geometry, geometry shading>>, and
<<mesh,mesh shading>>
endif::VK_NV_mesh_shader,VK_EXT_mesh_shader[]
are not active, fragment shader inputs decorated with code:PerVertexKHR will
take values from one of the vertices of the primitive that produced the
fragment, identified by the extra index provided in SPIR-V code accessing
the input.
If the _n_ vertices passed to a draw call are numbered 0 through _n_-1, and
the point, line, and triangle primitives produced by the draw call are
numbered with consecutive integers beginning with zero, the following table
indicates the original vertex numbers used
ifdef::VK_EXT_provoking_vertex[]
when the <<vertexpostproc-flatshading,provoking vertex mode>> is
ename:VK_PROVOKING_VERTEX_MODE_FIRST_VERTEX_EXT
endif::VK_EXT_provoking_vertex[]
for index values of 0, 1, and 2.
If an input decorated with code:PerVertexKHR is accessed with any other
vertex index value, or is accessed while rasterizing a polygon when the
slink:VkPipelineRasterizationStateCreateInfo::pname:polygonMode property of
the currently active pipeline is not ename:VK_POLYGON_MODE_FILL, an
undefined: value is returned.

[[primsrast-barycentric-order-table]]
[options="header"]
|====
| Primitive Topology                                               | Vertex 0    | Vertex 1    | Vertex 2
| ename:VK_PRIMITIVE_TOPOLOGY_POINT_LIST                           | i           | i           | i
| ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST                            | 2i          | 2i+1        | 2i+1
| ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP                           | i           | i+1         | i+1
| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST                        | 3i          | 3i+1        | 3i+2
| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP (even)                | i           | i+1         | i+2
| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP (odd)                 | i           | i+2         | i+1
| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN                         | i+1         | i+2         | 0
| ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY             | 4i+1        | 4i+2        | 4i+2
| ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY            | i+1         | i+2         | i+2
| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY         | 6i          | 6i+2        | 6i+4
| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY (even) | 2i          | 2i+2        | 2i+4
| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY (odd)  | 2i          | 2i+4        | 2i+2
|====

ifdef::VK_EXT_provoking_vertex[]
When the provoking vertex mode is
ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, the original vertex numbers
used are the same as above except as indicated in the table below.

[[primsrast-barycentric-order-table-last-vertex]]
[options="header"]
|====
| Primitive Topology                                               | Vertex 0    | Vertex 1    | Vertex 2
ifdef::VK_KHR_fragment_shader_barycentric[]
| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP (odd, and
pname:triStripVertexOrderIndependentOfProvokingVertex of
slink:VkPhysicalDeviceFragmentShaderBarycentricPropertiesKHR is ename:VK_FALSE)    | i+1         | i           | i+2
endif::VK_KHR_fragment_shader_barycentric[]
ifndef::VK_KHR_fragment_shader_barycentric[]
| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP (odd)                 | i+1         | i           | i+2
endif::VK_KHR_fragment_shader_barycentric[]
| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN                         | 0           | i+1         | i+2
| ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY (odd)  | 2i+2        | 2i          | 2i+4
|====
endif::VK_EXT_provoking_vertex[]

When geometry
ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[or mesh]
shading is active, primitives processed by fragment shaders are assembled
from the vertices emitted by the geometry
ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[or mesh]
shader.
In this case, the vertices used for fragment shader inputs decorated with
code:PerVertexKHR are derived by treating the primitives produced by the
shader as though they were specified by a draw call and consulting
<<primsrast-barycentric-order-table, the table above>>.

When using tessellation without geometry shading, the tessellator produces
primitives in an implementation-dependent manner.
While there is no defined vertex ordering for inputs decorated with
code:PerVertexKHR, the vertex ordering used in this case will be consistent
with the ordering used to derive the values of inputs decorated with
code:BaryCoordKHR or code:BaryCoordNoPerspKHR.

Fragment shader inputs decorated with code:BaryCoordKHR or
code:BaryCoordNoPerspKHR hold three-component vectors with barycentric
weights that indicate the location of the fragment relative to the
screen-space locations of vertices of its primitive.
For point primitives, such variables are always assigned the value
[eq]#(1,0,0)#.
For <<primsrast-lines-basic, line>> primitives, the built-ins are obtained
by interpolating an attribute whose values for the vertices numbered 0 and 1
are [eq]#(1,0,0)# and [eq]#(0,1,0)#, respectively.
For <<primsrast-polygons-basic, polygon>> primitives, the built-ins are
obtained by interpolating an attribute whose values for the vertices
numbered 0, 1, and 2 are [eq]#(1,0,0)#, [eq]#(0,1,0)#, and [eq]#(0,0,1)#,
respectively.
For code:BaryCoordKHR, the values are obtained using perspective
interpolation.
For code:BaryCoordNoPerspKHR, the values are obtained using linear
interpolation.
The values of code:BaryCoordKHR and code:BaryCoordNoPerspKHR are undefined:
while rasterizing a polygon when the
slink:VkPipelineRasterizationStateCreateInfo::pname:polygonMode property of
the currently active pipeline is not ename:VK_POLYGON_MODE_FILL.

endif::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[]


[[primsrast-points]]
== Points

A point is drawn by generating a set of fragments in the shape of a square
centered around the vertex of the point.
Each vertex has an associated point size controlling the width/height of
that square.
The point size is taken from the (potentially clipped) shader built-in
code:PointSize written by:

  * the geometry shader, if active;
  * the tessellation evaluation shader, if active and no geometry shader is
    active;
  * the vertex shader, otherwise

and clamped to the implementation-dependent point size range
[eq]#[pname:pointSizeRange[0],pname:pointSizeRange[1]]#.
The value written to code:PointSize must: be greater than zero.
ifdef::VK_KHR_maintenance5[]
If <<features-maintenance5, pname:maintenance5>> is enabled, and a value is
not written to code:PointSize, the point size takes a default value of 1.0.
endif::VK_KHR_maintenance5[]

Not all point sizes need be supported, but the size 1.0 must: be supported.
The range of supported sizes and the size of evenly-spaced gradations within
that range are implementation-dependent.
The range and gradations are obtained from the pname:pointSizeRange and
pname:pointSizeGranularity members of slink:VkPhysicalDeviceLimits.
If, for instance, the size range is from 0.1 to 2.0 and the gradation size
is 0.1, then the sizes 0.1, 0.2, ..., 1.9, 2.0 are supported.
Additional point sizes may: also be supported.
There is no requirement that these sizes be equally spaced.
If an unsupported size is requested, the nearest supported size is used
instead.

ifdef::VK_EXT_fragment_density_map[]
Further, if the render pass has a fragment density map attachment, point
size may: be rounded by the implementation to a multiple of the fragment's
width or height.
endif::VK_EXT_fragment_density_map[]


[[primsrast-points-basic]]
=== Basic Point Rasterization

Point rasterization produces a fragment for each fragment area group of
framebuffer pixels with one or more sample points that intersect a region
centered at the point's [eq]#(x~f~,y~f~)#.
This region is a square with side equal to the current point size.
Coverage bits that correspond to sample points that intersect the region are
1, other coverage bits are 0.
All fragments produced in rasterizing a point are assigned the same
associated data, which are those of the vertex corresponding to the point.
However, the fragment shader built-in code:PointCoord contains point sprite
texture coordinates.
The [eq]#s# and [eq]#t# point sprite texture coordinates vary from zero to
one across the point horizontally left-to-right and vertically
top-to-bottom, respectively.
The following formulas are used to evaluate [eq]#s# and [eq]#t#:

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
s = {1 \over 2} + { \left( x_p - x_f \right) \over \text{size} }
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
t = {1 \over 2} + { \left( y_p - y_f \right) \over \text{size} }
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

where size is the point's size; [eq]#(x~p~,y~p~)# is the location at which
the point sprite coordinates are evaluated - this may: be the framebuffer
coordinates of the fragment center, or the location of a sample; and
[eq]#(x~f~,y~f~)# is the exact, unrounded framebuffer coordinate of the
vertex for the point.


[[primsrast-lines]]
== Line Segments

ifdef::VK_EXT_line_rasterization[]
[open,refpage='VkPipelineRasterizationLineStateCreateInfoEXT',desc='Structure specifying parameters of a newly created pipeline line rasterization state',type='structs']
--
Line segment rasterization options are controlled by the
slink:VkPipelineRasterizationLineStateCreateInfoEXT structure.

The sname:VkPipelineRasterizationLineStateCreateInfoEXT structure is defined
as:

include::{generated}/api/structs/VkPipelineRasterizationLineStateCreateInfoEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:lineRasterizationMode is a elink:VkLineRasterizationModeEXT value
    selecting the style of line rasterization.
  * pname:stippledLineEnable enables <<primsrast-lines-stipple, stippled
    line rasterization>>.
  * pname:lineStippleFactor is the repeat factor used in stippled line
    rasterization.
  * pname:lineStipplePattern is the bit pattern used in stippled line
    rasterization.

If pname:stippledLineEnable is ename:VK_FALSE, the values of
pname:lineStippleFactor and pname:lineStipplePattern are ignored.

.Valid Usage
****
  * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-lineRasterizationMode-02768]]
    If pname:lineRasterizationMode is
    ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT, then the
    <<features-rectangularLines, pname:rectangularLines>> feature must: be
    enabled
  * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-lineRasterizationMode-02769]]
    If pname:lineRasterizationMode is
    ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT, then the
    <<features-bresenhamLines, pname:bresenhamLines>> feature must: be
    enabled
  * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-lineRasterizationMode-02770]]
    If pname:lineRasterizationMode is
    ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, then the
    <<features-smoothLines, pname:smoothLines>> feature must: be enabled
  * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-stippledLineEnable-02771]]
    If pname:stippledLineEnable is ename:VK_TRUE and
    pname:lineRasterizationMode is
    ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT, then the
    <<features-stippledRectangularLines, pname:stippledRectangularLines>>
    feature must: be enabled
  * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-stippledLineEnable-02772]]
    If pname:stippledLineEnable is ename:VK_TRUE and
    pname:lineRasterizationMode is
    ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT, then the
    <<features-stippledBresenhamLines, pname:stippledBresenhamLines>>
    feature must: be enabled
  * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-stippledLineEnable-02773]]
    If pname:stippledLineEnable is ename:VK_TRUE and
    pname:lineRasterizationMode is
    ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, then the
    <<features-stippledSmoothLines, pname:stippledSmoothLines>> feature
    must: be enabled
  * [[VUID-VkPipelineRasterizationLineStateCreateInfoEXT-stippledLineEnable-02774]]
    If pname:stippledLineEnable is ename:VK_TRUE and
    pname:lineRasterizationMode is
    ename:VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT, then the
    <<features-stippledRectangularLines, pname:stippledRectangularLines>>
    feature must: be enabled and
    slink:VkPhysicalDeviceLimits::pname:strictLines must: be ename:VK_TRUE
****

include::{generated}/validity/structs/VkPipelineRasterizationLineStateCreateInfoEXT.adoc[]
--

[open,refpage='VkLineRasterizationModeEXT',desc='Line rasterization modes',type='enums']
--
Possible values of
slink:VkPipelineRasterizationLineStateCreateInfoEXT::pname:lineRasterizationMode
are:

include::{generated}/api/enums/VkLineRasterizationModeEXT.adoc[]

  * ename:VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT is equivalent to
    ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT if
    slink:VkPhysicalDeviceLimits::pname:strictLines is ename:VK_TRUE,
    otherwise lines are drawn as non-pname:strictLines parallelograms.
    Both of these modes are defined in <<primsrast-lines-basic,Basic Line
    Segment Rasterization>>.
  * ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT specifies lines drawn
    as if they were rectangles extruded from the line
  * ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT specifies lines drawn by
    determining which pixel diamonds the line intersects and exits, as
    defined in <<primsrast-lines-bresenham,Bresenham Line Segment
    Rasterization>>.
  * ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT specifies lines
    drawn if they were rectangles extruded from the line, with alpha
    falloff, as defined in <<primsrast-lines-smooth,Smooth Lines>>.
--

ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]

[open,refpage='vkCmdSetLineRasterizationModeEXT',desc='Specify the line rasterization mode dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the
pname:lineRasterizationMode state, call:

include::{generated}/api/protos/vkCmdSetLineRasterizationModeEXT.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:lineRasterizationMode specifies the pname:lineRasterizationMode
    state.

This command sets the pname:lineRasterizationMode state for subsequent
drawing commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_EXT_extended_dynamic_state3[]
Otherwise, this state is specified by the
slink:VkPipelineRasterizationLineStateCreateInfoEXT::pname:lineRasterizationMode
value used to create the currently active pipeline.

.Valid Usage
****
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetLineRasterizationModeEXT-None-08558]]
    Either the <<features-extendedDynamicState3LineRasterizationMode,
    pname:extendedDynamicState3LineRasterizationMode>> feature or the
    <<features-shaderObject, pname:shaderObject>> feature or both must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
ifndef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetLineRasterizationModeEXT-None-08559]]
    The <<features-shaderObject, pname:shaderObject>> feature must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
endif::VK_EXT_shader_object[]
ifndef::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetLineRasterizationModeEXT-extendedDynamicState3LineRasterizationMode-07417]]
    The <<features-extendedDynamicState3LineRasterizationMode,
    pname:extendedDynamicState3LineRasterizationMode>> feature must: be
    enabled
endif::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetLineRasterizationModeEXT-lineRasterizationMode-07418]]
    If pname:lineRasterizationMode is
    ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT, then the
    <<features-rectangularLines, pname:rectangularLines>> feature must: be
    enabled
  * [[VUID-vkCmdSetLineRasterizationModeEXT-lineRasterizationMode-07419]]
    If pname:lineRasterizationMode is
    ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT, then the
    <<features-bresenhamLines, pname:bresenhamLines>> feature must: be
    enabled
  * [[VUID-vkCmdSetLineRasterizationModeEXT-lineRasterizationMode-07420]]
    If pname:lineRasterizationMode is
    ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, then the
    <<features-smoothLines, pname:smoothLines>> feature must: be enabled
****

include::{generated}/validity/protos/vkCmdSetLineRasterizationModeEXT.adoc[]
--

[open,refpage='vkCmdSetLineStippleEnableEXT',desc='Specify the line stipple enable dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the pname:stippledLineEnable
state, call:

include::{generated}/api/protos/vkCmdSetLineStippleEnableEXT.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:stippledLineEnable specifies the pname:stippledLineEnable state.

This command sets the pname:stippledLineEnable state for subsequent drawing
commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_EXT_extended_dynamic_state3[]
Otherwise, this state is specified by the
slink:VkPipelineRasterizationLineStateCreateInfoEXT::pname:stippledLineEnable
value used to create the currently active pipeline.

.Valid Usage
****
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetLineStippleEnableEXT-None-08560]]
    Either the <<features-extendedDynamicState3LineStippleEnable,
    pname:extendedDynamicState3LineStippleEnable>> feature or the
    <<features-shaderObject, pname:shaderObject>> feature or both must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
ifndef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetLineStippleEnableEXT-None-08561]]
    The <<features-shaderObject, pname:shaderObject>> feature must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
endif::VK_EXT_shader_object[]
ifndef::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetLineStippleEnableEXT-extendedDynamicState3LineStippleEnable-07421]]
    The <<features-extendedDynamicState3LineStippleEnable,
    pname:extendedDynamicState3LineStippleEnable>> feature must: be enabled
endif::VK_EXT_shader_object[]
****

include::{generated}/validity/protos/vkCmdSetLineStippleEnableEXT.adoc[]
--

endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]

endif::VK_EXT_line_rasterization[]

[open,refpage='vkCmdSetLineWidth',desc='Set line width dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the line width, call:

include::{generated}/api/protos/vkCmdSetLineWidth.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:lineWidth is the width of rasterized line segments.

This command sets the line width for subsequent drawing commands
ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or]
when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_LINE_WIDTH
set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
Otherwise, this state is specified by the
slink:VkPipelineRasterizationStateCreateInfo::pname:lineWidth value used to
create the currently active pipeline.

.Valid Usage
****
  * [[VUID-vkCmdSetLineWidth-lineWidth-00788]]
    If the <<features-wideLines, pname:wideLines>> feature is not enabled,
    pname:lineWidth must: be `1.0`
****

include::{generated}/validity/protos/vkCmdSetLineWidth.adoc[]
--

Not all line widths need be supported for line segment rasterization, but
width 1.0 antialiased segments must: be provided.
The range and gradations are obtained from the pname:lineWidthRange and
pname:lineWidthGranularity members of slink:VkPhysicalDeviceLimits.
If, for instance, the size range is from 0.1 to 2.0 and the gradation size
is 0.1, then the sizes 0.1, 0.2, ..., 1.9, 2.0 are supported.
Additional line widths may: also be supported.
There is no requirement that these widths be equally spaced.
If an unsupported width is requested, the nearest supported width is used
instead.

ifdef::VK_EXT_fragment_density_map[]
Further, if the render pass has a fragment density map attachment, line
width may: be rounded by the implementation to a multiple of the fragment's
width or height.
endif::VK_EXT_fragment_density_map[]


[[primsrast-lines-basic]]
=== Basic Line Segment Rasterization

ifdef::VK_EXT_line_rasterization[]
If the pname:lineRasterizationMode member of
slink:VkPipelineRasterizationLineStateCreateInfoEXT is
ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT, rasterized
endif::VK_EXT_line_rasterization[]
ifndef::VK_EXT_line_rasterization[]
Rasterized
endif::VK_EXT_line_rasterization[]
line segments produce fragments which intersect a rectangle centered on the
line segment.
Two of the edges are parallel to the specified line segment; each is at a
distance of one-half the current width from that segment in directions
perpendicular to the direction of the line.
The other two edges pass through the line endpoints and are perpendicular to
the direction of the specified line segment.
Coverage bits that correspond to sample points that intersect the rectangle
are 1, other coverage bits are 0.

Next we specify how the data associated with each rasterized fragment are
obtained.
Let [eq]#**p**~r~ = (x~d~, y~d~)# be the framebuffer coordinates at which
associated data are evaluated.
This may: be the center of a fragment or the location of a sample within the
fragment.
When pname:rasterizationSamples is ename:VK_SAMPLE_COUNT_1_BIT, the fragment
center must: be used.
Let [eq]#**p**~a~ = (x~a~, y~a~)# and [eq]#**p**~b~ = (x~b~,y~b~)# be
initial and final endpoints of the line segment, respectively.
Set

// Equation {linet:eq}
[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
t = {{( \mathbf{p}_r - \mathbf{p}_a ) \cdot ( \mathbf{p}_b - \mathbf{p}_a )}
    \over {\| \mathbf{p}_b - \mathbf{p}_a \|^2 }}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

(Note that [eq]#t = 0# at [eq]#**p**~a~# and [eq]#t = 1# at [eq]#**p**~b~#.
Also note that this calculation projects the vector from [eq]#**p**~a~# to
[eq]#**p**~r~# onto the line, and thus computes the normalized distance of
the fragment along the line.)

If <<limits-strictLines, pname:strictLines>> is ename:VK_TRUE, line segments
are rasterized using perspective or linear interpolation.

[[line_perspective_interpolation]]
_Perspective interpolation_ for a line segment interpolates two values in a
manner that is correct when taking the perspective of the viewport into
consideration, by way of the line segment's clip coordinates.
An interpolated value [eq]#f# can be determined by

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
f = {{ (1-t) {f_a / w_a} + t { f_b / w_b} } \over
    {(1-t) / w_a + t / w_b }}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

where [eq]#f~a~# and [eq]#f~b~# are the data associated with the starting
and ending endpoints of the segment, respectively; [eq]#w~a~# and [eq]#w~b~#
are the clip [eq]#w# coordinates of the starting and ending endpoints of the
segment, respectively.

[[line_linear_interpolation]]
_Linear interpolation_ for a line segment directly interpolates two values,
and an interpolated value [eq]#f# can be determined by

  {empty}:: [eq]#f = (1 - t) f~a~ {plus} t f~b~#

where [eq]#f~a~# and [eq]#f~b~# are the data associated with the starting
and ending endpoints of the segment, respectively.

The clip coordinate [eq]#w# for a sample is determined using perspective
interpolation.
The depth value [eq]#z# for a sample is determined using linear
interpolation.
Interpolation of fragment shader input values are determined by
<<shaders-interpolation-decorations,Interpolation decorations>>.

The above description documents the preferred method of line rasterization,
and must: be used when
ifdef::VK_EXT_line_rasterization[]
pname:lineRasterizationMode is
ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT.
endif::VK_EXT_line_rasterization[]
ifndef::VK_EXT_line_rasterization[]
the implementation advertises the pname:strictLines limit in
slink:VkPhysicalDeviceLimits as ename:VK_TRUE.
endif::VK_EXT_line_rasterization[]

ifndef::VK_KHR_maintenance5[]
When
endif::VK_KHR_maintenance5[]
ifdef::VK_KHR_maintenance5[]
By default, when
endif::VK_KHR_maintenance5[]
pname:strictLines is ename:VK_FALSE,
ifdef::VK_EXT_line_rasterization[]
and when the pname:lineRasterizationMode is
ename:VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT,
endif::VK_EXT_line_rasterization[]
the edges of the lines are generated as a parallelogram surrounding the
original line.
The major axis is chosen by noting the axis in which there is the greatest
distance between the line start and end points.
If the difference is equal in both directions then the X axis is chosen as
the major axis.
Edges 2 and 3 are aligned to the minor axis and are centered on the
endpoints of the line as in <<fig-non-strict-lines>>, and each is
pname:lineWidth long.
Edges 0 and 1 are parallel to the line and connect the endpoints of edges 2
and 3.
Coverage bits that correspond to sample points that intersect the
parallelogram are 1, other coverage bits are 0.

Samples that fall exactly on the edge of the parallelogram follow the
polygon rasterization rules.

Interpolation occurs as if the parallelogram was decomposed into two
triangles where each pair of vertices at each end of the line has identical
attributes.

[[fig-non-strict-lines]]
image::{images}/non_strict_lines.svg[align="center",title="Non strict lines",opts="{imageopts}"]

Only when pname:strictLines is ename:VK_FALSE implementations may: deviate
from the non-strict line algorithm described above in the following ways:

  * Implementations may: instead interpolate each fragment according to the
    formula in <<primsrast-lines-basic, Basic Line Segment Rasterization>>
    using the original line segment endpoints.

  * Rasterization of non-antialiased non-strict line segments may: be
    performed using the rules defined in
    <<primsrast-lines-bresenham,Bresenham Line Segment Rasterization>>.

ifdef::VK_KHR_maintenance5[]
If
sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:nonStrictSinglePixelWideLinesUseParallelogram
is ename:VK_TRUE,
ifdef::VK_EXT_line_rasterization[]
the pname:lineRasterizationMode is
ename:VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT,
endif::VK_EXT_line_rasterization[]
and pname:strictLines is ename:VK_FALSE, non-strict lines of width 1.0 are
rasterized as parallelograms, otherwise they are rasterized using
Bresenham's algorithm.

If
sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:nonStrictWideLinesUseParallelogram
is ename:VK_TRUE,
ifdef::VK_EXT_line_rasterization[]
the pname:lineRasterizationMode is
ename:VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT,
endif::VK_EXT_line_rasterization[]
and pname:strictLines is ename:VK_FALSE, non-strict lines of width greater
than 1.0 are rasterized as parallelograms, otherwise they are rasterized
using Bresenham's algorithm.
endif::VK_KHR_maintenance5[]

[[primsrast-lines-bresenham]]
=== Bresenham Line Segment Rasterization

ifdef::VK_EXT_line_rasterization[]
If pname:lineRasterizationMode is
ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT, then the following rules
replace the line rasterization rules defined in <<primsrast-lines-basic,
Basic Line Segment Rasterization>>.
endif::VK_EXT_line_rasterization[]

Non-strict lines may: also follow these rasterization rules for
non-antialiased lines.

Line segment rasterization begins by characterizing the segment as either
_x-major_ or _y-major_.
x-major line segments have slope in the closed interval [eq]#[-1,1]#; all
other line segments are y-major (slope is determined by the segment's
endpoints).
We specify rasterization only for x-major segments except in cases where the
modifications for y-major segments are not self-evident.

Ideally, Vulkan uses a _diamond-exit_ rule to determine those fragments that
are produced by rasterizing a line segment.
For each fragment [eq]#f# with center at framebuffer coordinates [eq]#x~f~#
and [eq]#y~f~#, define a diamond-shaped region that is the intersection of
four half planes:

[latexmath]
+++++++++++++++++++
    R_f = \{ (x,y) \mid | x - x_f | + | y - y_f | < \frac{1}{2} \}
+++++++++++++++++++

Essentially, a line segment starting at [eq]#p~a~# and ending at [eq]#p~b~#
produces those fragments [eq]#f# for which the segment intersects
[eq]#R~f~#, except if [eq]#p~b~# is contained in [eq]#R~f~#.

image::{images}/bresenham.svg[title="Visualization of Bresenham's algorithm",align="center",opts="{imageopts}"]

To avoid difficulties when an endpoint lies on a boundary of [eq]#R~f~# we
(in principle) perturb the supplied endpoints by a tiny amount.
Let [eq]#p~a~# and [eq]#p~b~# have framebuffer coordinates [eq]#(x~a~,
y~a~)# and [eq]#(x~b~, y~b~)#, respectively.
Obtain the perturbed endpoints [eq]#p~a~'# given by [eq]#(x~a~, y~a~) -
({epsilon}, {epsilon}^2^)# and [eq]#p~b~'# given by [eq]#(x~b~, y~b~) -
({epsilon}, {epsilon}^2^)#.
Rasterizing the line segment starting at [eq]#p~a~# and ending at [eq]#p~b~#
produces those fragments [eq]#f# for which the segment starting at
[eq]#p~a~'# and ending on [eq]#p~b~'# intersects [eq]#R~f~#, except if
[eq]#p~b~'# is contained in [eq]#R~f~#.
[eq]#{epsilon}# is chosen to be so small that rasterizing the line segment
produces the same fragments when [eq]#{delta}# is substituted for
[eq]#{epsilon}# for any [eq]#0 < {delta} {leq} {epsilon}#.

When [eq]#p~a~# and [eq]#p~b~# lie on fragment centers, this
characterization of fragments reduces to Bresenham's algorithm with one
modification: lines produced in this description are "`half-open`", meaning
that the final fragment (corresponding to [eq]#p~b~#) is not drawn.
This means that when rasterizing a series of connected line segments, shared
endpoints will be produced only once rather than twice (as would occur with
Bresenham's algorithm).

Implementations may: use other line segment rasterization algorithms,
subject to the following rules:

  * The coordinates of a fragment produced by the algorithm must: not
    deviate by more than one unit in either x or y framebuffer coordinates
    from a corresponding fragment produced by the diamond-exit rule.
  * The total number of fragments produced by the algorithm must: not differ
    from that produced by the diamond-exit rule by no more than one.
  * For an x-major line, two fragments that lie in the same
    framebuffer-coordinate column must: not be produced (for a y-major line,
    two fragments that lie in the same framebuffer-coordinate row must: not
    be produced).
  * If two line segments share a common endpoint, and both segments are
    either x-major (both left-to-right or both right-to-left) or y-major
    (both bottom-to-top or both top-to-bottom), then rasterizing both
    segments must: not produce duplicate fragments.
    Fragments also must: not be omitted so as to interrupt continuity of the
    connected segments.

The actual width [eq]#w# of Bresenham lines is determined by rounding the
line width to the nearest integer, clamping it to the
implementation-dependent pname:lineWidthRange (with both values rounded to
the nearest integer), then clamping it to be no less than 1.

Bresenham line segments of width other than one are rasterized by offsetting
them in the minor direction (for an x-major line, the minor direction is y,
and for a y-major line, the minor direction is x) and producing a row or
column of fragments in the minor direction.
If the line segment has endpoints given by [eq]#(x~0~, y~0~)# and
[eq]#(x~1~, y~1~)# in framebuffer coordinates, the segment with endpoints
latexmath:[(x_0, y_0 - \frac{w-1}{2})] and latexmath:[(x_1, y_1 -
\frac{w-1}{2})] is rasterized, but instead of a single fragment, a column of
fragments of height w (a row of fragments of length w for a y-major segment)
is produced at each x (y for y-major) location.
The lowest fragment of this column is the fragment that would be produced by
rasterizing the segment of width 1 with the modified coordinates.

The preferred method of attribute interpolation for a wide line is to
generate the same attribute values for all fragments in the row or column
described above, as if the adjusted line was used for interpolation and
those values replicated to the other fragments, except for code:FragCoord
which is interpolated as usual.
Implementations may: instead interpolate each fragment according to the
formula in <<primsrast-lines-basic,Basic Line Segment Rasterization>>, using
the original line segment endpoints.

When Bresenham lines are being rasterized, sample locations may: all be
treated as being at the pixel center (this may: affect attribute and depth
interpolation).

[NOTE]
.Note
====
The sample locations described above are *not* used for determining
coverage, they are only used for things like attribute interpolation.
The rasterization rules that determine coverage are defined in terms of
whether the line intersects *pixels*, as opposed to the point sampling rules
used for other primitive types.
So these rules are independent of the sample locations.
One consequence of this is that Bresenham lines cover the same pixels
regardless of the number of rasterization samples, and cover all samples in
those pixels (unless masked out or killed).
====


ifdef::VK_EXT_line_rasterization[]
[[primsrast-lines-stipple]]
=== Line Stipple

If the pname:stippledLineEnable member of
slink:VkPipelineRasterizationLineStateCreateInfoEXT is ename:VK_TRUE, then
lines are rasterized with a _line stipple_ determined by
pname:lineStippleFactor and pname:lineStipplePattern.
pname:lineStipplePattern is an unsigned 16-bit integer that determines which
fragments are to be drawn or discarded when the line is rasterized.
pname:lineStippleFactor is a count that is used to modify the effective line
stipple by causing each bit in pname:lineStipplePattern to be used
pname:lineStippleFactor times.

Line stippling discards certain fragments that are produced by
rasterization.
The masking is achieved using three parameters: the 16-bit line stipple
pattern _p_, the line stipple factor _r_, and an integer stipple counter
_s_.
Let

[latexmath]
+++++++++++++++++++
b  = \left\lfloor \frac{s}{r} \right\rfloor \bmod 16
+++++++++++++++++++

Then a fragment is produced if the _b_'th bit of _p_ is 1, and discarded
otherwise.
The bits of _p_ are numbered with 0 being the least significant and 15 being
the most significant.

The initial value of _s_ is zero.
For ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT lines, _s_ is incremented
after production of each fragment of a line segment (fragments are produced
in order, beginning at the starting point and working towards the ending
point).
For ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT and
ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT lines, the
rectangular region is subdivided into adjacent unit-length rectangles, and s
is incremented once for each rectangle.
Rectangles with a value of _s_ such that the _b_'th bit of _p_ is zero are
discarded.
If the last rectangle in a line segment is shorter than unit-length, then
the remainder may: carry over to the next line segment in the line strip
using the same value of _s_ (this is the preferred behavior, for the stipple
pattern to appear more consistent through the strip).

_s_ is reset to 0 at the start of each strip (for line strips), and before
every line segment in a group of independent segments.

If the line segment has been clipped, then the value of _s_ at the beginning
of the line segment is implementation-dependent.

[open,refpage='vkCmdSetLineStippleEXT',desc='Set line stipple dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the line stipple state,
call:

include::{generated}/api/protos/vkCmdSetLineStippleEXT.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:lineStippleFactor is the repeat factor used in stippled line
    rasterization.
  * pname:lineStipplePattern is the bit pattern used in stippled line
    rasterization.

This command sets the line stipple state for subsequent drawing commands
ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_LINE_STIPPLE_EXT set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
Otherwise, this state is specified by the
slink:VkPipelineRasterizationLineStateCreateInfoEXT::pname:lineStippleFactor
and
slink:VkPipelineRasterizationLineStateCreateInfoEXT::pname:lineStipplePattern
values used to create the currently active pipeline.

.Valid Usage
****
  * [[VUID-vkCmdSetLineStippleEXT-lineStippleFactor-02776]]
    pname:lineStippleFactor must: be in the range [eq]#[1,256]#
****

include::{generated}/validity/protos/vkCmdSetLineStippleEXT.adoc[]
--


[[primsrast-lines-smooth]]
=== Smooth Lines

If the pname:lineRasterizationMode member of
slink:VkPipelineRasterizationLineStateCreateInfoEXT is
ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, then lines are
considered to be rectangles using the same geometry as for
ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT lines.
The rules for determining which pixels are covered are
implementation-dependent, and may: include nearby pixels where no sample
locations are covered or where the rectangle does not intersect the pixel at
all.
For each pixel that is considered covered, the fragment computes a coverage
value that approximates the area of the intersection of the rectangle with
the pixel square, and this coverage value is multiplied into the color
location 0's alpha value after fragment shading, as described in
<<fragops-covg,Multisample Coverage>>.

[NOTE]
.Note
====
The details of the rasterization rules and area calculation are left
intentionally vague, to allow implementations to generate coverage and
values that are aesthetically pleasing.
====
endif::VK_EXT_line_rasterization[]


[[primsrast-polygons]]
== Polygons

A polygon results from the decomposition of a triangle strip, triangle fan
or a series of independent triangles.
Like points and line segments, polygon rasterization is controlled by
several variables in the slink:VkPipelineRasterizationStateCreateInfo
structure.


[[primsrast-polygons-basic]]
=== Basic Polygon Rasterization

[open,refpage='VkFrontFace',desc='Interpret polygon front-facing orientation',type='enums']
--
The first step of polygon rasterization is to determine whether the triangle
is _back-facing_ or _front-facing_.
This determination is made based on the sign of the (clipped or unclipped)
polygon's area computed in framebuffer coordinates.
One way to compute this area is:

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
a = -{1 \over 2}\sum_{i=0}^{n-1}
      x_f^i y_f^{i \oplus 1} -
      x_f^{i \oplus 1} y_f^i
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

where latexmath:[x_f^i] and latexmath:[y_f^i] are the [eq]#x# and [eq]#y#
framebuffer coordinates of the [eq]##i##th vertex of the [eq]#n#-vertex
polygon (vertices are numbered starting at zero for the purposes of this
computation) and [eq]#i {oplus} 1# is [eq]#(i {plus} 1) mod n#.

The interpretation of the sign of [eq]#a# is determined by the
slink:VkPipelineRasterizationStateCreateInfo::pname:frontFace property of
the currently active pipeline.
Possible values are:

include::{generated}/api/enums/VkFrontFace.adoc[]

  * ename:VK_FRONT_FACE_COUNTER_CLOCKWISE specifies that a triangle with
    positive area is considered front-facing.
  * ename:VK_FRONT_FACE_CLOCKWISE specifies that a triangle with negative
    area is considered front-facing.

Any triangle which is not front-facing is back-facing, including zero-area
triangles.
--

ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[]
[open,refpage='vkCmdSetFrontFace',desc='Set front face orientation dynamically for a command buffer',type='protos',alias='vkCmdSetFrontFaceEXT']
--
To <<pipelines-dynamic-state, dynamically set>> the front face orientation,
call:

ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkCmdSetFrontFace.adoc[]

ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command]
endif::VK_VERSION_1_3[]

ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[]
include::{generated}/api/protos/vkCmdSetFrontFaceEXT.adoc[]
endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:frontFace is a elink:VkFrontFace value specifying the front-facing
    triangle orientation to be used for culling.

This command sets the front face orientation for subsequent drawing commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[]
when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_FRONT_FACE
set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[]
Otherwise, this state is specified by the
slink:VkPipelineRasterizationStateCreateInfo::pname:frontFace value used to
create the currently active pipeline.

:refpage: vkCmdSetFrontFace

.Valid Usage
****
include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[]
****

include::{generated}/validity/protos/vkCmdSetFrontFace.adoc[]
--
endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[]


[open,refpage='VkCullModeFlagBits',desc='Bitmask controlling triangle culling',type='enums']
--
Once the orientation of triangles is determined, they are culled according
to the slink:VkPipelineRasterizationStateCreateInfo::pname:cullMode property
of the currently active pipeline.
Possible values are:

include::{generated}/api/enums/VkCullModeFlagBits.adoc[]

  * ename:VK_CULL_MODE_NONE specifies that no triangles are discarded
  * ename:VK_CULL_MODE_FRONT_BIT specifies that front-facing triangles are
    discarded
  * ename:VK_CULL_MODE_BACK_BIT specifies that back-facing triangles are
    discarded
  * ename:VK_CULL_MODE_FRONT_AND_BACK specifies that all triangles are
    discarded.

Following culling, fragments are produced for any triangles which have not
been discarded.
--

[open,refpage='VkCullModeFlags',desc='Bitmask of VkCullModeFlagBits',type='flags']
--
include::{generated}/api/flags/VkCullModeFlags.adoc[]

tname:VkCullModeFlags is a bitmask type for setting a mask of zero or more
elink:VkCullModeFlagBits.
--

ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[]
[open,refpage='vkCmdSetCullMode',desc='Set cull mode dynamically for a command buffer',type='protos',alias='vkCmdSetCullModeEXT']
--
To <<pipelines-dynamic-state, dynamically set>> the cull mode, call:

ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkCmdSetCullMode.adoc[]

ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command]
endif::VK_VERSION_1_3[]

ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[]
include::{generated}/api/protos/vkCmdSetCullModeEXT.adoc[]
endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:cullMode specifies the cull mode property to use for drawing.

This command sets the cull mode for subsequent drawing commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[]
when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_CULL_MODE
set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[]
Otherwise, this state is specified by the
slink:VkPipelineRasterizationStateCreateInfo::pname:cullMode value used to
create the currently active pipeline.

:refpage: vkCmdSetCullMode

.Valid Usage
****
include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[]
****

include::{generated}/validity/protos/vkCmdSetCullMode.adoc[]
--
endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[]

The rule for determining which fragments are produced by polygon
rasterization is called _point sampling_.
The two-dimensional projection obtained by taking the x and y framebuffer
coordinates of the polygon's vertices is formed.
Fragments are produced for any fragment area groups of pixels for which any
sample points lie inside of this polygon.
Coverage bits that correspond to sample points that satisfy the point
sampling criteria are 1, other coverage bits are 0.
Special treatment is given to a sample whose sample location lies on a
polygon edge.
In such a case, if two polygons lie on either side of a common edge (with
identical endpoints) on which a sample point lies, then exactly one of the
polygons must: result in a covered sample for that fragment during
rasterization.
As for the data associated with each fragment produced by rasterizing a
polygon, we begin by specifying how these values are produced for fragments
in a triangle.

[[primsrast-polygon-barycentrics]]
_Barycentric coordinates_ are a set of three numbers, [eq]#a#, [eq]#b#, and
[eq]#c#, each in the range [eq]#[0,1]#, with [eq]#a {plus} b {plus} c = 1#.
These coordinates uniquely specify any point [eq]#p# within the triangle or
on the triangle's boundary as

  {empty}:: [eq]#p = a p~a~ {plus} b p~b~ {plus} c p~c~#

where [eq]#p~a~#, [eq]#p~b~#, and [eq]#p~c~# are the vertices of the
triangle.
[eq]#a#, [eq]#b#, and [eq]#c# are determined by:

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
a = {{\mathrm{A}(p p_b p_c)} \over {\mathrm{A}(p_a p_b p_c)}}, \quad
b = {{\mathrm{A}(p p_a p_c)} \over {\mathrm{A}(p_a p_b p_c)}}, \quad
c = {{\mathrm{A}(p p_a p_b)} \over {\mathrm{A}(p_a p_b p_c)}},
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

where [eq]#A(lmn)# denotes the area in framebuffer coordinates of the
triangle with vertices [eq]#l#, [eq]#m#, and [eq]#n#.

Denote an associated datum at [eq]#p~a~#, [eq]#p~b~#, or [eq]#p~c~# as
[eq]#f~a~#, [eq]#f~b~#, or [eq]#f~c~#, respectively.

[[triangle_perspective_interpolation]]
_Perspective interpolation_ for a triangle interpolates three values in a
manner that is correct when taking the perspective of the viewport into
consideration, by way of the triangle's clip coordinates.
An interpolated value [eq]#f# can be determined by

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
f = {{ a {f_a / w_a} + b {f_b / w_b} + c {f_c / w_c} } \over
    { {a / w_a} + {b / w_b} + {c / w_c} }}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

where [eq]#w~a~#, [eq]#w~b~#, and [eq]#w~c~# are the clip [eq]#w#
coordinates of [eq]#p~a~#, [eq]#p~b~#, and [eq]#p~c~#, respectively.
[eq]#a#, [eq]#b#, and [eq]#c# are the barycentric coordinates of the
location at which the data are produced.

[[triangle_linear_interpolation]]
_Linear interpolation_ for a triangle directly interpolates three values,
and an interpolated value [eq]#f# can be determined by

  {empty}:: [eq]#f = a f~a~ {plus} b f~b~ {plus} c f~c~#

where [eq]#f~a~#, [eq]#f~b~#, and [eq]#f~c~# are the data associated with
[eq]#p~a~#, [eq]#p~b~#, and [eq]#p~c~#, respectively.

The clip coordinate [eq]#w# for a sample is determined using perspective
interpolation.
The depth value [eq]#z# for a sample is determined using linear
interpolation.
Interpolation of fragment shader input values are determined by
<<shaders-interpolation-decorations,Interpolation decorations>>.

For a polygon with more than three edges, such as are produced by clipping a
triangle, a convex combination of the values of the datum at the polygon's
vertices must: be used to obtain the value assigned to each fragment
produced by the rasterization algorithm.
That is, it must: be the case that at every fragment

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
f = \sum_{i=1}^{n} a_i f_i
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

where [eq]#n# is the number of vertices in the polygon and [eq]#f~i~# is the
value of [eq]#f# at vertex [eq]#i#.
For each [eq]#i#, [eq]#0 {leq} a~i~ {leq} 1# and
latexmath:[\sum_{i=1}^{n}a_i = 1].
The values of [eq]#a~i~# may: differ from fragment to fragment, but at
vertex [eq]#i#, [eq]#a~i~ = 1# and [eq]#a~j~ = 0# for [eq]#j {neq} i#.

[NOTE]
.Note
====
One algorithm that achieves the required behavior is to triangulate a
polygon (without adding any vertices) and then treat each triangle
individually as already discussed.
A scan-line rasterizer that linearly interpolates data along each edge and
then linearly interpolates data across each horizontal span from edge to
edge also satisfies the restrictions (in this case the numerator and
denominator of <<triangle_perspective_interpolation, perspective
interpolation>> are iterated independently, and a division is performed for
each fragment).
====


[[primsrast-polygonmode]]
=== Polygon Mode

[open,refpage='VkPolygonMode',desc='Control polygon rasterization mode',type='enums']
--
Possible values of the
slink:VkPipelineRasterizationStateCreateInfo::pname:polygonMode property of
the currently active pipeline, specifying the method of rasterization for
polygons, are:

include::{generated}/api/enums/VkPolygonMode.adoc[]

  * ename:VK_POLYGON_MODE_POINT specifies that polygon vertices are drawn as
    points.
  * ename:VK_POLYGON_MODE_LINE specifies that polygon edges are drawn as
    line segments.
  * ename:VK_POLYGON_MODE_FILL specifies that polygons are rendered using
    the polygon rasterization rules in this section.
ifdef::VK_NV_fill_rectangle[]
  * ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV specifies that polygons are
    rendered using polygon rasterization rules, modified to consider a
    sample within the primitive if the sample location is inside the
    axis-aligned bounding box of the triangle after projection.
    Note that the barycentric weights used in attribute interpolation can:
    extend outside the range [eq]#[0,1]# when these primitives are shaded.
    Special treatment is given to a sample position on the boundary edge of
    the bounding box.
    In such a case, if two rectangles lie on either side of a common edge
    (with identical endpoints) on which a sample position lies, then exactly
    one of the triangles must: produce a fragment that covers that sample
    during rasterization.
+
Polygons rendered in ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV mode may: be
clipped by the frustum or by user clip planes.
If clipping is applied, the triangle is culled rather than clipped.
+
Area calculation and facingness are determined for
ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV mode using the triangle's vertices.
endif::VK_NV_fill_rectangle[]

These modes affect only the final rasterization of polygons: in particular,
a polygon's vertices are shaded and the polygon is clipped and possibly
culled before these modes are applied.

ifndef::VK_KHR_maintenance5[]
The point size of the final rasterization of polygons when
<<primsrast-polygonmode, polygon mode>> is ename:VK_POLYGON_MODE_POINT is
implementation-dependent, and the point size may: either be code:PointSize
or 1.0.
endif::VK_KHR_maintenance5[]
ifdef::VK_KHR_maintenance5[]
If
sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:polygonModePointSize
is set to ename:VK_TRUE, the point size of the final rasterization of
polygons is taken from code:PointSize when <<primsrast-polygonmode, polygon
mode>> is ename:VK_POLYGON_MODE_POINT.

Otherwise, if
sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:polygonModePointSize
is set to ename:VK_FALSE, the point size of the final rasterization of
polygons is 1.0 when <<primsrast-polygonmode, polygon mode>> is
ename:VK_POLYGON_MODE_POINT.
endif::VK_KHR_maintenance5[]
--

ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]

[open,refpage='vkCmdSetPolygonModeEXT',desc='Specify polygon mode dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the polygon mode, call:

include::{generated}/api/protos/vkCmdSetPolygonModeEXT.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:polygonMode specifies polygon mode.

This command sets the polygon mode for subsequent drawing commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_POLYGON_MODE_EXT set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_EXT_extended_dynamic_state3[]
Otherwise, this state is specified by the
slink:VkPipelineRasterizationStateCreateInfo::pname:polygonMode value used
to create the currently active pipeline.

.Valid Usage
****
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetPolygonModeEXT-None-08566]]
    Either the <<features-extendedDynamicState3PolygonMode,
    pname:extendedDynamicState3PolygonMode>> feature or the
    <<features-shaderObject, pname:shaderObject>> feature or both must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
ifndef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetPolygonModeEXT-None-08567]]
    The <<features-shaderObject, pname:shaderObject>> feature must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
endif::VK_EXT_shader_object[]
ifndef::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetPolygonModeEXT-extendedDynamicState3PolygonMode-07422]]
    The <<features-extendedDynamicState3PolygonMode,
    pname:extendedDynamicState3PolygonMode>> feature must: be enabled
endif::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetPolygonModeEXT-fillModeNonSolid-07424]]
    If the <<features-fillModeNonSolid, pname:fillModeNonSolid>> feature is
    not enabled, pname:polygonMode must: be ename:VK_POLYGON_MODE_FILL
ifdef::VK_NV_fill_rectangle[or ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV]
ifdef::VK_NV_fill_rectangle[]
  * [[VUID-vkCmdSetPolygonModeEXT-polygonMode-07425]]
    If the `apiext:VK_NV_fill_rectangle` extension is not enabled,
    pname:polygonMode must: not be ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV
endif::VK_NV_fill_rectangle[]
****

include::{generated}/validity/protos/vkCmdSetPolygonModeEXT.adoc[]
--

endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]


[[primsrast-depthbias]]
=== Depth Bias

The depth values of all fragments generated by the rasterization of a
polygon can: be biased (offset) by a single depth bias value latexmath:[o]
that is computed for that polygon.


[[primsrast-depthbias-enable]]
==== Depth Bias Enable

The depth bias computation is enabled by the
ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[]
pname:depthBiasEnable set with flink:vkCmdSetDepthBiasEnable
ifdef::VK_EXT_extended_dynamic_state2[]
and fname:vkCmdSetDepthBiasEnableEXT,
endif::VK_EXT_extended_dynamic_state2[]
or the corresponding
endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[]
slink:VkPipelineRasterizationStateCreateInfo::pname:depthBiasEnable value
used to create the currently active pipeline.
If the depth bias enable is ename:VK_FALSE, no bias is applied and the
fragment's depth values are unchanged.

ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[]
[open,refpage='vkCmdSetDepthBiasEnable',desc='Control whether to bias fragment depth values dynamically for a command buffer',type='protos',alias='vkCmdSetDepthBiasEnableEXT']
--
To <<pipelines-dynamic-state, dynamically enable>> whether to bias fragment
depth values, call:

ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkCmdSetDepthBiasEnable.adoc[]

ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[or the equivalent command]
endif::VK_VERSION_1_3[]

ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[]
include::{generated}/api/protos/vkCmdSetDepthBiasEnableEXT.adoc[]
endif::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:depthBiasEnable controls whether to bias fragment depth values.

This command sets the depth bias enable for subsequent drawing commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[]
Otherwise, this state is specified by the
slink:VkPipelineRasterizationStateCreateInfo::pname:depthBiasEnable value
used to create the currently active pipeline.

:refpage: vkCmdSetDepthBiasEnable

.Valid Usage
****
include::{chapters}/commonvalidity/dynamic_state2_feature_common.adoc[]
****

include::{generated}/validity/protos/vkCmdSetDepthBiasEnable.adoc[]
--
endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[]


[[primsrast-depthbias-computation]]
==== Depth Bias Computation

The depth bias depends on three parameters:

  * pname:depthBiasSlopeFactor scales the maximum depth slope [eq]#m# of the
    polygon
  * pname:depthBiasConstantFactor scales the parameter [eq]#r# of the depth
    attachment
  * the scaled terms are summed to produce a value which is then clamped to
    a minimum or maximum value specified by pname:depthBiasClamp

pname:depthBiasSlopeFactor, pname:depthBiasConstantFactor, and
pname:depthBiasClamp can: each be positive, negative, or zero.
These parameters are set as described for flink:vkCmdSetDepthBias
ifdef::VK_EXT_depth_bias_control[]
and flink:vkCmdSetDepthBias2EXT
endif::VK_EXT_depth_bias_control[]
below.

The maximum depth slope [eq]#m# of a triangle is

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
m = \sqrt{ \left({{\partial z_f} \over {\partial x_f}}\right)^2
        +  \left({{\partial z_f} \over {\partial y_f}}\right)^2}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

where [eq]#(x~f~, y~f~, z~f~)# is a point on the triangle.
[eq]#m# may: be approximated as

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
m = \max\left( \left| { {\partial z_f} \over {\partial x_f} } \right|,
               \left| { {\partial z_f} \over {\partial y_f} } \right|
       \right).
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

ifdef::VK_EXT_depth_bias_control[]
In a pipeline with a depth bias representation of
ename:VK_DEPTH_BIAS_REPRESENTATION_FLOAT_EXT, [eq]#r#, for the given
primitive is defined as

  {empty}:: [eq]#r = 1#


Otherwise
endif::VK_EXT_depth_bias_control[]
[eq]#r# is the minimum resolvable difference that depends on the depth
attachment representation.
ifdef::VK_EXT_depth_bias_control[]
If sname:VkDepthBiasRepresentationInfoEXT::pname:depthBiasExact is
ename:VK_FALSE it
endif::VK_EXT_depth_bias_control[]
ifndef::VK_EXT_depth_bias_control[It]
is the smallest difference in framebuffer coordinate [eq]#z# values that is
guaranteed to remain distinct throughout polygon rasterization and in the
depth attachment.
All pairs of fragments generated by the rasterization of two polygons with
otherwise identical vertices, but [eq]#pname:z~f~# values that differ by
[eq]#r#, will have distinct depth values.

For fixed-point depth attachment representations,
ifdef::VK_EXT_depth_bias_control[]
or in a pipeline with a depth bias representation of
ename:VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORCE_UNORM_EXT,
endif::VK_EXT_depth_bias_control[]
[eq]#r# is constant throughout the range of the entire depth attachment.
ifdef::VK_EXT_depth_bias_control[]
If sname:VkDepthBiasRepresentationInfoEXT::pname:depthBiasExact is
ename:VK_TRUE, then its value must: be

  {empty}:: [eq]#r = 2^-n^#

Otherwise its value is implementation-dependent but must: be at most
endif::VK_EXT_depth_bias_control[]
ifndef::VK_EXT_depth_bias_control[]
Its value is implementation-dependent but must: be at most
endif::VK_EXT_depth_bias_control[]

  {empty}:: [eq]#r = 2 {times} 2^-n^#

where [eq]#n# is the number of bits used for the depth
ifndef::VK_EXT_depth_bias_control[aspect.]
ifdef::VK_EXT_depth_bias_control[]
aspect when using a fixed-point attachment, or the number of mantissa bits
plus one when using a floating-point attachment.
endif::VK_EXT_depth_bias_control[]


ifdef::VK_EXT_depth_bias_control[Otherwise for]
ifndef::VK_EXT_depth_bias_control[For]
floating-point depth attachment, there is no single minimum resolvable
difference.
In this case, the minimum resolvable difference for a given polygon is
dependent on the maximum exponent, [eq]#e#, in the range of [eq]#z# values
spanned by the primitive.
If [eq]#n# is the number of bits in the floating-point mantissa, the minimum
resolvable difference, [eq]#r#, for the given primitive is defined as

  {empty}:: [eq]#r = 2^e-n^#

ifdef::VK_NV_fill_rectangle[]
If a triangle is rasterized using the
ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV polygon mode, then this minimum
resolvable difference may: not be resolvable for samples outside of the
triangle, where the depth is extrapolated.
endif::VK_NV_fill_rectangle[]

If no depth attachment is present, [eq]#r# is undefined:.

The bias value [eq]#o# for a polygon is

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\begin{aligned}
o &= \mathrm{dbclamp}( m \times \mathtt{depthBiasSlopeFactor} + r \times \mathtt{depthBiasConstantFactor} ) \\
\text{where} &\quad \mathrm{dbclamp}(x) =
\begin{cases}
    x                                 & \mathtt{depthBiasClamp} = 0 \ \text{or}\ \texttt{NaN} \\
    \min(x, \mathtt{depthBiasClamp})  & \mathtt{depthBiasClamp} > 0 \\
    \max(x, \mathtt{depthBiasClamp})  & \mathtt{depthBiasClamp} < 0 \\
\end{cases}
\end{aligned}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

[eq]#m# is computed as described above.
If the depth attachment uses a fixed-point representation, [eq]#m# is a
function of depth values in the range [eq]#[0,1]#, and [eq]#o# is applied to
depth values in the same range.

Depth bias is applied to triangle topology primitives received by the
rasterizer regardless of <<primsrast-polygonmode, polygon mode>>.
Depth bias may: also be applied to line and point topology primitives
received by the rasterizer.

[open,refpage='vkCmdSetDepthBias',desc='Set depth bias factors and clamp dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the depth bias parameters,
call:

include::{generated}/api/protos/vkCmdSetDepthBias.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:depthBiasConstantFactor is a scalar factor controlling the
    constant depth value added to each fragment.
  * pname:depthBiasClamp is the maximum (or minimum) depth bias of a
    fragment.
  * pname:depthBiasSlopeFactor is a scalar factor applied to a fragment's
    slope in depth bias calculations.

This command sets the depth bias parameters for subsequent drawing commands
ifdef::VK_EXT_shader_object[when drawing using <<shaders-objects, shader objects>>, or]
when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_BIAS
set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
Otherwise, this state is specified by the corresponding
slink:VkPipelineRasterizationStateCreateInfo::pname:depthBiasConstantFactor,
pname:depthBiasClamp, and pname:depthBiasSlopeFactor values used to create
the currently active pipeline.

ifdef::VK_EXT_depth_bias_control[]
Calling this function is equivalent to calling fname:vkCmdSetDepthBias2EXT
without a sname:VkDepthBiasRepresentationInfoEXT in the pNext chain of
sname:VkDepthBiasInfoEXT.
endif::VK_EXT_depth_bias_control[]

.Valid Usage
****
  * [[VUID-vkCmdSetDepthBias-depthBiasClamp-00790]]
    If the <<features-depthBiasClamp, pname:depthBiasClamp>> feature is not
    enabled, pname:depthBiasClamp must: be `0.0`
****

include::{generated}/validity/protos/vkCmdSetDepthBias.adoc[]
--

ifdef::VK_EXT_depth_bias_control[]
[open,refpage='VkDepthBiasRepresentationInfoEXT',desc='Structure specifying depth bias parameters',type='structs']
--
:refpage: VkDepthBiasRepresentationInfoEXT

The sname:VkDepthBiasRepresentationInfoEXT structure is defined as:

include::{generated}/api/structs/VkDepthBiasRepresentationInfoEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:depthBiasRepresentation is a elink:VkDepthBiasRepresentationEXT
    value specifying the depth bias representation.
  * pname:depthBiasExact specifies that the implementation is not allowed to
    scale the depth bias value to ensure a minimum resolvable distance.

.Valid Usage
****
  * [[VUID-VkDepthBiasRepresentationInfoEXT-leastRepresentableValueForceUnormRepresentation-08947]]
    If the <<features-leastRepresentableValueForceUnormRepresentation,
    pname:leastRepresentableValueForceUnormRepresentation>> feature is not
    enabled, pname:depthBiasRepresentation must: not be
    `VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORCE_UNORM_EXT`
  * [[VUID-VkDepthBiasRepresentationInfoEXT-floatRepresentation-08948]]
    If the <<features-floatRepresentation, pname:floatRepresentation>>
    feature is not enabled, pname:depthBiasRepresentation must: not be
    `VK_DEPTH_BIAS_REPRESENTATION_FLOAT_EXT`
  * [[VUID-VkDepthBiasRepresentationInfoEXT-depthBiasExact-08949]]
    If the <<features-depthBiasExact, pname:depthBiasExact>> feature is not
    enabled, pname:depthBiasExact must: be `VK_FALSE`
****

include::{generated}/validity/structs/VkDepthBiasRepresentationInfoEXT.adoc[]
--

[open,refpage='VkDepthBiasRepresentationEXT',desc='Specify the depth bias representation',type='enums']
--
Possible values of
slink:VkDepthBiasRepresentationInfoEXT::pname:depthBiasRepresentation,
specifying the depth bias representation are:

include::{generated}/api/enums/VkDepthBiasRepresentationEXT.adoc[]

  * ename:VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORMAT_EXT
    specifies that the depth bias representation is a factor of the format's
    [eq]#r# as described in <<primsrast-depthbias-computation>>.
  * ename:VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORCE_UNORM_EXT
    specifies that the depth bias representation is a factor of a constant
    [eq]#r# defined by the bit-size or mantissa of the format as described
    in <<primsrast-depthbias-computation>>.
  * ename:VK_DEPTH_BIAS_REPRESENTATION_FLOAT_EXT specifies that the depth
    bias representation is a factor of constant [eq]#r# equal to 1.
--

[open,refpage='VkDepthBiasInfoEXT',desc='Structure specifying depth bias parameters',type='structs']
--
:refpage: VkDepthBiasInfoEXT

The sname:VkDepthBiasInfoEXT structure is defined as:

include::{generated}/api/structs/VkDepthBiasInfoEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:depthBiasConstantFactor is a scalar factor controlling the
    constant depth value added to each fragment.
  * pname:depthBiasClamp is the maximum (or minimum) depth bias of a
    fragment.
  * pname:depthBiasSlopeFactor is a scalar factor applied to a fragment's
    slope in depth bias calculations.

If pname:pNext does not contain a slink:VkDepthBiasRepresentationInfoEXT
structure, then this command is equivalent to including a
slink:VkDepthBiasRepresentationInfoEXT with pname:depthBiasExact set to
ename:VK_FALSE and pname:depthBiasRepresentation set to
ename:VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORMAT_EXT.

.Valid Usage
****
  * [[VUID-VkDepthBiasInfoEXT-depthBiasClamp-08950]]
    If the <<features-depthBiasClamp, pname:depthBiasClamp>> feature is not
    enabled, pname:depthBiasClamp must: be `0.0`
****

include::{generated}/validity/structs/VkDepthBiasInfoEXT.adoc[]
--

[open,refpage='vkCmdSetDepthBias2EXT',desc='Set depth bias factors and clamp dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the depth bias parameters,
call:

include::{generated}/api/protos/vkCmdSetDepthBias2EXT.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pDepthBiasInfo is a pointer to a slink:VkDepthBiasInfoEXT
    structure specifying depth bias parameters.

This command is functionally identical to flink:vkCmdSetDepthBias, but
includes extensible sub-structures that include pname:sType and pname:pNext
parameters, allowing them to be more easily extended.

include::{generated}/validity/protos/vkCmdSetDepthBias2EXT.adoc[]
--
endif::VK_EXT_depth_bias_control[]

ifdef::VK_EXT_conservative_rasterization[]
[[primsrast-conservativeraster]]
=== Conservative Rasterization

[open,refpage='VkPipelineRasterizationConservativeStateCreateInfoEXT',desc='Structure specifying conservative raster state',type='structs']
--
If the pname:pNext chain of slink:VkPipelineRasterizationStateCreateInfo
includes a sname:VkPipelineRasterizationConservativeStateCreateInfoEXT
structure, then that structure includes parameters controlling conservative
rasterization.

sname:VkPipelineRasterizationConservativeStateCreateInfoEXT is defined as:

include::{generated}/api/structs/VkPipelineRasterizationConservativeStateCreateInfoEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is reserved for future use.
  * pname:conservativeRasterizationMode is the conservative rasterization
    mode to use.
  * pname:extraPrimitiveOverestimationSize is the extra size in pixels to
    increase the generating primitive during conservative rasterization at
    each of its edges in `X` and `Y` equally in screen space beyond the base
    overestimation specified in
    sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:primitiveOverestimationSize.
    If pname:conservativeRasterizationMode is not
    ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT, this value is
    ignored.

If this structure is not included in the pname:pNext chain,
pname:conservativeRasterizationMode is considered to be
ename:VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT, and and conservative
rasterization is disabled.

Polygon rasterization can: be made conservative by setting
pname:conservativeRasterizationMode to
ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT or
ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT in
sname:VkPipelineRasterizationConservativeStateCreateInfoEXT.

[NOTE]
.Note
====
If <<limits-conservativePointAndLineRasterization,
pname:conservativePointAndLineRasterization>> is supported, conservative
rasterization can be applied to line and point primitives, otherwise it must
be disabled.
====

.Valid Usage
****
  * [[VUID-VkPipelineRasterizationConservativeStateCreateInfoEXT-extraPrimitiveOverestimationSize-01769]]
    pname:extraPrimitiveOverestimationSize must: be in the range of `0.0` to
    sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:maxExtraPrimitiveOverestimationSize
    inclusive
****

include::{generated}/validity/structs/VkPipelineRasterizationConservativeStateCreateInfoEXT.adoc[]
--

[open,refpage='VkPipelineRasterizationConservativeStateCreateFlagsEXT',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkPipelineRasterizationConservativeStateCreateFlagsEXT.adoc[]

tname:VkPipelineRasterizationConservativeStateCreateFlagsEXT is a bitmask
type for setting a mask, but is currently reserved for future use.
--

[open,refpage='VkConservativeRasterizationModeEXT',desc='Specify the conservative rasterization mode',type='enums']
--
Possible values of
slink:VkPipelineRasterizationConservativeStateCreateInfoEXT::pname:conservativeRasterizationMode,
specifying the conservative rasterization mode are:

include::{generated}/api/enums/VkConservativeRasterizationModeEXT.adoc[]

  * ename:VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT specifies that
    conservative rasterization is disabled and rasterization proceeds as
    normal.
  * ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT specifies that
    conservative rasterization is enabled in overestimation mode.
  * ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT specifies
    that conservative rasterization is enabled in underestimation mode.
--

ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]

[open,refpage='vkCmdSetConservativeRasterizationModeEXT',desc='Specify the conservative rasterization mode dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the
pname:conservativeRasterizationMode, call:

include::{generated}/api/protos/vkCmdSetConservativeRasterizationModeEXT.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:conservativeRasterizationMode specifies the
    pname:conservativeRasterizationMode state.

This command sets the pname:conservativeRasterizationMode state for
subsequent drawing commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_EXT_extended_dynamic_state3[]
Otherwise, this state is specified by the
slink:VkPipelineRasterizationConservativeStateCreateInfoEXT::pname:conservativeRasterizationMode
value used to create the currently active pipeline.

.Valid Usage
****
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetConservativeRasterizationModeEXT-None-08570]]
    Either the
    <<features-extendedDynamicState3ConservativeRasterizationMode,
    pname:extendedDynamicState3ConservativeRasterizationMode>> feature or
    the <<features-shaderObject, pname:shaderObject>> feature or both must:
    be enabled
endif::VK_EXT_extended_dynamic_state3[]
ifndef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetConservativeRasterizationModeEXT-None-08571]]
    The <<features-shaderObject, pname:shaderObject>> feature must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
endif::VK_EXT_shader_object[]
ifndef::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetConservativeRasterizationModeEXT-extendedDynamicState3ConservativeRasterizationMode-07426]]
    The <<features-extendedDynamicState3ConservativeRasterizationMode,
    pname:extendedDynamicState3ConservativeRasterizationMode>> feature must:
    be enabled
endif::VK_EXT_shader_object[]
****

include::{generated}/validity/protos/vkCmdSetConservativeRasterizationModeEXT.adoc[]
--

[open,refpage='vkCmdSetExtraPrimitiveOverestimationSizeEXT',desc='Specify the conservative rasterization extra primitive overestimation size dynamically for a command buffer',type='protos']
--
To <<pipelines-dynamic-state, dynamically set>> the
pname:extraPrimitiveOverestimationSize, call:

include::{generated}/api/protos/vkCmdSetExtraPrimitiveOverestimationSizeEXT.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:extraPrimitiveOverestimationSize specifies the
    pname:extraPrimitiveOverestimationSize.

This command sets the pname:extraPrimitiveOverestimationSize for subsequent
drawing commands
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>, or]
ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.]
endif::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
when the graphics pipeline is created with
ename:VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT set in
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates.
endif::VK_EXT_extended_dynamic_state3[]
Otherwise, this state is specified by the
slink:VkPipelineRasterizationConservativeStateCreateInfoEXT::pname:extraPrimitiveOverestimationSize
value used to create the currently active pipeline.

.Valid Usage
****
ifdef::VK_EXT_shader_object[]
ifdef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetExtraPrimitiveOverestimationSizeEXT-None-08572]]
    Either the
    <<features-extendedDynamicState3ExtraPrimitiveOverestimationSize,
    pname:extendedDynamicState3ExtraPrimitiveOverestimationSize>> feature or
    the <<features-shaderObject, pname:shaderObject>> feature or both must:
    be enabled
endif::VK_EXT_extended_dynamic_state3[]
ifndef::VK_EXT_extended_dynamic_state3[]
  * [[VUID-vkCmdSetExtraPrimitiveOverestimationSizeEXT-None-08573]]
    The <<features-shaderObject, pname:shaderObject>> feature must: be
    enabled
endif::VK_EXT_extended_dynamic_state3[]
endif::VK_EXT_shader_object[]
ifndef::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetExtraPrimitiveOverestimationSizeEXT-extendedDynamicState3ExtraPrimitiveOverestimationSize-07427]]
    The <<features-extendedDynamicState3ExtraPrimitiveOverestimationSize,
    pname:extendedDynamicState3ExtraPrimitiveOverestimationSize>> feature
    must: be enabled
endif::VK_EXT_shader_object[]
  * [[VUID-vkCmdSetExtraPrimitiveOverestimationSizeEXT-extraPrimitiveOverestimationSize-07428]]
    pname:extraPrimitiveOverestimationSize must: be in the range of `0.0` to
    sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:maxExtraPrimitiveOverestimationSize
    inclusive
****

include::{generated}/validity/protos/vkCmdSetExtraPrimitiveOverestimationSizeEXT.adoc[]
--

endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[]

When overestimate conservative rasterization is enabled, rather than
evaluating coverage at individual sample locations, a determination is made
whether any portion of the pixel (including its edges and corners) is
covered by the primitive.
If any portion of the pixel is covered, then all bits of the
<<primsrast-multisampling-coverage-mask, coverage mask>> for the fragment
corresponding to that pixel are enabled.
ifdef::VK_EXT_fragment_density_map[]
If the render pass has a fragment density map attachment and any bit of the
<<primsrast-multisampling-coverage-mask, coverage mask>> for the fragment is
enabled, then all bits of the <<primsrast-multisampling-coverage-mask,
coverage mask>> for the fragment are enabled.
endif::VK_EXT_fragment_density_map[]

For the purposes of evaluating which pixels are covered by the primitive,
implementations can: increase the size of the primitive by up to
sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:primitiveOverestimationSize
pixels at each of the primitive edges.
This may: increase the number of fragments generated by this primitive and
represents an overestimation of the pixel coverage.

This overestimation size can be increased further by setting the
pname:extraPrimitiveOverestimationSize value above `0.0` in steps of
sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:extraPrimitiveOverestimationSizeGranularity
up to and including
sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:extraPrimitiveOverestimationSize.
This may: further increase the number of fragments generated by this
primitive.

The actual precision of the overestimation size used for conservative
rasterization may: vary between implementations and produce results that
only approximate the pname:primitiveOverestimationSize and
pname:extraPrimitiveOverestimationSizeGranularity properties.
ifdef::VK_EXT_fragment_density_map[]
Implementations may: especially vary these approximations when the render
pass has a fragment density map and the fragment area covers multiple
pixels.
endif::VK_EXT_fragment_density_map[]

For triangles if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT
is enabled, fragments will be generated if the primitive area covers any
portion of any pixel inside the fragment area, including their edges or
corners.
The tie-breaking rule described in <<primsrast-polygons-basic, Basic Polygon
Rasterization>> does not apply during conservative rasterization and
coverage is set for all fragments generated from shared edges of polygons.
Degenerate triangles that evaluate to zero area after rasterization, even
for pixels containing a vertex or edge of the zero-area polygon, will be
culled if
sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:degenerateTrianglesRasterized
is ename:VK_FALSE or will generate fragments if
pname:degenerateTrianglesRasterized is ename:VK_TRUE.
The fragment input values for these degenerate triangles take their
attribute and depth values from the provoking vertex.
Degenerate triangles are considered backfacing and the application can:
enable backface culling if desired.
Triangles that are zero area before rasterization may: be culled regardless.

For lines if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT is
enabled, and the implementation sets
sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativePointAndLineRasterization
to ename:VK_TRUE, fragments will be generated if the line covers any portion
of any pixel inside the fragment area, including their edges or corners.
Degenerate lines that evaluate to zero length after rasterization will be
culled if
sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:degenerateLinesRasterized
is ename:VK_FALSE or will generate fragments if
pname:degenerateLinesRasterized is ename:VK_TRUE.
The fragments input values for these degenerate lines take their attribute
and depth values from the provoking vertex.
Lines that are zero length before rasterization may: be culled regardless.

For points if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT is
enabled, and the implementation sets
sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:conservativePointAndLineRasterization
to ename:VK_TRUE, fragments will be generated if the point square covers any
portion of any pixel inside the fragment area, including their edges or
corners.

When underestimate conservative rasterization is enabled, rather than
evaluating coverage at individual sample locations, a determination is made
whether all of the pixel (including its edges and corners) is covered by the
primitive.
If the entire pixel is covered, then a fragment is generated with all bits
of its <<primsrast-multisampling-coverage-mask, coverage mask>>
corresponding to the pixel enabled, otherwise the pixel is not considered
covered even if some portion of the pixel is covered.
The fragment is discarded if no pixels inside the fragment area are
considered covered.
ifdef::VK_EXT_fragment_density_map[]
If the render pass has a fragment density map attachment and any pixel
inside the fragment area is not considered covered, then the fragment is
discarded even if some pixels are considered covered.
endif::VK_EXT_fragment_density_map[]

For triangles, if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT
is enabled, fragments will only be generated if any pixel inside the
fragment area is fully covered by the generating primitive, including its
edges and corners.

For lines, if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT is
enabled, fragments will be generated if any pixel inside the fragment area,
including its edges and corners, are entirely covered by the line.

For points, if ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT is
enabled, fragments will only be generated if the point square covers the
entirety of any pixel square inside the fragment area, including its edges
or corners.

ifdef::VK_EXT_fragment_density_map[]
If the render pass has a fragment density map and
ename:VK_CONSERVATIVE_RASTERIZATION_MODE_UNDERESTIMATE_EXT is enabled,
fragments will only be generated if the entirety of all pixels inside the
fragment area are covered by the generating primitive, line, or point.
endif::VK_EXT_fragment_density_map[]

For both overestimate and underestimate conservative rasterization modes a
fragment has all of its pixel squares fully covered by the generating
primitive must: set code:FullyCoveredEXT to ename:VK_TRUE if the
implementation enables the
sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:fullyCoveredFragmentShaderInputVariable
feature.

ifdef::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[]
When
ifdef::VK_NV_shading_rate_image[]
the use of a <<primsrast-shading-rate-image, shading rate image>>
endif::VK_NV_shading_rate_image[]
ifdef::VK_NV_shading_rate_image+VK_KHR_fragment_shading_rate[or]
ifdef::VK_KHR_fragment_shading_rate[]
setting the <<primsrast-fragment-shading-rate, fragment shading rate>>
endif::VK_KHR_fragment_shading_rate[]
results in fragments covering multiple pixels, coverage for conservative
rasterization is still evaluated on a per-pixel basis and may result in
fragments with partial coverage.
For fragment shader inputs decorated with code:FullyCoveredEXT, a fragment
is considered fully covered if and only if all pixels in the fragment are
fully covered by the generating primitive.
endif::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[]

endif::VK_EXT_conservative_rasterization[]