32. Ray Tracing
Ray tracing uses a separate rendering pipeline from both the graphics and compute pipelines (see Ray Tracing Pipeline).
Within the ray tracing pipeline, OpTraceRayKHR can be called to
perform a ray traversal that invokes the various ray
tracing shader stages during its execution.
The relationship between the ray tracing pipeline object and the geometries
present in the acceleration structure traversed is passed into the ray
tracing command in a VkBuffer object known as a shader binding
table.
OpExecuteCallableKHR can also be used in ray tracing pipelines to
invoke a callable shader.
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, with each invocation handling one ray at a time.
Memory operations can be synchronized using standard memory barriers.
The Workgroup scope and variables with a storage class of
Workgroup must not be used in the ray tracing pipeline.
32.1. Shader Call Instructions
A shader call is an instruction which may cause execution to continue elsewhere by creating one or more invocations that execute a different shader stage.
The shader call instructions are:
-
OpTraceRayKHRwhich may invoke intersection, any-hit, closest hit, or miss shaders, -
OpReportIntersectionKHRwhich may invoke any-hit shaders, and -
OpExecuteCallableKHRwhich will invoke a callable shader.
The invocations created by shader call instructions are grouped into subgroups by the implementation. Those subgroups may be unrelated to the subgroup of the parent invocation.
Shader call instructions can be used recursively; invoked shaders can
themselves execute shader call instructions, to a maximum depth defined by
the maxRecursionDepth limit.
Shaders directly invoked from the API always have a recursion depth of 0;
each shader executed by a shader call instruction has a recursion depth one
higher than the recursion depth of the shader which invoked it.
Applications must not invoke a shader with a recursion depth greater than
the value of maxRecursionDepth specified in the pipeline.
An invocation repack instruction is a ray tracing shader call instruction
where the implementation may change the set of invocations that are
executing.
When a repack instruction is encountered, the invocation is suspended and a
new invocation begins and executes the instruction.
After executing the repack instruction (which may result in other ray
tracing shader stages executing) the new invocation ends and the original
invocation is resumed, but it may be resumed in a different subgroup or at
a different SubgroupLocalInvocationId within the same subgroup.
When a subset of invocations in a subgroup execute the invocation repack
instruction, those that do not execute it remain in the same subgroup at the
same SubgroupLocalInvocationId.
The OpTraceRayKHR, OpReportIntersectionKHR, and
OpExecuteCallableKHR instructions are invocation repack instructions.
The invocations that are executing before an invocation repack instruction, after the instruction, or are created by the instruction, are shader-call-related.
If the implementation changes the composition of subgroups, the values of
SubgroupLocalInvocationId,
and builtin variables that are derived from them (SubgroupEqMask,
SubgroupGeMask, SubgroupGtMask, SubgroupLeMask,
SubgroupLtMask) must be changed accordingly by the invocation repack
instruction.
|
Note
Subgroup operations are permitted in the programmable ray tracing shader stages. However, shader call instructions place a bound on where results of subgroup instructions or subgroup-scoped instructions that execute the dynamic instance of that instruction are potentially valid. For example, care must be taken when using the result of a ballot operation that was computed before an invocation repack instruction, after that repack instruction. The ballot may be incorrect as the set of invocations could have changed. For clock operations, the value of a |
When a ray tracing shader executes a dynamic instance of an invocation repack instruction which results in another ray tracing shader being invoked, their instructions are related by shader-call-order.
For ray tracing invocations that are shader-call-related:
-
memory operations on
StorageBuffer,Image, andShaderRecordBufferKHRstorage classes can be synchronized using theShaderCallKHRscope. -
the
CallableDataKHR,IncomingCallableDataKHR,RayPayloadKHR,HitAttributeKHR, andIncomingRayPayloadKHRstorage classes are system-synchronized and no application availability and visibility operations are required. -
memory operations within a single invocation before and after the invocation repack instruction are ordered by program-order and do not require explicit synchronzation.
32.2. Ray Tracing Commands
Ray tracing commands provoke work in the ray tracing pipeline. Ray tracing commands are recorded into a command buffer and when executed by a queue will produce work that executes according to the currently bound ray tracing pipeline. A ray tracing pipeline must be bound to a command buffer before any ray tracing commands are recorded in that command buffer.
To dispatch ray tracing use:
// Provided by VK_KHR_ray_tracing
void vkCmdTraceRaysKHR(
VkCommandBuffer commandBuffer,
const VkStridedBufferRegionKHR* pRaygenShaderBindingTable,
const VkStridedBufferRegionKHR* pMissShaderBindingTable,
const VkStridedBufferRegionKHR* pHitShaderBindingTable,
const VkStridedBufferRegionKHR* pCallableShaderBindingTable,
uint32_t width,
uint32_t height,
uint32_t depth);-
commandBufferis the command buffer into which the command will be recorded. -
pRaygenShaderBindingTableis a VkStridedBufferRegionKHR that holds the shader binding table data for the ray generation shader stage. -
pMissShaderBindingTableis a VkStridedBufferRegionKHR that holds the shader binding table data for the miss shader stage. -
pHitShaderBindingTableis a VkStridedBufferRegionKHR that holds the shader binding table data for the hit shader stage. -
pCallableShaderBindingTableis a VkStridedBufferRegionKHR that holds the shader binding table data for the callable shader stage. -
widthis the width of the ray trace query dimensions. -
heightis height of the ray trace query dimensions. -
depthis depth of the ray trace query dimensions.
When the command is executed, a ray generation group of width
× height × depth rays is assembled.
The VkStridedBufferRegionKHR structure is defined as:
// Provided by VK_KHR_ray_tracing
typedef struct VkStridedBufferRegionKHR {
VkBuffer buffer;
VkDeviceSize offset;
VkDeviceSize stride;
VkDeviceSize size;
} VkStridedBufferRegionKHR;-
bufferis the buffer containing this region. -
offsetis the byte offset inbufferat which the region starts. -
strideis the byte stride between consecutive elements. -
sizeis the size in bytes of the region starting atoffset.
To dispatch ray tracing, with some parameters sourced on the device, use:
// Provided by VK_KHR_ray_tracing
void vkCmdTraceRaysIndirectKHR(
VkCommandBuffer commandBuffer,
const VkStridedBufferRegionKHR* pRaygenShaderBindingTable,
const VkStridedBufferRegionKHR* pMissShaderBindingTable,
const VkStridedBufferRegionKHR* pHitShaderBindingTable,
const VkStridedBufferRegionKHR* pCallableShaderBindingTable,
VkBuffer buffer,
VkDeviceSize offset);-
commandBufferis the command buffer into which the command will be recorded. -
pRaygenShaderBindingTableis a VkStridedBufferRegionKHR that holds the shader binding table data for the ray generation shader stage. -
pMissShaderBindingTableis a VkStridedBufferRegionKHR that holds the shader binding table data for the miss shader stage. -
pHitShaderBindingTableis a VkStridedBufferRegionKHR that holds the shader binding table data for the hit shader stage. -
pCallableShaderBindingTableis a VkStridedBufferRegionKHR that holds the shader binding table data for the callable shader stage. -
bufferis the buffer containing the trace ray parameters. -
offsetis the byte offset intobufferwhere parameters begin.
vkCmdTraceRaysIndirectKHR behaves similarly to vkCmdTraceRaysKHR
except that the ray trace query dimensions are read by the device from
buffer during execution.
The parameters of trace ray are encoded in the
VkTraceRaysIndirectCommandKHR structure located at offset bytes
in buffer.
The VkTraceRaysIndirectCommandKHR structure is defined as:
// Provided by VK_KHR_ray_tracing
typedef struct VkTraceRaysIndirectCommandKHR {
uint32_t width;
uint32_t height;
uint32_t depth;
} VkTraceRaysIndirectCommandKHR;-
widthis the width of the ray trace query dimensions. -
heightis height of the ray trace query dimensions. -
depthis depth of the ray trace query dimensions.
The members of VkTraceRaysIndirectCommandKHR have the same meaning as
the similarly named parameters of vkCmdTraceRaysKHR.
32.3. Shader Binding Table
A shader binding table is a resource which establishes the relationship between the ray tracing pipeline and the acceleration structures that were built for the ray tracing pipeline. It indicates the shaders that operate on each geometry in an acceleration structure. In addition, it contains the resources accessed by each shader, including indices of textures, buffer device addresses, and constants. The application allocates and manages shader binding tables as VkBuffer objects.
Each entry in the shader binding table consists of
shaderGroupHandleSize bytes of data as queried by
vkGetRayTracingShaderGroupHandlesKHR to refer to the shader that it
invokes.
The remainder of the data specified by the stride is application-visible
data that can be referenced by a ShaderRecordBufferKHR block in the
shader.
The shader binding tables to use in a ray tracing pipeline are passed to the
vkCmdTraceRaysKHR, or vkCmdTraceRaysIndirectKHR commands.
Shader binding tables are read-only in shaders that are executing on the ray
tracing pipeline.
Accesses to the shader binding table from ray tracing pipelines must be
synchronized with the
VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_SHADER_READ_BIT.
32.3.1. 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 vkCmdTraceRaysKHR using the
pRaygenShaderBindingTable->buffer and
pRaygenShaderBindingTable->offset parameters — there is no indexing.
pRaygenShaderBindingTable->stride is unused.
All data accessed must be less than pRaygenShaderBindingTable->size
bytes from the base offset.
Hit Shaders
The base for the computation of intersection, any-hit and closest hit shader
locations is the instanceShaderBindingTableRecordOffset value stored
with each instance of a top-level acceleration structure.
This value determines the beginning of the shader binding table records for
a given instance.
Each geometry in the instance must map to at least one hit program record.
In the following rule, geometryIndex refers to the location of the
geometry within the instance.
This index is available to ray shaders via the RayGeometryIndexKHR
built-in.
The sbtRecordStride and sbtRecordOffset values are passed in as
parameters to
calls made in the shaders.
See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language
Specification for more details.
In SPIR-V, these correspond to the SBTOffset and SBTStride
parameters to the OpTraceRayKHR instruction.
The result of this computation is then added to
pHitShaderBindingTable->offset
, a base offset passed to vkCmdTraceRaysKHR
.
The complete rule to compute a hit shader binding table record address in
the pHitShaderBindingTable->buffer is:
-
pHitShaderBindingTable->offset+pHitShaderBindingTable->stride× (instanceShaderBindingTableRecordOffset+ geometryIndex ×sbtRecordStride+sbtRecordOffset)
All data accessed must be less than pHitShaderBindingTable->size
bytes from the base offset.
Miss Shaders
A miss shader is executed whenever a ray query fails to find an intersection for the given scene geometry. Multiple miss shaders may be executed throughout a ray tracing dispatch.
The base for the computation of miss shader locations is
pMissShaderBindingTable->offset, a base offset passed into
vkCmdTraceRaysKHR.
The missIndex value is passed in as a parameter to
calls made in the shaders.
See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language
Specification for more details.
In SPIR-V, this corresponds to the MissIndex parameter to the
OpTraceRayKHR instruction.
The complete rule to compute a miss shader binding table record address in
the pMissShaderBindingTable->buffer is:
-
pMissShaderBindingTable->offset+pMissShaderBindingTable->stride×missIndex
All data accessed must be less than pMissShaderBindingTable->size
bytes from the base offset.
Callable Shaders
A callable shader is executed when requested by a ray tracing shader. Multiple callable shaders may be executed throughout a ray tracing dispatch.
The base for the computation of callable shader locations is
pCallableShaderBindingTable->offset, a base offset passed into
vkCmdTraceRaysKHR.
The sbtRecordIndex value is passed in as a parameter to
calls made in the shaders.
See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language
Specification for more details.
In SPIR-V, this corresponds to the SBTIndex parameter to the
OpExecuteCallableKHR instruction.
The complete rule to compute a callable shader binding table record address
in the pCallableShaderBindingTable->buffer is:
-
pCallableShaderBindingTable->offset+pCallableShaderBindingTable->stride×sbtRecordIndex
All data accessed must be less than pCallableShaderBindingTable->size
bytes from the base offset.
32.4. Acceleration Structures
Acceleration structures are data structures used by the implementation to efficiently manage scene geometry as it is traversed during a ray tracing query. The application is responsible for managing acceleration structure objects (see Acceleration Structures), including allocation, destruction, executing builds or updates, and synchronizing resources used during ray tracing queries.
There are two types of acceleration structures, top level acceleration structures and bottom level acceleration structures.
32.4.2. Inactive Primitives and Instances
Acceleration structures allow the use of particular input values to signal inactive primitives or instances.
An inactive triangle is one for which the first (X) component of each vertex is NaN. If any other vertex component is NaN, and the first is not, the behavior is undefined. If the vertex format does not have a NaN representation, then all triangles are considered active.
An inactive instance is one whose acceleration structure handle is VK_NULL_HANDLE.
An inactive AABB is one for which the minimum X coordinate is NaN. If any other component is NaN, and the first is not, the behavior is undefined.
In the above definitions, "NaN" refers to any type of NaN. Signaling, non-signaling, quiet, loud, or otherwise.
An inactive object is considered invisible to all rays, and should not be represented in the acceleration structure. Implementations should ensure that the presence of inactive objects does not seriously degrade ray tracing performance.
Inactive objects are counted in the auto-generated index sequences which are
provided to shaders via InstanceId and PrimitiveId SPIR-V
decorations.
This allows objects in the scene to change freely between the active and
inactive states, without affecting the layout of any arrays which are being
indexed using the ID values.
Any transition between the active and inactive states requires a full acceleration structure rebuild. Applications must not perform an acceleration structure update where an object is active in the source acceleration structure but would be inactive in the destination, or vice versa.
32.4.3. Top Level Acceleration Structures
Opaque acceleration structure for an array of instances. The descriptor referencing this is the starting point for tracing. The top level acceleration structure takes a reference to any bottom level acceleration structure referenced by its instances. Those bottom level acceleration structure objects must be valid when the top level acceleration structure is accessed.
32.4.4. Bottom Level Acceleration Structures
Opaque acceleration structure for an array of geometries.
32.4.5. Building Acceleration Structures
To build acceleration structures call:
// Provided by VK_KHR_ray_tracing
void vkCmdBuildAccelerationStructureKHR(
VkCommandBuffer commandBuffer,
uint32_t infoCount,
const VkAccelerationStructureBuildGeometryInfoKHR* pInfos,
const VkAccelerationStructureBuildOffsetInfoKHR* const* ppOffsetInfos);-
commandBufferis the command buffer into which the command will be recorded. -
infoCountis the number of acceleration structures to build. It specifies the number of thepInfosstructures andppOffsetInfospointers that must be provided. -
pInfosis an array ofinfoCountVkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure. -
ppOffsetInfosis an array ofinfoCountpointers to arrays of VkAccelerationStructureBuildOffsetInfoKHR structures. EachppOffsetInfos[i] is an array ofpInfos[i].geometryCountVkAccelerationStructureBuildOffsetInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined bypInfos[i].
The vkCmdBuildAccelerationStructureKHR command provides the ability to
initiate multiple acceleration structures builds, however there is no
ordering or synchronization implied between any of the individual
acceleration structure builds.
|
Note
This means that an application cannot build a top-level acceleration structure in the same vkCmdBuildAccelerationStructureKHR call as the associated bottom-level or instance acceleration structures are being built. There also cannot be any memory aliasing between any acceleration structure memories or scratch memories being used by any of the builds. |
Accesses to the acceleration structure scratch buffers as identified by the
VkAccelerationStructureBuildGeometryInfoKHR→scratchData buffer
device addresses must be synchronized with
the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR.
To build an acceleration structure with some parameters sourced on the device call:
// Provided by VK_KHR_ray_tracing
void vkCmdBuildAccelerationStructureIndirectKHR(
VkCommandBuffer commandBuffer,
const VkAccelerationStructureBuildGeometryInfoKHR* pInfo,
VkBuffer indirectBuffer,
VkDeviceSize indirectOffset,
uint32_t indirectStride);-
commandBufferis the command buffer into which the command will be recorded. -
pInfois a pointer to a VkAccelerationStructureBuildGeometryInfoKHR structure defining the geometry used to build the acceleration structure. -
indirectBufferis the VkBuffer containingpInfo->geometryCountVkAccelerationStructureBuildOffsetInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined bypInfo. -
indirectOffsetis the byte offset intoindirectBufferwhere offset parameters begin. -
strideis the byte stride between successive sets of offset parameters.
The VkAccelerationStructureBuildGeometryInfoKHR structure is defined
as:
// Provided by VK_KHR_ray_tracing
typedef struct VkAccelerationStructureBuildGeometryInfoKHR {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureTypeKHR type;
VkBuildAccelerationStructureFlagsKHR flags;
VkBool32 update;
VkAccelerationStructureKHR srcAccelerationStructure;
VkAccelerationStructureKHR dstAccelerationStructure;
VkBool32 geometryArrayOfPointers;
uint32_t geometryCount;
const VkAccelerationStructureGeometryKHR* const* ppGeometries;
VkDeviceOrHostAddressKHR scratchData;
} VkAccelerationStructureBuildGeometryInfoKHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis a VkAccelerationStructureTypeKHR value specifying the type of acceleration structure being built. -
flagsis a bitmask of VkBuildAccelerationStructureFlagBitsKHR specifying additional parameters of the acceleration structure. -
updatespecifies whether to updatedstAccelerationStructurewith the data insrcAccelerationStructureor not. -
srcAccelerationStructurepoints to an existing acceleration structure that is to be used to update thedstacceleration structure whenupdateisVK_TRUE. -
dstAccelerationStructurepoints to the target acceleration structure for the build. -
geometryArrayOfPointersspecifies whetherppGeometriesis used as a pointer to an array of pointers or a pointer to a pointer to an array. -
geometryCountspecifies the number of geometries that will be built intodstAccelerationStructure. -
ppGeometriesis either a pointer to an array of pointers to VkAccelerationStructureGeometryKHR structures ifgeometryArrayOfPointersisVK_TRUE, or a pointer to a pointer to an array of VkAccelerationStructureGeometryKHR structures if it isVK_FALSE. Each element of the array describes the data used to build each acceleration structure geometry. -
scratchDatais the device or host address to memory that will be used as scratch memory for the build.
|
Note
Elements of |
The VkDeviceOrHostAddressKHR union is defined as:
// Provided by VK_KHR_ray_tracing
typedef union VkDeviceOrHostAddressKHR {
VkDeviceAddress deviceAddress;
void* hostAddress;
} VkDeviceOrHostAddressKHR;-
deviceAddressis a buffer device address as returned by the vkGetBufferDeviceAddressKHR command. -
hostAddressis a host memory address.
The VkDeviceOrHostAddressConstKHR union is defined as:
// Provided by VK_KHR_ray_tracing
typedef union VkDeviceOrHostAddressConstKHR {
VkDeviceAddress deviceAddress;
const void* hostAddress;
} VkDeviceOrHostAddressConstKHR;-
deviceAddressis a buffer device address as returned by the vkGetBufferDeviceAddressKHR command. -
hostAddressis a const host memory address.
The VkAccelerationStructureGeometryKHR structure is defined as:
// Provided by VK_KHR_ray_tracing
typedef struct VkAccelerationStructureGeometryKHR {
VkStructureType sType;
const void* pNext;
VkGeometryTypeKHR geometryType;
VkAccelerationStructureGeometryDataKHR geometry;
VkGeometryFlagsKHR flags;
} VkAccelerationStructureGeometryKHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
geometryTypedescribes which type of geometry thisVkAccelerationStructureGeometryKHRrefers to. -
geometryis a VkAccelerationStructureGeometryDataKHR union describing the geometry data for the relevant geometry type. -
flagsis a bitmask of VkGeometryFlagBitsKHR values describing additional properties of how the geometry should be built.
The VkAccelerationStructureGeometryDataKHR union is defined as:
// Provided by VK_KHR_ray_tracing
typedef union VkAccelerationStructureGeometryDataKHR {
VkAccelerationStructureGeometryTrianglesDataKHR triangles;
VkAccelerationStructureGeometryAabbsDataKHR aabbs;
VkAccelerationStructureGeometryInstancesDataKHR instances;
} VkAccelerationStructureGeometryDataKHR;-
trianglesis a VkAccelerationStructureGeometryTrianglesDataKHR structure. -
aabbsis a VkAccelerationStructureGeometryAabbsDataKHR struture. -
instancesis a VkAccelerationStructureGeometryInstancesDataKHR structure.
The VkAccelerationStructureGeometryTrianglesDataKHR structure is
defined as:
// Provided by VK_KHR_ray_tracing
typedef struct VkAccelerationStructureGeometryTrianglesDataKHR {
VkStructureType sType;
const void* pNext;
VkFormat vertexFormat;
VkDeviceOrHostAddressConstKHR vertexData;
VkDeviceSize vertexStride;
VkIndexType indexType;
VkDeviceOrHostAddressConstKHR indexData;
VkDeviceOrHostAddressConstKHR transformData;
} VkAccelerationStructureGeometryTrianglesDataKHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexFormatis the VkFormat of each vertex element. -
vertexDatais a device or host address to memory containing vertex data for this geometry. -
vertexStrideis the stride in bytes between each vertex. -
indexTypeis the VkIndexType of each index element. -
indexDatais a device or host address to memory containing index data for this geometry. -
transformDatais a device or host address to memory containing an optional reference to a VkTransformMatrixKHR structure defining a transformation that should be applied to vertices in this geometry.
The VkTransformMatrixKHR structure is defined as:
// Provided by VK_KHR_ray_tracing
typedef struct VkTransformMatrixKHR {
float matrix[3][4];
} VkTransformMatrixKHR;-
matrixis a 3x4 row-major affine transformation matrix.
The VkAccelerationStructureGeometryAabbsDataKHR structure is defined
as:
// Provided by VK_KHR_ray_tracing
typedef struct VkAccelerationStructureGeometryAabbsDataKHR {
VkStructureType sType;
const void* pNext;
VkDeviceOrHostAddressConstKHR data;
VkDeviceSize stride;
} VkAccelerationStructureGeometryAabbsDataKHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
datais a device or host address to memory containing VkAabbPositionsKHR structures containing position data for each axis-aligned bounding box in the geometry. -
strideis the stride in bytes between each entry indata.
The VkAabbPositionsKHR structure is defined as:
// Provided by VK_KHR_ray_tracing
typedef struct VkAabbPositionsKHR {
float minX;
float minY;
float minZ;
float maxX;
float maxY;
float maxZ;
} VkAabbPositionsKHR;-
minXis the x position of one opposing corner of a bounding box. -
minYis the y position of one opposing corner of a bounding box. -
minZis the z position of one opposing corner of a bounding box. -
maxXis the x position of the other opposing corner of a bounding box. -
maxYis the y position of the other opposing corner of a bounding box. -
maxZis the z position of the other opposing corner of a bounding box.
The VkAccelerationStructureGeometryInstancesDataKHR structure is
defined as:
// Provided by VK_KHR_ray_tracing
typedef struct VkAccelerationStructureGeometryInstancesDataKHR {
VkStructureType sType;
const void* pNext;
VkBool32 arrayOfPointers;
VkDeviceOrHostAddressConstKHR data;
} VkAccelerationStructureGeometryInstancesDataKHR;-
sTypeis the type of this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
arrayOfPointersspecifies whetherdatais used as an array of addresses or just an array. -
datais either the address of an array of device or host addresses referencing individual VkAccelerationStructureInstanceKHR structures ifarrayOfPointersisVK_TRUE, or the address of an array of VkAccelerationStructureInstanceKHR structures.
Acceleration structure instances can be built into top-level acceleration structures. Each acceleration structure instance is a separate entry in the top-level acceleration structure which includes all the geometry of a bottom-level acceleration structure at a transformed location. Multiple instances can point to the same bottom level acceleration structure.
An acceleration structure instance is defined by the structure:
// Provided by VK_KHR_ray_tracing
typedef struct VkAccelerationStructureInstanceKHR {
VkTransformMatrixKHR transform;
uint32_t instanceCustomIndex:24;
uint32_t mask:8;
uint32_t instanceShaderBindingTableRecordOffset:24;
VkGeometryInstanceFlagsKHR flags:8;
uint64_t accelerationStructureReference;
} VkAccelerationStructureInstanceKHR;-
transformis a VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure. -
instanceCustomIndexis a 24-bit user-specified index value accessible to ray shaders in theInstanceCustomIndexKHRbuilt-in. -
maskis an 8-bit visibility mask for the geometry. The instance may only be hit ifrayMask & instance.mask != 0 -
instanceShaderBindingTableRecordOffsetis a 24-bit offset used in calculating the hit shader binding table index. -
flagsis an 8-bit mask of VkGeometryInstanceFlagBitsKHR values to apply to this instance. -
accelerationStructureReferenceis either:-
a device address containing the value obtained from vkGetAccelerationStructureDeviceAddressKHR (used by device operations which reference acceleration structures) or,
-
a VkAccelerationStructureKHR object (used by host operations which reference acceleration structures).
-
The C language spec does not define the ordering of bit-fields, but in practice, this struct produces the correct layout with existing compilers. The intended bit pattern is for the following:
-
instanceCustomIndexandmaskoccupy the same memory as if a singleint32_twas specified in their place-
instanceCustomIndexoccupies the 24 least significant bits of that memory -
maskoccupies the 8 most significant bits of that memory
-
-
instanceShaderBindingTableRecordOffsetandflagsoccupy the same memory as if a singleint32_twas specified in their place-
instanceShaderBindingTableRecordOffsetoccupies the 24 least significant bits of that memory -
flagsoccupies the 8 most significant bits of that memory
-
If a compiler produces code that diverges from that pattern, applications must employ another method to set values according to the correct bit pattern.
Possible values of flags in the instance modifying the behavior of
that instance are:
// Provided by VK_KHR_ray_tracing
typedef enum VkGeometryInstanceFlagBitsKHR {
VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR = 0x00000001,
VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_KHR = 0x00000002,
VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR = 0x00000004,
VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR = 0x00000008,
} VkGeometryInstanceFlagBitsKHR;-
VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHRdisables face culling for this instance. -
VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_KHRindicates that the front face of the triangle for culling purposes is the face that is counter clockwise in object space relative to the ray origin. Because the facing is determined in object space, an instance transform matrix does not change the winding, but a geometry transform does. -
VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHRcauses this instance to act as thoughVK_GEOMETRY_OPAQUE_BIT_KHRwere specified on all geometries referenced by this instance. This behavior can be overridden by the SPIR-VNoOpaqueKHRray flag. -
VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHRcauses this instance to act as thoughVK_GEOMETRY_OPAQUE_BIT_KHRwere not specified on all geometries referenced by this instance. This behavior can be overridden by the SPIR-VOpaqueKHRray flag.
VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR and
VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR must not be used in the
same flag.
// Provided by VK_KHR_ray_tracing
typedef VkFlags VkGeometryInstanceFlagsKHR;VkGeometryInstanceFlagsKHR is a bitmask type for setting a mask of
zero or more VkGeometryInstanceFlagBitsKHR.
VkAccelerationStructureBuildOffsetInfoKHR is defined as:
// Provided by VK_KHR_ray_tracing
typedef struct VkAccelerationStructureBuildOffsetInfoKHR {
uint32_t primitiveCount;
uint32_t primitiveOffset;
uint32_t firstVertex;
uint32_t transformOffset;
} VkAccelerationStructureBuildOffsetInfoKHR;-
primitiveCountdefines the number of primitives for a corresponding acceleration structure geometry. -
primitiveOffsetdefines an offset in bytes into the memory where primitive data is defined. -
firstVertexis the index of the first vertex to build from for triangle geometry. -
transformOffsetdefines an offset in bytes into the memory where a transform matrix is defined.
The primitive count and primitive offset are interpreted differently depending on the VkGeometryTypeKHR used:
-
For geometries of type
VK_GEOMETRY_TYPE_TRIANGLES_KHR,primitiveCountis the number of triangles to be built, where each triangle is treated as 3 vertices.-
If the geometry uses indices,
primitiveCount× 3 indices are consumed from VkAccelerationStructureGeometryTrianglesDataKHR::indexData, starting at an offset ofprimitiveOffset. The value offirstVertexis added to the index values before fetching vertices. -
If the geometry does not use indices,
primitiveCount× 3 vertices are consumed from VkAccelerationStructureGeometryTrianglesDataKHR::vertexData, starting at an offset ofprimitiveOffset+ VkAccelerationStructureGeometryTrianglesDataKHR::vertexStride×firstVertex. -
A single VkTransformMatrixKHR structure is consumed from VkAccelerationStructureGeometryTrianglesDataKHR::
transformData, at an offset oftransformOffset. This transformation matrix is used by all triangles.
-
-
For geometries of type
VK_GEOMETRY_TYPE_AABBS_KHR,primitiveCountis the number of axis-aligned bounding boxes.primitiveCountVkAabbPositionsKHR structures are consumed from VkAccelerationStructureGeometryAabbsDataKHR::data, starting at an offset ofprimitiveOffset. -
For geometries of type
VK_GEOMETRY_TYPE_INSTANCES_KHR,primitiveCountis the number of acceleration structures.primitiveCountVkAccelerationStructureInstanceKHR structures are consumed from VkAccelerationStructureGeometryInstancesDataKHR::data, starting at an offset ofprimitiveOffset.
32.4.6. Copying Acceleration Structures
An additional command exists for copying acceleration structures without updating their contents. The acceleration structure object can be compacted in order to improve performance. Before copying, an application must query the size of the resulting acceleration structure.
To query acceleration structure size parameters call:
// Provided by VK_KHR_ray_tracing
void vkCmdWriteAccelerationStructuresPropertiesKHR(
VkCommandBuffer commandBuffer,
uint32_t accelerationStructureCount,
const VkAccelerationStructureKHR* pAccelerationStructures,
VkQueryType queryType,
VkQueryPool queryPool,
uint32_t firstQuery);-
commandBufferis the command buffer into which the command will be recorded. -
accelerationStructureCountis the count of acceleration structures for which to query the property. -
pAccelerationStructuresis a pointer to an array of existing previously built acceleration structures. -
queryTypeis a VkQueryType value specifying the type of queries managed by the pool. -
queryPoolis the query pool that will manage the results of the query. -
firstQueryis the first query index within the query pool that will contain theaccelerationStructureCountnumber of results.
To copy an acceleration structure call:
// Provided by VK_KHR_ray_tracing
void vkCmdCopyAccelerationStructureKHR(
VkCommandBuffer commandBuffer,
const VkCopyAccelerationStructureInfoKHR* pInfo);-
commandBufferis the command buffer into which the command will be recorded. -
pInfois a pointer to a VkCopyAccelerationStructureInfoKHR structure defining the copy operation.
The VkCopyAccelerationStructureInfoKHR structure is defined as:
// Provided by VK_KHR_ray_tracing
typedef struct VkCopyAccelerationStructureInfoKHR {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureKHR src;
VkAccelerationStructureKHR dst;
VkCopyAccelerationStructureModeKHR mode;
} VkCopyAccelerationStructureInfoKHR;-
srcis the source acceleration structure for the copy. -
dstis the target acceleration structure for the copy. -
modeis a VkCopyAccelerationStructureModeKHR value that specifies additional operations to perform during the copy.
Possible values of mode specifying additional operations to perform
during the copy, are:
// Provided by VK_KHR_ray_tracing
typedef enum VkCopyAccelerationStructureModeKHR {
VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR = 0,
VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR = 1,
VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR = 2,
VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR = 3,
} VkCopyAccelerationStructureModeKHR;-
VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHRcreates a direct copy of the acceleration structure specified insrcinto the one specified bydst. Thedstacceleration structure must have been created with the same parameters assrc. -
VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHRcreates a more compact version of an acceleration structuresrcintodst. The acceleration structuredstmust have been created with acompactedSizecorresponding to the one returned by vkCmdWriteAccelerationStructuresPropertiesKHR after the build of the acceleration structure specified bysrc. -
VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHRserializes the acceleration structure to a semi-opaque format which can be reloaded on a compatible implementation. -
VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHRdeserializes the semi-opaque serialization format in the buffer to the acceleration structure.
To copy an acceleration structure to device memory call:
// Provided by VK_KHR_ray_tracing
void vkCmdCopyAccelerationStructureToMemoryKHR(
VkCommandBuffer commandBuffer,
const VkCopyAccelerationStructureToMemoryInfoKHR* pInfo);This command produces the same results as vkCopyAccelerationStructureToMemoryKHR, but writes its result to a device address, and is executed on the device rather than the host. The output may not necessarily be bit-for-bit identical, but it can be equally used by either vkCmdCopyMemoryToAccelerationStructureKHR or vkCopyMemoryToAccelerationStructureKHR.
-
commandBufferis the command buffer into which the command will be recorded. -
pInfois an a pointer to a VkCopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation.
The defined header structure for the serialized data consists of:
-
VK_UUID_SIZEbytes of data matchingVkPhysicalDeviceIDProperties::driverUUID -
VK_UUID_SIZEbytes of data identifying the compatibility for comparison using vkGetDeviceAccelerationStructureCompatibilityKHR -
A 64-bit integer of the total size matching the value queried using
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR -
A 64-bit integer of the deserialized size to be passed in to
VkAccelerationStructureCreateInfoKHR::compactedSize -
A 64-bit integer of the count of the number of acceleration structure handles following. This will be zero for a bottom-level acceleration structure.
The corresponding handles matching the values returned by vkGetAccelerationStructureDeviceAddressKHR are tightly packed in the buffer following the count. The application is expected to store a mapping between those handles and the original application-generated bottom-level acceleration structures to provide when deserializing.
// Provided by VK_KHR_ray_tracing
typedef struct VkCopyAccelerationStructureToMemoryInfoKHR {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureKHR src;
VkDeviceOrHostAddressKHR dst;
VkCopyAccelerationStructureModeKHR mode;
} VkCopyAccelerationStructureToMemoryInfoKHR;-
srcis the source acceleration structure for the copy -
dstis the device or host address to memory which is the target for the copy -
modeis a VkCopyAccelerationStructureModeKHR value that specifies additional operations to perform during the copy.
To copy device memory to an acceleration structure call:
// Provided by VK_KHR_ray_tracing
void vkCmdCopyMemoryToAccelerationStructureKHR(
VkCommandBuffer commandBuffer,
const VkCopyMemoryToAccelerationStructureInfoKHR* pInfo);This command can accept acceleration structures produced by either vkCmdCopyAccelerationStructureToMemoryKHR or vkCopyAccelerationStructureToMemoryKHR.
-
commandBufferis the command buffer into which the command will be recorded. -
pInfois a pointer to a VkCopyMemoryToAccelerationStructureInfoKHR structure defining the copy operation.
The structure provided as input to deserialize is as described in vkCmdCopyAccelerationStructureToMemoryKHR, with any acceleration structure handles filled in with the newly-queried handles to bottom level acceleration structures created before deserialization. These do not need to be built at deserialize time, but must be created.
The VkCopyMemoryToAccelerationStructureInfoKHR structure is defined
as:
// Provided by VK_KHR_ray_tracing
typedef struct VkCopyMemoryToAccelerationStructureInfoKHR {
VkStructureType sType;
const void* pNext;
VkDeviceOrHostAddressConstKHR src;
VkAccelerationStructureKHR dst;
VkCopyAccelerationStructureModeKHR mode;
} VkCopyMemoryToAccelerationStructureInfoKHR;-
srcis the device or host address to memory containing the source data for the copy. -
dstis the target acceleration structure for the copy. -
modeis a VkCopyAccelerationStructureModeKHR value that specifies additional operations to perform during the copy.
To check if a serialized acceleration structure is compatible with the current device call:
// Provided by VK_KHR_ray_tracing
VkResult vkGetDeviceAccelerationStructureCompatibilityKHR(
VkDevice device,
const VkAccelerationStructureVersionKHR* version);-
deviceis the device to check the version against. -
versionpoints to the VkAccelerationStructureVersionKHR version information to check against the device.
This possible return values for
vkGetDeviceAccelerationStructureCompatibilityKHR are:
-
VK_SUCCESSis returned if an acceleration structure serialized withversionas the version information is compatible withdevice. -
VK_ERROR_INCOMPATIBLE_VERSION_KHRis returned if an acceleration structure serialized withversionas the version information is not compatible withdevice.
The VkAccelerationStructureVersionKHR structure is defined as:
// Provided by VK_KHR_ray_tracing
typedef struct VkAccelerationStructureVersionKHR {
VkStructureType sType;
const void* pNext;
const uint8_t* versionData;
} VkAccelerationStructureVersionKHR;-
versionDatais a pointer to the version header as defined in VkCopyAccelerationStructureModeKHR
32.5. Host Acceleration Structure Operations
Implementations are also required to provide host implementations of the
acceleration structure operations if the
rayTracingHostAccelerationStructureCommands
feature is enabled:
-
vkBuildAccelerationStructureKHR corresponding to vkCmdBuildAccelerationStructureKHR
-
vkCopyAccelerationStructureKHR corresponding to vkCmdCopyAccelerationStructureKHR
-
vkCopyAccelerationStructureToMemoryKHR corresponding to vkCmdCopyAccelerationStructureToMemoryKHR
-
vkCopyMemoryToAccelerationStructureKHR corresponding to vkCmdCopyMemoryToAccelerationStructureKHR
-
vkWriteAccelerationStructuresPropertiesKHR corresponding to vkCmdWriteAccelerationStructuresPropertiesKHR
These commands are functionally equivalent to their device counterparts, except that they are executed on the host timeline, rather than being enqueued into command buffers.
All acceleration structures used by the host commands must be bound to host-visible memory, and all input data for acceleration structure builds must be referenced using host addresses instead of device addresses. Applications are not required to map acceleration structure memory when using the host commands.
|
Note
The vkBuildAccelerationStructureKHR and vkCmdBuildAccelerationStructureKHR may use different algorithms, and thus are not required to produce identical structures. The structures produced by these two commands may exhibit different memory footprints or traversal performance, but should strive to be similar where possible. Apart from these details, the host and device operations are interchangable. For example, an application can use vkBuildAccelerationStructureKHR to build a structure, compact it on the device using vkCmdCopyAccelerationStructureKHR, and serialize the result using vkCopyAccelerationStructureToMemoryKHR. |
To build acceleration structures on the host, call:
// Provided by VK_KHR_ray_tracing
VkResult vkBuildAccelerationStructureKHR(
VkDevice device,
uint32_t infoCount,
const VkAccelerationStructureBuildGeometryInfoKHR* pInfos,
const VkAccelerationStructureBuildOffsetInfoKHR* const* ppOffsetInfos);This command fulfills the same task as vkCmdBuildAccelerationStructureKHR but executed by the host.
-
deviceis theVkDevicefor which the acceleration structures are being built. -
infoCountis the number of acceleration structures to build. It specifies the number of thepInfosstructures andppOffsetInfospointers that must be provided. -
pInfosis a pointer to an array ofinfoCountVkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure. -
ppOffsetInfosis an array ofinfoCountpointers to arrays of VkAccelerationStructureBuildOffsetInfoKHR structures. EachppOffsetInfos[i] is an array ofpInfos[i].geometryCountVkAccelerationStructureBuildOffsetInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined bypInfos[i].
The vkBuildAccelerationStructureKHR command provides the ability to
initiate multiple acceleration structures builds, however there is no
ordering or synchronization implied between any of the individual
acceleration structure builds.
|
Note
This means that an application cannot build a top-level acceleration structure in the same vkBuildAccelerationStructureKHR call as the associated bottom-level or instance acceleration structures are being built. There also cannot be any memory aliasing between any acceleration structure memories or scratch memories being used by any of the builds. |
If the VkDeferredOperationInfoKHR structure is included in the
pNext chain of any VkAccelerationStructureBuildGeometryInfoKHR
structure, the operation of this command is deferred, as defined in the
Deferred Host Operations chapter.
To copy or compact an acceleration structure on the host, call:
// Provided by VK_KHR_ray_tracing
VkResult vkCopyAccelerationStructureKHR(
VkDevice device,
const VkCopyAccelerationStructureInfoKHR* pInfo);This command fulfills the same task as vkCmdCopyAccelerationStructureKHR but executed by the host.
-
deviceis the device which owns the acceleration structures. -
pInfois a pointer to a VkCopyAccelerationStructureInfoKHR structure defining the copy operation.
If the VkDeferredOperationInfoKHR structure is included in the
pNext chain of the VkCopyAccelerationStructureInfoKHR structure,
the operation of this command is deferred, as defined in the
Deferred Host Operations chapter.
// Provided by VK_KHR_ray_tracing
VkResult vkCopyMemoryToAccelerationStructureKHR(
VkDevice device,
const VkCopyMemoryToAccelerationStructureInfoKHR* pInfo);This command fulfills the same task as vkCmdCopyMemoryToAccelerationStructureKHR but is executed by the host.
This command can accept acceleration structures produced by either vkCmdCopyAccelerationStructureToMemoryKHR or vkCopyAccelerationStructureToMemoryKHR.
-
deviceis the device which ownspInfo->dst. -
pInfois a pointer to a VkCopyMemoryToAccelerationStructureInfoKHR structure defining the copy operation.
If the VkDeferredOperationInfoKHR structure is included in the
pNext chain of the VkCopyMemoryToAccelerationStructureInfoKHR
structure, the operation of this command is deferred, as defined in the
Deferred Host Operations chapter.
// Provided by VK_KHR_ray_tracing
VkResult vkCopyAccelerationStructureToMemoryKHR(
VkDevice device,
const VkCopyAccelerationStructureToMemoryInfoKHR* pInfo);This command fulfills the same task as vkCmdCopyAccelerationStructureToMemoryKHR but executed by the host.
This command produces the same results as vkCmdCopyAccelerationStructureToMemoryKHR, but writes its result directly to a host pointer, and is executed on the host rather than the device. The output may not necessarily be bit-for-bit identical, but it can be equally used by either vkCmdCopyMemoryToAccelerationStructureKHR or vkCopyMemoryToAccelerationStructureKHR.
-
deviceis the device which ownspInfo->src. -
pInfois a pointer to a VkCopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation.
If the VkDeferredOperationInfoKHR structure is included in the
pNext chain of the VkCopyAccelerationStructureToMemoryInfoKHR
structure, the operation of this command is deferred, as defined in the
Deferred Host Operations chapter.
// Provided by VK_KHR_ray_tracing
VkResult vkWriteAccelerationStructuresPropertiesKHR(
VkDevice device,
uint32_t accelerationStructureCount,
const VkAccelerationStructureKHR* pAccelerationStructures,
VkQueryType queryType,
size_t dataSize,
void* pData,
size_t stride);This command fulfills the same task as vkCmdWriteAccelerationStructuresPropertiesKHR but executed by the host.
-
deviceis the device which owns the acceleration structures inpAccelerationStructures. -
accelerationStructureCountis the count of acceleration structures for which to query the property. -
pAccelerationStructurespoints to an array of existing previously built acceleration structures. -
queryTypeis a VkQueryType value specifying the property to be queried. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais a pointer to a user-allocated buffer where the results will be written. -
strideis the stride in bytes between results for individual queries withinpData.