[[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 <>). 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 <>, 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='Write acceleration structure result parameters to query results.',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[] * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NVX creates a direct copy of the acceleration structure specified in pname:src into the one specified by pname:dst. The pname:dst acceleration structure must: have been created with the same parameters as pname:src. * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NVX creates a more compact version of an acceleration structure pname:src into pname:dst. The acceleration structure pname:dst must: have been created with a pname:compactedSize corresponding to the one returned by slink:vkCmdWriteAccelerationStructurePropertiesNVX after the build of the acceleration structure specified by pname:src. --