mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 15:04:10 +00:00
82e0f83d43
* Bump API patch number and header version number to 40 for this update.
* There is a major build change in this release. We are now using the
Ruby-based ``asciidoctor'' implementation, rather than the Python-based
``asciidoc'' implementation, to process the specification. While the
actual specification markup changes were minimal, this requires a new
set of build tools and a very different installation process, especially
because we now use an experimental direct-to-PDF backend for Asciidoctor
instead of Docbook->dblatex->PDF. It is no longer possible to build the
Specification using asciidoc. See doc/specs/vulkan/README.adoc
for some guidance on installing the new toolchain components.
* There are some minor rendering issues in the PDF output due to teething
problems with the asciidoctor toolchain, especially with mathematical
equations. We are aware of these and working on them.
Github Issues:
* Updated sample code for the <<sparsememory-examples-basic,sparse
resource binding example>> (public issue 97).
* Modify line and point clipping behavior in the
<<vertexpostproc-clipping, Primitive Clipping>> section to allow for
pop-free behavior. The ability to check for which behavior is
implemented may be added a future feature or extension (public issue
113).
* Unify the discussions of implicit ordering throughout the spec, in
particular in the new sections <<drawing-primitive-order, Primitive
Order>>, <<primrast-order, Rasterization Order>>, and
<<synchronization-implicit, Implicit Synchronization Guarantees>>; the
discussion of <<synchronization-submission-order, submission order>>;
and references elsewhere to these sections (public issue 133).
* Clarify \<\<descriptorsets-compatibility,Pipeline Layout Compatibility>>
language and introduce the term ``identically defined'' (public issue
164).
* Add a dependency to the +VK_EXT_debug_marker+ extension that's needed to
reuse the object type enum from +VK_EXT_debug_report+, and moves the
definition of that enum into +VK_EXT_debug_report+ where it should be
(public issue 409).
* Remove redundant valid usage statement from slink:VkImageBlit (public
issue 421).
* Update GL_KHR_vulkan_glsl to allow the ternary operator to result in a
specialization constant (public issue 424).
* Fix valid usage for flink:VkPipelineShaderStageCreateInfo (public issue
426).
* Correct typo in New Objects list for <<VK_EXT_debug_report>> (public
issue 447).
Internal Issues:
* Moved to asciidoctor for spec builds (internal issue 121).
* Update style guide to describe where to put new extensions-specific
asciidoc files, and what to name them (internal issue 626).
* Add src/spec/indexExt.py to autogenerate registry index entries linking
into the 1.0-extensions specification, instead of maintaining the index
manually. (internal issue 642).
* Autogenerate extension dependencies and lists of all extensions and all
KHR extensions from the "supported" attributes in +vk.xml+. Execute
+make config/extDependency.sh+ from +doc/specs/vulkan+ when a supported
extension is added to vk.xml, to regenerate the dependency script. The
consequence is that specifying a single extension to the +makeExt+
script will automatically enable all extensions it depends on as well,
and that the +makeAllExts+ and +makeKHR+ scripts do not need to be
updated when a new extension is supported (internal issue 648).
* Put extension appendices all at the same asciidoc section level, so KHR
WSI extensions show up in the HTML index (internal issue 648).
Other Issues:
* Imbed images in the generated HTML specs instead of loading them from
the images/ directory.
* Fix missing EXT in extension name
(ename:VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME).
* Add new +VK_EXT_SMPTE_2086_metadata+ extension.
* In the <<platformCreateSurface_xlib,Xlib Surface>> section of the
+VK_KHR_xlib_surface+ specification, add language warning users that
they always need to call code:XinitThreads.
* Use the term "presentable image" (rather than "swapchain image")
consistently in +VK_KHR_swapchain+ and related extensions, and add a
glossary term defining it.
* Relocate the valid usage for samples of
flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo
to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR
structure.
166 lines
7.1 KiB
Plaintext
166 lines
7.1 KiB
Plaintext
// Copyright (c) 2015-2017 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[[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.
|
|
|
|
|
|
|