VulkanHub
Structures

VkPipelineShaderStageCreateInfo

Structure specifying parameters of a newly created pipeline shader stage

The VkPipelineShaderStageCreateInfo structure is defined as:

typedef struct VkPipelineShaderStageCreateInfo {
    VkStructureType sType;
    const void* pNext;
    VkPipelineShaderStageCreateFlags flags;
    VkShaderStageFlagBits stage;
    VkShaderModule module;
    const VkSpecializationInfo* pSpecializationInfo;
} VkPipelineShaderStageCreateInfo;
  • 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 VkPipelineShaderStageCreateFlagBits specifying how the pipeline shader stage will be generated.
  • stage is a VkShaderStageFlagBits value specifying a single pipeline stage.
  • module is optionally a VkShaderModule object containing the shader code for this stage. The implementation must not access this object outside of the duration of the command this structure is passed to.
  • pName is a pointer to a null-terminated UTF-8 string specifying the entry point name of the shader for this stage.
  • pSpecializationInfo is a pointer to a VkSpecializationInfo structure, as described in Specialization Constants, or NULL.

If module is not VK_NULL_HANDLE, the shader code used by the pipeline is defined by module. If module is VK_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 structure 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 VK_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 VK_PIPELINE_COMPILE_REQUIRED for any reason.

The rationale for the relaxed requirement on implementations to return a pipeline with VkPipelineShaderStageModuleIdentifierCreateInfoEXT is that layers or tools may intercept pipeline creation calls and require the full SPIR-V context to operate correctly. ICDs are not expected to fail pipeline compilation if the pipeline exists in a cache somewhere.

Applications can use identifiers when creating pipelines with VK_PIPELINE_CREATE_LIBRARY_BIT_KHR. When creating such pipelines, VK_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 VK_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

VUID-VkPipelineShaderStageCreateInfo-descriptorHeap-11314

If the descriptorHeap feature is not enabled, VkShaderDescriptorSetAndBindingMappingInfoEXT::mappingCountmust be 0

VUID-VkPipelineShaderStageCreateInfo-pNext-11315

If the pNext chain specifies a descriptor mapping using VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_DATA_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_DATA_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_RESOURCE_HEAP_DATA_EXT, the mapped resource in the shader must be a variable with a structure type decorated with Block in the Uniform Storage Class

VUID-VkPipelineShaderStageCreateInfo-pNext-11316

If the pNext chain specifies a descriptor mapping using VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_DATA_EXT, the mapped structure must not be larger than the sum of pushDataOffset used in the mapping and maxPushDataSize

VUID-VkPipelineShaderStageCreateInfo-pNext-11317

If the pNext chain specifies a descriptor mapping using VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_DATA_EXT, the sum of mapped structure size and shaderRecordDataOffset used in the mapping must not be larger than maxShaderGroupStride

VUID-VkPipelineShaderStageCreateInfo-pNext-11318

If the pNext chain specifies a descriptor mapping using VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_ADDRESS_EXT or VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_ADDRESS_EXT, the mapped resource in the shader must be one of:

  • A variable with a structure type decorated with Block in the Uniform Storage Class
  • A variable with a structure type decorated with BufferBlock in the Uniform Storage Class
  • A variable with a structure type decorated with Block in the StorageBuffer Storage Class
  • A OpTypeAccelerationStructureKHR variable
  • A OpTypeAccelerationStructureNV variable

VUID-VkPipelineShaderStageCreateInfo-pNext-11378

If the pNext chain specifies a descriptor mapping using VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_ADDRESS_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_ADDRESS_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_INDIRECT_ADDRESS_EXT, the OpArrayLength or OpUntypedArrayLengthKHR instruction must not be used on that resource

VUID-VkPipelineShaderStageCreateInfo-pNext-11399

If the pNext chain specifies a descriptor mapping using VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_CONSTANT_OFFSET_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_SHADER_RECORD_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, and the mapped resource declaration is an array, the pEmbeddedSampler member of the corresponding mapping structure must be NULL

VUID-VkPipelineShaderStageCreateInfo-stage-00704

If the geometryShader feature is not enabled, stage must not be VK_SHADER_STAGE_GEOMETRY_BIT

VUID-VkPipelineShaderStageCreateInfo-stage-00705

If the tessellationShader feature is not enabled, stage must not be VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT

VUID-VkPipelineShaderStageCreateInfo-stage-02091

If the meshShaders feature is not enabled, stage must not be VK_SHADER_STAGE_MESH_BIT_EXT

VUID-VkPipelineShaderStageCreateInfo-stage-02092

If the taskShaders feature is not enabled, stage must not be VK_SHADER_STAGE_TASK_BIT_EXT

VUID-VkPipelineShaderStageCreateInfo-clustercullingShader-07813

If the clustercullingShader feature is not enabled, stage must not be VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI

VUID-VkPipelineShaderStageCreateInfo-stage-00706

stage must not be VK_SHADER_STAGE_ALL_GRAPHICS, or VK_SHADER_STAGE_ALL

VUID-VkPipelineShaderStageCreateInfo-pName-00707

pName must be the name of an OpEntryPoint in module with an execution model that matches stage

VUID-VkPipelineShaderStageCreateInfo-maxClipDistances-00708

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

VUID-VkPipelineShaderStageCreateInfo-maxCullDistances-00709

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

VUID-VkPipelineShaderStageCreateInfo-maxCombinedClipAndCullDistances-00710

If the identified entry point includes variables in its interface that are declared with the ClipDistance BuiltIn decoration and variables in its interface that are declared with the CullDistance

BuiltIn decoration, those variables must not have array sizes which sum to more than VkPhysicalDeviceLimits::maxCombinedClipAndCullDistances

VUID-VkPipelineShaderStageCreateInfo-maxSampleMaskWords-00711

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

VUID-VkPipelineShaderStageCreateInfo-stage-00713

If stage is VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or VK_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

VUID-VkPipelineShaderStageCreateInfo-stage-00714

If stage is VK_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

VUID-VkPipelineShaderStageCreateInfo-stage-00715

If stage is VK_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

VUID-VkPipelineShaderStageCreateInfo-stage-02596

If stage is either VK_SHADER_STAGE_VERTEX_BIT, VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or VK_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

VUID-VkPipelineShaderStageCreateInfo-stage-02597

If stage is either VK_SHADER_STAGE_VERTEX_BIT, VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or VK_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

VUID-VkPipelineShaderStageCreateInfo-stage-06685

If stage is VK_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

VUID-VkPipelineShaderStageCreateInfo-stage-06686

If stage is VK_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

VUID-VkPipelineShaderStageCreateInfo-flags-02784

If flags has the VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set, the subgroupSizeControl feature must be enabled

VUID-VkPipelineShaderStageCreateInfo-flags-02785

If flags has the VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT flag set, the computeFullSubgroups feature must be enabled

VUID-VkPipelineShaderStageCreateInfo-flags-08988

If flags includes VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT, stage must be one of VK_SHADER_STAGE_MESH_BIT_EXT, VK_SHADER_STAGE_TASK_BIT_EXT, or VK_SHADER_STAGE_COMPUTE_BIT

VUID-VkPipelineShaderStageCreateInfo-pNext-02754

If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, flags must not have the VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set

VUID-VkPipelineShaderStageCreateInfo-pNext-02755

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

VUID-VkPipelineShaderStageCreateInfo-pNext-02756

If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain and stage is VK_SHADER_STAGE_COMPUTE_BIT, VK_SHADER_STAGE_MESH_BIT_EXT, or VK_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

VUID-VkPipelineShaderStageCreateInfo-pNext-02757

If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, and flags has the VK_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

VUID-VkPipelineShaderStageCreateInfo-flags-02758

If flags has both the VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT and VK_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

VUID-VkPipelineShaderStageCreateInfo-flags-02759

If flags has the VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT flag set and flags does not have the VK_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

VUID-VkPipelineShaderStageCreateInfo-module-08987

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 the effective subgroup size

VUID-VkPipelineShaderStageCreateInfo-module-10169

If module uses the OpTypeCooperativeMatrixKHR instruction with a Scope equal to Workgroup, then the local workgroup size in the X dimension of the pipeline must be a multiple of the effective subgroup size and the total local workgroup size must be a power of two multiple of the effective subgroup size and must be less than or equal to cooperativeMatrixWorkgroupScopeMaxWorkgroupSize

VUID-VkPipelineShaderStageCreateInfo-stage-08771

If a shader module identifier is not specified for this stage, module must be a valid VkShaderModule , or the pNext chain of the parent Vk*CreateInfo structure must set VkPipelineBinaryInfoKHR::binaryCount to a value greater than 0, if none of the following features are enabled:

VUID-VkPipelineShaderStageCreateInfo-stage-06845

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 , or the pNext chain of the parent Vk*CreateInfo structure must set VkPipelineBinaryInfoKHR::binaryCount to a value greater than 0,

VUID-VkPipelineShaderStageCreateInfo-stage-06844

If a shader module identifier is specified for this stage, the pNext chain must not include a VkShaderModuleCreateInfo structure

VUID-VkPipelineShaderStageCreateInfo-stage-06848

If a shader module identifier is specified for this stage, module must be VK_NULL_HANDLE

VUID-VkPipelineShaderStageCreateInfo-pSpecializationInfo-06849

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)

VUID-VkPipelineShaderStageCreateInfo-sType-sType

sType must be VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO

VUID-VkPipelineShaderStageCreateInfo-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 VkDebugUtilsObjectNameInfoEXT, VkPipelineRobustnessCreateInfo, VkPipelineShaderStageModuleIdentifierCreateInfoEXT, VkPipelineShaderStageNodeCreateInfoAMDX, VkPipelineShaderStageRequiredSubgroupSizeCreateInfo, VkShaderDescriptorSetAndBindingMappingInfoEXT, VkShaderModuleCreateInfo, or VkShaderModuleValidationCacheCreateInfoEXT

VUID-VkPipelineShaderStageCreateInfo-sType-unique

The sType value of each structure in the pNext chain must be unique

VUID-VkPipelineShaderStageCreateInfo-flags-parameter

flags must be a valid combination of VkPipelineShaderStageCreateFlagBits values

VUID-VkPipelineShaderStageCreateInfo-stage-parameter

stage must be a valid VkShaderStageFlagBits value

VUID-VkPipelineShaderStageCreateInfo-module-parameter

If module is not VK_NULL_HANDLE, module must be a valid VkShaderModule handle

VUID-VkPipelineShaderStageCreateInfo-pName-parameter

pName must be a null-terminated UTF-8 string

VUID-VkPipelineShaderStageCreateInfo-pSpecializationInfo-parameter

If pSpecializationInfo is not NULL, pSpecializationInfo must be a valid pointer to a valid VkSpecializationInfo structure