Structure specifying parameters of a newly created pipeline shader stage.

Description

If module is not NULL_HANDLE, the shader code used by the pipeline is defined by module. If module is NULL_HANDLE, the shader code is defined by the chained VkShaderModuleCreateInfo if present.

If the shaderModuleIdentifier feature is enabled, applications can omit shader code for stage and instead provide a module identifier. This is done by including a VkPipelineShaderStageModuleIdentifierCreateInfoEXT struct with identifierSize not equal to 0 in the pNext chain. A shader stage created in this way is equivalent to one created using a shader module with the same identifier. The identifier allows an implementation to look up a pipeline without consuming a valid SPIR-V module. If a pipeline is not found, pipeline compilation is not possible and the implementation must fail as specified by PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT.

When an identifier is used in lieu of a shader module, implementations may fail pipeline compilation with PIPELINE_COMPILE_REQUIRED for any reason.

Applications can use identifiers when creating pipelines with PIPELINE_CREATE_LIBRARY_BIT_KHR. When creating such pipelines, SUCCESS may be returned, but subsequently fail when referencing the pipeline in a VkPipelineLibraryCreateInfoKHR struct. Applications must allow pipeline compilation to fail during link steps with PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT as it may not be possible to determine if a pipeline can be created from identifiers until the link step.

Valid Usage

• If the geometryShader feature is not enabled, stage must not be SHADER_STAGE_GEOMETRY_BIT
• If the tessellationShader feature is not enabled, stage must not be SHADER_STAGE_TESSELLATION_CONTROL_BIT or SHADER_STAGE_TESSELLATION_EVALUATION_BIT
• If the meshShaders feature is not enabled, stage must not be SHADER_STAGE_MESH_BIT_EXT
• If the taskShaders feature is not enabled, stage must not be SHADER_STAGE_TASK_BIT_EXT
• If the clustercullingShader feature is not enabled, stage must not be SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI
• stage must not be SHADER_STAGE_ALL_GRAPHICS, or SHADER_STAGE_ALL
• pName must be the name of an OpEntryPoint in module with an execution model that matches stage
• If the identified entry point includes any variable in its interface that is declared with the ClipDistance BuiltIn decoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxClipDistances
• If the identified entry point includes any variable in its interface that is declared with the CullDistance BuiltIn decoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxCullDistances
• If the identified entry point includes any variables in its interface that are declared with the ClipDistance or CullDistance BuiltIn decoration, those variables must not have array sizes which sum to more than VkPhysicalDeviceLimits::maxCombinedClipAndCullDistances
• If the identified entry point includes any variable in its interface that is declared with the SampleMask BuiltIn decoration, that variable must not have an array size greater than VkPhysicalDeviceLimits::maxSampleMaskWords
• If stage is SHADER_STAGE_VERTEX_BIT, the identified entry point must not include any input variable in its interface that is decorated with CullDistance
• If stage is SHADER_STAGE_TESSELLATION_CONTROL_BIT or SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and the identified entry point has an OpExecutionMode instruction specifying a patch size with OutputVertices, the patch size must be greater than 0 and less than or equal to VkPhysicalDeviceLimits::maxTessellationPatchSize
• If stage is SHADER_STAGE_GEOMETRY_BIT, the identified entry point must have an OpExecutionMode instruction specifying a maximum output vertex count that is greater than 0 and less than or equal to VkPhysicalDeviceLimits::maxGeometryOutputVertices
• If stage is SHADER_STAGE_GEOMETRY_BIT, the identified entry point must have an OpExecutionMode instruction specifying an invocation count that is greater than 0 and less than or equal to VkPhysicalDeviceLimits::maxGeometryShaderInvocations
• If stage is either SHADER_STAGE_VERTEX_BIT, SHADER_STAGE_TESSELLATION_CONTROL_BIT, SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or SHADER_STAGE_GEOMETRY_BIT, and the identified entry point writes to Layer for any primitive, it must write the same value to Layer for all vertices of a given primitive
• If stage is either SHADER_STAGE_VERTEX_BIT, SHADER_STAGE_TESSELLATION_CONTROL_BIT, SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or SHADER_STAGE_GEOMETRY_BIT, and the identified entry point writes to ViewportIndex for any primitive, it must write the same value to ViewportIndex for all vertices of a given primitive
• If stage is SHADER_STAGE_FRAGMENT_BIT, the identified entry point must not include any output variables in its interface decorated with CullDistance
• If stage is SHADER_STAGE_FRAGMENT_BIT, and the identified entry point writes to FragDepth in any execution path, all execution paths that are not exclusive to helper invocations must either discard the fragment, or write or initialize the value of FragDepth
• If stage is SHADER_STAGE_FRAGMENT_BIT, and the identified entry point writes to FragStencilRefEXT in any execution path, all execution paths that are not exclusive to helper invocations must either discard the fragment, or write or initialize the value of FragStencilRefEXT
• If flags has the PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set, the subgroupSizeControl feature must be enabled
• If flags has the PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT flag set, the computeFullSubgroups feature must be enabled
• If flags includes PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT, stage must be one of SHADER_STAGE_MESH_BIT_EXT, SHADER_STAGE_TASK_BIT_EXT, or SHADER_STAGE_COMPUTE_BIT
• If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, flags must not have the PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set
• If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, the subgroupSizeControl feature must be enabled, and stage must be a valid bit specified in requiredSubgroupSizeStages
• If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain and stage is SHADER_STAGE_COMPUTE_BIT, SHADER_STAGE_MESH_BIT_EXT, or SHADER_STAGE_TASK_BIT_EXT, the local workgroup size of the shader must be less than or equal to the product of VkPipelineShaderStageRequiredSubgroupSizeCreateInfo::requiredSubgroupSize and maxComputeWorkgroupSubgroups
• If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, and flags has the PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT flag set, the local workgroup size in the X dimension of the pipeline must be a multiple of VkPipelineShaderStageRequiredSubgroupSizeCreateInfo::requiredSubgroupSize
• If flags has both the PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT and PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flags set, the local workgroup size in the X dimension of the pipeline must be a multiple of maxSubgroupSize
• If flags has the PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT flag set and flags does not have the PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set and no VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, the local workgroup size in the X dimension of the pipeline must be a multiple of subgroupSize
• If module uses the OpTypeCooperativeMatrixKHR instruction with a Scope equal to Subgroup, then the local workgroup size in the X dimension of the pipeline must be a multiple of subgroupSize.
• If a shader module identifier is specified for this stage, a VkShaderModuleCreateInfo structure must not be present in the pNext chain
• If a shader module identifier is not specified for this stage, module must be a valid VkShaderModule or there must be a valid VkShaderModuleCreateInfo structure in the pNext chain
• If a shader module identifier is not specified for this stage, and neither the maintenance5 nor graphicsPipelineLibrary feature are enabled, module must be a valid VkShaderModule
• If a shader module identifier is specified for this stage, module must be NULL_HANDLE
• If a shader module identifier is not specified, the shader code used by the pipeline must be valid as described by the Khronos SPIR-V Specification after applying the specializations provided in pSpecializationInfo, if any, and then converting all specialization constants into fixed constants

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO
• 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 VkDebugUtilsObjectNameInfoEXT, VkPipelineRobustnessCreateInfoEXT, VkPipelineShaderStageModuleIdentifierCreateInfoEXT, VkPipelineShaderStageNodeCreateInfoAMDX, VkPipelineShaderStageRequiredSubgroupSizeCreateInfo, VkShaderModuleCreateInfo, or VkShaderModuleValidationCacheCreateInfoEXT
• The sType value of each struct in the pNext chain must be unique
• flags must be a valid combination of VkPipelineShaderStageCreateFlagBits values
• stage must be a valid VkShaderStageFlagBits value
• If module is not NULL_HANDLE, module must be a valid VkShaderModule handle
• pName must be a null-terminated UTF-8 string
• If pSpecializationInfo is not NULL, pSpecializationInfo must be a valid pointer to a valid VkSpecializationInfo structure

See Also

VkComputePipelineCreateInfo, VkExecutionGraphPipelineCreateInfoAMDX, VkGraphicsPipelineCreateInfo, VkGraphicsShaderGroupCreateInfoNV, VkRayTracingPipelineCreateInfoKHR, VkRayTracingPipelineCreateInfoNV, VkSpecializationInfo

Layout

struct VkPipelineShaderStageCreateInfo {
    VkStructureType sType;
    void const * pNext;
    VkPipelineShaderStageCreateFlags flags;
    VkShaderStageFlagBits stage;
    VkShaderModule module;
    char const * pName;
    VkSpecializationInfo const * pSpecializationInfo;
}