Vulkan-Docs/chapters/VK_NVX_raytracing/raytracing.txt

[[raytracing]]
= Raytracing

Unlike draw commands which use rasterization, ray tracing is a rendering
method which generates an image by tracing the path of rays which have a
single origin and using shaders to determine the final colour of an image
plane.

Raytracing uses a separate rendering pipeline from both the graphics and
compute pipelines (see <<pipelines-raytracing,Raytracing Pipeline>>).
It has a unique set of programmable and fixed function stages.

[[fig-raypipe]]
image::images/raypipe.svg[align="center",title="Raytracing Pipeline",{fullimagewidth}]

.Caption
****
Interaction between the different shader stages in the raytracing pipeline
****

[[raytracing-properties]]
== Raytracing Properties

[open,refpage='VkPhysicalDeviceRaytracingPropertiesNVX',desc='Properties of the physical device for raytracing',type='structs']
--
The sname:VkPhysicalDeviceRaytracingPropertiesNVX structure is defined as:

include::../../api/structs/VkPhysicalDeviceRaytracingPropertiesNVX.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:shaderHeaderSize size in bytes of the shader header.
  * pname:maxRecursionDepth is the maximum number of levels of recursion
    allowed in a trace command.
  * pname:maxGeometryCount is the maximum number of geometries in the bottom
    level acceleration structure.

.Valid Usage
****
****

include::../../validity/structs/VkPhysicalDeviceRaytracingPropertiesNVX.txt[]
--


[[raytracing-commands]]
== Raytracing Commands
_Raytracing commands_ provoke work in the raytacing pipeline.
Raytracing commands are recorded into a command buffer and when executed by
a queue will produce work which executes according to the currently bound
raytracing pipeline.
A raytracing pipeline must: be bound to a command buffer before any
raytracing commands are recorded in that command buffer.

Each raytracing call operates on a set of shader stages that are specific to
the raytracing pipeline as well as a set of sname:VkAccelerationStructure
objects which describe the scene geometry in an implementation-specific way.
The relationship between the raytracing pipeline object and the acceleration
structures is passed into the raytacing command in a sname:VkBuffer object
known as a _shader binding table_.

During execution, control alternates between scheduling and other
operations.
The scheduling functionality is implementation-specific and is responsible
for workload execution.
The shader stages are programmable.
_Traversal_, which refers to the process of traversing acceleration
structures to find potential intersections of rays with geometry, is fixed
function.

The programmable portions of the pipeline are exposed in a single-ray
programming model.
Each GPU thread handles one ray at a time.
Memory operations can be synchronized using standard memory barriers.
However, communication and synchronization between threads is not allowed.
In particular, the use of compute pipeline synchronization functions is not
supported in the raytracing pipeline.

[open,refpage='vkCmdTraceRaysNVX',desc='Initialize a raytracing dispatch',type='protos']
--

To dispatch a raytracing call use:

include::../../api/protos/vkCmdTraceRaysNVX.txt[]

  * pname:cmdBuf is the command buffer into which the command will be
    recorded.
  * pname:raygenShaderBindingTableBuffer is the buffer object that holds the
    shader binding table data for the ray generation shader stage.
  * pname:raygenShaderBindingOffset is the offset (relative to
    pname:raygenShaderBindingTableBuffer) of the ray generation shader being
    used for the trace.
  * pname:missShaderBindingTableBuffer is the buffer object that holds the
    shader binding table data for the miss shader stage.
  * pname:missShaderBindingOffset is the offset (relative to
    pname:missShaderBindingTableBuffer) of the miss shader being used for
    the trace.
  * pname:missShaderBindingStride is the size of each shader binding table
    record in pname:missShaderBindingTableBuffer
  * pname:hitShaderBindingTableBuffer is the buffer object that holds the
    shader binding table data for the hit shader stages.
  * pname:hitShaderBindingOffset is the offset (relative to
    pname:hitShaderBindingTableBuffer) of the hit shader group being used
    for the trace.
  * pname:hitShaderBindingStride is the size of each shader binding table
    record in pname:hitShaderBindingTableBuffer
  * pname:width is the width of the ray trace query dimensions.
  * pname:height is height of the ray trace query dimensions.

When the command is executed, a ray query of [eq]#pname:width {times}
pname:height# rays is assembled.

.Valid Usage
****
****

include::../../validity/protos/vkCmdTraceRaysNVX.txt[]
--

[[shader-binding-table]]
== Shader Binding Table

A _shader binding table_ is a resource which establishes the relationship
between the raytracing pipeline and the acceleration structures that were
built for the ray tracing query.
It indicates the shaders that operate on each geometry in an acceleration
structure.
In addition, it contains the resources accessed by each shader, including
textures and constants.
The application allocates and manages _shader binding tables_ as
elink:VkBuffer objects.

The shader binding tables to use in a ray tracing query are passed to
fname:VkCmdTraceRaysNVX.
Shader binding tables are read-only in shaders that are executing on the ray
tracing pipeline.

[[shader-binding-table-indexing-rules]]
=== Indexing Rules

In order to execute the correct shaders and access the correct resources
during a ray tracing dispatch, the implementation must be able to locate
shader binding table entries at various stages of execution.
This is accomplished by defining a set of indexing rules that compute shader
binding table record positions relative to the buffer's base address in
memory.
The application must: organize the contents of the shader binding table's
memory in a way that application of the indexing rules will lead to correct
records.

==== Ray Generation Shaders
Only one ray generation shader is executed per ray tracing dispatch.
Its location is passed into fname:vkCmdTraceRaysNVX using the
pname:raygenShaderBindingTableBuffer and
pname:raygenShaderBindingTableOffset parameters.

The rule to compute a ray generation shader binding table record index is:

  :: [eq]#pname:raygenShaderBindingTableIndex#

==== Hit Shaders
The base for the computation of intersection, any hit and closest hit shader
locations is the pname:instanceShaderBindingTableRecordOffset value stored
with each instance of a top-level acceleration structure (see
elink:VkInstanceNVX).
This value determines the beginning of the shader binding table records for
a given instance.
Each geometry in the instance must: have at least one hit program record.

In the following rule, _geometryIndex_ refers to the location of the
geometry within the instance.

The pname:sbtRecordStride and pname:sbtRecordOffset values are passed in as
parameters to fname:traceNVX() calls made in the shaders.
See Section 8.19 (Raytracing Functions) of the OpenGL Shading Language
Specification for more details.

The result of this computation is then added to
pname:hitProgramShaderBindingTableBaseIndex, a base index passed to
fname:vkCmdTraceRaysNVX.

The complete rule to compute a hit shader binding table record index is:

 :: [eq]#instanceShaderBindingTableRecordOffset {plus}
      hitProgramShaderBindingTableBaseIndex {plus} geometryIndex {times}
      sbtRecordStride {plus} sbtRecordOffset#

==== Miss Shaders
A Miss shader is executed whenever a ray query fails to find an intersection
for the given scene geometry.
Multiple miss shaders can be executed throughout a ray tracing dispatch.

The base for the computation of miss shader locations is
pname:missProgramShaderBindingTableBaseIndex, a base index passed into
fname:vkCmdTraceRaysNVX.

The pname:sbtRecordOffset value is passed in as parameters to
fname:traceNVX() calls made in the shaders.
See Section 8.19 (Raytracing Functions) of the OpenGL Shading Language
Specification for more details.

The complete rule to compute a miss shader binding table record index is:

 :: [eq]#missProgramShaderBindingTableBaseIndex {plus} sbtRecordOffset#

[[acceleration-structure]]
== Acceleration Structures
_Acceleration structures_ are data structures used by the implementation to
efficiently manage the scene geometry as it is traversed during a ray
tracing query.
The application is responsible for managing acceleration structure objects
(see <<resources-acceleration-structures,Acceleration Structures>>,
including allocation, destruction, executing builds or updates, and
synchronizing resources used uring ray tracing queries.

There are two types of acceleration structures, _top level acceleration
structures_ and _bottom level acceleration structures_.

[[fig-accelstruct]]
image::images/accelstruct.svg[align="center",title="Acceleration Structure",{fullimagewidth}]

.Caption
****
The diagram shows the relationship between top and bottom level acceleration
structures.
****

[[acceleration-structure-instance]]
=== Instances
_Instances_ are found in top level acceleration structures and contain data
that refer to a single bottom-level acceleration structure, a transform
matrix, and shading information.
Multiple instances may point to a single bottom level acceleration
structure.

[[acceleration-structure-geometry]]
=== Geometry
_Geometries_ refer to a triangle or axis-aligned bounding box.

[[acceleration-structure-top-level]]
=== Top Level Acceleration Structures
Opaque acceleration structure for an array of instances.
The descriptor referencing this is the starting point for tracing

[[acceleration-structure-bottom-level]]
=== Bottom Level Acceleration Structures
Opaque acceleration structure for an array of geometries.

[[acceleration-structure-building]]
=== Building Acceleration Structures
[open,refpage='vkCmdBuildAccelerationStructureNVX',desc='Build an acceleration structure',type='protos']
--

To build an acceleration structure call:

include::../../api/protos/vkCmdBuildAccelerationStructureNVX.txt[]

  * pname:cmdBuf is the command buffer into which the command will be
    recorded
  * pname:type is the type of acceleration structure that is being built
  * pname:instanceCount is the number of instances in the acceleration
    structure.
    This parameter must: be 0 for bottom level acceleration structures.
  * pname:instanceData is the buffer containing instance data that will be
    used to build the acceleration structure.
    This parameter must: be NULL for bottom level acceleration structures.
  * pname:instanceOffset is the offset (relative to the start of
    pname:instanceData) at which the instance data is located.
  * pname:geometryCount is the number of geometries in the acceleration
    structure.
    This parameter must: be 0 for top level acceleration structures.
  * pname:pGeometries is a pointer to an array of geometries used by bottom
    level acceleration structures.
    This parameter must: be NULL for top level acceleration structures.
  * pname:flags is a ename:vkBuildAccelerationStructureFlagBitsNVX value
    that specifies additional parameters for the acceleration structure
    build.
  * pname:update specifies whether to update the pname:dst acceleration
    structure with the data in pname:src.
  * pname:dst points to the target acceleration structure for the build.
  * pname:src points to an existing acceleration structure that can be used
    to update the pname:dst acceleration structure.
  * pname:scratch is the sname:VkBuffer that will be used as scratch memory
    for the build.
  * pname:scratchOffset is the offset relative to the start of pname:scratch
    that will be used as scratch memory

.Valid Usage
****
  * [[VUID-vkCmdBuildAccelerationStructureNVX-geometryCount-02241]]
    pname:geometryCount must: be less than or equal to
    sname:VkPhysicalDeviceRaytracingPropertiesNVX::pname:maxGeometryCount
****

include::../../validity/protos/vkCmdBuildAccelerationStructureNVX.txt[]
--

[open,refpage='VkBuildAccelerationStructureFlagBitsNVX',desc='Bitmask specifying additional parameters for acceleration structure builds',type='enums']
--

Bits which can: be set in
slink:vkBuildAccelerationStructureFlagBitsNVX::pname:flags, specifying
additional parameters for acceleration structure builds, are:

include::../../api/enums/VkBuildAccelerationStructureFlagBitsNVX.txt[]

--

[[acceleration-structure-copying]]
=== Copying Acceleration Structures

An additional command exists for copying acceleration structures without
updating their contents.
The acceleration structure object may: be compacted in order to improve
performance.
Before copying, an application must: query the size of the resulting
acceleration structure.

[open,refpage='vkCmdWriteAccelerationStructurePropertiesNVX',desc='Copy an acceleration structure',type='protos']
--

To query acceleration structure size parameters call:

include::../../api/protos/vkCmdWriteAccelerationStructurePropertiesNVX.txt[]

  * pname:cmdBuf is the command buffer into which the command will be
    recorded.
  * pname:accelerationStructure points to an existing acceleration structure
    which has been built.
  * pname:queryType is a elink:VkQueryType value specifying the type of
    queries managed by the pool.
  * pname:queryPool is the query pool that will manage the results of the
    query.
  * pname:query is the query index within the query pool that will contain
    the results.

.Valid Usage
****
  * [[VUID-vkCmdWriteAccelerationStructurePropertiesNVX-queryType-02242]]
    pname:queryType must: be VK_QUERY_TYPE_COMPACTED_SIZE_NVX
****

include::../../validity/protos/vkCmdWriteAccelerationStructurePropertiesNVX.txt[]

--


[open,refpage='vkCmdCopyAccelerationStructureNVX',desc='Copy an acceleration structure',type='protos']
--

To copy an acceleration structure call:

include::../../api/protos/vkCmdCopyAccelerationStructureNVX.txt[]

  * pname:cmdBuf is the command buffer into which the command will be
    recorded.
  * pname:dst points to the target acceleration structure for the build
  * pname:src points to an existing acceleration structure that can be used
    to update the pname:dst acceleration structure
  * pname:mode is a ename:VkCopyAccelerationStructureModeNVX value that
    specifies additional operations to perform during the copy.

.Valid Usage
****
****

include::../../validity/protos/vkCmdCopyAccelerationStructureNVX.txt[]

--

[open,refpage='VkCopyAccelerationStructureModeNVX',desc='Acceleration structure copy mode',type='enums']
--

Possible values of slink:vkCmdCopyAccelerationStructureNVX::pname:mode,
specifying additional operations to perform during the copy, are:

include::../../api/enums/VkCopyAccelerationStructureModeNVX.txt[]

// Needs to be filled in
//  * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NVX specifies ...
//  * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NVX specifies ...

--