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