24. 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.
24.1. 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 Flat
.
If neither
geometry nor tessellation shading is active,
the provoking vertex is determined by the primitive topology defined by
VkPipelineInputAssemblyStateCreateInfo:topology
used to execute
the drawing command.
If geometry shading is active, the provoking vertex is
determined by the primitive topology
defined by the OutputPoints
,
OutputLineStrip
, or OutputTriangleStrip
execution mode.
If tessellation shading is active but geometry shading is not, the provoking vertex may be any of the vertices in each primitive.
24.2. 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:
where zm is equal to zero.
This view volume can be further restricted by as many as
VkPhysicalDeviceLimits
::maxClipDistances
client-defined
half-spaces.
The cull volume is the intersection of up to
VkPhysicalDeviceLimits
::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 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
VkPhysicalDeviceLimits
::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 ClipDistance
array.
Clip half-space i is then given by the set of points satisfying the
inequality
-
ci(P) ≥ 0
where ci(P) is the clip distance i at point P. For point primitives, ci(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 ClipDistance
and
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 depthClampEnable
enable
of the VkPipelineRasterizationStateCreateInfo structure.
Depth clipping is disabled when depthClampEnable
is VK_TRUE
.
To dynamically set enable or disable depth clamping, call:
// Provided by VK_EXT_extended_dynamic_state3, VK_EXT_shader_object
void vkCmdSetDepthClampEnableEXT(
VkCommandBuffer commandBuffer,
VkBool32 depthClampEnable);
-
commandBuffer
is the command buffer into which the command will be recorded. -
depthClampEnable
specifies whether depth clamping is enabled.
This command sets whether depth clamping is enabled or disabled for
subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT
set in
VkPipelineDynamicStateCreateInfo::pDynamicStates
.
Otherwise, this state is specified by the
VkPipelineRasterizationStateCreateInfo::depthClampEnable
value
used to create the currently active pipeline.
If the depth clamping state is changed dynamically, and the pipeline was not
created with VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT
enabled, then
depth clipping is enabled when depth clamping is disabled and vice versa.
When depth clipping is disabled, the plane equation
-
zm ≤ zc ≤ wc
(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.
Possible values of
VkPhysicalDevicePointClippingProperties::pointClippingBehavior
,
specifying clipping behavior of a point primitive whose vertex lies outside
the clip volume, are:
// Provided by VK_VERSION_1_1
typedef enum VkPointClippingBehavior {
VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES = 0,
VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY = 1,
// Provided by VK_KHR_maintenance2
VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES_KHR = VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES,
// Provided by VK_KHR_maintenance2
VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY_KHR = VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY,
} VkPointClippingBehavior;
or the equivalent
// Provided by VK_KHR_maintenance2
typedef VkPointClippingBehavior VkPointClippingBehaviorKHR;
-
VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES
specifies that the primitive is discarded if the vertex lies outside any clip plane, including the planes bounding the view volume. -
VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY
specifies that the primitive is discarded only if the vertex lies outside any user clip plane.
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 ≤ t ≤ 1, for each clipped vertex. If the coordinates of a clipped vertex are P and the unclipped line segment’s vertex coordinates are P1 and P2, then t satisfies the following equation
-
P = t P1 + (1-t) P2.
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 di (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 -di (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.
24.3. 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 P1 and P2 of an unclipped edge be c1 and c2. 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 c1 + (1-t) c2.
(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 wc, 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 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 c1 or c2, since flat shading has already occurred and the two values are identical.
24.4. Coordinate Transformations
Clip coordinates for a vertex result from shader execution, which yields a
vertex coordinate 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
then the vertex’s normalized device coordinates are
24.5. Controlling the Viewport
The viewport transformation is determined by the selected viewport’s width and height in pixels, px and py, respectively, and its center (ox, oy) (also in pixels), as well as its depth range min and max determining a depth range scale value pz and a depth range bias value oz (defined below). The vertex’s framebuffer coordinates (xf, yf, zf) are given by
-
xf = (px / 2) xd + ox
-
yf = (py / 2) yd + oy
-
zf = pz × zd + oz
Multiple viewports are available, numbered zero up to
VkPhysicalDeviceLimits
::maxViewports
minus one.
The number of viewports used by a pipeline is controlled by the
viewportCount
member of the VkPipelineViewportStateCreateInfo
structure used in pipeline creation.
xf and yf have limited precision, where the number of
fractional bits retained is specified by
VkPhysicalDeviceLimits
::subPixelPrecisionBits
.
The VkPipelineViewportStateCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkPipelineViewportStateCreateInfo {
VkStructureType sType;
const void* pNext;
VkPipelineViewportStateCreateFlags flags;
uint32_t viewportCount;
const VkViewport* pViewports;
uint32_t scissorCount;
const VkRect2D* pScissors;
} VkPipelineViewportStateCreateInfo;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
viewportCount
is the number of viewports used by the pipeline. -
pViewports
is a pointer to an array of VkViewport structures, defining the viewport transforms. If the viewport state is dynamic, this member is ignored. -
scissorCount
is the number of scissors and must match the number of viewports. -
pScissors
is a pointer to an array of VkRect2D structures defining the rectangular bounds of the scissor for the corresponding viewport. If the scissor state is dynamic, this member is ignored.
To dynamically set the viewport count and viewports, call:
// Provided by VK_VERSION_1_3
void vkCmdSetViewportWithCount(
VkCommandBuffer commandBuffer,
uint32_t viewportCount,
const VkViewport* pViewports);
or the equivalent command
// Provided by VK_EXT_shader_object
void vkCmdSetViewportWithCountEXT(
VkCommandBuffer commandBuffer,
uint32_t viewportCount,
const VkViewport* pViewports);
-
commandBuffer
is the command buffer into which the command will be recorded. -
viewportCount
specifies the viewport count. -
pViewports
specifies the viewports to use for drawing.
This command sets the viewport count and viewports state for subsequent
drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT
set in
VkPipelineDynamicStateCreateInfo::pDynamicStates
.
Otherwise, this state is specified by the corresponding
VkPipelineViewportStateCreateInfo::viewportCount
and
pViewports
values used to create the currently active pipeline.
To dynamically set the scissor count and scissor rectangular bounds, call:
// Provided by VK_VERSION_1_3
void vkCmdSetScissorWithCount(
VkCommandBuffer commandBuffer,
uint32_t scissorCount,
const VkRect2D* pScissors);
or the equivalent command
// Provided by VK_EXT_shader_object
void vkCmdSetScissorWithCountEXT(
VkCommandBuffer commandBuffer,
uint32_t scissorCount,
const VkRect2D* pScissors);
-
commandBuffer
is the command buffer into which the command will be recorded. -
scissorCount
specifies the scissor count. -
pScissors
specifies the scissors to use for drawing.
This command sets the scissor count and scissor rectangular bounds state for
subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with
VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT
set in
VkPipelineDynamicStateCreateInfo::pDynamicStates
.
Otherwise, this state is specified by the corresponding
VkPipelineViewportStateCreateInfo::scissorCount
and
pScissors
values used to create the currently active pipeline.
// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineViewportStateCreateFlags;
VkPipelineViewportStateCreateFlags
is a bitmask type for setting a
mask, but is currently reserved for future use.
A pre-rasterization shader
stage can direct each primitive to one of several viewports.
The destination viewport for a primitive is selected by the last active
pre-rasterization shader
stage that has an output variable decorated with ViewportIndex
.
The viewport transform uses the viewport corresponding to the value assigned
to ViewportIndex
, and taken from an implementation-dependent vertex of
each primitive.
If ViewportIndex
is outside the range zero to viewportCount
minus
one for a primitive, or if the last active
pre-rasterization shader
stage did not assign a value to 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 the last pre-rasterization
shader stage does not have an output decorated with 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 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:
// Provided by VK_VERSION_1_0
void vkCmdSetViewport(
VkCommandBuffer commandBuffer,
uint32_t firstViewport,
uint32_t viewportCount,
const VkViewport* pViewports);
-
commandBuffer
is the command buffer into which the command will be recorded. -
firstViewport
is the index of the first viewport whose parameters are updated by the command. -
viewportCount
is the number of viewports whose parameters are updated by the command. -
pViewports
is a pointer to an array of VkViewport structures specifying viewport parameters.
This command sets the viewport transformation parameters state for
subsequent drawing commands
when drawing using shader objects, or
when the graphics pipeline is created with VK_DYNAMIC_STATE_VIEWPORT
set in VkPipelineDynamicStateCreateInfo::pDynamicStates
.
Otherwise, this state is specified by the
VkPipelineViewportStateCreateInfo
::pViewports
values used to
create the currently active pipeline.
The viewport parameters taken from element i of pViewports
replace the current state for the viewport index firstViewport
+ i, for i in [0, viewportCount
).
Both VkPipelineViewportStateCreateInfo and vkCmdSetViewport use
VkViewport
to set the viewport transformation parameters.
The VkViewport
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkViewport {
float x;
float y;
float width;
float height;
float minDepth;
float maxDepth;
} VkViewport;
-
x
andy
are the viewport’s upper left corner (x,y). -
width
andheight
are the viewport’s width and height, respectively. -
minDepth
andmaxDepth
are the depth range for the viewport.
Note
Despite their names, |
The framebuffer depth coordinate 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 , where k ∈ {
0, 1, …, 2m-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
-
ox =
x
+width
/ 2 -
oy =
y
+height
/ 2 -
oz =
minDepth
-
px =
width
-
py =
height
-
pz =
maxDepth
-minDepth
The application can specify a negative term for height
, which has the
effect of negating the y coordinate in clip space before performing the
transform.
When using a negative height
, the application should also adjust the
y
value to point to the lower left corner of the viewport instead of
the upper left corner.
Using the negative height
allows the application to avoid having to
negate the y component of the Position
output from the last
pre-rasterization shader
stage.
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.