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 the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the 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.

Valid Usage

  • 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 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-03677
    If deferredOperation is not VK_NULL_HANDLE, it must be a valid VkDeferredOperationKHR object

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

  • 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
On success, this command returns

  • VK_SUCCESS

  • VK_OPERATION_DEFERRED_KHR

  • VK_OPERATION_NOT_DEFERRED_KHR

  • VK_PIPELINE_COMPILE_REQUIRED_EXT

On failure, this command returns

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS

See Also

VK_KHR_ray_tracing_pipeline, VkAllocationCallbacks, VkDeferredOperationKHR, VkDevice, VkPipeline, VkPipelineCache, VkRayTracingPipelineCreateInfoKHR

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

SPDX-License-Identifier: CC-BY-4.0