Structures

VkRayTracingPipelineCreateInfoKHR

Structure specifying parameters of a newly created ray tracing pipeline

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 maxPipelineRayRecursionDepth;
    const VkPipelineLibraryCreateInfoKHR* pLibraryInfo;
    const VkRayTracingPipelineInterfaceCreateInfoKHR* pLibraryInterface;
    const VkPipelineDynamicStateCreateInfo* pDynamicState;
    VkPipelineLayout layout;
    VkPipeline basePipelineHandle;
    int32_t basePipelineIndex;
} VkRayTracingPipelineCreateInfoKHR;

pub struct RayTracingPipelineCreateInfoKHR {
    s_type: vk::StructureType,
    p_next: *const c_void,
    flags: vk::PipelineCreateFlags, // Pipeline creation flags
    stage_count: u32,
    p_stages: *const vk::PipelineShaderStageCreateInfo, // One entry for each active shader stage
    group_count: u32,
    p_groups: *const vk::RayTracingShaderGroupCreateInfoKHR,
    max_pipeline_ray_recursion_depth: u32,
    p_library_info: *const vk::PipelineLibraryCreateInfoKHR,
    p_library_interface: *const vk::RayTracingPipelineInterfaceCreateInfoKHR,
    p_dynamic_state: *const vk::PipelineDynamicStateCreateInfo,
    layout: vk::PipelineLayout, // Interface layout of the pipeline
    base_pipeline_handle: vk::Pipeline, // If VK_PIPELINE_CREATE_DERIVATIVE_BIT is set and this value is nonzero, it specifies the handle of the base pipeline this is a derivative of
    base_pipeline_index: i32, // If VK_PIPELINE_CREATE_DERIVATIVE_BIT is set and this value is not -1, it specifies an index into pCreateInfos of the base pipeline this is a derivative of
}

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.

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 basePipelineHandlemust be VK_NULL_HANDLE

VUID-VkRayTracingPipelineCreateInfoKHR-layout-07987

If a push constant block is declared in a shader and layout is not VK_NULL_HANDLE, 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 and layout is not VK_NULL_HANDLE, 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 and layout is not VK_NULL_HANDLE, the corresponding descriptor set in layout must match the shader stage

VUID-VkRayTracingPipelineCreateInfoKHR-layout-07990

If a resource variable is declared in a shader, layout is not VK_NULL_HANDLE, 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 and layout is not VK_NULL_HANDLE, 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

VUID-VkRayTracingPipelineCreateInfoKHR-pipelineCreationCacheControl-02878

If the pipelineCreationCacheControl feature is not enabled, flagsmust not include VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT nor VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT

VUID-VkRayTracingPipelineCreateInfoKHR-pipelineProtectedAccess-07368

If the pipelineProtectedAccess feature is not enabled, flagsmust not include VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT nor VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT

VUID-VkRayTracingPipelineCreateInfoKHR-flags-07369

flags must not include both VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT and VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT

VUID-VkRayTracingPipelineCreateInfoKHR-flags-11311

If VkPipelineCreateFlags2CreateInfoKHR::flags includes VK_PIPELINE_CREATE_2_DESCRIPTOR_HEAP_BIT_EXT, layout must be VK_NULL_HANDLE

VUID-VkRayTracingPipelineCreateInfoKHR-flags-11312

If VkPipelineCreateFlags2CreateInfoKHR::flags includes VK_PIPELINE_CREATE_2_DESCRIPTOR_HEAP_BIT_EXT, all shader variables in the shader resource interface with a DescriptorSet and Binding decoration must have a mapping declared in VkShaderDescriptorSetAndBindingMappingInfoEXT::pMappings

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-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-flags-12341

flags must not include VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT nor VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT

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, pLibraryInterface must not be NULL

VUID-VkRayTracingPipelineCreateInfoKHR-pLibraries-03591

Each element of pLibraryInfo→pLibraries must have been created with the value of maxPipelineRayRecursionDepth equal to that in this pipeline

VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03592

If pLibraryInfo is not NULL and layout is not VK_NULL_HANDLE, each element of pLibraryInfo→pLibrariesmust 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 pLibraryInfo→pLibraries 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 pLibraryInfo→pLibraries 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 pLibraryInfo→pLibraries 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 pLibraryInfo→pLibraries 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 pLibraryInfo→pLibraries 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 pLibraryInfo→pLibraries 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 pLibraryInfo→pLibraries 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 each 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 each 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, flagsmust not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR

VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03597

If the rayTraversalPrimitiveCulling feature is not enabled, flagsmust not include VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR

VUID-VkRayTracingPipelineCreateInfoKHR-flags-06546

flags must not include both VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR and VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_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-07999

If pLibraryInfo is NULL or its libraryCount is 0, stageCount must not be 0

VUID-VkRayTracingPipelineCreateInfoKHR-flags-08700

If flags does not include VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and either pLibraryInfo is NULL or its libraryCount is 0, groupCount must not be 0

VUID-VkRayTracingPipelineCreateInfoKHR-pDynamicStates-03602

Any element of the pDynamicStates member of pDynamicStatemust be VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR

VUID-VkRayTracingPipelineCreateInfoKHR-pipelineStageCreationFeedbackCount-06652

If VkPipelineCreationFeedbackCreateInfo::pipelineStageCreationFeedbackCount is not 0, it must be equal to stageCount

VUID-VkRayTracingPipelineCreateInfoKHR-stage-06899

The stage value in all pStages elements must be one of VK_SHADER_STAGE_RAYGEN_BIT_KHR, VK_SHADER_STAGE_ANY_HIT_BIT_KHR, VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR, VK_SHADER_STAGE_MISS_BIT_KHR, VK_SHADER_STAGE_INTERSECTION_BIT_KHR, or VK_SHADER_STAGE_CALLABLE_BIT_KHR

Valid Usage (Implicit)

VUID-VkRayTracingPipelineCreateInfoKHR-sType-sType

sType must be VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_KHR

VUID-VkRayTracingPipelineCreateInfoKHR-pNext-pNext

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 VkPipelineBinaryInfoKHR, VkPipelineCreateFlags2CreateInfo, VkPipelineCreationFeedbackCreateInfo, VkPipelineRobustnessCreateInfo, or VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV

VK_KHR_ray_tracing_pipeline

Type

Structures

Extended By

VkPipelineBinaryInfoKHR VkPipelineCreateFlags2CreateInfo VkPipelineCreationFeedbackCreateInfo VkPipelineOfflineCreateInfo VkPipelineRobustnessCreateInfo VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV