VkRayTracingPipelineCreateInfoKHR(3)

Name

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

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 a VkStructureType value identifying 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. If VkPhysicalDeviceProperties::apiVersion is greater than or equal to Vulkan 1.3 or VK_KHR_maintenance4 is enabled layout must not be accessed by the implementation outside of the duration of the command this structure is passed to.

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

If the pNext chain includes a VkPipelineCreateFlags2CreateInfo structure, VkPipelineCreateFlags2CreateInfo::flags from that structure is used instead of flags from this structure.

If the pNext chain includes a VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV structure, then that structure controls whether cluster acceleration structures are allowed in this ray tracing pipeline.

Valid Usage

  • VUID-VkRayTracingPipelineCreateInfoKHR-None-09497
    If the pNext chain does not include a VkPipelineCreateFlags2CreateInfo structure, flags must be a valid combination of VkPipelineCreateFlagBits values

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-07984
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid ray tracing VkPipeline handle

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-07985
    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-07986
    If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, basePipelineIndex must be -1 or basePipelineHandle must be VK_NULL_HANDLE

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-07987
    If a push constant block is declared in a shader, a push constant range in layout must match the shader stage

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-10069
    If a push constant block is declared in a shader, the block must be contained inside the push constant range in layout that matches the stage

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-07988
    If a resource variable is declared in a shader, the corresponding descriptor set in layout must match the shader stage

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-07990
    If a resource variable is declared in a shader, and the descriptor type is not VK_DESCRIPTOR_TYPE_MUTABLE_EXT, the corresponding descriptor set in layout must match the descriptor type

  • VUID-VkRayTracingPipelineCreateInfoKHR-layout-07991
    If a resource variable is declared in a shader as an array, the corresponding descriptor binding used to create layout must have a descriptorCount that is greater than or equal to the length of the array

  • VUID-VkRayTracingPipelineCreateInfoKHR-None-10391
    If a resource variables is declared in a shader as an array of descriptors, then the descriptor type of that variable must not be VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK

  • VUID-VkRayTracingPipelineCreateInfoKHR-flags-11798
    If shader64BitIndexing feature is not enabled, flags must not contain VK_PIPELINE_CREATE_2_64_BIT_INDEXING_BIT_EXT

Valid Usage (Implicit)

See Also

VK_KHR_ray_tracing_pipeline, VkPipeline, VkPipelineCreateFlags, VkPipelineDynamicStateCreateInfo, 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.