Structure specifying parameters of a newly created ray tracing pipeline.

Description

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

When 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 DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR is not provided is computed as described in Ray Tracing Pipeline Stack.

If a VkPipelineCreateFlags2CreateInfoKHR structure is present in the pNext chain, VkPipelineCreateFlags2CreateInfoKHR::flags from that structure is used instead of flags from this structure.

Valid Usage

• If flags contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid ray tracing VkPipeline handle
• If flags contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is NULL_HANDLE, basePipelineIndex must be a valid index into the calling command’s pCreateInfos parameter
• If flags contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, basePipelineIndex must be -1 or basePipelineHandle must be NULL_HANDLE
• If a push constant block is declared in a shader, a push constant range in layout must match both the shader stage and range
• If a resource variables is declared in a shader, a descriptor slot in layout must match the shader stage
• If a resource variables is declared in a shader, and the descriptor type is not DESCRIPTOR_TYPE_MUTABLE_EXT, a descriptor slot in layout must match the descriptor type
• If a resource variables is declared in a shader as an array, a descriptor slot in layout must match the descriptor count

• 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
• 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
• flags must not include PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV
• If the pipelineCreationCacheControl feature is not enabled, flags must not include PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT or PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT
• If flags does not include PIPELINE_CREATE_LIBRARY_BIT_KHR, the stage member of at least one element of pStages, including those implicitly added by pLibraryInfo, must be SHADER_STAGE_RAYGEN_BIT_KHR
• maxPipelineRayRecursionDepth must be less than or equal to VkPhysicalDeviceRayTracingPipelinePropertiesKHR::maxRayRecursionDepth
• If flags includes PIPELINE_CREATE_LIBRARY_BIT_KHR, pLibraryInterface must not be NULL
• If pLibraryInfo is not NULL and its libraryCount member is greater than 0, pLibraryInterface must not be NULL
• Each element of pLibraryInfo→pLibraries must have been created with the value of maxPipelineRayRecursionDepth equal to that in this pipeline
• 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
• 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
• If flags includes PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, each element of pLibraryInfo→pLibraries must have been created with the PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR bit set
• If flags includes PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR, each element of pLibraryInfo→pLibraries must have been created with the PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR bit set
• If flags includes PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR, each element of pLibraryInfo→pLibraries must have been created with the PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR bit set
• If flags includes PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, each element of pLibraryInfo→pLibraries must have been created with the PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR bit set
• If flags includes PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, each element of pLibraryInfo→pLibraries must have been created with the PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR bit set
• If flags includes PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, each element of pLibraryInfo→pLibraries must have been created with the PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR bit set
• If flags includes PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, each element of pLibraryInfo→pLibraries must have been created with the PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR bit set
• If the VK_KHR_pipeline_library extension is not enabled, pLibraryInfo and pLibraryInterface must be NULL
• If flags includes PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, for any element of pGroups with a type of RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the anyHitShader of that element must not be SHADER_UNUSED_KHR
• If flags includes PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, for any element of pGroups with a type of RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the closestHitShader of that element must not be SHADER_UNUSED_KHR
• If the rayTraversalPrimitiveCulling feature is not enabled, flags must not include PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
• If the rayTraversalPrimitiveCulling feature is not enabled, flags must not include PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
• flags must not include both PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR and PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
• If flags includes PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, rayTracingPipelineShaderGroupHandleCaptureReplay must be enabled
• If VkPhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay is TRUE and the pShaderGroupCaptureReplayHandle member of any element of pGroups is not NULL, flags must include PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
• If pLibraryInfo is NULL or its libraryCount is 0, stageCount must not be 0
• If flags does not include PIPELINE_CREATE_LIBRARY_BIT_KHR and either pLibraryInfo is NULL or its libraryCount is 0, groupCount must not be 0
• Any element of the pDynamicStates member of pDynamicState must be DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR
• If VkPipelineCreationFeedbackCreateInfo::pipelineStageCreationFeedbackCount is not 0, it must be equal to stageCount
• The stage value in all pStages elements must be one of SHADER_STAGE_RAYGEN_BIT_KHR, SHADER_STAGE_ANY_HIT_BIT_KHR, SHADER_STAGE_CLOSEST_HIT_BIT_KHR, SHADER_STAGE_MISS_BIT_KHR, SHADER_STAGE_INTERSECTION_BIT_KHR, or SHADER_STAGE_CALLABLE_BIT_KHR
• If flags includes PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT, each element of pLibraryInfo→pLibraries must have been created with the PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT bit set
• If flags includes PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV, each element of pLibraryInfo→pLibraries must have been created with the PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV bit set

Valid Usage (Implicit)

• sType must be 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 VkPipelineCreateFlags2CreateInfoKHR, VkPipelineCreationFeedbackCreateInfo, or VkPipelineRobustnessCreateInfoEXT
• 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
• If pLibraryInfo is not NULL, pLibraryInfo must be a valid pointer to a valid VkPipelineLibraryCreateInfoKHR structure
• If pLibraryInterface is not NULL, pLibraryInterface must be a valid pointer to a valid VkRayTracingPipelineInterfaceCreateInfoKHR structure
• If pDynamicState is not NULL, pDynamicState must be a valid pointer to a valid VkPipelineDynamicStateCreateInfo 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

VkPipelineDynamicStateCreateInfo, VkPipelineLibraryCreateInfoKHR, VkPipelineShaderStageCreateInfo, VkRayTracingPipelineInterfaceCreateInfoKHR, VkRayTracingShaderGroupCreateInfoKHR, CreateRayTracingPipelinesKHR

Layout

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