Vulkan Logo

40. 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 30. Ray tracing pipeline execution
Caption

Interaction between the different shader stages in the ray tracing pipeline

Within the ray tracing pipeline, OpTraceRayKHR or OpTraceRayMotionNV 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.

40.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,

  • OpTraceRayMotionNV 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.

  • OpHitObjectTraceRayNV, OpHitObjectTraceRayMotionNV, and OpHitObjectExecuteShaderNV which may invoke intersection, any-hit, closest hit, miss, or callable shaders.

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.

Pipeline trace ray instructions can be used recursively; invoked shaders can themselves execute pipeline trace ray instructions, to a maximum depth defined by the maxRecursionDepth or maxRayRecursionDepth limit.

Shaders directly invoked from the API always have a recursion depth of 0; each shader executed by a pipeline trace ray 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 or maxPipelineRayRecursionDepth specified in the pipeline.

There is no explicit recursion limit for other shader call instructions which may recurse (e.g. OpExecuteCallableKHR) but there is an upper bound determined by the stack size.

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, OpTraceRayMotionNV, OpReorderThreadWithHintNV, OpReorderThreadWithHitObjectNV, 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 SubgroupSize, SubgroupLocalInvocationId, SMIDNV, WarpIDNV, and builtin variables that are derived from them (SubgroupEqMask, SubgroupGeMask, SubgroupGtMask, SubgroupLeMask, SubgroupLtMask) must be changed accordingly by the invocation repack instruction. The application must use Volatile semantics on these BuiltIn variables when used in the ray generation, closest hit, miss, intersection, and callable shaders. Similarly, the application must use Volatile semantics on any RayTmaxKHR decorated Builtin used in an intersection shader.

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.

While the SubgroupSize built-in is required to be declared Volatile, its value will never change unless VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT is set on pipeline creation, as without that bit set, its value is required to match that of VkPhysicalDeviceSubgroupProperties::subgroupSize.

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

40.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_NV_ray_tracing
void vkCmdTraceRaysNV(
    VkCommandBuffer                             commandBuffer,
    VkBuffer                                    raygenShaderBindingTableBuffer,
    VkDeviceSize                                raygenShaderBindingOffset,
    VkBuffer                                    missShaderBindingTableBuffer,
    VkDeviceSize                                missShaderBindingOffset,
    VkDeviceSize                                missShaderBindingStride,
    VkBuffer                                    hitShaderBindingTableBuffer,
    VkDeviceSize                                hitShaderBindingOffset,
    VkDeviceSize                                hitShaderBindingStride,
    VkBuffer                                    callableShaderBindingTableBuffer,
    VkDeviceSize                                callableShaderBindingOffset,
    VkDeviceSize                                callableShaderBindingStride,
    uint32_t                                    width,
    uint32_t                                    height,
    uint32_t                                    depth);
  • commandBuffer is the command buffer into which the command will be recorded.

  • raygenShaderBindingTableBuffer is the buffer object that holds the shader binding table data for the ray generation shader stage.

  • raygenShaderBindingOffset is the offset in bytes (relative to raygenShaderBindingTableBuffer) of the ray generation shader being used for the trace.

  • missShaderBindingTableBuffer is the buffer object that holds the shader binding table data for the miss shader stage.

  • missShaderBindingOffset is the offset in bytes (relative to missShaderBindingTableBuffer) of the miss shader being used for the trace.

  • missShaderBindingStride is the size in bytes of each shader binding table record in missShaderBindingTableBuffer.

  • hitShaderBindingTableBuffer is the buffer object that holds the shader binding table data for the hit shader stages.

  • hitShaderBindingOffset is the offset in bytes (relative to hitShaderBindingTableBuffer) of the hit shader group being used for the trace.

  • hitShaderBindingStride is the size in bytes of each shader binding table record in hitShaderBindingTableBuffer.

  • callableShaderBindingTableBuffer is the buffer object that holds the shader binding table data for the callable shader stage.

  • callableShaderBindingOffset is the offset in bytes (relative to callableShaderBindingTableBuffer) of the callable shader being used for the trace.

  • callableShaderBindingStride is the size in bytes of each shader binding table record in callableShaderBindingTableBuffer.

  • 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-vkCmdTraceRaysNV-magFilter-04553
    If a VkSampler created with magFilter or minFilter equal to VK_FILTER_LINEAR and compareEnable equal to VK_FALSE is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

  • VUID-vkCmdTraceRaysNV-mipmapMode-04770
    If a VkSampler created with mipmapMode equal to VK_SAMPLER_MIPMAP_MODE_LINEAR and compareEnable equal to VK_FALSE is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

  • VUID-vkCmdTraceRaysNV-None-06479
    If a VkImageView is sampled with depth comparison, the image view’s format features must contain VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT

  • VUID-vkCmdTraceRaysNV-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-vkCmdTraceRaysNV-None-07888
    If a VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER descriptor is accessed using atomic operations as a result of this command, then the storage texel buffer’s format features must contain VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT

  • VUID-vkCmdTraceRaysNV-None-02692
    If a VkImageView is sampled with VK_FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT

  • VUID-vkCmdTraceRaysNV-None-02693
    If the VK_EXT_filter_cubic extension is not enabled and any VkImageView is sampled with VK_FILTER_CUBIC_EXT as a result of this command, it must not have a VkImageViewType of VK_IMAGE_VIEW_TYPE_3D, VK_IMAGE_VIEW_TYPE_CUBE, or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY

  • VUID-vkCmdTraceRaysNV-filterCubic-02694
    Any VkImageView being sampled with VK_FILTER_CUBIC_EXT as a result of this command must have a VkImageViewType and format that supports cubic filtering, as specified by VkFilterCubicImageViewImageFormatPropertiesEXT::filterCubic returned by vkGetPhysicalDeviceImageFormatProperties2

  • VUID-vkCmdTraceRaysNV-filterCubicMinmax-02695
    Any VkImageView being sampled with VK_FILTER_CUBIC_EXT with a reduction mode of either VK_SAMPLER_REDUCTION_MODE_MIN or VK_SAMPLER_REDUCTION_MODE_MAX as a result of this command must have a VkImageViewType and format that supports cubic filtering together with minmax filtering, as specified by VkFilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax returned by vkGetPhysicalDeviceImageFormatProperties2

  • VUID-vkCmdTraceRaysNV-flags-02696
    Any VkImage created with a VkImageCreateInfo::flags containing VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must only be sampled using a VkSamplerAddressMode of VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE

  • VUID-vkCmdTraceRaysNV-OpTypeImage-07027
    For any VkImageView being written as a storage image where the image format field of the OpTypeImage is Unknown, the view’s format features must contain VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysNV-OpTypeImage-07028
    For any VkImageView being read as a storage image where the image format field of the OpTypeImage is Unknown, the view’s format features must contain VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysNV-OpTypeImage-07029
    For any VkBufferView being written as a storage texel buffer where the image format field of the OpTypeImage is Unknown, the view’s buffer features must contain VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysNV-OpTypeImage-07030
    Any VkBufferView being read as a storage texel buffer where the image format field of the OpTypeImage is Unknown then the view’s buffer features must contain VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysNV-None-02697
    For each set n that is statically used by a bound shader, 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-vkCmdTraceRaysNV-None-02698
    For each push constant that is statically used by a bound shader, 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-vkCmdTraceRaysNV-maintenance4-06425
    If the maintenance4 feature is not enabled, then for each push constant that is statically used by a bound shader, 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-vkCmdTraceRaysNV-None-08114
    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 and the bound VkPipeline was not created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysNV-None-08115
    If the descriptors used by the VkPipeline bound to the pipeline bind point were specified via vkCmdBindDescriptorSets, the bound VkPipeline must have been created without VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysNV-None-08116
    Descriptors in bound descriptor buffers, specified via vkCmdSetDescriptorBufferOffsetsEXT, must be valid if they are dynamically used by the VkPipeline bound to the pipeline bind point used by this command and the bound VkPipeline was created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysNV-None-08117
    If the descriptors used by the VkPipeline bound to the pipeline bind point were specified via vkCmdSetDescriptorBufferOffsetsEXT, the bound VkPipeline must have been created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysNV-None-08119
    If a descriptor is dynamically used with a VkPipeline created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT, the descriptor memory must be resident

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

  • VUID-vkCmdTraceRaysNV-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-vkCmdTraceRaysNV-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-vkCmdTraceRaysNV-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-vkCmdTraceRaysNV-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-vkCmdTraceRaysNV-uniformBuffers-06935
    If any stage of the VkPipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, and that stage was created without enabling either VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT or VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT for uniformBuffers, and the robustBufferAccess feature is not enabled, that stage 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-vkCmdTraceRaysNV-storageBuffers-06936
    If any stage of the VkPipeline object bound to the pipeline bind point used by this command accesses a storage buffer, and that stage was created without enabling either VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT or VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT for storageBuffers, and the robustBufferAccess feature is not enabled, that stage 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-vkCmdTraceRaysNV-commandBuffer-02707
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, any resource accessed by bound shaders must not be a protected resource

  • VUID-vkCmdTraceRaysNV-None-06550
    If a bound shader accesses a VkSampler or VkImageView object that enables sampler Y′CBCR conversion, that object must only be used with OpImageSample* or OpImageSparseSample* instructions

  • VUID-vkCmdTraceRaysNV-ConstOffset-06551
    If a bound shader accesses a VkSampler or VkImageView object that enables sampler Y′CBCR conversion, that object must not use the ConstOffset and Offset operands

  • VUID-vkCmdTraceRaysNV-viewType-07752
    If a VkImageView is accessed as a result of this command, then the image view’s viewType must match the Dim operand of the OpTypeImage as described in Instruction/Sampler/Image View Validation

  • VUID-vkCmdTraceRaysNV-format-07753
    If a VkImageView is accessed as a result of this command, then the numeric type of the image view’s format and the Sampled Type operand of the OpTypeImage must match

  • VUID-vkCmdTraceRaysNV-OpImageWrite-08795
    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-vkCmdTraceRaysNV-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 buffer view’s format

  • VUID-vkCmdTraceRaysNV-SampledType-04470
    If a VkImageView with a VkFormat that has a 64-bit component width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64

  • VUID-vkCmdTraceRaysNV-SampledType-04471
    If a VkImageView with a VkFormat that has a component width less than 64-bit is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32

  • VUID-vkCmdTraceRaysNV-SampledType-04472
    If a VkBufferView with a VkFormat that has a 64-bit component width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64

  • VUID-vkCmdTraceRaysNV-SampledType-04473
    If a VkBufferView with a VkFormat that has a component width less than 64-bit is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32

  • VUID-vkCmdTraceRaysNV-sparseImageInt64Atomics-04474
    If the sparseImageInt64Atomics feature is not enabled, VkImage objects created with the VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command

  • VUID-vkCmdTraceRaysNV-sparseImageInt64Atomics-04475
    If the sparseImageInt64Atomics feature is not enabled, VkBuffer objects created with the VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command

  • VUID-vkCmdTraceRaysNV-OpImageWeightedSampleQCOM-06971
    If OpImageWeightedSampleQCOM is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_WEIGHT_SAMPLED_IMAGE_BIT_QCOM

  • VUID-vkCmdTraceRaysNV-OpImageWeightedSampleQCOM-06972
    If OpImageWeightedSampleQCOM uses a VkImageView as a sample weight image as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_WEIGHT_IMAGE_BIT_QCOM

  • VUID-vkCmdTraceRaysNV-OpImageBoxFilterQCOM-06973
    If OpImageBoxFilterQCOM is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_BOX_FILTER_SAMPLED_BIT_QCOM

  • VUID-vkCmdTraceRaysNV-OpImageBlockMatchSSDQCOM-06974
    If OpImageBlockMatchSSDQCOM is used to read from an VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOM

  • VUID-vkCmdTraceRaysNV-OpImageBlockMatchSADQCOM-06975
    If OpImageBlockMatchSADQCOM is used to read from an VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOM

  • VUID-vkCmdTraceRaysNV-OpImageBlockMatchSADQCOM-06976
    If OpImageBlockMatchSADQCOM or OpImageBlockMatchSSDQCOM is used to read from a reference image as result of this command, then the specified reference coordinates must not fail integer texel coordinate validation

  • VUID-vkCmdTraceRaysNV-OpImageWeightedSampleQCOM-06977
    If OpImageWeightedSampleQCOM, OpImageBoxFilterQCOM, OpImageBlockMatchSSDQCOM, or OpImageBlockMatchSADQCOM uses a VkSampler as a result of this command, then the sampler must have been created with VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM

  • VUID-vkCmdTraceRaysNV-OpImageWeightedSampleQCOM-06978
    If any command other than OpImageWeightedSampleQCOM, OpImageBoxFilterQCOM, OpImageBlockMatchSSDQCOM, or OpImageBlockMatchSADQCOM uses a VkSampler as a result of this command, then the sampler must not have been created with VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM

  • VUID-vkCmdTraceRaysNV-None-07288
    Any shader invocation executed by this command must terminate

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

  • VUID-vkCmdTraceRaysNV-commandBuffer-04624
    commandBuffer must not be a protected command buffer

  • VUID-vkCmdTraceRaysNV-maxRecursionDepth-03625
    This command must not cause a pipeline trace ray 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-vkCmdTraceRaysNV-raygenShaderBindingTableBuffer-04042
    If raygenShaderBindingTableBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysNV-raygenShaderBindingOffset-02455
    raygenShaderBindingOffset must be less than the size of raygenShaderBindingTableBuffer

  • VUID-vkCmdTraceRaysNV-raygenShaderBindingOffset-02456
    raygenShaderBindingOffset must be a multiple of VkPhysicalDeviceRayTracingPropertiesNV::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysNV-missShaderBindingTableBuffer-04043
    If missShaderBindingTableBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysNV-missShaderBindingOffset-02457
    missShaderBindingOffset must be less than the size of missShaderBindingTableBuffer

  • VUID-vkCmdTraceRaysNV-missShaderBindingOffset-02458
    missShaderBindingOffset must be a multiple of VkPhysicalDeviceRayTracingPropertiesNV::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysNV-hitShaderBindingTableBuffer-04044
    If hitShaderBindingTableBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysNV-hitShaderBindingOffset-02459
    hitShaderBindingOffset must be less than the size of hitShaderBindingTableBuffer

  • VUID-vkCmdTraceRaysNV-hitShaderBindingOffset-02460
    hitShaderBindingOffset must be a multiple of VkPhysicalDeviceRayTracingPropertiesNV::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysNV-callableShaderBindingTableBuffer-04045
    If callableShaderBindingTableBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysNV-callableShaderBindingOffset-02461
    callableShaderBindingOffset must be less than the size of callableShaderBindingTableBuffer

  • VUID-vkCmdTraceRaysNV-callableShaderBindingOffset-02462
    callableShaderBindingOffset must be a multiple of VkPhysicalDeviceRayTracingPropertiesNV::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysNV-missShaderBindingStride-02463
    missShaderBindingStride must be a multiple of VkPhysicalDeviceRayTracingPropertiesNV::shaderGroupHandleSize

  • VUID-vkCmdTraceRaysNV-hitShaderBindingStride-02464
    hitShaderBindingStride must be a multiple of VkPhysicalDeviceRayTracingPropertiesNV::shaderGroupHandleSize

  • VUID-vkCmdTraceRaysNV-callableShaderBindingStride-02465
    callableShaderBindingStride must be a multiple of VkPhysicalDeviceRayTracingPropertiesNV::shaderGroupHandleSize

  • VUID-vkCmdTraceRaysNV-missShaderBindingStride-02466
    missShaderBindingStride must be less than or equal to VkPhysicalDeviceRayTracingPropertiesNV::maxShaderGroupStride

  • VUID-vkCmdTraceRaysNV-hitShaderBindingStride-02467
    hitShaderBindingStride must be less than or equal to VkPhysicalDeviceRayTracingPropertiesNV::maxShaderGroupStride

  • VUID-vkCmdTraceRaysNV-callableShaderBindingStride-02468
    callableShaderBindingStride must be less than or equal to VkPhysicalDeviceRayTracingPropertiesNV::maxShaderGroupStride

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

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

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

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

  • VUID-vkCmdTraceRaysNV-raygenShaderBindingTableBuffer-parameter
    raygenShaderBindingTableBuffer must be a valid VkBuffer handle

  • VUID-vkCmdTraceRaysNV-missShaderBindingTableBuffer-parameter
    If missShaderBindingTableBuffer is not VK_NULL_HANDLE, missShaderBindingTableBuffer must be a valid VkBuffer handle

  • VUID-vkCmdTraceRaysNV-hitShaderBindingTableBuffer-parameter
    If hitShaderBindingTableBuffer is not VK_NULL_HANDLE, hitShaderBindingTableBuffer must be a valid VkBuffer handle

  • VUID-vkCmdTraceRaysNV-callableShaderBindingTableBuffer-parameter
    If callableShaderBindingTableBuffer is not VK_NULL_HANDLE, callableShaderBindingTableBuffer must be a valid VkBuffer handle

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

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

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

  • VUID-vkCmdTraceRaysNV-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdTraceRaysNV-commonparent
    Each of callableShaderBindingTableBuffer, commandBuffer, hitShaderBindingTableBuffer, missShaderBindingTableBuffer, and raygenShaderBindingTableBuffer that are valid handles of non-ignored parameters 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 Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Compute

Action

To dispatch ray tracing use:

// Provided by VK_KHR_ray_tracing_pipeline
void vkCmdTraceRaysKHR(
    VkCommandBuffer                             commandBuffer,
    const VkStridedDeviceAddressRegionKHR*      pRaygenShaderBindingTable,
    const VkStridedDeviceAddressRegionKHR*      pMissShaderBindingTable,
    const VkStridedDeviceAddressRegionKHR*      pHitShaderBindingTable,
    const VkStridedDeviceAddressRegionKHR*      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 VkStridedDeviceAddressRegionKHR that holds the shader binding table data for the ray generation shader stage.

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

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

  • pCallableShaderBindingTable is a VkStridedDeviceAddressRegionKHR 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-magFilter-04553
    If a VkSampler created with magFilter or minFilter equal to VK_FILTER_LINEAR and compareEnable equal to VK_FALSE is used to sample a VkImageView 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-mipmapMode-04770
    If a VkSampler created with mipmapMode equal to VK_SAMPLER_MIPMAP_MODE_LINEAR and compareEnable equal to VK_FALSE is used to sample a VkImageView 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-06479
    If a VkImageView is sampled with depth comparison, the image view’s format features must contain VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_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-07888
    If a VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER descriptor is accessed using atomic operations as a result of this command, then the storage texel buffer’s format features must contain VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT

  • VUID-vkCmdTraceRaysKHR-None-02692
    If a VkImageView is sampled with VK_FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT

  • VUID-vkCmdTraceRaysKHR-None-02693
    If the VK_EXT_filter_cubic extension is not enabled and any VkImageView is sampled with VK_FILTER_CUBIC_EXT as a result of this command, it must not have a VkImageViewType of VK_IMAGE_VIEW_TYPE_3D, VK_IMAGE_VIEW_TYPE_CUBE, or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY

  • VUID-vkCmdTraceRaysKHR-filterCubic-02694
    Any VkImageView being sampled with VK_FILTER_CUBIC_EXT as a result of this command must have a VkImageViewType and format that supports cubic filtering, as specified by VkFilterCubicImageViewImageFormatPropertiesEXT::filterCubic returned by vkGetPhysicalDeviceImageFormatProperties2

  • VUID-vkCmdTraceRaysKHR-filterCubicMinmax-02695
    Any VkImageView being sampled with VK_FILTER_CUBIC_EXT with a reduction mode of either VK_SAMPLER_REDUCTION_MODE_MIN or VK_SAMPLER_REDUCTION_MODE_MAX as a result of this command must have a VkImageViewType and format that supports cubic filtering together with minmax filtering, as specified by VkFilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax returned by vkGetPhysicalDeviceImageFormatProperties2

  • VUID-vkCmdTraceRaysKHR-flags-02696
    Any VkImage created with a VkImageCreateInfo::flags containing VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must only be sampled using a VkSamplerAddressMode of VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE

  • VUID-vkCmdTraceRaysKHR-OpTypeImage-07027
    For any VkImageView being written as a storage image where the image format field of the OpTypeImage is Unknown, the view’s format features must contain VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysKHR-OpTypeImage-07028
    For any VkImageView being read as a storage image where the image format field of the OpTypeImage is Unknown, the view’s format features must contain VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysKHR-OpTypeImage-07029
    For any VkBufferView being written as a storage texel buffer where the image format field of the OpTypeImage is Unknown, the view’s buffer features must contain VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysKHR-OpTypeImage-07030
    Any VkBufferView being read as a storage texel buffer where the image format field of the OpTypeImage is Unknown then the view’s buffer features must contain VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysKHR-None-02697
    For each set n that is statically used by a bound shader, 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 a bound shader, 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-maintenance4-06425
    If the maintenance4 feature is not enabled, then for each push constant that is statically used by a bound shader, 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-08114
    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 and the bound VkPipeline was not created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysKHR-None-08115
    If the descriptors used by the VkPipeline bound to the pipeline bind point were specified via vkCmdBindDescriptorSets, the bound VkPipeline must have been created without VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysKHR-None-08116
    Descriptors in bound descriptor buffers, specified via vkCmdSetDescriptorBufferOffsetsEXT, must be valid if they are dynamically used by the VkPipeline bound to the pipeline bind point used by this command and the bound VkPipeline was created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysKHR-None-08117
    If the descriptors used by the VkPipeline bound to the pipeline bind point were specified via vkCmdSetDescriptorBufferOffsetsEXT, the bound VkPipeline must have been created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysKHR-None-08119
    If a descriptor is dynamically used with a VkPipeline created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT, the descriptor memory must be resident

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

  • 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-uniformBuffers-06935
    If any stage of the VkPipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, and that stage was created without enabling either VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT or VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT for uniformBuffers, and the robustBufferAccess feature is not enabled, that stage 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-storageBuffers-06936
    If any stage of the VkPipeline object bound to the pipeline bind point used by this command accesses a storage buffer, and that stage was created without enabling either VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT or VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT for storageBuffers, and the robustBufferAccess feature is not enabled, that stage 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 and protectedNoFault is not supported, any resource accessed by bound shaders must not be a protected resource

  • VUID-vkCmdTraceRaysKHR-None-06550
    If a bound shader accesses a VkSampler or VkImageView object that enables sampler Y′CBCR conversion, that object must only be used with OpImageSample* or OpImageSparseSample* instructions

  • VUID-vkCmdTraceRaysKHR-ConstOffset-06551
    If a bound shader accesses a VkSampler or VkImageView object that enables sampler Y′CBCR conversion, that object must not use the ConstOffset and Offset operands

  • VUID-vkCmdTraceRaysKHR-viewType-07752
    If a VkImageView is accessed as a result of this command, then the image view’s viewType must match the Dim operand of the OpTypeImage as described in Instruction/Sampler/Image View Validation

  • VUID-vkCmdTraceRaysKHR-format-07753
    If a VkImageView is accessed as a result of this command, then the numeric type of the image view’s format and the Sampled Type operand of the OpTypeImage must match

  • VUID-vkCmdTraceRaysKHR-OpImageWrite-08795
    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 buffer view’s format

  • VUID-vkCmdTraceRaysKHR-SampledType-04470
    If a VkImageView with a VkFormat that has a 64-bit component width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64

  • VUID-vkCmdTraceRaysKHR-SampledType-04471
    If a VkImageView with a VkFormat that has a component width less than 64-bit is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32

  • VUID-vkCmdTraceRaysKHR-SampledType-04472
    If a VkBufferView with a VkFormat that has a 64-bit component width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64

  • VUID-vkCmdTraceRaysKHR-SampledType-04473
    If a VkBufferView with a VkFormat that has a component width less than 64-bit is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32

  • VUID-vkCmdTraceRaysKHR-sparseImageInt64Atomics-04474
    If the sparseImageInt64Atomics feature is not enabled, VkImage objects created with the VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command

  • VUID-vkCmdTraceRaysKHR-sparseImageInt64Atomics-04475
    If the sparseImageInt64Atomics feature is not enabled, VkBuffer objects created with the VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command

  • VUID-vkCmdTraceRaysKHR-OpImageWeightedSampleQCOM-06971
    If OpImageWeightedSampleQCOM is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_WEIGHT_SAMPLED_IMAGE_BIT_QCOM

  • VUID-vkCmdTraceRaysKHR-OpImageWeightedSampleQCOM-06972
    If OpImageWeightedSampleQCOM uses a VkImageView as a sample weight image as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_WEIGHT_IMAGE_BIT_QCOM

  • VUID-vkCmdTraceRaysKHR-OpImageBoxFilterQCOM-06973
    If OpImageBoxFilterQCOM is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_BOX_FILTER_SAMPLED_BIT_QCOM

  • VUID-vkCmdTraceRaysKHR-OpImageBlockMatchSSDQCOM-06974
    If OpImageBlockMatchSSDQCOM is used to read from an VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOM

  • VUID-vkCmdTraceRaysKHR-OpImageBlockMatchSADQCOM-06975
    If OpImageBlockMatchSADQCOM is used to read from an VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOM

  • VUID-vkCmdTraceRaysKHR-OpImageBlockMatchSADQCOM-06976
    If OpImageBlockMatchSADQCOM or OpImageBlockMatchSSDQCOM is used to read from a reference image as result of this command, then the specified reference coordinates must not fail integer texel coordinate validation

  • VUID-vkCmdTraceRaysKHR-OpImageWeightedSampleQCOM-06977
    If OpImageWeightedSampleQCOM, OpImageBoxFilterQCOM, OpImageBlockMatchSSDQCOM, or OpImageBlockMatchSADQCOM uses a VkSampler as a result of this command, then the sampler must have been created with VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM

  • VUID-vkCmdTraceRaysKHR-OpImageWeightedSampleQCOM-06978
    If any command other than OpImageWeightedSampleQCOM, OpImageBoxFilterQCOM, OpImageBlockMatchSSDQCOM, or OpImageBlockMatchSADQCOM uses a VkSampler as a result of this command, then the sampler must not have been created with VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM

  • VUID-vkCmdTraceRaysKHR-None-07288
    Any shader invocation executed by this command must terminate

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

  • VUID-vkCmdTraceRaysKHR-maxPipelineRayRecursionDepth-03679
    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 maxPipelineRayRecursionDepth used to create the bound ray tracing pipeline

  • VUID-vkCmdTraceRaysKHR-commandBuffer-03635
    commandBuffer must not be a protected command buffer

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

  • VUID-vkCmdTraceRaysKHR-pRayGenShaderBindingTable-03680
    If the buffer from which pRayGenShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysKHR-pRayGenShaderBindingTable-03681
    The buffer from which the pRayGenShaderBindingTable->deviceAddress is queried must have been created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag

  • VUID-vkCmdTraceRaysKHR-pRayGenShaderBindingTable-03682
    pRayGenShaderBindingTable->deviceAddress must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysKHR-pMissShaderBindingTable-03683
    If the buffer from which pMissShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysKHR-pMissShaderBindingTable-03684
    The buffer from which the pMissShaderBindingTable->deviceAddress is queried must have been created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag

  • VUID-vkCmdTraceRaysKHR-pMissShaderBindingTable-03685
    pMissShaderBindingTable->deviceAddress must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysKHR-stride-03686
    pMissShaderBindingTable->stride must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment

  • VUID-vkCmdTraceRaysKHR-stride-04029
    pMissShaderBindingTable->stride must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride

  • VUID-vkCmdTraceRaysKHR-pHitShaderBindingTable-03687
    If the buffer from which pHitShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysKHR-pHitShaderBindingTable-03688
    The buffer from which the pHitShaderBindingTable->deviceAddress is queried must have been created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag

  • VUID-vkCmdTraceRaysKHR-pHitShaderBindingTable-03689
    pHitShaderBindingTable->deviceAddress must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysKHR-stride-03690
    pHitShaderBindingTable->stride must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment

  • VUID-vkCmdTraceRaysKHR-stride-04035
    pHitShaderBindingTable->stride must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride

  • VUID-vkCmdTraceRaysKHR-pCallableShaderBindingTable-03691
    If the buffer from which pCallableShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysKHR-pCallableShaderBindingTable-03692
    The buffer from which the pCallableShaderBindingTable->deviceAddress is queried must have been created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag

  • VUID-vkCmdTraceRaysKHR-pCallableShaderBindingTable-03693
    pCallableShaderBindingTable->deviceAddress must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysKHR-stride-03694
    pCallableShaderBindingTable->stride must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment

  • VUID-vkCmdTraceRaysKHR-stride-04041
    pCallableShaderBindingTable->stride must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride

  • VUID-vkCmdTraceRaysKHR-flags-03696
    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, pHitShaderBindingTable->deviceAddress must not be zero

  • VUID-vkCmdTraceRaysKHR-flags-03697
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, pHitShaderBindingTable->deviceAddress must not be zero

  • 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->deviceAddress must not be set to zero

  • 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 the table identified by pHitShaderBindingTable->deviceAddress 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 the table identified by pHitShaderBindingTable->deviceAddress 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 the table identified by pHitShaderBindingTable->deviceAddress accessed as a result of this command in order to execute an intersection shader must not be set to zero

  • VUID-vkCmdTraceRaysKHR-pHitShaderBindingTable-04735
    Any non-zero hit shader group entries in the table identified by pHitShaderBindingTable->deviceAddress accessed by this call from a geometry with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR must have been created with VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR

  • VUID-vkCmdTraceRaysKHR-pHitShaderBindingTable-04736
    Any non-zero hit shader group entries in the table identified by pHitShaderBindingTable->deviceAddress accessed by this call from a geometry with a geometryType of VK_GEOMETRY_TYPE_AABBS_KHR must have been created with VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR

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

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

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

  • VUID-vkCmdTraceRaysKHR-width-03641
    width × height × depth must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxRayDispatchInvocationCount

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 VkStridedDeviceAddressRegionKHR structure

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

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

  • VUID-vkCmdTraceRaysKHR-pCallableShaderBindingTable-parameter
    pCallableShaderBindingTable must be a valid pointer to a valid VkStridedDeviceAddressRegionKHR 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

  • VUID-vkCmdTraceRaysKHR-videocoding
    This command must only be called outside of a video coding scope

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 Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Compute

Action

The VkStridedDeviceAddressRegionKHR structure is defined as:

// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkStridedDeviceAddressRegionKHR {
    VkDeviceAddress    deviceAddress;
    VkDeviceSize       stride;
    VkDeviceSize       size;
} VkStridedDeviceAddressRegionKHR;
  • deviceAddress is the device address (as returned by the vkGetBufferDeviceAddress command) at which the region starts, or zero if the region is unused.

  • stride is the byte stride between consecutive elements.

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

Valid Usage
  • VUID-VkStridedDeviceAddressRegionKHR-size-04631
    If size is not zero, all addresses between deviceAddress and deviceAddress + size - 1 must be in the buffer device address range of the same buffer

  • VUID-VkStridedDeviceAddressRegionKHR-size-04632
    If size is not zero, stride must be less than or equal to the size of the buffer from which deviceAddress was queried

When invocation mask image usage is enabled in the bound ray tracing pipeline, the pipeline uses an invocation mask image specified by the command:

// Provided by VK_HUAWEI_invocation_mask
void vkCmdBindInvocationMaskHUAWEI(
    VkCommandBuffer                             commandBuffer,
    VkImageView                                 imageView,
    VkImageLayout                               imageLayout);
  • commandBuffer is the command buffer into which the command will be recorded

  • imageView is an image view handle specifying the invocation mask image imageView may be set to VK_NULL_HANDLE, which is equivalent to specifying a view of an image filled with ones value.

  • imageLayout is the layout that the image subresources accessible from imageView will be in when the invocation mask image is accessed

Valid Usage
  • VUID-vkCmdBindInvocationMaskHUAWEI-None-04976
    The invocationMask feature must be enabled

  • VUID-vkCmdBindInvocationMaskHUAWEI-imageView-04977
    If imageView is not VK_NULL_HANDLE, it must be a valid VkImageView handle of type VK_IMAGE_VIEW_TYPE_2D

  • VUID-vkCmdBindInvocationMaskHUAWEI-imageView-04978
    If imageView is not VK_NULL_HANDLE, it must have a format of VK_FORMAT_R8_UINT

  • VUID-vkCmdBindInvocationMaskHUAWEI-imageView-04979
    If imageView is not VK_NULL_HANDLE, it must have been created with VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI set

  • VUID-vkCmdBindInvocationMaskHUAWEI-imageView-04980
    If imageView is not VK_NULL_HANDLE, imageLayout must be VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdBindInvocationMaskHUAWEI-width-04981
    Thread mask image resolution must match the width and height in vkCmdTraceRaysKHR

  • VUID-vkCmdBindInvocationMaskHUAWEI-None-04982
    Each element in the invocation mask image must have the value 0 or 1. The value 1 means the invocation is active

  • VUID-vkCmdBindInvocationMaskHUAWEI-depth-04983
    depth in vkCmdTraceRaysKHR must be 1

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

  • VUID-vkCmdBindInvocationMaskHUAWEI-imageView-parameter
    If imageView is not VK_NULL_HANDLE, imageView must be a valid VkImageView handle

  • VUID-vkCmdBindInvocationMaskHUAWEI-imageLayout-parameter
    imageLayout must be a valid VkImageLayout value

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

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

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

  • VUID-vkCmdBindInvocationMaskHUAWEI-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdBindInvocationMaskHUAWEI-commonparent
    Both of commandBuffer, and imageView that are valid handles of non-ignored parameters 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 Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Compute

State

To dispatch ray tracing, with some parameters sourced on the device, use:

// Provided by VK_KHR_ray_tracing_pipeline
void vkCmdTraceRaysIndirectKHR(
    VkCommandBuffer                             commandBuffer,
    const VkStridedDeviceAddressRegionKHR*      pRaygenShaderBindingTable,
    const VkStridedDeviceAddressRegionKHR*      pMissShaderBindingTable,
    const VkStridedDeviceAddressRegionKHR*      pHitShaderBindingTable,
    const VkStridedDeviceAddressRegionKHR*      pCallableShaderBindingTable,
    VkDeviceAddress                             indirectDeviceAddress);

vkCmdTraceRaysIndirectKHR behaves similarly to vkCmdTraceRaysKHR except that the ray trace query dimensions are read by the device from indirectDeviceAddress during execution.

Valid Usage
  • VUID-vkCmdTraceRaysIndirectKHR-magFilter-04553
    If a VkSampler created with magFilter or minFilter equal to VK_FILTER_LINEAR and compareEnable equal to VK_FALSE is used to sample a VkImageView 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-mipmapMode-04770
    If a VkSampler created with mipmapMode equal to VK_SAMPLER_MIPMAP_MODE_LINEAR and compareEnable equal to VK_FALSE is used to sample a VkImageView 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-06479
    If a VkImageView is sampled with depth comparison, the image view’s format features must contain VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_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-07888
    If a VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER descriptor is accessed using atomic operations as a result of this command, then the storage texel buffer’s format features must contain VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT

  • VUID-vkCmdTraceRaysIndirectKHR-None-02692
    If a VkImageView is sampled with VK_FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT

  • VUID-vkCmdTraceRaysIndirectKHR-None-02693
    If the VK_EXT_filter_cubic extension is not enabled and any VkImageView is sampled with VK_FILTER_CUBIC_EXT as a result of this command, it must not have a VkImageViewType of VK_IMAGE_VIEW_TYPE_3D, VK_IMAGE_VIEW_TYPE_CUBE, or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY

  • VUID-vkCmdTraceRaysIndirectKHR-filterCubic-02694
    Any VkImageView being sampled with VK_FILTER_CUBIC_EXT as a result of this command must have a VkImageViewType and format that supports cubic filtering, as specified by VkFilterCubicImageViewImageFormatPropertiesEXT::filterCubic returned by vkGetPhysicalDeviceImageFormatProperties2

  • VUID-vkCmdTraceRaysIndirectKHR-filterCubicMinmax-02695
    Any VkImageView being sampled with VK_FILTER_CUBIC_EXT with a reduction mode of either VK_SAMPLER_REDUCTION_MODE_MIN or VK_SAMPLER_REDUCTION_MODE_MAX as a result of this command must have a VkImageViewType and format that supports cubic filtering together with minmax filtering, as specified by VkFilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax returned by vkGetPhysicalDeviceImageFormatProperties2

  • VUID-vkCmdTraceRaysIndirectKHR-flags-02696
    Any VkImage created with a VkImageCreateInfo::flags containing VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must only be sampled using a VkSamplerAddressMode of VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE

  • VUID-vkCmdTraceRaysIndirectKHR-OpTypeImage-07027
    For any VkImageView being written as a storage image where the image format field of the OpTypeImage is Unknown, the view’s format features must contain VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysIndirectKHR-OpTypeImage-07028
    For any VkImageView being read as a storage image where the image format field of the OpTypeImage is Unknown, the view’s format features must contain VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysIndirectKHR-OpTypeImage-07029
    For any VkBufferView being written as a storage texel buffer where the image format field of the OpTypeImage is Unknown, the view’s buffer features must contain VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysIndirectKHR-OpTypeImage-07030
    Any VkBufferView being read as a storage texel buffer where the image format field of the OpTypeImage is Unknown then the view’s buffer features must contain VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysIndirectKHR-None-02697
    For each set n that is statically used by a bound shader, 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 a bound shader, 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-maintenance4-06425
    If the maintenance4 feature is not enabled, then for each push constant that is statically used by a bound shader, 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-08114
    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 and the bound VkPipeline was not created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysIndirectKHR-None-08115
    If the descriptors used by the VkPipeline bound to the pipeline bind point were specified via vkCmdBindDescriptorSets, the bound VkPipeline must have been created without VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysIndirectKHR-None-08116
    Descriptors in bound descriptor buffers, specified via vkCmdSetDescriptorBufferOffsetsEXT, must be valid if they are dynamically used by the VkPipeline bound to the pipeline bind point used by this command and the bound VkPipeline was created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysIndirectKHR-None-08117
    If the descriptors used by the VkPipeline bound to the pipeline bind point were specified via vkCmdSetDescriptorBufferOffsetsEXT, the bound VkPipeline must have been created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysIndirectKHR-None-08119
    If a descriptor is dynamically used with a VkPipeline created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT, the descriptor memory must be resident

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

  • 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-uniformBuffers-06935
    If any stage of the VkPipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, and that stage was created without enabling either VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT or VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT for uniformBuffers, and the robustBufferAccess feature is not enabled, that stage 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-storageBuffers-06936
    If any stage of the VkPipeline object bound to the pipeline bind point used by this command accesses a storage buffer, and that stage was created without enabling either VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT or VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT for storageBuffers, and the robustBufferAccess feature is not enabled, that stage 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 and protectedNoFault is not supported, any resource accessed by bound shaders must not be a protected resource

  • VUID-vkCmdTraceRaysIndirectKHR-None-06550
    If a bound shader accesses a VkSampler or VkImageView object that enables sampler Y′CBCR conversion, that object must only be used with OpImageSample* or OpImageSparseSample* instructions

  • VUID-vkCmdTraceRaysIndirectKHR-ConstOffset-06551
    If a bound shader accesses a VkSampler or VkImageView object that enables sampler Y′CBCR conversion, that object must not use the ConstOffset and Offset operands

  • VUID-vkCmdTraceRaysIndirectKHR-viewType-07752
    If a VkImageView is accessed as a result of this command, then the image view’s viewType must match the Dim operand of the OpTypeImage as described in Instruction/Sampler/Image View Validation

  • VUID-vkCmdTraceRaysIndirectKHR-format-07753
    If a VkImageView is accessed as a result of this command, then the numeric type of the image view’s format and the Sampled Type operand of the OpTypeImage must match

  • VUID-vkCmdTraceRaysIndirectKHR-OpImageWrite-08795
    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 buffer view’s format

  • VUID-vkCmdTraceRaysIndirectKHR-SampledType-04470
    If a VkImageView with a VkFormat that has a 64-bit component width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64

  • VUID-vkCmdTraceRaysIndirectKHR-SampledType-04471
    If a VkImageView with a VkFormat that has a component width less than 64-bit is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32

  • VUID-vkCmdTraceRaysIndirectKHR-SampledType-04472
    If a VkBufferView with a VkFormat that has a 64-bit component width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64

  • VUID-vkCmdTraceRaysIndirectKHR-SampledType-04473
    If a VkBufferView with a VkFormat that has a component width less than 64-bit is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32

  • VUID-vkCmdTraceRaysIndirectKHR-sparseImageInt64Atomics-04474
    If the sparseImageInt64Atomics feature is not enabled, VkImage objects created with the VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command

  • VUID-vkCmdTraceRaysIndirectKHR-sparseImageInt64Atomics-04475
    If the sparseImageInt64Atomics feature is not enabled, VkBuffer objects created with the VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command

  • VUID-vkCmdTraceRaysIndirectKHR-OpImageWeightedSampleQCOM-06971
    If OpImageWeightedSampleQCOM is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_WEIGHT_SAMPLED_IMAGE_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirectKHR-OpImageWeightedSampleQCOM-06972
    If OpImageWeightedSampleQCOM uses a VkImageView as a sample weight image as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_WEIGHT_IMAGE_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirectKHR-OpImageBoxFilterQCOM-06973
    If OpImageBoxFilterQCOM is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_BOX_FILTER_SAMPLED_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirectKHR-OpImageBlockMatchSSDQCOM-06974
    If OpImageBlockMatchSSDQCOM is used to read from an VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirectKHR-OpImageBlockMatchSADQCOM-06975
    If OpImageBlockMatchSADQCOM is used to read from an VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirectKHR-OpImageBlockMatchSADQCOM-06976
    If OpImageBlockMatchSADQCOM or OpImageBlockMatchSSDQCOM is used to read from a reference image as result of this command, then the specified reference coordinates must not fail integer texel coordinate validation

  • VUID-vkCmdTraceRaysIndirectKHR-OpImageWeightedSampleQCOM-06977
    If OpImageWeightedSampleQCOM, OpImageBoxFilterQCOM, OpImageBlockMatchSSDQCOM, or OpImageBlockMatchSADQCOM uses a VkSampler as a result of this command, then the sampler must have been created with VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirectKHR-OpImageWeightedSampleQCOM-06978
    If any command other than OpImageWeightedSampleQCOM, OpImageBoxFilterQCOM, OpImageBlockMatchSSDQCOM, or OpImageBlockMatchSADQCOM uses a VkSampler as a result of this command, then the sampler must not have been created with VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirectKHR-None-07288
    Any shader invocation executed by this command must terminate

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

  • VUID-vkCmdTraceRaysIndirectKHR-maxPipelineRayRecursionDepth-03679
    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 maxPipelineRayRecursionDepth used to create the bound ray tracing pipeline

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

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

  • VUID-vkCmdTraceRaysIndirectKHR-pRayGenShaderBindingTable-03680
    If the buffer from which pRayGenShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysIndirectKHR-pRayGenShaderBindingTable-03681
    The buffer from which the pRayGenShaderBindingTable->deviceAddress is queried must have been created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag

  • VUID-vkCmdTraceRaysIndirectKHR-pRayGenShaderBindingTable-03682
    pRayGenShaderBindingTable->deviceAddress must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysIndirectKHR-pMissShaderBindingTable-03683
    If the buffer from which pMissShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysIndirectKHR-pMissShaderBindingTable-03684
    The buffer from which the pMissShaderBindingTable->deviceAddress is queried must have been created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag

  • VUID-vkCmdTraceRaysIndirectKHR-pMissShaderBindingTable-03685
    pMissShaderBindingTable->deviceAddress must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysIndirectKHR-stride-03686
    pMissShaderBindingTable->stride must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment

  • VUID-vkCmdTraceRaysIndirectKHR-stride-04029
    pMissShaderBindingTable->stride must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride

  • VUID-vkCmdTraceRaysIndirectKHR-pHitShaderBindingTable-03687
    If the buffer from which pHitShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysIndirectKHR-pHitShaderBindingTable-03688
    The buffer from which the pHitShaderBindingTable->deviceAddress is queried must have been created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag

  • VUID-vkCmdTraceRaysIndirectKHR-pHitShaderBindingTable-03689
    pHitShaderBindingTable->deviceAddress must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysIndirectKHR-stride-03690
    pHitShaderBindingTable->stride must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment

  • VUID-vkCmdTraceRaysIndirectKHR-stride-04035
    pHitShaderBindingTable->stride must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride

  • VUID-vkCmdTraceRaysIndirectKHR-pCallableShaderBindingTable-03691
    If the buffer from which pCallableShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysIndirectKHR-pCallableShaderBindingTable-03692
    The buffer from which the pCallableShaderBindingTable->deviceAddress is queried must have been created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag

  • VUID-vkCmdTraceRaysIndirectKHR-pCallableShaderBindingTable-03693
    pCallableShaderBindingTable->deviceAddress must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment

  • VUID-vkCmdTraceRaysIndirectKHR-stride-03694
    pCallableShaderBindingTable->stride must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment

  • VUID-vkCmdTraceRaysIndirectKHR-stride-04041
    pCallableShaderBindingTable->stride must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride

  • VUID-vkCmdTraceRaysIndirectKHR-flags-03696
    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, pHitShaderBindingTable->deviceAddress must not be zero

  • VUID-vkCmdTraceRaysIndirectKHR-flags-03697
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, pHitShaderBindingTable->deviceAddress must not be zero

  • 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->deviceAddress must not be set to zero

  • 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 the table identified by pHitShaderBindingTable->deviceAddress 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 the table identified by pHitShaderBindingTable->deviceAddress 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 the table identified by pHitShaderBindingTable->deviceAddress accessed as a result of this command in order to execute an intersection shader must not be set to zero

  • VUID-vkCmdTraceRaysIndirectKHR-pHitShaderBindingTable-04735
    Any non-zero hit shader group entries in the table identified by pHitShaderBindingTable->deviceAddress accessed by this call from a geometry with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR must have been created with VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR

  • VUID-vkCmdTraceRaysIndirectKHR-pHitShaderBindingTable-04736
    Any non-zero hit shader group entries in the table identified by pHitShaderBindingTable->deviceAddress accessed by this call from a geometry with a geometryType of VK_GEOMETRY_TYPE_AABBS_KHR must have been created with VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR

  • VUID-vkCmdTraceRaysIndirectKHR-indirectDeviceAddress-03632
    If the buffer from which indirectDeviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysIndirectKHR-indirectDeviceAddress-03633
    The buffer from which indirectDeviceAddress was queried must have been created with the VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set

  • VUID-vkCmdTraceRaysIndirectKHR-indirectDeviceAddress-03634
    indirectDeviceAddress must be a multiple of 4

  • VUID-vkCmdTraceRaysIndirectKHR-indirectDeviceAddress-03636
    All device addresses between indirectDeviceAddress and indirectDeviceAddress + sizeof(VkTraceRaysIndirectCommandKHR) - 1 must be in the buffer device address range of the same buffer

  • VUID-vkCmdTraceRaysIndirectKHR-rayTracingPipelineTraceRaysIndirect-03637
    The rayTracingPipelineTraceRaysIndirect feature must be enabled

  • VUID-vkCmdTraceRaysIndirectKHR-rayTracingMotionBlurPipelineTraceRaysIndirect-04951
    If the bound ray tracing pipeline was created with VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV VkPhysicalDeviceRayTracingMotionBlurFeaturesNV::rayTracingMotionBlurPipelineTraceRaysIndirect 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 VkStridedDeviceAddressRegionKHR structure

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

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

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

  • 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-videocoding
    This command must only be called outside of a video coding scope

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 Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Compute

Action

The VkTraceRaysIndirectCommandKHR structure is defined as:

// Provided by VK_KHR_ray_tracing_pipeline
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-03638
    width must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[0] × VkPhysicalDeviceLimits::maxComputeWorkGroupSize[0]

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

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

  • VUID-VkTraceRaysIndirectCommandKHR-width-03641
    width × height × depth must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxRayDispatchInvocationCount

To dispatch ray tracing, with some parameters sourced on the device, use:

// Provided by VK_KHR_ray_tracing_maintenance1 with VK_KHR_ray_tracing_pipeline
void vkCmdTraceRaysIndirect2KHR(
    VkCommandBuffer                             commandBuffer,
    VkDeviceAddress                             indirectDeviceAddress);
  • commandBuffer is the command buffer into which the command will be recorded.

  • indirectDeviceAddress is a buffer device address which is a pointer to a VkTraceRaysIndirectCommand2KHR structure containing the trace ray parameters.

vkCmdTraceRaysIndirect2KHR behaves similarly to vkCmdTraceRaysIndirectKHR except that shader binding table parameters as well as dispatch dimensions are read by the device from indirectDeviceAddress during execution.

Valid Usage
  • VUID-vkCmdTraceRaysIndirect2KHR-magFilter-04553
    If a VkSampler created with magFilter or minFilter equal to VK_FILTER_LINEAR and compareEnable equal to VK_FALSE is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

  • VUID-vkCmdTraceRaysIndirect2KHR-mipmapMode-04770
    If a VkSampler created with mipmapMode equal to VK_SAMPLER_MIPMAP_MODE_LINEAR and compareEnable equal to VK_FALSE is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

  • VUID-vkCmdTraceRaysIndirect2KHR-None-06479
    If a VkImageView is sampled with depth comparison, the image view’s format features must contain VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT

  • VUID-vkCmdTraceRaysIndirect2KHR-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-vkCmdTraceRaysIndirect2KHR-None-07888
    If a VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER descriptor is accessed using atomic operations as a result of this command, then the storage texel buffer’s format features must contain VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT

  • VUID-vkCmdTraceRaysIndirect2KHR-None-02692
    If a VkImageView is sampled with VK_FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT

  • VUID-vkCmdTraceRaysIndirect2KHR-None-02693
    If the VK_EXT_filter_cubic extension is not enabled and any VkImageView is sampled with VK_FILTER_CUBIC_EXT as a result of this command, it must not have a VkImageViewType of VK_IMAGE_VIEW_TYPE_3D, VK_IMAGE_VIEW_TYPE_CUBE, or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY

  • VUID-vkCmdTraceRaysIndirect2KHR-filterCubic-02694
    Any VkImageView being sampled with VK_FILTER_CUBIC_EXT as a result of this command must have a VkImageViewType and format that supports cubic filtering, as specified by VkFilterCubicImageViewImageFormatPropertiesEXT::filterCubic returned by vkGetPhysicalDeviceImageFormatProperties2

  • VUID-vkCmdTraceRaysIndirect2KHR-filterCubicMinmax-02695
    Any VkImageView being sampled with VK_FILTER_CUBIC_EXT with a reduction mode of either VK_SAMPLER_REDUCTION_MODE_MIN or VK_SAMPLER_REDUCTION_MODE_MAX as a result of this command must have a VkImageViewType and format that supports cubic filtering together with minmax filtering, as specified by VkFilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax returned by vkGetPhysicalDeviceImageFormatProperties2

  • VUID-vkCmdTraceRaysIndirect2KHR-flags-02696
    Any VkImage created with a VkImageCreateInfo::flags containing VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must only be sampled using a VkSamplerAddressMode of VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE

  • VUID-vkCmdTraceRaysIndirect2KHR-OpTypeImage-07027
    For any VkImageView being written as a storage image where the image format field of the OpTypeImage is Unknown, the view’s format features must contain VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysIndirect2KHR-OpTypeImage-07028
    For any VkImageView being read as a storage image where the image format field of the OpTypeImage is Unknown, the view’s format features must contain VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysIndirect2KHR-OpTypeImage-07029
    For any VkBufferView being written as a storage texel buffer where the image format field of the OpTypeImage is Unknown, the view’s buffer features must contain VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysIndirect2KHR-OpTypeImage-07030
    Any VkBufferView being read as a storage texel buffer where the image format field of the OpTypeImage is Unknown then the view’s buffer features must contain VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT

  • VUID-vkCmdTraceRaysIndirect2KHR-None-02697
    For each set n that is statically used by a bound shader, 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-vkCmdTraceRaysIndirect2KHR-None-02698
    For each push constant that is statically used by a bound shader, 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-vkCmdTraceRaysIndirect2KHR-maintenance4-06425
    If the maintenance4 feature is not enabled, then for each push constant that is statically used by a bound shader, 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-vkCmdTraceRaysIndirect2KHR-None-08114
    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 and the bound VkPipeline was not created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysIndirect2KHR-None-08115
    If the descriptors used by the VkPipeline bound to the pipeline bind point were specified via vkCmdBindDescriptorSets, the bound VkPipeline must have been created without VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysIndirect2KHR-None-08116
    Descriptors in bound descriptor buffers, specified via vkCmdSetDescriptorBufferOffsetsEXT, must be valid if they are dynamically used by the VkPipeline bound to the pipeline bind point used by this command and the bound VkPipeline was created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysIndirect2KHR-None-08117
    If the descriptors used by the VkPipeline bound to the pipeline bind point were specified via vkCmdSetDescriptorBufferOffsetsEXT, the bound VkPipeline must have been created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT

  • VUID-vkCmdTraceRaysIndirect2KHR-None-08119
    If a descriptor is dynamically used with a VkPipeline created with VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT, the descriptor memory must be resident

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

  • VUID-vkCmdTraceRaysIndirect2KHR-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-vkCmdTraceRaysIndirect2KHR-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-vkCmdTraceRaysIndirect2KHR-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-vkCmdTraceRaysIndirect2KHR-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-vkCmdTraceRaysIndirect2KHR-uniformBuffers-06935
    If any stage of the VkPipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, and that stage was created without enabling either VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT or VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT for uniformBuffers, and the robustBufferAccess feature is not enabled, that stage 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-vkCmdTraceRaysIndirect2KHR-storageBuffers-06936
    If any stage of the VkPipeline object bound to the pipeline bind point used by this command accesses a storage buffer, and that stage was created without enabling either VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_EXT or VK_PIPELINE_ROBUSTNESS_BUFFER_BEHAVIOR_ROBUST_BUFFER_ACCESS_2_EXT for storageBuffers, and the robustBufferAccess feature is not enabled, that stage 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-vkCmdTraceRaysIndirect2KHR-commandBuffer-02707
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, any resource accessed by bound shaders must not be a protected resource

  • VUID-vkCmdTraceRaysIndirect2KHR-None-06550
    If a bound shader accesses a VkSampler or VkImageView object that enables sampler Y′CBCR conversion, that object must only be used with OpImageSample* or OpImageSparseSample* instructions

  • VUID-vkCmdTraceRaysIndirect2KHR-ConstOffset-06551
    If a bound shader accesses a VkSampler or VkImageView object that enables sampler Y′CBCR conversion, that object must not use the ConstOffset and Offset operands

  • VUID-vkCmdTraceRaysIndirect2KHR-viewType-07752
    If a VkImageView is accessed as a result of this command, then the image view’s viewType must match the Dim operand of the OpTypeImage as described in Instruction/Sampler/Image View Validation

  • VUID-vkCmdTraceRaysIndirect2KHR-format-07753
    If a VkImageView is accessed as a result of this command, then the numeric type of the image view’s format and the Sampled Type operand of the OpTypeImage must match

  • VUID-vkCmdTraceRaysIndirect2KHR-OpImageWrite-08795
    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-vkCmdTraceRaysIndirect2KHR-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 buffer view’s format

  • VUID-vkCmdTraceRaysIndirect2KHR-SampledType-04470
    If a VkImageView with a VkFormat that has a 64-bit component width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64

  • VUID-vkCmdTraceRaysIndirect2KHR-SampledType-04471
    If a VkImageView with a VkFormat that has a component width less than 64-bit is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32

  • VUID-vkCmdTraceRaysIndirect2KHR-SampledType-04472
    If a VkBufferView with a VkFormat that has a 64-bit component width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64

  • VUID-vkCmdTraceRaysIndirect2KHR-SampledType-04473
    If a VkBufferView with a VkFormat that has a component width less than 64-bit is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32

  • VUID-vkCmdTraceRaysIndirect2KHR-sparseImageInt64Atomics-04474
    If the sparseImageInt64Atomics feature is not enabled, VkImage objects created with the VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command

  • VUID-vkCmdTraceRaysIndirect2KHR-sparseImageInt64Atomics-04475
    If the sparseImageInt64Atomics feature is not enabled, VkBuffer objects created with the VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command

  • VUID-vkCmdTraceRaysIndirect2KHR-OpImageWeightedSampleQCOM-06971
    If OpImageWeightedSampleQCOM is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_WEIGHT_SAMPLED_IMAGE_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirect2KHR-OpImageWeightedSampleQCOM-06972
    If OpImageWeightedSampleQCOM uses a VkImageView as a sample weight image as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_WEIGHT_IMAGE_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirect2KHR-OpImageBoxFilterQCOM-06973
    If OpImageBoxFilterQCOM is used to sample a VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_BOX_FILTER_SAMPLED_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirect2KHR-OpImageBlockMatchSSDQCOM-06974
    If OpImageBlockMatchSSDQCOM is used to read from an VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirect2KHR-OpImageBlockMatchSADQCOM-06975
    If OpImageBlockMatchSADQCOM is used to read from an VkImageView as a result of this command, then the image view’s format features must contain VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirect2KHR-OpImageBlockMatchSADQCOM-06976
    If OpImageBlockMatchSADQCOM or OpImageBlockMatchSSDQCOM is used to read from a reference image as result of this command, then the specified reference coordinates must not fail integer texel coordinate validation

  • VUID-vkCmdTraceRaysIndirect2KHR-OpImageWeightedSampleQCOM-06977
    If OpImageWeightedSampleQCOM, OpImageBoxFilterQCOM, OpImageBlockMatchSSDQCOM, or OpImageBlockMatchSADQCOM uses a VkSampler as a result of this command, then the sampler must have been created with VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirect2KHR-OpImageWeightedSampleQCOM-06978
    If any command other than OpImageWeightedSampleQCOM, OpImageBoxFilterQCOM, OpImageBlockMatchSSDQCOM, or OpImageBlockMatchSADQCOM uses a VkSampler as a result of this command, then the sampler must not have been created with VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM

  • VUID-vkCmdTraceRaysIndirect2KHR-None-07288
    Any shader invocation executed by this command must terminate

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

  • VUID-vkCmdTraceRaysIndirect2KHR-maxPipelineRayRecursionDepth-03679
    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 maxPipelineRayRecursionDepth used to create the bound ray tracing pipeline

  • VUID-vkCmdTraceRaysIndirect2KHR-commandBuffer-03635
    commandBuffer must not be a protected command buffer

  • VUID-vkCmdTraceRaysIndirect2KHR-indirectDeviceAddress-03632
    If the buffer from which indirectDeviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdTraceRaysIndirect2KHR-indirectDeviceAddress-03633
    The buffer from which indirectDeviceAddress was queried must have been created with the VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set

  • VUID-vkCmdTraceRaysIndirect2KHR-indirectDeviceAddress-03634
    indirectDeviceAddress must be a multiple of 4

  • VUID-vkCmdTraceRaysIndirect2KHR-indirectDeviceAddress-03636
    All device addresses between indirectDeviceAddress and indirectDeviceAddress + sizeof(VkTraceRaysIndirectCommand2KHR) - 1 must be in the buffer device address range of the same buffer

  • VUID-vkCmdTraceRaysIndirect2KHR-rayTracingPipelineTraceRaysIndirect2-03637
    The rayTracingPipelineTraceRaysIndirect2 feature must be enabled

  • VUID-vkCmdTraceRaysIndirect2KHR-rayTracingMotionBlurPipelineTraceRaysIndirect-04951
    If the bound ray tracing pipeline was created with VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV VkPhysicalDeviceRayTracingMotionBlurFeaturesNV::rayTracingMotionBlurPipelineTraceRaysIndirect feature must be enabled

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

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

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

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

  • VUID-vkCmdTraceRaysIndirect2KHR-videocoding
    This command must only be called outside of a video coding scope

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 Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Compute

Action

The VkTraceRaysIndirectCommand2KHR structure is defined as:

// Provided by VK_KHR_ray_tracing_maintenance1 with VK_KHR_ray_tracing_pipeline
typedef struct VkTraceRaysIndirectCommand2KHR {
    VkDeviceAddress    raygenShaderRecordAddress;
    VkDeviceSize       raygenShaderRecordSize;
    VkDeviceAddress    missShaderBindingTableAddress;
    VkDeviceSize       missShaderBindingTableSize;
    VkDeviceSize       missShaderBindingTableStride;
    VkDeviceAddress    hitShaderBindingTableAddress;
    VkDeviceSize       hitShaderBindingTableSize;
    VkDeviceSize       hitShaderBindingTableStride;
    VkDeviceAddress    callableShaderBindingTableAddress;
    VkDeviceSize       callableShaderBindingTableSize;
    VkDeviceSize       callableShaderBindingTableStride;
    uint32_t           width;
    uint32_t           height;
    uint32_t           depth;
} VkTraceRaysIndirectCommand2KHR;
  • raygenShaderRecordAddress is a VkDeviceAddress of the ray generation shader binding table record used by this command.

  • raygenShaderRecordSize is a VkDeviceSize number of bytes corresponding to the ray generation shader binding table record at base address raygenShaderRecordAddress.

  • missShaderBindingTableAddress is a VkDeviceAddress of the first record in the miss shader binding table used by this command.

  • missShaderBindingTableSize is a VkDeviceSize number of bytes corresponding to the total size of the miss shader binding table at missShaderBindingTableAddress that may be accessed by this command.

  • missShaderBindingTableStride is a VkDeviceSize number of bytes between records of the miss shader binding table.

  • hitShaderBindingTableAddress is a VkDeviceAddress of the first record in the hit shader binding table used by this command.

  • hitShaderBindingTableSize is a VkDeviceSize number of bytes corresponding to the total size of the hit shader binding table at hitShaderBindingTableAddress that may be accessed by this command.

  • hitShaderBindingTableStride is a VkDeviceSize number of bytes between records of the hit shader binding table.

  • callableShaderBindingTableAddress is a VkDeviceAddress of the first record in the callable shader binding table used by this command.

  • callableShaderBindingTableSize is a VkDeviceSize number of bytes corresponding to the total size of the callable shader binding table at callableShaderBindingTableAddress that may be accessed by this command.

  • callableShaderBindingTableStride is a VkDeviceSize number of bytes between records of the callable shader binding table.

  • 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 VkTraceRaysIndirectCommand2KHR have the same meaning as the similarly named parameters of vkCmdTraceRaysKHR.

Indirect shader binding table buffer parameters must satisfy the same memory alignment and binding requirements as their counterparts in vkCmdTraceRaysIndirectKHR and vkCmdTraceRaysKHR.

Valid Usage
  • VUID-VkTraceRaysIndirectCommand2KHR-pRayGenShaderBindingTable-03680
    If the buffer from which raygenShaderRecordAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkTraceRaysIndirectCommand2KHR-pRayGenShaderBindingTable-03681
    The buffer from which the raygenShaderRecordAddress is queried must have been created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag

  • VUID-VkTraceRaysIndirectCommand2KHR-pRayGenShaderBindingTable-03682
    raygenShaderRecordAddress must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment

  • VUID-VkTraceRaysIndirectCommand2KHR-pMissShaderBindingTable-03683
    If the buffer from which missShaderBindingTableAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkTraceRaysIndirectCommand2KHR-pMissShaderBindingTable-03684
    The buffer from which the missShaderBindingTableAddress is queried must have been created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag

  • VUID-VkTraceRaysIndirectCommand2KHR-pMissShaderBindingTable-03685
    missShaderBindingTableAddress must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment

  • VUID-VkTraceRaysIndirectCommand2KHR-stride-03686
    missShaderBindingTableStride must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment

  • VUID-VkTraceRaysIndirectCommand2KHR-stride-04029
    missShaderBindingTableStride must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride

  • VUID-VkTraceRaysIndirectCommand2KHR-pHitShaderBindingTable-03687
    If the buffer from which hitShaderBindingTableAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkTraceRaysIndirectCommand2KHR-pHitShaderBindingTable-03688
    The buffer from which the hitShaderBindingTableAddress is queried must have been created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag

  • VUID-VkTraceRaysIndirectCommand2KHR-pHitShaderBindingTable-03689
    hitShaderBindingTableAddress must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment

  • VUID-VkTraceRaysIndirectCommand2KHR-stride-03690
    hitShaderBindingTableStride must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment

  • VUID-VkTraceRaysIndirectCommand2KHR-stride-04035
    hitShaderBindingTableStride must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride

  • VUID-VkTraceRaysIndirectCommand2KHR-pCallableShaderBindingTable-03691
    If the buffer from which callableShaderBindingTableAddress was queried is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkTraceRaysIndirectCommand2KHR-pCallableShaderBindingTable-03692
    The buffer from which the callableShaderBindingTableAddress is queried must have been created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag

  • VUID-VkTraceRaysIndirectCommand2KHR-pCallableShaderBindingTable-03693
    callableShaderBindingTableAddress must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment

  • VUID-VkTraceRaysIndirectCommand2KHR-stride-03694
    callableShaderBindingTableStride must be a multiple of VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment

  • VUID-VkTraceRaysIndirectCommand2KHR-stride-04041
    callableShaderBindingTableStride must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride

  • VUID-VkTraceRaysIndirectCommand2KHR-flags-03696
    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, hitShaderBindingTableAddress must not be zero

  • VUID-VkTraceRaysIndirectCommand2KHR-flags-03697
    If the currently bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, hitShaderBindingTableAddress must not be zero

  • VUID-VkTraceRaysIndirectCommand2KHR-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 missShaderBindingTableAddress must not be set to zero

  • VUID-VkTraceRaysIndirectCommand2KHR-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 the table identified by hitShaderBindingTableAddress accessed as a result of this command in order to execute an any-hit shader must not be set to zero

  • VUID-VkTraceRaysIndirectCommand2KHR-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 the table identified by hitShaderBindingTableAddress accessed as a result of this command in order to execute a closest hit shader must not be set to zero

  • VUID-VkTraceRaysIndirectCommand2KHR-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 the table identified by hitShaderBindingTableAddress accessed as a result of this command in order to execute an intersection shader must not be set to zero

  • VUID-VkTraceRaysIndirectCommand2KHR-pHitShaderBindingTable-04735
    Any non-zero hit shader group entries in the table identified by hitShaderBindingTableAddress accessed by this call from a geometry with a geometryType of VK_GEOMETRY_TYPE_TRIANGLES_KHR must have been created with VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR

  • VUID-VkTraceRaysIndirectCommand2KHR-pHitShaderBindingTable-04736
    Any non-zero hit shader group entries in the table identified by hitShaderBindingTableAddress accessed by this call from a geometry with a geometryType of VK_GEOMETRY_TYPE_AABBS_KHR must have been created with VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR

  • VUID-VkTraceRaysIndirectCommand2KHR-width-03638
    width must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[0] × VkPhysicalDeviceLimits::maxComputeWorkGroupSize[0]

  • VUID-VkTraceRaysIndirectCommand2KHR-height-03639
    height must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[1] × VkPhysicalDeviceLimits::maxComputeWorkGroupSize[1]

  • VUID-VkTraceRaysIndirectCommand2KHR-depth-03640
    depth must be less than or equal to VkPhysicalDeviceLimits::maxComputeWorkGroupCount[2] × VkPhysicalDeviceLimits::maxComputeWorkGroupSize[2]

  • VUID-VkTraceRaysIndirectCommand2KHR-width-03641
    width × height × depth must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxRayDispatchInvocationCount

40.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, either as queried by vkGetRayTracingShaderGroupHandlesKHR to refer to those specified shaders, or all zeros to refer to a zero shader group. A zero shader group behaves as though it is a shader group consisting entirely of VK_SHADER_UNUSED_KHR. 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 vkCmdTraceRaysNV, vkCmdTraceRaysKHR, or vkCmdTraceRaysIndirectKHR commands. Shader binding tables are read-only in shaders that are executing on the ray tracing pipeline.

Shader variables identified with the ShaderRecordBufferKHR storage class are used to access the provided shader binding table. Such variables must be:

  • typed as OpTypeStruct, or an array of this type,

  • identified with a Block decoration, and

  • laid out explicitly using the Offset, ArrayStride, and MatrixStride decorations as specified in Offset and Stride Assignment.

The Offset decoration for any member of a Block-decorated variable in the ShaderRecordBufferKHR storage class must not cause the space required for that variable to extend outside the range [0, maxStorageBufferRange).

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.

Note

Because different shader record buffers can be associated with the same shader, a shader variable with ShaderRecordBufferKHR storage class will not be dynamically uniform if different invocations of the same shader can reference different data in the shader record buffer, such as if the same shader occurs twice in the shader binding table with a different shader record buffer. In this case, indexing resources based on values in the ShaderRecordBufferKHR storage class, the index should be decorated as NonUniform.

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

For vkCmdTraceRaysKHR, the location of the ray generation shader is specified by the pRaygenShaderBindingTable->deviceAddress parameter — there is no indexing. All data accessed must be less than pRaygenShaderBindingTable->size bytes from deviceAddress. pRaygenShaderBindingTable->stride is unused, and must be equal to pRaygenShaderBindingTable->size.

For vkCmdTraceRaysNV, the location of the ray generation shader is specified by the raygenShaderBindingTableBuffer and raygenShaderBindingOffset parameters — there is no indexing.

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 (VkAccelerationStructureInstanceKHR). This value determines the beginning of the shader binding table records for a given instance.

In the following rule, geometryIndex refers to the geometry index of the intersected geometry within the instance.

The sbtRecordOffset and sbtRecordStride values are passed in as parameters to traceNV() or traceRayEXT() 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 OpTraceRayNV or OpTraceRayKHR or OpTraceRayMotionNV instruction.

The result of this computation is then added to pHitShaderBindingTable->deviceAddress, a device address passed to vkCmdTraceRaysKHR , or hitShaderBindingOffset, a base offset passed to vkCmdTraceRaysNV .

For vkCmdTraceRaysKHR, the complete rule to compute a hit shader binding table record address in the pHitShaderBindingTable is:

pHitShaderBindingTable->deviceAddress + pHitShaderBindingTable->stride × ( instanceShaderBindingTableRecordOffset + geometryIndex × sbtRecordStride + sbtRecordOffset )

All data accessed must be less than pHitShaderBindingTable->size bytes from the base address.

For vkCmdTraceRaysNV, the offset and stride come from direct parameters, so the full rule to compute a hit shader binding table record address in the hitShaderBindingTableBuffer is:

hitShaderBindingOffset + hitShaderBindingStride × ( instanceShaderBindingTableRecordOffset + geometryIndex × sbtRecordStride + sbtRecordOffset )

Miss Shaders

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

The base for the computation of miss shader locations is pMissShaderBindingTable->deviceAddress, a device address passed into vkCmdTraceRaysKHR , or missShaderBindingOffset, a base offset passed into vkCmdTraceRaysNV .

The missIndex value is passed in as a parameter to traceNV() or traceRayEXT() 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 OpTraceRayNV or OpTraceRayKHR or OpTraceRayMotionNV instruction.

For vkCmdTraceRaysKHR, the complete rule to compute a miss shader binding table record address in the pMissShaderBindingTable is:

pMissShaderBindingTable->deviceAddress + pMissShaderBindingTable->stride × missIndex

All data accessed must be less than pMissShaderBindingTable->size bytes from the base address.

For vkCmdTraceRaysNV, the offset and stride come from direct parameters, so the full rule to compute a miss shader binding table record address in the missShaderBindingTableBuffer is:

missShaderBindingOffset + missShaderBindingStride × missIndex

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->deviceAddress, a device address passed into vkCmdTraceRaysKHR , or callableShaderBindingOffset, a base offset passed into vkCmdTraceRaysNV .

The sbtRecordIndex value is passed in as a parameter to executeCallableNV() or executeCallableEXT() 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 OpExecuteCallableNV or OpExecuteCallableKHR instruction.

For vkCmdTraceRaysKHR, the complete rule to compute a callable shader binding table record address in the pCallableShaderBindingTable is:

pCallableShaderBindingTable->deviceAddress + pCallableShaderBindingTable->stride × sbtRecordIndex

All data accessed must be less than pCallableShaderBindingTable->size bytes from the base address.

For vkCmdTraceRaysNV, the offset and stride come from direct parameters, so the full rule to compute a callable shader binding table record address in the callableShaderBindingTableBuffer is:

callableShaderBindingOffset + callableShaderBindingStride × sbtRecordIndex

40.4. Ray Tracing Pipeline Stack

Ray tracing pipelines have a potentially large set of shaders which may be invoked in various call chain combinations to perform ray tracing. To store parameters for a given shader execution, an implementation may use a stack of data in memory. This stack must be sized to the sum of the stack sizes of all shaders in any call chain executed by the application.

If the stack size is not set explicitly, the stack size for a pipeline is:

rayGenStackMax + min(1, maxPipelineRayRecursionDepth) × max(closestHitStackMax, missStackMax, intersectionStackMax + anyHitStackMax) + max(0, maxPipelineRayRecursionDepth-1) × max(closestHitStackMax, missStackMax) + 2 × callableStackMax

where rayGenStackMax, closestHitStackMax, missStackMax, anyHitStackMax, intersectionStackMax, and callableStackMax are the maximum stack values queried by the respective shader stages for any shaders in any shader groups defined by the pipeline.

This stack size is potentially significant, so an application may want to provide a more accurate stack size after pipeline compilation. The value that the application provides is the maximum value of the sum of all shaders in a call chain across all possible call chains, taking into account any application specific knowledge about the properties of the call chains.

Note

For example, if an application has two types of closest hit and miss shaders that it can use but the first level of rays will only use the first kind (possibly reflection) and the second level will only use the second kind (occlusion or shadow ray, for example) then the application can compute the stack size by something similar to:

rayGenStack + max(closestHit1Stack, miss1Stack) + max(closestHit2Stack, miss2Stack)

This is guaranteed to be no larger than the default stack size computation which assumes that both call levels may be the larger of the two.

40.5. Ray Tracing Capture Replay

In a similar way to bufferDeviceAddressCaptureReplay, the rayTracingPipelineShaderGroupHandleCaptureReplay feature allows the querying of opaque data which can be used in a future replay.

During the capture phase, capture/replay tools are expected to query opaque data for shader group handle replay using vkGetRayTracingCaptureReplayShaderGroupHandlesKHR.

Providing the opaque data during replay, using VkRayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle at pipeline creation time, causes the implementation to generate identical shader group handles to those in the capture phase, allowing capture/replay tools to reuse previously recorded shader binding table buffer contents or to obtain the same handles by calling vkGetRayTracingCaptureReplayShaderGroupHandlesKHR again.