status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-02-03 01:53:40 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/chapters/VK_NV_ray_tracing/raytracing-pipelines.txt
Jon Leech e24e42dcff Change log for November 4, 2018 Vulkan 1.1.91 spec update: 
* Update release number to 91.

Public Issues:

  * Update Ubuntu subsystem build instructions in `BUILD.adoc` (public pull
    request 624).
  * Delete the `VK_KHR_mir_surface` extension from the Specification and
    XML, due to EOL of the only driver known to have supported it, and
    near-EOL of Mir itself (public issue 814).
  * Fix options for some figures that were using old ones (public pull
    request 841).
  * Fix various accidentally repeated words (public pull request 843).
  * Use `time.process_time()`, introduced in Python 3.3, in the scripts
    instead of `time.clock()`, which will be removed in Python 3.8 (public
    pull request 844).

Internal Issues:

  * Update valid usage statements for
    `VK_ANDROID_external_memory_android_hardware_buffer` in
    slink:VkMemoryAllocateInfo,
    slink:VkImportAndroidHardwareBufferInfoANDROID, and
    flink:vkGetAndroidHardwareBufferPropertiesANDROID to actually be
    verifiable (internal issue 1419).
  * Update valid usage statements for
    `VK_ANDROID_external_memory_android_hardware_buffer` in
    slink:VkMemoryAllocateInfo, slink:VkImageCreateInfo, and
    slink:VkImageViewCreateInfo to move valid usage statements in
    doubly-nested bullet points up one level, accomodating limitations of
    the valid usage extraction script that creates `validusage.json`
    (internal issue 1434).
  * Fix typo etext:VK_ACCESS_SHADING_RATE_IMAGE_BIT_NV to the correct
    ename:VK_ACCESS_SHADING_RATE_IMAGE_READ_BIT_NV.
  * Add missing etext:VK_STRUCTURE_TYPE_* tokens to appendices for
    extensions missing them.

New Extensions:

  * `VK_AMD_memory_overallocation_behavior`
  * `VK_NV_ray_tracing`, replacing `VK_NVX_raytracing`
2018-11-03 23:50:13 -07:00

284 lines
13 KiB
Plaintext
Raw Blame History

// 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::../../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 compute
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::../../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::../../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
sname:VkPhysicalDeviceLimits::pname:maxPerStageResources
* [[VUID-VkRayTracingPipelineCreateInfoNV-maxRecursionDepth-02412]]
pname:maxRecursionDepth must: be less than or equal to
VkPhysicalDeviceRayTracingPropertiesNV::pname:maxRecursionDepth
****
include::../../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::../../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::../../validity/structs/VkRayTracingShaderGroupCreateInfoNV.txt[]
--
[open,refpage='VkRayTracingShaderGroupTypeNV',desc='Shader group types',type='enums']
--
Possible values of pname:type in sname:VkRayTracingShaderGroupCreateInfoNV
are:,
include::../../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 don't 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::../../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 sname:VkPipelineShaderStageCreateInfo::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 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::../../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 may: 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::../../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::../../validity/protos/vkCompileDeferredNV.txt[]
--
Reference in New Issue View Git Blame Copy Permalink