23. 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.
23.1. 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 OpExecutionMode
instruction in the geometry shader, and must match
the incoming primitive type specified by either the pipeline’s
primitive topology if tessellation is
inactive, or the tessellation mode if tessellation is
active, as follows:
-
An input primitive type of
InputPoints
must only be used with a pipeline topology ofVK_PRIMITIVE_TOPOLOGY_POINT_LIST
, or with a tessellation shader specifyingPointMode
. The input arrays always contain one element, as described by the point list topology or tessellation in point mode. -
An input primitive type of
InputLines
must only be used with a pipeline topology ofVK_PRIMITIVE_TOPOLOGY_LINE_LIST
orVK_PRIMITIVE_TOPOLOGY_LINE_STRIP
, or with a tessellation shader specifyingIsoLines
that does not specifyPointMode
. The input arrays always contain two elements, as described by the line list topology or line strip topology, or by isoline tessellation. -
An input primitive type of
InputLinesAdjacency
must only be used when tessellation is inactive, with a pipeline topology ofVK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY
orVK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY
. The input arrays always contain four elements, as described by the line list with adjacency topology or line strip with adjacency topology. -
An input primitive type of
Triangles
must only be used with a pipeline topology ofVK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST
,VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP
, orVK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN
; or with a tessellation shader specifyingQuads
orTriangles
that does not specifyPointMode
. The input arrays always contain three elements, as described by the triangle list topology, triangle strip topology, or triangle fan topology, or by triangle or quad tessellation. Vertices may be in a different absolute order than specified by the topology, but must adhere to the specified winding order. -
An input primitive type of
InputTrianglesAdjacency
must only be used when tessellation is inactive, with a pipeline topology ofVK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY
orVK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY
. The input arrays always contain six elements, as described by the triangle list with adjacency topology or triangle strip with adjacency topology. Vertices may be in a different absolute order than specified by the topology, but must adhere to the specified winding order, and the vertices making up the main primitive must still occur at the first, third, and fifth index.
23.2. 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 OpExecutionMode
instruction with the OutputPoints
, OutputLineStrip
or
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 Rasterization. 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
OpExecutionMode
instruction with the mode set to 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.
23.3. 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 OpExecutionMode
instruction with mode
specified as
Invocations
and the number of invocations specified as an integer
literal.
In this mode, the geometry shader will execute at least n times for
each input primitive, where n is the number of invocations specified
in the OpExecutionMode
instruction.
The instance number is available to each invocation as a built-in input
using InvocationId
.
23.4. Geometry Shader Primitive Ordering
Limited guarantees are provided for the relative ordering of primitives produced by a geometry shader, as they pertain to primitive order.
-
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.