mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-21 18:48:12 +00:00
e958791a01
* First public update for Vulkan 1.1.
Github Issues:
* Refer to standard sparse image block shape format tables explicitly in
the <<sparsememory-standard-shapes, Standard Sparse Image Block Shapes>>
section (public issue 93).
* Add the missing definition of the code:LocalInvocationIndex decoration
in the <<interfaces-builtin-variables, Built-In Variables>> section
(public issue 532).
* Clarify dynamic state definition in the introduction to the <<pipelines,
Pipelines>> section and the new <<pipelines-dynamic-state, Dynamic
State>> subsection (public issue 620).
* Clarified deprecation statement in the `VK_AMD_negative_viewport_height`
appendix (public issue 674).
* Fix parameter descriptions for flink:vkCreateIndirectCommandsLayoutNVX
(public issue 677).
Internal Issues:
* Remove description of <<primsrast-points, rasterization point size>>
being taken from the tessellation control shader, since there are no
circumstances under which you can have TCS without TES (internal issue
522).
* Define <<copies-images-format-size-compatibility, _size-compatible_
image formats>> for flink:vkCmdCopyImage, add it to the glossary, and
use that definition for slink:VkImageViewCreateInfo (internal issue
771).
* Change brief descriptions of enumerant names, and of parameters which
are enumerants, from "`enum *indicates*`" to "`enum *specifies*`" for
consistency, and add a markup style guide rule (internal issue 862).
* Clarify how execution dependencies interact with
<<synchronization-submission-order, submission order>> at numerous
places in the <<renderpass, Render Pass>> and <<synchronization,
Synchronization>> chapters (internal issue 1062).
* Clarify statement in the <<interfaces-resources-setandbinding,
DescriptorSet and Binding Assignment>> section that only interface
variables statically used by the entry point used in a pipeline must be
present in the descriptor set layout (internal issue 1172).
* Flip sparse image diagrams with partially full mip levels vertically, to
match graph origins of other image diagrams (internal issue 1176).
* Update new SVG diagrams to have consistent style and base font size,
increase consistency of primitive topology diagrams, and add a section
to the style guide on creating and editing images in a consistent style
(internal issue 1177).
* Resolve problems with valid usage statement extraction by fixing
existing VUID tags for interfaces promoted to version 1.1 and fixing
conditional directives around
VUID-VkMemoryDedicatedAllocateInfo-image-01797 (internal issue 1184).
* Strip `KHR` suffixes from a few interfaces promoted to Vulkan 1.1 that
were missed previously (internal issue 1185).
* Restrict code:OpImageQuerySizeLod and code:OpImageQueryLevels to only
work on code:Image operands with their code:Sampled operand set to 1. In
other words, these operations are not defined to work with storage
images (internal issue 1193).
* Recycle extension slot for extension #82 in `vk.xml`. This extension was
never published (internal issue 1195).
* Add an issue to the `VK_KHR_maintenance1` appendix noting that zero
height viewports are allowed when this extension is enabled (internal
issue 1202).
* Fix slink:VkDescriptorSetLayoutBinding description so that shader stages
always use descriptor bindings, not the other way around (internal issue
1206).
* Fix field name for
slink:VkInputAttachmentAspectReference::pname:inputAttachmentIndex
(internal issue 1210).
Other Issues:
* Fix a few broken links in the <<versions-1.1, Version 1.1>> appendix.
* Replace a few old refBegin/refEnd tags with open block markup around
interfaces, and remove old KHX VUID tags that were breaking the valid
usage statement extraction.
* Fix error codes accidentally tagged as success codes in `vk.xml` for
flink:vkGetSwapchainCounterEXT.
* Added valid usage statements for ftext:vkBind*Memory2 input structures
stext:VkBind*MemoryInfo, and fix a pname:image -> pname:buffer typo in a
couple of places.
* Fix swapped descriptions of elink:VkDescriptorType enums
ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE and
ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE (reported via tweet).
New Extensions:
* `VK_ANDROID_external_memory_android_hardware_buffer`
264 lines
12 KiB
Plaintext
264 lines
12 KiB
Plaintext
// 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 [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[]
|
|
|
|
|