Vulkan Logo

    10. Pipelines

    The following figure shows a block diagram of the Vulkan pipelines. Some Vulkan commands specify geometric objects to be drawn or computational work to be performed, while others specify state controlling how objects are handled by the various pipeline stages, or control data transfer between memory organized as images and buffers. Commands are effectively sent through a processing pipeline, either a graphics pipeline, or a compute pipeline.

    The first stage of the graphics pipeline (Input Assembler) assembles vertices to form geometric primitives such as points, lines, and triangles, based on a requested primitive topology. In the next stage (Vertex Shader) vertices can be transformed, computing positions and attributes for each vertex. If tessellation and/or geometry shaders are supported, they can then generate multiple primitives from a single input primitive, possibly changing the primitive topology or generating additional attribute data in the process.

    The final resulting primitives are clipped to a clip volume in preparation for the next stage, Rasterization. The rasterizer produces a series of fragments associated with a region of the framebuffer, from a two-dimensional description of a point, line segment, or triangle. These fragments are processed by fragment operations to determine whether generated values will be written to the framebuffer. Fragment shading determines the values to be written to the framebuffer attachments. Framebuffer operations then read and write the color and depth/stencil attachments of the framebuffer for a given subpass of a render pass instance. The attachments can be used as input attachments in the fragment shader in a later subpass of the same render pass.

    The compute pipeline is a separate pipeline from the graphics pipeline, which operates on one-, two-, or three-dimensional workgroups which can read from and write to buffer and image memory.

    This ordering is meant only as a tool for describing Vulkan, not as a strict rule of how Vulkan is implemented, and we present it only as a means to organize the various operations of the pipelines. Actual ordering guarantees between pipeline stages are explained in detail in the synchronization chapter.

    image/svg+xml Vertex Shader Draw Input Assembler Tessellation Control Shader Tessellation Primitive Generator Tessellation Evaluation Shader Rasterization Indirect Buffer Descriptor Sets Legend Geometry Shader Vertex Post-Processing Early Per-Fragment Tests Fragment Shader Late Per-Fragment Tests Blending Index Buffer Vertex Buffers Push Constants Uniform Buffers Uniform Texel Buffers Sampled Images Storage Buffers Storage Texel Buffers Storage Images Compute Shader Dispatch Depth/Stencil Attachments Input Attachments Color Attachments Fixed Function Stage Shader Stage Resource
    Figure 2. Block diagram of the Vulkan pipeline

    Each pipeline is controlled by a monolithic object created from a description of all of the shader stages and any relevant fixed-function stages. Linking the whole pipeline together allows the optimization of shaders based on their input/outputs and eliminates expensive draw time state validation.

    A pipeline object is bound to the current state using vkCmdBindPipeline. Any pipeline object state that is specified as dynamic is not applied to the current state when the pipeline object is bound, but is instead set by dynamic state setting commands.

    No state, including dynamic state, is inherited from one command buffer to another.

    Compute, and graphics pipelines are each represented by VkPipeline handles:

    // Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipeline)

    10.1. Multiple Pipeline Creation

    Multiple pipelines can be created in a single call by commands such as vkCreateComputePipelines, and vkCreateGraphicsPipelines.

    The creation commands are passed an array pCreateInfos of Vk*PipelineCreateInfo structures specifying parameters of each pipeline to be created, and return a corresponding array of handles in pPipelines. Each element index i of pPipelines is created based on the corresponding element i of pCreateInfos.

    Applications can group together similar pipelines to be created in a single call, and implementations are encouraged to look for reuse opportunities when creating a group.

    When attempting to create many pipelines in a single command, it is possible that creation may fail for a subset of them. In this case, the corresponding elements of pPipelines will be set to VK_NULL_HANDLE. If creation fails for a pipeline despite valid arguments (for example, due to out of memory errors), the VkResult code returned by the pipeline creation command will indicate why. The implementation will attempt to create all pipelines, and only return VK_NULL_HANDLE values for those that actually failed.

    If creation fails for a pipeline that has the VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT set in its Vk*PipelineCreateInfo, pipelines at an index in the pPipelines array greater than or equal to that of the failing pipeline will be set to VK_NULL_HANDLE.

    If creation fails for multiple pipelines, the returned VkResult must be the return value of any one of the pipelines which did not succeed. An application can reliably clean up from a failed call by iterating over the pPipelines array and destroying every element that is not VK_NULL_HANDLE.

    If the entire command fails and no pipelines are created, all elements of pPipelines will be set to VK_NULL_HANDLE.

    10.2. Compute Pipelines

    Compute pipelines consist of a single static compute shader stage and the pipeline layout.

    The compute pipeline represents a compute shader and is created by calling vkCreateComputePipelines with module and pName selecting an entry point from a shader module, where that entry point defines a valid compute shader, in the VkPipelineShaderStageCreateInfo structure contained within the VkComputePipelineCreateInfo structure.

    To create compute pipelines, call:

    // Provided by VK_VERSION_1_0
VkResult vkCreateComputePipelines(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    uint32_t                                    createInfoCount,
    const VkComputePipelineCreateInfo*          pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkPipeline*                                 pPipelines);

    • device is the logical device that creates the compute pipelines.

    • pipelineCache is either VK_NULL_HANDLE, indicating that pipeline caching is disabled; or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command.

    • createInfoCount is the length of the pCreateInfos and pPipelines arrays.

    • pCreateInfos is a pointer to an array of VkComputePipelineCreateInfo structures.

    • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

    • pPipelines is a pointer to an array of VkPipeline handles in which the resulting compute pipeline objects are returned.

    Pipelines are created and returned as described for Multiple Pipeline Creation.

    Valid Usage

    • VUID-vkCreateComputePipelines-flags-00695
      If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element

    • VUID-vkCreateComputePipelines-flags-00696
      If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set

    • VUID-vkCreateComputePipelines-pipelineCache-02873
      If pipelineCache was created with VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, host access to pipelineCache must be externally synchronized

    Valid Usage (Implicit)

    • VUID-vkCreateComputePipelines-device-parameter
      device must be a valid VkDevice handle

    • VUID-vkCreateComputePipelines-pipelineCache-parameter
      If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

    • VUID-vkCreateComputePipelines-pCreateInfos-parameter
      pCreateInfos must be a valid pointer to an array of createInfoCount valid VkComputePipelineCreateInfo structures

    • VUID-vkCreateComputePipelines-pAllocator-parameter
      If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

    • VUID-vkCreateComputePipelines-pPipelines-parameter
      pPipelines must be a valid pointer to an array of createInfoCount VkPipeline handles

    • VUID-vkCreateComputePipelines-createInfoCount-arraylength
      createInfoCount must be greater than 0

    • VUID-vkCreateComputePipelines-pipelineCache-parent
      If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

    Return Codes
    Success

    • VK_SUCCESS

    Failure

    • VK_ERROR_OUT_OF_HOST_MEMORY

    • VK_ERROR_OUT_OF_DEVICE_MEMORY

    The VkComputePipelineCreateInfo structure is defined as:

    // Provided by VK_VERSION_1_0
typedef struct VkComputePipelineCreateInfo {
    VkStructureType                    sType;
    const void*                        pNext;
    VkPipelineCreateFlags              flags;
    VkPipelineShaderStageCreateInfo    stage;
    VkPipelineLayout                   layout;
    VkPipeline                         basePipelineHandle;
    int32_t                            basePipelineIndex;
} VkComputePipelineCreateInfo;

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

    • stage is a VkPipelineShaderStageCreateInfo structure describing the compute shader.

    • layout is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline.

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

    Valid Usage

    • VUID-VkComputePipelineCreateInfo-None-09497
      flags must be a valid combination of VkPipelineCreateFlagBits values

    • VUID-VkComputePipelineCreateInfo-flags-07984
      If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid compute VkPipeline handle

    • VUID-VkComputePipelineCreateInfo-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-VkComputePipelineCreateInfo-flags-07986
      If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, basePipelineIndex must be -1 or basePipelineHandle must be VK_NULL_HANDLE

    • VUID-VkComputePipelineCreateInfo-layout-07987
      If a push constant block is declared in a shader, a push constant range in layout must match both the shader stage and range

    • VUID-VkComputePipelineCreateInfo-layout-07988
      If a resource variables is declared in a shader, a descriptor slot in layout must match the shader stage

    • VUID-VkComputePipelineCreateInfo-layout-07990
      If a resource variables is declared in a shader, a descriptor slot in layout must match the descriptor type

    • VUID-VkComputePipelineCreateInfo-layout-07991
      If a resource variables is declared in a shader as an array, a descriptor slot in layout must match the descriptor count

    • VUID-VkComputePipelineCreateInfo-pipelineCreationCacheControl-02875
      If the pipelineCreationCacheControl feature is not enabled, flags must not include VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT or VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT

    • VUID-VkComputePipelineCreateInfo-stage-00701
      The stage member of stage must be VK_SHADER_STAGE_COMPUTE_BIT

    • VUID-VkComputePipelineCreateInfo-stage-00702
      The shader code for the entry point identified by stage and the rest of the state identified by this structure must adhere to the pipeline linking rules described in the Shader Interfaces chapter

    • VUID-VkComputePipelineCreateInfo-layout-01687
      The number of resources in layout accessible to the compute shader stage must be less than or equal to VkPhysicalDeviceLimits::maxPerStageResources

    • VUID-VkComputePipelineCreateInfo-pipelineStageCreationFeedbackCount-06566
      If VkPipelineCreationFeedbackCreateInfo::pipelineStageCreationFeedbackCount is not 0, it must be 1

    Valid Usage (Implicit)

    • VUID-VkComputePipelineCreateInfo-sType-sType
      sType must be VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_CREATE_INFO

    • VUID-VkComputePipelineCreateInfo-pNext-pNext
      pNext must be NULL or a pointer to a valid instance of VkPipelineCreationFeedbackCreateInfo

    • VUID-VkComputePipelineCreateInfo-sType-unique
      The sType value of each struct in the pNext chain must be unique

    • VUID-VkComputePipelineCreateInfo-stage-parameter
      stage must be a valid VkPipelineShaderStageCreateInfo structure

    • VUID-VkComputePipelineCreateInfo-layout-parameter
      layout must be a valid VkPipelineLayout handle

    • VUID-VkComputePipelineCreateInfo-commonparent
      Both of basePipelineHandle, and layout that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

    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;

    The shader code used by the pipeline is defined by module.

    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-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-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 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, 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-stage-08771
      module must be a valid VkShaderModule

    • VUID-VkPipelineShaderStageCreateInfo-pSpecializationInfo-06849
      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 VkPipelineShaderStageRequiredSubgroupSizeCreateInfo or VkShaderModuleCreateInfo

    • 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

    // Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineShaderStageCreateFlags;

    VkPipelineShaderStageCreateFlags is a bitmask type for setting a mask of zero or more VkPipelineShaderStageCreateFlagBits.

    Possible values of the flags member of VkPipelineShaderStageCreateInfo specifying how a pipeline shader stage is created, are:

    // Provided by VK_VERSION_1_0
typedef enum VkPipelineShaderStageCreateFlagBits {
  // Provided by VK_VERSION_1_3
    VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT = 0x00000001,
  // Provided by VK_VERSION_1_3
    VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT = 0x00000002,
} VkPipelineShaderStageCreateFlagBits;

    • VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT specifies that the SubgroupSize may vary in the shader stage.

    • VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT specifies that the subgroup sizes must be launched with all invocations active in the compute stage.

    Note

    If VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT and VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT are specified and minSubgroupSize does not equal maxSubgroupSize and no required subgroup size is specified, then the only way to guarantee that the 'X' dimension of the local workgroup size is a multiple of SubgroupSize is to make it a multiple of maxSubgroupSize. Under these conditions, you are guaranteed full subgroups but not any particular subgroup size.

    Bits which can be set by commands and structures, specifying one or more shader stages, are:

    // Provided by VK_VERSION_1_0
typedef enum VkShaderStageFlagBits {
    VK_SHADER_STAGE_VERTEX_BIT = 0x00000001,
    VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT = 0x00000002,
    VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT = 0x00000004,
    VK_SHADER_STAGE_GEOMETRY_BIT = 0x00000008,
    VK_SHADER_STAGE_FRAGMENT_BIT = 0x00000010,
    VK_SHADER_STAGE_COMPUTE_BIT = 0x00000020,
    VK_SHADER_STAGE_ALL_GRAPHICS = 0x0000001F,
    VK_SHADER_STAGE_ALL = 0x7FFFFFFF,
} VkShaderStageFlagBits;

    • VK_SHADER_STAGE_VERTEX_BIT specifies the vertex stage.

    • VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT specifies the tessellation control stage.

    • VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT specifies the tessellation evaluation stage.

    • VK_SHADER_STAGE_GEOMETRY_BIT specifies the geometry stage.

    • VK_SHADER_STAGE_FRAGMENT_BIT specifies the fragment stage.

    • VK_SHADER_STAGE_COMPUTE_BIT specifies the compute stage.

    • VK_SHADER_STAGE_ALL_GRAPHICS is a combination of bits used as shorthand to specify all graphics stages defined above (excluding the compute stage).

    • VK_SHADER_STAGE_ALL is a combination of bits used as shorthand to specify all shader stages supported by the device, including all additional stages which are introduced by extensions.

    Note

    VK_SHADER_STAGE_ALL_GRAPHICS only includes the original five graphics stages included in Vulkan 1.0, and not any stages added by extensions. Thus, it may not have the desired effect in all cases.

    		 
    // Provided by VK_VERSION_1_0
typedef VkFlags VkShaderStageFlags;

    VkShaderStageFlags is a bitmask type for setting a mask of zero or more VkShaderStageFlagBits.

    The VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is defined as:

    // Provided by VK_VERSION_1_3
typedef struct VkPipelineShaderStageRequiredSubgroupSizeCreateInfo {
    VkStructureType    sType;
    void*              pNext;
    uint32_t           requiredSubgroupSize;
} VkPipelineShaderStageRequiredSubgroupSizeCreateInfo;

    • sType is a VkStructureType value identifying this structure.

    • pNext is NULL or a pointer to a structure extending this structure.

    • requiredSubgroupSize is an unsigned integer value specifying the required subgroup size for the newly created pipeline shader stage.

    If a VkPipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain of VkPipelineShaderStageCreateInfo, it specifies that the pipeline shader stage being compiled has a required subgroup size.

    Valid Usage

    • VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfo-requiredSubgroupSize-02760
      requiredSubgroupSize must be a power-of-two integer

    • VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfo-requiredSubgroupSize-02761
      requiredSubgroupSize must be greater or equal to minSubgroupSize

    • VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfo-requiredSubgroupSize-02762
      requiredSubgroupSize must be less than or equal to maxSubgroupSize

    Valid Usage (Implicit)

    • VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfo-sType-sType
      sType must be VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO

    10.3. Graphics Pipelines

    Graphics pipelines consist of multiple shader stages, multiple fixed-function pipeline stages, and a pipeline layout.

    To create graphics pipelines, call:

    // Provided by VK_VERSION_1_0
VkResult vkCreateGraphicsPipelines(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    uint32_t                                    createInfoCount,
    const VkGraphicsPipelineCreateInfo*         pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkPipeline*                                 pPipelines);

    • device is the logical device that creates the graphics pipelines.

    • pipelineCache is either VK_NULL_HANDLE, indicating that pipeline caching is disabled; or the handle of a valid pipeline cache object, in which case use of that cache is enabled for the duration of the command.

    • createInfoCount is the length of the pCreateInfos and pPipelines arrays.

    • pCreateInfos is a pointer to an array of VkGraphicsPipelineCreateInfo structures.

    • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

    • pPipelines is a pointer to an array of VkPipeline handles in which the resulting graphics pipeline objects are returned.

    The VkGraphicsPipelineCreateInfo structure includes an array of VkPipelineShaderStageCreateInfo structures for each of the desired active shader stages, as well as creation information for all relevant fixed-function stages, and a pipeline layout.

    Pipelines are created and returned as described for Multiple Pipeline Creation.

    Valid Usage

    • VUID-vkCreateGraphicsPipelines-flags-00720
      If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element

    • VUID-vkCreateGraphicsPipelines-flags-00721
      If the flags member of any element of pCreateInfos contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set

    • VUID-vkCreateGraphicsPipelines-pipelineCache-02876
      If pipelineCache was created with VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, host access to pipelineCache must be externally synchronized

    Note

    An implicit cache may be provided by the implementation or a layer. For this reason, it is still valid to set VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT on flags for any element of pCreateInfos while passing VK_NULL_HANDLE for pipelineCache.
    Valid Usage (Implicit)

    • VUID-vkCreateGraphicsPipelines-device-parameter
      device must be a valid VkDevice handle

    • VUID-vkCreateGraphicsPipelines-pipelineCache-parameter
      If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

    • VUID-vkCreateGraphicsPipelines-pCreateInfos-parameter
      pCreateInfos must be a valid pointer to an array of createInfoCount valid VkGraphicsPipelineCreateInfo structures

    • VUID-vkCreateGraphicsPipelines-pAllocator-parameter
      If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

    • VUID-vkCreateGraphicsPipelines-pPipelines-parameter
      pPipelines must be a valid pointer to an array of createInfoCount VkPipeline handles

    • VUID-vkCreateGraphicsPipelines-createInfoCount-arraylength
      createInfoCount must be greater than 0

    • VUID-vkCreateGraphicsPipelines-pipelineCache-parent
      If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

    Return Codes
    Success

    • VK_SUCCESS

    Failure

    • VK_ERROR_OUT_OF_HOST_MEMORY

    • VK_ERROR_OUT_OF_DEVICE_MEMORY

    The VkGraphicsPipelineCreateInfo structure is defined as:

    // Provided by VK_VERSION_1_0
typedef struct VkGraphicsPipelineCreateInfo {
    VkStructureType                                  sType;
    const void*                                      pNext;
    VkPipelineCreateFlags                            flags;
    uint32_t                                         stageCount;
    const VkPipelineShaderStageCreateInfo*           pStages;
    const VkPipelineVertexInputStateCreateInfo*      pVertexInputState;
    const VkPipelineInputAssemblyStateCreateInfo*    pInputAssemblyState;
    const VkPipelineTessellationStateCreateInfo*     pTessellationState;
    const VkPipelineViewportStateCreateInfo*         pViewportState;
    const VkPipelineRasterizationStateCreateInfo*    pRasterizationState;
    const VkPipelineMultisampleStateCreateInfo*      pMultisampleState;
    const VkPipelineDepthStencilStateCreateInfo*     pDepthStencilState;
    const VkPipelineColorBlendStateCreateInfo*       pColorBlendState;
    const VkPipelineDynamicStateCreateInfo*          pDynamicState;
    VkPipelineLayout                                 layout;
    VkRenderPass                                     renderPass;
    uint32_t                                         subpass;
    VkPipeline                                       basePipelineHandle;
    int32_t                                          basePipelineIndex;
} VkGraphicsPipelineCreateInfo;

    • 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 graphics pipeline.

    • pVertexInputState is a pointer to a VkPipelineVertexInputStateCreateInfo structure.

    • pInputAssemblyState is a pointer to a VkPipelineInputAssemblyStateCreateInfo structure which determines input assembly behavior for vertex shading, as described in Drawing Commands.

    • pTessellationState is a pointer to a VkPipelineTessellationStateCreateInfo structure defining tessellation state used by tessellation shaders.

    • pViewportState is a pointer to a VkPipelineViewportStateCreateInfo structure defining viewport state used when rasterization is enabled.

    • pRasterizationState is a pointer to a VkPipelineRasterizationStateCreateInfo structure defining rasterization state.

    • pMultisampleState is a pointer to a VkPipelineMultisampleStateCreateInfo structure defining multisample state used when rasterization is enabled.

    • pDepthStencilState is a pointer to a VkPipelineDepthStencilStateCreateInfo structure defining depth/stencil state used when rasterization is enabled for depth or stencil attachments accessed during rendering.

    • pColorBlendState is a pointer to a VkPipelineColorBlendStateCreateInfo structure defining color blend state used when rasterization is enabled for any color attachments accessed during rendering.

    • pDynamicState is a pointer to a VkPipelineDynamicStateCreateInfo structure defining 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.

    • renderPass is a handle to a render pass object describing the environment in which the pipeline will be used. The pipeline must only be used with a render pass instance compatible with the one provided. See Render Pass Compatibility for more information.

    • subpass is the index of the subpass in the render pass where this pipeline will be used.

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

    The state required for a graphics pipeline is divided into vertex input state, pre-rasterization shader state, fragment shader state, and fragment output state.

    Vertex Input State

    Vertex input state is defined by:

    This state must be specified to create a complete graphics pipeline.

    Pre-Rasterization Shader State

    Pre-rasterization shader state is defined by:

    This state must be specified to create a complete graphics pipeline.

    Fragment Shader State

    Fragment shader state is defined by:

    If rasterizerDiscardEnable is set to VK_FALSE or VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE is used, this state must be specified to create a complete graphics pipeline.

    Fragment Output State

    Fragment output state is defined by:

    If rasterizerDiscardEnable is set to VK_FALSE or VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE is used, this state must be specified to create a complete graphics pipeline.

    Dynamic State

    Dynamic state values set via pDynamicState must be ignored if the state they correspond to is not otherwise statically set by one of the state subsets used to create the pipeline. For example, if a pipeline only included pre-rasterization shader state, then any dynamic state value corresponding to depth or stencil testing has no effect.

    Complete Graphics Pipelines

    A complete graphics pipeline always includes pre-rasterization shader state, with other subsets included depending on that state as specified in the above sections.

    Valid Usage

    • VUID-VkGraphicsPipelineCreateInfo-None-09497
      flags must be a valid combination of VkPipelineCreateFlagBits values

    • VUID-VkGraphicsPipelineCreateInfo-flags-07984
      If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid graphics VkPipeline handle

    • VUID-VkGraphicsPipelineCreateInfo-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-VkGraphicsPipelineCreateInfo-flags-07986
      If flags contains the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, basePipelineIndex must be -1 or basePipelineHandle must be VK_NULL_HANDLE

    • VUID-VkGraphicsPipelineCreateInfo-layout-07987
      If a push constant block is declared in a shader, a push constant range in layout must match both the shader stage and range

    • VUID-VkGraphicsPipelineCreateInfo-layout-07988
      If a resource variables is declared in a shader, a descriptor slot in layout must match the shader stage

    • VUID-VkGraphicsPipelineCreateInfo-layout-07990
      If a resource variables is declared in a shader, a descriptor slot in layout must match the descriptor type

    • VUID-VkGraphicsPipelineCreateInfo-layout-07991
      If a resource variables is declared in a shader as an array, a descriptor slot in layout must match the descriptor count

    • VUID-VkGraphicsPipelineCreateInfo-stage-02096
      If the pipeline requires pre-rasterization shader state the stage member of one element of pStages must be VK_SHADER_STAGE_VERTEX_BIT

    • VUID-VkGraphicsPipelineCreateInfo-pStages-00729
      If the pipeline requires pre-rasterization shader state and pStages includes a tessellation control shader stage, it must include a tessellation evaluation shader stage

    • VUID-VkGraphicsPipelineCreateInfo-pStages-00730
      If the pipeline requires pre-rasterization shader state and pStages includes a tessellation evaluation shader stage, it must include a tessellation control shader stage

    • VUID-VkGraphicsPipelineCreateInfo-pStages-09022
      If the pipeline requires pre-rasterization shader state and pStages includes a tessellation control shader stage, pTessellationState must be a valid pointer to a valid VkPipelineTessellationStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-pStages-00732
      If the pipeline requires pre-rasterization shader state and pStages includes tessellation shader stages, the shader code of at least one stage must contain an OpExecutionMode instruction specifying the type of subdivision in the pipeline

    • VUID-VkGraphicsPipelineCreateInfo-pStages-00733
      If the pipeline requires pre-rasterization shader state and pStages includes tessellation shader stages, and the shader code of both stages contain an OpExecutionMode instruction specifying the type of subdivision in the pipeline, they must both specify the same subdivision mode

    • VUID-VkGraphicsPipelineCreateInfo-pStages-00734
      If the pipeline requires pre-rasterization shader state and pStages includes tessellation shader stages, the shader code of at least one stage must contain an OpExecutionMode instruction specifying the output patch size in the pipeline

    • VUID-VkGraphicsPipelineCreateInfo-pStages-00735
      If the pipeline requires pre-rasterization shader state and pStages includes tessellation shader stages, and the shader code of both contain an OpExecutionMode instruction specifying the out patch size in the pipeline, they must both specify the same patch size

    • VUID-VkGraphicsPipelineCreateInfo-pStages-08888
      If the pipeline is being created with pre-rasterization shader state and vertex input state and pStages includes tessellation shader stages, the topology member of pInputAssembly must be VK_PRIMITIVE_TOPOLOGY_PATCH_LIST

    • VUID-VkGraphicsPipelineCreateInfo-topology-08889
      If the pipeline is being created with pre-rasterization shader state and vertex input state and the topology member of pInputAssembly is VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, then pStages must include tessellation shader stages

    • VUID-VkGraphicsPipelineCreateInfo-TessellationEvaluation-07723
      If the pipeline is being created with a TessellationEvaluation Execution Model, no Geometry Execution Model, uses the PointMode Execution Mode, and shaderTessellationAndGeometryPointSize is enabled, a PointSize decorated variable must be written to

    • VUID-VkGraphicsPipelineCreateInfo-topology-08773
      If the pipeline is being created with a Vertex Execution Model and no TessellationEvaluation or Geometry Execution Model, and the topology member of pInputAssembly is VK_PRIMITIVE_TOPOLOGY_POINT_LIST, a PointSize decorated variable must be written to

    • VUID-VkGraphicsPipelineCreateInfo-TessellationEvaluation-07724
      If the pipeline is being created with a TessellationEvaluation Execution Model, no Geometry Execution Model, uses the PointMode Execution Mode, and shaderTessellationAndGeometryPointSize is not enabled, a PointSize decorated variable must not be written to

    • VUID-VkGraphicsPipelineCreateInfo-shaderTessellationAndGeometryPointSize-08776
      If the pipeline is being created with a Geometry Execution Model, uses the OutputPoints Execution Mode, and shaderTessellationAndGeometryPointSize is enabled, a PointSize decorated variable must be written to for every vertex emitted

    • VUID-VkGraphicsPipelineCreateInfo-Geometry-07726
      If the pipeline is being created with a Geometry Execution Model, uses the OutputPoints Execution Mode, and shaderTessellationAndGeometryPointSize is not enabled, a PointSize decorated variable must not be written to

    • VUID-VkGraphicsPipelineCreateInfo-pStages-00738
      If the pipeline requires pre-rasterization shader state and pStages includes a geometry shader stage, and does not include any tessellation shader stages, its shader code must contain an OpExecutionMode instruction specifying an input primitive type that is compatible with the primitive topology specified in pInputAssembly

    • VUID-VkGraphicsPipelineCreateInfo-pStages-00739
      If the pipeline requires pre-rasterization shader state and pStages includes a geometry shader stage, and also includes tessellation shader stages, its shader code must contain an OpExecutionMode instruction specifying an input primitive type that is compatible with the primitive topology that is output by the tessellation stages

    • VUID-VkGraphicsPipelineCreateInfo-pStages-00740
      If the pipeline requires pre-rasterization shader state and fragment shader state, it includes both a fragment shader and a geometry shader, and the fragment shader code reads from an input variable that is decorated with PrimitiveId, then the geometry shader code must write to a matching output variable, decorated with PrimitiveId, in all execution paths

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06038
      If renderPass is not VK_NULL_HANDLE and the pipeline is being created with fragment shader state the fragment shader must not read from any input attachment that is defined as VK_ATTACHMENT_UNUSED in subpass

    • VUID-VkGraphicsPipelineCreateInfo-pStages-00742
      If the pipeline requires pre-rasterization shader state and multiple pre-rasterization shader stages are included in pStages, the shader code for the entry points identified by those 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-VkGraphicsPipelineCreateInfo-None-04889
      If the pipeline requires pre-rasterization shader state and fragment shader state, the fragment shader and last pre-rasterization shader stage and any relevant state must adhere to the pipeline linking rules described in the Shader Interfaces chapter

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06041
      If renderPass is not VK_NULL_HANDLE, and the pipeline is being created with fragment output interface state, then for each color attachment in the subpass, if the potential format features of the format of the corresponding attachment description do not contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT, then the blendEnable member of the corresponding element of the pAttachments member of pColorBlendState must be VK_FALSE

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-07609
      If renderPass is not VK_NULL_HANDLE, the pipeline is being created with fragment output interface state, the pColorBlendState pointer is not NULL, the attachmentCount member of pColorBlendState is not ignored, and the subpass uses color attachments, the attachmentCount member of pColorBlendState must be equal to the colorAttachmentCount used to create subpass

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04130
      If the pipeline requires pre-rasterization shader state, and pViewportState->pViewports is not dynamic, then pViewportState->pViewports must be a valid pointer to an array of pViewportState->viewportCount valid VkViewport structures

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04131
      If the pipeline requires pre-rasterization shader state, and pViewportState->pScissors is not dynamic, then pViewportState->pScissors must be a valid pointer to an array of pViewportState->scissorCount VkRect2D structures

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00749
      If the pipeline requires pre-rasterization shader state, and the wideLines feature is not enabled, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_LINE_WIDTH, the lineWidth member of pRasterizationState must be 1.0

    • VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-09024
      If the pipeline requires pre-rasterization shader state, and the VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE dynamic state is enabled or the rasterizerDiscardEnable member of pRasterizationState is VK_FALSE, pViewportState must be a valid pointer to a valid VkPipelineViewportStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-pMultisampleState-09026
      If the pipeline requires fragment output interface state, pMultisampleState must be a valid pointer to a valid VkPipelineMultisampleStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-pMultisampleState-09027
      If pMultisampleState is not NULL it must be a valid pointer to a valid VkPipelineMultisampleStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-alphaToCoverageEnable-08891
      If the pipeline is being created with fragment shader state, the VkPipelineMultisampleStateCreateInfo::alphaToCoverageEnable is not ignored and is VK_TRUE, then the Fragment Output Interface must contain a variable for the alpha Component word in Location 0 at Index 0

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-09028
      If renderPass is not VK_NULL_HANDLE, the pipeline is being created with fragment shader state, and subpass uses a depth/stencil attachment, pDepthStencilState must be a valid pointer to a valid VkPipelineDepthStencilStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-pDepthStencilState-09029
      If pDepthStencilState is not NULL it must be a valid pointer to a valid VkPipelineDepthStencilStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-09030
      If renderPass is not VK_NULL_HANDLE, the pipeline is being created with fragment output interface state, and subpass uses color attachments, pColorBlendState must be a valid pointer to a valid VkPipelineColorBlendStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00754
      If the pipeline requires pre-rasterization shader state, the depthBiasClamp feature is not enabled, no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_DEPTH_BIAS, and the depthBiasEnable member of pRasterizationState is VK_TRUE, the depthBiasClamp member of pRasterizationState must be 0.0

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-02510
      If the pipeline requires fragment shader state, and no element of the pDynamicStates member of pDynamicState is VK_DYNAMIC_STATE_DEPTH_BOUNDS, and the depthBoundsTestEnable member of pDepthStencilState is VK_TRUE, the minDepthBounds and maxDepthBounds members of pDepthStencilState must be between 0.0 and 1.0, inclusive

    • VUID-VkGraphicsPipelineCreateInfo-subpass-00758
      If the pipeline requires fragment output interface state, rasterizationSamples is not dynamic, and subpass does not use any color and/or depth/stencil attachments, then the rasterizationSamples member of pMultisampleState must follow the rules for a zero-attachment subpass

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06046
      If renderPass is not VK_NULL_HANDLE, subpass must be a valid subpass within renderPass

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06047
      If renderPass is not VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, subpass viewMask is not 0, and multiviewTessellationShader is not enabled, then pStages must not include tessellation shaders

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06048
      If renderPass is not VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, subpass viewMask is not 0, and multiviewGeometryShader is not enabled, then pStages must not include a geometry shader

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06050
      If renderPass is not VK_NULL_HANDLE and the pipeline is being created with pre-rasterization shader state, and subpass viewMask is not 0, then all of the shaders in the pipeline must not include variables decorated with the Layer built-in decoration in their interfaces

    • VUID-VkGraphicsPipelineCreateInfo-flags-00764
      flags must not contain the VK_PIPELINE_CREATE_DISPATCH_BASE flag

    • VUID-VkGraphicsPipelineCreateInfo-pStages-01565
      If the pipeline requires fragment shader state and an input attachment was referenced by an aspectMask at renderPass creation time, the fragment shader must only read from the aspects that were specified for that input attachment

    • VUID-VkGraphicsPipelineCreateInfo-layout-01688
      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-VkGraphicsPipelineCreateInfo-pStages-02097
      If the pipeline requires vertex input state, and pVertexInputState is not dynamic, then pVertexInputState must be a valid pointer to a valid VkPipelineVertexInputStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-Input-07904
      If the pipeline is being created with vertex input state and pVertexInputState is not dynamic, then all variables with the Input storage class decorated with Location in the Vertex Execution Model OpEntryPoint must contain a location in VkVertexInputAttributeDescription::location

    • VUID-VkGraphicsPipelineCreateInfo-Input-08733
      If the pipeline requires vertex input state and pVertexInputState is not dynamic, then the numeric type associated with all Input variables of the corresponding Location in the Vertex Execution Model OpEntryPoint must be the same as VkVertexInputAttributeDescription::format

    • VUID-VkGraphicsPipelineCreateInfo-pVertexInputState-08929
      If the pipeline is being created with vertex input state and pVertexInputState is not dynamic, and VkVertexInputAttributeDescription::format has a 64-bit component, then the scalar width associated with all Input variables of the corresponding Location in the Vertex Execution Model OpEntryPoint must be 64-bit

    • VUID-VkGraphicsPipelineCreateInfo-pVertexInputState-08930
      If the pipeline is being created with vertex input state and pVertexInputState is not dynamic, and the scalar width associated with a Location decorated Input variable in the Vertex Execution Model OpEntryPoint is 64-bit, then the corresponding VkVertexInputAttributeDescription::format must have a 64-bit component

    • VUID-VkGraphicsPipelineCreateInfo-pVertexInputState-09198
      If the pipeline is being created with vertex input state and pVertexInputState is not dynamic, and VkVertexInputAttributeDescription::format has a 64-bit component, then all Input variables at the corresponding Location in the Vertex Execution Model OpEntryPoint must not use components that are not present in the format

    • VUID-VkGraphicsPipelineCreateInfo-dynamicPrimitiveTopologyUnrestricted-09031
      If the pipeline requires vertex input state, pInputAssemblyState must be a valid pointer to a valid VkPipelineInputAssemblyStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-pInputAssemblyState-09032
      If pInputAssemblyState is not NULL it must be a valid pointer to a valid VkPipelineInputAssemblyStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03378
      If the value of VkApplicationInfo::apiVersion used to create the VkInstance is less than Version 1.3 there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_CULL_MODE, VK_DYNAMIC_STATE_FRONT_FACE, VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY, VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT, VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT, VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE, VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE, VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE, VK_DYNAMIC_STATE_DEPTH_COMPARE_OP, VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE, VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE, or VK_DYNAMIC_STATE_STENCIL_OP

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03379
      If the pipeline requires pre-rasterization shader state, and VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT is included in the pDynamicStates array then viewportCount must be zero

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03380
      If the pipeline requires pre-rasterization shader state, and VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT is included in the pDynamicStates array then scissorCount must be zero

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04132
      If the pipeline requires pre-rasterization shader state, and VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT is included in the pDynamicStates array then VK_DYNAMIC_STATE_VIEWPORT must not be present

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04133
      If the pipeline requires pre-rasterization shader state, and VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT is included in the pDynamicStates array then VK_DYNAMIC_STATE_SCISSOR must not be present

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04868
      If the value of VkApplicationInfo::apiVersion used to create the VkInstance is less than Version 1.3 there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE, VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE, or VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04869
      If the extendedDynamicState2LogicOp feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_LOGIC_OP_EXT

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04870
      If the extendedDynamicState2PatchControlPoints feature is not enabled, there must be no element of the pDynamicStates member of pDynamicState set to VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT

    • VUID-VkGraphicsPipelineCreateInfo-pipelineCreationCacheControl-02878
      If the pipelineCreationCacheControl feature is not enabled, flags must not include VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT or VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT

    • VUID-VkGraphicsPipelineCreateInfo-dynamicRendering-06576
      If the dynamicRendering feature is not enabled and the pipeline requires pre-rasterization shader state, fragment shader state, or fragment output interface state, renderPass must not be VK_NULL_HANDLE

    • VUID-VkGraphicsPipelineCreateInfo-multiview-06577
      If the multiview feature is not enabled, the pipeline requires pre-rasterization shader state, fragment shader state, or fragment output interface state, and renderPass is VK_NULL_HANDLE, VkPipelineRenderingCreateInfo::viewMask must be 0

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06578
      If the pipeline requires pre-rasterization shader state, fragment shader state, or fragment output interface state, and renderPass is VK_NULL_HANDLE, the index of the most significant bit in VkPipelineRenderingCreateInfo::viewMask must be less than maxMultiviewViewCount

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06579
      If the pipeline requires fragment output interface state, and renderPass is VK_NULL_HANDLE, and VkPipelineRenderingCreateInfo::colorAttachmentCount is not 0, VkPipelineRenderingCreateInfo::pColorAttachmentFormats must be a valid pointer to an array of colorAttachmentCount valid VkFormat values

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06580
      If the pipeline requires fragment output interface state, and renderPass is VK_NULL_HANDLE, each element of VkPipelineRenderingCreateInfo::pColorAttachmentFormats must be a valid VkFormat value

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06582
      If the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and any element of VkPipelineRenderingCreateInfo::pColorAttachmentFormats is not VK_FORMAT_UNDEFINED, that format must be a format with potential format features that include VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06583
      If the pipeline requires fragment output interface state, and renderPass is VK_NULL_HANDLE, VkPipelineRenderingCreateInfo::depthAttachmentFormat must be a valid VkFormat value

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06584
      If the pipeline requires fragment output interface state, and renderPass is VK_NULL_HANDLE, VkPipelineRenderingCreateInfo::stencilAttachmentFormat must be a valid VkFormat value

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06585
      If the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkPipelineRenderingCreateInfo::depthAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format with potential format features that include VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06586
      If the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkPipelineRenderingCreateInfo::stencilAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format with potential format features that include VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06587
      If the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkPipelineRenderingCreateInfo::depthAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format that includes a depth component

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06588
      If the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, and VkPipelineRenderingCreateInfo::stencilAttachmentFormat is not VK_FORMAT_UNDEFINED, it must be a format that includes a stencil component

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06589
      If the pipeline requires fragment output interface state, renderPass is VK_NULL_HANDLE, VkPipelineRenderingCreateInfo::depthAttachmentFormat is not VK_FORMAT_UNDEFINED, and VkPipelineRenderingCreateInfo::stencilAttachmentFormat is not VK_FORMAT_UNDEFINED, depthAttachmentFormat must equal stencilAttachmentFormat

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-09033
      If renderPass is VK_NULL_HANDLE, the pipeline is being created with fragment shader state and fragment output interface state, and either of VkPipelineRenderingCreateInfo::depthAttachmentFormat or VkPipelineRenderingCreateInfo::stencilAttachmentFormat are not VK_FORMAT_UNDEFINED, pDepthStencilState must be a valid pointer to a valid VkPipelineDepthStencilStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-pDepthStencilState-09034
      If pDepthStencilState is not NULL it must be a valid pointer to a valid VkPipelineDepthStencilStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-09037
      If renderPass is VK_NULL_HANDLE, the pipeline is being created with fragment output interface state, and any element of VkPipelineRenderingCreateInfo::pColorAttachmentFormats is not VK_FORMAT_UNDEFINED, pColorBlendState must be a valid pointer to a valid VkPipelineColorBlendStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-pColorBlendState-09038
      If pColorBlendState is not NULL it must be a valid pointer to a valid VkPipelineColorBlendStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06055
      If renderPass is VK_NULL_HANDLE, pColorBlendState is not dynamic, and the pipeline is being created with fragment output interface state, pColorBlendState->attachmentCount must be equal to VkPipelineRenderingCreateInfo::colorAttachmentCount

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06057
      If renderPass is VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, VkPipelineRenderingCreateInfo::viewMask is not 0, and the multiviewTessellationShader feature is not enabled, then pStages must not include tessellation shaders

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06058
      If renderPass is VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, VkPipelineRenderingCreateInfo::viewMask is not 0, and the multiviewGeometryShader feature is not enabled, then pStages must not include a geometry shader

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06059
      If renderPass is VK_NULL_HANDLE, the pipeline is being created with pre-rasterization shader state, and VkPipelineRenderingCreateInfo::viewMask is not 0, all of the shaders in the pipeline must not include variables decorated with the Layer built-in decoration in their interfaces

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06061
      If the pipeline requires fragment shader state, and renderPass is VK_NULL_HANDLE, fragment shaders in pStages must not include the InputAttachment capability

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06062
      If the pipeline requires fragment output interface state and renderPass is VK_NULL_HANDLE, for each color attachment format defined by the pColorAttachmentFormats member of VkPipelineRenderingCreateInfo, if its potential format features do not contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT, then the blendEnable member of the corresponding element of the pAttachments member of pColorBlendState must be VK_FALSE

    • VUID-VkGraphicsPipelineCreateInfo-pipelineStageCreationFeedbackCount-06594
      If VkPipelineCreationFeedbackCreateInfo::pipelineStageCreationFeedbackCount is not 0, it must be equal to stageCount

    • VUID-VkGraphicsPipelineCreateInfo-pStages-06600
      If the pipeline requires pre-rasterization shader state or fragment shader state, pStages must be a valid pointer to an array of stageCount valid VkPipelineShaderStageCreateInfo structures

    • VUID-VkGraphicsPipelineCreateInfo-stageCount-09587
      If the pipeline does not require pre-rasterization shader state or fragment shader state, stageCount must be zero

    • VUID-VkGraphicsPipelineCreateInfo-pRasterizationState-06601
      If the pipeline requires pre-rasterization shader state, pRasterizationState must be a valid pointer to a valid VkPipelineRasterizationStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-layout-06602
      If the pipeline requires fragment shader state or pre-rasterization shader state, layout must be a valid VkPipelineLayout handle

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-06603
      If the pipeline requires pre-rasterization shader state, fragment shader state, or fragment output state, and renderPass is not VK_NULL_HANDLE, renderPass must be a valid VkRenderPass handle

    • VUID-VkGraphicsPipelineCreateInfo-stageCount-09530
      If the pipeline requires pre-rasterization shader state, stageCount must be greater than 0

    • VUID-VkGraphicsPipelineCreateInfo-pStages-06894
      If the pipeline requires pre-rasterization shader state but not fragment shader state, elements of pStages must not have stage set to VK_SHADER_STAGE_FRAGMENT_BIT

    • VUID-VkGraphicsPipelineCreateInfo-pStages-06895
      If the pipeline requires fragment shader state but not pre-rasterization shader state, elements of pStages must not have stage set to a shader stage which participates in pre-rasterization

    • VUID-VkGraphicsPipelineCreateInfo-pStages-06896
      If the pipeline requires pre-rasterization shader state, all elements of pStages must have a stage set to a shader stage which participates in fragment shader state or pre-rasterization shader state

    • VUID-VkGraphicsPipelineCreateInfo-stage-06897
      If the pipeline requires fragment shader state and/or pre-rasterization shader state, any value of stage must not be set in more than one element of pStages

    • VUID-VkGraphicsPipelineCreateInfo-renderPass-08744
      If renderPass is VK_NULL_HANDLE, the pipeline requires fragment output state or fragment shader state, the pipeline enables sample shading, rasterizationSamples is not dynamic, and the pNext chain includes a VkPipelineRenderingCreateInfo structure, rasterizationSamples must be a valid VkSampleCountFlagBits value that is set in imageCreateSampleCounts (as defined in Image Creation Limits) for every element of depthAttachmentFormat, stencilAttachmentFormat and the pColorAttachmentFormats array which is not VK_FORMAT_UNDEFINED

    • VUID-VkGraphicsPipelineCreateInfo-None-08893
      The pipeline must be created with pre-rasterization shader state

    • VUID-VkGraphicsPipelineCreateInfo-pStages-08894
      If pStages includes a vertex shader stage, the pipeline must be created with vertex input state

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-08896
      If pDynamicState->pDynamicStates includes VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE, or if it does not and pRasterizationState->rasterizerDiscardEnable is VK_FALSE, the pipeline must be created with fragment shader state and fragment output interface state

    • VUID-VkGraphicsPipelineCreateInfo-None-09043
      If the format of any color attachment is VK_FORMAT_E5B9G9R9_UFLOAT_PACK32, the colorWriteMask member of the corresponding element of pColorBlendState->pAttachments must either include all of VK_COLOR_COMPONENT_R_BIT, VK_COLOR_COMPONENT_G_BIT, and VK_COLOR_COMPONENT_B_BIT, or none of them

    Valid Usage (Implicit)

    • VUID-VkGraphicsPipelineCreateInfo-sType-sType
      sType must be VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO

    • VUID-VkGraphicsPipelineCreateInfo-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 VkPipelineCreationFeedbackCreateInfo or VkPipelineRenderingCreateInfo

    • VUID-VkGraphicsPipelineCreateInfo-sType-unique
      The sType value of each struct in the pNext chain must be unique

    • VUID-VkGraphicsPipelineCreateInfo-pDynamicState-parameter
      If pDynamicState is not NULL, pDynamicState must be a valid pointer to a valid VkPipelineDynamicStateCreateInfo structure

    • VUID-VkGraphicsPipelineCreateInfo-commonparent
      Each of basePipelineHandle, layout, and renderPass that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

    The VkPipelineRenderingCreateInfo structure is defined as:

    // Provided by VK_VERSION_1_3
typedef struct VkPipelineRenderingCreateInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           viewMask;
    uint32_t           colorAttachmentCount;
    const VkFormat*    pColorAttachmentFormats;
    VkFormat           depthAttachmentFormat;
    VkFormat           stencilAttachmentFormat;
} VkPipelineRenderingCreateInfo;

    • sType is a VkStructureType value identifying this structure.

    • pNext is NULL or a pointer to a structure extending this structure.

    • viewMask is the viewMask used for rendering.

    • colorAttachmentCount is the number of entries in pColorAttachmentFormats

    • pColorAttachmentFormats is a pointer to an array of VkFormat values defining the format of color attachments used in this pipeline.

    • depthAttachmentFormat is a VkFormat value defining the format of the depth attachment used in this pipeline.

    • stencilAttachmentFormat is a VkFormat value defining the format of the stencil attachment used in this pipeline.

    When a pipeline is created without a VkRenderPass, if the pNext chain of VkGraphicsPipelineCreateInfo includes this structure, it specifies the view mask and format of attachments used for rendering. If this structure is not specified, and the pipeline does not include a VkRenderPass, viewMask and colorAttachmentCount are 0, and depthAttachmentFormat and stencilAttachmentFormat are VK_FORMAT_UNDEFINED. If a graphics pipeline is created with a valid VkRenderPass, parameters of this structure are ignored.

    If depthAttachmentFormat, stencilAttachmentFormat, or any element of pColorAttachmentFormats is VK_FORMAT_UNDEFINED, it indicates that the corresponding attachment is unused within the render pass. Valid formats indicate that an attachment can be used - but it is still valid to set the attachment to NULL when beginning rendering.

    Valid Usage

    • VUID-VkPipelineRenderingCreateInfo-colorAttachmentCount-09533
      colorAttachmentCount must be less than or equal to maxColorAttachments

    Valid Usage (Implicit)

    • VUID-VkPipelineRenderingCreateInfo-sType-sType
      sType must be VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO

    Bits which can be set in

    specify how a pipeline is created, and are:

    // Provided by VK_VERSION_1_0
typedef enum VkPipelineCreateFlagBits {
    VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT = 0x00000001,
    VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT = 0x00000002,
    VK_PIPELINE_CREATE_DERIVATIVE_BIT = 0x00000004,
  // Provided by VK_VERSION_1_1
    VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT = 0x00000008,
  // Provided by VK_VERSION_1_1
    VK_PIPELINE_CREATE_DISPATCH_BASE_BIT = 0x00000010,
  // Provided by VK_VERSION_1_3
    VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT = 0x00000100,
  // Provided by VK_VERSION_1_3
    VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT = 0x00000200,
  // Provided by VK_VERSION_1_1
    VK_PIPELINE_CREATE_DISPATCH_BASE = VK_PIPELINE_CREATE_DISPATCH_BASE_BIT,
} VkPipelineCreateFlagBits;

    • VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT specifies that the created pipeline will not be optimized. Using this flag may reduce the time taken to create the pipeline.

    • VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT specifies that the pipeline to be created is allowed to be the parent of a pipeline that will be created in a subsequent pipeline creation call.

    • VK_PIPELINE_CREATE_DERIVATIVE_BIT specifies that the pipeline to be created will be a child of a previously created parent pipeline.

    • VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT specifies that any shader input variables decorated as ViewIndex will be assigned values as if they were decorated as DeviceIndex.

    • VK_PIPELINE_CREATE_DISPATCH_BASE specifies that a compute pipeline can be used with vkCmdDispatchBase with a non-zero base workgroup.

    • VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT specifies that pipeline creation will fail if a compile is required for creation of a valid VkPipeline object; VK_PIPELINE_COMPILE_REQUIRED will be returned by pipeline creation, and the VkPipeline will be set to VK_NULL_HANDLE.

    • When creating multiple pipelines, VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT specifies that control will be returned to the application if any individual pipeline returns a result which is not VK_SUCCESS rather than continuing to create additional pipelines.

    It is valid to set both VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT and VK_PIPELINE_CREATE_DERIVATIVE_BIT. This allows a pipeline to be both a parent and possibly a child in a pipeline hierarchy. See Pipeline Derivatives for more information.

    // Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineCreateFlags;

    VkPipelineCreateFlags is a bitmask type for setting a mask of zero or more VkPipelineCreateFlagBits.

    The VkPipelineDynamicStateCreateInfo structure is defined as:

    // Provided by VK_VERSION_1_0
typedef struct VkPipelineDynamicStateCreateInfo {
    VkStructureType                      sType;
    const void*                          pNext;
    VkPipelineDynamicStateCreateFlags    flags;
    uint32_t                             dynamicStateCount;
    const VkDynamicState*                pDynamicStates;
} VkPipelineDynamicStateCreateInfo;

    • sType is a VkStructureType value identifying this structure.

    • pNext is NULL or a pointer to a structure extending this structure.

    • flags is reserved for future use.

    • dynamicStateCount is the number of elements in the pDynamicStates array.

    • pDynamicStates is a pointer to an array of VkDynamicState values specifying which pieces of pipeline state will use the values from dynamic state commands rather than from pipeline state creation information.

    Valid Usage

    • VUID-VkPipelineDynamicStateCreateInfo-pDynamicStates-01442
      Each element of pDynamicStates must be unique

    Valid Usage (Implicit)

    • VUID-VkPipelineDynamicStateCreateInfo-sType-sType
      sType must be VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO

    • VUID-VkPipelineDynamicStateCreateInfo-pNext-pNext
      pNext must be NULL

    • VUID-VkPipelineDynamicStateCreateInfo-flags-zerobitmask
      flags must be 0

    • VUID-VkPipelineDynamicStateCreateInfo-pDynamicStates-parameter
      If dynamicStateCount is not 0, pDynamicStates must be a valid pointer to an array of dynamicStateCount valid VkDynamicState values

    // Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineDynamicStateCreateFlags;

    VkPipelineDynamicStateCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use.

    The source of different pieces of dynamic state is specified by the VkPipelineDynamicStateCreateInfo::pDynamicStates property of the currently active pipeline, each of whose elements must be one of the values:

    // Provided by VK_VERSION_1_0
typedef enum VkDynamicState {
    VK_DYNAMIC_STATE_VIEWPORT = 0,
    VK_DYNAMIC_STATE_SCISSOR = 1,
    VK_DYNAMIC_STATE_LINE_WIDTH = 2,
    VK_DYNAMIC_STATE_DEPTH_BIAS = 3,
    VK_DYNAMIC_STATE_BLEND_CONSTANTS = 4,
    VK_DYNAMIC_STATE_DEPTH_BOUNDS = 5,
    VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK = 6,
    VK_DYNAMIC_STATE_STENCIL_WRITE_MASK = 7,
    VK_DYNAMIC_STATE_STENCIL_REFERENCE = 8,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_CULL_MODE = 1000267000,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_FRONT_FACE = 1000267001,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY = 1000267002,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT = 1000267003,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT = 1000267004,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE = 1000267005,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE = 1000267006,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE = 1000267007,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_DEPTH_COMPARE_OP = 1000267008,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE = 1000267009,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE = 1000267010,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_STENCIL_OP = 1000267011,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE = 1000377001,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE = 1000377002,
  // Provided by VK_VERSION_1_3
    VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE = 1000377004,
} VkDynamicState;

    10.3.1. Valid Combinations of Stages for Graphics Pipelines

    If tessellation shader stages are omitted, the tessellation shading and fixed-function stages of the pipeline are skipped.

    If a geometry shader is omitted, the geometry shading stage is skipped.

    If a fragment shader is omitted, fragment color outputs have undefined values, and the fragment depth value is determined by Fragment Operations state. This can be useful for depth-only rendering.

    Presence of a shader stage in a pipeline is indicated by including a valid VkPipelineShaderStageCreateInfo with module and pName selecting an entry point from a shader module, where that entry point is valid for the stage specified by stage.

    Presence of some of the fixed-function stages in the pipeline is implicitly derived from enabled shaders and provided state. For example, the fixed-function tessellator is always present when the pipeline has valid Tessellation Control and Tessellation Evaluation shaders.

    For example:

    10.4. Pipeline Destruction

    To destroy a pipeline, call:

    // Provided by VK_VERSION_1_0
void vkDestroyPipeline(
    VkDevice                                    device,
    VkPipeline                                  pipeline,
    const VkAllocationCallbacks*                pAllocator);

    • device is the logical device that destroys the pipeline.

    • pipeline is the handle of the pipeline to destroy.

    • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

    Valid Usage

    • VUID-vkDestroyPipeline-pipeline-00765
      All submitted commands that refer to pipeline must have completed execution

    • VUID-vkDestroyPipeline-pipeline-00766
      If VkAllocationCallbacks were provided when pipeline was created, a compatible set of callbacks must be provided here

    • VUID-vkDestroyPipeline-pipeline-00767
      If no VkAllocationCallbacks were provided when pipeline was created, pAllocator must be NULL

    Valid Usage (Implicit)

    • VUID-vkDestroyPipeline-device-parameter
      device must be a valid VkDevice handle

    • VUID-vkDestroyPipeline-pipeline-parameter
      If pipeline is not VK_NULL_HANDLE, pipeline must be a valid VkPipeline handle

    • VUID-vkDestroyPipeline-pAllocator-parameter
      If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

    • VUID-vkDestroyPipeline-pipeline-parent
      If pipeline is a valid handle, it must have been created, allocated, or retrieved from device

    Host Synchronization

    • Host access to pipeline must be externally synchronized

    10.5. Pipeline Derivatives

    A pipeline derivative is a child pipeline created from a parent pipeline, where the child and parent are expected to have much commonality.

    The goal of derivative pipelines is that they be cheaper to create using the parent as a starting point, and that it be more efficient (on either host or device) to switch/bind between children of the same parent.

    A derivative pipeline is created by setting the VK_PIPELINE_CREATE_DERIVATIVE_BIT flag in the Vk*PipelineCreateInfo structure. If this is set, then exactly one of basePipelineHandle or basePipelineIndex members of the structure must have a valid handle/index, and specifies the parent pipeline. If basePipelineHandle is used, the parent pipeline must have already been created. If basePipelineIndex is used, then the parent is being created in the same command. VK_NULL_HANDLE acts as the invalid handle for basePipelineHandle, and -1 is the invalid index for basePipelineIndex. If basePipelineIndex is used, the base pipeline must appear earlier in the array. The base pipeline must have been created with the VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set.

    10.6. Pipeline Cache

    Pipeline cache objects allow the result of pipeline construction to be reused between pipelines and between runs of an application. Reuse between pipelines is achieved by passing the same pipeline cache object when creating multiple related pipelines. Reuse across runs of an application is achieved by retrieving pipeline cache contents in one run of an application, saving the contents, and using them to preinitialize a pipeline cache on a subsequent run. The contents of the pipeline cache objects are managed by the implementation. Applications can manage the host memory consumed by a pipeline cache object and control the amount of data retrieved from a pipeline cache object.

    Pipeline cache objects are represented by VkPipelineCache handles:

    // Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPipelineCache)

    10.6.1. Creating a Pipeline Cache

    To create pipeline cache objects, call:

    // Provided by VK_VERSION_1_0
VkResult vkCreatePipelineCache(
    VkDevice                                    device,
    const VkPipelineCacheCreateInfo*            pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkPipelineCache*                            pPipelineCache);

    • device is the logical device that creates the pipeline cache object.

    • pCreateInfo is a pointer to a VkPipelineCacheCreateInfo structure containing initial parameters for the pipeline cache object.

    • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

    • pPipelineCache is a pointer to a VkPipelineCache handle in which the resulting pipeline cache object is returned.

    Note

    Applications can track and manage the total host memory size of a pipeline cache object using the pAllocator. Applications can limit the amount of data retrieved from a pipeline cache object in vkGetPipelineCacheData. Implementations should not internally limit the total number of entries added to a pipeline cache object or the total host memory consumed.

    Once created, a pipeline cache can be passed to the vkCreateGraphicsPipelines and vkCreateComputePipelines commands. If the pipeline cache passed into these commands is not VK_NULL_HANDLE, the implementation will query it for possible reuse opportunities and update it with new content. The use of the pipeline cache object in these commands is internally synchronized, and the same pipeline cache object can be used in multiple threads simultaneously.

    If flags of pCreateInfo includes VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, all commands that modify the returned pipeline cache object must be externally synchronized.

    Note

    Implementations should make every effort to limit any critical sections to the actual accesses to the cache, which is expected to be significantly shorter than the duration of the vkCreate*Pipelines commands.
    Valid Usage (Implicit)

    • VUID-vkCreatePipelineCache-device-parameter
      device must be a valid VkDevice handle

    • VUID-vkCreatePipelineCache-pCreateInfo-parameter
      pCreateInfo must be a valid pointer to a valid VkPipelineCacheCreateInfo structure

    • VUID-vkCreatePipelineCache-pAllocator-parameter
      If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

    • VUID-vkCreatePipelineCache-pPipelineCache-parameter
      pPipelineCache must be a valid pointer to a VkPipelineCache handle

    Return Codes
    Success

    • VK_SUCCESS

    Failure

    • VK_ERROR_OUT_OF_HOST_MEMORY

    • VK_ERROR_OUT_OF_DEVICE_MEMORY

    The VkPipelineCacheCreateInfo structure is defined as:

    // Provided by VK_VERSION_1_0
typedef struct VkPipelineCacheCreateInfo {
    VkStructureType               sType;
    const void*                   pNext;
    VkPipelineCacheCreateFlags    flags;
    size_t                        initialDataSize;
    const void*                   pInitialData;
} VkPipelineCacheCreateInfo;

    • 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 VkPipelineCacheCreateFlagBits specifying the behavior of the pipeline cache.

    • initialDataSize is the number of bytes in pInitialData. If initialDataSize is zero, the pipeline cache will initially be empty.

    • pInitialData is a pointer to previously retrieved pipeline cache data. If the pipeline cache data is incompatible (as defined below) with the device, the pipeline cache will be initially empty. If initialDataSize is zero, pInitialData is ignored.

    Valid Usage

    • VUID-VkPipelineCacheCreateInfo-initialDataSize-00768
      If initialDataSize is not 0, it must be equal to the size of pInitialData, as returned by vkGetPipelineCacheData when pInitialData was originally retrieved

    • VUID-VkPipelineCacheCreateInfo-initialDataSize-00769
      If initialDataSize is not 0, pInitialData must have been retrieved from a previous call to vkGetPipelineCacheData

    • VUID-VkPipelineCacheCreateInfo-pipelineCreationCacheControl-02892
      If the pipelineCreationCacheControl feature is not enabled, flags must not include VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT

    Valid Usage (Implicit)

    • VUID-VkPipelineCacheCreateInfo-sType-sType
      sType must be VK_STRUCTURE_TYPE_PIPELINE_CACHE_CREATE_INFO

    • VUID-VkPipelineCacheCreateInfo-pNext-pNext
      pNext must be NULL

    • VUID-VkPipelineCacheCreateInfo-flags-parameter
      flags must be a valid combination of VkPipelineCacheCreateFlagBits values

    • VUID-VkPipelineCacheCreateInfo-pInitialData-parameter
      If initialDataSize is not 0, pInitialData must be a valid pointer to an array of initialDataSize bytes

    // Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineCacheCreateFlags;

    VkPipelineCacheCreateFlags is a bitmask type for setting a mask of zero or more VkPipelineCacheCreateFlagBits.

    Bits which can be set in VkPipelineCacheCreateInfo::flags, specifying behavior of the pipeline cache, are:

    typedef enum VkPipelineCacheCreateFlagBits {
  // Provided by VK_VERSION_1_3
    VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT = 0x00000001,
} VkPipelineCacheCreateFlagBits;

    • VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT specifies that all commands that modify the created VkPipelineCache will be externally synchronized. When set, the implementation may skip any unnecessary processing needed to support simultaneous modification from multiple threads where allowed.

    10.6.2. Merging Pipeline Caches

    Pipeline cache objects can be merged using the command:

    // Provided by VK_VERSION_1_0
VkResult vkMergePipelineCaches(
    VkDevice                                    device,
    VkPipelineCache                             dstCache,
    uint32_t                                    srcCacheCount,
    const VkPipelineCache*                      pSrcCaches);

    • device is the logical device that owns the pipeline cache objects.

    • dstCache is the handle of the pipeline cache to merge results into.

    • srcCacheCount is the length of the pSrcCaches array.

    • pSrcCaches is a pointer to an array of pipeline cache handles, which will be merged into dstCache. The previous contents of dstCache are included after the merge.

    Note

    The details of the merge operation are implementation-dependent, but implementations should merge the contents of the specified pipelines and prune duplicate entries.
    Valid Usage

    • VUID-vkMergePipelineCaches-dstCache-00770
      dstCache must not appear in the list of source caches

    Valid Usage (Implicit)

    • VUID-vkMergePipelineCaches-device-parameter
      device must be a valid VkDevice handle

    • VUID-vkMergePipelineCaches-dstCache-parameter
      dstCache must be a valid VkPipelineCache handle

    • VUID-vkMergePipelineCaches-pSrcCaches-parameter
      pSrcCaches must be a valid pointer to an array of srcCacheCount valid VkPipelineCache handles

    • VUID-vkMergePipelineCaches-srcCacheCount-arraylength
      srcCacheCount must be greater than 0

    • VUID-vkMergePipelineCaches-dstCache-parent
      dstCache must have been created, allocated, or retrieved from device

    • VUID-vkMergePipelineCaches-pSrcCaches-parent
      Each element of pSrcCaches must have been created, allocated, or retrieved from device

    Host Synchronization

    • Host access to dstCache must be externally synchronized

    Return Codes
    Success

    • VK_SUCCESS

    Failure

    • VK_ERROR_OUT_OF_HOST_MEMORY

    • VK_ERROR_OUT_OF_DEVICE_MEMORY

    10.6.3. Retrieving Pipeline Cache Data

    Data can be retrieved from a pipeline cache object using the command:

    // Provided by VK_VERSION_1_0
VkResult vkGetPipelineCacheData(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    size_t*                                     pDataSize,
    void*                                       pData);

    • device is the logical device that owns the pipeline cache.

    • pipelineCache is the pipeline cache to retrieve data from.

    • pDataSize is a pointer to a size_t value related to the amount of data in the pipeline cache, as described below.

    • pData is either NULL or a pointer to a buffer.

    If pData is NULL, then the maximum size of the data that can be retrieved from the pipeline cache, in bytes, is returned in pDataSize. Otherwise, pDataSize must point to a variable set by the user to the size of the buffer, in bytes, pointed to by pData, and on return the variable is overwritten with the amount of data actually written to pData. If pDataSize is less than the maximum size that can be retrieved by the pipeline cache, at most pDataSize bytes will be written to pData, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all of the pipeline cache was returned.

    Any data written to pData is valid and can be provided as the pInitialData member of the VkPipelineCacheCreateInfo structure passed to vkCreatePipelineCache.

    Two calls to vkGetPipelineCacheData with the same parameters must retrieve the same data unless a command that modifies the contents of the cache is called between them.

    The initial bytes written to pData must be a header as described in the Pipeline Cache Header section.

    If pDataSize is less than what is necessary to store this header, nothing will be written to pData and zero will be written to pDataSize.

    Valid Usage (Implicit)

    • VUID-vkGetPipelineCacheData-device-parameter
      device must be a valid VkDevice handle

    • VUID-vkGetPipelineCacheData-pipelineCache-parameter
      pipelineCache must be a valid VkPipelineCache handle

    • VUID-vkGetPipelineCacheData-pDataSize-parameter
      pDataSize must be a valid pointer to a size_t value

    • VUID-vkGetPipelineCacheData-pData-parameter
      If the value referenced by pDataSize is not 0, and pData is not NULL, pData must be a valid pointer to an array of pDataSize bytes

    • VUID-vkGetPipelineCacheData-pipelineCache-parent
      pipelineCache must have been created, allocated, or retrieved from device

    Return Codes
    Success

    • VK_SUCCESS

    • VK_INCOMPLETE

    Failure

    • VK_ERROR_OUT_OF_HOST_MEMORY

    • VK_ERROR_OUT_OF_DEVICE_MEMORY

    10.6.4. Pipeline Cache Header

    Applications can store the data retrieved from the pipeline cache, and use these data, possibly in a future run of the application, to populate new pipeline cache objects. The results of pipeline compiles, however, may depend on the vendor ID, device ID, driver version, and other details of the device. To enable applications to detect when previously retrieved data is incompatible with the device, the pipeline cache data must begin with a valid pipeline cache header.

    Note

    Structures described in this section are not part of the Vulkan API and are only used to describe the representation of data elements in pipeline cache data. Accordingly, the valid usage clauses defined for structures defined in this section do not define valid usage conditions for APIs accepting pipeline cache data as input, as providing invalid pipeline cache data as input to any Vulkan API commands will result in the provided pipeline cache data being ignored.

    Version one of the pipeline cache header is defined as:

    // Provided by VK_VERSION_1_0
typedef struct VkPipelineCacheHeaderVersionOne {
    uint32_t                        headerSize;
    VkPipelineCacheHeaderVersion    headerVersion;
    uint32_t                        vendorID;
    uint32_t                        deviceID;
    uint8_t                         pipelineCacheUUID[VK_UUID_SIZE];
} VkPipelineCacheHeaderVersionOne;

    • headerSize is the length in bytes of the pipeline cache header.

    • headerVersion is a VkPipelineCacheHeaderVersion value specifying the version of the header. A consumer of the pipeline cache should use the cache version to interpret the remainder of the cache header.

    • vendorID is the VkPhysicalDeviceProperties::vendorID of the implementation.

    • deviceID is the VkPhysicalDeviceProperties::deviceID of the implementation.

    • pipelineCacheUUID is the VkPhysicalDeviceProperties::pipelineCacheUUID of the implementation.

    Unlike most structures declared by the Vulkan API, all fields of this structure are written with the least significant byte first, regardless of host byte-order.

    The C language specification does not define the packing of structure members. This layout assumes tight structure member packing, with members laid out in the order listed in the structure, and the intended size of the structure is 32 bytes. If a compiler produces code that diverges from that pattern, applications must employ another method to set values at the correct offsets.

    Valid Usage

    • VUID-VkPipelineCacheHeaderVersionOne-headerSize-04967
      headerSize must be 32

    • VUID-VkPipelineCacheHeaderVersionOne-headerVersion-04968
      headerVersion must be VK_PIPELINE_CACHE_HEADER_VERSION_ONE

    • VUID-VkPipelineCacheHeaderVersionOne-headerSize-08990
      headerSize must not exceed the size of the pipeline cache

    Valid Usage (Implicit)

    Possible values of the headerVersion value of the pipeline cache header are:

    // Provided by VK_VERSION_1_0
typedef enum VkPipelineCacheHeaderVersion {
    VK_PIPELINE_CACHE_HEADER_VERSION_ONE = 1,
} VkPipelineCacheHeaderVersion;

    10.6.5. Destroying a Pipeline Cache

    To destroy a pipeline cache, call:

    // Provided by VK_VERSION_1_0
void vkDestroyPipelineCache(
    VkDevice                                    device,
    VkPipelineCache                             pipelineCache,
    const VkAllocationCallbacks*                pAllocator);

    • device is the logical device that destroys the pipeline cache object.

    • pipelineCache is the handle of the pipeline cache to destroy.

    • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

    Valid Usage

    • VUID-vkDestroyPipelineCache-pipelineCache-00771
      If VkAllocationCallbacks were provided when pipelineCache was created, a compatible set of callbacks must be provided here

    • VUID-vkDestroyPipelineCache-pipelineCache-00772
      If no VkAllocationCallbacks were provided when pipelineCache was created, pAllocator must be NULL

    Valid Usage (Implicit)

    • VUID-vkDestroyPipelineCache-device-parameter
      device must be a valid VkDevice handle

    • VUID-vkDestroyPipelineCache-pipelineCache-parameter
      If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

    • VUID-vkDestroyPipelineCache-pAllocator-parameter
      If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

    • VUID-vkDestroyPipelineCache-pipelineCache-parent
      If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

    Host Synchronization

    • Host access to pipelineCache must be externally synchronized

    10.7. Specialization Constants

    Specialization constants are a mechanism whereby constants in a SPIR-V module can have their constant value specified at the time the VkPipeline is created. This allows a SPIR-V module to have constants that can be modified while executing an application that uses the Vulkan API.

    Note

    Specialization constants are useful to allow a compute shader to have its local workgroup size changed at runtime by the user, for example.

    Each VkPipelineShaderStageCreateInfo structure contains a pSpecializationInfo member, which can be NULL to indicate no specialization constants, or point to a VkSpecializationInfo structure.

    The VkSpecializationInfo structure is defined as:

    // Provided by VK_VERSION_1_0
typedef struct VkSpecializationInfo {
    uint32_t                           mapEntryCount;
    const VkSpecializationMapEntry*    pMapEntries;
    size_t                             dataSize;
    const void*                        pData;
} VkSpecializationInfo;

    • mapEntryCount is the number of entries in the pMapEntries array.

    • pMapEntries is a pointer to an array of VkSpecializationMapEntry structures, which map constant IDs to offsets in pData.

    • dataSize is the byte size of the pData buffer.

    • pData contains the actual constant values to specialize with.

    Valid Usage

    • VUID-VkSpecializationInfo-offset-00773
      The offset member of each element of pMapEntries must be less than dataSize

    • VUID-VkSpecializationInfo-pMapEntries-00774
      The size member of each element of pMapEntries must be less than or equal to dataSize minus offset

    • VUID-VkSpecializationInfo-constantID-04911
      The constantID value of each element of pMapEntries must be unique within pMapEntries

    Valid Usage (Implicit)

    • VUID-VkSpecializationInfo-pMapEntries-parameter
      If mapEntryCount is not 0, pMapEntries must be a valid pointer to an array of mapEntryCount valid VkSpecializationMapEntry structures

    • VUID-VkSpecializationInfo-pData-parameter
      If dataSize is not 0, pData must be a valid pointer to an array of dataSize bytes

    The VkSpecializationMapEntry structure is defined as:

    // Provided by VK_VERSION_1_0
typedef struct VkSpecializationMapEntry {
    uint32_t    constantID;
    uint32_t    offset;
    size_t      size;
} VkSpecializationMapEntry;

    • constantID is the ID of the specialization constant in SPIR-V.

    • offset is the byte offset of the specialization constant value within the supplied data buffer.

    • size is the byte size of the specialization constant value within the supplied data buffer.

    If a constantID value is not a specialization constant ID used in the shader, that map entry does not affect the behavior of the pipeline.

    Valid Usage

    • VUID-VkSpecializationMapEntry-constantID-00776
      For a constantID specialization constant declared in a shader, size must match the byte size of the constantID. If the specialization constant is of type boolean, size must be the byte size of VkBool32

    In human readable SPIR-V:

    OpDecorate %x SpecId 13 ; decorate .x component of WorkgroupSize with ID 13
OpDecorate %y SpecId 42 ; decorate .y component of WorkgroupSize with ID 42
OpDecorate %z SpecId 3  ; decorate .z component of WorkgroupSize with ID 3
OpDecorate %wgsize BuiltIn WorkgroupSize ; decorate WorkgroupSize onto constant
%i32 = OpTypeInt 32 0 ; declare an unsigned 32-bit type
%uvec3 = OpTypeVector %i32 3 ; declare a 3 element vector type of unsigned 32-bit
%x = OpSpecConstant %i32 1 ; declare the .x component of WorkgroupSize
%y = OpSpecConstant %i32 1 ; declare the .y component of WorkgroupSize
%z = OpSpecConstant %i32 1 ; declare the .z component of WorkgroupSize
%wgsize = OpSpecConstantComposite %uvec3 %x %y %z ; declare WorkgroupSize

    From the above we have three specialization constants, one for each of the x, y & z elements of the WorkgroupSize vector.

    Now to specialize the above via the specialization constants mechanism:

    const VkSpecializationMapEntry entries[] =
{
    {
        .constantID = 13,
        .offset = 0 * sizeof(uint32_t),
        .size = sizeof(uint32_t)
    },
    {
        .constantID = 42,
        .offset = 1 * sizeof(uint32_t),
        .size = sizeof(uint32_t)
    },
    {
        .constantID = 3,
        .offset = 2 * sizeof(uint32_t),
        .size = sizeof(uint32_t)
    }
};

const uint32_t data[] = { 16, 8, 4 }; // our workgroup size is 16x8x4

const VkSpecializationInfo info =
{
    .mapEntryCount = 3,
    .pMapEntries  = entries,
    .dataSize = 3 * sizeof(uint32_t),
    .pData = data,
};

    Then when calling vkCreateComputePipelines, and passing the VkSpecializationInfo we defined as the pSpecializationInfo parameter of VkPipelineShaderStageCreateInfo, we will create a compute pipeline with the runtime specified local workgroup size.

    Another example would be that an application has a SPIR-V module that has some platform-dependent constants they wish to use.

    In human readable SPIR-V:

    OpDecorate %1 SpecId 0  ; decorate our signed 32-bit integer constant
OpDecorate %2 SpecId 12 ; decorate our 32-bit floating-point constant
%i32 = OpTypeInt 32 1   ; declare a signed 32-bit type
%float = OpTypeFloat 32 ; declare a 32-bit floating-point type
%1 = OpSpecConstant %i32 -1 ; some signed 32-bit integer constant
%2 = OpSpecConstant %float 0.5 ; some 32-bit floating-point constant

    From the above we have two specialization constants, one is a signed 32-bit integer and the second is a 32-bit floating-point value.

    Now to specialize the above via the specialization constants mechanism:

    struct SpecializationData {
    int32_t data0;
    float data1;
};

const VkSpecializationMapEntry entries[] =
{
    {
        .constantID = 0,
        .offset = offsetof(SpecializationData, data0),
        .size = sizeof(SpecializationData::data0)
    },
    {
        .constantID = 12,
        .offset = offsetof(SpecializationData, data1),
        .size = sizeof(SpecializationData::data1)
    }
};

SpecializationData data;
data.data0 = -42;    // set the data for the 32-bit integer
data.data1 = 42.0f;  // set the data for the 32-bit floating-point

const VkSpecializationInfo info =
{
    .mapEntryCount = 2,
    .pMapEntries = entries,
    .dataSize = sizeof(data),
    .pdata = &data,
};

    It is legal for a SPIR-V module with specializations to be compiled into a pipeline where no specialization information was provided. SPIR-V specialization constants contain default values such that if a specialization is not provided, the default value will be used. In the examples above, it would be valid for an application to only specialize some of the specialization constants within the SPIR-V module, and let the other constants use their default values encoded within the OpSpecConstant declarations.

    10.8. Pipeline Binding

    Once a pipeline has been created, it can be bound to the command buffer using the command:

    // Provided by VK_VERSION_1_0
void vkCmdBindPipeline(
    VkCommandBuffer                             commandBuffer,
    VkPipelineBindPoint                         pipelineBindPoint,
    VkPipeline                                  pipeline);

    • commandBuffer is the command buffer that the pipeline will be bound to.

    • pipelineBindPoint is a VkPipelineBindPoint value specifying to which bind point the pipeline is bound. Binding one does not disturb the others.

    • pipeline is the pipeline to be bound.

    Once bound, a pipeline binding affects subsequent commands that interact with the given pipeline type in the command buffer until a different pipeline of the same type is bound to the bind point. Commands that do not interact with the given pipeline type must not be affected by the pipeline state.

    Valid Usage

    • VUID-vkCmdBindPipeline-pipelineBindPoint-00777
      If pipelineBindPoint is VK_PIPELINE_BIND_POINT_COMPUTE, the VkCommandPool that commandBuffer was allocated from must support compute operations

    • VUID-vkCmdBindPipeline-pipelineBindPoint-00778
      If pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS, the VkCommandPool that commandBuffer was allocated from must support graphics operations

    • VUID-vkCmdBindPipeline-pipelineBindPoint-00779
      If pipelineBindPoint is VK_PIPELINE_BIND_POINT_COMPUTE, pipeline must be a compute pipeline

    • VUID-vkCmdBindPipeline-pipelineBindPoint-00780
      If pipelineBindPoint is VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline must be a graphics pipeline

    • VUID-vkCmdBindPipeline-pipeline-00781
      If the variableMultisampleRate feature is not supported, pipeline is a graphics pipeline, the current subpass uses no attachments, and this is not the first call to this function with a graphics pipeline after transitioning to the current subpass, then the sample count specified by this pipeline must match that set in the previous pipeline

    Valid Usage (Implicit)

    • VUID-vkCmdBindPipeline-commandBuffer-parameter
      commandBuffer must be a valid VkCommandBuffer handle

    • VUID-vkCmdBindPipeline-pipelineBindPoint-parameter
      pipelineBindPoint must be a valid VkPipelineBindPoint value

    • VUID-vkCmdBindPipeline-pipeline-parameter
      pipeline must be a valid VkPipeline handle

    • VUID-vkCmdBindPipeline-commandBuffer-recording
      commandBuffer must be in the recording state

    • VUID-vkCmdBindPipeline-commandBuffer-cmdpool
      The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

    • VUID-vkCmdBindPipeline-commonparent
      Both of commandBuffer, and pipeline must have been created, allocated, or retrieved from the same VkDevice

    Host Synchronization

    • Host access to commandBuffer must be externally synchronized

    • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

    Command Properties
    Command Buffer Levels Render Pass Scope Supported Queue Types Command Type

    Primary
    Secondary

    Both

    Graphics
    Compute

    State

    Possible values of vkCmdBindPipeline::pipelineBindPoint, specifying the bind point of a pipeline object, are:

    // Provided by VK_VERSION_1_0
typedef enum VkPipelineBindPoint {
    VK_PIPELINE_BIND_POINT_GRAPHICS = 0,
    VK_PIPELINE_BIND_POINT_COMPUTE = 1,
} VkPipelineBindPoint;

    • VK_PIPELINE_BIND_POINT_COMPUTE specifies binding as a compute pipeline.

    • VK_PIPELINE_BIND_POINT_GRAPHICS specifies binding as a graphics pipeline.

    10.9. Dynamic State

    When a pipeline object is bound, any pipeline object state that is not specified as dynamic is applied to the command buffer state. Pipeline object state that is specified as dynamic is not applied to the command buffer state at this time. Instead, dynamic state can be modified at any time and persists for the lifetime of the command buffer, or until modified by another dynamic state setting command, or made invalid by another pipeline bind with that state specified as static.

    When a pipeline object is bound, the following applies to each state parameter:

    • If the state is not specified as dynamic in the new pipeline object, then that command buffer state is overwritten by the state in the new pipeline object. Before any draw or dispatch call with this pipeline there must not have been any calls to any of the corresponding dynamic state setting commands after this pipeline was bound.

    • If the state is specified as dynamic in the new pipeline object, then that command buffer state is not disturbed. Before any draw or dispatch call with this pipeline there must have been at least one call to each of the corresponding dynamic state setting commands. The state-setting commands must be recorded after command buffer recording was begun, or after the last command binding a pipeline object with that state specified as static, whichever was the latter.

    • If the state is not included (corresponding pointer in VkGraphicsPipelineCreateInfo was NULL or was ignored) in the new pipeline object, then that command buffer state is not disturbed.

    Dynamic state that does not affect the result of operations can be left undefined.

    Note

    For example, if blending is disabled by the pipeline object state then the dynamic color blend constants do not need to be specified in the command buffer, even if this state is specified as dynamic in the pipeline object.
    Note

    Applications running on Vulkan implementations advertising an VkPhysicalDeviceDriverProperties::conformanceVersion less than 1.3.8.0 should be aware that rebinding the currently bound pipeline object may not reapply static state.

    10.10. Pipeline Creation Feedback

    Feedback about the creation of a particular pipeline object can be obtained by adding a VkPipelineCreationFeedbackCreateInfo structure to the pNext chain of VkGraphicsPipelineCreateInfo, or VkComputePipelineCreateInfo. The VkPipelineCreationFeedbackCreateInfo structure is defined as:

    // Provided by VK_VERSION_1_3
typedef struct VkPipelineCreationFeedbackCreateInfo {
    VkStructureType                sType;
    const void*                    pNext;
    VkPipelineCreationFeedback*    pPipelineCreationFeedback;
    uint32_t                       pipelineStageCreationFeedbackCount;
    VkPipelineCreationFeedback*    pPipelineStageCreationFeedbacks;
} VkPipelineCreationFeedbackCreateInfo;

    • sType is a VkStructureType value identifying this structure.

    • pNext is NULL or a pointer to a structure extending this structure.

    • pPipelineCreationFeedback is a pointer to a VkPipelineCreationFeedback structure.

    • pipelineStageCreationFeedbackCount is the number of elements in pPipelineStageCreationFeedbacks.

    • pPipelineStageCreationFeedbacks is a pointer to an array of pipelineStageCreationFeedbackCount VkPipelineCreationFeedback structures.

    An implementation should write pipeline creation feedback to pPipelineCreationFeedback and may write pipeline stage creation feedback to pPipelineStageCreationFeedbacks. An implementation must set or clear the VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT in VkPipelineCreationFeedback::flags for pPipelineCreationFeedback and every element of pPipelineStageCreationFeedbacks.

    Note

    One common scenario for an implementation to skip per-stage feedback is when VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT is set in pPipelineCreationFeedback.

    When chained to VkGraphicsPipelineCreateInfo, the i element of pPipelineStageCreationFeedbacks corresponds to the i element of VkGraphicsPipelineCreateInfo::pStages. When chained to VkComputePipelineCreateInfo, the first element of pPipelineStageCreationFeedbacks corresponds to VkComputePipelineCreateInfo::stage.

    Valid Usage (Implicit)

    • VUID-VkPipelineCreationFeedbackCreateInfo-sType-sType
      sType must be VK_STRUCTURE_TYPE_PIPELINE_CREATION_FEEDBACK_CREATE_INFO

    • VUID-VkPipelineCreationFeedbackCreateInfo-pPipelineCreationFeedback-parameter
      pPipelineCreationFeedback must be a valid pointer to a VkPipelineCreationFeedback structure

    • VUID-VkPipelineCreationFeedbackCreateInfo-pPipelineStageCreationFeedbacks-parameter
      If pipelineStageCreationFeedbackCount is not 0, pPipelineStageCreationFeedbacks must be a valid pointer to an array of pipelineStageCreationFeedbackCount VkPipelineCreationFeedback structures

    The VkPipelineCreationFeedback structure is defined as:

    // Provided by VK_VERSION_1_3
typedef struct VkPipelineCreationFeedback {
    VkPipelineCreationFeedbackFlags    flags;
    uint64_t                           duration;
} VkPipelineCreationFeedback;

    • flags is a bitmask of VkPipelineCreationFeedbackFlagBits providing feedback about the creation of a pipeline or of a pipeline stage.

    • duration is the duration spent creating a pipeline or pipeline stage in nanoseconds.

    If the VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT is not set in flags, an implementation must not set any other bits in flags, and the values of all other VkPipelineCreationFeedback data members are undefined.

    Possible values of the flags member of VkPipelineCreationFeedback are:

    // Provided by VK_VERSION_1_3
typedef enum VkPipelineCreationFeedbackFlagBits {
    VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT = 0x00000001,
    VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT = 0x00000002,
    VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT = 0x00000004,
    VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT,
    VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT,
    VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT_EXT = VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT,
} VkPipelineCreationFeedbackFlagBits;

    • VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT indicates that the feedback information is valid.

    • VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT indicates that a readily usable pipeline or pipeline stage was found in the pipelineCache specified by the application in the pipeline creation command.

      An implementation should set the VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT bit if it was able to avoid the large majority of pipeline or pipeline stage creation work by using the pipelineCache parameter of vkCreateGraphicsPipelines, or vkCreateComputePipelines. When an implementation sets this bit for the entire pipeline, it may leave it unset for any stage.

      Note

      Implementations are encouraged to provide a meaningful signal to applications using this bit. The intention is to communicate to the application that the pipeline or pipeline stage was created “as fast as it gets” using the pipeline cache provided by the application. If an implementation uses an internal cache, it is discouraged from setting this bit as the feedback would be unactionable.

    • VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT indicates that the base pipeline specified by the basePipelineHandle or basePipelineIndex member of the Vk*PipelineCreateInfo structure was used to accelerate the creation of the pipeline.

      An implementation should set the VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT bit if it was able to avoid a significant amount of work by using the base pipeline.

      Note

      While “significant amount of work” is subjective, implementations are encouraged to provide a meaningful signal to applications using this bit. For example, a 1% reduction in duration may not warrant setting this bit, while a 50% reduction would.

      		 
    // Provided by VK_VERSION_1_3
typedef VkFlags VkPipelineCreationFeedbackFlags;

    VkPipelineCreationFeedbackFlags is a bitmask type for providing zero or more VkPipelineCreationFeedbackFlagBits.