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

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

[[geometry]]
= Geometry Shading

The geometry shader operates on a group of vertices and their associated
data assembled from a single input primitive, and emits zero or more
output primitives and the group of vertices and their associated data
required for each output primitive. Geometry shading is enabled when a
geometry shader is included in the pipeline.


[[geometry-input]]
== Geometry Shader Input Primitives

Each geometry shader invocation has access to all vertices in the primitive
(and their associated data), which are presented to the shader as an array
of inputs. The input primitive type expected by the geometry shader is
specified with an code:OpExecutionMode instruction in the geometry shader,
and must: be compatible with the primitive topology used by primitive
assembly (if tessellation is not in use) or must: match the type of
primitive generated by the tessellation primitive generator (if tessellation
is in use). Compatibility is defined below, with each input primitive type.
The input primitive types accepted by a geometry shader are:

Points::

Geometry shaders that operate on points use an code:OpExecutionMode
instruction specifing the code:InputPoints input mode. Such a shader is
valid only when the pipeline primitive topology is
code:VK_PRIMITIVE_TOPOLOGY_POINT_LIST (if tessellation is not in use) or if
tessellation is in use and the tessellation evaluation shader uses
code:PointMode. There is only a single input vertex available for each
geometry shader invocation. However, inputs to the geometry shader are still
presented as an array, but this array has a length of one.

Lines::

Geometry shaders that operate on line segments are generated by including an
code:OpExecutionMode instruction with the code:InputLines mode. Such a
shader is valid only for the code:VK_PRIMITIVE_TOPOLOGY_LINE_LIST, and
code:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP primitive topologies (if tessellation
is not in use) or if tessellation is in use and the tessellation mode is
code:Isolines. There are two input vertices available for each geometry
shader invocation. The first vertex refers to the vertex at the beginning of
the line segment and the second vertex refers to the vertex at the end of
the line segment.

Lines with Adjacency::

Geometry shaders that operate on line segments with adjacent vertices are
generated by including an code:OpExecutionMode instruction with the
code:InputLinesAdjacency mode. Such a shader is valid only for the
code:VK_PRIMITIVE_TOPOLOGY_LINES_WITH_ADJACENCY and
code:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY primitive topologies
and mustnot: be used when tessellation is in use.
+
In this mode, there are four vertices available for each geometry shader
invocation. The second vertex refers to attributes of the vertex at the
beginning of the line segment and the third vertex refers to the vertex at
the end of the line segment. The first and fourth vertices refer to the
vertices adjacent to the beginning and end of the line segment,
respectively.

Triangles::

Geometry shaders that operate on triangles are created by including an
code:OpExecutionMode instruction with the code:Triangles mode. Such a
shader is valid when the pipeline topology is
code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST,
code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP, or
code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN (if tessellation is not in use) or
when tessellation is in use and the tessellation mode is code:Triangles or
code:Quads.
+
In this mode, there are three vertices available for each geometry shader
invocation. The first, second, and third vertices refer to attributes of the
first, second, and third vertex of the triangle, respectively.

Triangles with Adjacency::

Geometry shaders that operate on triangles with adjacent vertices are
created by including an code:OpExecutionMode instruction with the
code:InputTrianglesAdjacency mode. Such a shader is valid when the pipeline
topology is code:VK_PRIMITIVE_TOPOLOGY_TRIANGLES_WITH_ADJACENCY or
code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY, and mustnot: be
used when tessellation is in use.
+
In this mode, there are six vertices available for each geometry shader
invocation. The first, third and fifth vertices refer to attributes of the
first, second and third vertex of the triangle, respectively. The second,
fourth and sixth vertices refer to attributes of the vertices adjacent to
the edges from the first to the second vertex, from the second to the third
vertex, and from the third to the first vertex, respectively.


[[geometry-output]]
== Geometry Shader Output Primitives

A geometry shader generates primitives in one of three output modes: points,
line strips, or triangle strips. The primitive mode is specified in the
shader using an code:OpExecutionMode instruction with the code:OutputPoints,
code:OutputLineStrip or code:OutputTriangleStrip modes, respectively. Each
geometry shader must: include exactly one output primitive mode.

The vertices output by the geometry shader are assembled into points, lines,
or triangles based on the output primitive type and the resulting primitives
are then further processed as described in <<primsrast>>. If the number of
vertices emitted by the geometry shader is not sufficient to produce a
single primitive, vertices corresponding to incomplete primitives are not
processed by subsequent pipeline stages. The number of vertices output by
the geometry shader is limited to a maximum count specified in the shader.

The maximum output vertex count is specified in the shader using an
code:OpExecutionMode instruction with the mode set to code:OutputVertices
and the maximum number of vertices that will be produced by the geometry
shader specified as a literal. Each geometry shader must: specify a maximum
output vertex count.


[[geometry-invocations]]
== Multiple Invocations of Geometry Shaders

Geometry shaders can: be invoked more than one time for each input
primitive. This is known as _geometry shader instancing_ and is requested by
including an code:OpExecutionMode instruction with code:mode specified as
code:Invocations and the number of invocations specified as an integer
literal.

In this mode, the geometry shader will execute latexmath:[$n$] times for
each input primitive, where latexmath:[$n$] is the number of invocations
specified in the code:OpExecutionMode instruction. The instance number is
available to each invocation as a built-in input using code:InvocationId.


[[geometry-ordering]]
== Geometry Shader Primitive Ordering

Limited guarantees are provided for the relative ordering of primitives
produced by a geometry shader.

  - For instanced geometry shaders, the output primitives generated from
    each input primitive are passed to subsequent pipeline stages using the
    invocation number to order the primitives, from least to greatest.
  - All output primitives generated from a given input primitive are passed
    to subsequent pipeline stages before any output primitives generated
    from subsequent input primitives.