Vulkan^® 1.3.272 - A Specification (with all ratified extensions)

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

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:

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 region_x and region_y 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:

where texel is the value in the first component of the identified texel, and size_w and size_h are the width and height of the fragment size, decoded from the texel.

If no fragment shading rate attachment is specified, this size is calculated as size_w = size_h = 1. Applications must not specify a width or height greater than 4 by this method.

The Fragment Shading Rate enumeration in SPIR-V adheres to the above encoding.

The final rate (C_xy') 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, C_xy' must be set to {1,1}:

Otherwise, each of the specified shading rates are combined and then used to derive the value of C_xy'. 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.

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

where C_xy is the combined fragment area result, and A_xy and B_xy are the fragment areas of the fragment shading rates being combined.

Two combine operations are performed, first with A_xy equal to the pipeline fragment shading rate and B_xy equal to the primitive fragment shading rate, with the combine() operation selected by combinerOps[0]. A second combination is then performed, with A_xy equal to the result of the first combination and B_xy 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 A_xy and B_xy, and must clamp the result of the second combiner operation.

A fragment shading rate R_xy representing any of A_xy, B_xy or C_xy is clamped as follows. If R_xy is one of the rates returned by vkGetPhysicalDeviceFragmentShadingRatesKHR for the sample count used by rasterization, the clamped shading rate R_xy' is R_xy. 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:

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 (x_f,y_f). This region is a square with side equal to the current point size. Coverage bits that correspond to sample points that intersect the region are 1, other coverage bits are 0. All fragments produced in rasterizing a point are assigned the same associated data, which are those of the vertex corresponding to the point. However, the fragment shader built-in 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; (x_p,y_p) is the location at which the point sprite coordinates are evaluated - this may be the framebuffer coordinates of the fragment center, or the location of a sample; and (x_f,y_f) is the exact, unrounded framebuffer coordinate of the vertex for the point.

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 p_r = (x_d, y_d) be the framebuffer coordinates at which associated data are evaluated. This may be the center of a fragment or the location of a sample within the fragment. When rasterizationSamples is VK_SAMPLE_COUNT_1_BIT, the fragment center must be used. Let p_a = (x_a, y_a) and p_b = (x_b,y_b) be initial and final endpoints of the line segment, respectively. Set

(Note that t = 0 at p_a and t = 1 at p_b. Also note that this calculation projects the vector from p_a to p_r 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 f_a and f_b are the data associated with the starting and ending endpoints of the segment, respectively; w_a and w_b 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

where f_a and f_b 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 the implementation advertises the strictLines limit in VkPhysicalDeviceLimits as VK_TRUE.

By default, 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.

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.

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 x_f and y_f, define a diamond-shaped region that is the intersection of four half planes:

Essentially, a line segment starting at p_a and ending at p_b produces those fragments f for which the segment intersects R_f, except if p_b is contained in R_f.

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

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

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

The 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 (x₀, y₀) and (x₁, y₁) in framebuffer coordinates, the segment with endpoints $(x_0,y_0-\frac{w-1}{2})$ and $(x_1,y_1-\frac{w-1}{2})$ is rasterized, but instead of a single fragment, a column of fragments of height w (a row of fragments of length w for a y-major segment) is produced at each x (y for y-major) location. The lowest fragment of this column is the fragment that would be produced by rasterizing the segment of width 1 with the modified coordinates.

The preferred method of attribute interpolation for a wide line is to generate the same attribute values for all fragments in the row or column described above, as if the adjusted line was used for interpolation and those values replicated to the other fragments, except for 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).

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

where p_a, p_b, and p_c 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 p_a, p_b, or p_c as f_a, f_b, or f_c, 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 w_a, w_b, and w_c are the clip w coordinates of p_a, p_b, and p_c, 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

where f_a, f_b, and f_c are the data associated with p_a, p_b, and p_c, 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 f_i is the value of f at vertex i. For each i, 0 ≤ a_i ≤ 1 and ${\sum }_{i=1}^n{a}_i=1$. The values of a_i may differ from fragment to fragment, but at vertex i, a_i = 1 and a_j = 0 for j ≠ i.

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