C Specification

The VkRayTracingPipelineCreateInfoKHR structure is defined as:

// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkRayTracingPipelineCreateInfoKHR {
    VkStructureType                                      sType;
    const void*                                          pNext;
    VkPipelineCreateFlags                                flags;
    uint32_t                                             stageCount;
    const VkPipelineShaderStageCreateInfo*               pStages;
    uint32_t                                             groupCount;
    const VkRayTracingShaderGroupCreateInfoKHR*          pGroups;
    uint32_t                                             maxPipelineRayRecursionDepth;
    const VkPipelineLibraryCreateInfoKHR*                pLibraryInfo;
    const VkRayTracingPipelineInterfaceCreateInfoKHR*    pLibraryInterface;
    const VkPipelineDynamicStateCreateInfo*              pDynamicState;
    VkPipelineLayout                                     layout;
    VkPipeline                                           basePipelineHandle;
    int32_t                                              basePipelineIndex;
} VkRayTracingPipelineCreateInfoKHR;

Members

  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this 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.

  • maxPipelineRayRecursionDepth is the maximum recursion depth of shaders executed by this pipeline.

  • pLibraryInfo is a pointer to a VkPipelineLibraryCreateInfoKHR structure defining pipeline libraries to include.

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

  • pDynamicState is a pointer to a VkPipelineDynamicStateCreateInfo structure, and is used to indicate which properties of the pipeline state object are dynamic and can be changed independently of the pipeline state. This can be NULL, which means no state in the pipeline is considered dynamic.

  • 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 pLibraryInfo, 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.

The default stack size for a pipeline if VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR is not provided is computed as described in Ray Tracing Pipeline Stack.

Valid Usage
  • VUID-VkRayTracingPipelineCreateInfoKHR-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-VkRayTracingPipelineCreateInfoKHR-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-VkRayTracingPipelineCreateInfoKHR-flags-03423
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is not -1, basePipelineHandle must be VK_NULL_HANDLE

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03424
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is not VK_NULL_HANDLE, basePipelineIndex must be -1

  • VUID-VkRayTracingPipelineCreateInfoKHR-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-VkRayTracingPipelineCreateInfoKHR-layout-03427
    layout must be consistent with all shaders specified in pStages

  • VUID-VkRayTracingPipelineCreateInfoKHR-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-VkRayTracingPipelineCreateInfoKHR-flags-02904
    flags must not include VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV

  • VUID-VkRayTracingPipelineCreateInfoKHR-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

  • VUID-VkRayTracingPipelineCreateInfoKHR-stage-03425
    If flags does not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, the stage member of at least one element of pStages, including those implicitly added by pLibraryInfo, must be VK_SHADER_STAGE_RAYGEN_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-maxPipelineRayRecursionDepth-03589
    maxPipelineRayRecursionDepth must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxRayRecursionDepth

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03465
    If flags includes VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, pLibraryInterface must not be NULL

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03590
    If pLibraryInfo is not NULL and its libraryCount member is greater than 0, its pLibraryInterface member must not be NULL

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraries-03591
    Each element of the pLibraries member of pLibraryInfo must have been created with the value of maxPipelineRayRecursionDepth equal to that in this pipeline

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03592
    If pLibraryInfo is not NULL, each element of its pLibraries member must have been created with a layout that is compatible with the layout in this pipeline

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03593
    If pLibraryInfo is not NULL, each element of its pLibraries member must have been created with values of the maxPipelineRayPayloadSize and maxPipelineRayHitAttributeSize members of pLibraryInterface equal to those in this pipeline

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03594
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, each element of the pLibraries member of libraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04718
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR, each element of the pLibraries member of libraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04719
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR, each element of the pLibraries member of libraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04720
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, each element of the pLibraries member of libraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04721
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, each element of the pLibraries member of libraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04722
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, each element of the pLibraries member of libraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-04723
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, each element of the pLibraries member of libraries must have been created with the VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR bit set

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03595
    If the VK_KHR_pipeline_library extension is not enabled, pLibraryInfo and pLibraryInterface must be NULL.

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03470
    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

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03471
    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

  • VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03596
    If the rayTraversalPrimitiveCulling feature is not enabled, flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03597
    If the rayTraversalPrimitiveCulling feature is not enabled, flags must not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-03598
    If flags includes VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, rayTracingPipelineShaderGroupHandleCaptureReplay must be enabled

  • VUID-VkRayTracingPipelineCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplay-03599
    If VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay is VK_TRUE and the pShaderGroupCaptureReplayHandle member of any element of pGroups is not NULL, flags must include VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03600
    If pLibraryInfo is not NULL and its libraryCount is 0, stageCount must not be 0

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03601
    If pLibraryInfo is not NULL and its libraryCount is 0, groupCount must not be 0

  • VUID-VkRayTracingPipelineCreateInfoKHR-pDynamicStates-03602
    Any element of the pDynamicStates member of pDynamicState must be VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR

Valid Usage (Implicit)
  • VUID-VkRayTracingPipelineCreateInfoKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_KHR

  • VUID-VkRayTracingPipelineCreateInfoKHR-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkPipelineCreationFeedbackCreateInfoEXT

  • VUID-VkRayTracingPipelineCreateInfoKHR-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-parameter
    flags must be a valid combination of VkPipelineCreateFlagBits values

  • VUID-VkRayTracingPipelineCreateInfoKHR-pStages-parameter
    If stageCount is not 0, pStages must be a valid pointer to an array of stageCount valid VkPipelineShaderStageCreateInfo structures

  • VUID-VkRayTracingPipelineCreateInfoKHR-pGroups-parameter
    If groupCount is not 0, pGroups must be a valid pointer to an array of groupCount valid VkRayTracingShaderGroupCreateInfoKHR structures

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-parameter
    If pLibraryInfo is not NULL, pLibraryInfo must be a valid pointer to a valid VkPipelineLibraryCreateInfoKHR structure

  • VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInterface-parameter
    If pLibraryInterface is not NULL, pLibraryInterface must be a valid pointer to a valid VkRayTracingPipelineInterfaceCreateInfoKHR structure

  • VUID-VkRayTracingPipelineCreateInfoKHR-pDynamicState-parameter
    If pDynamicState is not NULL, pDynamicState must be a valid pointer to a valid VkPipelineDynamicStateCreateInfo structure

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-parameter
    layout must be a valid VkPipelineLayout handle

  • VUID-VkRayTracingPipelineCreateInfoKHR-commonparent
    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

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

SPDX-License-Identifier: CC-BY-4.0