| // Copyright (c) 2015-2018 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 <<primsrast>>. |
| 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 at least [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 <<drawing-primitive-order, |
| primitive order>>. |
| |
| * 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 |
| <<interfaces-iointerfaces-matching,Interface Matching>> 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[] |
| |
| |