status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-01-23 20:59:02 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/chapters/VK_NV_ray_tracing/raytracing-pipelines.txt
Jon Leech b59ec03ee3 Change log for February 3, 2019 Vulkan 1.1.99 spec update: 
* Update release number to 99.

Public Issues:

  * Add missing pname:pMemoryHostPointerProperties description to
    flink:vkGetMemoryHostPointerPropertiesEXT.txt (public pull request 896).
  * Minor markup fixes (public pull request 900).
  * Minor update to `khronos.css` and markup fixes (originally proposed in
    public pull request 901, but done via an internal MR).

Internal Issues:

  * Document restrictions on image queries for Y'CbCr formats in the
    <<features-formats-requiring-sampler-ycbcr-conversion>> table as well as
    for slink:sname:VkImageFormatProperties and slink:VkImageCreateInfo
    (internal issue 1361).
  * Correct type of the code:FragSizeEXT built-in in the
    <<interfaces-builtin-variables, Built-In Variables>> section (internal
    issue 1526).
  * Clean up math in the <<textures, Image Operations>> chapter by
    refactoring, using better naming conventions, updating diagrams to use
    the correct orientation, etc. (internal merge request 2968).
  * Fix minor typos for slink:VkImageCreateInfo and
    slink:VkImageStencilUsageCreateInfoEXT.
  * Add missing documentation for tlink:VkResolveModeFlagsKHR.
  * Fix extension dependency of pname:scalarBlockLayout in the
    <<features-features-requirements, Feature Requirements>> section.
  * Fix indexing math for shader binding table calculations in the
    <<shader-binding-table-indexing-rules, Indexing Rules>> section, and use
    spelling "`any-hit`" consistently.
  * Reconcile valid usage statement and text for sampled image layouts in
    slink:VkWriteDescriptorSet
    (https://github.com/KhronosGroup/Vulkan-ValidationLayers/issues/551).
  * Make SPIR-V code:OpConvertUToPtr and code:OpConvertPtrToU operations
    require a 64-bit integer for physical storage buffer pointers in the
    <<spirvenv-module-validation, Validation Rules within a Module>>
    section.
  * Update to KaTeX 10.0.

New Extensions:

  * `VK_EXT_filter_cubic`
  * `VK_NV_dedicated_allocation_image_aliasing`
2019-02-04 01:26:23 -08:00

285 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 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::../../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
slink:VkPhysicalDeviceLimits::pname:maxPerStageResources
* [[VUID-VkRayTracingPipelineCreateInfoNV-maxRecursionDepth-02412]]
pname:maxRecursionDepth must: be less than or equal to
slink: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 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::../../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
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::../../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::../../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