C Specification

To query the opaque handles of shaders in the ray tracing pipeline, call:

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

or the equivalent command

// Provided by VK_NV_ray_tracing
VkResult vkGetRayTracingShaderGroupHandlesNV(
    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 or VkRayTracingPipelineCreateInfoNV::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 a user-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::shaderGroupHandleSize.

If pipeline was created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and the pipelineLibraryGroupHandles feature is enabled applications can query group handles from that pipeline, even if the pipeline is a library and is never bound to a command buffer. These group handles remain 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-vkGetRayTracingShaderGroupHandlesKHR-pipeline-04619
    pipeline must be a ray tracing pipeline

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-firstGroup-04050
    firstGroup must be less than the number of shader groups in pipeline

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-firstGroup-02419
    The sum of firstGroup and groupCount must be less than or equal to the number of shader groups in pipeline

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-dataSize-02420
    dataSize must be at least VkPhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleSize × groupCount

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-07828
    If the pipelineLibraryGroupHandles feature is not enabled, pipeline must not have been created with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR

Valid Usage (Implicit)
  • VUID-vkGetRayTracingShaderGroupHandlesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-parameter
    pipeline must be a valid VkPipeline handle

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-pData-parameter
    pData must be a valid pointer to an array of dataSize bytes

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-dataSize-arraylength
    dataSize must be greater than 0

  • VUID-vkGetRayTracingShaderGroupHandlesKHR-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_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

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 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0