Vulkan Logo

25. 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 (x,y) framebuffer coordinates, 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 fragment operations.

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

The VkPipelineRasterizationStateCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPipelineRasterizationStateCreateInfo {
    VkStructureType                            sType;
    const void*                                pNext;
    VkPipelineRasterizationStateCreateFlags    flags;
    VkBool32                                   depthClampEnable;
    VkBool32                                   rasterizerDiscardEnable;
    VkPolygonMode                              polygonMode;
    VkCullModeFlags                            cullMode;
    VkFrontFace                                frontFace;
    VkBool32                                   depthBiasEnable;
    float                                      depthBiasConstantFactor;
    float                                      depthBiasClamp;
    float                                      depthBiasSlopeFactor;
    float                                      lineWidth;
} VkPipelineRasterizationStateCreateInfo;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • depthClampEnable controls whether to clamp the fragment’s depth values as described in Depth Test. If the pipeline is not created with VkPipelineRasterizationDepthClipStateCreateInfoEXT present then enabling depth clamp will also disable clipping primitives to the z planes of the frustum as described in Primitive Clipping. Otherwise depth clipping is controlled by the state set in VkPipelineRasterizationDepthClipStateCreateInfoEXT.

  • rasterizerDiscardEnable controls whether primitives are discarded immediately before the rasterization stage.

  • polygonMode is the triangle rendering mode. See VkPolygonMode.

  • cullMode is the triangle facing direction used for primitive culling. See VkCullModeFlagBits.

  • frontFace is a VkFrontFace value specifying the front-facing triangle orientation to be used for culling.

  • depthBiasEnable controls whether to bias fragment depth values.

  • depthBiasConstantFactor is a scalar factor controlling the constant depth value added to each fragment.

  • depthBiasClamp is the maximum (or minimum) depth bias of a fragment.

  • depthBiasSlopeFactor is a scalar factor applied to a fragment’s slope in depth bias calculations.

  • lineWidth is the width of rasterized line segments.

Valid Usage
  • VUID-VkPipelineRasterizationStateCreateInfo-depthClampEnable-00782
    If the depthClamp feature is not enabled, depthClampEnable must be VK_FALSE

  • VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-01507
    If the fillModeNonSolid feature is not enabled, polygonMode must be VK_POLYGON_MODE_FILL

  • VUID-VkPipelineRasterizationStateCreateInfo-pointPolygons-04458
    If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::pointPolygons is VK_FALSE, and rasterizerDiscardEnable is VK_FALSE, polygonMode must not be VK_POLYGON_MODE_POINT

Valid Usage (Implicit)
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineRasterizationStateCreateFlags;

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

If the pNext chain of VkPipelineRasterizationStateCreateInfo includes a VkPipelineRasterizationDepthClipStateCreateInfoEXT structure, then that structure controls whether depth clipping is enabled or disabled.

The VkPipelineRasterizationDepthClipStateCreateInfoEXT structure is defined as:

// Provided by VK_EXT_depth_clip_enable
typedef struct VkPipelineRasterizationDepthClipStateCreateInfoEXT {
    VkStructureType                                        sType;
    const void*                                            pNext;
    VkPipelineRasterizationDepthClipStateCreateFlagsEXT    flags;
    VkBool32                                               depthClipEnable;
} VkPipelineRasterizationDepthClipStateCreateInfoEXT;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • depthClipEnable controls whether depth clipping is enabled as described in Primitive Clipping.

Valid Usage (Implicit)
  • VUID-VkPipelineRasterizationDepthClipStateCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_DEPTH_CLIP_STATE_CREATE_INFO_EXT

  • VUID-VkPipelineRasterizationDepthClipStateCreateInfoEXT-flags-zerobitmask
    flags must be 0

// Provided by VK_EXT_depth_clip_enable
typedef VkFlags VkPipelineRasterizationDepthClipStateCreateFlagsEXT;

VkPipelineRasterizationDepthClipStateCreateFlagsEXT is a bitmask type for setting a mask, but is currently reserved for future use.

The VkPipelineMultisampleStateCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPipelineMultisampleStateCreateInfo {
    VkStructureType                          sType;
    const void*                              pNext;
    VkPipelineMultisampleStateCreateFlags    flags;
    VkSampleCountFlagBits                    rasterizationSamples;
    VkBool32                                 sampleShadingEnable;
    float                                    minSampleShading;
    const VkSampleMask*                      pSampleMask;
    VkBool32                                 alphaToCoverageEnable;
    VkBool32                                 alphaToOneEnable;
} VkPipelineMultisampleStateCreateInfo;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • rasterizationSamples is a VkSampleCountFlagBits value specifying the number of samples used in rasterization. This value is ignored for the purposes of setting the number of samples used in rasterization if the pipeline is created with the VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT dynamic state set, but if VK_DYNAMIC_STATE_SAMPLE_MASK_EXT dynamic state is not set, it is still used to define the size of the pSampleMask array as described below.

  • sampleShadingEnable can be used to enable Sample Shading.

  • minSampleShading specifies a minimum fraction of sample shading if sampleShadingEnable is set to VK_TRUE.

  • pSampleMask is a pointer to an array of VkSampleMask values used in the sample mask test.

  • 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 Multisample Coverage section.

  • alphaToOneEnable controls whether the alpha component of the fragment’s first color output is replaced with one as described in Multisample Coverage.

Each bit in the sample mask is associated with a unique sample index as defined for the coverage mask. Each bit b for mask word w in the sample mask corresponds to sample index i, where i = 32 × w + b. pSampleMask has a length equal to rasterizationSamples / 32 ⌉ words.

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

Valid Usage
  • VUID-VkPipelineMultisampleStateCreateInfo-sampleShadingEnable-00784
    If the sampleRateShading feature is not enabled, sampleShadingEnable must be VK_FALSE

  • VUID-VkPipelineMultisampleStateCreateInfo-alphaToOneEnable-00785
    If the alphaToOne feature is not enabled, alphaToOneEnable must be VK_FALSE

  • VUID-VkPipelineMultisampleStateCreateInfo-minSampleShading-00786
    minSampleShading must be in the range [0,1]

Valid Usage (Implicit)
  • VUID-VkPipelineMultisampleStateCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_MULTISAMPLE_STATE_CREATE_INFO

  • VUID-VkPipelineMultisampleStateCreateInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkPipelineMultisampleStateCreateInfo-flags-zerobitmask
    flags must be 0

  • VUID-VkPipelineMultisampleStateCreateInfo-rasterizationSamples-parameter
    rasterizationSamples must be a valid VkSampleCountFlagBits value

  • VUID-VkPipelineMultisampleStateCreateInfo-pSampleMask-parameter
    If pSampleMask is not NULL, pSampleMask must be a valid pointer to an array of VkSampleMask values

// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineMultisampleStateCreateFlags;

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

The elements of the sample mask array are of type VkSampleMask, each representing 32 bits of coverage information:

// Provided by VK_VERSION_1_0
typedef uint32_t VkSampleMask;

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 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.

25.1. Discarding Primitives Before Rasterization

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

To dynamically enable whether primitives are discarded before the rasterization stage, call:

// Provided by VK_VERSION_1_3
void vkCmdSetRasterizerDiscardEnable(
    VkCommandBuffer                             commandBuffer,
    VkBool32                                    rasterizerDiscardEnable);

or the equivalent command

// Provided by VK_EXT_shader_object
void vkCmdSetRasterizerDiscardEnableEXT(
    VkCommandBuffer                             commandBuffer,
    VkBool32                                    rasterizerDiscardEnable);
  • commandBuffer is the command buffer into which the command will be recorded.

  • rasterizerDiscardEnable controls whether primitives are discarded immediately before the rasterization stage.

This command sets the discard enable for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineRasterizationStateCreateInfo::rasterizerDiscardEnable value used to create the currently active pipeline.

Valid Usage
  • VUID-vkCmdSetRasterizerDiscardEnable-None-08970
    At least one of the following must be true:

Valid Usage (Implicit)
  • VUID-vkCmdSetRasterizerDiscardEnable-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetRasterizerDiscardEnable-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetRasterizerDiscardEnable-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetRasterizerDiscardEnable-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

25.2. Controlling the Vertex Stream Used for Rasterization

By default vertex data output from the last 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 OpEndPrimitive and 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 VkPhysicalDeviceTransformFeedbackPropertiesEXT::maxTransformFeedbackStreams streams, which is at least 1. The individual streams are numbered 0 through 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 VkPhysicalDeviceTransformFeedbackPropertiesEXT::maxTransformFeedbackStreamDataSize and VkPhysicalDeviceTransformFeedbackPropertiesEXT::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 pre-rasterization shader stage shader’s XfbBuffer, XfbStride, and 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 GeometryStreams capability must be specified.

By default, the primitives output from vertex stream zero are rasterized. If the implementation supports the VkPhysicalDeviceTransformFeedbackPropertiesEXT::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 OutputPoints output primitive type. If the implementation supports the VkPhysicalDeviceTransformFeedbackPropertiesEXT::transformFeedbackStreamsLinesTriangles property it is possible to emit OutputLineStrip or OutputTriangleStrip in addition to OutputPoints.

The vertex stream used for rasterization is specified by adding a VkPipelineRasterizationStateStreamCreateInfoEXT structure to the pNext chain of a VkPipelineRasterizationStateCreateInfo structure.

The VkPipelineRasterizationStateStreamCreateInfoEXT structure is defined as:

// Provided by VK_EXT_transform_feedback
typedef struct VkPipelineRasterizationStateStreamCreateInfoEXT {
    VkStructureType                                     sType;
    const void*                                         pNext;
    VkPipelineRasterizationStateStreamCreateFlagsEXT    flags;
    uint32_t                                            rasterizationStream;
} VkPipelineRasterizationStateStreamCreateInfoEXT;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • rasterizationStream is the vertex stream selected for rasterization.

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

Valid Usage
  • VUID-VkPipelineRasterizationStateStreamCreateInfoEXT-geometryStreams-02324
    VkPhysicalDeviceTransformFeedbackFeaturesEXT::geometryStreams must be enabled

  • VUID-VkPipelineRasterizationStateStreamCreateInfoEXT-rasterizationStream-02325
    rasterizationStream must be less than VkPhysicalDeviceTransformFeedbackPropertiesEXT::maxTransformFeedbackStreams

  • VUID-VkPipelineRasterizationStateStreamCreateInfoEXT-rasterizationStream-02326
    rasterizationStream must be zero if VkPhysicalDeviceTransformFeedbackPropertiesEXT::transformFeedbackRasterizationStreamSelect is VK_FALSE

Valid Usage (Implicit)
  • VUID-VkPipelineRasterizationStateStreamCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_STREAM_CREATE_INFO_EXT

  • VUID-VkPipelineRasterizationStateStreamCreateInfoEXT-flags-zerobitmask
    flags must be 0

// Provided by VK_EXT_transform_feedback
typedef VkFlags VkPipelineRasterizationStateStreamCreateFlagsEXT;

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

To dynamically set the rasterizationStream state, call:

// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_transform_feedback, VK_EXT_shader_object with VK_EXT_transform_feedback
void vkCmdSetRasterizationStreamEXT(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    rasterizationStream);
  • commandBuffer is the command buffer into which the command will be recorded.

  • rasterizationStream specifies the rasterizationStream state.

This command sets the rasterizationStream state for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineRasterizationStateStreamCreateInfoEXT::rasterizationStream value used to create the currently active pipeline.

Valid Usage
  • VUID-vkCmdSetRasterizationStreamEXT-None-09423
    At least one of the following must be true:

  • VUID-vkCmdSetRasterizationStreamEXT-transformFeedback-07411
    The transformFeedback feature must be enabled

  • VUID-vkCmdSetRasterizationStreamEXT-rasterizationStream-07412
    rasterizationStream must be less than VkPhysicalDeviceTransformFeedbackPropertiesEXT::maxTransformFeedbackStreams

  • VUID-vkCmdSetRasterizationStreamEXT-rasterizationStream-07413
    rasterizationStream must be zero if VkPhysicalDeviceTransformFeedbackPropertiesEXT::transformFeedbackRasterizationStreamSelect is VK_FALSE

Valid Usage (Implicit)
  • VUID-vkCmdSetRasterizationStreamEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetRasterizationStreamEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetRasterizationStreamEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetRasterizationStreamEXT-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

25.3. Rasterization Order

Within a subpass of a 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:

  1. Fragment operations, in the order defined

  2. Blending, logic operations, and color writes

Execution of these operations for each primitive in a subpass occurs in primitive order.

25.4. 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 Resolving Multisample Images and the 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 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 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.

If the current pipeline includes a fragment shader with one or more variables in its interface decorated with Sample and 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 Sample and Input need not be evaluated independently for each sample.

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 have one set of samples. Multi-pixel fragments defined by setting the fragment shading rate have one set of samples per pixel. Each set of samples has a number of samples determined by VkPipelineMultisampleStateCreateInfo::rasterizationSamples. Each sample in a set is assigned a unique sample index i in the range [0, rasterizationSamples).

To dynamically set the rasterizationSamples, call:

// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetRasterizationSamplesEXT(
    VkCommandBuffer                             commandBuffer,
    VkSampleCountFlagBits                       rasterizationSamples);
  • commandBuffer is the command buffer into which the command will be recorded.

  • rasterizationSamples specifies rasterizationSamples.

This command sets the rasterizationSamples for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineMultisampleStateCreateInfo::rasterizationSamples value used to create the currently active pipeline.

Valid Usage
Valid Usage (Implicit)
  • VUID-vkCmdSetRasterizationSamplesEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetRasterizationSamplesEXT-rasterizationSamples-parameter
    rasterizationSamples must be a valid VkSampleCountFlagBits value

  • VUID-vkCmdSetRasterizationSamplesEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetRasterizationSamplesEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetRasterizationSamplesEXT-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

Each sample in a fragment is also assigned a unique coverage index j in the range [0, n × rasterizationSamples), where 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.

If the fragment shading rate is set, the coverage index j is determined as a function of the pixel index p, the sample index i, and the number of rasterization samples r as:

j = i + r × ((fw × fh) - 1 - p)

where the pixel index p is determined as a function of the pixel’s framebuffer location (x,y) and the fragment size (fw,fh):

px = x % fw

py = y % fh

p = px + (py × fw)

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

Table 29. Pixel indices - 1 wide
1x1 1x2 1x4

image/svg+xml x f y f 0

image/svg+xml x f y f 0 1

image/svg+xml x f y f 0 1 2 3

Table 30. Pixel indices - 2 wide
2x1 2x2 2x4

image/svg+xml x f y f 0 1

image/svg+xml x f y f 0 1 2 3

image/svg+xml x f y f 0 1 2 3 5 4 7 6

Table 31. Pixel indices - 4 wide
4x1 4x2 4x4

image/svg+xml x f y f 0 1 2 3

image/svg+xml x f y f 0 1 2 3 7 6 5 4

image/svg+xml x f y f 0 1 2 3 7 6 5 4 8 9 10 11 15 14 13 12

The coverage mask includes B bits packed into W words, defined as:

B = n × rasterizationSamples

W = ⌈B/32⌉

Bit b in coverage mask word w is 1 if the sample with coverage index j = 32×w + b is covered, and 0 otherwise.

If the standardSampleLocations member of VkPhysicalDeviceLimits is VK_TRUE, then the sample counts VK_SAMPLE_COUNT_1_BIT, VK_SAMPLE_COUNT_2_BIT, VK_SAMPLE_COUNT_4_BIT, VK_SAMPLE_COUNT_8_BIT, and VK_SAMPLE_COUNT_16_BIT have sample locations as listed in the following table, with the ith entry in the table corresponding to sample index i. VK_SAMPLE_COUNT_32_BIT and 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.

Table 32. Standard sample locations
Sample count Sample Locations

VK_SAMPLE_COUNT_1_BIT

(0.5,0.5)

VK_SAMPLE_COUNT_1_BIT 0

VK_SAMPLE_COUNT_2_BIT

(0.75,0.75)
(0.25,0.25)

VK_SAMPLE_COUNT_2_BIT 0 1

VK_SAMPLE_COUNT_4_BIT

(0.375, 0.125)
(0.875, 0.375)
(0.125, 0.625)
(0.625, 0.875)

VK_SAMPLE_COUNT_4_BIT 0 1 2 3

VK_SAMPLE_COUNT_8_BIT

(0.5625, 0.3125)
(0.4375, 0.6875)
(0.8125, 0.5625)
(0.3125, 0.1875)
(0.1875, 0.8125)
(0.0625, 0.4375)
(0.6875, 0.9375)
(0.9375, 0.0625)

VK_SAMPLE_COUNT_8_BIT 0 1 2 3 4 5 6 7

VK_SAMPLE_COUNT_16_BIT

(0.5625, 0.5625)
(0.4375, 0.3125)
(0.3125, 0.625)
(0.75, 0.4375)
(0.1875, 0.375)
(0.625, 0.8125)
(0.8125, 0.6875)
(0.6875, 0.1875)
(0.375, 0.875)
(0.5, 0.0625)
(0.25, 0.125)
(0.125, 0.75)
(0.0, 0.5)
(0.9375, 0.25)
(0.875, 0.9375)
(0.0625, 0.0)

VK_SAMPLE_COUNT_16_BIT 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

25.5. Fragment Shading Rates

The features advertised by VkPhysicalDeviceFragmentShadingRateFeaturesKHR allow an application to control the shading rate of a given fragment shader invocation.

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

To query available shading rates, call:

// Provided by VK_KHR_fragment_shading_rate
VkResult vkGetPhysicalDeviceFragmentShadingRatesKHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t*                                   pFragmentShadingRateCount,
    VkPhysicalDeviceFragmentShadingRateKHR*     pFragmentShadingRates);
  • physicalDevice is the handle to the physical device whose properties will be queried.

  • pFragmentShadingRateCount is a pointer to an integer related to the number of fragment shading rates available or queried, as described below.

  • pFragmentShadingRates is either NULL or a pointer to an array of VkPhysicalDeviceFragmentShadingRateKHR structures.

If pFragmentShadingRates is NULL, then the number of fragment shading rates available is returned in pFragmentShadingRateCount. Otherwise, pFragmentShadingRateCount must point to a variable set by the user to the number of elements in the pFragmentShadingRates array, and on return the variable is overwritten with the number of structures actually written to pFragmentShadingRates. If pFragmentShadingRateCount is less than the number of fragment shading rates available, at most pFragmentShadingRateCount structures will be written, and VK_INCOMPLETE will be returned instead of 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 fragmentSize.width value to smallest, and each set of fragment shading rates with the same fragmentSize.width value must be ordered from largest fragmentSize.height to smallest. Any two entries in the array must not have the same fragmentSize values.

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

  • The value of fragmentSize.width must be less than or equal to maxFragmentSize.width.

  • The value of fragmentSize.width must be greater than or equal to 1.

  • The value of fragmentSize.width must be a power-of-two.

  • The value of fragmentSize.height must be less than or equal to maxFragmentSize.height.

  • The value of fragmentSize.height must be greater than or equal to 1.

  • The value of fragmentSize.height must be a power-of-two.

  • The highest sample count in sampleCounts must be less than or equal to maxFragmentShadingRateRasterizationSamples.

  • The product of fragmentSize.width, fragmentSize.height, and the highest sample count in sampleCounts must be less than or equal to maxFragmentShadingRateCoverageSamples.

Implementations must support at least the following shading rates:

sampleCounts fragmentSize

VK_SAMPLE_COUNT_1_BIT | VK_SAMPLE_COUNT_4_BIT

{2,2}

VK_SAMPLE_COUNT_1_BIT | VK_SAMPLE_COUNT_4_BIT

{2,1}

~0

{1,1}

If framebufferColorSampleCounts, includes VK_SAMPLE_COUNT_2_BIT, the required rates must also include VK_SAMPLE_COUNT_2_BIT.

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 are supported for this rate.

Valid Usage (Implicit)
  • VUID-vkGetPhysicalDeviceFragmentShadingRatesKHR-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkGetPhysicalDeviceFragmentShadingRatesKHR-pFragmentShadingRateCount-parameter
    pFragmentShadingRateCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPhysicalDeviceFragmentShadingRatesKHR-pFragmentShadingRates-parameter
    If the value referenced by pFragmentShadingRateCount is not 0, and pFragmentShadingRates is not NULL, pFragmentShadingRates must be a valid pointer to an array of pFragmentShadingRateCount VkPhysicalDeviceFragmentShadingRateKHR structures

Return Codes
Success
  • VK_SUCCESS

  • VK_INCOMPLETE

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkPhysicalDeviceFragmentShadingRateKHR structure is defined as

// Provided by VK_KHR_fragment_shading_rate
typedef struct VkPhysicalDeviceFragmentShadingRateKHR {
    VkStructureType       sType;
    void*                 pNext;
    VkSampleCountFlags    sampleCounts;
    VkExtent2D            fragmentSize;
} VkPhysicalDeviceFragmentShadingRateKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • sampleCounts is a bitmask of sample counts for which the shading rate described by fragmentSize is supported.

  • fragmentSize is a VkExtent2D describing the width and height of a supported shading rate.

Valid Usage (Implicit)
  • VUID-VkPhysicalDeviceFragmentShadingRateKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_SHADING_RATE_KHR

  • VUID-VkPhysicalDeviceFragmentShadingRateKHR-pNext-pNext
    pNext must be NULL

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

25.5.1. 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 vkCmdSetFragmentShadingRateKHR.

The VkPipelineFragmentShadingRateStateCreateInfoKHR structure is defined as:

// Provided by VK_KHR_fragment_shading_rate
typedef struct VkPipelineFragmentShadingRateStateCreateInfoKHR {
    VkStructureType                       sType;
    const void*                           pNext;
    VkExtent2D                            fragmentSize;
    VkFragmentShadingRateCombinerOpKHR    combinerOps[2];
} VkPipelineFragmentShadingRateStateCreateInfoKHR;

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

If this structure is not present, fragmentSize is considered to be equal to (1,1), and both elements of combinerOps are considered to be equal to VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR.

Valid Usage (Implicit)
  • VUID-VkPipelineFragmentShadingRateStateCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_FRAGMENT_SHADING_RATE_STATE_CREATE_INFO_KHR

To dynamically set the pipeline fragment shading rate and combiner operation, call:

// Provided by VK_KHR_fragment_shading_rate
void vkCmdSetFragmentShadingRateKHR(
    VkCommandBuffer                             commandBuffer,
    const VkExtent2D*                           pFragmentSize,
    const VkFragmentShadingRateCombinerOpKHR    combinerOps[2]);

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

Valid Usage
  • VUID-vkCmdSetFragmentShadingRateKHR-pipelineFragmentShadingRate-04507
    If pipelineFragmentShadingRate is not enabled, pFragmentSize->width must be 1

  • VUID-vkCmdSetFragmentShadingRateKHR-pipelineFragmentShadingRate-04508
    If pipelineFragmentShadingRate is not enabled, pFragmentSize->height must be 1

  • VUID-vkCmdSetFragmentShadingRateKHR-pipelineFragmentShadingRate-04509
    One of pipelineFragmentShadingRate, primitiveFragmentShadingRate, or attachmentFragmentShadingRate must be enabled

  • VUID-vkCmdSetFragmentShadingRateKHR-primitiveFragmentShadingRate-04510
    If the primitiveFragmentShadingRate feature is not enabled, combinerOps[0] must be VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR

  • VUID-vkCmdSetFragmentShadingRateKHR-attachmentFragmentShadingRate-04511
    If the attachmentFragmentShadingRate feature is not enabled, combinerOps[1] must be VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR

  • VUID-vkCmdSetFragmentShadingRateKHR-fragmentSizeNonTrivialCombinerOps-04512
    If the fragmentSizeNonTrivialCombinerOps limit is not supported, elements of combinerOps must be either VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR

  • VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04513
    pFragmentSize->width must be greater than or equal to 1

  • VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04514
    pFragmentSize->height must be greater than or equal to 1

  • VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04515
    pFragmentSize->width must be a power-of-two value

  • VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04516
    pFragmentSize->height must be a power-of-two value

  • VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04517
    pFragmentSize->width must be less than or equal to 4

  • VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-04518
    pFragmentSize->height must be less than or equal to 4

Valid Usage (Implicit)
  • VUID-vkCmdSetFragmentShadingRateKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetFragmentShadingRateKHR-pFragmentSize-parameter
    pFragmentSize must be a valid pointer to a valid VkExtent2D structure

  • VUID-vkCmdSetFragmentShadingRateKHR-combinerOps-parameter
    Each element of combinerOps must be a valid VkFragmentShadingRateCombinerOpKHR value

  • VUID-vkCmdSetFragmentShadingRateKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetFragmentShadingRateKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetFragmentShadingRateKHR-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

25.5.2. Primitive Fragment Shading Rate

The primitive fragment shading rate can be set via the PrimitiveShadingRateKHR built-in in the last active pre-rasterization shader stage. The rate associated with a given primitive is sourced from the value written to PrimitiveShadingRateKHR by that primitive’s provoking vertex.

25.5.3. Attachment Fragment Shading Rate

The attachment shading rate can be set by including 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:

x' = floor(x / regionx)

y' = floor(y / regiony)

where x' and y' are the coordinates of a texel in the fragment shading rate attachment, x and y are the coordinates of the pixel in the framebuffer, and regionx and regiony are the size of the region each texel corresponds to, as defined by the shadingRateAttachmentTexelSize member of VkFragmentShadingRateAttachmentInfoKHR.

If multiview is enabled and the shading rate attachment has multiple layers, the shading rate attachment texel is selected from the layer determined by the ViewIndex built-in. If 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 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:

sizew = 2((texel/4)&3)

sizeh = 2(texel&3)

where texel is the value in the first component of the identified texel, and sizew and sizeh 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 sizew = sizeh = 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.

25.5.4. Combining the Fragment Shading Rates

The final rate (Cxy') used for fragment shading must be one of the rates returned by vkGetPhysicalDeviceFragmentShadingRatesKHR for the sample count used by rasterization.

If any of the following conditions are met, Cxy' must be set to {1,1}:

Otherwise, each of the specified shading rates are combined and then used to derive the value of Cxy'. As there are three ways to specify shading rates, two combiner operations are specified - between the pipeline and primitive shading rates, and between the result of that and the attachment shading rate.

The equation used for each combiner operation is defined by VkFragmentShadingRateCombinerOpKHR:

// Provided by VK_KHR_fragment_shading_rate
typedef enum VkFragmentShadingRateCombinerOpKHR {
    VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR = 0,
    VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR = 1,
    VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR = 2,
    VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR = 3,
    VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR = 4,
} VkFragmentShadingRateCombinerOpKHR;
  • VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR specifies a combiner operation of combine(Axy,Bxy) = Axy.

  • VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR specifies a combiner operation of combine(Axy,Bxy) = Bxy.

  • VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MIN_KHR specifies a combiner operation of combine(Axy,Bxy) = min(Axy,Bxy).

  • VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MAX_KHR specifies a combiner operation of combine(Axy,Bxy) = max(Axy,Bxy).

  • VK_FRAGMENT_SHADING_RATE_COMBINER_OP_MUL_KHR specifies a combiner operation of combine(Axy,Bxy) = Axy*Bxy.

where combine(Axy,Bxy) is the combine operation, and Axy and Bxy are the inputs to the operation.

If fragmentShadingRateStrictMultiplyCombiner is VK_FALSE, using 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 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:

Cxy = combine(Axy,Bxy)

where Cxy is the combined fragment area result, and Axy and Bxy are the fragment areas of the fragment shading rates being combined.

Two combine operations are performed, first with Axy equal to the pipeline fragment shading rate and Bxy equal to the primitive fragment shading rate, with the combine() operation selected by combinerOps[0]. A second combination is then performed, with Axy equal to the result of the first combination and Bxy equal to the attachment fragment shading rate, with the combine() operation selected by combinerOps[1]. The result of the second combination is used as the final fragment shading rate, reported via the ShadingRateKHR built-in.

Implementations should clamp the inputs to the combiner operations Axy and Bxy, and must do so if VkPhysicalDeviceMaintenance6PropertiesKHR::fragmentShadingRateClampCombinerInputs is set to VK_TRUE. All implementations must clamp the result of the second combiner operation.

A fragment shading rate Rxy representing any of Axy, Bxy or Cxy is clamped as follows. If Rxy is one of the rates returned by vkGetPhysicalDeviceFragmentShadingRatesKHR for the sample count used by rasterization, the clamped shading rate Rxy' is Rxy. Otherwise, the clamped shading rate is selected from the rates returned by vkGetPhysicalDeviceFragmentShadingRatesKHR for the sample count used by rasterization. From this list of supported rates, the following steps are applied in order, to select a single value:

  1. Keep only rates where Rx' ≤ Rx and Ry' ≤ Ry.

    • Implementations may also keep rates where Rx' ≤ Ry and Ry' ≤ Rx.

  2. Keep only rates with the highest area (Rx' × Ry').

  3. Keep only rates with the lowest aspect ratio (Rx' + Ry').

  4. 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, and combiner operations for the lifetime of the VkDevice.

25.6. 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 max(⌈ VkPipelineMultisampleStateCreateInfo::minSampleShading × VkPipelineMultisampleStateCreateInfo::rasterizationSamples ⌉, 1) times per fragment. If VkPipelineMultisampleStateCreateInfo::sampleShadingEnable is set to VK_TRUE, sample shading is enabled.

If a fragment shader entry point statically uses an input variable decorated with a BuiltIn of SampleId or SamplePosition, sample shading is enabled and a value of 1.0 is used instead of minSampleShading. If a fragment shader entry point statically uses an input variable decorated with Sample, sample shading may be enabled and a value of 1.0 will be used instead of minSampleShading if it is.

Note

If a shader decorates an input variable with 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 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 helper invocation covers at least one sample.

25.7. Barycentric Interpolation

When the fragmentShaderBarycentric feature is enabled, the PerVertexKHR 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.

When tessellation and geometry shading are not active, fragment shader inputs decorated with 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 for index values of 0, 1, and 2. If an input decorated with PerVertexKHR is accessed with any other vertex index value, or is accessed while rasterizing a polygon when the VkPipelineRasterizationStateCreateInfo::polygonMode property of the currently active pipeline is not VK_POLYGON_MODE_FILL, an undefined value is returned.

Primitive Topology Vertex 0 Vertex 1 Vertex 2

VK_PRIMITIVE_TOPOLOGY_POINT_LIST

i

i

i

VK_PRIMITIVE_TOPOLOGY_LINE_LIST

2i

2i+1

2i+1

VK_PRIMITIVE_TOPOLOGY_LINE_STRIP

i

i+1

i+1

VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST

3i

3i+1

3i+2

VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP (even)

i

i+1

i+2

VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP (odd)

i

i+2

i+1

VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN

i+1

i+2

0

VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY

4i+1

4i+2

4i+2

VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY

i+1

i+2

i+2

VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY

6i

6i+2

6i+4

VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY (even)

2i

2i+2

2i+4

VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY (odd)

2i

2i+4

2i+2

When geometry shading is active, primitives processed by fragment shaders are assembled from the vertices emitted by the geometry shader. In this case, the vertices used for fragment shader inputs decorated with PerVertexKHR are derived by treating the primitives produced by the shader as though they were specified by a draw call and consulting 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 PerVertexKHR, the vertex ordering used in this case will be consistent with the ordering used to derive the values of inputs decorated with BaryCoordKHR or BaryCoordNoPerspKHR.

Fragment shader inputs decorated with BaryCoordKHR or 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 (1,0,0). For line primitives, the built-ins are obtained by interpolating an attribute whose values for the vertices numbered 0 and 1 are (1,0,0) and (0,1,0), respectively. For polygon primitives, the built-ins are obtained by interpolating an attribute whose values for the vertices numbered 0, 1, and 2 are (1,0,0), (0,1,0), and (0,0,1), respectively. For BaryCoordKHR, the values are obtained using perspective interpolation. For BaryCoordNoPerspKHR, the values are obtained using linear interpolation. The values of BaryCoordKHR and BaryCoordNoPerspKHR are undefined while rasterizing a polygon when the VkPipelineRasterizationStateCreateInfo::polygonMode property of the currently active pipeline is not VK_POLYGON_MODE_FILL.

25.8. 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 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 [pointSizeRange[0],pointSizeRange[1]]. The value written to PointSize must be greater than zero. If maintenance5 is enabled, and a value is not written to PointSize, the point size takes a default value of 1.0.

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 pointSizeRange and pointSizeGranularity members of 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.

25.8.1. 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 (xf,yf). 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 PointCoord contains point sprite texture coordinates. The s and 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 s and t:

where size is the point’s size; (xp,yp) 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 (xf,yf) is the exact, unrounded framebuffer coordinate of the vertex for the point.

25.9. Line Segments

Line segment rasterization options are controlled by the VkPipelineRasterizationLineStateCreateInfoKHR structure.

The VkPipelineRasterizationLineStateCreateInfoKHR structure is defined as:

// Provided by VK_KHR_line_rasterization
typedef struct VkPipelineRasterizationLineStateCreateInfoKHR {
    VkStructureType               sType;
    const void*                   pNext;
    VkLineRasterizationModeKHR    lineRasterizationMode;
    VkBool32                      stippledLineEnable;
    uint32_t                      lineStippleFactor;
    uint16_t                      lineStipplePattern;
} VkPipelineRasterizationLineStateCreateInfoKHR;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • lineRasterizationMode is a VkLineRasterizationModeKHR value selecting the style of line rasterization.

  • stippledLineEnable enables stippled line rasterization.

  • lineStippleFactor is the repeat factor used in stippled line rasterization.

  • lineStipplePattern is the bit pattern used in stippled line rasterization.

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

Valid Usage
  • VUID-VkPipelineRasterizationLineStateCreateInfoKHR-lineRasterizationMode-02768
    If lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR, then the rectangularLines feature must be enabled

  • VUID-VkPipelineRasterizationLineStateCreateInfoKHR-lineRasterizationMode-02769
    If lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_BRESENHAM_KHR, then the bresenhamLines feature must be enabled

  • VUID-VkPipelineRasterizationLineStateCreateInfoKHR-lineRasterizationMode-02770
    If lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_KHR, then the smoothLines feature must be enabled

  • VUID-VkPipelineRasterizationLineStateCreateInfoKHR-stippledLineEnable-02771
    If stippledLineEnable is VK_TRUE and lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR, then the stippledRectangularLines feature must be enabled

  • VUID-VkPipelineRasterizationLineStateCreateInfoKHR-stippledLineEnable-02772
    If stippledLineEnable is VK_TRUE and lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_BRESENHAM_KHR, then the stippledBresenhamLines feature must be enabled

  • VUID-VkPipelineRasterizationLineStateCreateInfoKHR-stippledLineEnable-02773
    If stippledLineEnable is VK_TRUE and lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_KHR, then the stippledSmoothLines feature must be enabled

  • VUID-VkPipelineRasterizationLineStateCreateInfoKHR-stippledLineEnable-02774
    If stippledLineEnable is VK_TRUE and lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_DEFAULT_KHR, then the stippledRectangularLines feature must be enabled and VkPhysicalDeviceLimits::strictLines must be VK_TRUE

Valid Usage (Implicit)
  • VUID-VkPipelineRasterizationLineStateCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_LINE_STATE_CREATE_INFO_KHR

  • VUID-VkPipelineRasterizationLineStateCreateInfoKHR-lineRasterizationMode-parameter
    lineRasterizationMode must be a valid VkLineRasterizationModeKHR value

Possible values of VkPipelineRasterizationLineStateCreateInfoKHR::lineRasterizationMode are:

// Provided by VK_KHR_line_rasterization
typedef enum VkLineRasterizationModeKHR {
    VK_LINE_RASTERIZATION_MODE_DEFAULT_KHR = 0,
    VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR = 1,
    VK_LINE_RASTERIZATION_MODE_BRESENHAM_KHR = 2,
    VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_KHR = 3,
    VK_LINE_RASTERIZATION_MODE_DEFAULT_EXT = VK_LINE_RASTERIZATION_MODE_DEFAULT_KHR,
    VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT = VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR,
    VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT = VK_LINE_RASTERIZATION_MODE_BRESENHAM_KHR,
    VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT = VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_KHR,
} VkLineRasterizationModeKHR;
  • VK_LINE_RASTERIZATION_MODE_DEFAULT_KHR is equivalent to VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR if VkPhysicalDeviceLimits::strictLines is VK_TRUE, otherwise lines are drawn as non-strictLines parallelograms. Both of these modes are defined in Basic Line Segment Rasterization.

  • VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR specifies lines drawn as if they were rectangles extruded from the line

  • VK_LINE_RASTERIZATION_MODE_BRESENHAM_KHR specifies lines drawn by determining which pixel diamonds the line intersects and exits, as defined in Bresenham Line Segment Rasterization.

  • VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_KHR specifies lines drawn if they were rectangles extruded from the line, with alpha falloff, as defined in Smooth Lines.

To dynamically set the lineRasterizationMode state, call:

// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_line_rasterization, VK_EXT_line_rasterization with VK_EXT_shader_object
void vkCmdSetLineRasterizationModeEXT(
    VkCommandBuffer                             commandBuffer,
    VkLineRasterizationModeEXT                  lineRasterizationMode);
  • commandBuffer is the command buffer into which the command will be recorded.

  • lineRasterizationMode specifies the lineRasterizationMode state.

This command sets the lineRasterizationMode state for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineRasterizationLineStateCreateInfoKHR::lineRasterizationMode value used to create the currently active pipeline.

Valid Usage
  • VUID-vkCmdSetLineRasterizationModeEXT-None-09423
    At least one of the following must be true:

  • VUID-vkCmdSetLineRasterizationModeEXT-lineRasterizationMode-07418
    If lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR, then the rectangularLines feature must be enabled

  • VUID-vkCmdSetLineRasterizationModeEXT-lineRasterizationMode-07419
    If lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_BRESENHAM_KHR, then the bresenhamLines feature must be enabled

  • VUID-vkCmdSetLineRasterizationModeEXT-lineRasterizationMode-07420
    If lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_KHR, then the smoothLines feature must be enabled

Valid Usage (Implicit)
  • VUID-vkCmdSetLineRasterizationModeEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetLineRasterizationModeEXT-lineRasterizationMode-parameter
    lineRasterizationMode must be a valid VkLineRasterizationModeEXT value

  • VUID-vkCmdSetLineRasterizationModeEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetLineRasterizationModeEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetLineRasterizationModeEXT-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

To dynamically set the stippledLineEnable state, call:

// Provided by VK_EXT_extended_dynamic_state3 with VK_EXT_line_rasterization, VK_EXT_line_rasterization with VK_EXT_shader_object
void vkCmdSetLineStippleEnableEXT(
    VkCommandBuffer                             commandBuffer,
    VkBool32                                    stippledLineEnable);
  • commandBuffer is the command buffer into which the command will be recorded.

  • stippledLineEnable specifies the stippledLineEnable state.

This command sets the stippledLineEnable state for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineRasterizationLineStateCreateInfoKHR::stippledLineEnable value used to create the currently active pipeline.

Valid Usage
Valid Usage (Implicit)
  • VUID-vkCmdSetLineStippleEnableEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetLineStippleEnableEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetLineStippleEnableEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetLineStippleEnableEXT-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

To dynamically set the line width, call:

// Provided by VK_VERSION_1_0
void vkCmdSetLineWidth(
    VkCommandBuffer                             commandBuffer,
    float                                       lineWidth);
  • commandBuffer is the command buffer into which the command will be recorded.

  • lineWidth is the width of rasterized line segments.

This command sets the line width for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_LINE_WIDTH set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineRasterizationStateCreateInfo::lineWidth value used to create the currently active pipeline.

Valid Usage
  • VUID-vkCmdSetLineWidth-lineWidth-00788
    If the wideLines feature is not enabled, lineWidth must be 1.0

Valid Usage (Implicit)
  • VUID-vkCmdSetLineWidth-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetLineWidth-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetLineWidth-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetLineWidth-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

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 lineWidthRange and lineWidthGranularity members of 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.

25.9.1. Basic Line Segment Rasterization

If the lineRasterizationMode member of VkPipelineRasterizationLineStateCreateInfoKHR is VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR, rasterized 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 pr = (xd, yd) 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 rasterizationSamples is VK_SAMPLE_COUNT_1_BIT, the fragment center must be used. Let pa = (xa, ya) and pb = (xb,yb) be initial and final endpoints of the line segment, respectively. Set

(Note that t = 0 at pa and t = 1 at pb. Also note that this calculation projects the vector from pa to pr onto the line, and thus computes the normalized distance of the fragment along the line.)

If strictLines is VK_TRUE, line segments are rasterized using perspective or linear 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 f can be determined by

where fa and fb are the data associated with the starting and ending endpoints of the segment, respectively; wa and wb are the clip w coordinates of the starting and ending endpoints of the segment, respectively.

Linear interpolation for a line segment directly interpolates two values, and an interpolated value f can be determined by

f = (1 - t) fa + t fb

where fa and fb are the data associated with the starting and ending endpoints of the segment, respectively.

The clip coordinate w for a sample is determined using perspective interpolation. The depth value z for a sample is determined using linear interpolation. Interpolation of fragment shader input values are determined by Interpolation decorations.

The above description documents the preferred method of line rasterization, and must be used when lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR.

By default, when strictLines is VK_FALSE, and when the lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_DEFAULT_KHR, 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 Non strict lines, and each is 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.

image/svg+xml Edge 0 Edge 1 Edge 3 Edge 2 OriginalLine (Xb,Yb,Zb) (Xa,Ya,Za) LineWidth
Figure 15. Non strict lines

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

If VkPhysicalDeviceMaintenance5PropertiesKHR::nonStrictSinglePixelWideLinesUseParallelogram is VK_TRUE, and strictLines is VK_FALSE, non-strict lines of width 1.0 are rasterized as parallelograms, otherwise they are rasterized using Bresenham’s algorithm.

If VkPhysicalDeviceMaintenance5PropertiesKHR::nonStrictWideLinesUseParallelogram is VK_TRUE, and strictLines is VK_FALSE, non-strict lines of width greater than 1.0 are rasterized as parallelograms, otherwise they are rasterized using Bresenham’s algorithm.

25.9.2. Bresenham Line Segment Rasterization

If lineRasterizationMode is VK_LINE_RASTERIZATION_MODE_BRESENHAM_KHR, then the following rules replace the line rasterization rules defined in Basic Line Segment 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 [-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 f with center at framebuffer coordinates xf and yf, define a diamond-shaped region that is the intersection of four half planes:

Essentially, a line segment starting at pa and ending at pb produces those fragments f for which the segment intersects Rf, except if pb is contained in Rf.

image/svg+xml
Figure 16. Visualization of Bresenham’s algorithm

To avoid difficulties when an endpoint lies on a boundary of Rf we (in principle) perturb the supplied endpoints by a tiny amount. Let pa and pb have framebuffer coordinates (xa, ya) and (xb, yb), respectively. Obtain the perturbed endpoints pa' given by (xa, ya) - (ε, ε2) and pb' given by (xb, yb) - (ε, ε2). Rasterizing the line segment starting at pa and ending at pb produces those fragments f for which the segment starting at pa' and ending on pb' intersects Rf, except if pb' is contained in Rf. ε is chosen to be so small that rasterizing the line segment produces the same fragments when δ is substituted for ε for any 0 < δ ≤ ε.

When pa and pb 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 pb) 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 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 w of Bresenham lines is determined by rounding the line width to the nearest integer, clamping it to the implementation-dependent 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 (x0, y0) and (x1, y1) in framebuffer coordinates, the segment with endpoints and 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 FragCoord which is interpolated as usual. Implementations may instead interpolate each fragment according to the formula in 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

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).

25.9.3. Line Stipple

If the stippledLineEnable member of VkPipelineRasterizationLineStateCreateInfoKHR is VK_TRUE, then lines are rasterized with a line stipple determined by lineStippleFactor and lineStipplePattern. lineStipplePattern is an unsigned 16-bit integer that determines which fragments are to be drawn or discarded when the line is rasterized. lineStippleFactor is a count that is used to modify the effective line stipple by causing each bit in lineStipplePattern to be used 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

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 VK_LINE_RASTERIZATION_MODE_BRESENHAM_KHR 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 VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR and VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_KHR 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.

To dynamically set the line stipple state, call:

// Provided by VK_KHR_line_rasterization
void vkCmdSetLineStippleKHR(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    lineStippleFactor,
    uint16_t                                    lineStipplePattern);
  • commandBuffer is the command buffer into which the command will be recorded.

  • lineStippleFactor is the repeat factor used in stippled line rasterization.

  • lineStipplePattern is the bit pattern used in stippled line rasterization.

This command sets the line stipple state for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_LINE_STIPPLE_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineRasterizationLineStateCreateInfoKHR::lineStippleFactor and VkPipelineRasterizationLineStateCreateInfoKHR::lineStipplePattern values used to create the currently active pipeline.

Valid Usage
  • VUID-vkCmdSetLineStippleKHR-lineStippleFactor-02776
    lineStippleFactor must be in the range [1,256]

Valid Usage (Implicit)
  • VUID-vkCmdSetLineStippleKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetLineStippleKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetLineStippleKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetLineStippleKHR-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

25.9.4. Smooth Lines

If the lineRasterizationMode member of VkPipelineRasterizationLineStateCreateInfoKHR is VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_KHR, then lines are considered to be rectangles using the same geometry as for VK_LINE_RASTERIZATION_MODE_RECTANGULAR_KHR 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 Multisample Coverage.

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.

25.10. 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 VkPipelineRasterizationStateCreateInfo structure.

25.10.1. Basic Polygon Rasterization

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:

where and are the x and y framebuffer coordinates of the ith vertex of the n-vertex polygon (vertices are numbered starting at zero for the purposes of this computation) and i ⊕ 1 is (i + 1) mod n.

The interpretation of the sign of a is determined by the VkPipelineRasterizationStateCreateInfo::frontFace property of the currently active pipeline. Possible values are:

// Provided by VK_VERSION_1_0
typedef enum VkFrontFace {
    VK_FRONT_FACE_COUNTER_CLOCKWISE = 0,
    VK_FRONT_FACE_CLOCKWISE = 1,
} VkFrontFace;
  • VK_FRONT_FACE_COUNTER_CLOCKWISE specifies that a triangle with positive area is considered front-facing.

  • 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.

To dynamically set the front face orientation, call:

// Provided by VK_VERSION_1_3
void vkCmdSetFrontFace(
    VkCommandBuffer                             commandBuffer,
    VkFrontFace                                 frontFace);

or the equivalent command

// Provided by VK_EXT_shader_object
void vkCmdSetFrontFaceEXT(
    VkCommandBuffer                             commandBuffer,
    VkFrontFace                                 frontFace);
  • commandBuffer is the command buffer into which the command will be recorded.

  • frontFace is a VkFrontFace value specifying the front-facing triangle orientation to be used for culling.

This command sets the front face orientation for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_FRONT_FACE set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineRasterizationStateCreateInfo::frontFace value used to create the currently active pipeline.

Valid Usage
  • VUID-vkCmdSetFrontFace-None-08971
    At least one of the following must be true:

Valid Usage (Implicit)
  • VUID-vkCmdSetFrontFace-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetFrontFace-frontFace-parameter
    frontFace must be a valid VkFrontFace value

  • VUID-vkCmdSetFrontFace-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetFrontFace-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetFrontFace-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

Once the orientation of triangles is determined, they are culled according to the VkPipelineRasterizationStateCreateInfo::cullMode property of the currently active pipeline. Possible values are:

// Provided by VK_VERSION_1_0
typedef enum VkCullModeFlagBits {
    VK_CULL_MODE_NONE = 0,
    VK_CULL_MODE_FRONT_BIT = 0x00000001,
    VK_CULL_MODE_BACK_BIT = 0x00000002,
    VK_CULL_MODE_FRONT_AND_BACK = 0x00000003,
} VkCullModeFlagBits;
  • VK_CULL_MODE_NONE specifies that no triangles are discarded

  • VK_CULL_MODE_FRONT_BIT specifies that front-facing triangles are discarded

  • VK_CULL_MODE_BACK_BIT specifies that back-facing triangles are discarded

  • 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.

// Provided by VK_VERSION_1_0
typedef VkFlags VkCullModeFlags;

VkCullModeFlags is a bitmask type for setting a mask of zero or more VkCullModeFlagBits.

To dynamically set the cull mode, call:

// Provided by VK_VERSION_1_3
void vkCmdSetCullMode(
    VkCommandBuffer                             commandBuffer,
    VkCullModeFlags                             cullMode);

or the equivalent command

// Provided by VK_EXT_shader_object
void vkCmdSetCullModeEXT(
    VkCommandBuffer                             commandBuffer,
    VkCullModeFlags                             cullMode);
  • commandBuffer is the command buffer into which the command will be recorded.

  • cullMode specifies the cull mode property to use for drawing.

This command sets the cull mode for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_CULL_MODE set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineRasterizationStateCreateInfo::cullMode value used to create the currently active pipeline.

Valid Usage
  • VUID-vkCmdSetCullMode-None-08971
    At least one of the following must be true:

Valid Usage (Implicit)
  • VUID-vkCmdSetCullMode-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetCullMode-cullMode-parameter
    cullMode must be a valid combination of VkCullModeFlagBits values

  • VUID-vkCmdSetCullMode-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetCullMode-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetCullMode-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

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.

Barycentric coordinates are a set of three numbers, a, b, and c, each in the range [0,1], with a + b + c = 1. These coordinates uniquely specify any point p within the triangle or on the triangle’s boundary as

p = a pa + b pb + c pc

where pa, pb, and pc are the vertices of the triangle. a, b, and c are determined by:

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

Denote an associated datum at pa, pb, or pc as fa, fb, or fc, respectively.

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 f can be determined by

where wa, wb, and wc are the clip w coordinates of pa, pb, and pc, respectively. a, b, and c are the barycentric coordinates of the location at which the data are produced.

Linear interpolation for a triangle directly interpolates three values, and an interpolated value f can be determined by

f = a fa + b fb + c fc

where fa, fb, and fc are the data associated with pa, pb, and pc, respectively.

The clip coordinate w for a sample is determined using perspective interpolation. The depth value z for a sample is determined using linear interpolation. Interpolation of fragment shader input values are determined by 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

where n is the number of vertices in the polygon and fi is the value of f at vertex i. For each i, 0 ≤ ai ≤ 1 and . The values of ai may differ from fragment to fragment, but at vertex i, ai = 1 and aj = 0 for j ≠ i.

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 perspective interpolation are iterated independently, and a division is performed for each fragment).

25.10.2. Polygon Mode

Possible values of the VkPipelineRasterizationStateCreateInfo::polygonMode property of the currently active pipeline, specifying the method of rasterization for polygons, are:

// Provided by VK_VERSION_1_0
typedef enum VkPolygonMode {
    VK_POLYGON_MODE_FILL = 0,
    VK_POLYGON_MODE_LINE = 1,
    VK_POLYGON_MODE_POINT = 2,
} VkPolygonMode;
  • VK_POLYGON_MODE_POINT specifies that polygon vertices are drawn as points.

  • VK_POLYGON_MODE_LINE specifies that polygon edges are drawn as line segments.

  • VK_POLYGON_MODE_FILL specifies that polygons are rendered using the polygon rasterization rules in this section.

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.

If VkPhysicalDeviceMaintenance5PropertiesKHR::polygonModePointSize is set to VK_TRUE, the point size of the final rasterization of polygons is taken from PointSize when polygon mode is VK_POLYGON_MODE_POINT.

Otherwise, if VkPhysicalDeviceMaintenance5PropertiesKHR::polygonModePointSize is set to VK_FALSE, the point size of the final rasterization of polygons is 1.0 when polygon mode is VK_POLYGON_MODE_POINT.

To dynamically set the polygon mode, call:

// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetPolygonModeEXT(
    VkCommandBuffer                             commandBuffer,
    VkPolygonMode                               polygonMode);
  • commandBuffer is the command buffer into which the command will be recorded.

  • polygonMode specifies polygon mode.

This command sets the polygon mode for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_POLYGON_MODE_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineRasterizationStateCreateInfo::polygonMode value used to create the currently active pipeline.

Valid Usage
  • VUID-vkCmdSetPolygonModeEXT-None-09423
    At least one of the following must be true:

  • VUID-vkCmdSetPolygonModeEXT-fillModeNonSolid-07424
    If the fillModeNonSolid feature is not enabled, polygonMode must be VK_POLYGON_MODE_FILL

Valid Usage (Implicit)
  • VUID-vkCmdSetPolygonModeEXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetPolygonModeEXT-polygonMode-parameter
    polygonMode must be a valid VkPolygonMode value

  • VUID-vkCmdSetPolygonModeEXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetPolygonModeEXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetPolygonModeEXT-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

25.10.3. 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 that is computed for that polygon.

Depth Bias Enable

The depth bias computation is enabled by the depthBiasEnable set with vkCmdSetDepthBiasEnable or the corresponding VkPipelineRasterizationStateCreateInfo::depthBiasEnable value used to create the currently active pipeline. If the depth bias enable is VK_FALSE, no bias is applied and the fragment’s depth values are unchanged.

To dynamically enable whether to bias fragment depth values, call:

// Provided by VK_VERSION_1_3
void vkCmdSetDepthBiasEnable(
    VkCommandBuffer                             commandBuffer,
    VkBool32                                    depthBiasEnable);

or the equivalent command

// Provided by VK_EXT_shader_object
void vkCmdSetDepthBiasEnableEXT(
    VkCommandBuffer                             commandBuffer,
    VkBool32                                    depthBiasEnable);
  • commandBuffer is the command buffer into which the command will be recorded.

  • depthBiasEnable controls whether to bias fragment depth values.

This command sets the depth bias enable for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineRasterizationStateCreateInfo::depthBiasEnable value used to create the currently active pipeline.

Valid Usage
  • VUID-vkCmdSetDepthBiasEnable-None-08970
    At least one of the following must be true:

Valid Usage (Implicit)
  • VUID-vkCmdSetDepthBiasEnable-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetDepthBiasEnable-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetDepthBiasEnable-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetDepthBiasEnable-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

Depth Bias Computation

The depth bias depends on three parameters:

  • depthBiasSlopeFactor scales the maximum depth slope m of the polygon

  • depthBiasConstantFactor scales the parameter 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 depthBiasClamp

depthBiasSlopeFactor, depthBiasConstantFactor, and depthBiasClamp can each be positive, negative, or zero. These parameters are set as described for vkCmdSetDepthBias and vkCmdSetDepthBias2EXT below.

The maximum depth slope m of a triangle is

where (xf, yf, zf) is a point on the triangle. m may be approximated as

In a pipeline with a depth bias representation of VK_DEPTH_BIAS_REPRESENTATION_FLOAT_EXT, r, for the given primitive is defined as

r = 1

Otherwise r is the minimum resolvable difference that depends on the depth attachment representation. If VkDepthBiasRepresentationInfoEXT::depthBiasExact is VK_FALSE it is the smallest difference in framebuffer coordinate 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 zf values that differ by r, will have distinct depth values.

For fixed-point depth attachment representations, or in a pipeline with a depth bias representation of VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORCE_UNORM_EXT, r is constant throughout the range of the entire depth attachment. If VkDepthBiasRepresentationInfoEXT::depthBiasExact is VK_TRUE, then its value must be

r = 2-n

Otherwise its value is implementation-dependent but must be at most

r = 2 × 2-n

where n is the number of bits used for the depth aspect when using a fixed-point attachment, or the number of mantissa bits plus one when using a floating-point attachment.

Otherwise 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, e, in the range of z values spanned by the primitive. If n is the number of bits in the floating-point mantissa, the minimum resolvable difference, r, for the given primitive is defined as

r = 2e-n

If no depth attachment is present, r is undefined.

The bias value o for a polygon is

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

Depth bias is applied to triangle topology primitives received by the rasterizer regardless of polygon mode. Depth bias may also be applied to line and point topology primitives received by the rasterizer.

To dynamically set the depth bias parameters, call:

// Provided by VK_VERSION_1_0
void vkCmdSetDepthBias(
    VkCommandBuffer                             commandBuffer,
    float                                       depthBiasConstantFactor,
    float                                       depthBiasClamp,
    float                                       depthBiasSlopeFactor);
  • commandBuffer is the command buffer into which the command will be recorded.

  • depthBiasConstantFactor is a scalar factor controlling the constant depth value added to each fragment.

  • depthBiasClamp is the maximum (or minimum) depth bias of a fragment.

  • 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 when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_DEPTH_BIAS set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the corresponding VkPipelineRasterizationStateCreateInfo::depthBiasConstantFactor, depthBiasClamp, and depthBiasSlopeFactor values used to create the currently active pipeline.

Calling this function is equivalent to calling vkCmdSetDepthBias2EXT without a VkDepthBiasRepresentationInfoEXT in the pNext chain of VkDepthBiasInfoEXT.

Valid Usage
  • VUID-vkCmdSetDepthBias-depthBiasClamp-00790
    If the depthBiasClamp feature is not enabled, depthBiasClamp must be 0.0

Valid Usage (Implicit)
  • VUID-vkCmdSetDepthBias-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetDepthBias-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetDepthBias-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetDepthBias-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State

The VkDepthBiasRepresentationInfoEXT structure is defined as:

// Provided by VK_EXT_depth_bias_control
typedef struct VkDepthBiasRepresentationInfoEXT {
    VkStructureType                 sType;
    const void*                     pNext;
    VkDepthBiasRepresentationEXT    depthBiasRepresentation;
    VkBool32                        depthBiasExact;
} VkDepthBiasRepresentationInfoEXT;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • depthBiasRepresentation is a VkDepthBiasRepresentationEXT value specifying the depth bias representation.

  • 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 leastRepresentableValueForceUnormRepresentation feature is not enabled, depthBiasRepresentation must not be VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORCE_UNORM_EXT

  • VUID-VkDepthBiasRepresentationInfoEXT-floatRepresentation-08948
    If the floatRepresentation feature is not enabled, depthBiasRepresentation must not be VK_DEPTH_BIAS_REPRESENTATION_FLOAT_EXT

  • VUID-VkDepthBiasRepresentationInfoEXT-depthBiasExact-08949
    If the depthBiasExact feature is not enabled, depthBiasExact must be VK_FALSE

Valid Usage (Implicit)
  • VUID-VkDepthBiasRepresentationInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEPTH_BIAS_REPRESENTATION_INFO_EXT

  • VUID-VkDepthBiasRepresentationInfoEXT-depthBiasRepresentation-parameter
    depthBiasRepresentation must be a valid VkDepthBiasRepresentationEXT value

Possible values of VkDepthBiasRepresentationInfoEXT::depthBiasRepresentation, specifying the depth bias representation are:

// Provided by VK_EXT_depth_bias_control
typedef enum VkDepthBiasRepresentationEXT {
    VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORMAT_EXT = 0,
    VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORCE_UNORM_EXT = 1,
    VK_DEPTH_BIAS_REPRESENTATION_FLOAT_EXT = 2,
} VkDepthBiasRepresentationEXT;
  • VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORMAT_EXT specifies that the depth bias representation is a factor of the format’s r as described in Depth Bias Computation.

  • VK_DEPTH_BIAS_REPRESENTATION_LEAST_REPRESENTABLE_VALUE_FORCE_UNORM_EXT specifies that the depth bias representation is a factor of a constant r defined by the bit-size or mantissa of the format as described in Depth Bias Computation.

  • VK_DEPTH_BIAS_REPRESENTATION_FLOAT_EXT specifies that the depth bias representation is a factor of constant r equal to 1.

The VkDepthBiasInfoEXT structure is defined as:

// Provided by VK_EXT_depth_bias_control
typedef struct VkDepthBiasInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    float              depthBiasConstantFactor;
    float              depthBiasClamp;
    float              depthBiasSlopeFactor;
} VkDepthBiasInfoEXT;
  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • depthBiasConstantFactor is a scalar factor controlling the constant depth value added to each fragment.

  • depthBiasClamp is the maximum (or minimum) depth bias of a fragment.

  • depthBiasSlopeFactor is a scalar factor applied to a fragment’s slope in depth bias calculations.

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

Valid Usage
  • VUID-VkDepthBiasInfoEXT-depthBiasClamp-08950
    If the depthBiasClamp feature is not enabled, depthBiasClamp must be 0.0

Valid Usage (Implicit)
  • VUID-VkDepthBiasInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEPTH_BIAS_INFO_EXT

  • VUID-VkDepthBiasInfoEXT-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkDepthBiasRepresentationInfoEXT

  • VUID-VkDepthBiasInfoEXT-sType-unique
    The sType value of each struct in the pNext chain must be unique

To dynamically set the depth bias parameters, call:

// Provided by VK_EXT_depth_bias_control
void vkCmdSetDepthBias2EXT(
    VkCommandBuffer                             commandBuffer,
    const VkDepthBiasInfoEXT*                   pDepthBiasInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pDepthBiasInfo is a pointer to a VkDepthBiasInfoEXT structure specifying depth bias parameters.

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

Valid Usage (Implicit)
  • VUID-vkCmdSetDepthBias2EXT-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdSetDepthBias2EXT-pDepthBiasInfo-parameter
    pDepthBiasInfo must be a valid pointer to a valid VkDepthBiasInfoEXT structure

  • VUID-vkCmdSetDepthBias2EXT-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdSetDepthBias2EXT-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdSetDepthBias2EXT-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Graphics

State