# VkRayTracingPipelineCreateInfoKHR(3) Manual Page

## Name

VkRayTracingPipelineCreateInfoKHR - Structure specifying parameters of a newly created ray tracing pipeline

## C Specification

The `VkRayTracingPipelineCreateInfoKHR` structure is defined as:

    typedef struct VkRayTracingPipelineCreateInfoKHR {
        VkStructureType                                      sType;
        const void*                                          pNext;
        VkPipelineCreateFlags                                flags;
        uint32_t                                             stageCount;
        const VkPipelineShaderStageCreateInfo*               pStages;
        uint32_t                                             groupCount;
        const VkRayTracingShaderGroupCreateInfoKHR*          pGroups;
        uint32_t                                             maxRecursionDepth;
        VkPipelineLibraryCreateInfoKHR                       libraries;
        const VkRayTracingPipelineInterfaceCreateInfoKHR*    pLibraryInterface;
        VkPipelineLayout                                     layout;
        VkPipeline                                           basePipelineHandle;
        int32_t                                              basePipelineIndex;
    } VkRayTracingPipelineCreateInfoKHR;

## Members

- `sType` is the type of this structure.

- `pNext` is `NULL` or a pointer to an extension-specific structure.

- `flags` is a bitmask of VkPipelineCreateFlagBits specifying how the pipeline will be generated.

- `stageCount` is the number of entries in the `pStages` array.

- `pStages` is a pointer to an array of `stageCount` VkPipelineShaderStageCreateInfo structures describing the set of the shader stages to be included in the ray tracing pipeline.

- `groupCount` is the number of entries in the `pGroups` array.

- `pGroups` is a pointer to an array of `groupCount` VkRayTracingShaderGroupCreateInfoKHR structures describing the set of the shader stages to be included in each shader group in the ray tracing pipeline.

- `maxRecursionDepth` is the maximum recursion depth of shaders executed by this pipeline.

- `libraries` is a VkPipelineLibraryCreateInfoKHR structure defining pipeline libraries to include.

- `pLibraryInterface` is a pointer to a VkRayTracingPipelineInterfaceCreateInfoKHR structure defining additional information when using pipeline libraries.

- `layout` is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline.

- `basePipelineHandle` is a pipeline to derive from.

- `basePipelineIndex` is an index into the `pCreateInfos` parameter to use as a pipeline to derive from.

## Description

The parameters `basePipelineHandle` and `basePipelineIndex` are described in more detail in Pipeline Derivatives.

When `VK_PIPELINE_CREATE_LIBRARY_BIT_KHR` is specified, this pipeline defines a pipeline library which cannot be bound as a ray tracing pipeline directly. Instead, pipeline libraries define common shaders and shader groups which can be included in future pipeline creation.

If pipeline libraries are included in `libraries`, shaders defined in those libraries are treated as if they were defined as additional entries in `pStages`, appended in the order they appear in the `pLibraries` array and in the `pStages` array when those libraries were defined.

When referencing shader groups in order to obtain a shader group handle, groups defined in those libraries are treated as if they were defined as additional entries in `pGroups`, appended in the order they appear in the `pLibraries` array and in the `pGroups` array when those libraries were defined. The shaders these groups reference are set when the pipeline library is created, referencing those specified in the pipeline library, not in the pipeline that includes it.

If the VkDeferredOperationInfoKHR structure is included in the `pNext` chain of VkRayTracingPipelineCreateInfoKHR, the operation of this pipeline creation is deferred, as defined in the Deferred Host Operations chapter.

Valid Usage

- [[VUID-{refpage}-flags-03421]] If `flags` contains the `VK_PIPELINE_CREATE_DERIVATIVE_BIT` flag, and `basePipelineIndex` is `-1`, `basePipelineHandle` must be a valid handle to a ray tracing `VkPipeline`

- [[VUID-{refpage}-flags-03422]] If `flags` contains the `VK_PIPELINE_CREATE_DERIVATIVE_BIT` flag, and `basePipelineHandle` is VK_NULL_HANDLE, `basePipelineIndex` must be a valid index into the calling command’s `pCreateInfos` parameter

- [[VUID-{refpage}-flags-03423]] If `flags` contains the `VK_PIPELINE_CREATE_DERIVATIVE_BIT` flag, and `basePipelineIndex` is not `-1`, `basePipelineHandle` must be VK_NULL_HANDLE

- [[VUID-{refpage}-flags-03424]] If `flags` contains the `VK_PIPELINE_CREATE_DERIVATIVE_BIT` flag, and `basePipelineHandle` is not VK_NULL_HANDLE, `basePipelineIndex` must be `-1`

- [[VUID-{refpage}-stage-03425]] The `stage` member of at least one element of `pStages` must be `VK_SHADER_STAGE_RAYGEN_BIT_KHR`

- [[VUID-{refpage}-pStages-03426]] The shader code for the entry points identified by `pStages`, and the rest of the state identified by this structure must adhere to the pipeline linking rules described in the Shader Interfaces chapter

- [[VUID-{refpage}-layout-03427]] `layout` must be consistent with all shaders specified in `pStages`

- [[VUID-{refpage}-layout-03428]] The number of resources in `layout` accessible to each shader stage that is used by the pipeline must be less than or equal to VkPhysicalDeviceLimits::`maxPerStageResources`

- [[VUID-{refpage}-flags-02904]] `flags` must not include `VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV`

- [[VUID-{refpage}-pipelineCreationCacheControl-02905]] If the `pipelineCreationCacheControl` feature is not enabled, `flags` must not include `VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT` or `VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT`

- `maxRecursionDepth` must be less than or equal to VkPhysicalDeviceRayTracingPropertiesKHR::`maxRecursionDepth`

- If `flags` includes `VK_PIPELINE_CREATE_LIBRARY_BIT_KHR`, `pLibraryInterface` must not be `NULL`

- If the `libraryCount` member of `libraries` is greater than `0`, `pLibraryInterface` must not be `NULL`

- Each element of the `pLibraries` member of `libraries` must have been created with the value of `maxRecursionDepth` equal to that in this pipeline

- Each element of the `pLibraries` member of `libraries` must have been created with a `layout` that is compatible with the `layout` in this pipeline

- Each element of the `pLibraries` member of `libraries` must have been created with values of the `maxPayloadSize`, `maxAttributeSize`, and `maxCallableSize` members of `pLibraryInterface` equal to those in this pipeline

- If `flags` includes `VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR`, for any element of `pGroups` with a `type` of `VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR` or `VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR`, the `anyHitShader` of that element must not be `VK_SHADER_UNUSED_KHR`

- If `flags` includes `VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR`, for any element of `pGroups` with a `type` of `VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR` or `VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR`, the `closestHitShader` of that element must not be `VK_SHADER_UNUSED_KHR`

- If the `rayTracingPrimitiveCulling` feature is not enabled, `flags` must not include `VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR`

- If the `rayTracingPrimitiveCulling` feature is not enabled, `flags` must not include `VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR`

- If `libraries.pname`:libraryCount is zero, then `stageCount` must not be zero

- If `libraries.pname`:libraryCount is zero, then `groupCount` must not be zero

Valid Usage (Implicit)

- `sType` must be `VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_KHR`

- Each `pNext` member of any structure (including this one) in the `pNext` chain must be either `NULL` or a pointer to a valid instance of VkDeferredOperationInfoKHR or VkPipelineCreationFeedbackCreateInfoEXT

- The `sType` value of each struct in the `pNext` chain must be unique

- `flags` must be a valid combination of VkPipelineCreateFlagBits values

- If `stageCount` is not `0`, `pStages` must be a valid pointer to an array of `stageCount` valid VkPipelineShaderStageCreateInfo structures

- If `groupCount` is not `0`, `pGroups` must be a valid pointer to an array of `groupCount` valid VkRayTracingShaderGroupCreateInfoKHR structures

- `libraries` must be a valid VkPipelineLibraryCreateInfoKHR structure

- If `pLibraryInterface` is not `NULL`, `pLibraryInterface` must be a valid pointer to a valid VkRayTracingPipelineInterfaceCreateInfoKHR structure

- `layout` must be a valid VkPipelineLayout handle

- Both of `basePipelineHandle`, and `layout` that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

## See Also

VkPipeline, VkPipelineCreateFlags, VkPipelineLayout, VkPipelineLibraryCreateInfoKHR, VkPipelineShaderStageCreateInfo, VkRayTracingPipelineInterfaceCreateInfoKHR, VkRayTracingShaderGroupCreateInfoKHR, VkStructureType, vkCreateRayTracingPipelinesKHR

## 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 (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.