// Copyright 2015-2021 The Khronos Group, Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[pipelines]]
= Pipelines

The following <<pipelines-block-diagram,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_,
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
a _ray tracing pipeline_,
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
or a _compute pipeline_.

ifdef::VK_NV_mesh_shader[]
The graphics pipeline can be operated in two modes, as either _primitive
shading_ or _mesh shading_ pipeline.

*Primitive Shading*

endif::VK_NV_mesh_shader[]

The first stage of the <<pipelines-graphics,graphics pipeline>>
(<<drawing,Input Assembler>>) assembles vertices to form geometric
primitives such as points, lines, and triangles, based on a requested
primitive topology.
In the next stage (<<shaders-vertex,Vertex Shader>>) vertices can: be
transformed, computing positions and attributes for each vertex.
If <<tessellation,tessellation>> and/or <<geometry,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.

ifdef::VK_NV_mesh_shader[]
*Mesh Shading*

When using the <<mesh,_mesh shading_>> pipeline input primitives are not
assembled implicitly, but explicitly through the (<<shaders-mesh,Mesh
Shader>>).
The work on the mesh pipeline is initiated by the application
<<drawing-mesh-shading,drawing>> a set of mesh tasks.

If an optional (<<shaders-task,Task Shader>>) is active, each task triggers
the execution of a task shader workgroup that will generate a new set of
tasks upon completion.
Each of these spawned tasks, or each of the original dispatched tasks if no
task shader is present, triggers the execution of a mesh shader workgroup
that produces an output mesh with a variable-sized number of primitives
assembled from vertices stored in the output mesh.

*Common*
endif::VK_NV_mesh_shader[]

The final resulting primitives are <<vertexpostproc-clipping,clipped>> to a
clip volume in preparation for the next stage, <<primsrast,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 <<fragops,fragment operations>> to
determine whether generated values will be written to the framebuffer.
<<shaders-fragment, 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 <<renderpass,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 <<pipelines-compute,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-pipeline-stages-order, synchronization chapter>>.

[[pipelines-block-diagram]]
ifndef::VK_NV_mesh_shader[]
image::{images}/pipeline.svg[title="Block diagram of the Vulkan pipeline",align="center",opts="{imageopts}"]
endif::VK_NV_mesh_shader[]
ifdef::VK_NV_mesh_shader[]
image::{images}/pipelinemesh.svg[title="Block diagram of the Vulkan pipeline",align="center",opts="{imageopts}"]
endif::VK_NV_mesh_shader[]

Each pipeline is controlled by a monolithic object created from a
description of all of the shader stages and any relevant fixed-function
stages.
<<interfaces,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
flink:vkCmdBindPipeline.
Any pipeline object state that is specified as <<pipelines-dynamic-state,
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.


[open,refpage='VkPipeline',desc='Opaque handle to a pipeline object',type='handles']
--
Compute,
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
ray tracing,
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
and graphics pipelines are each represented by sname:VkPipeline handles:

include::{generated}/api/handles/VkPipeline.txt[]
--


[[pipelines-compute]]
== 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
fname:vkCreateComputePipelines with pname:module and pname:pName selecting
an entry point from a shader module, where that entry point defines a valid
compute shader, in the slink:VkPipelineShaderStageCreateInfo structure
contained within the slink:VkComputePipelineCreateInfo structure.

[open,refpage='vkCreateComputePipelines',desc='Creates a new compute pipeline object',type='protos']
--
To create compute pipelines, call:

include::{generated}/api/protos/vkCreateComputePipelines.txt[]

  * pname:device is the logical device that creates the compute pipelines.
  * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that
    pipeline caching is disabled; or the handle of a valid
    <<pipelines-cache,pipeline cache>> object, in which case use of that
    cache is enabled for the duration of the command.
  * pname:createInfoCount is the length of the pname:pCreateInfos and
    pname:pPipelines arrays.
  * pname:pCreateInfos is a pointer to an array of
    slink:VkComputePipelineCreateInfo structures.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.
  * pname:pPipelines is a pointer to an array of slink:VkPipeline handles in
    which the resulting compute pipeline objects are returned.
ifdef::editing-notes[]
+
[NOTE]
.editing-note
====
TODO (Jon) - Should we say something like "`the i'th element of the
pname:pPipelines array is created based on the corresponding element of the
pname:pCreateInfos array`"? Also for flink:vkCreateGraphicsPipelines below.
====
endif::editing-notes[]

.Valid Usage
****
  * [[VUID-vkCreateComputePipelines-flags-00695]]
    If the pname:flags member of any element of pname:pCreateInfos contains
    the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the
    pname:basePipelineIndex member of that same element is not `-1`,
    pname:basePipelineIndex must: be less than the index into
    pname:pCreateInfos that corresponds to that element
  * [[VUID-vkCreateComputePipelines-flags-00696]]
    If the pname:flags member of any element of pname:pCreateInfos contains
    the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline
    must: have been created with the
    ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set
ifdef::VK_EXT_pipeline_creation_cache_control[]
  * [[VUID-vkCreateComputePipelines-pipelineCache-02873]]
    If pname:pipelineCache was created with
    ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT, host
    access to pname:pipelineCache must: be
    <<fundamentals-threadingbehavior,externally synchronized>>
endif::VK_EXT_pipeline_creation_cache_control[]
****

include::{generated}/validity/protos/vkCreateComputePipelines.txt[]
--

[open,refpage='VkComputePipelineCreateInfo',desc='Structure specifying parameters of a newly created compute pipeline',type='structs']
--
The sname:VkComputePipelineCreateInfo structure is defined as:

include::{generated}/api/structs/VkComputePipelineCreateInfo.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying
    how the pipeline will be generated.
  * pname:stage is a slink:VkPipelineShaderStageCreateInfo structure
    describing the compute shader.
  * pname:layout is the description of binding locations used by both the
    pipeline and descriptor sets used with the pipeline.
  * pname:basePipelineHandle is a pipeline to derive from
  * pname:basePipelineIndex is an index into the pname:pCreateInfos
    parameter to use as a pipeline to derive from

The parameters pname:basePipelineHandle and pname:basePipelineIndex are
described in more detail in <<pipelines-pipeline-derivatives,Pipeline
Derivatives>>.

.Valid Usage
****
  * [[VUID-VkComputePipelineCreateInfo-flags-00697]]
    If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
    flag, and pname:basePipelineIndex is -1, pname:basePipelineHandle must:
    be a valid handle to a compute sname:VkPipeline
  * [[VUID-VkComputePipelineCreateInfo-flags-00698]]
    If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
    flag, and pname:basePipelineHandle is dlink:VK_NULL_HANDLE,
    pname:basePipelineIndex must: be a valid index into the calling
    command's pname:pCreateInfos parameter
  * [[VUID-VkComputePipelineCreateInfo-flags-00699]]
    If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
    flag, and pname:basePipelineIndex is not -1, pname:basePipelineHandle
    must: be dlink:VK_NULL_HANDLE
  * [[VUID-VkComputePipelineCreateInfo-flags-00700]]
    If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
    flag, and pname:basePipelineHandle is not dlink:VK_NULL_HANDLE,
    pname:basePipelineIndex must: be -1
  * [[VUID-VkComputePipelineCreateInfo-stage-00701]]
    The pname:stage member of pname:stage must: be
    ename:VK_SHADER_STAGE_COMPUTE_BIT
  * [[VUID-VkComputePipelineCreateInfo-stage-00702]]
    The shader code for the entry point identified by pname:stage and the
    rest of the state identified by this structure must: adhere to the
    pipeline linking rules described in the <<interfaces,Shader Interfaces>>
    chapter
  * [[VUID-VkComputePipelineCreateInfo-layout-00703]]
    pname:layout must: be
    <<descriptorsets-pipelinelayout-consistency,consistent>> with the layout
    of the compute shader specified in pname:stage
  * [[VUID-VkComputePipelineCreateInfo-layout-01687]]
    The number of resources in pname:layout accessible to the compute shader
    stage must: be less than or equal to
    sname:VkPhysicalDeviceLimits::pname:maxPerStageResources
ifdef::VK_KHR_pipeline_library[]
  * [[VUID-VkComputePipelineCreateInfo-flags-03364]]
    pname:flags must: not include ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
endif::VK_KHR_pipeline_library[]
ifdef::VK_KHR_ray_tracing_pipeline[]
  * [[VUID-VkComputePipelineCreateInfo-flags-03365]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR
  * [[VUID-VkComputePipelineCreateInfo-flags-03366]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR
  * [[VUID-VkComputePipelineCreateInfo-flags-03367]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR
  * [[VUID-VkComputePipelineCreateInfo-flags-03368]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR
  * [[VUID-VkComputePipelineCreateInfo-flags-03369]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
  * [[VUID-VkComputePipelineCreateInfo-flags-03370]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
  * [[VUID-VkComputePipelineCreateInfo-flags-03576]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
endif::VK_KHR_ray_tracing_pipeline[]
ifdef::VK_NV_ray_tracing_motion_blur[]
  * [[VUID-VkComputePipelineCreateInfo-flags-04945]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV
endif::VK_NV_ray_tracing_motion_blur[]
ifdef::VK_NV_device_generated_commands[]
  * [[VUID-VkComputePipelineCreateInfo-flags-02874]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV
endif::VK_NV_device_generated_commands[]
ifdef::VK_EXT_pipeline_creation_cache_control[]
  * [[VUID-VkComputePipelineCreateInfo-pipelineCreationCacheControl-02875]]
    If the <<features-pipelineCreationCacheControl,
    pname:pipelineCreationCacheControl>> feature is not enabled, pname:flags
    must: not include
    ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT or
    ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT
endif::VK_EXT_pipeline_creation_cache_control[]
****

include::{generated}/validity/structs/VkComputePipelineCreateInfo.txt[]
--

[open,refpage='VkPipelineShaderStageCreateInfo',desc='Structure specifying parameters of a newly created pipeline shader stage',type='structs']
--
The sname:VkPipelineShaderStageCreateInfo structure is defined as:

include::{generated}/api/structs/VkPipelineShaderStageCreateInfo.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is a bitmask of elink:VkPipelineShaderStageCreateFlagBits
    specifying how the pipeline shader stage will be generated.
  * pname:stage is a elink:VkShaderStageFlagBits value specifying a single
    pipeline stage.
  * pname:module is a slink:VkShaderModule object containing the shader for
    this stage.
  * pname:pName is a pointer to a null-terminated UTF-8 string specifying
    the entry point name of the shader for this stage.
  * pname:pSpecializationInfo is a pointer to a slink:VkSpecializationInfo
    structure, as described in
    <<pipelines-specialization-constants,Specialization Constants>>, or
    `NULL`.

.Valid Usage
****
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-00704]]
    If the <<features-geometryShader,geometry shaders>> feature is not
    enabled, pname:stage must: not be ename:VK_SHADER_STAGE_GEOMETRY_BIT
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-00705]]
    If the <<features-tessellationShader,tessellation shaders>> feature is
    not enabled, pname:stage must: not be
    ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or
    ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT
ifdef::VK_NV_mesh_shader[]
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-02091]]
    If the <<features-meshShader,mesh shader>> feature is not enabled,
    pname:stage must: not be ename:VK_SHADER_STAGE_MESH_BIT_NV
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-02092]]
    If the <<features-taskShader,task shader>> feature is not enabled,
    pname:stage must: not be ename:VK_SHADER_STAGE_TASK_BIT_NV
endif::VK_NV_mesh_shader[]
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-00706]]
    pname:stage must: not be ename:VK_SHADER_STAGE_ALL_GRAPHICS, or
    ename:VK_SHADER_STAGE_ALL
  * [[VUID-VkPipelineShaderStageCreateInfo-pName-00707]]
    pname:pName must: be the name of an code:OpEntryPoint in pname:module
    with an execution model that matches pname:stage
  * [[VUID-VkPipelineShaderStageCreateInfo-maxClipDistances-00708]]
    If the identified entry point includes any variable in its interface
    that is declared with the code:ClipDistance code:BuiltIn decoration,
    that variable must: not have an array size greater than
    sname:VkPhysicalDeviceLimits::pname:maxClipDistances
  * [[VUID-VkPipelineShaderStageCreateInfo-maxCullDistances-00709]]
    If the identified entry point includes any variable in its interface
    that is declared with the code:CullDistance code:BuiltIn decoration,
    that variable must: not have an array size greater than
    sname:VkPhysicalDeviceLimits::pname:maxCullDistances
  * [[VUID-VkPipelineShaderStageCreateInfo-maxCombinedClipAndCullDistances-00710]]
    If the identified entry point includes any variables in its interface
    that are declared with the code:ClipDistance or code:CullDistance
    code:BuiltIn decoration, those variables must: not have array sizes
    which sum to more than
    sname:VkPhysicalDeviceLimits::pname:maxCombinedClipAndCullDistances
  * [[VUID-VkPipelineShaderStageCreateInfo-maxSampleMaskWords-00711]]
    If the identified entry point includes any variable in its interface
    that is declared with the code:SampleMask code:BuiltIn decoration, that
    variable must: not have an array size greater than
    sname:VkPhysicalDeviceLimits::pname:maxSampleMaskWords
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-00712]]
    If pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT, the identified entry
    point must: not include any input variable in its interface that is
    decorated with code:CullDistance
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-00713]]
    If pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or
    ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and the identified
    entry point has an code:OpExecutionMode instruction that specifies a
    patch size with code:OutputVertices, the patch size must: be greater
    than `0` and less than or equal to
    sname:VkPhysicalDeviceLimits::pname:maxTessellationPatchSize
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-00714]]
    If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, the identified
    entry point must: have an code:OpExecutionMode instruction that
    specifies a maximum output vertex count that is greater than `0` and
    less than or equal to
    sname:VkPhysicalDeviceLimits::pname:maxGeometryOutputVertices
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-00715]]
    If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, the identified
    entry point must: have an code:OpExecutionMode instruction that
    specifies an invocation count that is greater than `0` and less than or
    equal to
    sname:VkPhysicalDeviceLimits::pname:maxGeometryShaderInvocations
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-02596]]
    If pname:stage is a
    <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader
    stage>>, and the identified entry point writes to code:Layer for any
    primitive, it must: write the same value to code:Layer for all vertices
    of a given primitive
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-02597]]
    If pname:stage is a
    <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader
    stage>>, and the identified entry point writes to code:ViewportIndex for
    any primitive, it must: write the same value to code:ViewportIndex for
    all vertices of a given primitive
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-00718]]
    If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, the identified
    entry point must: not include any output variables in its interface
    decorated with code:CullDistance
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-00719]]
    If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, and the identified
    entry point writes to code:FragDepth in any execution path, it must:
    write to code:FragDepth in all execution paths
ifdef::VK_EXT_shader_stencil_export[]
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-01511]]
    If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, and the identified
    entry point writes to code:FragStencilRefEXT in any execution path, it
    must: write to code:FragStencilRefEXT in all execution paths
endif::VK_EXT_shader_stencil_export[]
ifdef::VK_NV_mesh_shader[]
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-02093]]
    If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_NV, the identified
    entry point must: have an code:OpExecutionMode instruction that
    specifies a maximum output vertex count, code:OutputVertices, that is
    greater than `0` and less than or equal to
    sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputVertices
  * [[VUID-VkPipelineShaderStageCreateInfo-stage-02094]]
    If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_NV, the identified
    entry point must: have an code:OpExecutionMode instruction that
    specifies a maximum output primitive count, code:OutputPrimitivesNV,
    that is greater than `0` and less than or equal to
    sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputPrimitives
endif::VK_NV_mesh_shader[]
ifdef::VK_EXT_subgroup_size_control[]
  * [[VUID-VkPipelineShaderStageCreateInfo-flags-02784]]
    If pname:flags has the
    ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT
    flag set, the <<features-subgroupSizeControl,
    pname:subgroupSizeControl>> feature must: be enabled
  * [[VUID-VkPipelineShaderStageCreateInfo-flags-02785]]
    If pname:flags has the
    ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT
    flag set, the <<features-computeFullSubgroups,
    pname:computeFullSubgroups>> feature must: be enabled
  * [[VUID-VkPipelineShaderStageCreateInfo-pNext-02754]]
    If a slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT
    structure is included in the pname:pNext chain, pname:flags must: not
    have the
    ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT
    flag set
  * [[VUID-VkPipelineShaderStageCreateInfo-pNext-02755]]
    If a slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT
    structure is included in the pname:pNext chain, the
    <<features-subgroupSizeControl, pname:subgroupSizeControl>> feature
    must: be enabled, and pname:stage must: be a valid bit specified in
    <<limits-required-subgroup-size-stages,
    pname:requiredSubgroupSizeStages>>
  * [[VUID-VkPipelineShaderStageCreateInfo-pNext-02756]]
    If a slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT
    structure is included in the pname:pNext chain and pname:stage is
    ename:VK_SHADER_STAGE_COMPUTE_BIT, the local workgroup size of the
    shader must: be less than or equal to the product of
    slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT::pname:requiredSubgroupSize
    and
    <<limits-max-subgroups-per-workgroup,pname:maxComputeWorkgroupSubgroups>>
  * [[VUID-VkPipelineShaderStageCreateInfo-pNext-02757]]
    If a slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT
    structure is included in the pname:pNext chain, and pname:flags has the
    ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT
    flag set, the local workgroup size in the X dimension of the pipeline
    must: be a multiple of
    slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT::pname:requiredSubgroupSize
  * [[VUID-VkPipelineShaderStageCreateInfo-flags-02758]]
    If pname:flags has both the
    ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT and
    ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT
    flags set, the local workgroup size in the X dimension of the pipeline
    must: be a multiple of
    <<limits-max-subgroup-size,pname:maxSubgroupSize>>
  * [[VUID-VkPipelineShaderStageCreateInfo-flags-02759]]
    If pname:flags has the
    ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT
    flag set and pname:flags does not have the
    ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT
    flag set and no
    slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure
    is included in the pname:pNext chain, the local workgroup size in the X
    dimension of the pipeline must: be a multiple of
    <<limits-subgroup-size,pname:subgroupSize>>
endif::VK_EXT_subgroup_size_control[]
  * [[VUID-VkPipelineShaderStageCreateInfo-module-04145]]
    The SPIR-V code that was used to create pname:module must: be valid as
    described by the <<spirv-spec,Khronos SPIR-V Specification>> after
    applying the specializations provided in pname:pSpecializationInfo, if
    any, and then converting all specialization constants into fixed
    constants.
****

include::{generated}/validity/structs/VkPipelineShaderStageCreateInfo.txt[]
--

[open,refpage='VkPipelineShaderStageCreateFlags',desc='Bitmask of VkPipelineShaderStageCreateFlagBits',type='flags']
--
include::{generated}/api/flags/VkPipelineShaderStageCreateFlags.txt[]

tname:VkPipelineShaderStageCreateFlags is a bitmask type for setting a mask
of zero or more elink:VkPipelineShaderStageCreateFlagBits.
--

[open,refpage='VkPipelineShaderStageCreateFlagBits',desc='Bitmask controlling how a pipeline shader stage is created',type='enums']
--
Possible values of the pname:flags member of
slink:VkPipelineShaderStageCreateInfo specifying how a pipeline shader stage
is created, are:

include::{generated}/api/enums/VkPipelineShaderStageCreateFlagBits.txt[]

ifdef::VK_EXT_subgroup_size_control[]
  * ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT
    specifies that the
    <<interfaces-builtin-variables-sgs,code:SubgroupSize>> may: vary in the
    shader stage.
  * ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT
    specifies that the subgroup sizes must: be launched with all invocations
    active in the compute stage.

[NOTE]
.Note
====
If ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT
and ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT are
specified and <<limits-max-subgroup-size,pname:minSubgroupSize>> does not
equal <<limits-max-subgroup-size,pname:maxSubgroupSize>> and no
<<pipelines-required-subgroup-size, required subgroup size>> is specified,
then the only way to guarantee that the 'X' dimension of the local workgroup
size is a multiple of <<interfaces-builtin-variables-sgs,code:SubgroupSize>>
is to make it a multiple of pname:maxSubgroupSize.
Under these conditions, you are guaranteed full subgroups but not any
particular subgroup size.
====

endif::VK_EXT_subgroup_size_control[]
--

[open,refpage='VkShaderStageFlagBits',desc='Bitmask specifying a pipeline stage',type='enums']
--
Commands and structures which need to specify one or more shader stages do
so using a bitmask whose bits correspond to stages.
Bits which can: be set to specify shader stages are:

include::{generated}/api/enums/VkShaderStageFlagBits.txt[]

  * ename:VK_SHADER_STAGE_VERTEX_BIT specifies the vertex stage.
  * ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT specifies the
    tessellation control stage.
  * ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT specifies the
    tessellation evaluation stage.
  * ename:VK_SHADER_STAGE_GEOMETRY_BIT specifies the geometry stage.
  * ename:VK_SHADER_STAGE_FRAGMENT_BIT specifies the fragment stage.
  * ename:VK_SHADER_STAGE_COMPUTE_BIT specifies the compute stage.
  * ename:VK_SHADER_STAGE_ALL_GRAPHICS is a combination of bits used as
    shorthand to specify all graphics stages defined above (excluding the
    compute stage).
  * ename: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.
ifdef::VK_NV_mesh_shader[]
  * ename:VK_SHADER_STAGE_TASK_BIT_NV specifies the task stage.
  * ename:VK_SHADER_STAGE_MESH_BIT_NV specifies the mesh stage.
endif::VK_NV_mesh_shader[]
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
  * ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR specifies the ray generation stage.
  * ename:VK_SHADER_STAGE_ANY_HIT_BIT_KHR specifies the any-hit stage.
  * ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR specifies the closest hit
    stage.
  * ename:VK_SHADER_STAGE_MISS_BIT_KHR specifies the miss stage.
  * ename:VK_SHADER_STAGE_INTERSECTION_BIT_KHR specifies the intersection
    stage.
  * ename:VK_SHADER_STAGE_CALLABLE_BIT_KHR specifies the callable stage.
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]

[NOTE]
.Note
====
ename: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.
====
--

[open,refpage='VkShaderStageFlags',desc='Bitmask of VkShaderStageFlagBits',type='flags']
--
include::{generated}/api/flags/VkShaderStageFlags.txt[]

tname:VkShaderStageFlags is a bitmask type for setting a mask of zero or
more elink:VkShaderStageFlagBits.
--

ifdef::VK_EXT_subgroup_size_control[]
[open,refpage='VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT',desc='Structure specifying the required subgroup size of a newly created pipeline shader stage',type='structs']
--
The sname:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure
is defined as:

include::{generated}/api/structs/VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT.txt[]
  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * [[pipelines-required-subgroup-size]] pname:requiredSubgroupSize is an
    unsigned integer value that specifies the required subgroup size for the
    newly created pipeline shader stage.

.Valid Usage
****
  * [[VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT-requiredSubgroupSize-02760]]
    pname:requiredSubgroupSize must: be a power-of-two integer
  * [[VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT-requiredSubgroupSize-02761]]
    pname:requiredSubgroupSize must: be greater or equal to
    <<limits-min-subgroup-size,minSubgroupSize>>
  * [[VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT-requiredSubgroupSize-02762]]
    pname:requiredSubgroupSize must: be less than or equal to
    <<limits-max-subgroup-size,maxSubgroupSize>>
****


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

include::{generated}/validity/structs/VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT.txt[]
--
endif::VK_EXT_subgroup_size_control[]

ifdef::VK_HUAWEI_subpass_shading[]
[open,refpage='VkSubpassShadingPipelineCreateInfoHUAWEI',desc='Structure specifying parameters of a newly created subpass shading pipeline',type='structs']
--
A subpass shading pipeline is a compute pipeline which must: be called only
in a subpass of a render pass with work dimensions specified by render area
size.
The subpass shading pipeline shader is a compute shader allowed to access
input attachments specified in the calling subpass.
To create a subpass shading pipeline, call flink:vkCreateComputePipelines
with slink:VkSubpassShadingPipelineCreateInfoHUAWEI in the pname:pNext chain
of slink:VkComputePipelineCreateInfo.

The sname:VkSubpassShadingPipelineCreateInfoHUAWEI structure is defined as:

include::{generated}/api/structs/VkSubpassShadingPipelineCreateInfoHUAWEI.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname: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 an instance of any render pass compatible with the one
    provided.
    See <<renderpass-compatibility,Render Pass Compatibility>> for more
    information.
  * pname:subpass is the index of the subpass in the render pass where this
    pipeline will be used.

.Valid Usage
****
  * [[VUID-VkSubpassShadingPipelineCreateInfoHUAWEI-subpass-04946]]
    pname:subpass must: be created with
    VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI bind point.
****

include::{generated}/validity/structs/VkSubpassShadingPipelineCreateInfoHUAWEI.txt[]
--

[open,refpage='vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI',desc='Query maximum supported subpass shading workgroup size for a give render pass',type='protos']
--
A subpass shading pipeline's workgroup size is a 2D vector with number of
power-of-two in width and height.
The maximum number of width and height is implementation dependent, and may:
vary for different formats and sample counts of attachments in a render
pass.

To query the maximum workgroup size, call:

include::{generated}/api/protos/vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI.txt[]

  * pname:device is a handle to a local device object that was used to
    create the given render pass.
  * pname: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 an instance of any render pass compatible with the one
    provided.
    See <<renderpass-compatibility,Render Pass Compatibility>> for more
    information.
  * pname:pMaxWorkgroupSize is a pointer to a slink:VkExtent2D structure.

include::{generated}/validity/protos/vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI.txt[]
--
endif::VK_HUAWEI_subpass_shading[]


[[pipelines-graphics]]
== Graphics Pipelines

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

[open,refpage='vkCreateGraphicsPipelines',desc='Create graphics pipelines',type='protos']
--
To create graphics pipelines, call:

include::{generated}/api/protos/vkCreateGraphicsPipelines.txt[]

  * pname:device is the logical device that creates the graphics pipelines.
  * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that
    pipeline caching is disabled; or the handle of a valid
    <<pipelines-cache,pipeline cache>> object, in which case use of that
    cache is enabled for the duration of the command.
  * pname:createInfoCount is the length of the pname:pCreateInfos and
    pname:pPipelines arrays.
  * pname:pCreateInfos is a pointer to an array of
    slink:VkGraphicsPipelineCreateInfo structures.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.
  * pname:pPipelines is a pointer to an array of slink:VkPipeline handles in
    which the resulting graphics pipeline objects are returned.

The slink:VkGraphicsPipelineCreateInfo structure includes an array of
slink: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.

.Valid Usage
****
  * [[VUID-vkCreateGraphicsPipelines-flags-00720]]
    If the pname:flags member of any element of pname:pCreateInfos contains
    the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the
    pname:basePipelineIndex member of that same element is not `-1`,
    pname:basePipelineIndex must: be less than the index into
    pname:pCreateInfos that corresponds to that element
  * [[VUID-vkCreateGraphicsPipelines-flags-00721]]
    If the pname:flags member of any element of pname:pCreateInfos contains
    the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline
    must: have been created with the
    ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set
ifdef::VK_EXT_pipeline_creation_cache_control[]
  * [[VUID-vkCreateGraphicsPipelines-pipelineCache-02876]]
    If pname:pipelineCache was created with
    ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT, host
    access to pname:pipelineCache must: be
    <<fundamentals-threadingbehavior,externally synchronized>>
endif::VK_EXT_pipeline_creation_cache_control[]
****

ifdef::VK_EXT_pipeline_creation_cache_control[]
[NOTE]
.Note
====
An implicit cache may be provided by the implementation or a layer.
For this reason, it is still valid to set
ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT on
pname:flags for any element of pname:pCreateInfos while passing
dlink:VK_NULL_HANDLE for pname:pipelineCache.
====
endif::VK_EXT_pipeline_creation_cache_control[]

include::{generated}/validity/protos/vkCreateGraphicsPipelines.txt[]
--

[open,refpage='VkGraphicsPipelineCreateInfo',desc='Structure specifying parameters of a newly created graphics pipeline',type='structs']
--
The sname:VkGraphicsPipelineCreateInfo structure is defined as:

include::{generated}/api/structs/VkGraphicsPipelineCreateInfo.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying
    how the pipeline will be generated.
  * pname:stageCount is the number of entries in the pname:pStages array.
  * pname:pStages is a pointer to an array of pname:stageCount
    slink:VkPipelineShaderStageCreateInfo structures describing the set of
    the shader stages to be included in the graphics pipeline.
  * pname:pVertexInputState is a pointer to a
    slink:VkPipelineVertexInputStateCreateInfo structure.
ifdef::VK_NV_mesh_shader[]
    It is ignored if the pipeline includes a mesh shader stage.
endif::VK_NV_mesh_shader[]
ifdef::VK_EXT_vertex_input_dynamic_state[]
    It is ignored if the pipeline is created with the
    ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state set.
endif::VK_EXT_vertex_input_dynamic_state[]
  * pname:pInputAssemblyState is a pointer to a
    slink:VkPipelineInputAssemblyStateCreateInfo structure which determines
    input assembly behavior, as described in <<drawing, Drawing Commands>>.
ifdef::VK_NV_mesh_shader[]
    It is ignored if the pipeline includes a mesh shader stage.
endif::VK_NV_mesh_shader[]
  * pname:pTessellationState is a pointer to a
    slink:VkPipelineTessellationStateCreateInfo structure, and is ignored if
    the pipeline does not include a tessellation control shader stage and
    tessellation evaluation shader stage.
  * pname:pViewportState is a pointer to a
    slink:VkPipelineViewportStateCreateInfo structure, and is ignored if the
    pipeline has rasterization disabled.
  * pname:pRasterizationState is a pointer to a
    slink:VkPipelineRasterizationStateCreateInfo structure.
  * pname:pMultisampleState is a pointer to a
    slink:VkPipelineMultisampleStateCreateInfo structure, and is ignored if
    the pipeline has rasterization disabled.
  * pname:pDepthStencilState is a pointer to a
    slink:VkPipelineDepthStencilStateCreateInfo structure, and is ignored if
    the pipeline has rasterization disabled or if the subpass of the render
    pass the pipeline is created against does not use a depth/stencil
    attachment.
  * pname:pColorBlendState is a pointer to a
    slink:VkPipelineColorBlendStateCreateInfo structure, and is ignored if
    the pipeline has rasterization disabled or if the subpass of the render
    pass the pipeline is created against does not use any color attachments.
  * pname:pDynamicState is a pointer to a
    slink:VkPipelineDynamicStateCreateInfo structure, and is used to
    indicate 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.
  * pname:layout is the description of binding locations used by both the
    pipeline and descriptor sets used with the pipeline.
  * pname: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 an instance of any render pass compatible with the one
    provided.
    See <<renderpass-compatibility,Render Pass Compatibility>> for more
    information.
  * pname:subpass is the index of the subpass in the render pass where this
    pipeline will be used.
  * pname:basePipelineHandle is a pipeline to derive from.
  * pname:basePipelineIndex is an index into the pname:pCreateInfos
    parameter to use as a pipeline to derive from.

The parameters pname:basePipelineHandle and pname:basePipelineIndex are
described in more detail in <<pipelines-pipeline-derivatives,Pipeline
Derivatives>>.

ifdef::VK_NV_glsl_shader[]
If any shader stage fails to compile,
ifdef::VK_EXT_debug_report[]
the compile log will be reported back to the application, and
endif::VK_EXT_debug_report[]
ename:VK_ERROR_INVALID_SHADER_NV will be generated.
endif::VK_NV_glsl_shader[]

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

[[pipeline-graphics-subsets-vertex-input]]
Vertex input state is defined by:

  * slink:VkPipelineVertexInputStateCreateInfo
  * slink:VkPipelineInputAssemblyStateCreateInfo

[[pipeline-graphics-subsets-pre-rasterization]]
Pre-rasterization shader state is defined by:

  * slink:VkPipelineShaderStageCreateInfo entries for:
  ** Vertex shaders
  ** Tessellation control shaders
  ** Tessellation evaluation shaders
  ** Geometry shaders
ifdef::VK_NV_mesh_shader[]
  ** Task shaders
  ** Mesh shaders
endif::VK_NV_mesh_shader[]
  * Within the slink:VkPipelineLayout, all bindings that affect the
    specified shader stages
  * slink:VkPipelineViewportStateCreateInfo
  * slink:VkPipelineRasterizationStateCreateInfo
  * slink:VkPipelineTessellationStateCreateInfo if tessellation stages are
    included.
  * slink:VkRenderPass and pname:subpass parameter
ifdef::VK_EXT_discard_rectangles[]
  * slink:VkPipelineDiscardRectangleStateCreateInfoEXT
endif::VK_EXT_discard_rectangles[]
ifdef::VK_KHR_fragment_shading_rate[]
  * slink:VkPipelineFragmentShadingRateStateCreateInfoKHR
ifdef::VK_NV_fragment_shading_rate_enums[]
  * slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV
endif::VK_NV_fragment_shading_rate_enums[]
endif::VK_KHR_fragment_shading_rate[]

[[pipeline-graphics-subsets-fragment-shader]]
Fragment shader state is defined by:

  * A slink:VkPipelineShaderStageCreateInfo entry for the fragment shader
  * Within the slink:VkPipelineLayout, all bindings that affect the fragment
    shader
  * slink:VkPipelineMultisampleStateCreateInfo
  * slink:VkPipelineDepthStencilStateCreateInfo
  * slink:VkRenderPass and pname:subpass parameter
ifdef::VK_KHR_fragment_shading_rate[]
  * slink:VkPipelineFragmentShadingRateStateCreateInfoKHR
ifdef::VK_NV_fragment_shading_rate_enums[]
  * slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV
endif::VK_NV_fragment_shading_rate_enums[]
endif::VK_KHR_fragment_shading_rate[]

[[pipeline-graphics-subsets-fragment-output]]
Fragment output state is defined by:

  * slink:VkPipelineColorBlendStateCreateInfo
  * The pname:alphaToCoverageEnable and pname:alphaToOneEnable members of
    slink:VkPipelineMultisampleStateCreateInfo.
  * slink:VkRenderPass and pname:subpass parameter

[[pipeline-graphics-subsets-complete]]
A complete graphics pipeline always includes
<<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
state>>, with other subsets included depending on that state.
If the <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization
shader state>> includes a vertex shader, then
<<pipeline-graphics-subsets-vertex-input, vertex input state>> is included
in a complete graphics pipeline.
If the value of
slink:VkPipelineRasterizationStateCreateInfo::pname:rasterizerDiscardEnable
in the <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization
shader state>> is ename:VK_FALSE
ifdef::VK_EXT_extended_dynamic_state2[]
or the ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT dynamic state is
enabled
endif::VK_EXT_extended_dynamic_state2[]
<<pipeline-graphics-subsets-fragment-shader, fragment shader state>> and
<<pipeline-graphics-subsets-fragment-output, fragment output interface
state>> is included in a complete graphics pipeline.

Pipelines must: be created with a complete set of pipeline state.

.Valid Usage
****
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-00722]]
    If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
    flag, and pname:basePipelineIndex is -1, pname:basePipelineHandle must:
    be a valid handle to a graphics sname:VkPipeline
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-00723]]
    If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
    flag, and pname:basePipelineHandle is dlink:VK_NULL_HANDLE,
    pname:basePipelineIndex must: be a valid index into the calling
    command's pname:pCreateInfos parameter
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-00724]]
    If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
    flag, and pname:basePipelineIndex is not -1, pname:basePipelineHandle
    must: be dlink:VK_NULL_HANDLE
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-00725]]
    If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
    flag, and pname:basePipelineHandle is not dlink:VK_NULL_HANDLE,
    pname:basePipelineIndex must: be -1
  * [[VUID-VkGraphicsPipelineCreateInfo-stage-00726]]
    The pname:stage member of each element of pname:pStages must: be unique
ifndef::VK_NV_mesh_shader[]
  * [[VUID-VkGraphicsPipelineCreateInfo-stage-00727]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> the pname:stage member of one element of pname:pStages must: be
    ename:VK_SHADER_STAGE_VERTEX_BIT
endif::VK_NV_mesh_shader[]
ifdef::VK_NV_mesh_shader[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02095]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> the geometric shader stages provided in pname:pStages must: be
    either from the mesh shading pipeline (pname:stage is
    ename:VK_SHADER_STAGE_TASK_BIT_NV or ename:VK_SHADER_STAGE_MESH_BIT_NV)
    or from the primitive shading pipeline (pname:stage is
    ename:VK_SHADER_STAGE_VERTEX_BIT,
    ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT,
    ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or
    ename:VK_SHADER_STAGE_GEOMETRY_BIT)
  * [[VUID-VkGraphicsPipelineCreateInfo-stage-02096]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> the pname:stage member of one element of pname:pStages must: be
    either ename:VK_SHADER_STAGE_VERTEX_BIT or
    ename:VK_SHADER_STAGE_MESH_BIT_NV
endif::VK_NV_mesh_shader[]
  * [[VUID-VkGraphicsPipelineCreateInfo-stage-00728]]
    The pname:stage member of each element of pname:pStages must: not be
    ename:VK_SHADER_STAGE_COMPUTE_BIT
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00729]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and pname:pStages includes a tessellation control shader stage,
    it must: include a tessellation evaluation shader stage
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00730]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and pname:pStages includes a tessellation evaluation shader
    stage, it must: include a tessellation control shader stage
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00731]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and pname:pStages includes a tessellation control shader stage
    and a tessellation evaluation shader stage, pname:pTessellationState
    must: be a valid pointer to a valid
    slink:VkPipelineTessellationStateCreateInfo structure
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00732]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and pname:pStages includes tessellation shader stages, the
    shader code of at least one stage must: contain an code:OpExecutionMode
    instruction that specifies the type of subdivision in the pipeline
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00733]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and pname:pStages includes tessellation shader stages, and the
    shader code of both stages contain an code:OpExecutionMode instruction
    that specifies the type of subdivision in the pipeline, they must: both
    specify the same subdivision mode
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00734]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and pname:pStages includes tessellation shader stages, the
    shader code of at least one stage must: contain an code:OpExecutionMode
    instruction that specifies the output patch size in the pipeline
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00735]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and pname:pStages includes tessellation shader stages, and the
    shader code of both contain an code:OpExecutionMode instruction that
    specifies the out patch size in the pipeline, they must: both specify
    the same patch size
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00736]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and pname:pStages includes tessellation shader stages, the
    pname:topology member of pname:pInputAssembly must: be
    ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST
  * [[VUID-VkGraphicsPipelineCreateInfo-topology-00737]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and the pname:topology member of pname:pInputAssembly is
    ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, pname:pStages must: include
    tessellation shader stages
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00738]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and pname:pStages includes a geometry shader stage, and does not
    include any tessellation shader stages, its shader code must: contain an
    code:OpExecutionMode instruction that specifies an input primitive type
    that is <<shaders-geometry-execution, compatible>> with the primitive
    topology specified in pname:pInputAssembly
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00739]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and pname:pStages includes a geometry shader stage, and also
    includes tessellation shader stages, its shader code must: contain an
    code:OpExecutionMode instruction that specifies an input primitive type
    that is <<shaders-geometry-execution, compatible>> with the primitive
    topology that is output by the tessellation stages
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00740]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and <<pipeline-graphics-subsets-fragment-shader, 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 code:PrimitiveID, then the geometry shader code must: write to a
    matching output variable, decorated with code:PrimitiveID, in all
    execution paths
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00741]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>> the
    fragment shader must: not read from any input attachment that is defined
    as ename:VK_ATTACHMENT_UNUSED in pname:subpass
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00742]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and multiple pre-rasterization shader stages are included in
    pname:pStages, the shader code for the entry points identified by those
    pname:pStages and the rest of the state identified by this structure
    must: adhere to the pipeline linking rules described in the
    <<interfaces,Shader Interfaces>> chapter
  * [[VUID-VkGraphicsPipelineCreateInfo-None-04889]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>>, the fragment shader and last
    <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader
    stage>> and any relevant state must: adhere to the pipeline linking
    rules described in the <<interfaces,Shader Interfaces>> chapter
  * [[VUID-VkGraphicsPipelineCreateInfo-subpass-04890]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and pname:subpass uses a depth/stencil attachment in pname:renderPass
    with a read-only layout for the depth aspect in the
    slink:VkAttachmentReference defined by pname:subpass, the
    pname:depthWriteEnable member of pname:pDepthStencilState must: be
    ename:VK_FALSE
  * [[VUID-VkGraphicsPipelineCreateInfo-subpass-04891]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and pname:subpass uses a depth/stencil attachment in pname:renderPass
    with a read-only layout for the stencil aspect in the
    slink:VkAttachmentReference defined by pname:subpass, the pname:failOp,
    pname:passOp and pname:depthFailOp members of each of the pname:front
    and pname:back members of pname:pDepthStencilState must: be
    ename:VK_STENCIL_OP_KEEP
  * [[VUID-VkGraphicsPipelineCreateInfo-blendEnable-04717]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-output, fragment output interface
    state>>, then for each color attachment in the subpass, if the
    <<potential-format-features,potential format features>> of the format of
    the corresponding attachment description do not contain
    ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT, then the
    pname:blendEnable member of the corresponding element of the
    pname:pAttachments member of pname:pColorBlendState must: be
    ename:VK_FALSE
  * [[VUID-VkGraphicsPipelineCreateInfo-attachmentCount-00746]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-output, fragment output interface
    state>>, and the subpass uses color attachments, the
    pname:attachmentCount member of pname:pColorBlendState must: be equal to
    the pname:colorAttachmentCount used to create pname:subpass
ifndef::VK_EXT_extended_dynamic_state[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00747]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and no element of the pname:pDynamicStates member of
    pname:pDynamicState is ename:VK_DYNAMIC_STATE_VIEWPORT, the
    pname:pViewports member of pname:pViewportState must: be a valid pointer
    to an array of pname:pViewportState->viewportCount valid
    sname:VkViewport structures
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00748]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and no element of the pname:pDynamicStates member of
    pname:pDynamicState is ename:VK_DYNAMIC_STATE_SCISSOR, the
    pname:pScissors member of pname:pViewportState must: be a valid pointer
    to an array of pname:pViewportState->scissorCount sname:VkRect2D
    structures
endif::VK_EXT_extended_dynamic_state[]
ifdef::VK_EXT_extended_dynamic_state[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04130]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and no element of the pname:pDynamicStates member of
    pname:pDynamicState is ename:VK_DYNAMIC_STATE_VIEWPORT or
    ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT, the pname:pViewports
    member of pname:pViewportState must: be a valid pointer to an array of
    pname:pViewportState->viewportCount valid sname:VkViewport structures
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04131]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and no element of the pname:pDynamicStates member of
    pname:pDynamicState is ename:VK_DYNAMIC_STATE_SCISSOR or
    ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT, the pname:pScissors
    member of pname:pViewportState must: be a valid pointer to an array of
    pname:pViewportState->scissorCount sname:VkRect2D structures
endif::VK_EXT_extended_dynamic_state[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00749]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and the wide lines feature is not enabled, and no element of
    the pname:pDynamicStates member of pname:pDynamicState is
    ename:VK_DYNAMIC_STATE_LINE_WIDTH, the pname:lineWidth member of
    pname:pRasterizationState must: be `1.0`
  * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00750]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and the pname:rasterizerDiscardEnable member of
    pname:pRasterizationState is ename:VK_FALSE, pname:pViewportState must:
    be a valid pointer to a valid slink:VkPipelineViewportStateCreateInfo
    structure
ifdef::VK_EXT_extended_dynamic_state2[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pViewportState-04892]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and the graphics pipeline state was created with the
    ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT dynamic state
    enabled, pname:pViewportState must: be a valid pointer to a valid
    slink:VkPipelineViewportStateCreateInfo structure
endif::VK_EXT_extended_dynamic_state2[]
  * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00751]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    pname:pMultisampleState must: be a valid pointer to a valid
    slink:VkPipelineMultisampleStateCreateInfo structure
  * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00752]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and pname:subpass uses a depth/stencil attachment,
    pname:pDepthStencilState must: be a valid pointer to a valid
    slink:VkPipelineDepthStencilStateCreateInfo structure
  * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00753]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-output, fragment output interface
    state>>, and pname:subpass uses color attachments,
    pname:pColorBlendState must: be a valid pointer to a valid
    slink:VkPipelineColorBlendStateCreateInfo structure
  * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-04493]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-output, fragment output interface
    state>>, pname:pColorBlendState->attachmentCount must: be greater than
    the index of all color attachments that are not
    ename:VK_ATTACHMENT_UNUSED for the pname:subpass index in
    pname:renderPass
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00754]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, the depth bias clamping feature is not enabled, no element of
    the pname:pDynamicStates member of pname:pDynamicState is
    ename:VK_DYNAMIC_STATE_DEPTH_BIAS, and the pname:depthBiasEnable member
    of pname:pRasterizationState is ename:VK_TRUE, the pname:depthBiasClamp
    member of pname:pRasterizationState must: be `0.0`
ifndef::VK_EXT_depth_range_unrestricted[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00755]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and no element of the pname:pDynamicStates member of pname:pDynamicState
    is ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS, and the
    pname:depthBoundsTestEnable member of pname:pDepthStencilState is
    ename:VK_TRUE, the pname:minDepthBounds and pname:maxDepthBounds members
    of pname:pDepthStencilState must: be between `0.0` and `1.0`, inclusive
endif::VK_EXT_depth_range_unrestricted[]
ifdef::VK_EXT_depth_range_unrestricted[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-02510]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and the `<<VK_EXT_depth_range_unrestricted>>` extension is not enabled
    and no element of the pname:pDynamicStates member of pname:pDynamicState
    is ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS, and the
    pname:depthBoundsTestEnable member of pname:pDepthStencilState is
    ename:VK_TRUE, the pname:minDepthBounds and pname:maxDepthBounds members
    of pname:pDepthStencilState must: be between `0.0` and `1.0`, inclusive
endif::VK_EXT_depth_range_unrestricted[]
ifdef::VK_EXT_sample_locations[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01521]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and no element of the pname:pDynamicStates member of pname:pDynamicState
    is ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT, and the
    pname:sampleLocationsEnable member of a
    slink:VkPipelineSampleLocationsStateCreateInfoEXT structure included in
    the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE,
    pname:sampleLocationsInfo.sampleLocationGridSize.width must: evenly
    divide
    slink:VkMultisamplePropertiesEXT::pname:sampleLocationGridSize.width as
    returned by flink:vkGetPhysicalDeviceMultisamplePropertiesEXT with a
    pname:samples parameter equaling pname:rasterizationSamples
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01522]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and no element of the pname:pDynamicStates member of pname:pDynamicState
    is ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT, and the
    pname:sampleLocationsEnable member of a
    slink:VkPipelineSampleLocationsStateCreateInfoEXT structure included in
    the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE,
    pname:sampleLocationsInfo.sampleLocationGridSize.height must: evenly
    divide
    slink:VkMultisamplePropertiesEXT::pname:sampleLocationGridSize.height as
    returned by flink:vkGetPhysicalDeviceMultisamplePropertiesEXT with a
    pname:samples parameter equaling pname:rasterizationSamples
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01523]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and no element of the pname:pDynamicStates member of pname:pDynamicState
    is ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT, and the
    pname:sampleLocationsEnable member of a
    slink:VkPipelineSampleLocationsStateCreateInfoEXT structure included in
    the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE,
    pname:sampleLocationsInfo.sampleLocationsPerPixel must: equal
    pname:rasterizationSamples
  * [[VUID-VkGraphicsPipelineCreateInfo-sampleLocationsEnable-01524]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and the pname:sampleLocationsEnable member of a
    slink:VkPipelineSampleLocationsStateCreateInfoEXT structure included in
    the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE, the
    fragment shader code must: not statically use the extended instruction
    code:InterpolateAtSample
endif::VK_EXT_sample_locations[]
  * [[VUID-VkGraphicsPipelineCreateInfo-layout-00756]]
    pname:layout must: be
    <<descriptorsets-pipelinelayout-consistency,consistent>> with all
    shaders specified in pname:pStages
  * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00757]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and neither the `<<VK_AMD_mixed_attachment_samples>>` nor the
    `<<VK_NV_framebuffer_mixed_samples>>` extensions are enabled, and if
    pname:subpass uses color and/or depth/stencil attachments, then the
    pname:rasterizationSamples member of pname:pMultisampleState must: be
    the same as the sample count for those subpass attachments
ifdef::VK_AMD_mixed_attachment_samples[]
  * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01505]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and the `<<VK_AMD_mixed_attachment_samples>>` extension is enabled, and
    if pname:subpass uses color and/or depth/stencil attachments, then the
    pname:rasterizationSamples member of pname:pMultisampleState must: equal
    the maximum of the sample counts of those subpass attachments
endif::VK_AMD_mixed_attachment_samples[]
ifdef::VK_NV_framebuffer_mixed_samples[]
  * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01411]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and the `<<VK_NV_framebuffer_mixed_samples>>` extension is enabled, and
    if pname:subpass has a depth/stencil attachment and depth test, stencil
    test, or depth bounds test are enabled, then the
    pname:rasterizationSamples member of pname:pMultisampleState must: be
    the same as the sample count of the depth/stencil attachment
  * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01412]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and the `<<VK_NV_framebuffer_mixed_samples>>` extension is enabled, and
    if pname:subpass has any color attachments, then the
    pname:rasterizationSamples member of pname:pMultisampleState must: be
    greater than or equal to the sample count for those subpass attachments
endif::VK_NV_framebuffer_mixed_samples[]
ifdef::VK_NV_coverage_reduction_mode[]
  * [[VUID-VkGraphicsPipelineCreateInfo-coverageReductionMode-02722]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    and the `<<VK_NV_coverage_reduction_mode>>` extension is enabled, the
    coverage reduction mode specified by
    slink:VkPipelineCoverageReductionStateCreateInfoNV::pname:coverageReductionMode,
    the pname:rasterizationSamples member of pname:pMultisampleState and the
    sample counts for the color and depth/stencil attachments (if the
    subpass has them) must: be a valid combination returned by
    fname:vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV
endif::VK_NV_coverage_reduction_mode[]
  * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00758]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>> and
    pname:subpass does not use any color and/or depth/stencil attachments,
    then the pname:rasterizationSamples member of pname:pMultisampleState
    must: follow the rules for a <<renderpass-noattachments, zero-attachment
    subpass>>
  * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00759]]
    pname:subpass must: be a valid subpass within pname:renderPass
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
  * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00760]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and the pname:renderPass has multiview enabled and
    pname:subpass has more than one bit set in the view mask and
    pname:multiviewTessellationShader is not enabled, then pname:pStages
    must: not include tessellation shaders
  * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00761]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and the pname:renderPass has multiview enabled and
    pname:subpass has more than one bit set in the view mask and
    pname:multiviewGeometryShader is not enabled, then pname:pStages must:
    not include a geometry shader
  * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00762]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and the pname:renderPass has multiview enabled and
    pname:subpass has more than one bit set in the view mask, shaders in the
    pipeline must: not write to the code:Layer built-in output
  * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00763]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and the pname:renderPass has multiview enabled, then all
    shaders must: not include variables decorated with the code:Layer
    built-in decoration in their interfaces
endif::VK_VERSION_1_1,VK_KHR_multiview[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-00764]]
    pname:flags must: not contain the ename:VK_PIPELINE_CREATE_DISPATCH_BASE
    flag
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2,VK_KHR_create_renderpass2[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-01565]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>> and
    an input attachment was referenced by an pname:aspectMask at
    pname:renderPass creation time, the fragment shader must: only read from
    the aspects that were specified for that input attachment
endif::VK_VERSION_1_1,VK_KHR_maintenance2,VK_KHR_create_renderpass2[]
  * [[VUID-VkGraphicsPipelineCreateInfo-layout-01688]]
    The number of resources in pname:layout accessible to each shader stage
    that is used by the pipeline must: be less than or equal to
    sname:VkPhysicalDeviceLimits::pname:maxPerStageResources
ifdef::VK_NV_clip_space_w_scaling[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01715]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and no element of the pname:pDynamicStates member of
    pname:pDynamicState is ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV, and
    the pname:viewportWScalingEnable member of a
    slink:VkPipelineViewportWScalingStateCreateInfoNV structure, included in
    the pname:pNext chain of pname:pViewportState, is ename:VK_TRUE, the
    pname:pViewportWScalings member of the
    slink:VkPipelineViewportWScalingStateCreateInfoNV must: be a pointer to
    an array of
    slink:VkPipelineViewportWScalingStateCreateInfoNV::pname:viewportCount
    valid slink:VkViewportWScalingNV structures
endif::VK_NV_clip_space_w_scaling[]
ifdef::VK_NV_scissor_exclusive[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04056]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and no element of the pname:pDynamicStates member of
    pname:pDynamicState is ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV, and
    if pname:pViewportState->pNext chain includes a
    slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV structure, and
    if its pname:exclusiveScissorCount member is not `0`, then its
    pname:pExclusiveScissors member must: be a valid pointer to an array of
    pname:exclusiveScissorCount slink:VkRect2D structures
endif::VK_NV_scissor_exclusive[]
ifdef::VK_NV_shading_rate_image[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04057]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and no element of the pname:pDynamicStates member of
    pname:pDynamicState is
    ename:VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV, and if
    pname:pViewportState->pNext chain includes a
    slink:VkPipelineViewportShadingRateImageStateCreateInfoNV structure,
    then its pname:pShadingRatePalettes member must: be a valid pointer to
    an array of pname:viewportCount valid slink:VkShadingRatePaletteNV
    structures
endif::VK_NV_shading_rate_image[]
ifdef::VK_EXT_discard_rectangles[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04058]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and no element of the pname:pDynamicStates member of
    pname:pDynamicState is ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT, and
    if pname:pNext chain includes a
    slink:VkPipelineDiscardRectangleStateCreateInfoEXT structure, and if its
    pname:discardRectangleCount member is not `0`, then its
    pname:pDiscardRectangles member must: be a valid pointer to an array of
    pname:discardRectangleCount slink:VkRect2D structures
endif::VK_EXT_discard_rectangles[]
ifndef::VK_EXT_vertex_input_dynamic_state[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02097]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-vertex-input, vertex input state>>,
    pname:pVertexInputState must: be a valid pointer to a valid
    slink:VkPipelineVertexInputStateCreateInfo structure
endif::VK_EXT_vertex_input_dynamic_state[]
ifndef::VK_EXT_vertex_input_dynamic_state[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pVertexInputState-04910]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-vertex-input, vertex input state>>, and
    ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT is not set,
    pname:pVertexInputState must: be a valid pointer to a valid
    slink:VkPipelineVertexInputStateCreateInfo structure
endif::VK_EXT_vertex_input_dynamic_state[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02098]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-vertex-input, vertex input state>>,
    pname:pInputAssemblyState must: be a valid pointer to a valid
    slink:VkPipelineInputAssemblyStateCreateInfo structure
ifdef::VK_EXT_transform_feedback[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02317]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, the code:Xfb execution mode can: be specified by no more than
    one shader stage in pname:pStages
  * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02318]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and any shader stage in pname:pStages specifies code:Xfb
    execution mode it must: be the last
    <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader
    stage>>
  * [[VUID-VkGraphicsPipelineCreateInfo-rasterizationStream-02319]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and a
    slink:VkPipelineRasterizationStateStreamCreateInfoEXT::pname:rasterizationStream
    value other than zero is specified, all variables in the output
    interface of the entry point being compiled decorated with
    code:Position, code:PointSize, code:ClipDistance, or code:CullDistance
    must: be decorated with identical code:Stream values that match the
    pname:rasterizationStream
  * [[VUID-VkGraphicsPipelineCreateInfo-rasterizationStream-02320]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and
    slink:VkPipelineRasterizationStateStreamCreateInfoEXT::pname:rasterizationStream
    is zero, or not specified, all variables in the output interface of the
    entry point being compiled decorated with code:Position, code:PointSize,
    code:ClipDistance, or code:CullDistance must: be decorated with a
    code:Stream value of zero, or must: not specify the code:Stream
    decoration
  * [[VUID-VkGraphicsPipelineCreateInfo-geometryStreams-02321]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and the last
    <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader
    stage>> is a geometry shader, and that geometry shader uses the
    code:GeometryStreams capability, then
    sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:geometryStreams
    feature must: be enabled
ifdef::VK_NV_mesh_shader[]
  * [[VUID-VkGraphicsPipelineCreateInfo-None-02322]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and there are any mesh shader stages in the pipeline there
    must: not be any shader stage in the pipeline with a code:Xfb execution
    mode
endif::VK_NV_mesh_shader[]
endif::VK_EXT_transform_feedback[]
ifdef::VK_EXT_line_rasterization[]
  * [[VUID-VkGraphicsPipelineCreateInfo-lineRasterizationMode-02766]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and at least one of <<pipeline-graphics-subsets-fragment-output,
    fragment output interface state>> or
    <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>,
    the pname:lineRasterizationMode member of a
    slink:VkPipelineRasterizationLineStateCreateInfoEXT structure included
    in the pname:pNext chain of pname:pRasterizationState is
    ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT or
    ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, then the
    pname:alphaToCoverageEnable, pname:alphaToOneEnable, and
    pname:sampleShadingEnable members of pname:pMultisampleState must: all
    be ename:VK_FALSE
  * [[VUID-VkGraphicsPipelineCreateInfo-stippledLineEnable-02767]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, the pname:stippledLineEnable member of
    slink:VkPipelineRasterizationLineStateCreateInfoEXT is ename:VK_TRUE,
    and no element of the pname:pDynamicStates member of pname:pDynamicState
    is ename:VK_DYNAMIC_STATE_LINE_STIPPLE_EXT, then the
    pname:lineStippleFactor member of
    slink:VkPipelineRasterizationLineStateCreateInfoEXT must: be in the
    range [eq]#[1,256]#
endif::VK_EXT_line_rasterization[]
ifdef::VK_KHR_pipeline_library[]
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-03371]]
    pname:flags must: not include ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
endif::VK_KHR_pipeline_library[]
ifdef::VK_KHR_ray_tracing_pipeline[]
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-03372]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-03373]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-03374]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-03375]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-03376]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-03377]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-03577]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
endif::VK_KHR_ray_tracing_pipeline[]
ifdef::VK_NV_ray_tracing_motion_blur[]
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-04947]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV
endif::VK_NV_ray_tracing_motion_blur[]
ifdef::VK_EXT_extended_dynamic_state[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03378]]
    If the <<features-extendedDynamicState, extendedDynamicState>> feature
    is not enabled, there must: be no element of the pname:pDynamicStates
    member of pname:pDynamicState set to
    ename:VK_DYNAMIC_STATE_CULL_MODE_EXT,
    ename:VK_DYNAMIC_STATE_FRONT_FACE_EXT,
    ename:VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT,
    ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT,
    ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT,
    ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE_EXT,
    ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT,
    ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT,
    ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT,
    ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT,
    ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT, or
    ename:VK_DYNAMIC_STATE_STENCIL_OP_EXT
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03379]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT is included
    in the pname:pDynamicStates array then pname:viewportCount must: be zero
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03380]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT is included
    in the pname:pDynamicStates array then pname:scissorCount must: be zero
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04132]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT is included
    in the pname:pDynamicStates array then ename:VK_DYNAMIC_STATE_VIEWPORT
    must: not be present
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04133]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>>, and ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT is included
    in the pname:pDynamicStates array then ename:VK_DYNAMIC_STATE_SCISSOR
    must: not be present
endif::VK_EXT_extended_dynamic_state[]
ifdef::VK_EXT_extended_dynamic_state2[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04868]]
    If the <<features-extendedDynamicState2, extendedDynamicState2>> feature
    is not enabled, there must: be no element of the pname:pDynamicStates
    member of pname:pDynamicState set to
    ename:VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE_EXT,
    ename:VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE_EXT, or
    ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04869]]
    If the <<features-extendedDynamicState2LogicOp,
    extendedDynamicState2LogicOp>> feature is not enabled, there must: be no
    element of the pname:pDynamicStates member of pname:pDynamicState set to
    ename:VK_DYNAMIC_STATE_LOGIC_OP_EXT
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04870]]
    If the <<features-extendedDynamicState2PatchControlPoints,
    extendedDynamicState2PatchControlPoints>> feature is not enabled, there
    must: be no element of the pname:pDynamicStates member of
    pname:pDynamicState set to
    ename:VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT
endif::VK_EXT_extended_dynamic_state2[]
ifdef::VK_NV_device_generated_commands[]
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-02877]]
    If pname:flags includes
    ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV, then the
    <<features-deviceGeneratedCommands,
    sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>>
    feature must: be enabled
ifdef::VK_EXT_transform_feedback[]
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-02966]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and pname:flags includes
    ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV, then all stages must:
    not specify code:Xfb execution mode
endif::VK_EXT_transform_feedback[]
endif::VK_NV_device_generated_commands[]
ifdef::VK_EXT_pipeline_creation_cache_control[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pipelineCreationCacheControl-02878]]
    If the <<features-pipelineCreationCacheControl,
    pname:pipelineCreationCacheControl>> feature is not enabled, pname:flags
    must: not include
    ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT or
    ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT
endif::VK_EXT_pipeline_creation_cache_control[]
ifdef::VK_KHR_fragment_shading_rate[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04494]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates,
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.width
    must: be greater than or equal to `1`
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04495]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates,
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.height
    must: be greater than or equal to `1`
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04496]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates,
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.width
    must: be a power-of-two value
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04497]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates,
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.height
    must: be a power-of-two value
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04498]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates,
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.width
    must: be less than or equal to `4`
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04499]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates,
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.height
    must: be less than or equal to `4`
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04500]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates, and the
    <<features-pipelineFragmentShadingRate,
    pname:pipelineFragmentShadingRate feature>> is not enabled,
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.width
    and
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.height
    must: both be equal to `1`
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04501]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates, and the
    <<feature-primitiveFragmentShadingRate,
    pname:primitiveFragmentShadingRate feature>> is not enabled,
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:combinerOps[0]
    must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04502]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates, and the
    <<feature-attachmentFragmentShadingRate,
    pname:attachmentFragmentShadingRate feature>> is not enabled,
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:combinerOps[1]
    must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR
ifdef::VK_EXT_extended_dynamic_state[]
  * [[VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04503]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and the
    <<limits-primitiveFragmentShadingRateWithMultipleViewports,
    pname:primitiveFragmentShadingRateWithMultipleViewports>> limit is not
    supported, ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT is not
    included in pname:pDynamicState->pDynamicStates, and
    slink:VkPipelineViewportStateCreateInfo::pname:viewportCount is greater
    than `1`, entry points specified in pname:pStages must: not write to the
    code:PrimitiveShadingRateKHR built-in
endif::VK_EXT_extended_dynamic_state[]
  * [[VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04504]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and the
    <<limits-primitiveFragmentShadingRateWithMultipleViewports,
    pname:primitiveFragmentShadingRateWithMultipleViewports>> limit is not
    supported, and entry points specified in pname:pStages write to the
    code:ViewportIndex built-in, they must: not also write to the
    code:PrimitiveShadingRateKHR built-in
ifdef::VK_NV_viewport_array2[]
  * [[VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04505]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and the
    <<limits-primitiveFragmentShadingRateWithMultipleViewports,
    pname:primitiveFragmentShadingRateWithMultipleViewports>> limit is not
    supported, and entry points specified in pname:pStages write to the
    code:ViewportMaskNV built-in, they must: not also write to the
    code:PrimitiveShadingRateKHR built-in
endif::VK_NV_viewport_array2[]
  * [[VUID-VkGraphicsPipelineCreateInfo-fragmentShadingRateNonTrivialCombinerOps-04506]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>>, the <<limits-fragmentShadingRateNonTrivialCombinerOps,
    pname:fragmentShadingRateNonTrivialCombinerOps>> limit is not supported,
    and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in
    pname:pDynamicState->pDynamicStates, elements of
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:combinerOps
    must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or
    ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR
endif::VK_KHR_fragment_shading_rate[]
ifdef::VK_NV_fragment_shading_rate_enums[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04569]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates, and the
    <<features-fragmentShadingRateEnums, pname:fragmentShadingRateEnums
    feature>> is not enabled,
    slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:shadingRateType
    must: be equal to ename:VK_FRAGMENT_SHADING_RATE_TYPE_FRAGMENT_SIZE_NV.
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04570]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates, and the
    <<features-pipelineFragmentShadingRate,
    pname:pipelineFragmentShadingRate feature>> is not enabled,
    slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:shadingRate
    must: be equal to
    ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NV.
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04571]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates, and the
    <<feature-primitiveFragmentShadingRate,
    pname:primitiveFragmentShadingRate feature>> is not enabled,
    slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:combinerOps[0]
    must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04572]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not
    included in pname:pDynamicState->pDynamicStates, and the
    <<feature-attachmentFragmentShadingRate,
    pname:attachmentFragmentShadingRate feature>> is not enabled,
    slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:combinerOps[1]
    must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR
  * [[VUID-VkGraphicsPipelineCreateInfo-fragmentShadingRateNonTrivialCombinerOps-04573]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>>, and the <<limits-fragmentShadingRateNonTrivialCombinerOps,
    pname:fragmentShadingRateNonTrivialCombinerOps>> limit is not supported
    and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in
    pname:pDynamicState->pDynamicStates, elements of
    slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:combinerOps
    must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or
    ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR
  * [[VUID-VkGraphicsPipelineCreateInfo-None-04574]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>>, and the <<limits-supersampleFragmentShadingRates,
    supersampleFragmentShadingRates feature>> is not enabled,
    slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:shadingRate
    must: not be equal to
    ename:VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NV,
    ename:VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NV,
    ename:VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NV, or
    ename:VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NV.
  * [[VUID-VkGraphicsPipelineCreateInfo-None-04575]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader
    state>>, and the <<limits-noInvocationFragmentShadingRates,
    noInvocationFragmentShadingRates feature>> is not enabled,
    slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:shadingRate
    must: not be equal to ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV.
endif::VK_NV_fragment_shading_rate_enums[]
ifdef::VK_KHR_ray_tracing_pipeline[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03578]]
    All elements of the pname:pDynamicStates member of pname:pDynamicState
    must: not be ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR
endif::VK_KHR_ray_tracing_pipeline[]
ifdef::VK_EXT_vertex_input_dynamic_state[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04807]]
    If the pipeline is being created with
    <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader
    state>> and the <<features-vertexInputDynamicState,
    vertexInputDynamicState>> feature is not enabled, there must: be no
    element of the pname:pDynamicStates member of pname:pDynamicState set to
    ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT
endif::VK_EXT_vertex_input_dynamic_state[]
  * [[VUID-VkGraphicsPipelineCreateInfo-None-04893]]
    The pipeline must: be created with a
    <<pipeline-graphics-subsets-complete, complete set of state>>
ifdef::VK_EXT_color_write_enable[]
  * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04800]]
    If the <<features-colorWriteEnable, colorWriteEnable>> feature is not
    enabled, there must: be no element of the pname:pDynamicStates member of
    pname:pDynamicState set to ename:VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT
endif::VK_EXT_color_write_enable[]
ifdef::VK_QCOM_render_pass_shader_resolve[]
  * [[VUID-VkGraphicsPipelineCreateInfo-rasterizationSamples-04899]]
    If the pipeline is being created with fragment shader state, and the
    VK_QCOM_render_pass_shader_resolve extension is enabled, and if subpass
    has any input attachments, and if the subpass description contains
    ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then the sample
    count of the input attachments must: equal pname:rasterizationSamples
  * [[VUID-VkGraphicsPipelineCreateInfo-sampleShadingEnable-04900]]
    If the pipeline is being created with fragment shader state, and the
    VK_QCOM_render_pass_shader_resolve extension is enabled, and if the
    subpass description contains
    ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then
    pname:sampleShadingEnable must: be false
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-04901]]
    If pname:flags includes
    ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, then the subpass
    must: be the last subpass in a subpass dependency chain
  * [[VUID-VkGraphicsPipelineCreateInfo-flags-04902]]
    If pname:flags includes
    ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if
    pname:pResolveAttachments is not `NULL`, then each resolve attachment
    must: be ename:VK_ATTACHMENT_UNUSED
endif::VK_QCOM_render_pass_shader_resolve[]
****

include::{generated}/validity/structs/VkGraphicsPipelineCreateInfo.txt[]
--

[open,refpage='VkPipelineCreateFlagBits',desc='Bitmask controlling how a pipeline is created',type='enums']
--
Possible values of the pname:flags member of
slink:VkGraphicsPipelineCreateInfo,
ifdef::VK_KHR_ray_tracing_pipeline[slink:VkRayTracingPipelineCreateInfoKHR,]
ifdef::VK_NV_ray_tracing[slink:VkRayTracingPipelineCreateInfoNV,]
and slink:VkComputePipelineCreateInfo, specifying how a pipeline is created,
are:

include::{generated}/api/enums/VkPipelineCreateFlagBits.txt[]

  * ename: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.
  * ename: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.
  * ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT specifies that the pipeline to
    be created will be a child of a previously created parent pipeline.
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]
  * ename:VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT specifies that
    any shader input variables decorated as code:ViewIndex will be assigned
    values as if they were decorated as code:DeviceIndex.
endif::VK_VERSION_1_1,VK_KHR_multiview[]
  * ename:VK_PIPELINE_CREATE_DISPATCH_BASE specifies that a compute pipeline
    can: be used with flink:vkCmdDispatchBase with a non-zero base
    workgroup.
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_NV_ray_tracing[]
  * ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV specifies that a pipeline
    is created with all shaders in the deferred state.
    Before using the pipeline the application must: call
    flink:vkCompileDeferredNV exactly once on each shader in the pipeline
    before using the pipeline.
endif::VK_NV_ray_tracing[]
ifdef::VK_KHR_pipeline_executable_properties[]
  * ename:VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR specifies that the
    shader compiler should capture statistics for the pipeline executables
    produced by the compile process which can: later be retrieved by calling
    flink:vkGetPipelineExecutableStatisticsKHR.
    Enabling this flag must: not affect the final compiled pipeline but may:
    disable pipeline caching or otherwise affect pipeline creation time.
  * ename:VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR
    specifies that the shader compiler should capture the internal
    representations of pipeline executables produced by the compile process
    which can: later be retrieved by calling
    flink:vkGetPipelineExecutableInternalRepresentationsKHR.
    Enabling this flag must: not affect the final compiled pipeline but may:
    disable pipeline caching or otherwise affect pipeline creation time.
endif::VK_KHR_pipeline_executable_properties[]
ifdef::VK_KHR_pipeline_library[]
  * ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR specifies that the pipeline
    cannot: be used directly, and instead defines a _pipeline library_ that
    can: be combined with other pipelines using the
    slink:VkPipelineLibraryCreateInfoKHR structure.
ifdef::VK_KHR_ray_tracing_pipeline[]
    This is available in ray tracing pipelines.
endif::VK_KHR_ray_tracing_pipeline[]
endif::VK_KHR_pipeline_library[]
ifdef::VK_KHR_ray_tracing_pipeline[]
  * ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR
    specifies that an any-hit shader will always be present when an any-hit
    shader would be executed.
    A NULL any-hit shader is an any-hit shader which is effectively
    ename:VK_SHADER_UNUSED_KHR, such as from a shader group consisting
    entirely of zeros.
  * ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR
    specifies that a closest hit shader will always be present when a
    closest hit shader would be executed.
    A NULL closest hit shader is a closest hit shader which is effectively
    ename:VK_SHADER_UNUSED_KHR, such as from a shader group consisting
    entirely of zeros.
  * ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR
    specifies that a miss shader will always be present when a miss shader
    would be executed.
    A NULL miss shader is a miss shader which is effectively
    ename:VK_SHADER_UNUSED_KHR, such as from a shader group consisting
    entirely of zeros.
  * ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR
    specifies that an intersection shader will always be present when an
    intersection shader would be executed.
    A NULL intersection shader is an intersection shader which is
    effectively ename:VK_SHADER_UNUSED_KHR, such as from a shader group
    consisting entirely of zeros.
  * ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR specifies
    that triangle primitives will be skipped during traversal using
    code:OpTraceRayKHR.
  * ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR specifies that
    AABB primitives will be skipped during traversal using
    code:OpTraceRayKHR.
  * ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
    specifies that the shader group handles can: be saved and reused on a
    subsequent run (e.g. for trace capture and replay).
endif::VK_KHR_ray_tracing_pipeline[]
ifdef::VK_NV_device_generated_commands[]
  * ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV specifies that the
    pipeline can be used in combination with <<device-generated-commands>>.
endif::VK_NV_device_generated_commands[]
ifdef::VK_EXT_pipeline_creation_cache_control[]
  * ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT
    specifies that pipeline creation will fail if a compile is required for
    creation of a valid slink:VkPipeline object;
    ename:VK_PIPELINE_COMPILE_REQUIRED_EXT will be returned by pipeline
    creation, and the slink:VkPipeline will be set to dlink:VK_NULL_HANDLE.
  * When creating multiple pipelines,
    ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT specifies that
    control will be returned to the application on failure of the
    corresponding pipeline rather than continuing to create additional
    pipelines.
endif::VK_EXT_pipeline_creation_cache_control[]
ifdef::VK_NV_ray_tracing_motion_blur[]
  * ename:VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV specifies that
    the pipeline is allowed to use code:OpTraceRayMotionNV.
endif::VK_NV_ray_tracing_motion_blur[]

It is valid to set both ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT and
ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT.
This allows a pipeline to be both a parent and possibly a child in a
pipeline hierarchy.
See <<pipelines-pipeline-derivatives,Pipeline Derivatives>> for more
information.
--

[open,refpage='VkPipelineCreateFlags',desc='Bitmask of VkPipelineCreateFlagBits',type='flags']
--
include::{generated}/api/flags/VkPipelineCreateFlags.txt[]

tname:VkPipelineCreateFlags is a bitmask type for setting a mask of zero or
more elink:VkPipelineCreateFlagBits.
--

[open,refpage='VkPipelineDynamicStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline dynamic state',type='structs']
--
The sname:VkPipelineDynamicStateCreateInfo structure is defined as:

include::{generated}/api/structs/VkPipelineDynamicStateCreateInfo.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is reserved for future use.
  * pname:dynamicStateCount is the number of elements in the
    pname:pDynamicStates array.
  * pname:pDynamicStates is a pointer to an array of elink: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 pname:pDynamicStates must: be unique
****

include::{generated}/validity/structs/VkPipelineDynamicStateCreateInfo.txt[]
--

[open,refpage='VkPipelineDynamicStateCreateFlags',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkPipelineDynamicStateCreateFlags.txt[]

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

[open,refpage='VkDynamicState',desc='Indicate which dynamic state is taken from dynamic state commands',type='enums']
--
The source of different pieces of dynamic state is specified by the
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates property of the
currently active pipeline, each of whose elements must: be one of the
values:

include::{generated}/api/enums/VkDynamicState.txt[]

  * ename:VK_DYNAMIC_STATE_VIEWPORT specifies that the pname:pViewports
    state in slink:VkPipelineViewportStateCreateInfo will be ignored and
    must: be set dynamically with flink:vkCmdSetViewport before any drawing
    commands.
    The number of viewports used by a pipeline is still specified by the
    pname:viewportCount member of slink:VkPipelineViewportStateCreateInfo.
  * ename:VK_DYNAMIC_STATE_SCISSOR specifies that the pname:pScissors state
    in slink:VkPipelineViewportStateCreateInfo will be ignored and must: be
    set dynamically with flink:vkCmdSetScissor before any drawing commands.
    The number of scissor rectangles used by a pipeline is still specified
    by the pname:scissorCount member of
    slink:VkPipelineViewportStateCreateInfo.
  * ename:VK_DYNAMIC_STATE_LINE_WIDTH specifies that the pname:lineWidth
    state in slink:VkPipelineRasterizationStateCreateInfo will be ignored
    and must: be set dynamically with flink:vkCmdSetLineWidth before any
    drawing commands that generate line primitives for the rasterizer.
  * ename:VK_DYNAMIC_STATE_DEPTH_BIAS specifies that the
    pname:depthBiasConstantFactor, pname:depthBiasClamp and
    pname:depthBiasSlopeFactor states in
    slink:VkPipelineRasterizationStateCreateInfo will be ignored and must:
    be set dynamically with flink:vkCmdSetDepthBias before any draws are
    performed with pname:depthBiasEnable in
    slink:VkPipelineRasterizationStateCreateInfo set to ename:VK_TRUE.
  * ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS specifies that the
    pname:blendConstants state in slink:VkPipelineColorBlendStateCreateInfo
    will be ignored and must: be set dynamically with
    flink:vkCmdSetBlendConstants before any draws are performed with a
    pipeline state with sname:VkPipelineColorBlendAttachmentState member
    pname:blendEnable set to ename:VK_TRUE and any of the blend functions
    using a constant blend color.
  * ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS specifies that the
    pname:minDepthBounds and pname:maxDepthBounds states of
    slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be
    set dynamically with flink:vkCmdSetDepthBounds before any draws are
    performed with a pipeline state with
    slink:VkPipelineDepthStencilStateCreateInfo member
    pname:depthBoundsTestEnable set to ename:VK_TRUE.
  * ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK specifies that the
    pname:compareMask state in slink:VkPipelineDepthStencilStateCreateInfo
    for both pname:front and pname:back will be ignored and must: be set
    dynamically with flink:vkCmdSetStencilCompareMask before any draws are
    performed with a pipeline state with
    slink:VkPipelineDepthStencilStateCreateInfo member
    pname:stencilTestEnable set to ename:VK_TRUE
  * ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK specifies that the
    pname:writeMask state in slink:VkPipelineDepthStencilStateCreateInfo for
    both pname:front and pname:back will be ignored and must: be set
    dynamically with flink:vkCmdSetStencilWriteMask before any draws are
    performed with a pipeline state with
    slink:VkPipelineDepthStencilStateCreateInfo member
    pname:stencilTestEnable set to ename:VK_TRUE
  * ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE specifies that the
    pname:reference state in slink:VkPipelineDepthStencilStateCreateInfo for
    both pname:front and pname:back will be ignored and must: be set
    dynamically with flink:vkCmdSetStencilReference before any draws are
    performed with a pipeline state with
    slink:VkPipelineDepthStencilStateCreateInfo member
    pname:stencilTestEnable set to ename:VK_TRUE
ifdef::VK_NV_clip_space_w_scaling[]
  * ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV specifies that the
    pname:pViewportScalings state in
    slink:VkPipelineViewportWScalingStateCreateInfoNV will be ignored and
    must: be set dynamically with flink:vkCmdSetViewportWScalingNV before
    any draws are performed with a pipeline state with
    slink:VkPipelineViewportWScalingStateCreateInfoNV member
    pname:viewportScalingEnable set to ename:VK_TRUE
endif::VK_NV_clip_space_w_scaling[]
ifdef::VK_EXT_discard_rectangles[]
  * ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT specifies that the
    pname:pDiscardRectangles state in
    slink:VkPipelineDiscardRectangleStateCreateInfoEXT will be ignored and
    must: be set dynamically with flink:vkCmdSetDiscardRectangleEXT before
    any draw or clear commands.
    The elink:VkDiscardRectangleModeEXT and the number of active discard
    rectangles is still specified by the pname:discardRectangleMode and
    pname:discardRectangleCount members of
    slink:VkPipelineDiscardRectangleStateCreateInfoEXT.
endif::VK_EXT_discard_rectangles[]
ifdef::VK_EXT_sample_locations[]
  * ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT specifies that the
    pname:sampleLocationsInfo state in
    slink:VkPipelineSampleLocationsStateCreateInfoEXT will be ignored and
    must: be set dynamically with flink:vkCmdSetSampleLocationsEXT before
    any draw or clear commands.
    Enabling custom sample locations is still indicated by the
    pname:sampleLocationsEnable member of
    slink:VkPipelineSampleLocationsStateCreateInfoEXT.
endif::VK_EXT_sample_locations[]
ifdef::VK_NV_scissor_exclusive[]
  * ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV specifies that the
    pname:pExclusiveScissors state in
    slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV will be
    ignored and must: be set dynamically with
    flink:vkCmdSetExclusiveScissorNV before any drawing commands.
    The number of exclusive scissor rectangles used by a pipeline is still
    specified by the pname:exclusiveScissorCount member of
    slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV.
endif::VK_NV_scissor_exclusive[]
ifdef::VK_NV_shading_rate_image[]
  * ename:VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV specifies that
    the pname:pShadingRatePalettes state in
    slink:VkPipelineViewportShadingRateImageStateCreateInfoNV will be
    ignored and must: be set dynamically with
    flink:vkCmdSetViewportShadingRatePaletteNV before any drawing commands.
  * ename:VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV specifies that
    the coarse sample order state in
    slink:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV will be
    ignored and must: be set dynamically with
    flink:vkCmdSetCoarseSampleOrderNV before any drawing commands.
endif::VK_NV_shading_rate_image[]
ifdef::VK_EXT_line_rasterization[]
  * ename:VK_DYNAMIC_STATE_LINE_STIPPLE_EXT specifies that the
    pname:lineStippleFactor and pname:lineStipplePattern state in
    slink:VkPipelineRasterizationLineStateCreateInfoEXT will be ignored and
    must: be set dynamically with flink:vkCmdSetLineStippleEXT before any
    draws are performed with a pipeline state with
    slink:VkPipelineRasterizationLineStateCreateInfoEXT member
    pname:stippledLineEnable set to ename:VK_TRUE.
endif::VK_EXT_line_rasterization[]
ifdef::VK_EXT_extended_dynamic_state[]
  * ename:VK_DYNAMIC_STATE_CULL_MODE_EXT specifies that the pname:cullMode
    state in slink:VkPipelineRasterizationStateCreateInfo will be ignored
    and must: be set dynamically with flink:vkCmdSetCullModeEXT before any
    drawing commands.
  * ename:VK_DYNAMIC_STATE_FRONT_FACE_EXT specifies that the pname:frontFace
    state in slink:VkPipelineRasterizationStateCreateInfo will be ignored
    and must: be set dynamically with flink:vkCmdSetFrontFaceEXT before any
    drawing commands.
  * ename:VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT specifies that the
    pname:topology state in slink:VkPipelineInputAssemblyStateCreateInfo
    only specifies the <<drawing-primitive-topology-class, topology class>>,
    and the specific topology order and adjacency must: be set dynamically
    with flink:vkCmdSetPrimitiveTopologyEXT before any drawing commands.
  * ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT specifies that the
    pname:viewportCount and pname:pViewports state in
    slink:VkPipelineViewportStateCreateInfo will be ignored and must: be set
    dynamically with flink:vkCmdSetViewportWithCountEXT before any draw
    call.
  * ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT specifies that the
    pname:scissorCount and pname:pScissors state in
    slink:VkPipelineViewportStateCreateInfo will be ignored and must: be set
    dynamically with flink:vkCmdSetScissorWithCountEXT before any draw call.
  * ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE_EXT specifies that
    the pname:stride state in slink:VkVertexInputBindingDescription will be
    ignored and must: be set dynamically with
    flink:vkCmdBindVertexBuffers2EXT before any draw call.
  * ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT specifies that the
    pname:depthTestEnable state in
    slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be
    set dynamically with flink:vkCmdSetDepthTestEnableEXT before any draw
    call.
  * ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT specifies that the
    pname:depthWriteEnable state in
    slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be
    set dynamically with flink:vkCmdSetDepthWriteEnableEXT before any draw
    call.
  * ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT specifies that the
    pname:depthCompareOp state in
    slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be
    set dynamically with flink:vkCmdSetDepthCompareOpEXT before any draw
    call.
  * ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT specifies that the
    pname:depthBoundsTestEnable state in
    slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be
    set dynamically with flink:vkCmdSetDepthBoundsTestEnableEXT before any
    draw call.
  * ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT specifies that the
    pname:stencilTestEnable state in
    slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be
    set dynamically with flink:vkCmdSetStencilTestEnableEXT before any draw
    call.
  * ename:VK_DYNAMIC_STATE_STENCIL_OP_EXT specifies that the pname:failOp,
    pname:passOp, pname:depthFailOp, and pname:compareOp states in
    sname:VkPipelineDepthStencilStateCreateInfo for both pname:front and
    pname:back will be ignored and must: be set dynamically with
    flink:vkCmdSetStencilOpEXT before any draws are performed with a
    pipeline state with sname:VkPipelineDepthStencilStateCreateInfo member
    pname:stencilTestEnable set to ename:VK_TRUE
endif::VK_EXT_extended_dynamic_state[]
ifdef::VK_EXT_extended_dynamic_state2[]
  * ename:VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT specifies that the
    pname:patchControlPoints state in
    slink:VkPipelineTessellationStateCreateInfo will be ignored and must: be
    set dynamically with flink:vkCmdSetPatchControlPointsEXT before any
    drawing commands.
  * ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT specifies that the
    pname:rasterizerDiscardEnable state in
    slink:VkPipelineRasterizationStateCreateInfo will be ignored and must:
    be set dynamically with flink:vkCmdSetRasterizerDiscardEnableEXT before
    any drawing commands.
  * ename:VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE_EXT specifies that the
    pname:depthBiasEnable state in
    slink:VkPipelineRasterizationStateCreateInfo will be ignored and must:
    be set dynamically with flink:vkCmdSetDepthBiasEnableEXT before any
    drawing commands.
  * ename:VK_DYNAMIC_STATE_LOGIC_OP_EXT specifies that the pname:logicOp
    state in slink:VkPipelineColorBlendStateCreateInfo will be ignored and
    must: be set dynamically with flink:vkCmdSetLogicOpEXT before any
    drawing commands.
  * ename:VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE_EXT specifies that the
    pname:primitiveRestartEnable state in
    slink:VkPipelineInputAssemblyStateCreateInfo will be ignored and must:
    be set dynamically with flink:vkCmdSetPrimitiveRestartEnableEXT before
    any drawing commands.
endif::VK_EXT_extended_dynamic_state2[]
ifdef::VK_KHR_fragment_shading_rate[]
  * ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR specifies that state in
    slink:VkPipelineFragmentShadingRateStateCreateInfoKHR
ifdef::VK_NV_fragment_shading_rate_enums[]
    and slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV
endif::VK_NV_fragment_shading_rate_enums[]
    will be ignored and must: be set dynamically with
    flink:vkCmdSetFragmentShadingRateKHR
ifdef::VK_NV_fragment_shading_rate_enums[]
    or flink:vkCmdSetFragmentShadingRateEnumNV
endif::VK_NV_fragment_shading_rate_enums[]
    before any drawing commands.
endif::VK_KHR_fragment_shading_rate[]
ifdef::VK_KHR_ray_tracing_pipeline[]
  * ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR specifies
    that the default stack size computation for the pipeline will be ignored
    and must: be set dynamically with
    flink:vkCmdSetRayTracingPipelineStackSizeKHR before any ray tracing
    calls are performed.
endif::VK_KHR_ray_tracing_pipeline[]
ifdef::VK_EXT_vertex_input_dynamic_state[]
  * ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT specifies that the
    pname:pVertexInputState state will be ignored and must: be set
    dynamically with flink:vkCmdSetVertexInputEXT before any drawing
    commands
endif::VK_EXT_vertex_input_dynamic_state[]
ifdef::VK_EXT_color_write_enable[]
  * ename:VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT specifies that the
    pname:pColorWriteEnables state in
    slink:VkPipelineColorWriteCreateInfoEXT will be ignored and must: be set
    dynamically with flink:vkCmdSetColorWriteEnableEXT before any draw call.
endif::VK_EXT_color_write_enable[]
--


=== Valid Combinations of Stages for Graphics Pipelines

ifdef::VK_NV_mesh_shader[]
The geometric primitive processing can either be handled on a per primitive
basis by the vertex, tessellation, and geometry shader stages, or on a per
mesh basis using task and mesh shader stages.
If the pipeline includes a mesh shader stage, it uses the mesh pipeline,
otherwise it uses the primitive pipeline.

If a task shader is omitted, the task shading stage is skipped.
endif::VK_NV_mesh_shader[]

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 unmodified.
This can: be useful for depth-only rendering.

Presence of a shader stage in a pipeline is indicated by including a valid
slink:VkPipelineShaderStageCreateInfo with pname:module and pname:pName
selecting an entry point from a shader module, where that entry point is
valid for the stage specified by pname: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:
  * Depth/stencil-only rendering in a subpass with no color attachments
  ** Active Pipeline Shader Stages
  *** Vertex Shader
  ** Required: Fixed-Function Pipeline Stages
  *** slink:VkPipelineVertexInputStateCreateInfo
  *** slink:VkPipelineInputAssemblyStateCreateInfo
  *** slink:VkPipelineViewportStateCreateInfo
  *** slink:VkPipelineRasterizationStateCreateInfo
  *** slink:VkPipelineMultisampleStateCreateInfo
  *** slink:VkPipelineDepthStencilStateCreateInfo
  * Color-only rendering in a subpass with no depth/stencil attachment
  ** Active Pipeline Shader Stages
  *** Vertex Shader
  *** Fragment Shader
  ** Required: Fixed-Function Pipeline Stages
  *** slink:VkPipelineVertexInputStateCreateInfo
  *** slink:VkPipelineInputAssemblyStateCreateInfo
  *** slink:VkPipelineViewportStateCreateInfo
  *** slink:VkPipelineRasterizationStateCreateInfo
  *** slink:VkPipelineMultisampleStateCreateInfo
  *** slink:VkPipelineColorBlendStateCreateInfo
  * Rendering pipeline with tessellation and geometry shaders
  ** Active Pipeline Shader Stages
  *** Vertex Shader
  *** Tessellation Control Shader
  *** Tessellation Evaluation Shader
  *** Geometry Shader
  *** Fragment Shader
  ** Required: Fixed-Function Pipeline Stages
  *** slink:VkPipelineVertexInputStateCreateInfo
  *** slink:VkPipelineInputAssemblyStateCreateInfo
  *** slink:VkPipelineTessellationStateCreateInfo
  *** slink:VkPipelineViewportStateCreateInfo
  *** slink:VkPipelineRasterizationStateCreateInfo
  *** slink:VkPipelineMultisampleStateCreateInfo
  *** slink:VkPipelineDepthStencilStateCreateInfo
  *** slink:VkPipelineColorBlendStateCreateInfo
ifdef::VK_NV_mesh_shader[]
  * Rendering pipeline with task and mesh shaders
  ** Active Pipeline Shader Stages
  *** Task Shader
  *** Mesh Shader
  *** Fragment Shader
  ** Required: Fixed-Function Pipeline Stages
  *** slink:VkPipelineViewportStateCreateInfo
  *** slink:VkPipelineRasterizationStateCreateInfo
  *** slink:VkPipelineMultisampleStateCreateInfo
  *** slink:VkPipelineDepthStencilStateCreateInfo
  *** slink:VkPipelineColorBlendStateCreateInfo
endif::VK_NV_mesh_shader[]


ifdef::VK_NV_device_generated_commands[]
[[graphics-shadergroups]]
=== Graphics Pipeline Shader Groups

Graphics pipelines can contain multiple shader groups that can be bound
individually.
Each shader group behaves as if it was a pipeline using the shader group's
state.
When the pipeline is bound by regular means, it behaves as if the state of
group `0` is active, use flink:vkCmdBindPipelineShaderGroupNV to bind an
invidual shader group.

The primary purpose of shader groups is allowing the device to bind
different pipeline state using <<device-generated-commands>>.

[open,refpage='VkGraphicsPipelineShaderGroupsCreateInfoNV',desc='Structure specifying parameters of a newly created multi shader group pipeline',type='structs']
--
The sname:VkGraphicsPipelineShaderGroupsCreateInfoNV structure is defined
as:

include::{generated}/api/structs/VkGraphicsPipelineShaderGroupsCreateInfoNV.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:groupCount is the number of elements in the pname:pGroups array.
  * pname:pGroups is a pointer to an array of
    slink:VkGraphicsShaderGroupCreateInfoNV structures specifying which
    state of the original slink:VkGraphicsPipelineCreateInfo each shader
    group overrides.
  * pname:pipelineCount is the number of elements in the pname:pPipelines
    array.
  * pname:pPipelines is a pointer to an array of graphics sname:VkPipeline
    structures which are referenced within the created pipeline, including
    all their shader groups.

When referencing shader groups by index, groups defined in the referenced
pipelines are treated as if they were defined as additional entries in
pname:pGroups.
They are appended in the order they appear in the pname:pPipelines array and
in the pname:pGroups array when those pipelines were defined.

The application must: maintain the lifetime of all such referenced pipelines
based on the pipelines that make use of them.

.Valid Usage
****
  * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-groupCount-02879]]
    pname:groupCount must: be at least `1` and as maximum
    sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxGraphicsShaderGroupCount
  * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-groupCount-02880]]
    The sum of pname:groupCount including those groups added from referenced
    pname:pPipelines must: also be as maximum
    sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxGraphicsShaderGroupCount
  * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02881]]
    The state of the first element of pname:pGroups must: match its
    equivalent within the parent's slink:VkGraphicsPipelineCreateInfo
  * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02882]]
    Each element of pname:pGroups must: in combination with the rest of the
    pipeline state yield a valid state configuration
ifndef::VK_NV_mesh_shader[]
  * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02883]]
    All elements of pname:pGroups must: use the same shader stage
    combinations
endif::VK_NV_mesh_shader[]
ifdef::VK_NV_mesh_shader[]
  * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02884]]
    All elements of pname:pGroups must: use the same shader stage
    combinations unless any mesh shader stage is used, then either
    combination of task and mesh or just mesh shader is valid
  * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02885]]
    Mesh and regular primitive shading stages cannot be mixed across
    pname:pGroups
endif::VK_NV_mesh_shader[]
  * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pPipelines-02886]]
    Each element of pname:pPipelines must: have been created with identical
    state to the pipeline currently created except the state that can be
    overridden by slink:VkGraphicsShaderGroupCreateInfoNV
  * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-deviceGeneratedCommands-02887]]
    The <<features-deviceGeneratedCommands,
    sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>>
    feature must: be enabled
****

include::{generated}/validity/structs/VkGraphicsPipelineShaderGroupsCreateInfoNV.txt[]
--

[open,refpage='VkGraphicsShaderGroupCreateInfoNV',desc='Structure specifying override parameters for each shader group',type='structs']
--
The sname:VkGraphicsShaderGroupCreateInfoNV structure provides the state
overrides for each shader group.
Each shader group behaves like a pipeline that was created from its state as
well as the remaining parent's state.
It is defined as:

include::{generated}/api/structs/VkGraphicsShaderGroupCreateInfoNV.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:stageCount is the number of entries in the pname:pStages array.
  * pname:pStages is a pointer to an array
    slink:VkPipelineShaderStageCreateInfo structures specifying the set of
    the shader stages to be included in this shader group.
  * pname:pVertexInputState is a pointer to a
    slink:VkPipelineVertexInputStateCreateInfo structure.
  * pname:pTessellationState is a pointer to a
    slink:VkPipelineTessellationStateCreateInfo structure, and is ignored if
    the shader group does not include a tessellation control shader stage
    and tessellation evaluation shader stage.

.Valid Usage
****
  * [[VUID-VkGraphicsShaderGroupCreateInfoNV-stageCount-02888]]
    For pname:stageCount, the same restrictions as in
    slink:VkGraphicsPipelineCreateInfo::pname:stageCount apply
  * [[VUID-VkGraphicsShaderGroupCreateInfoNV-pStages-02889]]
    For pname:pStages, the same restrictions as in
    slink:VkGraphicsPipelineCreateInfo::pname:pStages apply
  * [[VUID-VkGraphicsShaderGroupCreateInfoNV-pVertexInputState-02890]]
    For pname:pVertexInputState, the same restrictions as in
    slink:VkGraphicsPipelineCreateInfo::pname:pVertexInputState apply
  * [[VUID-VkGraphicsShaderGroupCreateInfoNV-pTessellationState-02891]]
    For pname:pTessellationState, the same restrictions as in
    slink:VkGraphicsPipelineCreateInfo::pname:pTessellationState apply
****

include::{generated}/validity/structs/VkGraphicsShaderGroupCreateInfoNV.txt[]
--
endif::VK_NV_device_generated_commands[]


ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
[[pipelines-ray-tracing]]
== Ray Tracing Pipelines

Ray tracing pipelines consist of multiple shader stages, fixed-function
traversal stages, and a pipeline layout.

[open,refpage='VK_SHADER_UNUSED_KHR',desc='Sentinel for an unused shader index',type='consts',alias='VK_SHADER_UNUSED_NV']
--
ename:VK_SHADER_UNUSED_KHR is a special shader index used to indicate that a
ray generation, miss, or callable shader member is not used.

include::{generated}/api/enums/VK_SHADER_UNUSED_KHR.txt[]

ifdef::VK_NV_ray_tracing[]
or the equivalent

include::{generated}/api/enums/VK_SHADER_UNUSED_NV.txt[]
endif::VK_NV_ray_tracing[]
--

ifdef::VK_NV_ray_tracing[]
[open,refpage='vkCreateRayTracingPipelinesNV',desc='Creates a new ray tracing pipeline object',type='protos']
--
:refpage: vkCreateRayTracingPipelinesNV

To create ray tracing pipelines, call:

include::{generated}/api/protos/vkCreateRayTracingPipelinesNV.txt[]

  * pname:device is the logical device that creates the ray tracing
    pipelines.
  * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that
    pipeline caching is disabled, or the handle of a valid
    <<pipelines-cache,pipeline cache>> object, in which case use of that
    cache is enabled for the duration of the command.
  * pname:createInfoCount is the length of the pname:pCreateInfos and
    pname:pPipelines arrays.
  * pname:pCreateInfos is a pointer to an array of
    slink:VkRayTracingPipelineCreateInfoNV structures.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.
  * pname:pPipelines is a pointer to an array in which the resulting ray
    tracing pipeline objects are returned.

.Valid Usage
****
include::{chapters}/commonvalidity/create_ray_tracing_pipelines_common.txt[]
****

include::{generated}/validity/protos/vkCreateRayTracingPipelinesNV.txt[]
--
endif::VK_NV_ray_tracing[]

ifdef::VK_KHR_ray_tracing_pipeline[]
[open,refpage='vkCreateRayTracingPipelinesKHR',desc='Creates a new ray tracing pipeline object',type='protos']
--
:refpage: vkCreateRayTracingPipelinesKHR

To create ray tracing pipelines, call:

include::{generated}/api/protos/vkCreateRayTracingPipelinesKHR.txt[]

  * pname:device is the logical device that creates the ray tracing
    pipelines.
  * pname:deferredOperation is dlink:VK_NULL_HANDLE or the handle of a valid
    slink:VkDeferredOperationKHR <<deferred-host-operations-requesting,
    request deferral>> object for this command.
  * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that
    pipeline caching is disabled, or the handle of a valid
    <<pipelines-cache,pipeline cache>> object, in which case use of that
    cache is enabled for the duration of the command.
  * pname:createInfoCount is the length of the pname:pCreateInfos and
    pname:pPipelines arrays.
  * pname:pCreateInfos is a pointer to an array of
    slink:VkRayTracingPipelineCreateInfoKHR structures.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.
  * pname:pPipelines is a pointer to an array in which the resulting ray
    tracing pipeline objects are returned.

The ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS error is returned if the
implementation is unable to re-use the shader group handles provided in
slink:VkRayTracingShaderGroupCreateInfoKHR::pname:pShaderGroupCaptureReplayHandle
when
slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay
is enabled.

.Valid Usage
****
include::{chapters}/commonvalidity/create_ray_tracing_pipelines_common.txt[]
include::{chapters}/commonvalidity/deferred_operations_common.txt[]
  * [[VUID-vkCreateRayTracingPipelinesKHR-rayTracingPipeline-03586]]
    The <<features-rayTracingPipeline, pname:rayTracingPipeline>> feature
    must: be enabled
ifdef::VK_EXT_pipeline_creation_cache_control+VK_KHR_deferred_host_operations[]
  * [[VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-03587]]
    If pname:deferredOperation is not dlink:VK_NULL_HANDLE, the pname:flags
    member of elements of pname:pCreateInfos must: not include
    ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT
endif::VK_EXT_pipeline_creation_cache_control+VK_KHR_deferred_host_operations[]
****

include::{generated}/validity/protos/vkCreateRayTracingPipelinesKHR.txt[]
--
endif::VK_KHR_ray_tracing_pipeline[]

ifdef::VK_NV_ray_tracing[]
[open,refpage='VkRayTracingPipelineCreateInfoNV',desc='Structure specifying parameters of a newly created ray tracing pipeline',type='structs']
--
:refpage: VkRayTracingPipelineCreateInfoNV

The sname:VkRayTracingPipelineCreateInfoNV structure is defined as:

include::{generated}/api/structs/VkRayTracingPipelineCreateInfoNV.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying
    how the pipeline will be generated.
  * pname:stageCount is the number of entries in the pname:pStages array.
  * pname:pStages is a pointer to an array of
    slink:VkPipelineShaderStageCreateInfo structures specifying the set of
    the shader stages to be included in the ray tracing pipeline.
  * pname:groupCount is the number of entries in the pname:pGroups array.
  * pname:pGroups is a pointer to an array of
    slink:VkRayTracingShaderGroupCreateInfoNV structures describing the set
    of the shader stages to be included in each shader group in the ray
    tracing pipeline.
  * pname:maxRecursionDepth is the <<ray-tracing-recursion-depth, maximum
    recursion depth>> of shaders executed by this pipeline.
  * pname:layout is the description of binding locations used by both the
    pipeline and descriptor sets used with the pipeline.
  * pname:basePipelineHandle is a pipeline to derive from.
  * pname:basePipelineIndex is an index into the pname:pCreateInfos
    parameter to use as a pipeline to derive from.

The parameters pname:basePipelineHandle and pname:basePipelineIndex are
described in more detail in <<pipelines-pipeline-derivatives,Pipeline
Derivatives>>.

.Valid Usage
****
include::{chapters}/commonvalidity/ray_tracing_pipeline_create_info_common.txt[]
  * [[VUID-VkRayTracingPipelineCreateInfoNV-stage-06232]]
    The pname:stage member of at least one element of pname:pStages must: be
    ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR
ifdef::VK_KHR_pipeline_library[]
  * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03456]]
    pname:flags must: not include ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
endif::VK_KHR_pipeline_library[]
  * [[VUID-VkRayTracingPipelineCreateInfoNV-maxRecursionDepth-03457]]
    pname:maxRecursionDepth must: be less than or equal to
    slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxRecursionDepth
ifdef::VK_KHR_ray_tracing_pipeline[]
  * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03458]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR
  * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03459]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR
  * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03460]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR
  * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03461]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR
  * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03462]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
  * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03463]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
  * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03588]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
endif::VK_KHR_ray_tracing_pipeline[]
ifdef::VK_NV_ray_tracing_motion_blur[]
  * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-04948]]
    pname:flags must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV
endif::VK_NV_ray_tracing_motion_blur[]
ifdef::VK_EXT_pipeline_creation_cache_control[]
  * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02957]]
    pname:flags must: not include both
    ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV and
    ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT at
    the same time
endif::VK_EXT_pipeline_creation_cache_control[]
****

include::{generated}/validity/structs/VkRayTracingPipelineCreateInfoNV.txt[]
--
endif::VK_NV_ray_tracing[]

ifdef::VK_KHR_ray_tracing_pipeline[]
[open,refpage='VkRayTracingPipelineCreateInfoKHR',desc='Structure specifying parameters of a newly created ray tracing pipeline',type='structs']
--
:refpage: VkRayTracingPipelineCreateInfoKHR

The sname:VkRayTracingPipelineCreateInfoKHR structure is defined as:

include::{generated}/api/structs/VkRayTracingPipelineCreateInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying
    how the pipeline will be generated.
  * pname:stageCount is the number of entries in the pname:pStages array.
  * pname:pStages is a pointer to an array of pname:stageCount
    slink:VkPipelineShaderStageCreateInfo structures describing the set of
    the shader stages to be included in the ray tracing pipeline.
  * pname:groupCount is the number of entries in the pname:pGroups array.
  * pname:pGroups is a pointer to an array of pname:groupCount
    slink:VkRayTracingShaderGroupCreateInfoKHR structures describing the set
    of the shader stages to be included in each shader group in the ray
    tracing pipeline.
  * pname:maxPipelineRayRecursionDepth is the <<ray-tracing-recursion-depth,
    maximum recursion depth>> of shaders executed by this pipeline.
  * pname:pLibraryInfo is a pointer to a
    slink:VkPipelineLibraryCreateInfoKHR structure defining pipeline
    libraries to include.
  * pname:pLibraryInterface is a pointer to a
    slink:VkRayTracingPipelineInterfaceCreateInfoKHR structure defining
    additional information when using pipeline libraries.
  * pname:pDynamicState is a pointer to a
    slink:VkPipelineDynamicStateCreateInfo structure, and is used to
    indicate 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.
  * pname:layout is the description of binding locations used by both the
    pipeline and descriptor sets used with the pipeline.
  * pname:basePipelineHandle is a pipeline to derive from.
  * pname:basePipelineIndex is an index into the pname:pCreateInfos
    parameter to use as a pipeline to derive from.

The parameters pname:basePipelineHandle and pname:basePipelineIndex are
described in more detail in <<pipelines-pipeline-derivatives,Pipeline
Derivatives>>.

ifdef::VK_KHR_pipeline_library[]
When ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR is specified, this pipeline
defines a _pipeline library_ which cannot: be bound as a ray tracing
pipeline directly.
Instead, pipeline libraries define common shaders and shader groups which
can: be included in future pipeline creation.

If pipeline libraries are included in pname:pLibraryInfo, shaders defined in
those libraries are treated as if they were defined as additional entries in
pname:pStages, appended in the order they appear in the pname:pLibraries
array and in the pname:pStages array when those libraries were defined.

When referencing shader groups in order to obtain a shader group handle,
groups defined in those libraries are treated as if they were defined as
additional entries in pname:pGroups, appended in the order they appear in
the pname:pLibraries array and in the pname:pGroups array when those
libraries were defined.
The shaders these groups reference are set when the pipeline library is
created, referencing those specified in the pipeline library, not in the
pipeline that includes it.
endif::VK_KHR_pipeline_library[]

The default stack size for a pipeline if
ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR is not provided
is computed as described in <<ray-tracing-pipeline-stack, Ray Tracing
Pipeline Stack>>.

.Valid Usage
****
include::{chapters}/commonvalidity/ray_tracing_pipeline_create_info_common.txt[]
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-stage-03425]]
    If pname:flags does not include
    ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, the pname:stage member of at
    least one element of pname:pStages, including those implicitly added by
    pname:pLibraryInfo, must: be ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-maxPipelineRayRecursionDepth-03589]]
    pname:maxPipelineRayRecursionDepth must: be less than or equal to
    slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR::pname:maxRayRecursionDepth
ifdef::VK_KHR_pipeline_library[]
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03465]]
    If pname:flags includes ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR,
    pname:pLibraryInterface must: not be `NULL`
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03590]]
    If pname:pLibraryInfo is not `NULL` and its pname:libraryCount member is
    greater than `0`, its pname:pLibraryInterface member must: not be `NULL`
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraries-03591]]
    Each element of pname:pLibraryInfo->pLibraries must: have been created
    with the value of pname:maxPipelineRayRecursionDepth equal to that in
    this pipeline
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03592]]
    If pname:pLibraryInfo is not `NULL`, each element of its
    pname:pLibraries member must: have been created with a pname:layout that
    is compatible with the pname:layout in this pipeline
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03593]]
    If pname:pLibraryInfo is not `NULL`, each element of its
    pname:pLibraries member must: have been created with values of the
    pname:maxPipelineRayPayloadSize and pname:maxPipelineRayHitAttributeSize
    members of pname:pLibraryInterface equal to those in this pipeline
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03594]]
    If pname:flags includes
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR,
    each element of pname:pLibraryInfo->pLibraries must: have been created
    with the
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
    bit set
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04718]]
    If pname:flags includes
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR, each element of
    pname:pLibraryInfo->pLibraries must: have been created with the
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR bit set
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04719]]
    If pname:flags includes
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR, each
    element of pname:pLibraryInfo->pLibraries must: have been created with
    the ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR bit set
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04720]]
    If pname:flags includes
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR,
    each element of pname:pLibraryInfo->pLibraries must: have been created
    with the
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR bit
    set
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04721]]
    If pname:flags includes
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR,
    each element of pname:pLibraryInfo->pLibraries must: have been created
    with the
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR
    bit set
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04722]]
    If pname:flags includes
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR,
    each element of pname:pLibraryInfo->pLibraries must: have been created
    with the
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR
    bit set
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04723]]
    If pname:flags includes
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, each
    element of pname:pLibraryInfo->pLibraries must: have been created with
    the ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR
    bit set
endif::VK_KHR_pipeline_library[]
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03595]]
    If the <<VK_KHR_pipeline_library>> extension is not enabled,
    pname:pLibraryInfo and pname:pLibraryInterface must: be `NULL`.
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03470]]
    If pname:flags includes
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR,
    for any element of pname:pGroups with a pname:type of
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the
    pname:anyHitShader of that element must: not be
    ename:VK_SHADER_UNUSED_KHR
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03471]]
    If pname:flags includes
    ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR,
    for any element of pname:pGroups with a pname:type of
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the
    pname:closestHitShader of that element must: not be
    ename:VK_SHADER_UNUSED_KHR
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03596]]
    If the <<features-rayTraversalPrimitiveCulling,
    pname:rayTraversalPrimitiveCulling>> feature is not enabled, pname:flags
    must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03597]]
    If the <<features-rayTraversalPrimitiveCulling,
    pname:rayTraversalPrimitiveCulling>> feature is not enabled, pname:flags
    must: not include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03598]]
    If pname:flags includes
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR,
    <<features-rayTracingPipelineShaderGroupHandleCaptureReplay,
    pname:rayTracingPipelineShaderGroupHandleCaptureReplay>> must: be
    enabled
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplay-03599]]
    If
    slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay
    is ename:VK_TRUE and the pname:pShaderGroupCaptureReplayHandle member of
    any element of pname:pGroups is not `NULL`, pname:flags must: include
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03600]]
    If pname:pLibraryInfo is not `NULL` and its pname:libraryCount is `0`,
    pname:stageCount must: not be `0`
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03601]]
    If pname:pLibraryInfo is not `NULL` and its pname:libraryCount is `0`,
    pname:groupCount must: not be `0`
  * [[VUID-VkRayTracingPipelineCreateInfoKHR-pDynamicStates-03602]]
    Any element of the pname:pDynamicStates member of pname:pDynamicState
    must: be ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR
****

include::{generated}/validity/structs/VkRayTracingPipelineCreateInfoKHR.txt[]
--
endif::VK_KHR_ray_tracing_pipeline[]

ifdef::VK_NV_ray_tracing[]
[open,refpage='VkRayTracingShaderGroupCreateInfoNV',desc='Structure specifying shaders in a shader group',type='structs']
--
:refpage: VkRayTracingShaderGroupCreateInfoNV

The sname:VkRayTracingShaderGroupCreateInfoNV structure is defined as:

include::{generated}/api/structs/VkRayTracingShaderGroupCreateInfoNV.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:type is the type of hit group specified in this structure.
  * pname:generalShader is the index of the ray generation, miss, or
    callable shader from
    slink:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if
    the shader group has pname:type of
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV, and
    ename:VK_SHADER_UNUSED_NV otherwise.
  * pname:closestHitShader is the optional index of the closest hit shader
    from slink:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group
    if the shader group has pname:type of
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, and
    ename:VK_SHADER_UNUSED_NV otherwise.
  * pname:anyHitShader is the optional index of the any-hit shader from
    slink:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if
    the shader group has pname:type of
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, and
    ename:VK_SHADER_UNUSED_NV otherwise.
  * pname:intersectionShader is the index of the intersection shader from
    slink:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if
    the shader group has pname:type of
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, and
    ename:VK_SHADER_UNUSED_NV otherwise.

.Valid Usage
****
  * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02413]]
    If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then
    pname:generalShader must: be a valid index into
    slink:VkRayTracingPipelineCreateInfoNV::pname:pStages referring to a
    shader of ename:VK_SHADER_STAGE_RAYGEN_BIT_NV,
    ename:VK_SHADER_STAGE_MISS_BIT_NV, or
    ename:VK_SHADER_STAGE_CALLABLE_BIT_NV
  * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02414]]
    If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then
    pname:closestHitShader, pname:anyHitShader, and pname:intersectionShader
    must: be ename:VK_SHADER_UNUSED_NV
  * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02415]]
    If pname:type is
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV then
    pname:intersectionShader must: be a valid index into
    slink:VkRayTracingPipelineCreateInfoNV::pname:pStages referring to a
    shader of ename:VK_SHADER_STAGE_INTERSECTION_BIT_NV
  * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02416]]
    If pname:type is
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV then
    pname:intersectionShader must: be ename:VK_SHADER_UNUSED_NV
  * [[VUID-VkRayTracingShaderGroupCreateInfoNV-closestHitShader-02417]]
    pname:closestHitShader must: be either ename:VK_SHADER_UNUSED_NV or a
    valid index into slink:VkRayTracingPipelineCreateInfoNV::pname:pStages
    referring to a shader of ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV
  * [[VUID-VkRayTracingShaderGroupCreateInfoNV-anyHitShader-02418]]
    pname:anyHitShader must: be either ename:VK_SHADER_UNUSED_NV or a valid
    index into slink:VkRayTracingPipelineCreateInfoNV::pname:pStages
    referring to a shader of ename:VK_SHADER_STAGE_ANY_HIT_BIT_NV
****

include::{generated}/validity/structs/VkRayTracingShaderGroupCreateInfoNV.txt[]
--

endif::VK_NV_ray_tracing[]

ifdef::VK_KHR_ray_tracing_pipeline[]
[open,refpage='VkRayTracingShaderGroupCreateInfoKHR',desc='Structure specifying shaders in a shader group',type='structs']
--
:refpage: VkRayTracingShaderGroupCreateInfoKHR

The sname:VkRayTracingShaderGroupCreateInfoKHR structure is defined as:

include::{generated}/api/structs/VkRayTracingShaderGroupCreateInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:type is the type of hit group specified in this structure.
  * pname:generalShader is the index of the ray generation, miss, or
    callable shader from
    slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages in the group if
    the shader group has pname:type of
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR, and
    ename:VK_SHADER_UNUSED_KHR otherwise.
  * pname:closestHitShader is the optional index of the closest hit shader
    from slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages in the group
    if the shader group has pname:type of
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and
    ename:VK_SHADER_UNUSED_KHR otherwise.
  * pname:anyHitShader is the optional index of the any-hit shader from
    slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages in the group if
    the shader group has pname:type of
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and
    ename:VK_SHADER_UNUSED_KHR otherwise.
  * pname:intersectionShader is the index of the intersection shader from
    slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages in the group if
    the shader group has pname:type of
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and
    ename:VK_SHADER_UNUSED_KHR otherwise.
  * pname:pShaderGroupCaptureReplayHandle is an optional pointer to replay
    information for this shader group.
    Ignored if
    slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay
    is ename:VK_FALSE.

.Valid Usage
****
  * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03474]]
    If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR then
    pname:generalShader must: be a valid index into
    slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages referring to a
    shader of ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR,
    ename:VK_SHADER_STAGE_MISS_BIT_KHR, or
    ename:VK_SHADER_STAGE_CALLABLE_BIT_KHR
  * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03475]]
    If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR then
    pname:closestHitShader, pname:anyHitShader, and pname:intersectionShader
    must: be ename:VK_SHADER_UNUSED_KHR
  * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03476]]
    If pname:type is
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR then
    pname:intersectionShader must: be a valid index into
    slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages referring to a
    shader of ename:VK_SHADER_STAGE_INTERSECTION_BIT_KHR
  * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03477]]
    If pname:type is
    ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR then
    pname:intersectionShader must: be ename:VK_SHADER_UNUSED_KHR
  * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-closestHitShader-03478]]
    pname:closestHitShader must: be either ename:VK_SHADER_UNUSED_KHR or a
    valid index into slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages
    referring to a shader of ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR
  * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-anyHitShader-03479]]
    pname:anyHitShader must: be either ename:VK_SHADER_UNUSED_KHR or a valid
    index into slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages
    referring to a shader of ename:VK_SHADER_STAGE_ANY_HIT_BIT_KHR
  * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplayMixed-03603]]
    If
    slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplayMixed
    is ename:VK_FALSE then pname:pShaderGroupCaptureReplayHandle must: not
    be provided if it has not been provided on a previous call to ray
    tracing pipeline creation
  * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplayMixed-03604]]
    If
    slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplayMixed
    is ename:VK_FALSE then the caller must: guarantee that no ray tracing
    pipeline creation commands with pname:pShaderGroupCaptureReplayHandle
    provided execute simultaneously with ray tracing pipeline creation
    commands without pname:pShaderGroupCaptureReplayHandle provided
****

include::{generated}/validity/structs/VkRayTracingShaderGroupCreateInfoKHR.txt[]
--
endif::VK_KHR_ray_tracing_pipeline[]

[open,refpage='VkRayTracingShaderGroupTypeKHR',desc='Shader group types',type='enums',alias='VkRayTracingShaderGroupTypeNV']
--
:refpage: VkRayTracingShaderGroupTypeKHR

Possible values of pname:type in sname:VkRayTracingShaderGroupCreateInfoKHR
are:

include::{generated}/api/enums/VkRayTracingShaderGroupTypeKHR.txt[]

ifdef::VK_NV_ray_tracing[]
or the equivalent

include::{generated}/api/enums/VkRayTracingShaderGroupTypeNV.txt[]
endif::VK_NV_ray_tracing[]

  * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR indicates a shader
    group with a single ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR,
    ename:VK_SHADER_STAGE_MISS_BIT_KHR, or
    ename:VK_SHADER_STAGE_CALLABLE_BIT_KHR shader in it.
  * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR specifies
    a shader group that only hits triangles and must: not contain an
    intersection shader, only closest hit and any-hit shaders.
  * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR
    specifies a shader group that only intersects with custom geometry and
    must: contain an intersection shader and may: contain closest hit and
    any-hit shaders.

[NOTE]
.Note
====
For current group types, the hit group type could be inferred from the
presence or absence of the intersection shader, but we provide the type
explicitly for future hit groups that do not have that property.
====
--

ifdef::VK_KHR_ray_tracing_pipeline[]
[open,refpage='VkRayTracingPipelineInterfaceCreateInfoKHR',desc='Structure specifying additional interface information when using libraries',type='structs']
--
:refpage: VkRayTracingPipelineInterfaceCreateInfoKHR

The sname:VkRayTracingPipelineInterfaceCreateInfoKHR structure is defined
as:

include::{generated}/api/structs/VkRayTracingPipelineInterfaceCreateInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:maxPipelineRayPayloadSize is the maximum payload size in bytes
    used by any shader in the pipeline.
  * pname:maxPipelineRayHitAttributeSize is the maximum attribute structure
    size in bytes used by any shader in the pipeline.

pname:maxPipelineRayPayloadSize is calculated as the maximum number of bytes
used by any block declared in the code:RayPayloadKHR or
code:IncomingRayPayloadKHR storage classes.
pname:maxPipelineRayHitAttributeSize is calculated as the maximum number of
bytes used by any block declared in the code:HitAttributeKHR storage class.
As variables in these storage classes do not have explicit offsets, the size
should be calculated as if each variable has a
<<interfaces-alignment-requirements, scalar alignment>> equal to the largest
scalar alignment of any of the block's members.

[NOTE]
.Note
====
There is no explicit upper limit for pname:maxPipelineRayPayloadSize, but in
practice it should be kept as small as possible.
Similar to invocation local memory, it must be allocated for each shader
invocation and for devices which support many simultaneous invocations, this
storage can rapidly be exhausted, resulting in failure.
====

.Valid Usage
****
  * [[VUID-VkRayTracingPipelineInterfaceCreateInfoKHR-maxPipelineRayHitAttributeSize-03605]]
    pname:maxPipelineRayHitAttributeSize must: be less than or equal to
    slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR::pname:maxRayHitAttributeSize
****

include::{generated}/validity/structs/VkRayTracingPipelineInterfaceCreateInfoKHR.txt[]
--
endif::VK_KHR_ray_tracing_pipeline[]

[open,refpage='vkGetRayTracingShaderGroupHandlesKHR',desc='Query ray tracing pipeline shader group handles',type='protos',alias='vkGetRayTracingShaderGroupHandlesNV']
--
:refpage: vkGetRayTracingShaderGroupHandlesKHR

To query the opaque handles of shaders in the ray tracing pipeline, call:

ifdef::VK_KHR_ray_tracing_pipeline[]
include::{generated}/api/protos/vkGetRayTracingShaderGroupHandlesKHR.txt[]
endif::VK_KHR_ray_tracing_pipeline[]

ifdef::VK_KHR_ray_tracing_pipeline+VK_NV_ray_tracing[or the equivalent command]

ifdef::VK_NV_ray_tracing[]
include::{generated}/api/protos/vkGetRayTracingShaderGroupHandlesNV.txt[]
endif::VK_NV_ray_tracing[]

  * pname:device is the logical device containing the ray tracing pipeline.
  * pname:pipeline is the ray tracing pipeline object containing the
    shaders.
  * pname:firstGroup is the index of the first group to retrieve a handle
    for from the
ifdef::VK_KHR_ray_tracing_pipeline[]
slink:VkRayTracingPipelineCreateInfoKHR::pname:pGroups
endif::VK_KHR_ray_tracing_pipeline[]
ifdef::VK_KHR_ray_tracing_pipeline+VK_NV_ray_tracing[or]
ifdef::VK_NV_ray_tracing[]
slink:VkRayTracingPipelineCreateInfoNV::pname:pGroups
endif::VK_NV_ray_tracing[]
    array.
  * pname:groupCount is the number of shader handles to retrieve.
  * pname:dataSize is the size in bytes of the buffer pointed to by
    pname:pData.
  * pname:pData is a pointer to a user-allocated buffer where the results
    will be written.

.Valid Usage
****
  * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-04619]]
    pname:pipeline must: be a ray tracing pipeline
  * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-firstGroup-04050]]
    pname:firstGroup must: be less than the number of shader groups in
    pname:pipeline
  * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-firstGroup-02419]]
    The sum of pname:firstGroup and pname:groupCount must: be less than or
    equal to the number of shader groups in pname:pipeline
  * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-dataSize-02420]]
    pname:dataSize must: be at least
    [eq]#slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR::pname:shaderGroupHandleSize
    {times} pname:groupCount#
ifdef::VK_KHR_pipeline_library[]
  * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-03482]]
    pname:pipeline must: have not been created with
    ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
endif::VK_KHR_pipeline_library[]
****

include::{generated}/validity/protos/vkGetRayTracingShaderGroupHandlesKHR.txt[]
--

ifdef::VK_KHR_ray_tracing_pipeline[]
[open,refpage='vkGetRayTracingCaptureReplayShaderGroupHandlesKHR',desc='Query ray tracing capture replay pipeline shader group handles',type='protos']
--
:refpage: vkGetRayTracingCaptureReplayShaderGroupHandlesKHR

To query the optional capture handle information of shaders in the ray
tracing pipeline, call:

include::{generated}/api/protos/vkGetRayTracingCaptureReplayShaderGroupHandlesKHR.txt[]

  * pname:device is the logical device containing the ray tracing pipeline.
  * pname:pipeline is the ray tracing pipeline object containing the
    shaders.
  * pname:firstGroup is the index of the first group to retrieve a handle
    for from the slink:VkRayTracingPipelineCreateInfoKHR::pname:pGroups
    array.
  * pname:groupCount is the number of shader handles to retrieve.
  * pname:dataSize is the size in bytes of the buffer pointed to by
    pname:pData.
  * pname:pData is a pointer to a user-allocated buffer where the results
    will be written.

.Valid Usage
****
  * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-04620]]
    pname:pipeline must: be a ray tracing pipeline
  * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-firstGroup-04051]]
    pname:firstGroup must: be less than the number of shader groups in
    pname:pipeline
  * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-firstGroup-03483]]
    The sum of pname:firstGroup and pname:groupCount must: be less than or
    equal to the number of shader groups in pname:pipeline
  * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-dataSize-03484]]
    pname:dataSize must: be at least
    [eq]#slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR::pname:shaderGroupHandleCaptureReplaySize
    {times} pname:groupCount#
  * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-rayTracingPipelineShaderGroupHandleCaptureReplay-03606]]
    sname:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay
    must: be enabled to call this function
  * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-03607]]
    pname:pipeline must: have been created with a pname:flags that included
    ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
****

include::{generated}/validity/protos/vkGetRayTracingCaptureReplayShaderGroupHandlesKHR.txt[]
--
endif::VK_KHR_ray_tracing_pipeline[]

ifdef::VK_NV_ray_tracing[]
Ray tracing pipelines can: contain more shaders than a graphics or compute
pipeline, so to allow parallel compilation of shaders within a pipeline, an
application can: choose to defer compilation until a later point in time.

[open,refpage='vkCompileDeferredNV',desc='Deferred compilation of shaders',type='protos']
--
:refpage: vkCompileDeferredNV

To compile a deferred shader in a pipeline call:

include::{generated}/api/protos/vkCompileDeferredNV.txt[]

  * pname:device is the logical device containing the ray tracing pipeline.
  * pname:pipeline is the ray tracing pipeline object containing the
    shaders.
  * pname:shader is the index of the shader to compile.

.Valid Usage
****
  * [[VUID-vkCompileDeferredNV-pipeline-04621]]
    pname:pipeline must: be a ray tracing pipeline
  * [[VUID-vkCompileDeferredNV-pipeline-02237]]
    pname:pipeline must: have been created with
    ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV
  * [[VUID-vkCompileDeferredNV-shader-02238]]
    pname:shader must: not have been called as a deferred compile before
****

include::{generated}/validity/protos/vkCompileDeferredNV.txt[]
--
endif::VK_NV_ray_tracing[]

ifdef::VK_KHR_ray_tracing_pipeline[]
[open,refpage='vkGetRayTracingShaderGroupStackSizeKHR',desc='Query ray tracing pipeline shader group shader stack size',type='protos']
--
To query the pipeline stack size of shaders in a shader group in the ray
tracing pipeline, call:

include::{generated}/api/protos/vkGetRayTracingShaderGroupStackSizeKHR.txt[]

  * pname:device is the logical device containing the ray tracing pipeline.
  * pname:pipeline is the ray tracing pipeline object containing the shaders
    groups.
  * pname:group is the index of the shader group to query.
  * pname:groupShader is the type of shader from the group to query.

The return value is the ray tracing pipeline stack size in bytes for the
specified shader as called from the specified shader group.

.Valid Usage
****
  * [[VUID-vkGetRayTracingShaderGroupStackSizeKHR-pipeline-04622]]
    pname:pipeline must: be a ray tracing pipeline
  * [[VUID-vkGetRayTracingShaderGroupStackSizeKHR-group-03608]]
    The value of pname:group must be less than the number of shader groups
    in pname:pipeline
  * [[VUID-vkGetRayTracingShaderGroupStackSizeKHR-groupShader-03609]]
    The shader identified by pname:groupShader in pname:group must: not be
    ename:VK_SHADER_UNUSED_KHR
****

include::{generated}/validity/protos/vkGetRayTracingShaderGroupStackSizeKHR.txt[]
--

[open,refpage='VkShaderGroupShaderKHR',desc='Shader group shaders',type='enums']
--
Possible values of pname:groupShader in
flink:vkGetRayTracingShaderGroupStackSizeKHR are:

include::{generated}/api/enums/VkShaderGroupShaderKHR.txt[]

  * ename:VK_SHADER_GROUP_SHADER_GENERAL_KHR uses the shader specified in
    the group with
    slink:VkRayTracingShaderGroupCreateInfoKHR::pname:generalShader
  * ename:VK_SHADER_GROUP_SHADER_CLOSEST_HIT_KHR uses the shader specified
    in the group with
    slink:VkRayTracingShaderGroupCreateInfoKHR::pname:closestHitShader
  * ename:VK_SHADER_GROUP_SHADER_ANY_HIT_KHR uses the shader specified in
    the group with
    slink:VkRayTracingShaderGroupCreateInfoKHR::pname:anyHitShader
  * ename:VK_SHADER_GROUP_SHADER_INTERSECTION_KHR uses the shader specified
    in the group with
    slink:VkRayTracingShaderGroupCreateInfoKHR::pname:intersectionShader
--


[open,refpage='vkCmdSetRayTracingPipelineStackSizeKHR',desc='Set the dynamic stack size for a ray tracing pipeline',type='protos']
--
:refpage: vkCmdSetRayTracingPipelineStackSizeKHR

To set the dynamic stack size for a ray tracing pipeline call:

include::{generated}/api/protos/vkCmdSetRayTracingPipelineStackSizeKHR.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pipelineStackSize is the stack size to use for subsequent ray
    tracing trace commands.

See <<ray-tracing-pipeline-stack, Ray Tracing Pipeline Stack>> for more on
computing pname:pipelineStackSize.

.Valid Usage
****
  * [[VUID-vkCmdSetRayTracingPipelineStackSizeKHR-pipelineStackSize-03610]]
    pname:pipelineStackSize must: be large enough for any dynamic execution
    through the shaders in the ray tracing pipeline used by a subsequent
    trace call
****
include::{generated}/validity/protos/vkCmdSetRayTracingPipelineStackSizeKHR.txt[]
--
endif::VK_KHR_ray_tracing_pipeline[]
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]


[[pipelines-destruction]]
== Pipeline Destruction

[open,refpage='vkDestroyPipeline',desc='Destroy a pipeline object',type='protos']
--
To destroy a pipeline, call:

include::{generated}/api/protos/vkDestroyPipeline.txt[]

  * pname:device is the logical device that destroys the pipeline.
  * pname:pipeline is the handle of the pipeline to destroy.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.

.Valid Usage
****
  * [[VUID-vkDestroyPipeline-pipeline-00765]]
    All submitted commands that refer to pname:pipeline must: have completed
    execution
  * [[VUID-vkDestroyPipeline-pipeline-00766]]
    If sname:VkAllocationCallbacks were provided when pname:pipeline was
    created, a compatible set of callbacks must: be provided here
  * [[VUID-vkDestroyPipeline-pipeline-00767]]
    If no sname:VkAllocationCallbacks were provided when pname:pipeline was
    created, pname:pAllocator must: be `NULL`
****

include::{generated}/validity/protos/vkDestroyPipeline.txt[]
--


[[pipelines-multiple]]
== Multiple Pipeline Creation

Multiple pipelines can: be created simultaneously by passing an array of
slink:VkGraphicsPipelineCreateInfo,
ifdef::VK_KHR_ray_tracing_pipeline[slink:VkRayTracingPipelineCreateInfoKHR,]
ifdef::VK_NV_ray_tracing[slink:VkRayTracingPipelineCreateInfoNV,]
or slink:VkComputePipelineCreateInfo structures into the
flink:vkCreateGraphicsPipelines,
ifdef::VK_KHR_ray_tracing_pipeline[flink:vkCreateRayTracingPipelinesKHR,]
ifdef::VK_NV_ray_tracing[flink:vkCreateRayTracingPipelinesNV,]
and flink:vkCreateComputePipelines commands, respectively.
Applications can: group together similar pipelines to be created in a single
call, and implementations are encouraged to look for reuse opportunities
within a group-create.

When an application attempts to create many pipelines in a single command,
it is possible that some subset may: fail creation.
In that case, the corresponding entries in the pname:pPipelines output array
will be filled with dlink:VK_NULL_HANDLE values.
If any pipeline fails creation despite valid arguments (for example, due to
out of memory errors), the elink:VkResult code returned by
ftext:vkCreate*Pipelines will indicate why.
The implementation will attempt to create all pipelines, and only return
dlink:VK_NULL_HANDLE values for those that actually failed.

ifdef::VK_EXT_pipeline_creation_cache_control[]
If creation fails for a pipeline that had
ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT set, pipelines at
an index in the pname:pPipelines array greater than or equal to that of the
failing pipeline must: be set to dlink:VK_NULL_HANDLE.
endif::VK_EXT_pipeline_creation_cache_control[]

[[pipelines-pipeline-derivatives]]
== 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
ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag in the
stext:Vk*PipelineCreateInfo structure.
If this is set, then exactly one of pname:basePipelineHandle or
pname:basePipelineIndex members of the structure must: have a valid
handle/index, and specifies the parent pipeline.
If pname:basePipelineHandle is used, the parent pipeline must: have already
been created.
If pname:basePipelineIndex is used, then the parent is being created in the
same command.
dlink:VK_NULL_HANDLE acts as the invalid handle for
pname:basePipelineHandle, and -1 is the invalid index for
pname:basePipelineIndex.
If pname:basePipelineIndex is used, the base pipeline must: appear earlier
in the array.
The base pipeline must: have been created with the
ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set.


[[pipelines-cache]]
== Pipeline Cache

[open,refpage='VkPipelineCache',desc='Opaque handle to a pipeline cache object',type='handles']
--
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 sname:VkPipelineCache handles:

include::{generated}/api/handles/VkPipelineCache.txt[]
--

[[pipelines-cache-create]]
=== Creating a Pipeline Cache

[open,refpage='vkCreatePipelineCache',desc='Creates a new pipeline cache',type='protos']
--
To create pipeline cache objects, call:

include::{generated}/api/protos/vkCreatePipelineCache.txt[]

  * pname:device is the logical device that creates the pipeline cache
    object.
  * pname:pCreateInfo is a pointer to a slink:VkPipelineCacheCreateInfo
    structure containing initial parameters for the pipeline cache object.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.
  * pname:pPipelineCache is a pointer to a slink:VkPipelineCache handle in
    which the resulting pipeline cache object is returned.

[NOTE]
.Note
====
Applications can: track and manage the total host memory size of a pipeline
cache object using the pname:pAllocator.
Applications can: limit the amount of data retrieved from a pipeline cache
object in fname: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
flink:vkCreateGraphicsPipelines
ifdef::VK_KHR_ray_tracing_pipeline[flink:vkCreateRayTracingPipelinesKHR,]
ifdef::VK_NV_ray_tracing[flink:vkCreateRayTracingPipelinesNV,]
and flink:vkCreateComputePipelines commands.
If the pipeline cache passed into these commands is not
dlink: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.

ifdef::VK_EXT_pipeline_creation_cache_control[]
If pname:flags of pname:pCreateInfo includes
ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT, all commands
that modify the returned pipeline cache object must: be
<<fundamentals-threadingbehavior,externally synchronized>>.
endif::VK_EXT_pipeline_creation_cache_control[]

[NOTE]
.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 ftext:vkCreate*Pipelines commands.
====

include::{generated}/validity/protos/vkCreatePipelineCache.txt[]
--

[open,refpage='VkPipelineCacheCreateInfo',desc='Structure specifying parameters of a newly created pipeline cache',type='structs']
--
The sname:VkPipelineCacheCreateInfo structure is defined as:

include::{generated}/api/structs/VkPipelineCacheCreateInfo.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
ifdef::VK_EXT_pipeline_creation_cache_control[]
  * pname:flags is a bitmask of elink:VkPipelineCacheCreateFlagBits
    specifying the behavior of the pipeline cache.
endif::VK_EXT_pipeline_creation_cache_control[]
ifndef::VK_EXT_pipeline_creation_cache_control[]
  * pname:flags is reserved for future use.
endif::VK_EXT_pipeline_creation_cache_control[]
  * pname:initialDataSize is the number of bytes in pname:pInitialData.
    If pname:initialDataSize is zero, the pipeline cache will initially be
    empty.
  * pname: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 pname:initialDataSize is zero, pname:pInitialData is ignored.

.Valid Usage
****
  * [[VUID-VkPipelineCacheCreateInfo-initialDataSize-00768]]
    If pname:initialDataSize is not `0`, it must: be equal to the size of
    pname:pInitialData, as returned by fname:vkGetPipelineCacheData when
    pname:pInitialData was originally retrieved
  * [[VUID-VkPipelineCacheCreateInfo-initialDataSize-00769]]
    If pname:initialDataSize is not `0`, pname:pInitialData must: have been
    retrieved from a previous call to fname:vkGetPipelineCacheData
ifdef::VK_EXT_pipeline_creation_cache_control[]
  * [[VUID-VkPipelineCacheCreateInfo-pipelineCreationCacheControl-02892]]
    If the <<features-pipelineCreationCacheControl,
    pname:pipelineCreationCacheControl>> feature is not enabled, pname:flags
    must: not include
    ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT
endif::VK_EXT_pipeline_creation_cache_control[]
****

include::{generated}/validity/structs/VkPipelineCacheCreateInfo.txt[]
--

[open,refpage='VkPipelineCacheCreateFlags', desc='Bitmask of VkPipelineCreateFlagBits', type='flags']
--
include::{generated}/api/flags/VkPipelineCacheCreateFlags.txt[]

ifdef::VK_EXT_pipeline_creation_cache_control[]
tname:VkPipelineCacheCreateFlags is a bitmask type for setting a mask of
zero or more elink:VkPipelineCacheCreateFlagBits.
endif::VK_EXT_pipeline_creation_cache_control[]
ifndef::VK_EXT_pipeline_creation_cache_control[]
tname:VkPipelineCacheCreateFlags is a bitmask type for setting a mask, but
is currently reserved for future use.
endif::VK_EXT_pipeline_creation_cache_control[]
--

ifdef::VK_EXT_pipeline_creation_cache_control[]
[open,refpage='VkPipelineCacheCreateFlagBits',desc='Bitmask specifying the behavior of the pipeline cache',type='enums']
--
Possible values of the pname:flags member of
slink:VkPipelineCacheCreateInfo, specifying the behavior of the pipeline
cache, are:

include::{generated}/api/enums/VkPipelineCacheCreateFlagBits.txt[]

  * ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT specifies
    that all commands that modify the created slink:VkPipelineCache will be
    <<fundamentals-threadingbehavior,externally synchronized>>.
    When set, the implementation may: skip any unnecessary processing needed
    to support simultaneous modification from multiple threads where
    allowed.
--
endif::VK_EXT_pipeline_creation_cache_control[]

[[pipelines-cache-merge]]
=== Merging Pipeline Caches

[open,refpage='vkMergePipelineCaches',desc='Combine the data stores of pipeline caches',type='protos']
--
Pipeline cache objects can: be merged using the command:

include::{generated}/api/protos/vkMergePipelineCaches.txt[]

  * pname:device is the logical device that owns the pipeline cache objects.
  * pname:dstCache is the handle of the pipeline cache to merge results
    into.
  * pname:srcCacheCount is the length of the pname:pSrcCaches array.
  * pname:pSrcCaches is a pointer to an array of pipeline cache handles,
    which will be merged into pname:dstCache.
    The previous contents of pname:dstCache are included after the merge.

[NOTE]
.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]]
    pname:dstCache must: not appear in the list of source caches
****

include::{generated}/validity/protos/vkMergePipelineCaches.txt[]
--

[[pipelines-cache-retrieval]]
=== Retrieving Pipeline Cache Data

[open,refpage='vkGetPipelineCacheData',desc='Get the data store from a pipeline cache',type='protos']
--
Data can: be retrieved from a pipeline cache object using the command:

include::{generated}/api/protos/vkGetPipelineCacheData.txt[]

  * pname:device is the logical device that owns the pipeline cache.
  * pname:pipelineCache is the pipeline cache to retrieve data from.
  * pname:pDataSize is a pointer to a code:size_t value related to the
    amount of data in the pipeline cache, as described below.
  * pname:pData is either `NULL` or a pointer to a buffer.

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

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

Two calls to fname: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 pname:pData must: be a header as described in
the <<pipelines-cache-header, Pipeline Cache Header>> section.

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

include::{generated}/validity/protos/vkGetPipelineCacheData.txt[]
--

[[pipelines-cache-header]]
=== 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.

[open,refpage='VkPipelineCacheHeaderVersionOne',desc='Structure describing the layout of the pipeline cache header',type='structs']
--
Version one of the pipeline cache header is defined as:

include::{generated}/api/structs/VkPipelineCacheHeaderVersionOne.txt[]

  * pname:headerSize is the length in bytes of the pipeline cache header.
  * pname:headerVersion is a elink:VkPipelineCacheHeaderVersion enum 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.
  * pname:vendorID is the sname:VkPhysicalDeviceProperties::pname:vendorID
    of the implementation.
  * pname:deviceID is the sname:VkPhysicalDeviceProperties::pname:deviceID
    of the implementation.
  * pname:pipelineCacheUUID is the
    sname:VkPhysicalDeviceProperties::pname: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]]
    pname:headerSize must: be 32
  * [[VUID-VkPipelineCacheHeaderVersionOne-headerVersion-04968]]
    pname:headerVersion must: be ename:VK_PIPELINE_CACHE_HEADER_VERSION_ONE
****

include::{generated}/validity/structs/VkPipelineCacheHeaderVersionOne.txt[]
--


[open,refpage='VkPipelineCacheHeaderVersion',desc='Encode pipeline cache version',type='enums',xrefs='vkCreatePipelineCache vkGetPipelineCacheData']
--
Possible values of the pname:headerVersion value of the pipeline cache
header are:

include::{generated}/api/enums/VkPipelineCacheHeaderVersion.txt[]

  * ename:VK_PIPELINE_CACHE_HEADER_VERSION_ONE specifies version one of the
    pipeline cache.
--

[[pipelines-cache-destroy]]
=== Destroying a Pipeline Cache

[open,refpage='vkDestroyPipelineCache',desc='Destroy a pipeline cache object',type='protos']
--
To destroy a pipeline cache, call:

include::{generated}/api/protos/vkDestroyPipelineCache.txt[]

  * pname:device is the logical device that destroys the pipeline cache
    object.
  * pname:pipelineCache is the handle of the pipeline cache to destroy.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.

.Valid Usage
****
  * [[VUID-vkDestroyPipelineCache-pipelineCache-00771]]
    If sname:VkAllocationCallbacks were provided when pname:pipelineCache
    was created, a compatible set of callbacks must: be provided here
  * [[VUID-vkDestroyPipelineCache-pipelineCache-00772]]
    If no sname:VkAllocationCallbacks were provided when pname:pipelineCache
    was created, pname:pAllocator must: be `NULL`
****

include::{generated}/validity/protos/vkDestroyPipelineCache.txt[]
--


[[pipelines-specialization-constants]]
== Specialization Constants

Specialization constants are a mechanism whereby constants in a SPIR-V
module can: have their constant value specified at the time the
sname: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]
.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 slink:VkPipelineShaderStageCreateInfo structure contains a
pname:pSpecializationInfo member, which can: be `NULL` to indicate no
specialization constants, or point to a sname:VkSpecializationInfo
structure.

[open,refpage='VkSpecializationInfo',desc='Structure specifying specialization information',type='structs']
--
The sname:VkSpecializationInfo structure is defined as:

include::{generated}/api/structs/VkSpecializationInfo.txt[]

  * pname:mapEntryCount is the number of entries in the pname:pMapEntries
    array.
  * pname:pMapEntries is a pointer to an array of
    sname:VkSpecializationMapEntry structures which map constant IDs to
    offsets in pname:pData.
  * pname:dataSize is the byte size of the pname:pData buffer.
  * pname:pData contains the actual constant values to specialize with.

.Valid Usage
****
  * [[VUID-VkSpecializationInfo-offset-00773]]
    The pname:offset member of each element of pname:pMapEntries must: be
    less than pname:dataSize
  * [[VUID-VkSpecializationInfo-pMapEntries-00774]]
    The pname:size member of each element of pname:pMapEntries must: be less
    than or equal to pname:dataSize minus pname:offset
  * [[VUID-VkSpecializationInfo-constantID-04911]]
    The pname:constantID value of each element of pname:pMapEntries must: be
    unique within pname:pMapEntries
****

include::{generated}/validity/structs/VkSpecializationInfo.txt[]
--

[open,refpage='VkSpecializationMapEntry',desc='Structure specifying a specialization map entry',type='structs']
--
The sname:VkSpecializationMapEntry structure is defined as:

include::{generated}/api/structs/VkSpecializationMapEntry.txt[]

  * pname:constantID is the ID of the specialization constant in SPIR-V.
  * pname:offset is the byte offset of the specialization constant value
    within the supplied data buffer.
  * pname:size is the byte size of the specialization constant value within
    the supplied data buffer.

If a pname: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 pname:constantID specialization constant declared in a shader,
    pname:size must: match the byte size of the pname:constantID.
    If the specialization constant is of type code:boolean, pname:size must:
    be the byte size of basetype:VkBool32
****

include::{generated}/validity/structs/VkSpecializationMapEntry.txt[]
--

In human readable SPIR-V:

[source,glsl]
---------------------------------------------------
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:

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

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

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

Then when calling flink:vkCreateComputePipelines, and passing the
sname:VkSpecializationInfo we defined as the pname:pSpecializationInfo
parameter of slink: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:

// [source,glsl]
[source,glsl]
---------------------------------------------------
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:

[source,c++]
---------------------------------------------------
struct SpecializationData {
    int32_t data0;
    float data1;
};

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

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 =
{
    2,                                  // mapEntryCount
    entries,                            // pMapEntries
    sizeof(data),                       // dataSize
    &data,                              // pData
};
---------------------------------------------------

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.


ifdef::VK_KHR_pipeline_library[]
[[pipeline-library]]
== Pipeline Libraries

A pipeline library is a special pipeline that was created using the
ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and cannot be bound, instead it
defines a set of pipeline state which can be linked into other pipelines.
ifdef::VK_KHR_ray_tracing_pipeline[]
For ray tracing pipelines this includes shaders and shader groups.
endif::VK_KHR_ray_tracing_pipeline[]
The application must: maintain the lifetime of a pipeline library based on
the pipelines that link with it.
A pipeline library is considered in-use, as long as one of the linking
pipelines is in-use.

This linkage is achieved by using the following structure within the
appropriate creation mechanisms:

[open,refpage='VkPipelineLibraryCreateInfoKHR',desc='Structure specifying pipeline libraries to use when creating a pipeline',type='structs']
--
The sname:VkPipelineLibraryCreateInfoKHR structure is defined as:

include::{generated}/api/structs/VkPipelineLibraryCreateInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:libraryCount is the number of pipeline libraries in
    pname:pLibraries.
  * pname:pLibraries is a pointer to an array of slink:VkPipeline structures
    specifying pipeline libraries to use when creating a pipeline.

.Valid Usage
****
  * [[VUID-VkPipelineLibraryCreateInfoKHR-pLibraries-03381]]
    Each element of pname:pLibraries must: have been created with
    ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR
****

include::{generated}/validity/structs/VkPipelineLibraryCreateInfoKHR.txt[]
--
endif::VK_KHR_pipeline_library[]


[[pipelines-binding]]
== Pipeline Binding

[open,refpage='vkCmdBindPipeline',desc='Bind a pipeline object to a command buffer',type='protos']
--
Once a pipeline has been created, it can: be bound to the command buffer
using the command:

include::{generated}/api/protos/vkCmdBindPipeline.txt[]

  * pname:commandBuffer is the command buffer that the pipeline will be
    bound to.
  * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying
    to which bind point the pipeline is bound.
    Binding one does not disturb the others.
  * pname:pipeline is the pipeline to be bound.

[[pipeline-bindpoint-commands]]
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.

  * The pipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE controls the
    behavior of all <<dispatch, dispatching commands>>.
  * The pipeline bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS controls the
    behavior of all <<drawing, drawing commands>>.
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
  * The pipeline bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR
    controls the behavior of flink:vkCmdTraceRaysKHR and
    flink:vkCmdTraceRaysIndirectKHR.
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
ifdef::VK_HUAWEI_subpass_shading[]
  * The pipeline bound to
    ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI controls the
    behavior of flink:vkCmdSubpassShadingHUAWEI.
endif::VK_HUAWEI_subpass_shading[]

.Valid Usage
****
  * [[VUID-vkCmdBindPipeline-pipelineBindPoint-00777]]
    If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE, the
    sname:VkCommandPool that pname:commandBuffer was allocated from must:
    support compute operations
  * [[VUID-vkCmdBindPipeline-pipelineBindPoint-00778]]
    If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_GRAPHICS, the
    sname:VkCommandPool that pname:commandBuffer was allocated from must:
    support graphics operations
  * [[VUID-vkCmdBindPipeline-pipelineBindPoint-00779]]
    If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE,
    pname:pipeline must: be a compute pipeline
  * [[VUID-vkCmdBindPipeline-pipelineBindPoint-00780]]
    If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_GRAPHICS,
    pname:pipeline must: be a graphics pipeline
  * [[VUID-vkCmdBindPipeline-pipeline-00781]]
    If the <<features-variableMultisampleRate,variable multisample rate>>
    feature is not supported, pname:pipeline is a graphics pipeline, the
    current subpass <<renderpass-noattachments, 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
ifdef::VK_EXT_sample_locations[]
  * [[VUID-vkCmdBindPipeline-variableSampleLocations-01525]]
    If
    slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations
    is ename:VK_FALSE, and pname:pipeline is a graphics pipeline created
    with a slink:VkPipelineSampleLocationsStateCreateInfoEXT structure
    having its pname:sampleLocationsEnable member set to ename:VK_TRUE but
    without ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT enabled then the
    current render pass instance must: have been begun by specifying a
    slink:VkRenderPassSampleLocationsBeginInfoEXT structure whose
    pname:pPostSubpassSampleLocations member contains an element with a
    pname:subpassIndex matching the current subpass index and the
    pname:sampleLocationsInfo member of that element must: match the
    pname:sampleLocationsInfo specified in
    slink:VkPipelineSampleLocationsStateCreateInfoEXT when the pipeline was
    created
endif::VK_EXT_sample_locations[]
ifdef::VK_EXT_transform_feedback[]
  * [[VUID-vkCmdBindPipeline-None-02323]]
    This command must: not be recorded when transform feedback is active
endif::VK_EXT_transform_feedback[]
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
  * [[VUID-vkCmdBindPipeline-pipelineBindPoint-02391]]
    If pname:pipelineBindPoint is
    ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, the sname:VkCommandPool
    that pname:commandBuffer was allocated from must: support compute
    operations
  * [[VUID-vkCmdBindPipeline-pipelineBindPoint-02392]]
    If pname:pipelineBindPoint is
    ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, pname:pipeline must: be a
    ray tracing pipeline
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
ifdef::VK_KHR_pipeline_library[]
  * [[VUID-vkCmdBindPipeline-pipeline-03382]]
    pname:pipeline must: not have been created with
    ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR set
endif::VK_KHR_pipeline_library[]
ifdef::VK_NV_inherited_viewport_scissor[]
  * [[VUID-vkCmdBindPipeline-commandBuffer-04808]]
    If pname:commandBuffer is a secondary command buffer with
    slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D
    enabled and pname:pipelineBindPoint is
    ename:VK_PIPELINE_BIND_POINT_GRAPHICS, then the pname:pipeline must:
    have been created with ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT or
    ename:VK_DYNAMIC_STATE_VIEWPORT, and
    ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT or
    ename:VK_DYNAMIC_STATE_SCISSOR enabled.
endif::VK_NV_inherited_viewport_scissor[]
ifdef::VK_NV_inherited_viewport_scissor,VK_EXT_discard_rectangles[]
  * [[VUID-vkCmdBindPipeline-commandBuffer-04809]]
    If pname:commandBuffer is a secondary command buffer with
    slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D
    enabled and pname:pipelineBindPoint is
    ename:VK_PIPELINE_BIND_POINT_GRAPHICS and pname:pipeline was created
    with slink:VkPipelineDiscardRectangleStateCreateInfoEXT structure and
    its pname:discardRectangleCount member is not `0`, then the pipeline
    must: have been created with
    ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT enabled.
endif::VK_NV_inherited_viewport_scissor,VK_EXT_discard_rectangles[]
ifdef::VK_EXT_provoking_vertex[]
  * [[VUID-vkCmdBindPipeline-pipelineBindPoint-04881]]
    If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_GRAPHICS and
    the
    <<limits-provokingVertexModePerPipeline,provokingVertexModePerPipeline>>
    limit is ename:VK_FALSE, then pipeline's
    slink:VkPipelineRasterizationProvokingVertexStateCreateInfoEXT::pname:provokingVertexMode
    must: be the same as that of any other pipelines previously bound to
    this bind point within the current renderpass instance, including any
    pipeline already bound when beginning the renderpass instance
endif::VK_EXT_provoking_vertex[]
ifdef::VK_HUAWEI_subpass_shading[]
  * [[VUID-vkCmdBindPipeline-pipelineBindPoint-04949]]
    If pname:pipelineBindPoint is
    ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI, the
    sname:VkCommandPool that pname:commandBuffer was allocated from must:
    support compute operations
  * [[VUID-vkCmdBindPipeline-pipelineBindPoint-04950]]
    If pname:pipelineBindPoint is
    ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI, pname:pipeline
    must: be a subpass shading pipeline
endif::VK_HUAWEI_subpass_shading[]

****

include::{generated}/validity/protos/vkCmdBindPipeline.txt[]
--

[open,refpage='VkPipelineBindPoint',desc='Specify the bind point of a pipeline object to a command buffer',type='enums']
--
Possible values of flink:vkCmdBindPipeline::pname:pipelineBindPoint,
specifying the bind point of a pipeline object, are:

include::{generated}/api/enums/VkPipelineBindPoint.txt[]

  * ename:VK_PIPELINE_BIND_POINT_COMPUTE specifies binding as a compute
    pipeline.
  * ename:VK_PIPELINE_BIND_POINT_GRAPHICS specifies binding as a graphics
    pipeline.
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
  * ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR specifies binding as a ray
    tracing pipeline.
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
ifdef::VK_HUAWEI_subpass_shading[]
  * ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI specifies binding as
    a subpass shading pipeline.
endif::VK_HUAWEI_subpass_shading[]
--

ifdef::VK_NV_device_generated_commands[]
[open,refpage='vkCmdBindPipelineShaderGroupNV',desc='Bind a pipeline object's shader group to a command buffer',type='protos']
--
For pipelines that were created with the support of multiple shader groups
(see <<graphics-shadergroups,Graphics Pipeline Shader Groups>>), the regular
fname:vkCmdBindPipeline command will bind Shader Group `0`.
To explicitly bind a shader group use:

include::{generated}/api/protos/vkCmdBindPipelineShaderGroupNV.txt[]

  * pname:commandBuffer is the command buffer that the pipeline will be
    bound to.
  * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying
    the bind point to which the pipeline will be bound.
  * pname:pipeline is the pipeline to be bound.
  * pname:groupIndex is the shader group to be bound.


.Valid Usage
****
  * [[VUID-vkCmdBindPipelineShaderGroupNV-groupIndex-02893]]
    pname:groupIndex must: be `0` or less than the effective
    slink:VkGraphicsPipelineShaderGroupsCreateInfoNV::pname:groupCount
    including the referenced pipelines
  * [[VUID-vkCmdBindPipelineShaderGroupNV-pipelineBindPoint-02894]]
    The pname:pipelineBindPoint must: be
    ename:VK_PIPELINE_BIND_POINT_GRAPHICS
  * [[VUID-vkCmdBindPipelineShaderGroupNV-groupIndex-02895]]
    The same restrictions as flink:vkCmdBindPipeline apply as if the bound
    pipeline was created only with the Shader Group from the
    pname:groupIndex information
  * [[VUID-vkCmdBindPipelineShaderGroupNV-deviceGeneratedCommands-02896]]
    The <<features-deviceGeneratedCommands,
    sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>>
    feature must: be enabled
****

include::{generated}/validity/protos/vkCmdBindPipelineShaderGroupNV.txt[]
--
endif::VK_NV_device_generated_commands[]


[[pipelines-dynamic-state]]
== 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 another pipeline bind.

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 since the command buffer recording was begun, or the
    last bound pipeline object with that state specified as static,
    whichever was the latter

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

[NOTE]
.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.
====

ifdef::VK_AMD_shader_info,VK_KHR_pipeline_executable_properties[]
[[pipelines-shader-information]]
== Pipeline Shader Information
endif::VK_AMD_shader_info,VK_KHR_pipeline_executable_properties[]

ifdef::VK_KHR_pipeline_executable_properties[]
include::VK_KHR_pipeline_executable_properties/pipelines.txt[]
endif::VK_KHR_pipeline_executable_properties[]

ifdef::VK_AMD_shader_info[]
include::VK_AMD_shader_info.txt[]
endif::VK_AMD_shader_info[]

// These includes have their own section headers

ifdef::VK_AMD_pipeline_compiler_control[]
include::VK_AMD_pipeline_compiler_control.txt[]
endif::VK_AMD_pipeline_compiler_control[]

ifdef::VK_EXT_pipeline_creation_feedback[]
include::VK_EXT_pipeline_creation_feedback/pipelines.txt[]
endif::VK_EXT_pipeline_creation_feedback[]
