19.1. Primitive Topologies

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.

19.1.1. Points

A series of individual points are specified with topology VK_PRIMITIVE_TOPOLOGY_POINT_LIST. Each vertex defines a separate point.

19.1.2. Separate Lines

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.

19.1.3. Line Strips

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.

19.1.4. Triangle Strips

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.

Figure 19.1. Triangle strips, fans, and lists

images/triangles.svg

[Note]editing-note

TODO: Add full caption:

  • (a) A triangle strip.
  • (b) A triangle fan.
  • (c) Independent triangles.

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.

19.1.5. Triangle Fans

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.

19.1.6. Separate Triangles

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.

19.1.7. Lines With Adjacency

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

Figure 19.2. Lines with adjacency

images/lineadj.svg

[Note]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.

19.1.8. Line Strips With Adjacency

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

19.1.9. Triangle List 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”.

Figure 19.3. Triangles with adjacency

images/triadj.svg

[Note]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.}

19.1.10. Triangle Strips With Adjacency

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$


[Note]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$ .

Figure 19.4. Triangle strips with adjacency

images/tstripadj.svg

[Note]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.

19.1.11. Separate Patches

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.

19.1.12. General Considerations For Polygon Primitives

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.