vkCmdTraceRaysNV(3)

Name

vkCmdTraceRaysNV - Initialize a ray tracing dispatch

C Specification

To dispatch ray tracing for the VK_NV_ray_tracing extension 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);

Parameters

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

Description

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

Valid Usage
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 VK_QUEUE_COMPUTE_BIT operations

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

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

  • 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

VK_QUEUE_COMPUTE_BIT

Action
Conditional Rendering

vkCmdTraceRaysNV is not affected by conditional rendering

See Also

VK_NV_ray_tracing, VkBuffer, VkCommandBuffer, VkDeviceSize

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.