// Copyright 2015-2021 The Khronos Group, Inc. // // SPDX-License-Identifier: CC-BY-4.0 [[pipelines]] = Pipelines The following <> 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 <> (<>) assembles vertices to form geometric primitives such as points, lines, and triangles, based on a requested primitive topology. In the next stage (<>) vertices can: be transformed, computing positions and attributes for each vertex. If <> and/or <> 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 <> pipeline input primitives are not assembled implicitly, but explicitly through the (<>). The work on the mesh pipeline is initiated by the application <> a set of mesh tasks. If an optional (<>) 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 <> to a clip volume in preparation for the next stage, <>. 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 <> to determine whether generated values will be written to the framebuffer. <> 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 <>. The attachments can: be used as input attachments in the fragment shader in a later subpass of the same render pass. The <> 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 <>. [[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. <> 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 <> 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 <> 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 <> 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 <> 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 <>. .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 <> chapter * [[VUID-VkComputePipelineCreateInfo-layout-00703]] pname:layout must: be <> 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 <> 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 <>, or `NULL`. .Valid Usage **** * [[VUID-VkPipelineShaderStageCreateInfo-stage-00704]] If the <> feature is not enabled, pname:stage must: not be ename:VK_SHADER_STAGE_GEOMETRY_BIT * [[VUID-VkPipelineShaderStageCreateInfo-stage-00705]] If the <> 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 <> feature is not enabled, pname:stage must: not be ename:VK_SHADER_STAGE_MESH_BIT_NV * [[VUID-VkPipelineShaderStageCreateInfo-stage-02092]] If the <> 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 specifying 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 specifying 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 specifying 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 <>, 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 <>, 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 specifying 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 specifying 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 <> 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 <> 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 <> feature must: be enabled, and pname:stage must: be a valid bit specified in <> * [[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 <> * [[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 <> * [[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 <> 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 <> 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 <> 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 <> does not equal <> and no <> is specified, then the only way to guarantee that the 'X' dimension of the local workgroup size is a multiple of <> 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 specifying 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 <> * [[VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT-requiredSubgroupSize-02762]] pname:requiredSubgroupSize must: be less than or equal to <> **** 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 a render pass instance compatible with the one provided. See <> 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 ename: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 a render pass instance compatible with the one provided. See <> 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 <> 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 <> 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 <> 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 <>. 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 no depth/stencil attachment is used. * pname:pColorBlendState is a pointer to a slink:VkPipelineColorBlendStateCreateInfo structure, and is ignored if the pipeline has rasterization disabled or if no color attachments are used. * 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 a render pass instance compatible with the one provided. See <> 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 <>. 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 <>, <>, <>, and <>. [[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 <>, with other subsets included depending on that state. If the <> includes a vertex shader, then <> is included in a complete graphics pipeline. If the value of slink:VkPipelineRasterizationStateCreateInfo::pname:rasterizerDiscardEnable in the <> 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[] <> and <> 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 <> 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 <> 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 <> 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 <> 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 <> 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 <> 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 <> and pname:pStages includes tessellation shader stages, the shader code of at least one stage must: contain an code:OpExecutionMode instruction specifying the type of subdivision in the pipeline * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00733]] If the pipeline is being created with <> and pname:pStages includes tessellation shader stages, and the shader code of both stages contain an code:OpExecutionMode instruction specifying the type of subdivision in the pipeline, they must: both specify the same subdivision mode * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00734]] If the pipeline is being created with <> and pname:pStages includes tessellation shader stages, the shader code of at least one stage must: contain an code:OpExecutionMode instruction specifying the output patch size in the pipeline * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00735]] If the pipeline is being created with <> and pname:pStages includes tessellation shader stages, and the shader code of both contain an code:OpExecutionMode instruction specifying 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 <> 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 <> 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 <> 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 specifying an input primitive type that is <> with the primitive topology specified in pname:pInputAssembly * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00739]] If the pipeline is being created with <> and pname:pStages includes a geometry shader stage, and also includes tessellation shader stages, its shader code must: contain an code:OpExecutionMode instruction specifying an input primitive type that is <> with the primitive topology that is output by the tessellation stages * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00740]] If the pipeline is being created with <> and <>, 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 ifdef::VK_NV_mesh_shader[] * [[VUID-VkGraphicsPipelineCreateInfo-PrimitiveId-06264]] If the pipeline is being created with <>, it includes a mesh shader and the fragment shader code reads from an input variable that is decorated with code:PrimitiveId, then the mesh shader code must: write to a matching output variable, decorated with code:PrimitiveId, in all execution paths endif::VK_NV_mesh_shader[] * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06038]] If pname:renderPass is not dlink:VK_NULL_HANDLE and the pipeline is being created with <> 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 <> 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 <> chapter * [[VUID-VkGraphicsPipelineCreateInfo-None-04889]] If the pipeline is being created with <> and <>, the fragment shader and last <> and any relevant state must: adhere to the pipeline linking rules described in the <> chapter * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06039]] If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being created with <>, 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-renderPass-06040]] If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being created with <>, 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-renderPass-06041]] If pname:renderPass is not dlink:VK_NULL_HANDLE, and the pipeline is being created with <>, then for each color attachment in the subpass, if the <> 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-renderPass-06042]] If pname:renderPass is not dlink:VK_NULL_HANDLE, and the pipeline is being created with <>, 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 <>, 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 <>, 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 <>, 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 <>, 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 <>, 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 <>, 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 <>, 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 <>, pname:pMultisampleState must: be a valid pointer to a valid slink:VkPipelineMultisampleStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06043]] If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being created with <>, and pname:subpass uses a depth/stencil attachment, pname:pDepthStencilState must: be a valid pointer to a valid slink:VkPipelineDepthStencilStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06044]] If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being created with <>, and pname:subpass uses color attachments, pname:pColorBlendState must: be a valid pointer to a valid slink:VkPipelineColorBlendStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06045]] If pname:renderPass is not dlink:VK_NULL_HANDLE and the pipeline is being created with <>, 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 <>, 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 <>, 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 <>, and the `apiext: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 <>, 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 <>, 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 <>, 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 <>, 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 <> with all shaders specified in pname:pStages * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00757]] If the pipeline is being created with <>, and neither the `apiext:VK_AMD_mixed_attachment_samples` nor the `apiext: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 <>, and the `apiext: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 <>, and the `apiext: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 <>, and the `apiext: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 <>, and the `apiext: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 <> 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 <> * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06046]] If pname:renderPass is a valid renderPass, pname:subpass must: be a valid subpass within pname:renderPass ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06047]] If pname:renderPass is a valid renderPass, the pipeline is being created with <>, 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-06048]] If pname:renderPass is a valid renderPass, the pipeline is being created with <>, 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-06049]] If pname:renderPass is a valid renderPass, the pipeline is being created with <>, 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-06050]] If pname:renderPass is a valid renderPass and the pipeline is being created with <>, 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 <> 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 <>, 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 <>, 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 <>, 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 <>, 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 <>, 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 <>, 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 <>, 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 <>, 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 <>, and any shader stage in pname:pStages specifies code:Xfb execution mode it must: be the last <> * [[VUID-VkGraphicsPipelineCreateInfo-rasterizationStream-02319]] If the pipeline is being created with <>, 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 <>, 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 <>, and the last <> 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 <>, 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 <> and at least one of <> or <>, 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 <>, 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 <> 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 <>, 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 <>, 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 <>, 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 <>, 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 <> 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 <> 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 <> 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 <> feature must: be enabled ifdef::VK_EXT_transform_feedback[] * [[VUID-VkGraphicsPipelineCreateInfo-flags-02966]] If the pipeline is being created with <> 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 <> 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 <> or <> 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 <> or <> 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 <> or <> 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 <> or <> 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 <> or <> 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 <> or <> 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 <> or <> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pname:pDynamicState->pDynamicStates, and the <> 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 <> or <> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pname:pDynamicState->pDynamicStates, and the <> 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 <> or <> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pname:pDynamicState->pDynamicStates, and the <> 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 <> and the <> 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 <> and the <> 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 <> and the <> 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 <> or <>, the <> 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 <> or <>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pname:pDynamicState->pDynamicStates, and the <> 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 <> or <>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pname:pDynamicState->pDynamicStates, and the <> 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 <> or <>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pname:pDynamicState->pDynamicStates, and the <> 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 <> or <>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in pname:pDynamicState->pDynamicStates, and the <> 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 <> or <>, and the <> 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 <> or <>, and the <> 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 <> or <>, and the <> 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 <> and the <> 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 <> ifdef::VK_EXT_color_write_enable[] * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04800]] If the <> 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 apiext: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 apiext: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[] ifndef::VK_KHR_dynamic_rendering[] * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06051]] pname:renderPass must: not be dlink:VK_NULL_HANDLE endif::VK_KHR_dynamic_rendering[] ifdef::VK_KHR_dynamic_rendering[] * [[VUID-VkGraphicsPipelineCreateInfo-dynamicRendering-06052]] If the <> feature is not enabled, pname:renderPass must: not be dlink:VK_NULL_HANDLE * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06053]] If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being created with <>, and either of slink:VkPipelineRenderingCreateInfoKHR::depthAttachmentFormat or slink:VkPipelineRenderingCreateInfoKHR::stencilAttachmentFormat are not ename:VK_FORMAT_UNDEFINED, pname:pDepthStencilState must: be a valid pointer to a valid slink:VkPipelineDepthStencilStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06054]] If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being created with <>, and slink:VkPipelineRenderingCreateInfoKHR::colorAttachmentCount is not equal to `0`, pname:pColorBlendState must: be a valid pointer to a valid slink:VkPipelineColorBlendStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06055]] If pname:renderPass is dlink:VK_NULL_HANDLE and the pipeline is being created with <>, pname:pColorBlendState->attachmentCount must: be equal to slink:VkPipelineRenderingCreateInfoKHR::colorAttachmentCount * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06056]] If pname:renderPass is dlink:VK_NULL_HANDLE and the pipeline is being created with <> the fragment shader must: not read from any input attachment ifdef::VK_KHR_multiview,VK_VERSION_1_1[] * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06057]] If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being created with <>, the pname:viewMask member of a slink:VkPipelineRenderingCreateInfoKHR structure included in the pname:pNext chain is not `0`, and the <> feature is not enabled, then pname:pStages must: not include tessellation shaders * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06058]] If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being created with <>, the pname:viewMask member of a slink:VkPipelineRenderingCreateInfoKHR structure included in the pname:pNext chain is not `0`, and the <> feature is not enabled, then pname:pStages must: not include a geometry shader * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06059]] If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being created with <>, and the pname:viewMask member of a slink:VkPipelineRenderingCreateInfoKHR structure included in the pname:pNext chain is not `0`, shaders in pname:pStages must: not include variables decorated with the code:Layer built-in decoration in their interfaces * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06060]] If the pipeline is being created with <> and pname:renderPass is dlink:VK_NULL_HANDLE, pname:pColorBlendState->attachmentCount must: be equal to the pname:colorAttachmentCount member of the slink:VkPipelineRenderingCreateInfoKHR structure included in the pname:pNext chain * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06061]] If the pipeline is being created with <> and pname:renderPass is dlink:VK_NULL_HANDLE, fragment shaders in pname:pStages must: not include the code:InputAttachment capability * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06062]] If the pipeline is being created with <> and pname:renderPass is dlink:VK_NULL_HANDLE, for each color attachment format defined by the pname:pColorAttachmentFormats member of slink:VkPipelineRenderingCreateInfoKHR, if its <> 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 endif::VK_KHR_multiview,VK_VERSION_1_1[] ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06063]] If the pipeline is being created with <> and pname:renderPass is dlink:VK_NULL_HANDLE, if the pname:pNext chain includes slink:VkAttachmentSampleCountInfoAMD or sname:VkAttachmentSampleCountInfoNV, the pname:colorAttachmentCount member of that structure must: be equal to the value of slink:VkPipelineRenderingCreateInfoKHR::pname:colorAttachmentCount endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] endif::VK_KHR_dynamic_rendering[] ifdef::VK_ARM_rasterization_order_attachment_access[] * [[VUID-VkGraphicsPipelineCreateInfo-pStages-06466]] If pname:pStages includes a fragment shader stage, and the fragment shader code enables <>, the pname:flags member of slink:VkPipelineDepthStencilStateCreateInfo must: not include ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM or ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM * [[VUID-VkGraphicsPipelineCreateInfo-flags-06467]] If the pname:flags member of slink:VkPipelineColorBlendStateCreateInfo includes ename:VK_PIPELINE_COLOR_BLEND_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_ACCESS_BIT_ARM pname:subpass must: have been created with ename:VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_COLOR_ACCESS_BIT_ARM * [[VUID-VkGraphicsPipelineCreateInfo-flags-06468]] If the pname:flags member of slink:VkPipelineDepthStencilStateCreateInfo includes ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM, pname:subpass must: have been created with ename:VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_ARM * [[VUID-VkGraphicsPipelineCreateInfo-flags-06469]] If the pname:flags member of slink:VkPipelineDepthStencilStateCreateInfo includes ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM, pname:subpass must: have been created with ename:VK_SUBPASS_DESCRIPTION_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_ARM endif::VK_ARM_rasterization_order_attachment_access[] **** include::{generated}/validity/structs/VkGraphicsPipelineCreateInfo.txt[] -- ifdef::VK_KHR_dynamic_rendering[] [open,refpage='VkPipelineRenderingCreateInfoKHR',desc='Structure specifying attachment formats',type='structs'] -- The sname:VkPipelineRenderingCreateInfoKHR structure is defined as: include::{generated}/api/structs/VkPipelineRenderingCreateInfoKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:viewMask is the viewMask used for rendering. * pname:colorAttachmentCount is the number of entries in pname:pColorAttachmentFormats * pname:pColorAttachmentFormats is a pointer to an array of elink:VkFormat values defining the format of color attachments used in this pipeline. * pname:depthAttachmentFormat is a elink:VkFormat value defining the format of the depth attachment used in this pipeline. * pname:stencilAttachmentFormat is a elink:VkFormat value defining the format of the stencil attachment used in this pipeline. When a pipeline is created without a slink:VkRenderPass, if this structure is present in the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo, it specifies the view mask and format of attachments used for rendering. If this structure is not specified, and the pipeline does not include a slink:VkRenderPass, pname:viewMask and pname:colorAttachmentCount are `0`, and pname:depthAttachmentFormat and pname:stencilAttachmentFormat are ename:VK_FORMAT_UNDEFINED. If a graphics pipeline is created with a valid slink:VkRenderPass, parameters of this structure are ignored. If pname:depthAttachmentFormat, pname:stencilAttachmentFormat, or any element of pname:pColorAttachmentFormats is ename:VK_FORMAT_UNDEFINED, it indicates that the corresponding attachment is unused within the render pass. Valid formats indicate that an attachment can: be used - but it is still valid to set the attachment to `NULL` when beginning rendering. .Valid Usage **** * [[VUID-VkPipelineRenderingCreateInfoKHR-pColorAttachmentFormats-06064]] If any element of pname:pColorAttachmentFormats is not ename:VK_FORMAT_UNDEFINED, it must: be a format with <> that include ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT * [[VUID-VkPipelineRenderingCreateInfoKHR-depthAttachmentFormat-06065]] If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it must: be a format with <> that include ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT * [[VUID-VkPipelineRenderingCreateInfoKHR-stencilAttachmentFormat-06164]] If pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it must: be a format with <> that include ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT * [[VUID-VkPipelineRenderingCreateInfoKHR-depthAttachmentFormat-06165]] If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED and pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, pname:depthAttachmentFormat must: equal pname:stencilAttachmentFormat * [[VUID-VkPipelineRenderingCreateInfoKHR-multiview-06066]] If the <> feature is not enabled, pname:viewMask must: be `0` ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-VkPipelineRenderingCreateInfoKHR-viewMask-06067]] The index of the most significant bit in pname:viewMask must: be less than <> endif::VK_VERSION_1_1,VK_KHR_multiview[] **** include::{generated}/validity/structs/VkPipelineRenderingCreateInfoKHR.txt[] -- endif::VK_KHR_dynamic_rendering[] [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 <>. 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[] ifdef::VK_KHR_dynamic_rendering[] ifdef::VK_KHR_fragment_shading_rate[] * ename:VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies that the pipeline will be used with a fragment shading rate attachment. endif::VK_KHR_fragment_shading_rate[] ifdef::VK_EXT_fragment_density_map[] * ename:VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT specifies that the pipeline will be used with a fragment density map attachment. endif::VK_EXT_fragment_density_map[] endif::VK_KHR_dynamic_rendering[] 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 <> 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 <>, 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 <>. [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 <> 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 <> 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 <> 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 <> object for this command. * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that pipeline caching is disabled, or the handle of a valid <> 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 <> 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 <> 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 <> 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 <>. .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 <> 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 <>. 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 <>. .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 `apiext: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 <> 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 <> 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, <> 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 `NULL` or a 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 <> 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 stack size dynamically for a ray tracing pipeline',type='protos'] -- :refpage: vkCmdSetRayTracingPipelineStackSizeKHR To <> the 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. This command sets the stack size for subsequent ray tracing commands when the ray tracing pipeline is created with ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, the stack size is computed as described in <>. .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 <> 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 <> 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 <>. 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 <> 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 <>. 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 <> 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 <> 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 <>. * The pipeline bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS controls the behavior of all <>. 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 <> feature is not supported, pname:pipeline is a graphics pipeline, the current subpass <>, 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 <> 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 render pass instance, including any pipeline already bound when beginning the render pass 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[] ifdef::VK_KHR_dynamic_rendering[] * [[VUID-vkCmdBindPipeline-pipeline-06195]] If pname:pipeline is a graphics pipeline, this command has been called inside a render pass instance started with flink:vkCmdBeginRenderingKHR, and commands using the previously bound graphics pipeline have been recorded within the render pass instance, then the value of slink:VkPipelineRenderingCreateInfoKHR::pname:colorAttachmentCount specified by this pipeline must: match that set in the previous pipeline * [[VUID-vkCmdBindPipeline-pipeline-06196]] If pname:pipeline is a graphics pipeline, this command has been called inside a render pass instance started with flink:vkCmdBeginRenderingKHR, and commands using the previously bound graphics pipeline have been recorded within the render pass instance, then the elements of slink:VkPipelineRenderingCreateInfoKHR::pname:pColorAttachmentFormats specified by this pipeline must: match that set in the previous pipeline * [[VUID-vkCmdBindPipeline-pipeline-06197]] If pname:pipeline is a graphics pipeline, this command has been called inside a render pass instance started with flink:vkCmdBeginRenderingKHR, and commands using the previously bound graphics pipeline have been recorded within the render pass instance, then the value of slink:VkPipelineRenderingCreateInfoKHR::pname:depthAttachmentFormat specified by this pipeline must: match that set in the previous pipeline * [[VUID-vkCmdBindPipeline-pipeline-06194]] If pname:pipeline is a graphics pipeline, this command has been called inside a render pass instance started with flink:vkCmdBeginRenderingKHR, and commands using the previously bound graphics pipeline have been recorded within the render pass instance, then the value of slink:VkPipelineRenderingCreateInfoKHR::pname:stencilAttachmentFormat specified by this pipeline must: match that set in the previous pipeline endif::VK_KHR_dynamic_rendering[] **** 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 <>), 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 <> 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::{chapters}/VK_KHR_pipeline_executable_properties/pipelines.txt[] endif::VK_KHR_pipeline_executable_properties[] ifdef::VK_AMD_shader_info[] include::{chapters}/VK_AMD_shader_info.txt[] endif::VK_AMD_shader_info[] // These includes have their own section headers ifdef::VK_AMD_pipeline_compiler_control[] include::{chapters}/VK_AMD_pipeline_compiler_control.txt[] endif::VK_AMD_pipeline_compiler_control[] ifdef::VK_EXT_pipeline_creation_feedback[] include::{chapters}/VK_EXT_pipeline_creation_feedback/pipelines.txt[] endif::VK_EXT_pipeline_creation_feedback[]