1// Copyright 2015-2021 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[[geometry-output]] 80== Geometry Shader Output Primitives 81 82A geometry shader generates primitives in one of three output modes: points, 83line strips, or triangle strips. 84The primitive mode is specified in the shader using an code:OpExecutionMode 85instruction with the code:OutputPoints, code:OutputLineStrip or 86code:OutputTriangleStrip modes, respectively. 87Each geometry shader must: include exactly one output primitive mode. 88 89The vertices output by the geometry shader are assembled into points, lines, 90or triangles based on the output primitive type and the resulting primitives 91are then further processed as described in <<primsrast>>. 92If the number of vertices emitted by the geometry shader is not sufficient 93to produce a single primitive, vertices corresponding to incomplete 94primitives are not processed by subsequent pipeline stages. 95The number of vertices output by the geometry shader is limited to a maximum 96count specified in the shader. 97 98The maximum output vertex count is specified in the shader using an 99code:OpExecutionMode instruction with the mode set to code:OutputVertices 100and the maximum number of vertices that will be produced by the geometry 101shader specified as a literal. 102Each geometry shader must: specify a maximum output vertex count. 103 104 105[[geometry-invocations]] 106== Multiple Invocations of Geometry Shaders 107 108Geometry shaders can: be invoked more than one time for each input 109primitive. 110This is known as _geometry shader instancing_ and is requested by including 111an code:OpExecutionMode instruction with code:mode specified as 112code:Invocations and the number of invocations specified as an integer 113literal. 114 115In this mode, the geometry shader will execute at least [eq]#n# times for 116each input primitive, where [eq]#n# is the number of invocations specified 117in the code:OpExecutionMode instruction. 118The instance number is available to each invocation as a built-in input 119using code:InvocationId. 120 121 122[[geometry-ordering]] 123== Geometry Shader Primitive Ordering 124 125Limited guarantees are provided for the relative ordering of primitives 126produced by a geometry shader, as they pertain to <<drawing-primitive-order, 127primitive 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 137ifdef::VK_NV_geometry_shader_passthrough[] 138[[geometry-passthrough]] 139== Geometry Shader Passthrough 140 141A geometry shader that uses the code:PassthroughNV decoration on a variable 142in its input interface is considered a _passthrough geometry shader_. 143Output primitives in a passthrough geometry shader must: have the same 144topology as the input primitive and are not produced by emitting vertices. 145The vertices of the output primitive have two different types of attributes, 146per-vertex and per-primitive. 147Geometry shader input variables with code:PassthroughNV decoration are 148considered to produce per-vertex outputs, where values for each output 149vertex are copied from the corresponding input vertex. 150Any built-in or user-defined geometry shader outputs are considered 151per-primitive in a passthrough geometry shader, where a single output value 152is copied to all output vertices. 153 154The remainder of this section details the usage of the code:PassthroughNV 155decoration and modifications to the interface matching rules when using 156passthrough geometry shaders. 157 158 159[[geometry-passthrough-passthrough]] 160=== code:PassthroughNV Decoration 161 162Decorating a geometry shader input variable with the code:PassthroughNV 163decoration indicates that values of this input are copied through to the 164corresponding vertex of the output primitive. 165Input variables and block members which do not have the code:PassthroughNV 166decoration are consumed by the geometry shader without being passed through 167to subsequent stages. 168 169The code:PassthroughNV decoration must: only be used within a geometry 170shader. 171 172Any variable decorated with code:PassthroughNV must: be declared using the 173code:Input storage class. 174 175The 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 191When a passthrough geometry shader is in use, the 192<<interfaces-iointerfaces-matching,Interface Matching>> rules involving the 193geometry shader input and output interfaces operate as described in this 194section. 195 196For the purposes of matching passthrough geometry shader inputs with outputs 197of the previous pipeline stages, the code:PassthroughNV decoration is 198ignored. 199 200For the purposes of matching the outputs of the geometry shader with 201subsequent pipeline stages, each input variable with the code:PassthroughNV 202decoration is considered to add an equivalent output variable with the same 203type, decoration (other than code:PassthroughNV), number, and declaration 204order on the output interface. 205The output variable declaration corresponding to an input variable decorated 206with code:PassthroughNV will be identical to the input declaration, except 207that the outermost array dimension of such variables is removed. 208The output block declaration corresponding to an input block decorated with 209code:PassthroughNV or having members decorated with code:PassthroughNV will 210be identical to the input declaration, except that the outermost array 211dimension of such declaration is removed. 212 213If an input block is decorated with code:PassthroughNV, the equivalent 214output block contains all the members of the input block. 215Otherwise, the equivalent output block contains only those input block 216members decorated with code:PassthroughNV. 217All members of the corresponding output block are assigned code:Location and 218code:Component decorations identical to those assigned to the corresponding 219input block members. 220 221Output variables and blocks generated from inputs decorated with 222code:PassthroughNV will only exist for the purposes of interface matching; 223these declarations are not available to geometry shader code or listed in 224the module interface. 225 226For the purposes of component counting, passthrough geometry shaders count 227all statically used input variable components declared with the 228code:PassthroughNV decoration as output components as well, since their 229values will be copied to the output primitive produced by the geometry 230shader. 231 232endif::VK_NV_geometry_shader_passthrough[] 233 234 235