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

  • VK_OPERATION_DEFERRED_KHR

  • VK_OPERATION_NOT_DEFERRED_KHR

  • VK_PIPELINE_COMPILE_REQUIRED_EXT

  • VK_SUCCESS

Failure

  • VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_UNKNOWN

  • VK_ERROR_VALIDATION_FAILED

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.