vkCreateRayTracingPipelinesKHR(3)

# vkCreateRayTracingPipelinesKHR(3) Manual Page

## Name

vkCreateRayTracingPipelinesKHR - Creates a new ray tracing pipeline object

Loading… please wait.

## 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.

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` 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

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

SPDX-License-Identifier: CC-BY-4.0