vkCreateRayTracingPipelinesKHR(3)

Name

vkCreateRayTracingPipelinesKHR - Creates a new ray tracing pipeline object

C Specification

To create ray tracing pipelines, call:

// Provided by VK_KHR_ray_tracing_pipeline
VkResult vkCreateRayTracingPipelinesKHR(
    VkDevice                                    device,
    VkDeferredOperationKHR                      deferredOperation,
    VkPipelineCache                             pipelineCache,
    uint32_t                                    createInfoCount,
    const VkRayTracingPipelineCreateInfoKHR*    pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkPipeline*                                 pPipelines);

Parameters

device is the logical device that creates the ray tracing pipelines.
deferredOperation is VK_NULL_HANDLE or the handle of a valid VkDeferredOperationKHR request deferral object for this command.
pipelineCache is either VK_NULL_HANDLE, indicating that pipeline caching is disabled, or to enable caching, the handle of a valid VkPipelineCache object. The implementation must not access this object outside of the duration of this command.
createInfoCount is the length of the pCreateInfos and pPipelines arrays.
pCreateInfos is a pointer to an array of VkRayTracingPipelineCreateInfoKHR structures.
pAllocator controls host memory allocation as described in the Memory Allocation chapter.
pPipelines is a pointer to an array in which the resulting ray tracing pipeline objects are returned.

Description

The VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS error is returned if the implementation is unable to reuse the shader group handles provided in VkRayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle when VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay is enabled.

Pipelines are created and returned as described for Multiple Pipeline Creation.

Valid Usage

VUID-vkCreateRayTracingPipelinesKHR-device-09677
device must support at least one queue family with the VK_QUEUE_COMPUTE_BIT capability
VUID-vkCreateRayTracingPipelinesKHR-flags-03415
If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element
VUID-vkCreateRayTracingPipelinesKHR-flags-03416
If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set
VUID-vkCreateRayTracingPipelinesKHR-flags-03816
flags must not contain the VK_PIPELINE_CREATE_DISPATCH_BASE_BIT flag
VUID-vkCreateRayTracingPipelinesKHR-pipelineCache-02903
If pipelineCache was created with VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, host access to pipelineCache must be externally synchronized

VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-03678
Any previous deferred operation that was associated with deferredOperation must be complete

VUID-vkCreateRayTracingPipelinesKHR-pNext-09616
If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, pipelineCache must be VK_NULL_HANDLE
VUID-vkCreateRayTracingPipelinesKHR-pNext-09617
If a VkPipelineCreateFlags2CreateInfoKHR structure with the VK_PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR flag set is included in the pNext chain of any element of pCreateInfos, pipelineCache must be VK_NULL_HANDLE
VUID-vkCreateRayTracingPipelinesKHR-binaryCount-09620
If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT must not be set in the flags of that element
VUID-vkCreateRayTracingPipelinesKHR-binaryCount-09621
If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT must not be set in the flags of that element
VUID-vkCreateRayTracingPipelinesKHR-binaryCount-09622
If VkPipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT must not be set in the flags of that element
VUID-vkCreateRayTracingPipelinesKHR-rayTracingPipeline-03586
The rayTracingPipeline feature must be enabled
VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-03587
If deferredOperation is not VK_NULL_HANDLE, the flags member of elements of pCreateInfos must not include VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT

Valid Usage (Implicit)

VUID-vkCreateRayTracingPipelinesKHR-device-parameter
device must be a valid VkDevice handle
VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-parameter
If deferredOperation is not VK_NULL_HANDLE, deferredOperation must be a valid VkDeferredOperationKHR handle
VUID-vkCreateRayTracingPipelinesKHR-pipelineCache-parameter
If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle
VUID-vkCreateRayTracingPipelinesKHR-pCreateInfos-parameter
pCreateInfos must be a valid pointer to an array of createInfoCount valid VkRayTracingPipelineCreateInfoKHR structures
VUID-vkCreateRayTracingPipelinesKHR-pAllocator-parameter
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
VUID-vkCreateRayTracingPipelinesKHR-pPipelines-parameter
pPipelines must be a valid pointer to an array of createInfoCount VkPipeline handles
VUID-vkCreateRayTracingPipelinesKHR-createInfoCount-arraylength
createInfoCount must be greater than 0
VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-parent
If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device
VUID-vkCreateRayTracingPipelinesKHR-pipelineCache-parent
If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

Failure

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.