1// Copyright 2015-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[geometry]]
6= Geometry Shading
7
8The geometry shader operates on a group of vertices and their associated
9data assembled from a single input primitive, and emits zero or more output
10primitives and the group of vertices and their associated data required for
11each output primitive.
12Geometry shading is enabled when a geometry shader is included in the
13pipeline.
14
15
16[[geometry-input]]
17== Geometry Shader Input Primitives
18
19Each geometry shader invocation has access to all vertices in the primitive
20(and their associated data), which are presented to the shader as an array
21of inputs.
22
23The input primitive type expected by the geometry shader is specified with
24an code:OpExecutionMode instruction in the geometry shader, and must: match
25the incoming primitive type specified by either the pipeline's
26<<drawing-primitive-topologies, primitive topology>> if tessellation is
27inactive, or the <<tessellation, tessellation mode>> if tessellation is
28active, as follows:
29
30  * An input primitive type of code:InputPoints must: only be used with a
31    pipeline topology of ename:VK_PRIMITIVE_TOPOLOGY_POINT_LIST, or with a
32    tessellation shader specifying code:PointMode.
33    The input arrays always contain one element, as described by the
34    <<drawing-point-lists, point list topology>> or
35    <<tessellation-point-mode, tessellation in point mode>>.
36  * An input primitive type of code:InputLines must: only be used with a
37    pipeline topology of ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST or
38    ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP, or with a tessellation shader
39    specifying code:IsoLines that does not specify code:PointMode.
40    The input arrays always contain two elements, as described by the
41    <<drawing-line-lists, line list topology>> or <<drawing-line-strips,
42    line strip topology>>, or by <<tessellation-isoline-tessellation,
43    isoline tessellation>>.
44  * An input primitive type of code:InputLinesAdjacency must: only be used
45    when tessellation is inactive, with a pipeline topology of
46    ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY or
47    ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY.
48    The input arrays always contain four elements, as described by the
49    <<drawing-line-lists-with-adjacency, line list with adjacency topology>>
50    or <<drawing-line-strips-with-adjacency, line strip with adjacency
51    topology>>.
52  * An input primitive type of code:Triangles must: only be used with a
53    pipeline topology of ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST,
54    ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP, or
55    ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN; or with a tessellation shader
56    specifying code:Quads or code:Triangles that does not specify
57    code:PointMode.
58    The input arrays always contain three elements, as described by the
59    <<drawing-triangle-lists, triangle list topology>>,
60    <<drawing-triangle-strips, triangle strip topology>>, or
61    <<drawing-triangle-fans, triangle fan topology>>, or by
62    <<tessellation-triangle-tessellation, triangle>> or
63    <<tessellation-quad-tessellation, quad tessellation>>.
64    Vertices may: be in a different absolute order than specified by the
65    topology, but must: adhere to the specified winding order.
66  * An input primitive type of code:InputTrianglesAdjacency must: only be
67    used when tessellation is inactive, with a pipeline topology of
68    ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY or
69    ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY.
70    The input arrays always contain six elements, as described by the
71    <<drawing-triangle-lists-with-adjacency, triangle list with adjacency
72    topology>> or <<drawing-triangle-strips-with-adjacency, triangle strip
73    with adjacency topology>>.
74    Vertices may: be in a different absolute order than specified by the
75    topology, but must: adhere to the specified winding order, and the
76    vertices making up the main primitive must: still occur at the first,
77    third, and fifth index.
78
79
80[[geometry-output]]
81== Geometry Shader Output Primitives
82
83A geometry shader generates primitives in one of three output modes: points,
84line strips, or triangle strips.
85The primitive mode is specified in the shader using an code:OpExecutionMode
86instruction with the code:OutputPoints, code:OutputLineStrip or
87code:OutputTriangleStrip modes, respectively.
88Each geometry shader must: include exactly one output primitive mode.
89
90The vertices output by the geometry shader are assembled into points, lines,
91or triangles based on the output primitive type and the resulting primitives
92are then further processed as described in <<primsrast>>.
93If the number of vertices emitted by the geometry shader is not sufficient
94to produce a single primitive, vertices corresponding to incomplete
95primitives are not processed by subsequent pipeline stages.
96The number of vertices output by the geometry shader is limited to a maximum
97count specified in the shader.
98
99The maximum output vertex count is specified in the shader using an
100code:OpExecutionMode instruction with the mode set to code:OutputVertices
101and the maximum number of vertices that will be produced by the geometry
102shader specified as a literal.
103Each geometry shader must: specify a maximum output vertex count.
104
105
106[[geometry-invocations]]
107== Multiple Invocations of Geometry Shaders
108
109Geometry shaders can: be invoked more than one time for each input
110primitive.
111This is known as _geometry shader instancing_ and is requested by including
112an code:OpExecutionMode instruction with code:mode specified as
113code:Invocations and the number of invocations specified as an integer
114literal.
115
116In this mode, the geometry shader will execute at least [eq]#n# times for
117each input primitive, where [eq]#n# is the number of invocations specified
118in the code:OpExecutionMode instruction.
119The instance number is available to each invocation as a built-in input
120using code:InvocationId.
121
122
123[[geometry-ordering]]
124== Geometry Shader Primitive Ordering
125
126Limited guarantees are provided for the relative ordering of primitives
127produced by a geometry shader, as they pertain to <<drawing-primitive-order,
128primitive order>>.
129
130  * For instanced geometry shaders, the output primitives generated from
131    each input primitive are passed to subsequent pipeline stages using the
132    invocation number to order the primitives, from least to greatest.
133  * All output primitives generated from a given input primitive are passed
134    to subsequent pipeline stages before any output primitives generated
135    from subsequent input primitives.
136
137
138ifdef::VK_NV_geometry_shader_passthrough[]
139[[geometry-passthrough]]
140== Geometry Shader Passthrough
141
142A geometry shader that uses the code:PassthroughNV decoration on a variable
143in its input interface is considered a _passthrough geometry shader_.
144Output primitives in a passthrough geometry shader must: have the same
145topology as the input primitive and are not produced by emitting vertices.
146The vertices of the output primitive have two different types of attributes,
147per-vertex and per-primitive.
148Geometry shader input variables with code:PassthroughNV decoration are
149considered to produce per-vertex outputs, where values for each output
150vertex are copied from the corresponding input vertex.
151Any built-in or user-defined geometry shader outputs are considered
152per-primitive in a passthrough geometry shader, where a single output value
153is copied to all output vertices.
154
155The remainder of this section details the usage of the code:PassthroughNV
156decoration and modifications to the interface matching rules when using
157passthrough geometry shaders.
158
159
160[[geometry-passthrough-passthrough]]
161=== code:PassthroughNV Decoration
162
163Decorating a geometry shader input variable with the code:PassthroughNV
164decoration indicates that values of this input are copied through to the
165corresponding vertex of the output primitive.
166Input variables and block members which do not have the code:PassthroughNV
167decoration are consumed by the geometry shader without being passed through
168to subsequent stages.
169
170The code:PassthroughNV decoration must: only be used within a geometry
171shader.
172
173Any variable decorated with code:PassthroughNV must: be declared using the
174code:Input storage class.
175
176The code:PassthroughNV decoration must: not be used with any of:
177
178  * an input primitive type other than code:InputPoints, code:InputLines, or
179    code:Triangles, as specified by the mode for code:OpExecutionMode.
180  * an invocation count other than one, as specified by the code:Invocations
181    mode for code:OpExecutionMode.
182  * an code:OpEntryPoint which statically uses the code:OpEmitVertex or
183    code:OpEndPrimitive instructions.
184  * a variable decorated with the code:InvocationId built-in decoration.
185  * a variable decorated with the code:PrimitiveId built-in decoration that
186    is declared using the code:Input storage class.
187
188
189[[geometry-passthrough-interface]]
190=== Passthrough Interface Matching
191
192When a passthrough geometry shader is in use, the
193<<interfaces-iointerfaces-matching,Interface Matching>> rules involving the
194geometry shader input and output interfaces operate as described in this
195section.
196
197For the purposes of matching passthrough geometry shader inputs with outputs
198of the previous pipeline stages, the code:PassthroughNV decoration is
199ignored.
200
201For the purposes of matching the outputs of the geometry shader with
202subsequent pipeline stages, each input variable with the code:PassthroughNV
203decoration is considered to add an equivalent output variable with the same
204type, decoration (other than code:PassthroughNV), number, and declaration
205order on the output interface.
206The output variable declaration corresponding to an input variable decorated
207with code:PassthroughNV will be identical to the input declaration, except
208that the outermost array dimension of such variables is removed.
209The output block declaration corresponding to an input block decorated with
210code:PassthroughNV or having members decorated with code:PassthroughNV will
211be identical to the input declaration, except that the outermost array
212dimension of such declaration is removed.
213
214If an input block is decorated with code:PassthroughNV, the equivalent
215output block contains all the members of the input block.
216Otherwise, the equivalent output block contains only those input block
217members decorated with code:PassthroughNV.
218All members of the corresponding output block are assigned code:Location and
219code:Component decorations identical to those assigned to the corresponding
220input block members.
221
222Output variables and blocks generated from inputs decorated with
223code:PassthroughNV will only exist for the purposes of interface matching;
224these declarations are not available to geometry shader code or listed in
225the module interface.
226
227For the purposes of component counting, passthrough geometry shaders count
228all statically used input variable components declared with the
229code:PassthroughNV decoration as output components as well, since their
230values will be copied to the output primitive produced by the geometry
231shader.
232
233endif::VK_NV_geometry_shader_passthrough[]
234
235
236