vertexpostproc.adoc

Fixed-Function Vertex Post-Processing

After pre-rasterization shader stages, the following fixed-function operations are applied to vertices of the resulting primitives:

• Flat shading (see Flat Shading).

• Primitive clipping, including client-defined half-spaces (see Primitive Clipping).

• Shader output attribute clipping (see Clipping Shader Outputs).

• Perspective division on clip coordinates (see Coordinate Transformations).

• Viewport mapping, including depth range scaling (see Controlling the Viewport).

• Front face determination for polygon primitives (see Basic Polygon Rasterization).

Next, rasterization is performed on primitives as described in chapter Rasterization.

Flat Shading

Flat shading a vertex output attribute means to assign all vertices of the primitive the same value for that output. The output values assigned are those of the provoking vertex of the primitive. Flat shading is applied to those vertex attributes that match fragment input attributes which are decorated as code:Flat.

If neither geometry nor tessellation shading is active, the provoking vertex is determined by the primitive topology defined by slink:VkPipelineInputAssemblyStateCreateInfo:pname:topology used to execute the drawing command.

If geometry shading is active, the provoking vertex is determined by the primitive topology defined by the code:OutputPoints, code:OutputLineStrips, or code:OutputTriangleStrips execution mode.

If tessellation shading is active but geometry shading is not, the provoking vertex may: be any of the vertices in each primitive.

Primitive Clipping

Primitives are culled against the cull volume and then clipped to the clip volume. In clip coordinates, the view volume is defined by:

\[\begin{array}{c} -w_c \leq x_c \leq w_c \\ -w_c \leq y_c \leq w_c \\ z_m \leq z_c \leq w_c \end{array}\]

where z_m is equal to zero.

This view volume can: be further restricted by as many as sname:VkPhysicalDeviceLimits::pname:maxClipDistances client-defined half-spaces.

The cull volume is the intersection of up to sname:VkPhysicalDeviceLimits::pname:maxCullDistances client-defined half-spaces (if no client-defined cull half-spaces are enabled, culling against the cull volume is skipped).

A shader must: write a single cull distance for each enabled cull half-space to elements of the code:CullDistance array. If the cull distance for any enabled cull half-space is negative for all of the vertices of the primitive under consideration, the primitive is discarded. Otherwise the primitive is clipped against the clip volume as defined below.

The clip volume is the intersection of up to sname:VkPhysicalDeviceLimits::pname:maxClipDistances client-defined half-spaces with the view volume (if no client-defined clip half-spaces are enabled, the clip volume is the view volume).

A shader must: write a single clip distance for each enabled clip half-space to elements of the code:ClipDistance array. Clip half-space i is then given by the set of points satisfying the inequality

c_i(P) {geq} 0

where c_i(P) is the clip distance i at point P. For point primitives, c_i(P) is simply the clip distance for the vertex in question. For line and triangle primitives, per-vertex clip distances are interpolated using a weighted mean, with weights derived according to the algorithms described in sections Basic Line Segment Rasterization and Basic Polygon Rasterization, using the perspective interpolation equations.

The number of client-defined clip and cull half-spaces that are enabled is determined by the explicit size of the built-in arrays code:ClipDistance and code:CullDistance, respectively, declared as an output in the interface of the entry point of the final shader stage before clipping.

Depth clamping is enabled or disabled via the pname:depthClampEnable enable of the slink:VkPipelineRasterizationStateCreateInfo structure. Depth clipping is disabled when pname:depthClampEnable is ename:VK_TRUE.

When depth clipping is disabled, the plane equation

z_m {leq} z_c {leq} w_c

(see the clip volume definition above) is ignored by view volume clipping (effectively, there is no near or far plane clipping).

If the primitive under consideration is a point or line segment, then clipping passes it unchanged if its vertices lie entirely within the clip volume.

If a point’s vertex lies outside of the clip volume, the entire primitive may: be discarded.

If either of a line segment’s vertices lie outside of the clip volume, the line segment may: be clipped, with new vertex coordinates computed for each vertex that lies outside the clip volume. A clipped line segment endpoint lies on both the original line segment and the boundary of the clip volume.

This clipping produces a value, 0 {leq} t {leq} 1, for each clipped vertex. If the coordinates of a clipped vertex are P and the unclipped line segment’s vertex coordinates are P₁ and P₂, then t satisfies the following equation

P = t P₁ + (1-t) P₂.

t is used to clip vertex output attributes as described in Clipping Shader Outputs.

If the primitive is a polygon, it passes unchanged if every one of its edges lies entirely inside the clip volume, and is either clipped or discarded otherwise. If the edges of the polygon intersect the boundary of the clip volume, the intersecting edges are reconnected by new edges that lie along the boundary of the clip volume - in some cases requiring the introduction of new vertices into a polygon.

If a polygon intersects an edge of the clip volume’s boundary, the clipped polygon must: include a point on this boundary edge.

Primitives rendered with user-defined half-spaces must: satisfy a complementarity criterion. Suppose a series of primitives is drawn where each vertex i has a single specified clip distance d_i (or a number of similarly specified clip distances, if multiple half-spaces are enabled). Next, suppose that the same series of primitives are drawn again with each such clip distance replaced by -d_i (and the graphics pipeline is otherwise the same). In this case, primitives must: not be missing any pixels, and pixels must: not be drawn twice in regions where those primitives are cut by the clip planes.

Clipping Shader Outputs

Next, vertex output attributes are clipped. The output values associated with a vertex that lies within the clip volume are unaffected by clipping. If a primitive is clipped, however, the output values assigned to vertices produced by clipping are clipped.

Let the output values assigned to the two vertices P₁ and P₂ of an unclipped edge be c₁ and c₂. The value of t (see Primitive Clipping) for a clipped point P is used to obtain the output value associated with P as

c = t c₁ + (1-t) c₂.

(Multiplying an output value by a scalar means multiplying each of x, y, z, and w by the scalar.)

Since this computation is performed in clip space before division by w_c, clipped output values are perspective-correct.

Polygon clipping creates a clipped vertex along an edge of the clip volume’s boundary. This situation is handled by noting that polygon clipping proceeds by clipping against one half-space at a time. Output value clipping is done in the same way, so that clipped points always occur at the intersection of polygon edges (possibly already clipped) with the clip volume’s boundary.

For vertex output attributes whose matching fragment input attributes are decorated with code:NoPerspective, the value of t used to obtain the output value associated with P will be adjusted to produce results that vary linearly in framebuffer space.

Output attributes of integer or unsigned integer type must: always be flat shaded. Flat shaded attributes are constant over the primitive being rasterized (see Basic Line Segment Rasterization and Basic Polygon Rasterization), and no interpolation is performed. The output value c is taken from either c₁ or c₂, since flat shading has already occurred and the two values are identical.

Coordinate Transformations

Clip coordinates for a vertex result from shader execution, which yields a vertex coordinate code:Position.

Perspective division on clip coordinates yields normalized device coordinates, followed by a viewport transformation (see Controlling the Viewport) to convert these coordinates into framebuffer coordinates.

If a vertex in clip coordinates has a position given by

\[\left(\begin{array}{c} x_c \\ y_c \\ z_c \\ w_c \end{array}\right)\]

then the vertex’s normalized device coordinates are

\[\left( \begin{array}{c} x_d \\ y_d \\ z_d \end{array} \right) = \left( \begin{array}{c} \frac{x_c}{w_c} \\ \frac{y_c}{w_c} \\ \frac{z_c}{w_c} \end{array} \right)\]

Controlling the Viewport

The viewport transformation is determined by the selected viewport’s width and height in pixels, p_x and p_y, respectively, and its center (o_x, o_y) (also in pixels), as well as its depth range min and max determining a depth range scale value p_z and a depth range bias value o_z (defined below). The vertex’s framebuffer coordinates (x_f, y_f, z_f) are given by

x_f = (p_x / 2) x_d + o_x

y_f = (p_y / 2) y_d + o_y

z_f = p_z {times} z_d + o_z

Multiple viewports are available, numbered zero up to sname:VkPhysicalDeviceLimits::pname:maxViewports minus one. The number of viewports used by a pipeline is controlled by the pname:viewportCount member of the sname:VkPipelineViewportStateCreateInfo structure used in pipeline creation.

x_f and y_f have limited precision, where the number of fractional bits retained is specified by sname:VkPhysicalDeviceLimits::pname:subPixelPrecisionBits.

The sname:VkPipelineViewportStateCreateInfo structure is defined as:

{generated}/api/structs/VkPipelineViewportStateCreateInfo.adoc

• pname:sType is the type of this structure.

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

• pname:flags is reserved for future use.

• pname:viewportCount is the number of viewports used by the pipeline.

• pname:pViewports is a pointer to an array of slink:VkViewport structures, defining the viewport transforms. If the viewport state is dynamic, this member is ignored.

• pname:scissorCount is the number of scissors and must: match the number of viewports.

• pname:pScissors is a pointer to an array of slink:VkRect2D structures defining the rectangular bounds of the scissor for the corresponding viewport. If the scissor state is dynamic, this member is ignored.

Valid Usage

• If the pname:multiViewport feature is not enabled, pname:viewportCount must: not be greater than 1

• If the pname:multiViewport feature is not enabled, pname:scissorCount must: not be greater than 1

• pname:viewportCount must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxViewports

• pname:scissorCount must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxViewports

• pname:scissorCount and pname:viewportCount must: be identical

• The pname:x and pname:y members of pname:offset member of any element of pname:pScissors must: be greater than or equal to 0

• Evaluation of (pname:offset.x + pname:extent.width) must: not cause a signed integer addition overflow for any element of pname:pScissors

• Evaluation of (pname:offset.y + pname:extent.height) must: not cause a signed integer addition overflow for any element of pname:pScissors

• pname:viewportCount must: be greater than 0

• pname:scissorCount must: be greater than 0

{generated}/validity/structs/VkPipelineViewportStateCreateInfo.adoc

{generated}/api/flags/VkPipelineViewportStateCreateFlags.adoc

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

If a geometry shader is active and has an output variable decorated with code:ViewportIndex, the viewport transformation uses the viewport corresponding to the value assigned to code:ViewportIndex taken from an implementation-dependent vertex of each primitive. If code:ViewportIndex is outside the range zero to pname:viewportCount minus one for a primitive, or if the geometry shader did not assign a value to code:ViewportIndex for all vertices of a primitive due to flow control, the values resulting from the viewport transformation of the vertices of such primitives are undefined:. If no geometry shader is active, or if the geometry shader does not have an output decorated with code:ViewportIndex, the viewport numbered zero is used by the viewport transformation.

A single vertex can: be used in more than one individual primitive, in primitives such as ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP. In this case, the viewport transformation is applied separately for each primitive.

To dynamically set the viewport transformation parameters, call:

{generated}/api/protos/vkCmdSetViewport.adoc

• pname:commandBuffer is the command buffer into which the command will be recorded.

• pname:firstViewport is the index of the first viewport whose parameters are updated by the command.

• pname:viewportCount is the number of viewports whose parameters are updated by the command.

• pname:pViewports is a pointer to an array of slink:VkViewport structures specifying viewport parameters.

This command sets the viewport transformation parameters state for subsequent drawing commands when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_VIEWPORT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the sname:VkPipelineViewportStateCreateInfo::pname:pViewports values used to create the currently active pipeline.

The viewport parameters taken from element i of pname:pViewports replace the current state for the viewport index pname:firstViewport + i, for i in [0, pname:viewportCount).

Valid Usage

• The sum of pname:firstViewport and pname:viewportCount must: be between 1 and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive

• If the pname:multiViewport feature is not enabled, pname:firstViewport must: be 0

• If the pname:multiViewport feature is not enabled, pname:viewportCount must: be 1

{generated}/validity/protos/vkCmdSetViewport.adoc

Both slink:VkPipelineViewportStateCreateInfo and flink:vkCmdSetViewport use sname:VkViewport to set the viewport transformation parameters.

The sname:VkViewport structure is defined as:

{generated}/api/structs/VkViewport.adoc

• pname:x and pname:y are the viewport’s upper left corner (x,y).

• pname:width and pname:height are the viewport’s width and height, respectively.

• pname:minDepth and pname:maxDepth are the depth range for the viewport.

Note	Note Despite their names, pname:minDepth can: be less than, equal to, or greater than pname:maxDepth.

The framebuffer depth coordinate pname:z_f may: be represented using either a fixed-point or floating-point representation. However, a floating-point representation must: be used if the depth/stencil attachment has a floating-point depth component. If an m-bit fixed-point representation is used, we assume that it represents each value \(\frac{k}{2^m - 1}\), where k {elem} { 0, 1, …​, 2^m-1 }, as k (e.g. 1.0 is represented in binary as a string of all ones).

The viewport parameters shown in the above equations are found from these values as

o_x = pname:x + pname:width / 2

o_y = pname:y + pname:height / 2

o_z = pname:minDepth

p_x = pname:width

p_y = pname:height

p_z = pname:maxDepth - pname:minDepth

The width and height of the implementation-dependent maximum viewport dimensions must: be greater than or equal to the width and height of the largest image which can: be created and attached to a framebuffer.

The floating-point viewport bounds are represented with an implementation-dependent precision.

Valid Usage

• pname:width must: be greater than 0.0

• pname:width must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxViewportDimensions[0]

• pname:height must: be greater than 0.0

• The absolute value of pname:height must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxViewportDimensions[1]

• pname:x must: be greater than or equal to pname:viewportBoundsRange[0]

• (pname:x + pname:width) must: be less than or equal to pname:viewportBoundsRange[1]

• pname:y must: be greater than or equal to pname:viewportBoundsRange[0]

• (pname:y + pname:height) must: be less than or equal to pname:viewportBoundsRange[1]

• pname:minDepth must: be between 0.0 and 1.0, inclusive

• pname:maxDepth must: be between 0.0 and 1.0, inclusive

{generated}/validity/structs/VkViewport.adoc