Vulkan-Docs/doc/specs/vulkan/chapters/tessellation.txt

// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html

[[tessellation]]
= Tessellation

Tessellation involves three pipeline stages.
First, a <<shaders-tessellation-control,tessellation control shader>>
transforms control points of a patch and can: produce per-patch data.
Second, a fixed-function tessellator generates multiple primitives
corresponding to a tessellation of the patch in (u,v) or (u,v,w) parameter
space.
Third, a <<shaders-tessellation-evaluation,tessellation evaluation shader>>
transforms the vertices of the tessellated patch, for example to compute
their positions and attributes as part of the tessellated surface.
The tessellator is enabled when the pipeline contains both a tessellation
control shader and a tessellation evaluation shader.


== Tessellator

If a pipeline includes both tessellation shaders (control and evaluation),
the tessellator consumes each input patch (after vertex shading) and
produces a new set of independent primitives (points, lines, or triangles).
These primitives are logically produced by subdividing a geometric primitive
(rectangle or triangle) according to the per-patch outer and inner
tessellation levels written by the tessellation control shader.
These levels are specified using the <<interfaces-builtin-variables,built-in
variables>> code:TessLevelOuter and code:TessLevelInner, respectively.
This subdivision is performed in an implementation-dependent manner.
If no tessellation shaders are present in the pipeline, the tessellator is
disabled and incoming primitives are passed through without modification.

The type of subdivision performed by the tessellator is specified by an
code:OpExecutionMode instruction in the tessellation evaluation or
tessellation control shader using one of execution modes code:Triangles,
code:Quads, and code:IsoLines.
Other tessellation-related execution modes can: also be specified in either
the tessellation control or tessellation evaluation shaders, and if they are
specified in both then the modes must: be the same.

Tessellation execution modes include:

  * code:Triangles, code:Quads, and code:IsoLines.
    These control the type of subdivision and topology of the output
    primitives.
    One mode must: be set in at least one of the tessellation shader stages.
  * code:VertexOrderCw and code:VertexOrderCcw.
    These control the orientation of triangles generated by the tessellator.
    One mode must: be set in at least one of the tessellation shader stages.
  * code:PointMode.
    Controls generation of points rather than triangles or lines.
    This functionality defaults to disabled, and is enabled if either shader
    stage includes the execution mode.
  * code:SpacingEqual, code:SpacingFractionalEven, and
    code:SpacingFractionalOdd.
    Controls the spacing of segments on the edges of tessellated primitives.
    One mode must: be set in at least one of the tessellation shader stages.
  * code:OutputVertices.
    Controls the size of the output patch of the tessellation control
    shader.
    One value must: be set in at least one of the tessellation shader
    stages.

For triangles, the tessellator subdivides a triangle primitive into smaller
triangles.
For quads, the tessellator subdivides a rectangle primitive into smaller
triangles.
For isolines, the tessellator subdivides a rectangle primitive into a
collection of line segments arranged in strips stretching across the
rectangle in the latexmath:[$u$] dimension (i.e.
the coordinates in code:TessCoord are of the form (0,x) through (1,x) for
all tessellation evaluation shader invocations that share a line).

Each vertex produced by the tessellator has an associated (u,v,w) or (u,v)
position in a normalized parameter space, with parameter values in the range
latexmath:[$[0,1\]$], as illustrated in figure
<<img-tessellation-topology>>.

[[img-tessellation-topology]]
image::images/tessparam.{svgpdf}[align="center",title="Domain parameterization for tessellation primitive modes",{fullimagewidth}]

For triangles, the vertex's position is a barycentric coordinate (u,v,w),
where u + v + w = 1.0, and indicates the relative influence of the three
vertices of the triangle on the position of the vertex.
For quads and isolines, the position is a (u,v) coordinate indicating the
relative horizontal and vertical position of the vertex relative to the
subdivided rectangle.
The subdivision process is explained in more detail in subsequent sections.


== Tessellator Patch Discard

A patch is discarded by the tessellator if any relevant outer tessellation
level is less than or equal to zero.

Patches will also be discarded if any relevant outer tessellation level
corresponds to a floating-point NaN (not a number) in implementations
supporting NaN.

No new primitives are generated and the tessellation evaluation shader is
not executed for patches that are discarded.
For code:Quads, all four outer levels are relevant.
For code:Triangles and code:IsoLines, only the first three or two outer
levels, respectively, are relevant.
Negative inner levels will not cause a patch to be discarded; they will be
clamped as described below.


[[tessellation-tessellator-spacing]]
== Tessellator Spacing

Each of the tessellation levels is used to determine the number and spacing
of segments used to subdivide a corresponding edge.
The method used to derive the number and spacing of segments is specified by
an code:OpExecutionMode in the tessellation control or tessellation
evaluation shader using one of the identifiers code:SpacingEqual,
code:SpacingFractionalEven, or code:SpacingFractionalOdd.

If code:SpacingEqual is used, the floating-point tessellation level is first
clamped to latexmath:[$[1,\mathit{maxLevel}\]$], where
latexmath:[$\mathit{maxLevel}$] is the implementation-dependent maximum
tessellation level
(sname:VkPhysicalDeviceLimits::pname:maxTessellationGenerationLevel).
The result is rounded up to the nearest integer latexmath:[$n$], and the
corresponding edge is divided into latexmath:[$n$] segments of equal length
in (u,v) space.

If code:SpacingFractionalEven is used, the tessellation level is first
clamped to latexmath:[$[2,\mathit{maxLevel}\]$] and then rounded up to the
nearest even integer latexmath:[$n$].
If code:SpacingFractionalOdd is used, the tessellation level is clamped to
latexmath:[$[1,\mathit{maxLevel}-1\]$] and then rounded up to the nearest
odd integer latexmath:[$n$].
If latexmath:[$n$] is one, the edge will not be subdivided.
Otherwise, the corresponding edge will be divided into latexmath:[$n-2$]
segments of equal length, and two additional segments of equal length that
are typically shorter than the other segments.
The length of the two additional segments relative to the others will
decrease monotonically with latexmath:[$n-f$], where latexmath:[$f$] is the
clamped floating-point tessellation level.
When latexmath:[$n-f$] is zero, the additional segments will have equal
length to the other segments.
As latexmath:[$n-f$] approaches 2.0, the relative length of the additional
segments approaches zero.
The two additional segments must: be placed symmetrically on opposite sides
of the subdivided edge.
The relative location of these two segments is implementation-dependent, but
must: be identical for any pair of subdivided edges with identical values of
latexmath:[$f$].

When the tessellator produces triangles (in the code:Triangles or code:Quads
modes), the orientation of all triangles is specified with an
code:OpExecutionMode of code:VertexOrderCw or code:VertexOrderCcw in the
tessellation control or tessellation evaluation shaders.
If the order is code:VertexOrderCw, the vertices of all generated triangles
will have clockwise ordering in (u,v) or (u,v,w) space.
If the order is code:VertexOrderCcw, the vertices will have
counter-clockwise ordering.

The vertices of a triangle have counter-clockwise ordering if

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\[
  a = u_0 v_1 - u_1 v_0 + u_1 v_2 - u_2 v_1 + u_2 v_0 - u_0 v_2
\]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

is positive, and clockwise ordering if latexmath:[$a$] is negative.
latexmath:[$u_i$] and latexmath:[$v_i$] are the latexmath:[$u$] and
latexmath:[$v$] coordinates in normalized parameter space of the
latexmath:[$i$]th vertex of the triangle.

[NOTE]
.Note
====
The value latexmath:[$a$] is proportional (with a positive factor) to the
signed area of the triangle.

In code:Triangles mode, even though the vertex coordinates have a
latexmath:[$w$] value, it does not participate directly in the computation
of latexmath:[$a$], being an affine combination of latexmath:[$u$] and
latexmath:[$v$].
====

For all primitive modes, the tessellator is capable of generating points
instead of lines or triangles.
If the tessellation control or tessellation evaluation shader specifies the
code:OpExecutionMode code:PointMode, the primitive generator will generate
one point for each distinct vertex produced by tessellation.
Otherwise, the tessellator will produce a collection of line segments or
triangles according to the primitive mode.
When tessellating triangles or quads in point mode with fractional odd
spacing, the tessellator may: produce _interior vertices_ that are
positioned on the edge of the patch if an inner tessellation level is less
than or equal to one.
Such vertices are considered distinct from vertices produced by subdividing
the outer edge of the patch, even if there are pairs of vertices with
identical coordinates.

The points, lines, or triangles produced by the tessellator are passed to
subsequent pipeline stages in an implementation-dependent order.


[[tessellation-triangle-tessellation]]
== Triangle Tessellation

If the tessellation primitive mode is code:Triangles, an equilateral
triangle is subdivided into a collection of triangles covering the area of
the original triangle.
First, the original triangle is subdivided into a collection of concentric
equilateral triangles.
The edges of each of these triangles are subdivided, and the area between
each triangle pair is filled by triangles produced by joining the vertices
on the subdivided edges.
The number of concentric triangles and the number of subdivisions along each
triangle except the outermost is derived from the first inner tessellation
level.
The edges of the outermost triangle are subdivided independently, using the
first, second, and third outer tessellation levels to control the number of
subdivisions of the latexmath:[$u=0$] (left), latexmath:[$v=0$] (bottom),
and latexmath:[$w=0$] (right) edges, respectively.
The second inner tessellation level and the fourth outer tessellation level
have no effect in this mode.

If the first inner tessellation level and all three outer tessellation
levels are exactly one after clamping and rounding, only a single triangle
with (u,v,w) coordinates of (0,0,1), (1,0,0), and (0,1,0) is generated.
If the inner tessellation level is one and any of the outer tessellation
levels is greater than one, the inner tessellation level is treated as
though it were originally specified as latexmath:[$1+\epsilon$] and will
result in a two- or three-segment subdivision depending on the tessellation
spacing.
When used with fractional odd spacing, the three-segment subdivision may:
produce _inner vertices_ positioned on the edge of the triangle.

If any tessellation level is greater than one, tessellation begins by
producing a set of concentric inner triangles and subdividing their edges.
First, the three outer edges are temporarily subdivided using the clamped
and rounded first inner tessellation level and the specified tessellation
spacing, generating latexmath:[$n$] segments.
For the outermost inner triangle, the inner triangle is degenerate -- a
single point at the center of the triangle -- if latexmath:[$n$] is two.
Otherwise, for each corner of the outer triangle, an inner triangle corner
is produced at the intersection of two lines extended perpendicular to the
corner's two adjacent edges running through the vertex of the subdivided
outer edge nearest that corner.
If latexmath:[$n$] is three, the edges of the inner triangle are not
subdivided and is the final triangle in the set of concentric triangles.
Otherwise, each edge of the inner triangle is divided into latexmath:[$n-2$]
segments, with the latexmath:[$n-1$] vertices of this subdivision produced
by intersecting the inner edge with lines perpendicular to the edge running
through the latexmath:[$n-1$] innermost vertices of the subdivision of the
outer edge.
Once the outermost inner triangle is subdivided, the previous subdivision
process repeats itself, using the generated triangle as an outer triangle.
This subdivision process is illustrated in <<img-innertri,Inner Triangle
Tessellation>>.

[[img-innertri]]
image::images/innertri.{svgpdf}[align="center",title="Inner Triangle Tessellation",{fullimagewidth}]

// TODO: Add caption:
//  Inner triangle tessellation with inner tessellation
//  levels of (a) five and (b) four, respectively (not to scale). Solid
//  black circles depict vertices along the edges of the concentric
//  triangles. The edges of inner triangles are subdivided by intersecting
//  the edge with segments perpendicular to the edge passing through each
//  inner vertex of the subdivided outer edge. Dotted lines depict edges
//  connecting corresponding vertices on the inner and outer triangle
//  edges.

Once all the concentric triangles are produced and their edges are
subdivided, the area between each pair of adjacent inner triangles is filled
completely with a set of non-overlapping triangles.
In this subdivision, two of the three vertices of each triangle are taken
from adjacent vertices on a subdivided edge of one triangle; the third is
one of the vertices on the corresponding edge of the other triangle.
If the innermost triangle is degenerate (i.e., a point), the triangle
containing it is subdivided into six triangles by connecting each of the six
vertices on that triangle with the center point.
If the innermost triangle is not degenerate, that triangle is added to the
set of generated triangles as-is.

After the area corresponding to any inner triangles is filled, the
tessellator generates triangles to cover the area between the outermost
triangle and the outermost inner triangle.
To do this, the temporary subdivision of the outer triangle edge above is
discarded.
Instead, the latexmath:[$u=0$], latexmath:[$v=0$], and latexmath:[$w=0$]
edges are subdivided according to the first, second, and third outer
tessellation levels, respectively, and the tessellation spacing.
The original subdivision of the first inner triangle is retained.
The area between the outer and first inner triangles is completely filled by
non-overlapping triangles as described above.
If the first (and only) inner triangle is degenerate, a set of triangles is
produced by connecting each vertex on the outer triangle edges with the
center point.

After all triangles are generated, each vertex in the subdivided triangle is
assigned a barycentric (u,v,w) coordinate based on its location relative to
the three vertices of the outer triangle.

The algorithm used to subdivide the triangular domain in (u,v,w) space into
individual triangles is implementation-dependent.
However, the set of triangles produced will completely cover the domain, and
no portion of the domain will be covered by multiple triangles.
The order in which the generated triangles passed to subsequent pipeline
stages and the order of the vertices in those triangles are both
implementation-dependent.
However, when depicted in a manner similar to <<img-innertri,Inner Triangle
Tessellation>>, the order of the vertices in the generated triangles will be
either all clockwise or all counter-clockwise, according to the vertex order
layout declaration.


[[tessellation-quad-tessellation]]
== Quad Tessellation

If the tessellation primitive mode is code:Quads, a rectangle is subdivided
into a collection of triangles covering the area of the original rectangle.
First, the original rectangle is subdivided into a regular mesh of
rectangles, where the number of rectangles along the latexmath:[$u=0$] and
latexmath:[$u=1$] (vertical) and latexmath:[$v=0$] and latexmath:[$v=1$]
(horizontal) edges are derived from the first and second inner tessellation
levels, respectively.
All rectangles, except those adjacent to one of the outer rectangle edges,
are decomposed into triangle pairs.
The outermost rectangle edges are subdivided independently, using the first,
second, third, and fourth outer tessellation levels to control the number of
subdivisions of the latexmath:[$u=0$] (left), latexmath:[$v=0$] (bottom),
latexmath:[$u=1$] (right), and latexmath:[$v=1$] (top) edges, respectively.
The area between the inner rectangles of the mesh and the outer rectangle
edges are filled by triangles produced by joining the vertices on the
subdivided outer edges to the vertices on the edge of the inner rectangle
mesh.

If both clamped inner tessellation levels and all four clamped outer
tessellation levels are exactly one, only a single triangle pair covering
the outer rectangle is generated.
Otherwise, if either clamped inner tessellation level is one, that
tessellation level is treated as though it were originally specified as
latexmath:[$1+\epsilon$] and will result in a two- or three-segment
subdivision depending on the tessellation spacing.
When used with fractional odd spacing, the three-segment subdivision may:
produce _inner vertices_ positioned on the edge of the rectangle.

If any tessellation level is greater than one, tessellation begins by
subdividing the latexmath:[$u=0$] and latexmath:[$u=1$] edges of the outer
rectangle into latexmath:[$m$] segments using the clamped and rounded first
inner tessellation level and the tessellation spacing.
The latexmath:[$v=0$] and latexmath:[$v=1$] edges are subdivided into
latexmath:[$n$] segments using the second inner tessellation level.
Each vertex on the latexmath:[$u=0$] and latexmath:[$v=0$] edges are joined
with the corresponding vertex on the latexmath:[$u=1$] and latexmath:[$v=1$]
edges to produce a set of vertical and horizontal lines that divide the
rectangle into a grid of smaller rectangles.
The primitive generator emits a pair of non-overlapping triangles covering
each such rectangle not adjacent to an edge of the outer rectangle.
The boundary of the region covered by these triangles forms an inner
rectangle, the edges of which are subdivided by the grid vertices that lie
on the edge.
If either latexmath:[$m$] or latexmath:[$n$] is two, the inner rectangle is
degenerate, and one or both of the rectangle's _edges_ consist of a single
point.
This subdivision is illustrated in Figure <<img-innerquad,Inner Quad
Tessellation>>.

[[img-innerquad]]
image::images/innerquad.{svgpdf}[align="center",title="Inner Quad Tessellation",{fullimagewidth}]

// TODO: Add caption:
//  Inner quad tessellation with inner tessellation
//  levels of
//  (a) $(4,2)$ and (b) $(7,4)$, respectively. Gray regions on the
//  bottom figure
//  depict the 10 inner rectangles, each of which will be subdivided
//  into two triangles.
//  Solid black circles depict vertices on the boundary of the outer and
//  inner rectangles,
//  where the inner rectangle on the top figure
//  is degenerate (a single line segment). Dotted lines depict the
//  horizontal and vertical edges connecting corresponding
//  vertices on the inner and outer rectangle edges.

After the area corresponding to the inner rectangle is filled, the
tessellator must: produce triangles to cover the area between the inner and
outer rectangles.
To do this, the subdivision of the outer rectangle edge above is discarded.
Instead, the latexmath:[$u=0$], latexmath:[$v=0$], latexmath:[$u=1$], and
latexmath:[$v=1$] edges are subdivided according to the first, second,
third, and fourth outer tessellation levels, respectively, and the
tessellation spacing.
The original subdivision of the inner rectangle is retained.
The area between the outer and inner rectangles is completely filled by
non-overlapping triangles.
Two of the three vertices of each triangle are adjacent vertices on a
subdivided edge of one rectangle; the third is one of the vertices on the
corresponding edge of the other triangle.
If either edge of the innermost rectangle is degenerate, the area near the
corresponding outer edges is filled by connecting each vertex on the outer
edge with the single vertex making up the _inner edge_.

The algorithm used to subdivide the rectangular domain in (u,v) space into
individual triangles is implementation-dependent.
However, the set of triangles produced will completely cover the domain, and
no portion of the domain will be covered by multiple triangles.
The order in which the generated triangles passed to subsequent pipeline
stages and the order of the vertices in those triangles are both
implementation-dependent.
However, when depicted in a manner similar to <<img-innerquad,Inner Quad
Tessellation>>, the order of the vertices in the generated triangles will be
either all clockwise or all counter-clockwise, according to the vertex order
layout declaration.


[[tessellation-isoline-tessellation]]
== Isoline Tessellation

If the tessellation primitive mode is code:IsoLines, a set of independent
horizontal line segments is drawn.
The segments are arranged into connected strips called _isolines_, where the
vertices of each isoline have a constant v coordinate and u coordinates
covering the full range [0,1].
The number of isolines generated is derived from the first outer
tessellation level; the number of segments in each isoline is derived from
the second outer tessellation level.
Both inner tessellation levels and the third and fourth outer tessellation
levels have no effect in this mode.

As with quad tessellation above, isoline tessellation begins with a
rectangle.
The latexmath:[$u=0$] and latexmath:[$u=1$] edges of the rectangle are
subdivided according to the first outer tessellation level.
For the purposes of this subdivision, the tessellation spacing mode is
ignored and treated as equal_spacing.
An isoline is drawn connecting each vertex on the latexmath:[$u=0$]
rectangle edge to the corresponding vertex on the latexmath:[$u=1$]
rectangle edge, except that no line is drawn between (0,1) and (1,1).
If the number of isolines on the subdivided latexmath:[$u=0$] and
latexmath:[$u=1$] edges is latexmath:[$n$], this process will result in
latexmath:[$n$] equally spaced lines with constant v coordinates of 0,
latexmath:[$\frac{1}{n}, \frac{2}{n}, \ldots, \frac{n-1}{n}$].

Each of the latexmath:[$n$] isolines is then subdivided according to the
second outer tessellation level and the tessellation spacing, resulting in
latexmath:[$m$] line segments.
Each segment of each line is emitted by the tessellator.

The order in which the generated line segments are passed to subsequent
pipeline stages and the order of the vertices in each generated line segment
are both implementation-dependent.


== Tessellation Pipeline State

The pname:pTessellationState member of slink:VkGraphicsPipelineCreateInfo
points to a structure of type sname:VkPipelineTessellationStateCreateInfo.

// refBegin VkPipelineTessellationStateCreateInfo Structure specifying parameters of a newly created pipeline tessellation state

The sname:VkPipelineTessellationStateCreateInfo structure is defined as:

include::../api/structs/VkPipelineTessellationStateCreateInfo.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:flags is reserved for future use.
  * pname:patchControlPoints number of control points per patch.

include::../validity/structs/VkPipelineTessellationStateCreateInfo.txt[]