mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-21 10:38:09 +00:00
5abf83f95d
* Update release number to 107.
Public Issues:
* Fix revision date for the `<<VK_AMD_gpu_shader_half_float>>` appendix
(public issue 617).
* Make <<synchronization-pipeline-barriers-subpass-self-dependencies,
subpass self-dependencies>> less restrictive (public issue 777).
* Fix the `<<VK_EXT_full_screen_exclusive>>` dependency on
`<<VK_KHR_win32_surface>>` in `vk.xml` (public pull request 849).
* Remove single-page (`apispec.html`) refpage sub-targets from the
Makefile `allman` target and the build instructions. The target is still
present in the Makefile, but we have not been actively maintaining the
single-page document and do not promise it will work. The full
Specification and the individual API reference pages are what we support
and publish at present (public issue 949).
Internal Issues:
* De-duplicate common valid usage statements shared by multiple commands
or structures by using asciidoctor includes and dynamically assigning
part of the valid usage ID based on which command or structure they're
being applied to (internal issue 779).
* Add reference pages for constructs not part of the formal API, such as
platform calling convention macros, and script changes supporting them
This required suppressing some check_spec_links warning classes in order
to pass CI, until a more sophisticated fix can be done (internal issue
888).
* Change math notation for the elink:VkPrimitiveTopology descriptions to
use short forms `v` and `p` instead of `vertex` and `primitive`,
increasing legibility (internal issue 1611).
* Rewrite generated file includes relative to a globally specified path,
fixing some issues with refpage generation (internal issue 1630).
* Update contributor list for `<<VK_EXT_calibrated_timestamps>>`.
* Fix use of pathlin in `scripts/generator.py` so the script will work on
Windows under Python 3.5 (internal merge request 3107).
* Add missing conditionals around the
<<descriptorsets-accelerationstructure, Acceleration Structure>>
section (internal merge request 3108).
* More script synchronization with OpenXR spec repository (internal merge
request 3109).
* Mark the `<<VK_AMD_gpu_shader_half_float>>` and
`<<VK_AMD_gpu_shader_int16>>` extensions as deprecated in `vk.xml` and
the corresponding extension appendices (internal merge request 3112).
New Extensions:
* `<<VK_EXT_headless_surface>>`
286 lines
13 KiB
Plaintext
286 lines
13 KiB
Plaintext
// This section is included inside the Pipelines chapter (pipelines.txt)
|
|
|
|
[[pipelines-raytracing]]
|
|
== Ray Tracing Pipeline
|
|
|
|
Ray tracing pipelines consist of multiple shader stages, fixed-function
|
|
traversal stages, and a pipeline layout.
|
|
|
|
[open,refpage='vkCreateRayTracingPipelinesNV',desc='Creates a new ray tracing pipeline object',type='protos']
|
|
--
|
|
|
|
To create ray tracing pipelines, call:
|
|
|
|
include::{generated}/api/protos/vkCreateRayTracingPipelinesNV.txt[]
|
|
|
|
* pname:device is the logical device that creates the ray tracing
|
|
pipelines.
|
|
* pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that
|
|
pipeline caching is disabled, or the handle of a valid
|
|
<<pipelines-cache,pipeline cache>> object, in which case use of that
|
|
cache is enabled for the duration of the command.
|
|
* pname:createInfoCount is the length of the pname:pCreateInfos and
|
|
pname:pPipelines arrays.
|
|
* pname:pCreateInfos is an array of sname:VkRayTracingPipelineCreateInfoNV
|
|
structures.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pPipelines is a pointer to an array in which the resulting ray
|
|
tracing pipeline objects are returned.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCreateRayTracingPipelinesNV-flags-02402]]
|
|
If the pname:flags member of any element of pname:pCreateInfos contains
|
|
the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the
|
|
pname:basePipelineIndex member of that same element is not `-1`,
|
|
pname:basePipelineIndex must: be less than the index into
|
|
pname:pCreateInfos that corresponds to that element
|
|
* [[VUID-vkCreateRayTracingPipelinesNV-flags-02403]]
|
|
If the pname:flags member of any element of pname:pCreateInfos contains
|
|
the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline
|
|
must: have been created with the
|
|
ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set
|
|
****
|
|
|
|
include::{generated}/validity/protos/vkCreateRayTracingPipelinesNV.txt[]
|
|
--
|
|
|
|
[open,refpage='VkRayTracingPipelineCreateInfoNV',desc='Structure specifying parameters of a newly created ray tracing pipeline',type='structs']
|
|
--
|
|
|
|
The sname:VkRayTracingPipelineCreateInfoNV structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkRayTracingPipelineCreateInfoNV.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying
|
|
how the pipeline will be generated.
|
|
* pname:stageCount is the number of entries in the pname:pStages array.
|
|
* pname:pStages is an array of size pname:stageCount structures of type
|
|
slink:VkPipelineShaderStageCreateInfo describing the set of the shader
|
|
stages to be included in the ray tracing pipeline.
|
|
* pname:groupCount is the number of entries in the pname:pGroups array.
|
|
* pname:pGroups is an array of size pname:groupCount structures of type
|
|
slink:VkRayTracingShaderGroupCreateInfoNV describing the set of the
|
|
shader stages to be included in each shader group in the ray tracing
|
|
pipeline.
|
|
* pname:maxRecursionDepth is the maximum recursion that will be called
|
|
from this pipeline.
|
|
* pname:layout is the description of binding locations used by both the
|
|
pipeline and descriptor sets used with the pipeline.
|
|
* pname:basePipelineHandle is a pipeline to derive from.
|
|
* pname:basePipelineIndex is an index into the pname:pCreateInfos
|
|
parameter to use as a pipeline to derive from.
|
|
|
|
The parameters pname:basePipelineHandle and pname:basePipelineIndex are
|
|
described in more detail in <<pipelines-pipeline-derivatives,Pipeline
|
|
Derivatives>>.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02404]]
|
|
If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
|
|
flag, and pname:basePipelineIndex is `-1`, pname:basePipelineHandle
|
|
must: be a valid handle to a ray tracing sname:VkPipeline
|
|
* [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02405]]
|
|
If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
|
|
flag, and pname:basePipelineHandle is dlink:VK_NULL_HANDLE,
|
|
pname:basePipelineIndex must: be a valid index into the calling
|
|
command's pname:pCreateInfos parameter
|
|
* [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02406]]
|
|
If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
|
|
flag, and pname:basePipelineIndex is not `-1`, pname:basePipelineHandle
|
|
must: be dlink:VK_NULL_HANDLE
|
|
* [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02407]]
|
|
If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
|
|
flag, and pname:basePipelineHandle is not dlink:VK_NULL_HANDLE,
|
|
pname:basePipelineIndex must: be `-1`
|
|
* [[VUID-VkRayTracingPipelineCreateInfoNV-stage-02408]]
|
|
The pname:stage member of one element of pname:pStages must: be
|
|
ename:VK_SHADER_STAGE_RAYGEN_BIT_NV
|
|
* [[VUID-VkRayTracingPipelineCreateInfoNV-pStages-02409]]
|
|
The shader code for the entry points identified by pname:pStages, and
|
|
the rest of the state identified by this structure must: adhere to the
|
|
pipeline linking rules described in the <<interfaces,Shader Interfaces>>
|
|
chapter
|
|
* [[VUID-VkRayTracingPipelineCreateInfoNV-layout-02410]]
|
|
pname:layout must: be
|
|
<<descriptorsets-pipelinelayout-consistency,consistent>> with all
|
|
shaders specified in pname:pStages
|
|
* [[VUID-VkRayTracingPipelineCreateInfoNV-layout-02411]]
|
|
The number of resources in pname:layout accessible to each shader stage
|
|
that is used by the pipeline must: be less than or equal to
|
|
slink:VkPhysicalDeviceLimits::pname:maxPerStageResources
|
|
* [[VUID-VkRayTracingPipelineCreateInfoNV-maxRecursionDepth-02412]]
|
|
pname:maxRecursionDepth must: be less than or equal to
|
|
slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxRecursionDepth
|
|
****
|
|
|
|
include::{generated}/validity/structs/VkRayTracingPipelineCreateInfoNV.txt[]
|
|
--
|
|
|
|
[open,refpage='VkRayTracingShaderGroupCreateInfoNV',desc='Structure specifying shaders in a shader group',type='structs']
|
|
--
|
|
|
|
The sname:VkRayTracingShaderGroupCreateInfoNV structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkRayTracingShaderGroupCreateInfoNV.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:type is the type of hit group specified in this structure.
|
|
* pname:generalShader is the index of the ray generation, miss, or
|
|
callable shader from
|
|
sname:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if
|
|
the shader group has pname:type of
|
|
ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV and
|
|
ename:VK_SHADER_UNUSED_NV otherwise.
|
|
* pname:closestHitShader is the optional index of the closest hit shader
|
|
from sname:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group
|
|
if the shader group has pname:type of
|
|
ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or
|
|
ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV and
|
|
ename:VK_SHADER_UNUSED_NV otherwise.
|
|
* pname:anyHitShader is the optional index of the any-hit shader from
|
|
sname:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if
|
|
the shader group has pname:type of
|
|
ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or
|
|
ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV and
|
|
ename:VK_SHADER_UNUSED_NV otherwise.
|
|
* pname:intersectionShader is the index of the intersection shader from
|
|
sname:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if
|
|
the shader group has pname:type of
|
|
ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV and
|
|
ename:VK_SHADER_UNUSED_NV otherwise.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02413]]
|
|
If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then
|
|
pname:generalShader must: be a valid index into pname:pStages referring
|
|
to a shader of ename:VK_SHADER_STAGE_RAYGEN_BIT_NV,
|
|
ename:VK_SHADER_STAGE_MISS_BIT_NV, or
|
|
ename:VK_SHADER_STAGE_CALLABLE_BIT_NV
|
|
* [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02414]]
|
|
If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then
|
|
pname:closestHitShader, pname:anyHitShader, and pname:intersectionShader
|
|
must: be ename:VK_SHADER_UNUSED_NV
|
|
* [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02415]]
|
|
If pname:type is
|
|
ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV then
|
|
pname:intersectionShader must: be a valid index into pname:pStages
|
|
referring to a shader of ename:VK_SHADER_STAGE_INTERSECTION_BIT_NV
|
|
* [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02416]]
|
|
If pname:type is
|
|
ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV then
|
|
pname:intersectionShader must: be ename:VK_SHADER_UNUSED_NV
|
|
* [[VUID-VkRayTracingShaderGroupCreateInfoNV-closestHitShader-02417]]
|
|
pname:closestHitShader must: be either ename:VK_SHADER_UNUSED_NV or a
|
|
valid index into pname:pStages referring to a shader of
|
|
ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV
|
|
* [[VUID-VkRayTracingShaderGroupCreateInfoNV-anyHitShader-02418]]
|
|
pname:anyHitShader must: be either ename:VK_SHADER_UNUSED_NV or a valid
|
|
index into pname:pStages referring to a shader of
|
|
ename:VK_SHADER_STAGE_ANY_HIT_BIT_NV
|
|
****
|
|
|
|
include::{generated}/validity/structs/VkRayTracingShaderGroupCreateInfoNV.txt[]
|
|
--
|
|
|
|
|
|
[open,refpage='VkRayTracingShaderGroupTypeNV',desc='Shader group types',type='enums']
|
|
--
|
|
|
|
Possible values of pname:type in sname:VkRayTracingShaderGroupCreateInfoNV
|
|
are:
|
|
|
|
include::{generated}/api/enums/VkRayTracingShaderGroupTypeNV.txt[]
|
|
|
|
* ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV indicates a shader
|
|
group with a single ename:VK_SHADER_STAGE_RAYGEN_BIT_NV,
|
|
ename:VK_SHADER_STAGE_MISS_BIT_NV, or
|
|
ename:VK_SHADER_STAGE_CALLABLE_BIT_NV shader in it.
|
|
* ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV specifies
|
|
a shader group that only hits triangles and must: not contain an
|
|
intersection shader, only closest hit and any-hit.
|
|
* ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV specifies
|
|
a shader group that only intersects with custom geometry and must:
|
|
contain an intersection shader and may: contain closest hit and any-hit
|
|
shaders.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
For current group types, the hit group type could be inferred from the
|
|
presence or absence of the intersection shader, but we provide the type
|
|
explicitly for future hit groups that do not have that property.
|
|
====
|
|
|
|
--
|
|
|
|
[open,refpage='vkGetRayTracingShaderGroupHandlesNV',desc='Query ray tracing pipeline shader group handles',type='protos']
|
|
--
|
|
|
|
To query the opaque handles of shaders in the ray tracing pipeline, call:
|
|
|
|
include::{generated}/api/protos/vkGetRayTracingShaderGroupHandlesNV.txt[]
|
|
|
|
* pname:device is the logical device that contains the ray tracing
|
|
pipeline.
|
|
* pname:pipeline is the ray tracing pipeline object that contains the
|
|
shaders.
|
|
* pname:firstGroup is the index of the first group to retrieve a handle
|
|
for from the slink:VkRayTracingShaderGroupCreateInfoNV::pname:pGroups
|
|
array.
|
|
* pname:groupCount is the number of shader handles to retrieve.
|
|
* pname:dataSize is the size in bytes of the buffer pointed to by
|
|
pname:pData.
|
|
* pname:pData is a pointer to a user-allocated buffer where the results
|
|
will be written.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkGetRayTracingShaderGroupHandlesNV-firstGroup-02419]]
|
|
The sum of pname:firstGroup and pname:groupCount must: be less than the
|
|
number of shader groups in pname:pipeline.
|
|
* [[VUID-vkGetRayTracingShaderGroupHandlesNV-dataSize-02420]]
|
|
pname:dataSize must: be at least
|
|
[eq]#sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupHandleSize
|
|
{times} pname:groupCount#
|
|
****
|
|
|
|
include::{generated}/validity/protos/vkGetRayTracingShaderGroupHandlesNV.txt[]
|
|
--
|
|
|
|
Ray tracing pipelines can: contain more shaders than a graphics or compute
|
|
pipeline, so to allow parallel compilation of shaders within a pipeline, an
|
|
application can: choose to defer compilation until a later point in time.
|
|
|
|
[open,refpage='vkCompileDeferredNV',desc='Deferred compilation of shaders',type='protos']
|
|
--
|
|
|
|
To compile a deferred shader in a pipeline call:
|
|
|
|
include::{generated}/api/protos/vkCompileDeferredNV.txt[]
|
|
|
|
* pname:device is the logical device that contains the ray tracing
|
|
pipeline.
|
|
* pname:pipeline is the ray tracing pipeline object that contains the
|
|
shaders.
|
|
* pname:shader is the index of the shader to compile.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCompileDeferredNV-pipeline-02237]]
|
|
pname:pipeline must: have been created with
|
|
ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV
|
|
* [[VUID-vkCompileDeferredNV-shader-02238]]
|
|
pname:shader must: not have been called as a deferred compile before
|
|
****
|
|
|
|
include::{generated}/validity/protos/vkCompileDeferredNV.txt[]
|
|
--
|
|
|