VkPipelineShaderStageCreateInfo(3)

# VkPipelineShaderStageCreateInfo(3) Manual Page

## Name

VkPipelineShaderStageCreateInfo - Structure specifying parameters of a newly created pipeline shader stage

Loading… please wait.

## C Specification

The `VkPipelineShaderStageCreateInfo` structure is defined as:

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

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

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

## Description

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

| Note 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-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 `subgroupSize`.

- VUID-VkPipelineShaderStageCreateInfo-stage-08771
  If a shader module identifier is not specified for this `stage`, `module` must be a valid VkShaderModule if none of the following features are enabled:

  - `graphicsPipelineLibrary`

  - `maintenance5`

- 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

- VUID-VkPipelineShaderStageCreateInfo-stage-06844
  If a shader module identifier is specified for this `stage`, a VkShaderModuleCreateInfo structure must not be present in the `pNext` chain

- 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, VkPipelineRobustnessCreateInfoEXT, VkPipelineShaderStageModuleIdentifierCreateInfoEXT, VkPipelineShaderStageNodeCreateInfoAMDX, VkPipelineShaderStageRequiredSubgroupSizeCreateInfo, VkShaderModuleCreateInfo, or VkShaderModuleValidationCacheCreateInfoEXT

- VUID-VkPipelineShaderStageCreateInfo-sType-unique
  The `sType` value of each struct 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

## See Also

VK_VERSION_1_0, VkComputePipelineCreateInfo, VkExecutionGraphPipelineCreateInfoAMDX, VkGraphicsPipelineCreateInfo, VkGraphicsShaderGroupCreateInfoNV, VkPipelineShaderStageCreateFlags, VkRayTracingPipelineCreateInfoKHR, VkRayTracingPipelineCreateInfoNV, VkShaderModule, VkShaderStageFlagBits, VkSpecializationInfo, VkStructureType

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

## Copyright

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0