vkCmdTraceRaysNV(3)

# vkCmdTraceRaysNV(3) Manual Page

## Name

vkCmdTraceRaysNV - Initialize a ray tracing dispatch

Loading… please wait.

## C Specification

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

## 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

- 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-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-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-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-None-02697
  For each set n that is statically used by the `VkPipeline` bound to the pipeline bind point used by this command, a descriptor set must have been bound to n at the same pipeline bind point, with a `VkPipelineLayout` that is compatible for set n, with the `VkPipelineLayout` used to create the current `VkPipeline`, as described in [descriptorsets-compatibility]

- VUID-vkCmdTraceRaysNV-None-02698
  For each push constant that is statically used by the `VkPipeline` bound to the pipeline bind point used by this command, a push constant value must have been set for the same pipeline bind point, with a `VkPipelineLayout` that is compatible for push constants, with the `VkPipelineLayout` used to create the current `VkPipeline`, as described in [descriptorsets-compatibility]

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

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

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

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

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

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

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

- VUID-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 image view’s format.

- VUID-vkCmdTraceRaysNV-SampledType-04470
  If a VkImageView with a VkFormat that has a 64-bit channel 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 channel 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 channel 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 channel 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-None-03429
  Any shader group handle referenced by this call must have been queried from the currently bound ray tracing shader pipeline

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

- VUID-vkCmdTraceRaysNV-maxRecursionDepth-03625
  This command must not cause a 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-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 | Supported Queue Types | Pipeline Type
--- | --- | --- | ---
Primary Secondary | Outside | Compute |

## See Also

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.

## Copyright

Copyright 2014-2021 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0