// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ [[geometry]] = 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. [[geometry-input]] == 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 code:OpExecutionMode instruction in the geometry shader, and must: be compatible with the primitive topology used by primitive assembly (if tessellation is not in use) or must: match the type of primitive generated by the tessellation primitive generator (if tessellation is in use). Compatibility is defined below, with each input primitive type. The input primitive types accepted by a geometry shader are: Points:: Geometry shaders that operate on points use an code:OpExecutionMode instruction specifying the code:InputPoints input mode. Such a shader is valid only when the pipeline primitive topology is code:VK_PRIMITIVE_TOPOLOGY_POINT_LIST (if tessellation is not in use) or if tessellation is in use and the tessellation evaluation shader uses code:PointMode. There is only a single input vertex available for each geometry shader invocation. However, inputs to the geometry shader are still presented as an array, but this array has a length of one. Lines:: Geometry shaders that operate on line segments are generated by including an code:OpExecutionMode instruction with the code:InputLines mode. Such a shader is valid only for the code:VK_PRIMITIVE_TOPOLOGY_LINE_LIST, and code:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP primitive topologies (if tessellation is not in use) or if tessellation is in use and the tessellation mode is code:Isolines. There are two input vertices available for each geometry shader invocation. The first vertex refers to the vertex at the beginning of the line segment and the second vertex refers to the vertex at the end of the line segment. Lines with Adjacency:: Geometry shaders that operate on line segments with adjacent vertices are generated by including an code:OpExecutionMode instruction with the code:InputLinesAdjacency mode. Such a shader is valid only for the code:VK_PRIMITIVE_TOPOLOGY_LINES_WITH_ADJACENCY and code:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY primitive topologies and must: not be used when tessellation is in use. + In this mode, there are four vertices available for each geometry shader invocation. The second vertex refers to attributes of the vertex at the beginning of the line segment and the third vertex refers to the vertex at the end of the line segment. The first and fourth vertices refer to the vertices adjacent to the beginning and end of the line segment, respectively. Triangles:: Geometry shaders that operate on triangles are created by including an code:OpExecutionMode instruction with the code:Triangles mode. Such a shader is valid when the pipeline topology is code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST, code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP, or code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN (if tessellation is not in use) or when tessellation is in use and the tessellation mode is code:Triangles or code:Quads. + In this mode, there are three vertices available for each geometry shader invocation. The first, second, and third vertices refer to attributes of the first, second, and third vertex of the triangle, respectively. Triangles with Adjacency:: Geometry shaders that operate on triangles with adjacent vertices are created by including an code:OpExecutionMode instruction with the code:InputTrianglesAdjacency mode. Such a shader is valid when the pipeline topology is code:VK_PRIMITIVE_TOPOLOGY_TRIANGLES_WITH_ADJACENCY or code:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY, and must: not be used when tessellation is in use. + In this mode, there are six vertices available for each geometry shader invocation. The first, third and fifth vertices refer to attributes of the first, second and third vertex of the triangle, respectively. The second, fourth and sixth vertices refer to attributes of the vertices adjacent to the edges from the first to the second vertex, from the second to the third vertex, and from the third to the first vertex, respectively. [[geometry-output]] == 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 code:OpExecutionMode instruction with the code:OutputPoints, code:OutputLineStrip or code: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 <>. 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 code:OpExecutionMode instruction with the mode set to code: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. [[geometry-invocations]] == 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 code:OpExecutionMode instruction with code:mode specified as code:Invocations and the number of invocations specified as an integer literal. In this mode, the geometry shader will execute [eq]#n# times for each input primitive, where [eq]#n# is the number of invocations specified in the code:OpExecutionMode instruction. The instance number is available to each invocation as a built-in input using code:InvocationId. [[geometry-ordering]] == Geometry Shader Primitive Ordering Limited guarantees are provided for the relative ordering of primitives produced by a geometry shader, as they pertain to <>. * 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. ifdef::VK_NV_geometry_shader_passthrough[] [[geometry-passthrough]] == Geometry Shader Passthrough A geometry shader that uses the code:PassthroughNV decoration on a variable in its input interface is considered a _passthrough geometry shader_. Output primitives in a passthrough geometry shader must: have the same topology as the input primitive and are not produced by emitting vertices. The vertices of the output primitive have two different types of attributes, per-vertex and per-primitive. Geometry shader input variables with code:PassthroughNV decoration are considered to produce per-vertex outputs, where values for each output vertex are copied from the corresponding input vertex. Any built-in or user-defined geometry shader outputs are considered per-primitive in a passthrough geometry shader, where a single output value is copied to all output vertices. The remainder of this section details the usage of the code:PassthroughNV decoration and modifications to the interface matching rules when using passthrough geometry shaders. [[geometry-passthrough-passthrough]] === code:PassthroughNV Decoration Decorating a geometry shader input variable with the code:PassthroughNV decoration indicates that values of this input are copied through to the corresponding vertex of the output primitive. Input variables and block members which do not have the code:PassthroughNV decoration are consumed by the geometry shader without being passed through to subsequent stages. The code:PassthroughNV decoration must: only be used within a geometry shader. Any variable decorated with code:PassthroughNV must: be declared using the code:Input storage class. The code:PassthroughNV decoration must: not be used with any of: * an input primitive type other than code:InputPoints, code:InputLines, or code:Triangles, as specified by the mode for code:OpExecutionMode. * an invocation count other than one, as specified by the code:Invocations mode for code:OpExecutionMode. * an code:OpEntryPoint which statically uses the code:OpEmitVertex or code:OpEndPrimitive instructions. * a variable decorated with the code:InvocationId built-in decoration. * a variable decorated with the code:PrimitiveId built-in decoration that is declared using the code:Input storage class. [[geometry-passthrough-interface]] === Passthrough Interface Matching When a passthrough geometry shader is in use, the <> rules involving the geometry shader input and output interfaces operate as described in this section. For the purposes of matching passthrough geometry shader inputs with outputs of the previous pipeline stages, the code:PassthroughNV decoration is ignored. For the purposes of matching the outputs of the geometry shader with subsequent pipeline stages, each input variable with the code:PassthroughNV decoration is considered to add an equivalent output variable with the same type, decoration (other than code:PassthroughNV), number, and declaration order on the output interface. The output variable declaration corresponding to an input variable decorated with code:PassthroughNV will be identical to the input declaration, except that the outermost array dimension of such variables is removed. The output block declaration corresponding to an input block decorated with code:PassthroughNV or having members decorated with code:PassthroughNV will be identical to the input declaration, except that the outermost array dimension of such declaration is removed. If an input block is decorated with code:PassthroughNV, the equivalent output block contains all the members of the input block. Otherwise, the equivalent output block contains only those input block members decorated with code:PassthroughNV. All members of the corresponding output block are assigned code:Location and code:Component decorations identical to those assigned to the corresponding input block members. Output variables and blocks generated from inputs decorated with code:PassthroughNV will only exist for the purposes of interface matching; these declarations are not available to geometry shader code or listed in the module interface. For the purposes of component counting, passthrough geometry shaders count all statically used input variable components declared with the code:PassthroughNV decoration as output components as well, since their values will be copied to the output primitive produced by the geometry shader. endif::VK_NV_geometry_shader_passthrough[]