1// Copyright (c) 2015-2018 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 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. 22The input primitive type expected by the geometry shader is specified with 23an code:OpExecutionMode instruction in the geometry shader, and must: be 24compatible with the primitive topology used by primitive assembly (if 25tessellation is not in use) or must: match the type of primitive generated 26by the tessellation primitive generator (if tessellation is in use). 27Compatibility is defined below, with each input primitive type. 28The input primitive types accepted by a geometry shader are: 29 30Points:: 31 32Geometry shaders that operate on points use an code:OpExecutionMode 33instruction specifying the code:InputPoints input mode. 34Such a shader is valid only when the pipeline primitive topology is 35code:VK_PRIMITIVE_TOPOLOGY_POINT_LIST (if tessellation is not in use) or if 36tessellation is in use and the tessellation evaluation shader uses 37code:PointMode. 38There is only a single input vertex available for each geometry shader 39invocation. 40However, inputs to the geometry shader are still presented as an array, but 41this array has a length of one. 42 43Lines:: 44 45Geometry shaders that operate on line segments are generated by including an 46code:OpExecutionMode instruction with the code:InputLines mode. 47Such a shader is valid only for the code:VK_PRIMITIVE_TOPOLOGY_LINE_LIST, 48and code:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP primitive topologies (if 49tessellation is not in use) or if tessellation is in use and the 50tessellation mode is code:Isolines. 51There are two input vertices available for each geometry shader invocation. 52The first vertex refers to the vertex at the beginning of the line segment 53and the second vertex refers to the vertex at the end of the line segment. 54 55Lines with Adjacency:: 56 57Geometry shaders that operate on line segments with adjacent vertices are 58generated by including an code:OpExecutionMode instruction with the 59code:InputLinesAdjacency mode. 60Such a shader is valid only for the 61code:VK_PRIMITIVE_TOPOLOGY_LINES_WITH_ADJACENCY and 62code:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY primitive topologies 63and must: not be used when tessellation is in use. 64+ 65In this mode, there are four vertices available for each geometry shader 66invocation. 67The second vertex refers to attributes of the vertex at the beginning of the 68line segment and the third vertex refers to the vertex at the end of the 69line segment. 70The first and fourth vertices refer to the vertices adjacent to the 71beginning and end of the line segment, respectively. 72 73Triangles:: 74 75Geometry shaders that operate on triangles are created by including an 76code:OpExecutionMode instruction with the code:Triangles mode. 77Such a shader is valid when the pipeline topology is 78code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST, 79code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP, or 80code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN (if tessellation is not in use) or 81when tessellation is in use and the tessellation mode is code:Triangles or 82code:Quads. 83+ 84In this mode, there are three vertices available for each geometry shader 85invocation. 86The first, second, and third vertices refer to attributes of the first, 87second, and third vertex of the triangle, respectively. 88 89Triangles with Adjacency:: 90 91Geometry shaders that operate on triangles with adjacent vertices are 92created by including an code:OpExecutionMode instruction with the 93code:InputTrianglesAdjacency mode. 94Such a shader is valid when the pipeline topology is 95code:VK_PRIMITIVE_TOPOLOGY_TRIANGLES_WITH_ADJACENCY or 96code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY, and must: not be 97used when tessellation is in use. 98+ 99In this mode, there are six vertices available for each geometry shader 100invocation. 101The first, third and fifth vertices refer to attributes of the first, second 102and third vertex of the triangle, respectively. 103The second, fourth and sixth vertices refer to attributes of the vertices 104adjacent to the edges from the first to the second vertex, from the second 105to the third vertex, and from the third to the first vertex, respectively. 106 107 108[[geometry-output]] 109== Geometry Shader Output Primitives 110 111A geometry shader generates primitives in one of three output modes: points, 112line strips, or triangle strips. 113The primitive mode is specified in the shader using an code:OpExecutionMode 114instruction with the code:OutputPoints, code:OutputLineStrip or 115code:OutputTriangleStrip modes, respectively. 116Each geometry shader must: include exactly one output primitive mode. 117 118The vertices output by the geometry shader are assembled into points, lines, 119or triangles based on the output primitive type and the resulting primitives 120are then further processed as described in <<primsrast>>. 121If the number of vertices emitted by the geometry shader is not sufficient 122to produce a single primitive, vertices corresponding to incomplete 123primitives are not processed by subsequent pipeline stages. 124The number of vertices output by the geometry shader is limited to a maximum 125count specified in the shader. 126 127The maximum output vertex count is specified in the shader using an 128code:OpExecutionMode instruction with the mode set to code:OutputVertices 129and the maximum number of vertices that will be produced by the geometry 130shader specified as a literal. 131Each geometry shader must: specify a maximum output vertex count. 132 133 134[[geometry-invocations]] 135== Multiple Invocations of Geometry Shaders 136 137Geometry shaders can: be invoked more than one time for each input 138primitive. 139This is known as _geometry shader instancing_ and is requested by including 140an code:OpExecutionMode instruction with code:mode specified as 141code:Invocations and the number of invocations specified as an integer 142literal. 143 144In this mode, the geometry shader will execute at least [eq]#n# times for 145each input primitive, where [eq]#n# is the number of invocations specified 146in the code:OpExecutionMode instruction. 147The instance number is available to each invocation as a built-in input 148using code:InvocationId. 149 150 151[[geometry-ordering]] 152== Geometry Shader Primitive Ordering 153 154Limited guarantees are provided for the relative ordering of primitives 155produced by a geometry shader, as they pertain to <<drawing-primitive-order, 156primitive order>>. 157 158 * For instanced geometry shaders, the output primitives generated from 159 each input primitive are passed to subsequent pipeline stages using the 160 invocation number to order the primitives, from least to greatest. 161 * All output primitives generated from a given input primitive are passed 162 to subsequent pipeline stages before any output primitives generated 163 from subsequent input primitives. 164 165 166ifdef::VK_NV_geometry_shader_passthrough[] 167[[geometry-passthrough]] 168== Geometry Shader Passthrough 169 170A geometry shader that uses the code:PassthroughNV decoration on a variable 171in its input interface is considered a _passthrough geometry shader_. 172Output primitives in a passthrough geometry shader must: have the same 173topology as the input primitive and are not produced by emitting vertices. 174The vertices of the output primitive have two different types of attributes, 175per-vertex and per-primitive. 176Geometry shader input variables with code:PassthroughNV decoration are 177considered to produce per-vertex outputs, where values for each output 178vertex are copied from the corresponding input vertex. 179Any built-in or user-defined geometry shader outputs are considered 180per-primitive in a passthrough geometry shader, where a single output value 181is copied to all output vertices. 182 183The remainder of this section details the usage of the code:PassthroughNV 184decoration and modifications to the interface matching rules when using 185passthrough geometry shaders. 186 187 188[[geometry-passthrough-passthrough]] 189=== code:PassthroughNV Decoration 190 191Decorating a geometry shader input variable with the code:PassthroughNV 192decoration indicates that values of this input are copied through to the 193corresponding vertex of the output primitive. 194Input variables and block members which do not have the code:PassthroughNV 195decoration are consumed by the geometry shader without being passed through 196to subsequent stages. 197 198The code:PassthroughNV decoration must: only be used within a geometry 199shader. 200 201Any variable decorated with code:PassthroughNV must: be declared using the 202code:Input storage class. 203 204The code:PassthroughNV decoration must: not be used with any of: 205 206 * an input primitive type other than code:InputPoints, code:InputLines, or 207 code:Triangles, as specified by the mode for code:OpExecutionMode. 208 * an invocation count other than one, as specified by the code:Invocations 209 mode for code:OpExecutionMode. 210 * an code:OpEntryPoint which statically uses the code:OpEmitVertex or 211 code:OpEndPrimitive instructions. 212 * a variable decorated with the code:InvocationId built-in decoration. 213 * a variable decorated with the code:PrimitiveId built-in decoration that 214 is declared using the code:Input storage class. 215 216 217[[geometry-passthrough-interface]] 218=== Passthrough Interface Matching 219 220When a passthrough geometry shader is in use, the 221<<interfaces-iointerfaces-matching,Interface Matching>> rules involving the 222geometry shader input and output interfaces operate as described in this 223section. 224 225For the purposes of matching passthrough geometry shader inputs with outputs 226of the previous pipeline stages, the code:PassthroughNV decoration is 227ignored. 228 229For the purposes of matching the outputs of the geometry shader with 230subsequent pipeline stages, each input variable with the code:PassthroughNV 231decoration is considered to add an equivalent output variable with the same 232type, decoration (other than code:PassthroughNV), number, and declaration 233order on the output interface. 234The output variable declaration corresponding to an input variable decorated 235with code:PassthroughNV will be identical to the input declaration, except 236that the outermost array dimension of such variables is removed. 237The output block declaration corresponding to an input block decorated with 238code:PassthroughNV or having members decorated with code:PassthroughNV will 239be identical to the input declaration, except that the outermost array 240dimension of such declaration is removed. 241 242If an input block is decorated with code:PassthroughNV, the equivalent 243output block contains all the members of the input block. 244Otherwise, the equivalent output block contains only those input block 245members decorated with code:PassthroughNV. 246All members of the corresponding output block are assigned code:Location and 247code:Component decorations identical to those assigned to the corresponding 248input block members. 249 250Output variables and blocks generated from inputs decorated with 251code:PassthroughNV will only exist for the purposes of interface matching; 252these declarations are not available to geometry shader code or listed in 253the module interface. 254 255For the purposes of component counting, passthrough geometry shaders count 256all statically used input variable components declared with the 257code:PassthroughNV decoration as output components as well, since their 258values will be copied to the output primitive produced by the geometry 259shader. 260 261endif::VK_NV_geometry_shader_passthrough[] 262 263 264