24. Rasterization

Rasterization is the process by which a primitive is converted to a two-dimensional image. Each point 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 the type of 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. Enabling depth clamp will also disable clipping primitives to the z planes of the frustrum as described in Primitive Clipping.

  • 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 depth clamping feature is not enabled, depthClampEnable must be VK_FALSE

  • VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-01413
    If the non-solid fill modes feature is not enabled, polygonMode must be VK_POLYGON_MODE_FILL

Valid Usage (Implicit)
  • VUID-VkPipelineRasterizationStateCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_CREATE_INFO

  • VUID-VkPipelineRasterizationStateCreateInfo-pNext-pNext
    pNext must be NULL

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

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

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

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

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

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 the type of this structure.

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

  • flags is reserved for future use.

  • rasterizationSamples is a VkSampleCountFlagBits specifying the number of samples used in rasterization.

  • 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 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 sample rate shading feature is not enabled, sampleShadingEnable must be VK_FALSE

  • VUID-VkPipelineMultisampleStateCreateInfo-alphaToOneEnable-00785
    If the alpha to one 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.

When the VK_AMD_mixed_attachment_samples and VK_NV_framebuffer_mixed_samples extensions are not enabled, if the subpass for which this pipeline is being created uses color and/or depth/stencil attachments, then rasterizationSamples must be the same as the sample count for those subpass attachments.

If the subpass for which this pipeline is being created does not use color or depth/stencil attachments, rasterizationSamples must follow the rules for a zero-attachment subpass.

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

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

Each operation is atomically executed for each primitive and sample location.

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

24.3. 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. An implementation may choose to assign the same associated data to more than one sample. The location for evaluating such associated data may be anywhere within the fragment area including the fragment’s center location (xf,yf) or any of the sample locations. When rasterizationSamples is VK_SAMPLE_COUNT_1_BIT, the fragment’s center location must be used. The different associated data values need not all be evaluated at the same location.

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

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.

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

24.4. 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 provide a minimum of max(⌈ minSampleShadingFactor × totalSamples ⌉, 1) unique associated data for each fragment, where minSampleShadingFactor is the minimum fraction of sample shading. totalSamples is the value of VkPipelineMultisampleStateCreateInfo::rasterizationSamples specified at pipeline creation time. These are associated with the samples in an implementation-dependent manner. When minSampleShadingFactor is 1.0, a separate set of associated data are evaluated for each sample, and each set of values is evaluated at the sample location.

Sample shading is enabled for a graphics pipeline:

  • If the interface of the fragment shader entry point of the graphics pipeline includes an input variable decorated with SampleId or SamplePosition. In this case minSampleShadingFactor takes the value 1.0.

  • Else if the sampleShadingEnable member of the VkPipelineMultisampleStateCreateInfo structure specified when creating the graphics pipeline is set to VK_TRUE. In this case minSampleShadingFactor takes the value of VkPipelineMultisampleStateCreateInfo::minSampleShading.

Otherwise, sample shading is considered disabled.

24.5. 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 that controls 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.

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

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

24.6. Line Segments

Each line segment has an associated width. The line width is specified by the VkPipelineRasterizationStateCreateInfo::lineWidth property of the currently active pipeline, if the pipeline was not created with VK_DYNAMIC_STATE_LINE_WIDTH enabled.

Otherwise, the line width is set by calling vkCmdSetLineWidth:

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

Valid Usage
  • VUID-vkCmdSetLineWidth-lineWidth-00788
    If the wide lines 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

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 Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

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

24.6.1. Basic Line Segment Rasterization

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

The value of an associated datum f for the fragment, whether it be a shader output or the clip w coordinate, must be determined using perspective interpolation:

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 segments, respectively.

Depth values for lines must be determined using linear interpolation:

z = (1 - t) za + t zb

where za and zb are the depth values of the starting and ending endpoints of the segment, respectively.

The NoPerspective and Flat interpolation decorations can be used with fragment shader inputs to declare how they are interpolated. When neither decoration is applied, perspective interpolation is performed as described above. When the NoPerspective decoration is used, linear interpolation is performed in the same fashion as for depth values, as described above. When the Flat decoration is used, no interpolation is performed, and outputs are taken from the corresponding input value of the provoking vertex corresponding to that primitive.

The above description documents the preferred method of line rasterization, and must be used when the implementation advertises the strictLines limit in VkPhysicalDeviceLimits as VK_TRUE.

When strictLines is VK_FALSE, 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:

24.6.2. Bresenham 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 no more than one.

  • For an x-major line, two fragments that lie in the same framebuffer-coordinate column must not be produced (for a y-major line, two fragments that lie in the same framebuffer-coordinate row must not be produced).

  • If two line segments share a common endpoint, and both segments are either x-major (both left-to-right or both right-to-left) or y-major (both bottom-to-top or both top-to-bottom), then rasterizing both segments must not produce duplicate fragments. Fragments also must not be omitted so as to interrupt continuity of the connected segments.

The actual width 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 were 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).

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

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

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.

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.

The value of an associated datum f for a fragment produced by rasterizing a triangle, whether it be a shader output or the clip w coordinate, must be determined using perspective interpolation:

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 - this must be the location of the fragment center or the location of a sample. When rasterizationSamples is VK_SAMPLE_COUNT_1_BIT, the fragment center must be used.

Depth values for triangles must be determined using linear interpolation:

z = a za + b zb + c zc

where za, zb, and zc are the depth values of pa, pb, and pc, respectively.

The NoPerspective and Flat interpolation decorations can be used with fragment shader inputs to declare how they are interpolated. When neither decoration is applied, perspective interpolation is performed as described above. When the NoPerspective decoration is used, linear interpolation is performed in the same fashion as for depth values, as described above. When the Flat decoration is used, no interpolation is performed, and outputs are taken from the corresponding input value of the provoking vertex corresponding to that primitive.

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 equation [triangle_perspective_interpolation] are iterated independently and a division performed for each fragment).

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

24.7.3. Depth Bias

The depth values of all fragments generated by the rasterization of a polygon can be offset by a single value that is computed for that polygon. This behavior is controlled by the depthBiasEnable, depthBiasConstantFactor, depthBiasClamp, and depthBiasSlopeFactor members of VkPipelineRasterizationStateCreateInfo, or by the corresponding parameters to the vkCmdSetDepthBias command if depth bias state is dynamic.

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

If depthBiasEnable is VK_FALSE, no depth bias is applied and the fragment’s depth values are unchanged.

depthBiasSlopeFactor scales the maximum depth slope of the polygon, and depthBiasConstantFactor scales an implementation-dependent constant that relates to the usable resolution of the depth buffer. The resulting values are summed to produce the depth bias 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.

The maximum depth slope m of a triangle is

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

The minimum resolvable difference r is an implementation-dependent parameter that depends on the depth buffer representation. It is the smallest difference in framebuffer coordinate z values that is guaranteed to remain distinct throughout polygon rasterization and in the depth buffer. 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 buffer representations, r is constant throughout the range of the entire depth buffer. For floating-point depth buffers, 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 buffer is present, r is undefined.

The bias value o for a polygon is

m is computed as described above. If the depth buffer 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.

For fixed-point depth buffers, fragment depth values are always limited to the range [0,1] by clamping after depth bias addition is performed. Fragment depth values are clamped even when the depth buffer uses a floating-point representation.

Valid Usage
  • VUID-vkCmdSetDepthBias-depthBiasClamp-00790
    If the depth bias clamping 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

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 Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics