1  // Copyright (c) 2015-2019 Khronos Group. This work is licensed under a
  2  // Creative Commons Attribution 4.0 International License; see
  3  // http://creativecommons.org/licenses/by/4.0/
  4  
  5  [[geometry]]
  6  = Geometry Shading
  7  
  8  The geometry shader operates on a group of vertices and their associated
  9  data assembled from a single input primitive, and emits zero or more output
 10  primitives and the group of vertices and their associated data required for
 11  each output primitive.
 12  Geometry shading is enabled when a geometry shader is included in the
 13  pipeline.
 14  
 15  
 16  [[geometry-input]]
 17  == Geometry Shader Input Primitives
 18  
 19  Each 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
 21  of inputs.
 22  
 23  The input primitive type expected by the geometry shader is specified with
 24  an code:OpExecutionMode instruction in the geometry shader, and must: match
 25  the incoming primitive type specified by either the pipeline's
 26  <<drawing-primitive-topologies, primitive topology>> if tessellation is
 27  inactive, or the <<tessellation, tessellation mode>> if tessellation is
 28  active, 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 that specifies 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 to that 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 to that 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  [[geometry-output]]
 80  == Geometry Shader Output Primitives
 81  
 82  A geometry shader generates primitives in one of three output modes: points,
 83  line strips, or triangle strips.
 84  The primitive mode is specified in the shader using an code:OpExecutionMode
 85  instruction with the code:OutputPoints, code:OutputLineStrip or
 86  code:OutputTriangleStrip modes, respectively.
 87  Each geometry shader must: include exactly one output primitive mode.
 88  
 89  The vertices output by the geometry shader are assembled into points, lines,
 90  or triangles based on the output primitive type and the resulting primitives
 91  are then further processed as described in <<primsrast>>.
 92  If the number of vertices emitted by the geometry shader is not sufficient
 93  to produce a single primitive, vertices corresponding to incomplete
 94  primitives are not processed by subsequent pipeline stages.
 95  The number of vertices output by the geometry shader is limited to a maximum
 96  count specified in the shader.
 97  
 98  The maximum output vertex count is specified in the shader using an
 99  code:OpExecutionMode instruction with the mode set to code:OutputVertices
100  and the maximum number of vertices that will be produced by the geometry
101  shader specified as a literal.
102  Each geometry shader must: specify a maximum output vertex count.
103  
104  
105  [[geometry-invocations]]
106  == Multiple Invocations of Geometry Shaders
107  
108  Geometry shaders can: be invoked more than one time for each input
109  primitive.
110  This is known as _geometry shader instancing_ and is requested by including
111  an code:OpExecutionMode instruction with code:mode specified as
112  code:Invocations and the number of invocations specified as an integer
113  literal.
114  
115  In this mode, the geometry shader will execute at least [eq]#n# times for
116  each input primitive, where [eq]#n# is the number of invocations specified
117  in the code:OpExecutionMode instruction.
118  The instance number is available to each invocation as a built-in input
119  using code:InvocationId.
120  
121  
122  [[geometry-ordering]]
123  == Geometry Shader Primitive Ordering
124  
125  Limited guarantees are provided for the relative ordering of primitives
126  produced by a geometry shader, as they pertain to <<drawing-primitive-order,
127  primitive order>>.
128  
129    * For instanced geometry shaders, the output primitives generated from
130      each input primitive are passed to subsequent pipeline stages using the
131      invocation number to order the primitives, from least to greatest.
132    * All output primitives generated from a given input primitive are passed
133      to subsequent pipeline stages before any output primitives generated
134      from subsequent input primitives.
135  
136  
137  ifdef::VK_NV_geometry_shader_passthrough[]
138  [[geometry-passthrough]]
139  == Geometry Shader Passthrough
140  
141  A geometry shader that uses the code:PassthroughNV decoration on a variable
142  in its input interface is considered a _passthrough geometry shader_.
143  Output primitives in a passthrough geometry shader must: have the same
144  topology as the input primitive and are not produced by emitting vertices.
145  The vertices of the output primitive have two different types of attributes,
146  per-vertex and per-primitive.
147  Geometry shader input variables with code:PassthroughNV decoration are
148  considered to produce per-vertex outputs, where values for each output
149  vertex are copied from the corresponding input vertex.
150  Any built-in or user-defined geometry shader outputs are considered
151  per-primitive in a passthrough geometry shader, where a single output value
152  is copied to all output vertices.
153  
154  The remainder of this section details the usage of the code:PassthroughNV
155  decoration and modifications to the interface matching rules when using
156  passthrough geometry shaders.
157  
158  
159  [[geometry-passthrough-passthrough]]
160  === code:PassthroughNV Decoration
161  
162  Decorating a geometry shader input variable with the code:PassthroughNV
163  decoration indicates that values of this input are copied through to the
164  corresponding vertex of the output primitive.
165  Input variables and block members which do not have the code:PassthroughNV
166  decoration are consumed by the geometry shader without being passed through
167  to subsequent stages.
168  
169  The code:PassthroughNV decoration must: only be used within a geometry
170  shader.
171  
172  Any variable decorated with code:PassthroughNV must: be declared using the
173  code:Input storage class.
174  
175  The code:PassthroughNV decoration must: not be used with any of:
176  
177    * an input primitive type other than code:InputPoints, code:InputLines, or
178      code:Triangles, as specified by the mode for code:OpExecutionMode.
179    * an invocation count other than one, as specified by the code:Invocations
180      mode for code:OpExecutionMode.
181    * an code:OpEntryPoint which statically uses the code:OpEmitVertex or
182      code:OpEndPrimitive instructions.
183    * a variable decorated with the code:InvocationId built-in decoration.
184    * a variable decorated with the code:PrimitiveId built-in decoration that
185      is declared using the code:Input storage class.
186  
187  
188  [[geometry-passthrough-interface]]
189  === Passthrough Interface Matching
190  
191  When a passthrough geometry shader is in use, the
192  <<interfaces-iointerfaces-matching,Interface Matching>> rules involving the
193  geometry shader input and output interfaces operate as described in this
194  section.
195  
196  For the purposes of matching passthrough geometry shader inputs with outputs
197  of the previous pipeline stages, the code:PassthroughNV decoration is
198  ignored.
199  
200  For the purposes of matching the outputs of the geometry shader with
201  subsequent pipeline stages, each input variable with the code:PassthroughNV
202  decoration is considered to add an equivalent output variable with the same
203  type, decoration (other than code:PassthroughNV), number, and declaration
204  order on the output interface.
205  The output variable declaration corresponding to an input variable decorated
206  with code:PassthroughNV will be identical to the input declaration, except
207  that the outermost array dimension of such variables is removed.
208  The output block declaration corresponding to an input block decorated with
209  code:PassthroughNV or having members decorated with code:PassthroughNV will
210  be identical to the input declaration, except that the outermost array
211  dimension of such declaration is removed.
212  
213  If an input block is decorated with code:PassthroughNV, the equivalent
214  output block contains all the members of the input block.
215  Otherwise, the equivalent output block contains only those input block
216  members decorated with code:PassthroughNV.
217  All members of the corresponding output block are assigned code:Location and
218  code:Component decorations identical to those assigned to the corresponding
219  input block members.
220  
221  Output variables and blocks generated from inputs decorated with
222  code:PassthroughNV will only exist for the purposes of interface matching;
223  these declarations are not available to geometry shader code or listed in
224  the module interface.
225  
226  For the purposes of component counting, passthrough geometry shaders count
227  all statically used input variable components declared with the
228  code:PassthroughNV decoration as output components as well, since their
229  values will be copied to the output primitive produced by the geometry
230  shader.
231  
232  endif::VK_NV_geometry_shader_passthrough[]
233  
234