vkCmdTraceRaysKHR(3)

# vkCmdTraceRaysKHR(3) Manual Page

## Name

vkCmdTraceRaysKHR - Initialize a ray tracing dispatch

Loading… please wait.

## C Specification

To dispatch ray tracing use:

    // Provided by VK_KHR_ray_tracing
    void vkCmdTraceRaysKHR(
        VkCommandBuffer                             commandBuffer,
        const VkStridedBufferRegionKHR*             pRaygenShaderBindingTable,
        const VkStridedBufferRegionKHR*             pMissShaderBindingTable,
        const VkStridedBufferRegionKHR*             pHitShaderBindingTable,
        const VkStridedBufferRegionKHR*             pCallableShaderBindingTable,
        uint32_t                                    width,
        uint32_t                                    height,
        uint32_t                                    depth);

## Parameters

- `commandBuffer` is the command buffer into which the command will be recorded.

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

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

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

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

- `width` is the width of the ray trace query dimensions.

- `height` is height of the ray trace query dimensions.

- `depth` is depth of the ray trace query dimensions.

## Description

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

Valid Usage

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Valid Usage (Implicit)

- VUID-vkCmdTraceRaysKHR-commandBuffer-parameter
  `commandBuffer` must be a valid VkCommandBuffer handle

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

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

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

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

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

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

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

Host Synchronization

- Host access to `commandBuffer` must be externally synchronized

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

Command Properties

Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type
--- | --- | --- | ---
Primary Secondary | Outside | Compute |

## See Also

VkCommandBuffer, VkStridedBufferRegionKHR

## 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 (c) 2014-2020 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0