235 lines
11 KiB
Plaintext
235 lines
11 KiB
Plaintext
// Copyright (c) 2015-2019 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: match
|
|
the incoming primitive type specified by either the pipeline's
|
|
<<drawing-primitive-topologies, primitive topology>> if tessellation is
|
|
inactive, or the <<tessellation, tessellation mode>> if tessellation is
|
|
active, as follows:
|
|
|
|
* An input primitive type of code:InputPoints must: only be used with a
|
|
pipeline topology of ename:VK_PRIMITIVE_TOPOLOGY_POINT_LIST, or with a
|
|
tessellation shader that specifies code:PointMode.
|
|
The input arrays always contain one element, as described by the
|
|
<<drawing-point-lists, point list topology>> or
|
|
<<tessellation-point-mode, tessellation in point mode>>.
|
|
* An input primitive type of code:InputLines must: only be used with a
|
|
pipeline topology of ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST or
|
|
ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP, or with a tessellation shader
|
|
specifying code:IsoLines that does not specify code:PointMode.
|
|
The input arrays always contain two elements, as described by the
|
|
<<drawing-line-lists, line list topology>> or <<drawing-line-strips,
|
|
line strip topology>>, or by <<tessellation-isoline-tessellation,
|
|
isoline tessellation>>.
|
|
* An input primitive type of code:InputLinesAdjacency must: only be used
|
|
when tessellation is inactive, with a pipeline topology of
|
|
ename:VK_PRIMITIVE_TOPOLOGY_LINE_LIST_WITH_ADJACENCY or
|
|
ename:VK_PRIMITIVE_TOPOLOGY_LINE_STRIP_WITH_ADJACENCY.
|
|
The input arrays always contain four elements, as described by the
|
|
<<drawing-line-lists-with-adjacency, line list with adjacency topology>>
|
|
or <<drawing-line-strips-with-adjacency, line strip with adjacency
|
|
topology>>.
|
|
* An input primitive type of code:Triangles must: only be used with a
|
|
pipeline topology of ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST,
|
|
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP, or
|
|
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN; or with a tessellation shader
|
|
specifying code:Quads or code:Triangles that does not specify
|
|
code:PointMode.
|
|
The input arrays always contain three elements, as described by the
|
|
<<drawing-triangle-lists, triangle list topology>>,
|
|
<<drawing-triangle-strips, triangle strip topology>>, or
|
|
<<drawing-triangle-fans, triangle fan topology>>, or by
|
|
<<tessellation-triangle-tessellation, triangle>> or
|
|
<<tessellation-quad-tessellation, quad tessellation>>.
|
|
Vertices may: be in a different absolute order to that specified by the
|
|
topology, but must: adhere to the specified winding order.
|
|
* An input primitive type of code:InputTrianglesAdjacency must: only be
|
|
used when tessellation is inactive, with a pipeline topology of
|
|
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY or
|
|
ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY.
|
|
The input arrays always contain six elements, as described by the
|
|
<<drawing-triangle-lists-with-adjacency, triangle list with adjacency
|
|
topology>> or <<drawing-triangle-strips-with-adjacency, triangle strip
|
|
with adjacency topology>>.
|
|
Vertices may: be in a different absolute order to that specified by the
|
|
topology, but must: adhere to the specified winding order, and the
|
|
vertices making up the main primitive must: still occur at the first,
|
|
third, and fifth index.
|
|
|
|
[[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[]
|
|
|
|
|