vkCmdTraceRaysKHR(3)

Name

vkCmdTraceRaysKHR - Initialize a ray tracing dispatch

C Specification

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

Parameters

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

Description

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

Valid Usage

  • 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-03681
    pRayGenShaderBindingTable->deviceAddress must be a device address allocated to the application from a buffer created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag set

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

  • VUID-vkCmdTraceRaysKHR-pMissShaderBindingTable-03684
    pMissShaderBindingTable->deviceAddress must be a device address allocated to the application from a buffer created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag set

  • 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-03688
    pHitShaderBindingTable->deviceAddress must be a device address allocated to the application from a buffer created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag set

  • 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-03692
    pCallableShaderBindingTable->deviceAddress must be a device address allocated to the application from a buffer created with the VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag set

  • 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-03511
    If the bound ray tracing pipeline was created with flags that included VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, the entries in the table identified by pMissShaderBindingTable->deviceAddress accessed as a result of this command in order to execute a miss shader must not be zero

  • VUID-vkCmdTraceRaysKHR-flags-03512
    If the 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 zero

  • VUID-vkCmdTraceRaysKHR-flags-03513
    If the 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 zero

  • VUID-vkCmdTraceRaysKHR-flags-03514
    If the 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 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 VK_QUEUE_COMPUTE_BIT operations

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

  • VUID-vkCmdTraceRaysKHR-suspended
    This command must not be called between suspended render pass instances

  • 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

VK_QUEUE_COMPUTE_BIT

Action
Conditional Rendering

vkCmdTraceRaysKHR is not affected by conditional rendering

See Also

VK_KHR_ray_tracing_pipeline, VkCommandBuffer, VkStridedDeviceAddressRegionKHR

Document Notes

For more information, see the Vulkan Specification.

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.