Primitive topology determines how consecutive vertices are organized into
primitives, and determines the type of primitive that is used at the
beginning of the graphics pipeline. The effective topology for later stages
of the pipeline is altered by tessellation or geometry shading (if either is
in use) and depends on the execution modes of those shaders. Supported
topologies are defined by VkPrimitiveTopology
and include:
typedef enum VkPrimitiveTopology { VK_PRIMITIVE_TOPOLOGY_POINT_LIST = 0, VK_PRIMITIVE_TOPOLOGY_LINE_LIST = 1, VK_PRIMITIVE_TOPOLOGY_LINE_STRIP = 2, VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST = 3, VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP = 4, VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN = 5, VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY = 6, VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY = 7, VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY = 8, VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY = 9, VK_PRIMITIVE_TOPOLOGY_PATCH_LIST = 10, } VkPrimitiveTopology;
Each primitive topology, and its construction from a list of vertices, is summarized below.
A series of individual points are specified with topology
VK_PRIMITIVE_TOPOLOGY_POINT_LIST
. Each vertex defines a separate
point.
Individual line segments, each defined by a pair of vertices, are specified
with topology
VK_PRIMITIVE_TOPOLOGY_LINE_LIST
. The first two
vertices define the first segment, with subsequent pairs of vertices each
defining one more segment. If the number of vertices is odd, then the last
vertex is ignored.
A series of one or more connected line segments are specified with
topology
VK_PRIMITIVE_TOPOLOGY_LINE_STRIP
. In this case, the
first vertex specifies the first segment’s start point while the second
vertex specifies the first segment’s endpoint and the second segment’s start
point. In general, the
$i$
th vertex (for
$i > 0$
)
specifies the beginning of the
$i$
th segment and the end of the
$i-1$
st. The last vertex specifies the end of the last segment.
If only one vertex is specified, then no primitive is generated.
A triangle strip is a series of triangles connected along shared edges, and
is specified with topology
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP
.
In this case, the first three vertices define the first triangle, and their
order is significant. Each subsequent vertex defines a new triangle using
that point along with the last two vertices from the previous triangle, as
shown in figure Figure 19.1, “Triangle strips, fans, and lists”. If fewer than three vertices are
specified, no primitive is produced. The order of vertices in successive
triangles changes as shown in the figure, so that all triangle faces have
the same orientation.
![]() | editing-note |
---|---|
TODO: Add full caption:
The numbers give the sequencing of the vertices in order within the vertex arrays. Note that in (a) and (b) triangle edge ordering is determined by the first triangle, while in (c) the order of each triangle’s edges is independent of the other triangles. |
A triangle fan is specified with topology
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN
. It is similar to a triangle strip,
but changes the vertex replaced from the previous triangle as shown in
figure Figure 19.1, “Triangle strips, fans, and lists”, so that all triangles in the fan share a common
vertex.
Separate triangles are specified with topology
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST
, as shown in figure
Figure 19.1, “Triangle strips, fans, and lists”. In this case, vertices
$3i$
,
$3i+1$
, and
$3i+2$
vertices (in that order)
determine a triangle for each
$i=0,1,\ldots,n-1$
, where there
are
$3n+k$
vertices drawn.
$k$
is either 0, 1, or 2;
if
$k$
is not zero, the final
$k$
vertices are
ignored.
Lines with adjacency are specified with topology
VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY
, and are independent
line segments where each endpoint has a corresponding adjacent vertex that
is accessible in a geometry shader.
If a geometry shader is not active, the adjacent vertices are ignored.
A line segment is drawn from the $4 i+1$ st vertex to the $4 i+2$ nd vertex for each $i=0,1,\ldots, n-1$ , where there are $4 n+k$ vertices. $k$ is either 0, 1, 2, or 3; if $k$ is not zero, the final $k$ vertices are ignored. For line segment $i$ , the $4 i$ th and $4 i+3$ rd vertices are considered adjacent to the $4 i+1$ st and $4 i+2$ nd vertices, respectively, as shown in figure Figure 19.2, “Lines with adjacency”.
![]() | editing-note |
---|---|
TODO: Add full caption: Lines with adjacency (a) and line strips with adjacency (b). The vertices connected with solid lines belong to the main primitives; the vertices connected by dashed lines are the adjacent vertices that are accessible in a geometry shader. |
Line strips with adjacency are specified with topology
VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY
and are similar to
line strips, except that each line segment has a pair of adjacent vertices
that are accessible in a geometry shader. If a geometry shader is not
active, the adjacent vertices are ignored.
A line segment is drawn from the $i+1$ st vertex to the $i+2$ nd vertex for each $i=0,1,\ldots, n-1$ , where there are $n+3$ vertices. If there are fewer than four vertices, all vertices are ignored. For line segment $i$ , the $i$ th and $i+3$ rd vertex are considered adjacent to the $i+1$ st and $i+2$ nd vertices, respectively, as shown in figure Figure 19.2, “Lines with adjacency”.
Triangles with adjacency are specified with topology
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY
, and are similar to
separate triangles except that each triangle edge has an adjacent vertex
that is accessible in a geometry shader. If a geometry shader is not
active, the adjacent vertices are ignored.
The $6i$ th, $6i+2$ nd, and $6i+4$ th vertices (in that order) determine a triangle for each $i=0,1, \ldots, n-1$ , where there are $6 n+k$ vertices. $k$ is either 0, 1, 2, 3, 4, or 5; if $k$ is non-zero, the final $k$ vertices are ignored. For triangle $i$ , the $6 i+1$ st, $6 i+3$ rd, and $6 i+5$ th vertices are considered adjacent to edges from the $6 i$ th to the $6 i+2$ nd, from the $6 i+2$ nd to the $6 i+4$ th, and from the $6 i+4$ th to the $6 i$ th vertices, respectively, as shown in figure Figure 19.3, “Triangles with adjacency”.
![]() | editing-note |
---|---|
TODO: Add full caption: Triangles with adjacency. The vertices connected with solid lines belong to the main primitive; the vertices connected by dashed lines are the adjacent vertices that are accessible in a geometry shader.} |
Triangle strips with adjacency are specified with topology
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY
, and are similar
to triangle strips except that each triangle edge has an adjacent vertex
that is accessible in a geometry shader. If a geometry shader is not
active, the adjacent vertices are ignored.
In triangle strips with adjacency, $n$ triangles are drawn where there are $2(n+2)+k$ vertices. $k$ is either 0 or 1; if $k$ is 1, the final vertex is ignored. If there are fewer than 6 vertices, the entire primitive is ignored. Table Table 19.1, “Triangles generated by triangle strips with adjacency.” describes the vertices and order used to draw each triangle, and which vertices are considered adjacent to each edge of the triangle, as shown in figure Figure 19.4, “Triangle strips with adjacency”.
Table 19.1. Triangles generated by triangle strips with adjacency.
Primitive Vertices | Adjacent Vertices | |||||
---|---|---|---|---|---|---|
Primitive | 1st | 2nd | 3rd | 1/2 | 2/3 | 3/1 |
only ( $i=0$ , $n=1$ ) | 0 | 2 | 4 | 1 | 5 | 3 |
first ( $i=0$ ) | 0 | 2 | 4 | 1 | 6 | 3 |
middle ( $i$ odd) | $2 i+2$ | $2 i $ | $2 i+4$ | $2 i-2$ | $2 i+3$ | $2 i+6$ |
middle ( $i$ even) | $2 i $ | $2 i+2$ | $2 i+4$ | $2 i-2$ | $2 i+6$ | $2 i+3$ |
last ( $i=n-1$ , $i$ odd) | $2 i+2$ | $2 i $ | $2 i+4$ | $2 i-2$ | $2 i+3$ | $2 i+5$ |
last ( $i=n-1$ , $i$ even) | $2 i $ | $2 i+2$ | $2 i+4$ | $2 i-2$ | $2 i+5$ | $2 i+3$ |
![]() | editing-note |
---|---|
TODO: Add full caption: Triangles generated by triangle strips with adjacency. Each triangle is drawn using the vertices whose numbers are in the 1st, 2nd, and 3rd columns under primitive vertices, in that order. The vertices in the 1/2, 2/3, and 3/1 columns under adjacent vertices are considered adjacent to the edges from the first to the second, from the second to the third, and from the third to the first vertex of the triangle, respectively. The six rows correspond to six cases: the first and only triangle $(i=0, n=1)$ , the first triangle of several $(i=0, n>0)$ , “odd” middle triangles $(i=1,3,5 \ldots)$ , “even” middle triangles $(i=2,4,6,\ldots)$ , and special cases for the last triangle, when $i$ is either even or odd. For the purposes of this table, both the first vertex and first triangle are numbered $0$ . |
![]() | editing-note |
---|---|
TODO: Add full caption: Triangle strips with adjacency. The vertices connected with solid lines belong to the main primitives; the vertices connected by dashed lines are the adjacent vertices that are accessible in a geometry shader. |
Separate patches are specified with topology
VK_PRIMITIVE_TOPOLOGY_PATCH_LIST
. A patch is an ordered collection of
vertices used for primitive tessellation. The
vertices comprising a patch have no implied geometric ordering, and are used
by tessellation shaders and the fixed-function tessellator to generate new
point, line, or triangle primitives.
Each patch in the series has a fixed number of vertices, specified by the
patchControlPoints
member of the
VkPipelineTessellationStateCreateInfo
structure passed to
vkCreateGraphicsPipelines
. Once assembled and vertex shaded, these
patches are provided as input to the tessellation control shader stage.
If the number of vertices in a patch is given by $v$ , the $v i$ th through $v i+v-1$ st vertices (in that order) determine a patch for each $i=0,1,\dots n-1$ , where there are $v n+k$ vertices. $k$ is in the range $[0,v-1]$ ; if $k$ is not zero, the final $k$ vertices are ignored.
Depending on the polygon mode, a polygon
primitive generated from a drawing command with topology
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN
,
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP
,
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST
,
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY
, or
VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY
is rendered in
one of several ways, such as outlining its border or filling its interior.
The order of vertices in such a primitive is significant during
polygon rasterization and
fragment shading.