# vkCmdTraceRaysKHR(3) Manual Page

## Name

vkCmdTraceRaysKHR - Initialize a ray tracing dispatch

## C Specification

To dispatch ray tracing use:

    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 the strided buffer range that holds the shader binding table data for the ray generation shader stage.

- `pMissShaderBindingTable` is the strided buffer range that holds the shader binding table data for the miss shader stage.

- `pHitShaderBindingTable` is the strided buffer range that holds the shader binding table data for the hit shader stage.

- `pCallableShaderBindingTable` is the strided buffer range 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

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

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

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

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

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

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

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

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

- 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

- A valid pipeline must be bound to the pipeline bind point used by this command

- 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

- 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

- 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

- 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

- 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

- 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

- 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

- 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

- `raygenShaderBindingOffset` must be less than the size of `raygenShaderBindingTableBuffer`

- `raygenShaderBindingOffset` must be a multiple of `VkPhysicalDeviceRayTracingPropertiesKHR`::`shaderGroupBaseAlignment`

- `missShaderBindingOffset` must be less than the size of `missShaderBindingTableBuffer`

- `missShaderBindingOffset` must be a multiple of `VkPhysicalDeviceRayTracingPropertiesKHR`::`shaderGroupBaseAlignment`

- `hitShaderBindingOffset` must be less than the size of `hitShaderBindingTableBuffer`

- `hitShaderBindingOffset` must be a multiple of `VkPhysicalDeviceRayTracingPropertiesKHR`::`shaderGroupBaseAlignment`

- `callableShaderBindingOffset` must be less than the size of `callableShaderBindingTableBuffer`

- `callableShaderBindingOffset` must be a multiple of `VkPhysicalDeviceRayTracingPropertiesKHR`::`shaderGroupBaseAlignment`

- `missShaderBindingStride` must be a multiple of `VkPhysicalDeviceRayTracingPropertiesKHR`::`shaderGroupHandleSize`

- `hitShaderBindingStride` must be a multiple of `VkPhysicalDeviceRayTracingPropertiesKHR`::`shaderGroupHandleSize`

- `callableShaderBindingStride` must be a multiple of `VkPhysicalDeviceRayTracingPropertiesKHR`::`shaderGroupHandleSize`

- `missShaderBindingStride` must be less than or equal to `VkPhysicalDeviceRayTracingPropertiesKHR`::`maxShaderGroupStride`

- `hitShaderBindingStride` must be less than or equal to `VkPhysicalDeviceRayTracingPropertiesKHR`::`maxShaderGroupStride`

- `callableShaderBindingStride` must be less than or equal to `VkPhysicalDeviceRayTracingPropertiesKHR`::`maxShaderGroupStride`

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

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

- 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

- 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

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

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

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

- 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 `hitShaderBindingTable` must not be VK_NULL_HANDLE

- 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 `hitShaderBindingTable` must not be VK_NULL_HANDLE

- 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 `hitShaderBindingTable` must not be VK_NULL_HANDLE

- 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 `missShaderBindingTable` must contain a valid miss shader

- 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 `hitShaderBindingTable` accessed as a result of this command in order to execute an any hit shader must not be set to zero

- 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 `hitShaderBindingTable` accessed as a result of this command in order to execute a closest hit shader must not be set to zero

- 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 `hitShaderBindingTable` accessed as a result of this command in order to execute an intersection shader must not be set to zero

Valid Usage (Implicit)

- `commandBuffer` must be a valid VkCommandBuffer handle

- `pRaygenShaderBindingTable` must be a valid pointer to a valid VkStridedBufferRegionKHR structure

- `pMissShaderBindingTable` must be a valid pointer to a valid VkStridedBufferRegionKHR structure

- `pHitShaderBindingTable` must be a valid pointer to a valid VkStridedBufferRegionKHR structure

- `pCallableShaderBindingTable` must be a valid pointer to a valid VkStridedBufferRegionKHR structure

- `commandBuffer` must be in the recording state

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

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

Host Synchronization

- 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 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.