Function Prototype

vkGetRayTracingShaderGroupHandlesKHR

Query ray tracing pipeline shader group handles

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

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

or the equivalent command

VkResult vkGetRayTracingShaderGroupHandlesNV(
    VkDevice device,
    VkPipeline pipeline,
    uint32_t firstGroup,
    uint32_t groupCount,
    size_t dataSize,
    void* pData);
  • 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 an application-allocated buffer where the results will be written.

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-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-pData-parameter

pData must be a valid pointer to an array of dataSize bytes

VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-parent

pipeline must have been created, allocated, or retrieved from device