vkGetRayTracingCaptureReplayShaderGroupHandlesKHR(3)

# vkGetRayTracingCaptureReplayShaderGroupHandlesKHR(3) Manual Page

## Name

vkGetRayTracingCaptureReplayShaderGroupHandlesKHR - Query opaque capture replay data for pipeline shader group handles

## C Specification

To query the opaque capture data of shader groups in a ray tracing pipeline, call:

    // Provided by VK_KHR_ray_tracing_pipeline
    VkResult vkGetRayTracingCaptureReplayShaderGroupHandlesKHR(
        VkDevice                                    device,
        VkPipeline                                  pipeline,
        uint32_t                                    firstGroup,
        uint32_t                                    groupCount,
        size_t                                      dataSize,
        void*                                       pData);

## Parameters

- `device` is the logical device containing the ray tracing pipeline.

- `pipeline` is the ray tracing pipeline object containing the shaders.

- `firstGroup` is the index of the first group to retrieve a handle for from the VkRayTracingPipelineCreateInfoKHR::`pGroups` array.

- `groupCount` is the number of shader handles to retrieve.

- `dataSize` is the size in bytes of the buffer pointed to by `pData`.

- `pData` is a pointer to an application-allocated buffer where the results will be written.

## Description

On success, an array of `groupCount` shader handles will be written to `pData`, with each element being of size VkPhysicalDeviceRayTracingPipelinePropertiesKHR::`shaderGroupHandleCaptureReplaySize`. The first handle written corresponds to the group identified by `firstGroup`, with subsequent handles corresponding to consecutive shader groups in the order they appear in the VkRayTracingPipelineCreateInfoKHR::`pGroups` array.

Once queried, this opaque data can be provided at pipeline creation time (in a subsequent execution), using VkRayTracingShaderGroupCreateInfoKHR::`pShaderGroupCaptureReplayHandle`, as described in Ray Tracing Capture Replay.

If `pipeline` was created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and the pipelineLibraryGroupHandles feature is enabled applications can query capture replay group handles from that pipeline. The capture replay handle remains bitwise identical for any `pipeline` which references the pipeline library. Group indices are assigned as-if the pipeline was created without VK_PIPELINE_CREATE_LIBRARY_BIT_KHR.

Valid Usage

- VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-04620
  `pipeline` must be a ray tracing pipeline

- VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-firstGroup-04051
  `firstGroup` must be less than the number of shader groups in `pipeline`

- VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-firstGroup-03483
  The sum of `firstGroup` and `groupCount` must be less than or equal to the number of shader groups in `pipeline`

- VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-dataSize-03484
  `dataSize` must be at least VkPhysicalDeviceRayTracingPipelinePropertiesKHR::`shaderGroupHandleCaptureReplaySize` × `groupCount`

- VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-rayTracingPipelineShaderGroupHandleCaptureReplay-03606
  `VkPhysicalDeviceRayTracingPipelineFeaturesKHR`::`rayTracingPipelineShaderGroupHandleCaptureReplay` must be enabled to call this function

- VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-03607
  `pipeline` must have been created with a `flags` that included VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR

- VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-07829
  If the pipelineLibraryGroupHandles feature is not enabled, `pipeline` must not have been created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

Valid Usage (Implicit)

- VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-parameter
  `pipeline` must be a valid VkPipeline handle

- VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pData-parameter
  `pData` must be a valid pointer to an array of `dataSize` bytes

- VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-dataSize-arraylength
  `dataSize` must be greater than `0`

- VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-parent
  `pipeline` must have been created, allocated, or retrieved from `device`

Return Codes

On success, this command returns

  - VK_SUCCESS

On failure, this command returns

  - VK_ERROR_OUT_OF_DEVICE_MEMORY

  - VK_ERROR_OUT_OF_HOST_MEMORY

  - VK_ERROR_UNKNOWN

  - VK_ERROR_VALIDATION_FAILED

## See Also

VK_KHR_ray_tracing_pipeline, VkDevice, VkPipeline

## 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-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0