32. Ray Tracing

Ray tracing uses a separate rendering pipeline from both the graphics and compute pipelines (see Ray Tracing Pipeline).

image/svg+xml Any Hit Intersection Hit? Closest Hit Miss Y N RayGeneration AccelerationStructureTraversal
Figure 22. Ray tracing pipeline execution
Caption

Interaction between the different shader stages in the 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:

  • OpTraceRayKHR which may invoke intersection, any-hit, closest hit, or miss shaders,

  • OpReportIntersectionKHR which may invoke any-hit shaders, and

  • OpExecuteCallableKHR which 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 Subgroup scoped OpReadClockKHR read before the dynamic instance of a repack instruction should not be compared to the result of that clock instruction after the repack instruction.

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, and ShaderRecordBufferKHR storage classes can be synchronized using the ShaderCallKHR scope.

  • the CallableDataKHR, IncomingCallableDataKHR, RayPayloadKHR, HitAttributeKHR, and IncomingRayPayloadKHR storage 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);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pRaygenShaderBindingTable is a VkStridedBufferRegionKHR that holds the shader binding table data for the ray generation shader stage.

  • pMissShaderBindingTable is a VkStridedBufferRegionKHR that holds the shader binding table data for the miss shader stage.

  • pHitShaderBindingTable is a VkStridedBufferRegionKHR that holds the shader binding table data for the hit shader stage.

  • pCallableShaderBindingTable is a VkStridedBufferRegionKHR that holds the shader binding table data for the callable shader stage.

  • width is the width of the ray trace query dimensions.

  • height is height of the ray trace query dimensions.

  • depth is depth of the ray trace query dimensions.

When the command is executed, a ray generation group of width × height × depth rays is assembled.

Valid Usage
  • VUID-vkCmdTraceRaysKHR-None-02690
    If a VkImageView is sampled with VK_FILTER_LINEAR as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

  • VUID-vkCmdTraceRaysKHR-None-02691
    If a VkImageView is accessed using atomic operations as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT

  • VUID-vkCmdTraceRaysKHR-None-02697
    For each set n that is statically used by the VkPipeline bound to the pipeline bind point used by this command, a descriptor set must have been bound to n at the same pipeline bind point, with a VkPipelineLayout that is compatible for set n, with the VkPipelineLayout used to create the current VkPipeline, as described in Pipeline Layout Compatibility

  • VUID-vkCmdTraceRaysKHR-None-02698
    For each push constant that is statically used by the VkPipeline bound to the pipeline bind point used by this command, a push constant value must have been set for the same pipeline bind point, with a VkPipelineLayout that is compatible for push constants, with the VkPipelineLayout used to create the current VkPipeline, as described in Pipeline Layout Compatibility

  • VUID-vkCmdTraceRaysKHR-None-02699
    Descriptors in each bound descriptor set, specified via vkCmdBindDescriptorSets, must be valid if they are statically used by the VkPipeline bound to the pipeline bind point used by this command

  • VUID-vkCmdTraceRaysKHR-None-02700
    A valid pipeline must be bound to the pipeline bind point used by this command

  • VUID-vkCmdTraceRaysKHR-commandBuffer-02701
    If the VkPipeline object bound to the pipeline bind point used by this command requires any dynamic state, that state must have been set for commandBuffer, and done so after any previously bound pipeline with the corresponding state not specified as dynamic

  • VUID-vkCmdTraceRaysKHR-None-02859
    There must not have been any calls to dynamic state setting commands for any state not specified as dynamic in the VkPipeline object bound to the pipeline bind point used by this command, since that pipeline was bound

  • VUID-vkCmdTraceRaysKHR-None-02702
    If the VkPipeline object bound to the pipeline bind point used by this command accesses a VkSampler object that uses unnormalized coordinates, that sampler must not be used to sample from any VkImage with a VkImageView of the type VK_IMAGE_VIEW_TYPE_3D, VK_IMAGE_VIEW_TYPE_CUBE, VK_IMAGE_VIEW_TYPE_1D_ARRAY, VK_IMAGE_VIEW_TYPE_2D_ARRAY or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage

  • VUID-vkCmdTraceRaysKHR-None-02703
    If the VkPipeline object bound to the pipeline bind point used by this command accesses a VkSampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions with ImplicitLod, Dref or Proj in their name, in any shader stage

  • VUID-vkCmdTraceRaysKHR-None-02704
    If the VkPipeline object bound to the pipeline bind point used by this command accesses a VkSampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions that includes a LOD bias or any offset values, in any shader stage

  • VUID-vkCmdTraceRaysKHR-None-02705
    If the robust buffer access feature is not enabled, and if the VkPipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point

  • VUID-vkCmdTraceRaysKHR-None-02706
    If the robust buffer access feature is not enabled, and if the VkPipeline object bound to the pipeline bind point used by this command accesses a storage buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point

  • VUID-vkCmdTraceRaysKHR-commandBuffer-02707
    If commandBuffer is an unprotected command buffer, any resource accessed by the VkPipeline object bound to the pipeline bind point used by this command must not be a protected resource

  • VUID-vkCmdTraceRaysKHR-None-04115
    If a VkImageView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.

  • VUID-vkCmdTraceRaysKHR-OpImageWrite-04469
    If a VkBufferView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.

  • VUID-vkCmdTraceRaysKHR-None-03429
    Any shader group handle referenced by this call must have been queried from the currently bound ray tracing shader pipeline

  • VUID-vkCmdTraceRaysKHR-maxRecursionDepth-03430
    This command must not cause a shader call instruction to be executed from a shader invocation with a recursion depth greater than the value of maxRecursionDepth used to create the bound ray tracing pipeline

  • VUID-vkCmdTraceRaysKHR-pRayGenShaderBindingTable-04019
    If pRayGenShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysKHR-offset-04020
    The offset member of pRayGenShaderBindingTable must be less than the size of the pRayGenShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysKHR-pRayGenShaderBindingTable-04021
    pRayGenShaderBindingTable->offset must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysKHR-pRayGenShaderBindingTable-04022
    pRayGenShaderBindingTable->offset + pRayGenShaderBindingTable->size must be less than or equal to the size of pRayGenShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysKHR-size-04023
    The size member of pRayGenShaderBindingTable must be equal to its stride member

  • VUID-vkCmdTraceRaysKHR-pMissShaderBindingTable-04024
    If pMissShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysKHR-offset-04025
    The offset member of pMissShaderBindingTable must be less than the size of pMissShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysKHR-offset-04026
    The offset member of pMissShaderBindingTable must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysKHR-pMissShaderBindingTable-04027
    pMissShaderBindingTable->offset + pMissShaderBindingTable->size must be less than or equal to the size of pMissShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysKHR-stride-04028
    The stride member of pMissShaderBindingTable must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleSize

  • VUID-vkCmdTraceRaysKHR-stride-04029
    The stride member of pMissShaderBindingTable must be less than or equal to VkPhysicalDeviceRayTracingPropertiesKHR::maxShaderGroupStride

  • VUID-vkCmdTraceRaysKHR-pHitShaderBindingTable-04030
    If pHitShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysKHR-offset-04031
    The offset member of pHitShaderBindingTable must be less than the size of pHitShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysKHR-offset-04032
    The offset member of pHitShaderBindingTable must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysKHR-pHitShaderBindingTable-04033
    pHitShaderBindingTable->offset + pHitShaderBindingTable->size must be less than or equal to the size of pHitShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysKHR-stride-04034
    The stride member of pHitShaderBindingTable must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleSize

  • VUID-vkCmdTraceRaysKHR-stride-04035
    The stride member of pHitShaderBindingTable must be less than or equal to VkPhysicalDeviceRayTracingPropertiesKHR::maxShaderGroupStride

  • VUID-vkCmdTraceRaysKHR-pCallableShaderBindingTable-04036
    If pCallableShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysKHR-offset-04037
    The offset member of pCallableShaderBindingTable must be less than the size of pCallableShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysKHR-offset-04038
    The offset member of pCallableShaderBindingTable must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysKHR-pCallableShaderBindingTable-04039
    pCallableShaderBindingTable->offset + pCallableShaderBindingTable->size must be less than or equal to the size of pCallableShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysKHR-stride-04040
    The stride member of pCallableShaderBindingTable must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleSize

  • VUID-vkCmdTraceRaysKHR-stride-04041
    The stride member of pCallableShaderBindingTable must be less than or equal to VkPhysicalDeviceRayTracingPropertiesKHR::maxShaderGroupStride

  • VUID-vkCmdTraceRaysKHR-flags-03508
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, the buffer member of pHitShaderBindingTable must not be VK_NULL_HANDLE

  • VUID-vkCmdTraceRaysKHR-flags-03509
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, the buffer member of pHitShaderBindingTable must not be VK_NULL_HANDLE

  • VUID-vkCmdTraceRaysKHR-flags-03510
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, the buffer member of pHitShaderBindingTable must not be VK_NULL_HANDLE

  • VUID-vkCmdTraceRaysKHR-flags-03511
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, the shader group handle identified by pMissShaderBindingTable must contain a valid miss shader

  • VUID-vkCmdTraceRaysKHR-flags-03512
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, entries in pHitShaderBindingTable accessed as a result of this command in order to execute an any hit shader must not be set to zero

  • VUID-vkCmdTraceRaysKHR-flags-03513
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, entries in pHitShaderBindingTable accessed as a result of this command in order to execute a closest hit shader must not be set to zero

  • VUID-vkCmdTraceRaysKHR-flags-03514
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, entries in pHitShaderBindingTable accessed as a result of this command in order to execute an intersection shader must not be set to zero

  • VUID-vkCmdTraceRaysKHR-commandBuffer-02712
    If commandBuffer is a protected command buffer, any resource written to by the VkPipeline object bound to the pipeline bind point used by this command must not be an unprotected resource

  • VUID-vkCmdTraceRaysKHR-commandBuffer-02713
    If commandBuffer is a protected command buffer, pipeline stages other than the framebuffer-space and compute stages in the VkPipeline object bound to the pipeline bind point must not write to any resource

  • VUID-vkCmdTraceRaysKHR-width-03505
    width must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[0]

  • VUID-vkCmdTraceRaysKHR-height-03506
    height must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[1]

  • VUID-vkCmdTraceRaysKHR-depth-03507
    depth must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[2]

Valid Usage (Implicit)
  • VUID-vkCmdTraceRaysKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdTraceRaysKHR-pRaygenShaderBindingTable-parameter
    pRaygenShaderBindingTable must be a valid pointer to a valid VkStridedBufferRegionKHR structure

  • VUID-vkCmdTraceRaysKHR-pMissShaderBindingTable-parameter
    pMissShaderBindingTable must be a valid pointer to a valid VkStridedBufferRegionKHR structure

  • VUID-vkCmdTraceRaysKHR-pHitShaderBindingTable-parameter
    pHitShaderBindingTable must be a valid pointer to a valid VkStridedBufferRegionKHR structure

  • VUID-vkCmdTraceRaysKHR-pCallableShaderBindingTable-parameter
    pCallableShaderBindingTable must be a valid pointer to a valid VkStridedBufferRegionKHR structure

  • VUID-vkCmdTraceRaysKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdTraceRaysKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdTraceRaysKHR-renderpass
    This command must only be called outside of a render pass instance

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

The VkStridedBufferRegionKHR structure is defined as:

// Provided by VK_KHR_ray_tracing
typedef struct VkStridedBufferRegionKHR {
    VkBuffer        buffer;
    VkDeviceSize    offset;
    VkDeviceSize    stride;
    VkDeviceSize    size;
} VkStridedBufferRegionKHR;
  • buffer is the buffer containing this region.

  • offset is the byte offset in buffer at which the region starts.

  • stride is the byte stride between consecutive elements.

  • size is the size in bytes of the region starting at offset.

Valid Usage
  • VUID-VkStridedBufferRegionKHR-buffer-03515
    If buffer is not VK_NULL_HANDLE, size plus offset must be less than or equal to the size of buffer

  • VUID-VkStridedBufferRegionKHR-buffer-03516
    If buffer is not VK_NULL_HANDLE, stride must be less than the size of buffer

Valid Usage (Implicit)
  • VUID-VkStridedBufferRegionKHR-buffer-parameter
    If buffer is not VK_NULL_HANDLE, buffer must be a valid VkBuffer handle

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);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pRaygenShaderBindingTable is a VkStridedBufferRegionKHR that holds the shader binding table data for the ray generation shader stage.

  • pMissShaderBindingTable is a VkStridedBufferRegionKHR that holds the shader binding table data for the miss shader stage.

  • pHitShaderBindingTable is a VkStridedBufferRegionKHR that holds the shader binding table data for the hit shader stage.

  • pCallableShaderBindingTable is a VkStridedBufferRegionKHR that holds the shader binding table data for the callable shader stage.

  • buffer is the buffer containing the trace ray parameters.

  • offset is the byte offset into buffer where 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.

Valid Usage
  • VUID-vkCmdTraceRaysIndirectKHR-None-02690
    If a VkImageView is sampled with VK_FILTER_LINEAR as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

  • VUID-vkCmdTraceRaysIndirectKHR-None-02691
    If a VkImageView is accessed using atomic operations as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT

  • VUID-vkCmdTraceRaysIndirectKHR-None-02697
    For each set n that is statically used by the VkPipeline bound to the pipeline bind point used by this command, a descriptor set must have been bound to n at the same pipeline bind point, with a VkPipelineLayout that is compatible for set n, with the VkPipelineLayout used to create the current VkPipeline, as described in Pipeline Layout Compatibility

  • VUID-vkCmdTraceRaysIndirectKHR-None-02698
    For each push constant that is statically used by the VkPipeline bound to the pipeline bind point used by this command, a push constant value must have been set for the same pipeline bind point, with a VkPipelineLayout that is compatible for push constants, with the VkPipelineLayout used to create the current VkPipeline, as described in Pipeline Layout Compatibility

  • VUID-vkCmdTraceRaysIndirectKHR-None-02699
    Descriptors in each bound descriptor set, specified via vkCmdBindDescriptorSets, must be valid if they are statically used by the VkPipeline bound to the pipeline bind point used by this command

  • VUID-vkCmdTraceRaysIndirectKHR-None-02700
    A valid pipeline must be bound to the pipeline bind point used by this command

  • VUID-vkCmdTraceRaysIndirectKHR-commandBuffer-02701
    If the VkPipeline object bound to the pipeline bind point used by this command requires any dynamic state, that state must have been set for commandBuffer, and done so after any previously bound pipeline with the corresponding state not specified as dynamic

  • VUID-vkCmdTraceRaysIndirectKHR-None-02859
    There must not have been any calls to dynamic state setting commands for any state not specified as dynamic in the VkPipeline object bound to the pipeline bind point used by this command, since that pipeline was bound

  • VUID-vkCmdTraceRaysIndirectKHR-None-02702
    If the VkPipeline object bound to the pipeline bind point used by this command accesses a VkSampler object that uses unnormalized coordinates, that sampler must not be used to sample from any VkImage with a VkImageView of the type VK_IMAGE_VIEW_TYPE_3D, VK_IMAGE_VIEW_TYPE_CUBE, VK_IMAGE_VIEW_TYPE_1D_ARRAY, VK_IMAGE_VIEW_TYPE_2D_ARRAY or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage

  • VUID-vkCmdTraceRaysIndirectKHR-None-02703
    If the VkPipeline object bound to the pipeline bind point used by this command accesses a VkSampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions with ImplicitLod, Dref or Proj in their name, in any shader stage

  • VUID-vkCmdTraceRaysIndirectKHR-None-02704
    If the VkPipeline object bound to the pipeline bind point used by this command accesses a VkSampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions that includes a LOD bias or any offset values, in any shader stage

  • VUID-vkCmdTraceRaysIndirectKHR-None-02705
    If the robust buffer access feature is not enabled, and if the VkPipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point

  • VUID-vkCmdTraceRaysIndirectKHR-None-02706
    If the robust buffer access feature is not enabled, and if the VkPipeline object bound to the pipeline bind point used by this command accesses a storage buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point

  • VUID-vkCmdTraceRaysIndirectKHR-commandBuffer-02707
    If commandBuffer is an unprotected command buffer, any resource accessed by the VkPipeline object bound to the pipeline bind point used by this command must not be a protected resource

  • VUID-vkCmdTraceRaysIndirectKHR-None-04115
    If a VkImageView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.

  • VUID-vkCmdTraceRaysIndirectKHR-OpImageWrite-04469
    If a VkBufferView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.

  • VUID-vkCmdTraceRaysIndirectKHR-None-03429
    Any shader group handle referenced by this call must have been queried from the currently bound ray tracing shader pipeline

  • VUID-vkCmdTraceRaysIndirectKHR-maxRecursionDepth-03430
    This command must not cause a shader call instruction to be executed from a shader invocation with a recursion depth greater than the value of maxRecursionDepth used to create the bound ray tracing pipeline

  • VUID-vkCmdTraceRaysIndirectKHR-pRayGenShaderBindingTable-04019
    If pRayGenShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysIndirectKHR-offset-04020
    The offset member of pRayGenShaderBindingTable must be less than the size of the pRayGenShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysIndirectKHR-pRayGenShaderBindingTable-04021
    pRayGenShaderBindingTable->offset must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysIndirectKHR-pRayGenShaderBindingTable-04022
    pRayGenShaderBindingTable->offset + pRayGenShaderBindingTable->size must be less than or equal to the size of pRayGenShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysIndirectKHR-size-04023
    The size member of pRayGenShaderBindingTable must be equal to its stride member

  • VUID-vkCmdTraceRaysIndirectKHR-pMissShaderBindingTable-04024
    If pMissShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysIndirectKHR-offset-04025
    The offset member of pMissShaderBindingTable must be less than the size of pMissShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysIndirectKHR-offset-04026
    The offset member of pMissShaderBindingTable must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysIndirectKHR-pMissShaderBindingTable-04027
    pMissShaderBindingTable->offset + pMissShaderBindingTable->size must be less than or equal to the size of pMissShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysIndirectKHR-stride-04028
    The stride member of pMissShaderBindingTable must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleSize

  • VUID-vkCmdTraceRaysIndirectKHR-stride-04029
    The stride member of pMissShaderBindingTable must be less than or equal to VkPhysicalDeviceRayTracingPropertiesKHR::maxShaderGroupStride

  • VUID-vkCmdTraceRaysIndirectKHR-pHitShaderBindingTable-04030
    If pHitShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysIndirectKHR-offset-04031
    The offset member of pHitShaderBindingTable must be less than the size of pHitShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysIndirectKHR-offset-04032
    The offset member of pHitShaderBindingTable must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysIndirectKHR-pHitShaderBindingTable-04033
    pHitShaderBindingTable->offset + pHitShaderBindingTable->size must be less than or equal to the size of pHitShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysIndirectKHR-stride-04034
    The stride member of pHitShaderBindingTable must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleSize

  • VUID-vkCmdTraceRaysIndirectKHR-stride-04035
    The stride member of pHitShaderBindingTable must be less than or equal to VkPhysicalDeviceRayTracingPropertiesKHR::maxShaderGroupStride

  • VUID-vkCmdTraceRaysIndirectKHR-pCallableShaderBindingTable-04036
    If pCallableShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysIndirectKHR-offset-04037
    The offset member of pCallableShaderBindingTable must be less than the size of pCallableShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysIndirectKHR-offset-04038
    The offset member of pCallableShaderBindingTable must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysIndirectKHR-pCallableShaderBindingTable-04039
    pCallableShaderBindingTable->offset + pCallableShaderBindingTable->size must be less than or equal to the size of pCallableShaderBindingTable->buffer

  • VUID-vkCmdTraceRaysIndirectKHR-stride-04040
    The stride member of pCallableShaderBindingTable must be a multiple of VkPhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleSize

  • VUID-vkCmdTraceRaysIndirectKHR-stride-04041
    The stride member of pCallableShaderBindingTable must be less than or equal to VkPhysicalDeviceRayTracingPropertiesKHR::maxShaderGroupStride

  • VUID-vkCmdTraceRaysIndirectKHR-flags-03508
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, the buffer member of pHitShaderBindingTable must not be VK_NULL_HANDLE

  • VUID-vkCmdTraceRaysIndirectKHR-flags-03509
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, the buffer member of pHitShaderBindingTable must not be VK_NULL_HANDLE

  • VUID-vkCmdTraceRaysIndirectKHR-flags-03510
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, the buffer member of pHitShaderBindingTable must not be VK_NULL_HANDLE

  • VUID-vkCmdTraceRaysIndirectKHR-flags-03511
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, the shader group handle identified by pMissShaderBindingTable must contain a valid miss shader

  • VUID-vkCmdTraceRaysIndirectKHR-flags-03512
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, entries in pHitShaderBindingTable accessed as a result of this command in order to execute an any hit shader must not be set to zero

  • VUID-vkCmdTraceRaysIndirectKHR-flags-03513
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, entries in pHitShaderBindingTable accessed as a result of this command in order to execute a closest hit shader must not be set to zero

  • VUID-vkCmdTraceRaysIndirectKHR-flags-03514
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, entries in pHitShaderBindingTable accessed as a result of this command in order to execute an intersection shader must not be set to zero

  • VUID-vkCmdTraceRaysIndirectKHR-buffer-02708
    If buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysIndirectKHR-buffer-02709
    buffer must have been created with the VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set

  • VUID-vkCmdTraceRaysIndirectKHR-offset-02710
    offset must be a multiple of 4

  • VUID-vkCmdTraceRaysIndirectKHR-commandBuffer-02711
    commandBuffer must not be a protected command buffer

  • VUID-vkCmdTraceRaysIndirectKHR-offset-03517
    (offset + sizeof(VkTraceRaysIndirectCommandKHR)) must be less than or equal to the size of buffer

  • VUID-vkCmdTraceRaysIndirectKHR-rayTracingIndirectTraceRays-03518
    the VkPhysicalDeviceRayTracingFeaturesKHR::rayTracingIndirectTraceRays feature must be enabled

Valid Usage (Implicit)
  • VUID-vkCmdTraceRaysIndirectKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdTraceRaysIndirectKHR-pRaygenShaderBindingTable-parameter
    pRaygenShaderBindingTable must be a valid pointer to a valid VkStridedBufferRegionKHR structure

  • VUID-vkCmdTraceRaysIndirectKHR-pMissShaderBindingTable-parameter
    pMissShaderBindingTable must be a valid pointer to a valid VkStridedBufferRegionKHR structure

  • VUID-vkCmdTraceRaysIndirectKHR-pHitShaderBindingTable-parameter
    pHitShaderBindingTable must be a valid pointer to a valid VkStridedBufferRegionKHR structure

  • VUID-vkCmdTraceRaysIndirectKHR-pCallableShaderBindingTable-parameter
    pCallableShaderBindingTable must be a valid pointer to a valid VkStridedBufferRegionKHR structure

  • VUID-vkCmdTraceRaysIndirectKHR-buffer-parameter
    buffer must be a valid VkBuffer handle

  • VUID-vkCmdTraceRaysIndirectKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdTraceRaysIndirectKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdTraceRaysIndirectKHR-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdTraceRaysIndirectKHR-commonparent
    Both of buffer, and commandBuffer must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

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;
  • width is the width of the ray trace query dimensions.

  • height is height of the ray trace query dimensions.

  • depth is depth of the ray trace query dimensions.

The members of VkTraceRaysIndirectCommandKHR have the same meaning as the similarly named parameters of vkCmdTraceRaysKHR.

Valid Usage
  • VUID-VkTraceRaysIndirectCommandKHR-width-03519
    width must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[0]

  • VUID-VkTraceRaysIndirectCommandKHR-height-03520
    height must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[1]

  • VUID-VkTraceRaysIndirectCommandKHR-depth-03521
    depth must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[2]

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.

image/svg+xml Top-Level Acceleration Structure Bottom-LevelAccelerationStructure Bottom-LevelAccelerationStructure Transformand shadinginformation Transformand shadinginformation Transformand shadinginformation
Figure 23. Acceleration Structure
Caption

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

32.4.1. Geometry

Geometries refer to a triangle or axis-aligned bounding box.

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);
  • commandBuffer is the command buffer into which the command will be recorded.

  • infoCount is the number of acceleration structures to build. It specifies the number of the pInfos structures and ppOffsetInfos pointers that must be provided.

  • pInfos is an array of infoCount VkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure.

  • ppOffsetInfos is an array of infoCount pointers to arrays of VkAccelerationStructureBuildOffsetInfoKHR structures. Each ppOffsetInfos[i] is an array of pInfos[i].geometryCount VkAccelerationStructureBuildOffsetInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined by pInfos[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 VkAccelerationStructureBuildGeometryInfoKHRscratchData 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.

Valid Usage
  • VUID-vkCmdBuildAccelerationStructureKHR-pOffsetInfos-03402
    Each element of ppOffsetInfos[i] must be a valid pointer to an array of pInfos[i].geometryCount VkAccelerationStructureBuildOffsetInfoKHR structures

  • VUID-vkCmdBuildAccelerationStructureKHR-pInfos-03403
    Each pInfos[i].srcAccelerationStructure must not refer to the same acceleration structure as any pInfos[i].dstAccelerationStructure that is provided to the same build command unless it is identical for an update

  • VUID-vkCmdBuildAccelerationStructureKHR-pInfos-03404
    For each pInfos[i], dstAccelerationStructure must have been created with compatible VkAccelerationStructureCreateInfoKHR where VkAccelerationStructureCreateInfoKHR::type and VkAccelerationStructureCreateInfoKHR::flags are identical to VkAccelerationStructureBuildGeometryInfoKHR::type and VkAccelerationStructureBuildGeometryInfoKHR::flags respectively, VkAccelerationStructureBuildGeometryInfoKHR::geometryCount for dstAccelerationStructure are greater than or equal to the build size, and each geometry in VkAccelerationStructureBuildGeometryInfoKHR::ppGeometries for dstAccelerationStructure has greater than or equal to the number of vertices, indices, and AABBs, VkAccelerationStructureGeometryTrianglesDataKHR::transformData is both 0 or both non-zero, and all other parameters are the same

  • VUID-vkCmdBuildAccelerationStructureKHR-pInfos-03405
    For each pInfos[i], if update is VK_TRUE, then objects that were previously active for that acceleration structure must not be made inactive as per Inactive Primitives and Instances

  • VUID-vkCmdBuildAccelerationStructureKHR-pInfos-03406
    For each pInfos[i], if update is VK_TRUE, then objects that were previously inactive for that acceleration structure must not be made active as per Inactive Primitives and Instances

  • VUID-vkCmdBuildAccelerationStructureKHR-None-03407
    Any acceleration structure instance in any top level build in this command must not reference any bottom level acceleration structure built by this command

  • VUID-vkCmdBuildAccelerationStructureKHR-pInfos-03408
    There must not be any memory aliasing between the scratch memories that are provided in all the pInfos[i].scratchData memories for the acceleration structure builds

  • VUID-vkCmdBuildAccelerationStructureKHR-None-03409
    There must not be any memory aliasing between memory bound to any top level, bottom level, or instance acceleration structure accessed by this command

Valid Usage (Implicit)
  • VUID-vkCmdBuildAccelerationStructureKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBuildAccelerationStructureKHR-pInfos-parameter
    pInfos must be a valid pointer to an array of infoCount valid VkAccelerationStructureBuildGeometryInfoKHR structures

  • VUID-vkCmdBuildAccelerationStructureKHR-ppOffsetInfos-parameter
    ppOffsetInfos must be a valid pointer to an array of infoCount VkAccelerationStructureBuildOffsetInfoKHR structures

  • VUID-vkCmdBuildAccelerationStructureKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBuildAccelerationStructureKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBuildAccelerationStructureKHR-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBuildAccelerationStructureKHR-infoCount-arraylength
    infoCount must be greater than 0

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

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);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pInfo is a pointer to a VkAccelerationStructureBuildGeometryInfoKHR structure defining the geometry used to build the acceleration structure.

  • indirectBuffer is the VkBuffer containing pInfo->geometryCount VkAccelerationStructureBuildOffsetInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined by pInfo.

  • indirectOffset is the byte offset into indirectBuffer where offset parameters begin.

  • stride is the byte stride between successive sets of offset parameters.

Valid Usage
Valid Usage (Implicit)
  • VUID-vkCmdBuildAccelerationStructureIndirectKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBuildAccelerationStructureIndirectKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkAccelerationStructureBuildGeometryInfoKHR structure

  • VUID-vkCmdBuildAccelerationStructureIndirectKHR-indirectBuffer-parameter
    indirectBuffer must be a valid VkBuffer handle

  • VUID-vkCmdBuildAccelerationStructureIndirectKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBuildAccelerationStructureIndirectKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdBuildAccelerationStructureIndirectKHR-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBuildAccelerationStructureIndirectKHR-commonparent
    Both of commandBuffer, and indirectBuffer must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

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;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • type is a VkAccelerationStructureTypeKHR value specifying the type of acceleration structure being built.

  • flags is a bitmask of VkBuildAccelerationStructureFlagBitsKHR specifying additional parameters of the acceleration structure.

  • update specifies whether to update dstAccelerationStructure with the data in srcAccelerationStructure or not.

  • srcAccelerationStructure points to an existing acceleration structure that is to be used to update the dst acceleration structure when update is VK_TRUE.

  • dstAccelerationStructure points to the target acceleration structure for the build.

  • geometryArrayOfPointers specifies whether ppGeometries is used as a pointer to an array of pointers or a pointer to a pointer to an array.

  • geometryCount specifies the number of geometries that will be built into dstAccelerationStructure.

  • ppGeometries is either a pointer to an array of pointers to VkAccelerationStructureGeometryKHR structures if geometryArrayOfPointers is VK_TRUE, or a pointer to a pointer to an array of VkAccelerationStructureGeometryKHR structures if it is VK_FALSE. Each element of the array describes the data used to build each acceleration structure geometry.

  • scratchData is the device or host address to memory that will be used as scratch memory for the build.

Note

Elements of ppGeometries are accessed as follows, based on geometryArrayOfPointers:

if (geometryArrayOfPointers) {
    use *(ppGeometries[i]);
} else {
    use (*ppGeometries)[i];
}
Valid Usage
  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-update-03537
    If update is VK_TRUE, srcAccelerationStructure must not be VK_NULL_HANDLE

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-update-03538
    If update is VK_TRUE, srcAccelerationStructure must have been built before with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR set in VkAccelerationStructureBuildGeometryInfoKHR::flags

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-scratchData-03539
    scratchData must have been created with VK_BUFFER_USAGE_RAY_TRACING_BIT_KHR usage flag

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-update-03540
    If update is VK_TRUE, the srcAccelerationStructure and dstAccelerationStructure objects must either be the same object or not have any memory aliasing

Valid Usage (Implicit)
  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_GEOMETRY_INFO_KHR

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkDeferredOperationInfoKHR

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-parameter
    type must be a valid VkAccelerationStructureTypeKHR value

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-parameter
    flags must be a valid combination of VkBuildAccelerationStructureFlagBitsKHR values

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-srcAccelerationStructure-parameter
    If srcAccelerationStructure is not VK_NULL_HANDLE, srcAccelerationStructure must be a valid VkAccelerationStructureKHR handle

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-dstAccelerationStructure-parameter
    dstAccelerationStructure must be a valid VkAccelerationStructureKHR handle

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-scratchData-parameter
    scratchData must be a valid VkDeviceOrHostAddressKHR union

  • VUID-VkAccelerationStructureBuildGeometryInfoKHR-commonparent
    Both of dstAccelerationStructure, and srcAccelerationStructure that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

The VkDeviceOrHostAddressKHR union is defined as:

// Provided by VK_KHR_ray_tracing
typedef union VkDeviceOrHostAddressKHR {
    VkDeviceAddress    deviceAddress;
    void*              hostAddress;
} VkDeviceOrHostAddressKHR;
  • deviceAddress is a buffer device address as returned by the vkGetBufferDeviceAddressKHR command.

  • hostAddress is 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;
  • deviceAddress is a buffer device address as returned by the vkGetBufferDeviceAddressKHR command.

  • hostAddress is 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;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • geometryType describes which type of geometry this VkAccelerationStructureGeometryKHR refers to.

  • geometry is a VkAccelerationStructureGeometryDataKHR union describing the geometry data for the relevant geometry type.

  • flags is a bitmask of VkGeometryFlagBitsKHR values describing additional properties of how the geometry should be built.

Valid Usage
Valid Usage (Implicit)
  • VUID-VkAccelerationStructureGeometryKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_KHR

  • VUID-VkAccelerationStructureGeometryKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkAccelerationStructureGeometryKHR-geometryType-parameter
    geometryType must be a valid VkGeometryTypeKHR value

  • VUID-VkAccelerationStructureGeometryKHR-triangles-parameter
    If geometryType is VK_GEOMETRY_TYPE_TRIANGLES_KHR, the triangles member of geometry must be a valid VkAccelerationStructureGeometryTrianglesDataKHR structure

  • VUID-VkAccelerationStructureGeometryKHR-aabbs-parameter
    If geometryType is VK_GEOMETRY_TYPE_AABBS_KHR, the aabbs member of geometry must be a valid VkAccelerationStructureGeometryAabbsDataKHR structure

  • VUID-VkAccelerationStructureGeometryKHR-instances-parameter
    If geometryType is VK_GEOMETRY_TYPE_INSTANCES_KHR, the instances member of geometry must be a valid VkAccelerationStructureGeometryInstancesDataKHR structure

  • VUID-VkAccelerationStructureGeometryKHR-flags-parameter
    flags must be a valid combination of VkGeometryFlagBitsKHR values

The VkAccelerationStructureGeometryDataKHR union is defined as:

// Provided by VK_KHR_ray_tracing
typedef union VkAccelerationStructureGeometryDataKHR {
    VkAccelerationStructureGeometryTrianglesDataKHR    triangles;
    VkAccelerationStructureGeometryAabbsDataKHR        aabbs;
    VkAccelerationStructureGeometryInstancesDataKHR    instances;
} VkAccelerationStructureGeometryDataKHR;

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;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • vertexFormat is the VkFormat of each vertex element.

  • vertexData is a device or host address to memory containing vertex data for this geometry.

  • vertexStride is the stride in bytes between each vertex.

  • indexType is the VkIndexType of each index element.

  • indexData is a device or host address to memory containing index data for this geometry.

  • transformData is 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.

Valid Usage
Valid Usage (Implicit)
  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_TRIANGLES_DATA_KHR

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexFormat-parameter
    vertexFormat must be a valid VkFormat value

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexData-parameter
    vertexData must be a valid VkDeviceOrHostAddressConstKHR union

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-indexType-parameter
    indexType must be a valid VkIndexType value

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-indexData-parameter
    If indexData is not 0, indexData must be a valid VkDeviceOrHostAddressConstKHR union

  • VUID-VkAccelerationStructureGeometryTrianglesDataKHR-transformData-parameter
    If transformData is not 0, transformData must be a valid VkDeviceOrHostAddressConstKHR union

The VkTransformMatrixKHR structure is defined as:

// Provided by VK_KHR_ray_tracing
typedef struct VkTransformMatrixKHR {
    float    matrix[3][4];
} VkTransformMatrixKHR;
  • matrix is 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;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • data is a device or host address to memory containing VkAabbPositionsKHR structures containing position data for each axis-aligned bounding box in the geometry.

  • stride is the stride in bytes between each entry in data.

Valid Usage
  • VUID-VkAccelerationStructureGeometryAabbsDataKHR-data-03544
    data must be aligned to 8 bytes

  • VUID-VkAccelerationStructureGeometryAabbsDataKHR-stride-03545
    stride must be a multiple of 8

Valid Usage (Implicit)
  • VUID-VkAccelerationStructureGeometryAabbsDataKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_AABBS_DATA_KHR

  • VUID-VkAccelerationStructureGeometryAabbsDataKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkAccelerationStructureGeometryAabbsDataKHR-data-parameter
    data must be a valid VkDeviceOrHostAddressConstKHR union

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;
  • minX is the x position of one opposing corner of a bounding box.

  • minY is the y position of one opposing corner of a bounding box.

  • minZ is the z position of one opposing corner of a bounding box.

  • maxX is the x position of the other opposing corner of a bounding box.

  • maxY is the y position of the other opposing corner of a bounding box.

  • maxZ is the z position of the other opposing corner of a bounding box.

Valid Usage
  • VUID-VkAabbPositionsKHR-minX-03546
    minX must be less than or equal to maxX

  • VUID-VkAabbPositionsKHR-minY-03547
    minY must be less than or equal to maxY

  • VUID-VkAabbPositionsKHR-minZ-03548
    minZ must be less than or equal to maxZ

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;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • arrayOfPointers specifies whether data is used as an array of addresses or just an array.

  • data is either the address of an array of device or host addresses referencing individual VkAccelerationStructureInstanceKHR structures if arrayOfPointers is VK_TRUE, or the address of an array of VkAccelerationStructureInstanceKHR structures.

Valid Usage
  • VUID-VkAccelerationStructureGeometryInstancesDataKHR-data-03549
    data must be aligned to 16 bytes

  • VUID-VkAccelerationStructureGeometryInstancesDataKHR-arrayOfPointers-03550
    If arrayOfPointers is true, each pointer must be aligned to 16 bytes

Valid Usage (Implicit)
  • VUID-VkAccelerationStructureGeometryInstancesDataKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_INSTANCES_DATA_KHR

  • VUID-VkAccelerationStructureGeometryInstancesDataKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkAccelerationStructureGeometryInstancesDataKHR-data-parameter
    data must be a valid VkDeviceOrHostAddressConstKHR union

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;
  • transform is a VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure.

  • instanceCustomIndex is a 24-bit user-specified index value accessible to ray shaders in the InstanceCustomIndexKHR built-in.

  • mask is an 8-bit visibility mask for the geometry. The instance may only be hit if rayMask & instance.mask != 0

  • instanceShaderBindingTableRecordOffset is a 24-bit offset used in calculating the hit shader binding table index.

  • flags is an 8-bit mask of VkGeometryInstanceFlagBitsKHR values to apply to this instance.

  • accelerationStructureReference is either:

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:

  • instanceCustomIndex and mask occupy the same memory as if a single int32_t was specified in their place

    • instanceCustomIndex occupies the 24 least significant bits of that memory

    • mask occupies the 8 most significant bits of that memory

  • instanceShaderBindingTableRecordOffset and flags occupy the same memory as if a single int32_t was specified in their place

    • instanceShaderBindingTableRecordOffset occupies the 24 least significant bits of that memory

    • flags occupies 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.

Valid Usage
Valid Usage (Implicit)

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_KHR disables face culling for this instance.

  • VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_KHR indicates 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_KHR causes this instance to act as though VK_GEOMETRY_OPAQUE_BIT_KHR were specified on all geometries referenced by this instance. This behavior can be overridden by the SPIR-V NoOpaqueKHR ray flag.

  • VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR causes this instance to act as though VK_GEOMETRY_OPAQUE_BIT_KHR were not specified on all geometries referenced by this instance. This behavior can be overridden by the SPIR-V OpaqueKHR ray 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;
  • primitiveCount defines the number of primitives for a corresponding acceleration structure geometry.

  • primitiveOffset defines an offset in bytes into the memory where primitive data is defined.

  • firstVertex is the index of the first vertex to build from for triangle geometry.

  • transformOffset defines 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:

Valid Usage

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);
  • commandBuffer is the command buffer into which the command will be recorded.

  • accelerationStructureCount is the count of acceleration structures for which to query the property.

  • pAccelerationStructures is a pointer to an array of existing previously built acceleration structures.

  • queryType is a VkQueryType value specifying the type of queries managed by the pool.

  • queryPool is the query pool that will manage the results of the query.

  • firstQuery is the first query index within the query pool that will contain the accelerationStructureCount number of results.

Valid Usage
  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-02493
    queryPool must have been created with a queryType matching queryType

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-02494
    The queries identified by queryPool and firstQuery must be unavailable

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-accelerationStructures-03431
    All acceleration structures in accelerationStructures must have been built with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryType-03432
    queryType must be VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR or VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR

Valid Usage (Implicit)
  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-pAccelerationStructures-parameter
    pAccelerationStructures must be a valid pointer to an array of accelerationStructureCount valid VkAccelerationStructureKHR handles

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryType-parameter
    queryType must be a valid VkQueryType value

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-parameter
    queryPool must be a valid VkQueryPool handle

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-accelerationStructureCount-arraylength
    accelerationStructureCount must be greater than 0

  • VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-commonparent
    Each of commandBuffer, queryPool, and the elements of pAccelerationStructures must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

To copy an acceleration structure call:

// Provided by VK_KHR_ray_tracing
void vkCmdCopyAccelerationStructureKHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyAccelerationStructureInfoKHR*   pInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pInfo is a pointer to a VkCopyAccelerationStructureInfoKHR structure defining the copy operation.

Valid Usage
  • VUID-vkCmdCopyAccelerationStructureKHR-None-03556
    All VkAccelerationStructureKHR objects referenced by this command must be bound to device memory

  • VUID-vkCmdCopyAccelerationStructureKHR-pNext-03557
    The VkDeferredOperationInfoKHR structure must not be included in the pNext chain of the VkCopyAccelerationStructureInfoKHR structure

Valid Usage (Implicit)
  • VUID-vkCmdCopyAccelerationStructureKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyAccelerationStructureKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkCopyAccelerationStructureInfoKHR structure

  • VUID-vkCmdCopyAccelerationStructureKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyAccelerationStructureKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdCopyAccelerationStructureKHR-renderpass
    This command must only be called outside of a render pass instance

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

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;
  • src is the source acceleration structure for the copy.

  • dst is the target acceleration structure for the copy.

  • mode is a VkCopyAccelerationStructureModeKHR value that specifies additional operations to perform during the copy.

Valid Usage
  • VUID-VkCopyAccelerationStructureInfoKHR-mode-03410
    mode must be VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR or VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR

  • VUID-VkCopyAccelerationStructureInfoKHR-src-03411
    src must have been built with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if mode is VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR

Valid Usage (Implicit)
  • VUID-VkCopyAccelerationStructureInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_INFO_KHR

  • VUID-VkCopyAccelerationStructureInfoKHR-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkDeferredOperationInfoKHR

  • VUID-VkCopyAccelerationStructureInfoKHR-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkCopyAccelerationStructureInfoKHR-src-parameter
    src must be a valid VkAccelerationStructureKHR handle

  • VUID-VkCopyAccelerationStructureInfoKHR-dst-parameter
    dst must be a valid VkAccelerationStructureKHR handle

  • VUID-VkCopyAccelerationStructureInfoKHR-mode-parameter
    mode must be a valid VkCopyAccelerationStructureModeKHR value

  • VUID-VkCopyAccelerationStructureInfoKHR-commonparent
    Both of dst, and src must have been created, allocated, or retrieved from the same VkDevice

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_KHR creates a direct copy of the acceleration structure specified in src into the one specified by dst. The dst acceleration structure must have been created with the same parameters as src.

  • VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR creates a more compact version of an acceleration structure src into dst. The acceleration structure dst must have been created with a compactedSize corresponding to the one returned by vkCmdWriteAccelerationStructuresPropertiesKHR after the build of the acceleration structure specified by src.

  • VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR serializes the acceleration structure to a semi-opaque format which can be reloaded on a compatible implementation.

  • VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR deserializes 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.

The defined header structure for the serialized data consists of:

  • VK_UUID_SIZE bytes of data matching VkPhysicalDeviceIDProperties::driverUUID

  • VK_UUID_SIZE bytes 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.

Valid Usage
  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-None-04048
    All VkDeviceOrHostAddressConstKHR referenced by this command must contain valid device addresses for a buffer bound to device memory. If the buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-None-03559
    All VkAccelerationStructureKHR objects referenced by this command must be bound to device memory

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pNext-03560
    The VkDeferredOperationInfoKHR structure must not be included in the pNext chain of the VkCopyAccelerationStructureToMemoryInfoKHR structure

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-mode-03412
    mode must be VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR

Valid Usage (Implicit)
  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkCopyAccelerationStructureToMemoryInfoKHR structure

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdCopyAccelerationStructureToMemoryKHR-renderpass
    This command must only be called outside of a render pass instance

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

// Provided by VK_KHR_ray_tracing
typedef struct VkCopyAccelerationStructureToMemoryInfoKHR {
    VkStructureType                       sType;
    const void*                           pNext;
    VkAccelerationStructureKHR            src;
    VkDeviceOrHostAddressKHR              dst;
    VkCopyAccelerationStructureModeKHR    mode;
} VkCopyAccelerationStructureToMemoryInfoKHR;
  • src is the source acceleration structure for the copy

  • dst is the device or host address to memory which is the target for the copy

  • mode is a VkCopyAccelerationStructureModeKHR value that specifies additional operations to perform during the copy.

Valid Usage
  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-dst-03561
    The memory pointed to by dst must be at least as large as the serialization size of src, as reported by VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR

  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-mode-03412
    mode must be VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR

Valid Usage (Implicit)
  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_TO_MEMORY_INFO_KHR

  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkDeferredOperationInfoKHR

  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-src-parameter
    src must be a valid VkAccelerationStructureKHR handle

  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-dst-parameter
    dst must be a valid VkDeviceOrHostAddressKHR union

  • VUID-VkCopyAccelerationStructureToMemoryInfoKHR-mode-parameter
    mode must be a valid VkCopyAccelerationStructureModeKHR value

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.

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.

Valid Usage
  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-None-04049
    All VkDeviceOrHostAddressKHR referenced by this command must contain valid device addresses for a buffer bound to device memory. If the buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-None-03563
    All VkAccelerationStructureKHR objects referenced by this command must be bound to device memory

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pNext-03564
    The VkDeferredOperationInfoKHR structure must not be included in the pNext chain of the VkCopyMemoryToAccelerationStructureInfoKHR structure

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-mode-03413
    mode must be VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03414
    The data in pInfo->src must have a format compatible with the destination physical device as returned by vkGetDeviceAccelerationStructureCompatibilityKHR

Valid Usage (Implicit)
  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkCopyMemoryToAccelerationStructureInfoKHR structure

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support compute operations

  • VUID-vkCmdCopyMemoryToAccelerationStructureKHR-renderpass
    This command must only be called outside of a render pass instance

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Compute

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;
  • src is the device or host address to memory containing the source data for the copy.

  • dst is the target acceleration structure for the copy.

  • mode is a VkCopyAccelerationStructureModeKHR value that specifies additional operations to perform during the copy.

Valid Usage
  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-mode-03413
    mode must be VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR

  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-pInfo-03414
    The data in pInfo->src must have a format compatible with the destination physical device as returned by vkGetDeviceAccelerationStructureCompatibilityKHR

Valid Usage (Implicit)
  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_MEMORY_TO_ACCELERATION_STRUCTURE_INFO_KHR

  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkDeferredOperationInfoKHR

  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-src-parameter
    src must be a valid VkDeviceOrHostAddressConstKHR union

  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-dst-parameter
    dst must be a valid VkAccelerationStructureKHR handle

  • VUID-VkCopyMemoryToAccelerationStructureInfoKHR-mode-parameter
    mode must be a valid VkCopyAccelerationStructureModeKHR value

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);

This possible return values for vkGetDeviceAccelerationStructureCompatibilityKHR are:

  • VK_SUCCESS is returned if an acceleration structure serialized with version as the version information is compatible with device.

  • VK_ERROR_INCOMPATIBLE_VERSION_KHR is returned if an acceleration structure serialized with version as the version information is not compatible with device.

Valid Usage
  • VUID-vkGetDeviceAccelerationStructureCompatibilityKHR-rayTracing-03565
    The rayTracing or rayQuery feature must be enabled

Valid Usage (Implicit)
  • VUID-vkGetDeviceAccelerationStructureCompatibilityKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDeviceAccelerationStructureCompatibilityKHR-version-parameter
    version must be a valid pointer to a valid VkAccelerationStructureVersionKHR structure

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_INCOMPATIBLE_VERSION_KHR

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;
Valid Usage
Valid Usage (Implicit)
  • VUID-VkAccelerationStructureVersionKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_VERSION_KHR

  • VUID-VkAccelerationStructureVersionKHR-pNext-pNext
    pNext must be NULL

  • VUID-VkAccelerationStructureVersionKHR-versionData-parameter
    versionData must be a valid pointer to an array of 2*VK_UUID_SIZE uint8_t values

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:

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.

  • device is the VkDevice for which the acceleration structures are being built.

  • infoCount is the number of acceleration structures to build. It specifies the number of the pInfos structures and ppOffsetInfos pointers that must be provided.

  • pInfos is a pointer to an array of infoCount VkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure.

  • ppOffsetInfos is an array of infoCount pointers to arrays of VkAccelerationStructureBuildOffsetInfoKHR structures. Each ppOffsetInfos[i] is an array of pInfos[i].geometryCount VkAccelerationStructureBuildOffsetInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined by pInfos[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.

Valid Usage
  • VUID-vkBuildAccelerationStructureKHR-pOffsetInfos-03402
    Each element of ppOffsetInfos[i] must be a valid pointer to an array of pInfos[i].geometryCount VkAccelerationStructureBuildOffsetInfoKHR structures

  • VUID-vkBuildAccelerationStructureKHR-pInfos-03403
    Each pInfos[i].srcAccelerationStructure must not refer to the same acceleration structure as any pInfos[i].dstAccelerationStructure that is provided to the same build command unless it is identical for an update

  • VUID-vkBuildAccelerationStructureKHR-pInfos-03404
    For each pInfos[i], dstAccelerationStructure must have been created with compatible VkAccelerationStructureCreateInfoKHR where VkAccelerationStructureCreateInfoKHR::type and VkAccelerationStructureCreateInfoKHR::flags are identical to VkAccelerationStructureBuildGeometryInfoKHR::type and VkAccelerationStructureBuildGeometryInfoKHR::flags respectively, VkAccelerationStructureBuildGeometryInfoKHR::geometryCount for dstAccelerationStructure are greater than or equal to the build size, and each geometry in VkAccelerationStructureBuildGeometryInfoKHR::ppGeometries for dstAccelerationStructure has greater than or equal to the number of vertices, indices, and AABBs, VkAccelerationStructureGeometryTrianglesDataKHR::transformData is both 0 or both non-zero, and all other parameters are the same

  • VUID-vkBuildAccelerationStructureKHR-pInfos-03405
    For each pInfos[i], if update is VK_TRUE, then objects that were previously active for that acceleration structure must not be made inactive as per Inactive Primitives and Instances

  • VUID-vkBuildAccelerationStructureKHR-pInfos-03406
    For each pInfos[i], if update is VK_TRUE, then objects that were previously inactive for that acceleration structure must not be made active as per Inactive Primitives and Instances

  • VUID-vkBuildAccelerationStructureKHR-None-03407
    Any acceleration structure instance in any top level build in this command must not reference any bottom level acceleration structure built by this command

  • VUID-vkBuildAccelerationStructureKHR-pInfos-03408
    There must not be any memory aliasing between the scratch memories that are provided in all the pInfos[i].scratchData memories for the acceleration structure builds

  • VUID-vkBuildAccelerationStructureKHR-None-03409
    There must not be any memory aliasing between memory bound to any top level, bottom level, or instance acceleration structure accessed by this command

Valid Usage (Implicit)
  • VUID-vkBuildAccelerationStructureKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkBuildAccelerationStructureKHR-pInfos-parameter
    pInfos must be a valid pointer to an array of infoCount valid VkAccelerationStructureBuildGeometryInfoKHR structures

  • VUID-vkBuildAccelerationStructureKHR-ppOffsetInfos-parameter
    ppOffsetInfos must be a valid pointer to an array of infoCount VkAccelerationStructureBuildOffsetInfoKHR structures

  • VUID-vkBuildAccelerationStructureKHR-infoCount-arraylength
    infoCount must be greater than 0

Return Codes
Success
  • VK_SUCCESS

  • VK_OPERATION_DEFERRED_KHR

  • VK_OPERATION_NOT_DEFERRED_KHR

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

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.

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.

Valid Usage
Valid Usage (Implicit)
  • VUID-vkCopyAccelerationStructureKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCopyAccelerationStructureKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkCopyAccelerationStructureInfoKHR structure

Return Codes
Success
  • VK_SUCCESS

  • VK_OPERATION_DEFERRED_KHR

  • VK_OPERATION_NOT_DEFERRED_KHR

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

// 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.

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.

Valid Usage
  • VUID-vkCopyMemoryToAccelerationStructureKHR-None-03442
    All VkAccelerationStructureKHR objects referenced by this command must be bound to host-visible memory

  • VUID-vkCopyMemoryToAccelerationStructureKHR-None-03443
    All VkDeviceOrHostAddressConstKHR referenced by this command must contain valid host pointers

  • VUID-vkCopyMemoryToAccelerationStructureKHR-rayTracingHostAccelerationStructureCommands-03444
    the VkPhysicalDeviceRayTracingFeaturesKHR::rayTracingHostAccelerationStructureCommands feature must be enabled

Valid Usage (Implicit)
  • VUID-vkCopyMemoryToAccelerationStructureKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCopyMemoryToAccelerationStructureKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkCopyMemoryToAccelerationStructureInfoKHR structure

Return Codes
Success
  • VK_SUCCESS

  • VK_OPERATION_DEFERRED_KHR

  • VK_OPERATION_NOT_DEFERRED_KHR

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

// 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.

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.

Valid Usage
  • VUID-vkCopyAccelerationStructureToMemoryKHR-None-03445
    All VkAccelerationStructureKHR objects referenced by this command must be bound to host-visible memory

  • VUID-vkCopyAccelerationStructureToMemoryKHR-None-03446
    All VkDeviceOrHostAddressKHR referenced by this command must contain valid host pointers

  • VUID-vkCopyAccelerationStructureToMemoryKHR-rayTracingHostAccelerationStructureCommands-03447
    the VkPhysicalDeviceRayTracingFeaturesKHR::rayTracingHostAccelerationStructureCommands feature must be enabled

Valid Usage (Implicit)
  • VUID-vkCopyAccelerationStructureToMemoryKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCopyAccelerationStructureToMemoryKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkCopyAccelerationStructureToMemoryInfoKHR structure

Return Codes
Success
  • VK_SUCCESS

  • VK_OPERATION_DEFERRED_KHR

  • VK_OPERATION_NOT_DEFERRED_KHR

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

// 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.

  • device is the device which owns the acceleration structures in pAccelerationStructures.

  • accelerationStructureCount is the count of acceleration structures for which to query the property.

  • pAccelerationStructures points to an array of existing previously built acceleration structures.

  • queryType is a VkQueryType value specifying the property to be queried.

  • dataSize is the size in bytes of the buffer pointed to by pData.

  • pData is a pointer to a user-allocated buffer where the results will be written.

  • stride is the stride in bytes between results for individual queries within pData.

Valid Usage
  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03448
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then stride must be a multiple of the size of VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03449
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then data must point to a VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03450
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then stride must be a multiple of the size of VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03451
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then data must point to a VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-dataSize-03452
    dataSize must be greater than or equal to accelerationStructureCount*stride

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-pAccelerationStructures-03453
    The acceleration structures referenced by pAccelerationStructures must be bound to host-visible memory

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-accelerationStructures-03431
    All acceleration structures in accelerationStructures must have been built with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03432
    queryType must be VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR or VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR

Valid Usage (Implicit)
  • VUID-vkWriteAccelerationStructuresPropertiesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-pAccelerationStructures-parameter
    pAccelerationStructures must be a valid pointer to an array of accelerationStructureCount valid VkAccelerationStructureKHR handles

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-parameter
    queryType must be a valid VkQueryType value

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-pData-parameter
    pData must be a valid pointer to an array of dataSize bytes

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-accelerationStructureCount-arraylength
    accelerationStructureCount must be greater than 0

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-dataSize-arraylength
    dataSize must be greater than 0

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-pAccelerationStructures-parent
    Each element of pAccelerationStructures must have been created, allocated, or retrieved from device

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY