1// Copyright 2015-2021 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[pipelines]] 6= Pipelines 7 8The following <<pipelines-block-diagram,figure>> shows a block diagram of 9the Vulkan pipelines. 10Some Vulkan commands specify geometric objects to be drawn or computational 11work to be performed, while others specify state controlling how objects are 12handled by the various pipeline stages, or control data transfer between 13memory organized as images and buffers. 14Commands are effectively sent through a processing pipeline, either a 15_graphics pipeline_, 16ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 17a _ray tracing pipeline_, 18endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 19or a _compute pipeline_. 20 21ifdef::VK_NV_mesh_shader[] 22The graphics pipeline can be operated in two modes, as either _primitive 23shading_ or _mesh shading_ pipeline. 24 25*Primitive Shading* 26 27endif::VK_NV_mesh_shader[] 28 29The first stage of the <<pipelines-graphics,graphics pipeline>> 30(<<drawing,Input Assembler>>) assembles vertices to form geometric 31primitives such as points, lines, and triangles, based on a requested 32primitive topology. 33In the next stage (<<shaders-vertex,Vertex Shader>>) vertices can: be 34transformed, computing positions and attributes for each vertex. 35If <<tessellation,tessellation>> and/or <<geometry,geometry>> shaders are 36supported, they can: then generate multiple primitives from a single input 37primitive, possibly changing the primitive topology or generating additional 38attribute data in the process. 39 40ifdef::VK_NV_mesh_shader[] 41*Mesh Shading* 42 43When using the <<mesh,_mesh shading_>> pipeline input primitives are not 44assembled implicitly, but explicitly through the (<<shaders-mesh,Mesh 45Shader>>). 46The work on the mesh pipeline is initiated by the application 47<<drawing-mesh-shading,drawing>> a set of mesh tasks. 48 49If an optional (<<shaders-task,Task Shader>>) is active, each task triggers 50the execution of a task shader workgroup that will generate a new set of 51tasks upon completion. 52Each of these spawned tasks, or each of the original dispatched tasks if no 53task shader is present, triggers the execution of a mesh shader workgroup 54that produces an output mesh with a variable-sized number of primitives 55assembled from vertices stored in the output mesh. 56 57*Common* 58endif::VK_NV_mesh_shader[] 59 60The final resulting primitives are <<vertexpostproc-clipping,clipped>> to a 61clip volume in preparation for the next stage, <<primsrast,Rasterization>>. 62The rasterizer produces a series of _fragments_ associated with a region of 63the framebuffer, from a two-dimensional description of a point, line 64segment, or triangle. 65These fragments are processed by <<fragops,fragment operations>> to 66determine whether generated values will be written to the framebuffer. 67<<fragops-shader, Fragment shading>> determines the values to be written to 68the framebuffer attachments. 69Framebuffer operations then read and write the color and depth/stencil 70attachments of the framebuffer for a given subpass of a <<renderpass,render 71pass instance>>. 72The attachments can: be used as input attachments in the fragment shader in 73a later subpass of the same render pass. 74 75The <<pipelines-compute,compute pipeline>> is a separate pipeline from the 76graphics pipeline, which operates on one-, two-, or three-dimensional 77workgroups which can: read from and write to buffer and image memory. 78 79This ordering is meant only as a tool for describing Vulkan, not as a strict 80rule of how Vulkan is implemented, and we present it only as a means to 81organize the various operations of the pipelines. 82Actual ordering guarantees between pipeline stages are explained in detail 83in the <<synchronization-pipeline-stages-order, synchronization chapter>>. 84 85[[pipelines-block-diagram]] 86ifndef::VK_NV_mesh_shader[] 87image::{images}/pipeline.svg[title="Block diagram of the Vulkan pipeline",align="center",opts="{imageopts}"] 88endif::VK_NV_mesh_shader[] 89ifdef::VK_NV_mesh_shader[] 90image::{images}/pipelinemesh.svg[title="Block diagram of the Vulkan pipeline",align="center",opts="{imageopts}"] 91endif::VK_NV_mesh_shader[] 92 93Each pipeline is controlled by a monolithic object created from a 94description of all of the shader stages and any relevant fixed-function 95stages. 96<<interfaces,Linking>> the whole pipeline together allows the optimization 97of shaders based on their input/outputs and eliminates expensive draw time 98state validation. 99 100A pipeline object is bound to the current state using 101flink:vkCmdBindPipeline. 102Any pipeline object state that is specified as <<pipelines-dynamic-state, 103dynamic>> is not applied to the current state when the pipeline object is 104bound, but is instead set by dynamic state setting commands. 105 106No state, including dynamic state, is inherited from one command buffer to 107another. 108 109 110[open,refpage='VkPipeline',desc='Opaque handle to a pipeline object',type='handles'] 111-- 112Compute, 113ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 114ray tracing, 115endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 116and graphics pipelines are each represented by sname:VkPipeline handles: 117 118include::{generated}/api/handles/VkPipeline.txt[] 119-- 120 121 122[[pipelines-compute]] 123== Compute Pipelines 124 125Compute pipelines consist of a single static compute shader stage and the 126pipeline layout. 127 128The compute pipeline represents a compute shader and is created by calling 129fname:vkCreateComputePipelines with pname:module and pname:pName selecting 130an entry point from a shader module, where that entry point defines a valid 131compute shader, in the slink:VkPipelineShaderStageCreateInfo structure 132contained within the slink:VkComputePipelineCreateInfo structure. 133 134[open,refpage='vkCreateComputePipelines',desc='Creates a new compute pipeline object',type='protos'] 135-- 136To create compute pipelines, call: 137 138include::{generated}/api/protos/vkCreateComputePipelines.txt[] 139 140 * pname:device is the logical device that creates the compute pipelines. 141 * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that 142 pipeline caching is disabled; or the handle of a valid 143 <<pipelines-cache,pipeline cache>> object, in which case use of that 144 cache is enabled for the duration of the command. 145 * pname:createInfoCount is the length of the pname:pCreateInfos and 146 pname:pPipelines arrays. 147 * pname:pCreateInfos is a pointer to an array of 148 slink:VkComputePipelineCreateInfo structures. 149 * pname:pAllocator controls host memory allocation as described in the 150 <<memory-allocation, Memory Allocation>> chapter. 151 * pname:pPipelines is a pointer to an array of slink:VkPipeline handles in 152 which the resulting compute pipeline objects are returned. 153ifdef::editing-notes[] 154+ 155[NOTE] 156.editing-note 157==== 158TODO (Jon) - Should we say something like "`the i'th element of the 159pname:pPipelines array is created based on the corresponding element of the 160pname:pCreateInfos array`"? Also for flink:vkCreateGraphicsPipelines below. 161==== 162endif::editing-notes[] 163 164.Valid Usage 165**** 166 * [[VUID-vkCreateComputePipelines-flags-00695]] 167 If the pname:flags member of any element of pname:pCreateInfos contains 168 the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the 169 pname:basePipelineIndex member of that same element is not `-1`, 170 pname:basePipelineIndex must: be less than the index into 171 pname:pCreateInfos that corresponds to that element 172 * [[VUID-vkCreateComputePipelines-flags-00696]] 173 If the pname:flags member of any element of pname:pCreateInfos contains 174 the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline 175 must: have been created with the 176 ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set 177ifdef::VK_EXT_pipeline_creation_cache_control[] 178 * [[VUID-vkCreateComputePipelines-pipelineCache-02873]] 179 If pname:pipelineCache was created with 180 ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT, host 181 access to pname:pipelineCache must: be 182 <<fundamentals-threadingbehavior,externally synchronized>> 183endif::VK_EXT_pipeline_creation_cache_control[] 184**** 185 186include::{generated}/validity/protos/vkCreateComputePipelines.txt[] 187-- 188 189[open,refpage='VkComputePipelineCreateInfo',desc='Structure specifying parameters of a newly created compute pipeline',type='structs'] 190-- 191The sname:VkComputePipelineCreateInfo structure is defined as: 192 193include::{generated}/api/structs/VkComputePipelineCreateInfo.txt[] 194 195 * pname:sType is the type of this structure. 196 * pname:pNext is `NULL` or a pointer to a structure extending this 197 structure. 198 * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying 199 how the pipeline will be generated. 200 * pname:stage is a slink:VkPipelineShaderStageCreateInfo structure 201 describing the compute shader. 202 * pname:layout is the description of binding locations used by both the 203 pipeline and descriptor sets used with the pipeline. 204 * pname:basePipelineHandle is a pipeline to derive from 205 * pname:basePipelineIndex is an index into the pname:pCreateInfos 206 parameter to use as a pipeline to derive from 207 208The parameters pname:basePipelineHandle and pname:basePipelineIndex are 209described in more detail in <<pipelines-pipeline-derivatives,Pipeline 210Derivatives>>. 211 212.Valid Usage 213**** 214 * [[VUID-VkComputePipelineCreateInfo-flags-00697]] 215 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 216 flag, and pname:basePipelineIndex is -1, pname:basePipelineHandle must: 217 be a valid handle to a compute sname:VkPipeline 218 * [[VUID-VkComputePipelineCreateInfo-flags-00698]] 219 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 220 flag, and pname:basePipelineHandle is dlink:VK_NULL_HANDLE, 221 pname:basePipelineIndex must: be a valid index into the calling 222 command's pname:pCreateInfos parameter 223 * [[VUID-VkComputePipelineCreateInfo-flags-00699]] 224 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 225 flag, and pname:basePipelineIndex is not -1, pname:basePipelineHandle 226 must: be dlink:VK_NULL_HANDLE 227 * [[VUID-VkComputePipelineCreateInfo-flags-00700]] 228 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 229 flag, and pname:basePipelineHandle is not dlink:VK_NULL_HANDLE, 230 pname:basePipelineIndex must: be -1 231 * [[VUID-VkComputePipelineCreateInfo-stage-00701]] 232 The pname:stage member of pname:stage must: be 233 ename:VK_SHADER_STAGE_COMPUTE_BIT 234 * [[VUID-VkComputePipelineCreateInfo-stage-00702]] 235 The shader code for the entry point identified by pname:stage and the 236 rest of the state identified by this structure must: adhere to the 237 pipeline linking rules described in the <<interfaces,Shader Interfaces>> 238 chapter 239 * [[VUID-VkComputePipelineCreateInfo-layout-00703]] 240 pname:layout must: be 241 <<descriptorsets-pipelinelayout-consistency,consistent>> with the layout 242 of the compute shader specified in pname:stage 243 * [[VUID-VkComputePipelineCreateInfo-layout-01687]] 244 The number of resources in pname:layout accessible to the compute shader 245 stage must: be less than or equal to 246 sname:VkPhysicalDeviceLimits::pname:maxPerStageResources 247ifdef::VK_KHR_pipeline_library[] 248 * [[VUID-VkComputePipelineCreateInfo-flags-03364]] 249 pname:flags must: not include ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR 250endif::VK_KHR_pipeline_library[] 251ifdef::VK_KHR_ray_tracing_pipeline[] 252 * [[VUID-VkComputePipelineCreateInfo-flags-03365]] 253 pname:flags must: not include 254 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR 255 * [[VUID-VkComputePipelineCreateInfo-flags-03366]] 256 pname:flags must: not include 257 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR 258 * [[VUID-VkComputePipelineCreateInfo-flags-03367]] 259 pname:flags must: not include 260 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR 261 * [[VUID-VkComputePipelineCreateInfo-flags-03368]] 262 pname:flags must: not include 263 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR 264 * [[VUID-VkComputePipelineCreateInfo-flags-03369]] 265 pname:flags must: not include 266 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR 267 * [[VUID-VkComputePipelineCreateInfo-flags-03370]] 268 pname:flags must: not include 269 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR 270 * [[VUID-VkComputePipelineCreateInfo-flags-03576]] 271 pname:flags must: not include 272 ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR 273endif::VK_KHR_ray_tracing_pipeline[] 274ifdef::VK_NV_ray_tracing_motion_blur[] 275 * [[VUID-VkComputePipelineCreateInfo-flags-04945]] 276 pname:flags must: not include 277 ename:VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV 278endif::VK_NV_ray_tracing_motion_blur[] 279ifdef::VK_NV_device_generated_commands[] 280 * [[VUID-VkComputePipelineCreateInfo-flags-02874]] 281 pname:flags must: not include 282 ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV 283endif::VK_NV_device_generated_commands[] 284ifdef::VK_EXT_pipeline_creation_cache_control[] 285 * [[VUID-VkComputePipelineCreateInfo-pipelineCreationCacheControl-02875]] 286 If the <<features-pipelineCreationCacheControl, 287 pname:pipelineCreationCacheControl>> feature is not enabled, pname:flags 288 must: not include 289 ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT or 290 ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT 291endif::VK_EXT_pipeline_creation_cache_control[] 292**** 293 294include::{generated}/validity/structs/VkComputePipelineCreateInfo.txt[] 295-- 296 297[open,refpage='VkPipelineShaderStageCreateInfo',desc='Structure specifying parameters of a newly created pipeline shader stage',type='structs'] 298-- 299The sname:VkPipelineShaderStageCreateInfo structure is defined as: 300 301include::{generated}/api/structs/VkPipelineShaderStageCreateInfo.txt[] 302 303 * pname:sType is the type of this structure. 304 * pname:pNext is `NULL` or a pointer to a structure extending this 305 structure. 306 * pname:flags is a bitmask of elink:VkPipelineShaderStageCreateFlagBits 307 specifying how the pipeline shader stage will be generated. 308 * pname:stage is a elink:VkShaderStageFlagBits value specifying a single 309 pipeline stage. 310 * pname:module is a slink:VkShaderModule object containing the shader for 311 this stage. 312 * pname:pName is a pointer to a null-terminated UTF-8 string specifying 313 the entry point name of the shader for this stage. 314 * pname:pSpecializationInfo is a pointer to a slink:VkSpecializationInfo 315 structure, as described in 316 <<pipelines-specialization-constants,Specialization Constants>>, or 317 `NULL`. 318 319.Valid Usage 320**** 321 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00704]] 322 If the <<features-geometryShader,geometry shaders>> feature is not 323 enabled, pname:stage must: not be ename:VK_SHADER_STAGE_GEOMETRY_BIT 324 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00705]] 325 If the <<features-tessellationShader,tessellation shaders>> feature is 326 not enabled, pname:stage must: not be 327 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or 328 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT 329ifdef::VK_NV_mesh_shader[] 330 * [[VUID-VkPipelineShaderStageCreateInfo-stage-02091]] 331 If the <<features-meshShader,mesh shader>> feature is not enabled, 332 pname:stage must: not be ename:VK_SHADER_STAGE_MESH_BIT_NV 333 * [[VUID-VkPipelineShaderStageCreateInfo-stage-02092]] 334 If the <<features-taskShader,task shader>> feature is not enabled, 335 pname:stage must: not be ename:VK_SHADER_STAGE_TASK_BIT_NV 336endif::VK_NV_mesh_shader[] 337 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00706]] 338 pname:stage must: not be ename:VK_SHADER_STAGE_ALL_GRAPHICS, or 339 ename:VK_SHADER_STAGE_ALL 340 * [[VUID-VkPipelineShaderStageCreateInfo-pName-00707]] 341 pname:pName must: be the name of an code:OpEntryPoint in pname:module 342 with an execution model that matches pname:stage 343 * [[VUID-VkPipelineShaderStageCreateInfo-maxClipDistances-00708]] 344 If the identified entry point includes any variable in its interface 345 that is declared with the code:ClipDistance code:BuiltIn decoration, 346 that variable must: not have an array size greater than 347 sname:VkPhysicalDeviceLimits::pname:maxClipDistances 348 * [[VUID-VkPipelineShaderStageCreateInfo-maxCullDistances-00709]] 349 If the identified entry point includes any variable in its interface 350 that is declared with the code:CullDistance code:BuiltIn decoration, 351 that variable must: not have an array size greater than 352 sname:VkPhysicalDeviceLimits::pname:maxCullDistances 353 * [[VUID-VkPipelineShaderStageCreateInfo-maxCombinedClipAndCullDistances-00710]] 354 If the identified entry point includes any variables in its interface 355 that are declared with the code:ClipDistance or code:CullDistance 356 code:BuiltIn decoration, those variables must: not have array sizes 357 which sum to more than 358 sname:VkPhysicalDeviceLimits::pname:maxCombinedClipAndCullDistances 359 * [[VUID-VkPipelineShaderStageCreateInfo-maxSampleMaskWords-00711]] 360 If the identified entry point includes any variable in its interface 361 that is declared with the code:SampleMask code:BuiltIn decoration, that 362 variable must: not have an array size greater than 363 sname:VkPhysicalDeviceLimits::pname:maxSampleMaskWords 364 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00712]] 365 If pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT, the identified entry 366 point must: not include any input variable in its interface that is 367 decorated with code:CullDistance 368 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00713]] 369 If pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or 370 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and the identified 371 entry point has an code:OpExecutionMode instruction that specifies a 372 patch size with code:OutputVertices, the patch size must: be greater 373 than `0` and less than or equal to 374 sname:VkPhysicalDeviceLimits::pname:maxTessellationPatchSize 375 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00714]] 376 If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, the identified 377 entry point must: have an code:OpExecutionMode instruction that 378 specifies a maximum output vertex count that is greater than `0` and 379 less than or equal to 380 sname:VkPhysicalDeviceLimits::pname:maxGeometryOutputVertices 381 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00715]] 382 If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, the identified 383 entry point must: have an code:OpExecutionMode instruction that 384 specifies an invocation count that is greater than `0` and less than or 385 equal to 386 sname:VkPhysicalDeviceLimits::pname:maxGeometryShaderInvocations 387 * [[VUID-VkPipelineShaderStageCreateInfo-stage-02596]] 388 If pname:stage is a 389 <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 390 stage>>, and the identified entry point writes to code:Layer for any 391 primitive, it must: write the same value to code:Layer for all vertices 392 of a given primitive 393 * [[VUID-VkPipelineShaderStageCreateInfo-stage-02597]] 394 If pname:stage is a 395 <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 396 stage>>, and the identified entry point writes to code:ViewportIndex for 397 any primitive, it must: write the same value to code:ViewportIndex for 398 all vertices of a given primitive 399 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00718]] 400 If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, the identified 401 entry point must: not include any output variables in its interface 402 decorated with code:CullDistance 403 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00719]] 404 If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, and the identified 405 entry point writes to code:FragDepth in any execution path, it must: 406 write to code:FragDepth in all execution paths 407ifdef::VK_EXT_shader_stencil_export[] 408 * [[VUID-VkPipelineShaderStageCreateInfo-stage-01511]] 409 If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, and the identified 410 entry point writes to code:FragStencilRefEXT in any execution path, it 411 must: write to code:FragStencilRefEXT in all execution paths 412endif::VK_EXT_shader_stencil_export[] 413ifdef::VK_NV_mesh_shader[] 414 * [[VUID-VkPipelineShaderStageCreateInfo-stage-02093]] 415 If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_NV, the identified 416 entry point must: have an code:OpExecutionMode instruction that 417 specifies a maximum output vertex count, code:OutputVertices, that is 418 greater than `0` and less than or equal to 419 sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputVertices 420 * [[VUID-VkPipelineShaderStageCreateInfo-stage-02094]] 421 If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_NV, the identified 422 entry point must: have an code:OpExecutionMode instruction that 423 specifies a maximum output primitive count, code:OutputPrimitivesNV, 424 that is greater than `0` and less than or equal to 425 sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputPrimitives 426endif::VK_NV_mesh_shader[] 427ifdef::VK_EXT_subgroup_size_control[] 428 * [[VUID-VkPipelineShaderStageCreateInfo-flags-02784]] 429 If pname:flags has the 430 ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT 431 flag set, the <<features-subgroupSizeControl, 432 pname:subgroupSizeControl>> feature must: be enabled 433 * [[VUID-VkPipelineShaderStageCreateInfo-flags-02785]] 434 If pname:flags has the 435 ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT 436 flag set, the <<features-computeFullSubgroups, 437 pname:computeFullSubgroups>> feature must: be enabled 438 * [[VUID-VkPipelineShaderStageCreateInfo-pNext-02754]] 439 If a slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT 440 structure is included in the pname:pNext chain, pname:flags must: not 441 have the 442 ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT 443 flag set 444 * [[VUID-VkPipelineShaderStageCreateInfo-pNext-02755]] 445 If a slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT 446 structure is included in the pname:pNext chain, the 447 <<features-subgroupSizeControl, pname:subgroupSizeControl>> feature 448 must: be enabled, and pname:stage must: be a valid bit specified in 449 <<limits-required-subgroup-size-stages, 450 pname:requiredSubgroupSizeStages>> 451 * [[VUID-VkPipelineShaderStageCreateInfo-pNext-02756]] 452 If a slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT 453 structure is included in the pname:pNext chain and pname:stage is 454 ename:VK_SHADER_STAGE_COMPUTE_BIT, the local workgroup size of the 455 shader must: be less than or equal to the product of 456 slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT::pname:requiredSubgroupSize 457 and 458 <<limits-max-subgroups-per-workgroup,pname:maxComputeWorkgroupSubgroups>> 459 * [[VUID-VkPipelineShaderStageCreateInfo-pNext-02757]] 460 If a slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT 461 structure is included in the pname:pNext chain, and pname:flags has the 462 ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT 463 flag set, the local workgroup size in the X dimension of the pipeline 464 must: be a multiple of 465 slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT::pname:requiredSubgroupSize 466 * [[VUID-VkPipelineShaderStageCreateInfo-flags-02758]] 467 If pname:flags has both the 468 ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT and 469 ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT 470 flags set, the local workgroup size in the X dimension of the pipeline 471 must: be a multiple of 472 <<limits-max-subgroup-size,pname:maxSubgroupSize>> 473 * [[VUID-VkPipelineShaderStageCreateInfo-flags-02759]] 474 If pname:flags has the 475 ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT 476 flag set and pname:flags does not have the 477 ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT 478 flag set and no 479 slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure 480 is included in the pname:pNext chain, the local workgroup size in the X 481 dimension of the pipeline must: be a multiple of 482 <<limits-subgroup-size,pname:subgroupSize>> 483endif::VK_EXT_subgroup_size_control[] 484 * [[VUID-VkPipelineShaderStageCreateInfo-module-04145]] 485 The SPIR-V code that was used to create pname:module must: be valid as 486 described by the <<spirv-spec,Khronos SPIR-V Specification>> after 487 applying the specializations provided in pname:pSpecializationInfo, if 488 any, and then converting all specialization constants into fixed 489 constants 490**** 491 492include::{generated}/validity/structs/VkPipelineShaderStageCreateInfo.txt[] 493-- 494 495[open,refpage='VkPipelineShaderStageCreateFlags',desc='Bitmask of VkPipelineShaderStageCreateFlagBits',type='flags'] 496-- 497include::{generated}/api/flags/VkPipelineShaderStageCreateFlags.txt[] 498 499tname:VkPipelineShaderStageCreateFlags is a bitmask type for setting a mask 500of zero or more elink:VkPipelineShaderStageCreateFlagBits. 501-- 502 503[open,refpage='VkPipelineShaderStageCreateFlagBits',desc='Bitmask controlling how a pipeline shader stage is created',type='enums'] 504-- 505Possible values of the pname:flags member of 506slink:VkPipelineShaderStageCreateInfo specifying how a pipeline shader stage 507is created, are: 508 509include::{generated}/api/enums/VkPipelineShaderStageCreateFlagBits.txt[] 510 511ifdef::VK_EXT_subgroup_size_control[] 512 * ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT 513 specifies that the 514 <<interfaces-builtin-variables-sgs,code:SubgroupSize>> may: vary in the 515 shader stage. 516 * ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT 517 specifies that the subgroup sizes must: be launched with all invocations 518 active in the compute stage. 519 520[NOTE] 521.Note 522==== 523If ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT 524and ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT are 525specified and <<limits-max-subgroup-size,pname:minSubgroupSize>> does not 526equal <<limits-max-subgroup-size,pname:maxSubgroupSize>> and no 527<<pipelines-required-subgroup-size, required subgroup size>> is specified, 528then the only way to guarantee that the 'X' dimension of the local workgroup 529size is a multiple of <<interfaces-builtin-variables-sgs,code:SubgroupSize>> 530is to make it a multiple of pname:maxSubgroupSize. 531Under these conditions, you are guaranteed full subgroups but not any 532particular subgroup size. 533==== 534 535endif::VK_EXT_subgroup_size_control[] 536-- 537 538[open,refpage='VkShaderStageFlagBits',desc='Bitmask specifying a pipeline stage',type='enums'] 539-- 540Commands and structures which need to specify one or more shader stages do 541so using a bitmask whose bits correspond to stages. 542Bits which can: be set to specify shader stages are: 543 544include::{generated}/api/enums/VkShaderStageFlagBits.txt[] 545 546 * ename:VK_SHADER_STAGE_VERTEX_BIT specifies the vertex stage. 547 * ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT specifies the 548 tessellation control stage. 549 * ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT specifies the 550 tessellation evaluation stage. 551 * ename:VK_SHADER_STAGE_GEOMETRY_BIT specifies the geometry stage. 552 * ename:VK_SHADER_STAGE_FRAGMENT_BIT specifies the fragment stage. 553 * ename:VK_SHADER_STAGE_COMPUTE_BIT specifies the compute stage. 554 * ename:VK_SHADER_STAGE_ALL_GRAPHICS is a combination of bits used as 555 shorthand to specify all graphics stages defined above (excluding the 556 compute stage). 557 * ename:VK_SHADER_STAGE_ALL is a combination of bits used as shorthand to 558 specify all shader stages supported by the device, including all 559 additional stages which are introduced by extensions. 560ifdef::VK_NV_mesh_shader[] 561 * ename:VK_SHADER_STAGE_TASK_BIT_NV specifies the task stage. 562 * ename:VK_SHADER_STAGE_MESH_BIT_NV specifies the mesh stage. 563endif::VK_NV_mesh_shader[] 564ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 565 * ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR specifies the ray generation stage. 566 * ename:VK_SHADER_STAGE_ANY_HIT_BIT_KHR specifies the any-hit stage. 567 * ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR specifies the closest hit 568 stage. 569 * ename:VK_SHADER_STAGE_MISS_BIT_KHR specifies the miss stage. 570 * ename:VK_SHADER_STAGE_INTERSECTION_BIT_KHR specifies the intersection 571 stage. 572 * ename:VK_SHADER_STAGE_CALLABLE_BIT_KHR specifies the callable stage. 573endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 574 575[NOTE] 576.Note 577==== 578ename:VK_SHADER_STAGE_ALL_GRAPHICS only includes the original five graphics 579stages included in Vulkan 1.0, and not any stages added by extensions. 580Thus, it may not have the desired effect in all cases. 581==== 582-- 583 584[open,refpage='VkShaderStageFlags',desc='Bitmask of VkShaderStageFlagBits',type='flags'] 585-- 586include::{generated}/api/flags/VkShaderStageFlags.txt[] 587 588tname:VkShaderStageFlags is a bitmask type for setting a mask of zero or 589more elink:VkShaderStageFlagBits. 590-- 591 592ifdef::VK_EXT_subgroup_size_control[] 593[open,refpage='VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT',desc='Structure specifying the required subgroup size of a newly created pipeline shader stage',type='structs'] 594-- 595The sname:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure 596is defined as: 597 598include::{generated}/api/structs/VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT.txt[] 599 * pname:sType is the type of this structure. 600 * pname:pNext is `NULL` or a pointer to a structure extending this 601 structure. 602 * [[pipelines-required-subgroup-size]] pname:requiredSubgroupSize is an 603 unsigned integer value that specifies the required subgroup size for the 604 newly created pipeline shader stage. 605 606.Valid Usage 607**** 608 * [[VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT-requiredSubgroupSize-02760]] 609 pname:requiredSubgroupSize must: be a power-of-two integer 610 * [[VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT-requiredSubgroupSize-02761]] 611 pname:requiredSubgroupSize must: be greater or equal to 612 <<limits-min-subgroup-size,minSubgroupSize>> 613 * [[VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT-requiredSubgroupSize-02762]] 614 pname:requiredSubgroupSize must: be less than or equal to 615 <<limits-max-subgroup-size,maxSubgroupSize>> 616**** 617 618 619If a sname:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure 620is included in the pname:pNext chain of 621slink:VkPipelineShaderStageCreateInfo, it specifies that the pipeline shader 622stage being compiled has a required subgroup size. 623 624include::{generated}/validity/structs/VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT.txt[] 625-- 626endif::VK_EXT_subgroup_size_control[] 627 628ifdef::VK_HUAWEI_subpass_shading[] 629[open,refpage='VkSubpassShadingPipelineCreateInfoHUAWEI',desc='Structure specifying parameters of a newly created subpass shading pipeline',type='structs'] 630-- 631A subpass shading pipeline is a compute pipeline which must: be called only 632in a subpass of a render pass with work dimensions specified by render area 633size. 634The subpass shading pipeline shader is a compute shader allowed to access 635input attachments specified in the calling subpass. 636To create a subpass shading pipeline, call flink:vkCreateComputePipelines 637with slink:VkSubpassShadingPipelineCreateInfoHUAWEI in the pname:pNext chain 638of slink:VkComputePipelineCreateInfo. 639 640The sname:VkSubpassShadingPipelineCreateInfoHUAWEI structure is defined as: 641 642include::{generated}/api/structs/VkSubpassShadingPipelineCreateInfoHUAWEI.txt[] 643 644 * pname:sType is the type of this structure. 645 * pname:pNext is `NULL` or a pointer to a structure extending this 646 structure. 647 * pname:renderPass is a handle to a render pass object describing the 648 environment in which the pipeline will be used. 649 The pipeline must: only be used with a render pass instance compatible 650 with the one provided. 651 See <<renderpass-compatibility,Render Pass Compatibility>> for more 652 information. 653 * pname:subpass is the index of the subpass in the render pass where this 654 pipeline will be used. 655 656.Valid Usage 657**** 658 * [[VUID-VkSubpassShadingPipelineCreateInfoHUAWEI-subpass-04946]] 659 pname:subpass must: be created with 660 ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI bind point 661**** 662 663include::{generated}/validity/structs/VkSubpassShadingPipelineCreateInfoHUAWEI.txt[] 664-- 665 666[open,refpage='vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI',desc='Query maximum supported subpass shading workgroup size for a give render pass',type='protos'] 667-- 668A subpass shading pipeline's workgroup size is a 2D vector with number of 669power-of-two in width and height. 670The maximum number of width and height is implementation dependent, and may: 671vary for different formats and sample counts of attachments in a render 672pass. 673 674To query the maximum workgroup size, call: 675 676include::{generated}/api/protos/vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI.txt[] 677 678 * pname:device is a handle to a local device object that was used to 679 create the given render pass. 680 * pname:renderPass is a handle to a render pass object describing the 681 environment in which the pipeline will be used. 682 The pipeline must: only be used with a render pass instance compatible 683 with the one provided. 684 See <<renderpass-compatibility,Render Pass Compatibility>> for more 685 information. 686 * pname:pMaxWorkgroupSize is a pointer to a slink:VkExtent2D structure. 687 688include::{generated}/validity/protos/vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI.txt[] 689-- 690endif::VK_HUAWEI_subpass_shading[] 691 692 693[[pipelines-graphics]] 694== Graphics Pipelines 695 696Graphics pipelines consist of multiple shader stages, multiple 697fixed-function pipeline stages, and a pipeline layout. 698 699[open,refpage='vkCreateGraphicsPipelines',desc='Create graphics pipelines',type='protos'] 700-- 701To create graphics pipelines, call: 702 703include::{generated}/api/protos/vkCreateGraphicsPipelines.txt[] 704 705 * pname:device is the logical device that creates the graphics pipelines. 706 * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that 707 pipeline caching is disabled; or the handle of a valid 708 <<pipelines-cache,pipeline cache>> object, in which case use of that 709 cache is enabled for the duration of the command. 710 * pname:createInfoCount is the length of the pname:pCreateInfos and 711 pname:pPipelines arrays. 712 * pname:pCreateInfos is a pointer to an array of 713 slink:VkGraphicsPipelineCreateInfo structures. 714 * pname:pAllocator controls host memory allocation as described in the 715 <<memory-allocation, Memory Allocation>> chapter. 716 * pname:pPipelines is a pointer to an array of slink:VkPipeline handles in 717 which the resulting graphics pipeline objects are returned. 718 719The slink:VkGraphicsPipelineCreateInfo structure includes an array of 720slink:VkPipelineShaderStageCreateInfo structures for each of the desired 721active shader stages, as well as creation information for all relevant 722fixed-function stages, and a pipeline layout. 723 724.Valid Usage 725**** 726 * [[VUID-vkCreateGraphicsPipelines-flags-00720]] 727 If the pname:flags member of any element of pname:pCreateInfos contains 728 the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the 729 pname:basePipelineIndex member of that same element is not `-1`, 730 pname:basePipelineIndex must: be less than the index into 731 pname:pCreateInfos that corresponds to that element 732 * [[VUID-vkCreateGraphicsPipelines-flags-00721]] 733 If the pname:flags member of any element of pname:pCreateInfos contains 734 the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline 735 must: have been created with the 736 ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set 737ifdef::VK_EXT_pipeline_creation_cache_control[] 738 * [[VUID-vkCreateGraphicsPipelines-pipelineCache-02876]] 739 If pname:pipelineCache was created with 740 ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT, host 741 access to pname:pipelineCache must: be 742 <<fundamentals-threadingbehavior,externally synchronized>> 743endif::VK_EXT_pipeline_creation_cache_control[] 744**** 745 746ifdef::VK_EXT_pipeline_creation_cache_control[] 747[NOTE] 748.Note 749==== 750An implicit cache may be provided by the implementation or a layer. 751For this reason, it is still valid to set 752ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT on 753pname:flags for any element of pname:pCreateInfos while passing 754dlink:VK_NULL_HANDLE for pname:pipelineCache. 755==== 756endif::VK_EXT_pipeline_creation_cache_control[] 757 758include::{generated}/validity/protos/vkCreateGraphicsPipelines.txt[] 759-- 760 761[open,refpage='VkGraphicsPipelineCreateInfo',desc='Structure specifying parameters of a newly created graphics pipeline',type='structs'] 762-- 763The sname:VkGraphicsPipelineCreateInfo structure is defined as: 764 765include::{generated}/api/structs/VkGraphicsPipelineCreateInfo.txt[] 766 767 * pname:sType is the type of this structure. 768 * pname:pNext is `NULL` or a pointer to a structure extending this 769 structure. 770 * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying 771 how the pipeline will be generated. 772 * pname:stageCount is the number of entries in the pname:pStages array. 773 * pname:pStages is a pointer to an array of pname:stageCount 774 slink:VkPipelineShaderStageCreateInfo structures describing the set of 775 the shader stages to be included in the graphics pipeline. 776 * pname:pVertexInputState is a pointer to a 777 slink:VkPipelineVertexInputStateCreateInfo structure. 778ifdef::VK_NV_mesh_shader[] 779 It is ignored if the pipeline includes a mesh shader stage. 780endif::VK_NV_mesh_shader[] 781ifdef::VK_EXT_vertex_input_dynamic_state[] 782 It is ignored if the pipeline is created with the 783 ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state set. 784endif::VK_EXT_vertex_input_dynamic_state[] 785 * pname:pInputAssemblyState is a pointer to a 786 slink:VkPipelineInputAssemblyStateCreateInfo structure which determines 787 input assembly behavior, as described in <<drawing, Drawing Commands>>. 788ifdef::VK_NV_mesh_shader[] 789 It is ignored if the pipeline includes a mesh shader stage. 790endif::VK_NV_mesh_shader[] 791 * pname:pTessellationState is a pointer to a 792 slink:VkPipelineTessellationStateCreateInfo structure, and is ignored if 793 the pipeline does not include a tessellation control shader stage and 794 tessellation evaluation shader stage. 795 * pname:pViewportState is a pointer to a 796 slink:VkPipelineViewportStateCreateInfo structure, and is ignored if the 797 pipeline has rasterization disabled. 798 * pname:pRasterizationState is a pointer to a 799 slink:VkPipelineRasterizationStateCreateInfo structure. 800 * pname:pMultisampleState is a pointer to a 801 slink:VkPipelineMultisampleStateCreateInfo structure, and is ignored if 802 the pipeline has rasterization disabled. 803 * pname:pDepthStencilState is a pointer to a 804 slink:VkPipelineDepthStencilStateCreateInfo structure, and is ignored if 805 the pipeline has rasterization disabled or if no depth/stencil 806 attachment is used. 807 * pname:pColorBlendState is a pointer to a 808 slink:VkPipelineColorBlendStateCreateInfo structure, and is ignored if 809 the pipeline has rasterization disabled or if no color attachments are 810 used. 811 * pname:pDynamicState is a pointer to a 812 slink:VkPipelineDynamicStateCreateInfo structure, and is used to 813 indicate which properties of the pipeline state object are dynamic and 814 can: be changed independently of the pipeline state. 815 This can: be `NULL`, which means no state in the pipeline is considered 816 dynamic. 817 * pname:layout is the description of binding locations used by both the 818 pipeline and descriptor sets used with the pipeline. 819 * pname:renderPass is a handle to a render pass object describing the 820 environment in which the pipeline will be used. 821 The pipeline must: only be used with a render pass instance compatible 822 with the one provided. 823 See <<renderpass-compatibility,Render Pass Compatibility>> for more 824 information. 825 * pname:subpass is the index of the subpass in the render pass where this 826 pipeline will be used. 827 * pname:basePipelineHandle is a pipeline to derive from. 828 * pname:basePipelineIndex is an index into the pname:pCreateInfos 829 parameter to use as a pipeline to derive from. 830 831The parameters pname:basePipelineHandle and pname:basePipelineIndex are 832described in more detail in <<pipelines-pipeline-derivatives,Pipeline 833Derivatives>>. 834 835ifdef::VK_NV_glsl_shader[] 836If any shader stage fails to compile, 837ifdef::VK_EXT_debug_report[] 838the compile log will be reported back to the application, and 839endif::VK_EXT_debug_report[] 840ename:VK_ERROR_INVALID_SHADER_NV will be generated. 841endif::VK_NV_glsl_shader[] 842 843[[pipeline-graphics-subsets]] 844The state required for a graphics pipeline is divided into 845<<pipeline-graphics-subsets-vertex-input, vertex input state>>, 846<<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 847state>>, <<pipeline-graphics-subsets-fragment-shader,fragment shader 848state>>, and <<pipeline-graphics-subsets-fragment-output,fragment output 849state>>. 850 851[[pipeline-graphics-subsets-vertex-input]] 852Vertex input state is defined by: 853 854 * slink:VkPipelineVertexInputStateCreateInfo 855 * slink:VkPipelineInputAssemblyStateCreateInfo 856 857[[pipeline-graphics-subsets-pre-rasterization]] 858Pre-rasterization shader state is defined by: 859 860 * slink:VkPipelineShaderStageCreateInfo entries for: 861 ** Vertex shaders 862 ** Tessellation control shaders 863 ** Tessellation evaluation shaders 864 ** Geometry shaders 865ifdef::VK_NV_mesh_shader[] 866 ** Task shaders 867 ** Mesh shaders 868endif::VK_NV_mesh_shader[] 869 * Within the slink:VkPipelineLayout, all bindings that affect the 870 specified shader stages 871 * slink:VkPipelineViewportStateCreateInfo 872 * slink:VkPipelineRasterizationStateCreateInfo 873 * slink:VkPipelineTessellationStateCreateInfo if tessellation stages are 874 included. 875 * slink:VkRenderPass and pname:subpass parameter 876ifdef::VK_EXT_discard_rectangles[] 877 * slink:VkPipelineDiscardRectangleStateCreateInfoEXT 878endif::VK_EXT_discard_rectangles[] 879ifdef::VK_KHR_fragment_shading_rate[] 880 * slink:VkPipelineFragmentShadingRateStateCreateInfoKHR 881ifdef::VK_NV_fragment_shading_rate_enums[] 882 * slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV 883endif::VK_NV_fragment_shading_rate_enums[] 884endif::VK_KHR_fragment_shading_rate[] 885 886[[pipeline-graphics-subsets-fragment-shader]] 887Fragment shader state is defined by: 888 889 * A slink:VkPipelineShaderStageCreateInfo entry for the fragment shader 890 * Within the slink:VkPipelineLayout, all bindings that affect the fragment 891 shader 892 * slink:VkPipelineMultisampleStateCreateInfo 893 * slink:VkPipelineDepthStencilStateCreateInfo 894 * slink:VkRenderPass and pname:subpass parameter 895ifdef::VK_KHR_fragment_shading_rate[] 896 * slink:VkPipelineFragmentShadingRateStateCreateInfoKHR 897ifdef::VK_NV_fragment_shading_rate_enums[] 898 * slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV 899endif::VK_NV_fragment_shading_rate_enums[] 900endif::VK_KHR_fragment_shading_rate[] 901 902[[pipeline-graphics-subsets-fragment-output]] 903Fragment output state is defined by: 904 905 * slink:VkPipelineColorBlendStateCreateInfo 906 * The pname:alphaToCoverageEnable and pname:alphaToOneEnable members of 907 slink:VkPipelineMultisampleStateCreateInfo. 908 * slink:VkRenderPass and pname:subpass parameter 909 910[[pipeline-graphics-subsets-complete]] 911A complete graphics pipeline always includes 912<<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 913state>>, with other subsets included depending on that state. 914If the <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization 915shader state>> includes a vertex shader, then 916<<pipeline-graphics-subsets-vertex-input, vertex input state>> is included 917in a complete graphics pipeline. 918If the value of 919slink:VkPipelineRasterizationStateCreateInfo::pname:rasterizerDiscardEnable 920in the <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization 921shader state>> is ename:VK_FALSE 922ifdef::VK_EXT_extended_dynamic_state2[] 923or the ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT dynamic state is 924enabled 925endif::VK_EXT_extended_dynamic_state2[] 926<<pipeline-graphics-subsets-fragment-shader, fragment shader state>> and 927<<pipeline-graphics-subsets-fragment-output, fragment output interface 928state>> is included in a complete graphics pipeline. 929 930Pipelines must: be created with a complete set of pipeline state. 931 932.Valid Usage 933**** 934 * [[VUID-VkGraphicsPipelineCreateInfo-flags-00722]] 935 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 936 flag, and pname:basePipelineIndex is -1, pname:basePipelineHandle must: 937 be a valid handle to a graphics sname:VkPipeline 938 * [[VUID-VkGraphicsPipelineCreateInfo-flags-00723]] 939 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 940 flag, and pname:basePipelineHandle is dlink:VK_NULL_HANDLE, 941 pname:basePipelineIndex must: be a valid index into the calling 942 command's pname:pCreateInfos parameter 943 * [[VUID-VkGraphicsPipelineCreateInfo-flags-00724]] 944 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 945 flag, and pname:basePipelineIndex is not -1, pname:basePipelineHandle 946 must: be dlink:VK_NULL_HANDLE 947 * [[VUID-VkGraphicsPipelineCreateInfo-flags-00725]] 948 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 949 flag, and pname:basePipelineHandle is not dlink:VK_NULL_HANDLE, 950 pname:basePipelineIndex must: be -1 951 * [[VUID-VkGraphicsPipelineCreateInfo-stage-00726]] 952 The pname:stage member of each element of pname:pStages must: be unique 953ifndef::VK_NV_mesh_shader[] 954 * [[VUID-VkGraphicsPipelineCreateInfo-stage-00727]] 955 If the pipeline is being created with 956 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 957 state>> the pname:stage member of one element of pname:pStages must: be 958 ename:VK_SHADER_STAGE_VERTEX_BIT 959endif::VK_NV_mesh_shader[] 960ifdef::VK_NV_mesh_shader[] 961 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02095]] 962 If the pipeline is being created with 963 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 964 state>> the geometric shader stages provided in pname:pStages must: be 965 either from the mesh shading pipeline (pname:stage is 966 ename:VK_SHADER_STAGE_TASK_BIT_NV or ename:VK_SHADER_STAGE_MESH_BIT_NV) 967 or from the primitive shading pipeline (pname:stage is 968 ename:VK_SHADER_STAGE_VERTEX_BIT, 969 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, 970 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or 971 ename:VK_SHADER_STAGE_GEOMETRY_BIT) 972 * [[VUID-VkGraphicsPipelineCreateInfo-stage-02096]] 973 If the pipeline is being created with 974 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 975 state>> the pname:stage member of one element of pname:pStages must: be 976 either ename:VK_SHADER_STAGE_VERTEX_BIT or 977 ename:VK_SHADER_STAGE_MESH_BIT_NV 978endif::VK_NV_mesh_shader[] 979 * [[VUID-VkGraphicsPipelineCreateInfo-stage-00728]] 980 The pname:stage member of each element of pname:pStages must: not be 981 ename:VK_SHADER_STAGE_COMPUTE_BIT 982 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00729]] 983 If the pipeline is being created with 984 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 985 state>> and pname:pStages includes a tessellation control shader stage, 986 it must: include a tessellation evaluation shader stage 987 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00730]] 988 If the pipeline is being created with 989 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 990 state>> and pname:pStages includes a tessellation evaluation shader 991 stage, it must: include a tessellation control shader stage 992 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00731]] 993 If the pipeline is being created with 994 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 995 state>> and pname:pStages includes a tessellation control shader stage 996 and a tessellation evaluation shader stage, pname:pTessellationState 997 must: be a valid pointer to a valid 998 slink:VkPipelineTessellationStateCreateInfo structure 999 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00732]] 1000 If the pipeline is being created with 1001 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1002 state>> and pname:pStages includes tessellation shader stages, the 1003 shader code of at least one stage must: contain an code:OpExecutionMode 1004 instruction that specifies the type of subdivision in the pipeline 1005 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00733]] 1006 If the pipeline is being created with 1007 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1008 state>> and pname:pStages includes tessellation shader stages, and the 1009 shader code of both stages contain an code:OpExecutionMode instruction 1010 that specifies the type of subdivision in the pipeline, they must: both 1011 specify the same subdivision mode 1012 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00734]] 1013 If the pipeline is being created with 1014 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1015 state>> and pname:pStages includes tessellation shader stages, the 1016 shader code of at least one stage must: contain an code:OpExecutionMode 1017 instruction that specifies the output patch size in the pipeline 1018 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00735]] 1019 If the pipeline is being created with 1020 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1021 state>> and pname:pStages includes tessellation shader stages, and the 1022 shader code of both contain an code:OpExecutionMode instruction that 1023 specifies the out patch size in the pipeline, they must: both specify 1024 the same patch size 1025 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00736]] 1026 If the pipeline is being created with 1027 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1028 state>> and pname:pStages includes tessellation shader stages, the 1029 pname:topology member of pname:pInputAssembly must: be 1030 ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST 1031 * [[VUID-VkGraphicsPipelineCreateInfo-topology-00737]] 1032 If the pipeline is being created with 1033 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1034 state>> and the pname:topology member of pname:pInputAssembly is 1035 ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, pname:pStages must: include 1036 tessellation shader stages 1037 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00738]] 1038 If the pipeline is being created with 1039 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1040 state>> and pname:pStages includes a geometry shader stage, and does not 1041 include any tessellation shader stages, its shader code must: contain an 1042 code:OpExecutionMode instruction that specifies an input primitive type 1043 that is <<shaders-geometry-execution, compatible>> with the primitive 1044 topology specified in pname:pInputAssembly 1045 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00739]] 1046 If the pipeline is being created with 1047 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1048 state>> and pname:pStages includes a geometry shader stage, and also 1049 includes tessellation shader stages, its shader code must: contain an 1050 code:OpExecutionMode instruction that specifies an input primitive type 1051 that is <<shaders-geometry-execution, compatible>> with the primitive 1052 topology that is output by the tessellation stages 1053 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00740]] 1054 If the pipeline is being created with 1055 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1056 state>> and <<pipeline-graphics-subsets-fragment-shader, fragment shader 1057 state>>, it includes both a fragment shader and a geometry shader, and 1058 the fragment shader code reads from an input variable that is decorated 1059 with code:PrimitiveId, then the geometry shader code must: write to a 1060 matching output variable, decorated with code:PrimitiveId, in all 1061 execution paths 1062ifdef::VK_NV_mesh_shader[] 1063 * [[VUID-VkGraphicsPipelineCreateInfo-PrimitiveId-06264]] 1064 If the pipeline is being created with 1065 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1066 state>>, it includes a mesh shader and the fragment shader code reads 1067 from an input variable that is decorated with code:PrimitiveId, then the 1068 mesh shader code must: write to a matching output variable, decorated 1069 with code:PrimitiveId, in all execution paths 1070endif::VK_NV_mesh_shader[] 1071 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06038]] 1072 If pname:renderPass is not dlink:VK_NULL_HANDLE and the pipeline is 1073 being created with <<pipeline-graphics-subsets-fragment-shader, fragment 1074 shader state>> the fragment shader must: not read from any input 1075 attachment that is defined as ename:VK_ATTACHMENT_UNUSED in 1076 pname:subpass 1077 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00742]] 1078 If the pipeline is being created with 1079 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1080 state>> and multiple pre-rasterization shader stages are included in 1081 pname:pStages, the shader code for the entry points identified by those 1082 pname:pStages and the rest of the state identified by this structure 1083 must: adhere to the pipeline linking rules described in the 1084 <<interfaces,Shader Interfaces>> chapter 1085 * [[VUID-VkGraphicsPipelineCreateInfo-None-04889]] 1086 If the pipeline is being created with 1087 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1088 state>> and <<pipeline-graphics-subsets-fragment-shader, fragment shader 1089 state>>, the fragment shader and last 1090 <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 1091 stage>> and any relevant state must: adhere to the pipeline linking 1092 rules described in the <<interfaces,Shader Interfaces>> chapter 1093 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06039]] 1094 If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being 1095 created with <<pipeline-graphics-subsets-fragment-shader, fragment 1096 shader state>>, and pname:subpass uses a depth/stencil attachment in 1097 pname:renderPass with a read-only layout for the depth aspect in the 1098 slink:VkAttachmentReference defined by pname:subpass, the 1099 pname:depthWriteEnable member of pname:pDepthStencilState must: be 1100 ename:VK_FALSE 1101 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06040]] 1102 If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being 1103 created with <<pipeline-graphics-subsets-fragment-shader, fragment 1104 shader state>>, and pname:subpass uses a depth/stencil attachment in 1105 pname:renderPass with a read-only layout for the stencil aspect in the 1106 slink:VkAttachmentReference defined by pname:subpass, the pname:failOp, 1107 pname:passOp and pname:depthFailOp members of each of the pname:front 1108 and pname:back members of pname:pDepthStencilState must: be 1109 ename:VK_STENCIL_OP_KEEP 1110 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06041]] 1111 If pname:renderPass is not dlink:VK_NULL_HANDLE, and the pipeline is 1112 being created with <<pipeline-graphics-subsets-fragment-output, fragment 1113 output interface state>>, then for each color attachment in the subpass, 1114 if the <<potential-format-features,potential format features>> of the 1115 format of the corresponding attachment description do not contain 1116 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT, then the 1117 pname:blendEnable member of the corresponding element of the 1118 pname:pAttachments member of pname:pColorBlendState must: be 1119 ename:VK_FALSE 1120 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06042]] 1121 If pname:renderPass is not dlink:VK_NULL_HANDLE, and the pipeline is 1122 being created with <<pipeline-graphics-subsets-fragment-output, fragment 1123 output interface state>>, and the subpass uses color attachments, the 1124 pname:attachmentCount member of pname:pColorBlendState must: be equal to 1125 the pname:colorAttachmentCount used to create pname:subpass 1126ifndef::VK_EXT_extended_dynamic_state[] 1127 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00747]] 1128 If the pipeline is being created with 1129 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1130 state>>, and no element of the pname:pDynamicStates member of 1131 pname:pDynamicState is ename:VK_DYNAMIC_STATE_VIEWPORT, the 1132 pname:pViewports member of pname:pViewportState must: be a valid pointer 1133 to an array of pname:pViewportState->viewportCount valid 1134 sname:VkViewport structures 1135 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00748]] 1136 If the pipeline is being created with 1137 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1138 state>>, and no element of the pname:pDynamicStates member of 1139 pname:pDynamicState is ename:VK_DYNAMIC_STATE_SCISSOR, the 1140 pname:pScissors member of pname:pViewportState must: be a valid pointer 1141 to an array of pname:pViewportState->scissorCount sname:VkRect2D 1142 structures 1143endif::VK_EXT_extended_dynamic_state[] 1144ifdef::VK_EXT_extended_dynamic_state[] 1145 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04130]] 1146 If the pipeline is being created with 1147 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1148 state>>, and no element of the pname:pDynamicStates member of 1149 pname:pDynamicState is ename:VK_DYNAMIC_STATE_VIEWPORT or 1150 ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT, the pname:pViewports 1151 member of pname:pViewportState must: be a valid pointer to an array of 1152 pname:pViewportState->viewportCount valid sname:VkViewport structures 1153 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04131]] 1154 If the pipeline is being created with 1155 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1156 state>>, and no element of the pname:pDynamicStates member of 1157 pname:pDynamicState is ename:VK_DYNAMIC_STATE_SCISSOR or 1158 ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT, the pname:pScissors 1159 member of pname:pViewportState must: be a valid pointer to an array of 1160 pname:pViewportState->scissorCount sname:VkRect2D structures 1161endif::VK_EXT_extended_dynamic_state[] 1162 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00749]] 1163 If the pipeline is being created with 1164 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1165 state>>, and the wide lines feature is not enabled, and no element of 1166 the pname:pDynamicStates member of pname:pDynamicState is 1167 ename:VK_DYNAMIC_STATE_LINE_WIDTH, the pname:lineWidth member of 1168 pname:pRasterizationState must: be `1.0` 1169 * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00750]] 1170 If the pipeline is being created with 1171 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1172 state>>, and the pname:rasterizerDiscardEnable member of 1173 pname:pRasterizationState is ename:VK_FALSE, pname:pViewportState must: 1174 be a valid pointer to a valid slink:VkPipelineViewportStateCreateInfo 1175 structure 1176ifdef::VK_EXT_extended_dynamic_state2[] 1177 * [[VUID-VkGraphicsPipelineCreateInfo-pViewportState-04892]] 1178 If the pipeline is being created with 1179 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1180 state>>, and the graphics pipeline state was created with the 1181 ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT dynamic state 1182 enabled, pname:pViewportState must: be a valid pointer to a valid 1183 slink:VkPipelineViewportStateCreateInfo structure 1184endif::VK_EXT_extended_dynamic_state2[] 1185 * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00751]] 1186 If the pipeline is being created with 1187 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1188 pname:pMultisampleState must: be a valid pointer to a valid 1189 slink:VkPipelineMultisampleStateCreateInfo structure 1190 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06043]] 1191 If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being 1192 created with <<pipeline-graphics-subsets-fragment-shader, fragment 1193 shader state>>, and pname:subpass uses a depth/stencil attachment, 1194 pname:pDepthStencilState must: be a valid pointer to a valid 1195 slink:VkPipelineDepthStencilStateCreateInfo structure 1196 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06044]] 1197 If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being 1198 created with <<pipeline-graphics-subsets-fragment-output, fragment 1199 output interface state>>, and pname:subpass uses color attachments, 1200 pname:pColorBlendState must: be a valid pointer to a valid 1201 slink:VkPipelineColorBlendStateCreateInfo structure 1202 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06045]] 1203 If pname:renderPass is not dlink:VK_NULL_HANDLE and the pipeline is 1204 being created with <<pipeline-graphics-subsets-fragment-output, fragment 1205 output interface state>>, pname:pColorBlendState->attachmentCount must: 1206 be greater than the index of all color attachments that are not 1207 ename:VK_ATTACHMENT_UNUSED for the pname:subpass index in 1208 pname:renderPass 1209 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00754]] 1210 If the pipeline is being created with 1211 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1212 state>>, the depth bias clamping feature is not enabled, no element of 1213 the pname:pDynamicStates member of pname:pDynamicState is 1214 ename:VK_DYNAMIC_STATE_DEPTH_BIAS, and the pname:depthBiasEnable member 1215 of pname:pRasterizationState is ename:VK_TRUE, the pname:depthBiasClamp 1216 member of pname:pRasterizationState must: be `0.0` 1217ifndef::VK_EXT_depth_range_unrestricted[] 1218 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00755]] 1219 If the pipeline is being created with 1220 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1221 and no element of the pname:pDynamicStates member of pname:pDynamicState 1222 is ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS, and the 1223 pname:depthBoundsTestEnable member of pname:pDepthStencilState is 1224 ename:VK_TRUE, the pname:minDepthBounds and pname:maxDepthBounds members 1225 of pname:pDepthStencilState must: be between `0.0` and `1.0`, inclusive 1226endif::VK_EXT_depth_range_unrestricted[] 1227ifdef::VK_EXT_depth_range_unrestricted[] 1228 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-02510]] 1229 If the pipeline is being created with 1230 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1231 and the `apiext:VK_EXT_depth_range_unrestricted` extension is not 1232 enabled and no element of the pname:pDynamicStates member of 1233 pname:pDynamicState is ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS, and the 1234 pname:depthBoundsTestEnable member of pname:pDepthStencilState is 1235 ename:VK_TRUE, the pname:minDepthBounds and pname:maxDepthBounds members 1236 of pname:pDepthStencilState must: be between `0.0` and `1.0`, inclusive 1237endif::VK_EXT_depth_range_unrestricted[] 1238ifdef::VK_EXT_sample_locations[] 1239 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01521]] 1240 If the pipeline is being created with 1241 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1242 and no element of the pname:pDynamicStates member of pname:pDynamicState 1243 is ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT, and the 1244 pname:sampleLocationsEnable member of a 1245 slink:VkPipelineSampleLocationsStateCreateInfoEXT structure included in 1246 the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE, 1247 pname:sampleLocationsInfo.sampleLocationGridSize.width must: evenly 1248 divide 1249 slink:VkMultisamplePropertiesEXT::pname:sampleLocationGridSize.width as 1250 returned by flink:vkGetPhysicalDeviceMultisamplePropertiesEXT with a 1251 pname:samples parameter equaling pname:rasterizationSamples 1252 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01522]] 1253 If the pipeline is being created with 1254 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1255 and no element of the pname:pDynamicStates member of pname:pDynamicState 1256 is ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT, and the 1257 pname:sampleLocationsEnable member of a 1258 slink:VkPipelineSampleLocationsStateCreateInfoEXT structure included in 1259 the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE, 1260 pname:sampleLocationsInfo.sampleLocationGridSize.height must: evenly 1261 divide 1262 slink:VkMultisamplePropertiesEXT::pname:sampleLocationGridSize.height as 1263 returned by flink:vkGetPhysicalDeviceMultisamplePropertiesEXT with a 1264 pname:samples parameter equaling pname:rasterizationSamples 1265 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01523]] 1266 If the pipeline is being created with 1267 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1268 and no element of the pname:pDynamicStates member of pname:pDynamicState 1269 is ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT, and the 1270 pname:sampleLocationsEnable member of a 1271 slink:VkPipelineSampleLocationsStateCreateInfoEXT structure included in 1272 the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE, 1273 pname:sampleLocationsInfo.sampleLocationsPerPixel must: equal 1274 pname:rasterizationSamples 1275 * [[VUID-VkGraphicsPipelineCreateInfo-sampleLocationsEnable-01524]] 1276 If the pipeline is being created with 1277 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1278 and the pname:sampleLocationsEnable member of a 1279 slink:VkPipelineSampleLocationsStateCreateInfoEXT structure included in 1280 the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE, the 1281 fragment shader code must: not statically use the extended instruction 1282 code:InterpolateAtSample 1283endif::VK_EXT_sample_locations[] 1284 * [[VUID-VkGraphicsPipelineCreateInfo-layout-00756]] 1285 pname:layout must: be 1286 <<descriptorsets-pipelinelayout-consistency,consistent>> with all 1287 shaders specified in pname:pStages 1288 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00757]] 1289 If the pipeline is being created with 1290 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1291 and neither the `apiext:VK_AMD_mixed_attachment_samples` nor the 1292 `apiext:VK_NV_framebuffer_mixed_samples` extensions are enabled, and if 1293 pname:subpass uses color and/or depth/stencil attachments, then the 1294 pname:rasterizationSamples member of pname:pMultisampleState must: be 1295 the same as the sample count for those subpass attachments 1296ifdef::VK_AMD_mixed_attachment_samples[] 1297 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01505]] 1298 If the pipeline is being created with 1299 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1300 and the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, 1301 and if pname:subpass uses color and/or depth/stencil attachments, then 1302 the pname:rasterizationSamples member of pname:pMultisampleState must: 1303 equal the maximum of the sample counts of those subpass attachments 1304endif::VK_AMD_mixed_attachment_samples[] 1305ifdef::VK_NV_framebuffer_mixed_samples[] 1306 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01411]] 1307 If the pipeline is being created with 1308 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1309 and the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, 1310 and if pname:subpass has a depth/stencil attachment and depth test, 1311 stencil test, or depth bounds test are enabled, then the 1312 pname:rasterizationSamples member of pname:pMultisampleState must: be 1313 the same as the sample count of the depth/stencil attachment 1314 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01412]] 1315 If the pipeline is being created with 1316 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1317 and the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, 1318 and if pname:subpass has any color attachments, then the 1319 pname:rasterizationSamples member of pname:pMultisampleState must: be 1320 greater than or equal to the sample count for those subpass attachments 1321endif::VK_NV_framebuffer_mixed_samples[] 1322ifdef::VK_NV_coverage_reduction_mode[] 1323 * [[VUID-VkGraphicsPipelineCreateInfo-coverageReductionMode-02722]] 1324 If the pipeline is being created with 1325 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1326 and the `apiext:VK_NV_coverage_reduction_mode` extension is enabled, the 1327 coverage reduction mode specified by 1328 slink:VkPipelineCoverageReductionStateCreateInfoNV::pname:coverageReductionMode, 1329 the pname:rasterizationSamples member of pname:pMultisampleState and the 1330 sample counts for the color and depth/stencil attachments (if the 1331 subpass has them) must: be a valid combination returned by 1332 fname:vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV 1333endif::VK_NV_coverage_reduction_mode[] 1334 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00758]] 1335 If the pipeline is being created with 1336 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>> and 1337 pname:subpass does not use any color and/or depth/stencil attachments, 1338 then the pname:rasterizationSamples member of pname:pMultisampleState 1339 must: follow the rules for a <<renderpass-noattachments, zero-attachment 1340 subpass>> 1341 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06046]] 1342 If pname:renderPass is a valid renderPass, pname:subpass must: be a 1343 valid subpass within pname:renderPass 1344ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1345 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06047]] 1346 If pname:renderPass is a valid renderPass, the pipeline is being created 1347 with <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization 1348 shader state>>, and the pname:renderPass has multiview enabled and 1349 pname:subpass has more than one bit set in the view mask and 1350 pname:multiviewTessellationShader is not enabled, then pname:pStages 1351 must: not include tessellation shaders 1352 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06048]] 1353 If pname:renderPass is a valid renderPass, the pipeline is being created 1354 with <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization 1355 shader state>>, and the pname:renderPass has multiview enabled and 1356 pname:subpass has more than one bit set in the view mask and 1357 pname:multiviewGeometryShader is not enabled, then pname:pStages must: 1358 not include a geometry shader 1359 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06049]] 1360 If pname:renderPass is a valid renderPass, the pipeline is being created 1361 with <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization 1362 shader state>>, and the pname:renderPass has multiview enabled and 1363 pname:subpass has more than one bit set in the view mask, shaders in the 1364 pipeline must: not write to the code:Layer built-in output 1365 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06050]] 1366 If pname:renderPass is a valid renderPass and the pipeline is being 1367 created with <<pipeline-graphics-subsets-pre-rasterization, 1368 pre-rasterization shader state>>, and the pname:renderPass has multiview 1369 enabled, then all shaders must: not include variables decorated with the 1370 code:Layer built-in decoration in their interfaces 1371endif::VK_VERSION_1_1,VK_KHR_multiview[] 1372ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1373 * [[VUID-VkGraphicsPipelineCreateInfo-flags-00764]] 1374 pname:flags must: not contain the ename:VK_PIPELINE_CREATE_DISPATCH_BASE 1375 flag 1376endif::VK_VERSION_1_1,VK_KHR_device_group[] 1377ifdef::VK_VERSION_1_1,VK_KHR_maintenance2,VK_KHR_create_renderpass2[] 1378 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-01565]] 1379 If the pipeline is being created with 1380 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>> and 1381 an input attachment was referenced by an pname:aspectMask at 1382 pname:renderPass creation time, the fragment shader must: only read from 1383 the aspects that were specified for that input attachment 1384endif::VK_VERSION_1_1,VK_KHR_maintenance2,VK_KHR_create_renderpass2[] 1385 * [[VUID-VkGraphicsPipelineCreateInfo-layout-01688]] 1386 The number of resources in pname:layout accessible to each shader stage 1387 that is used by the pipeline must: be less than or equal to 1388 sname:VkPhysicalDeviceLimits::pname:maxPerStageResources 1389ifdef::VK_NV_clip_space_w_scaling[] 1390 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01715]] 1391 If the pipeline is being created with 1392 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1393 state>>, and no element of the pname:pDynamicStates member of 1394 pname:pDynamicState is ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV, and 1395 the pname:viewportWScalingEnable member of a 1396 slink:VkPipelineViewportWScalingStateCreateInfoNV structure, included in 1397 the pname:pNext chain of pname:pViewportState, is ename:VK_TRUE, the 1398 pname:pViewportWScalings member of the 1399 slink:VkPipelineViewportWScalingStateCreateInfoNV must: be a pointer to 1400 an array of 1401 slink:VkPipelineViewportWScalingStateCreateInfoNV::pname:viewportCount 1402 valid slink:VkViewportWScalingNV structures 1403endif::VK_NV_clip_space_w_scaling[] 1404ifdef::VK_NV_scissor_exclusive[] 1405 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04056]] 1406 If the pipeline is being created with 1407 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1408 state>>, and no element of the pname:pDynamicStates member of 1409 pname:pDynamicState is ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV, and 1410 if pname:pViewportState->pNext chain includes a 1411 slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV structure, and 1412 if its pname:exclusiveScissorCount member is not `0`, then its 1413 pname:pExclusiveScissors member must: be a valid pointer to an array of 1414 pname:exclusiveScissorCount slink:VkRect2D structures 1415endif::VK_NV_scissor_exclusive[] 1416ifdef::VK_NV_shading_rate_image[] 1417 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04057]] 1418 If the pipeline is being created with 1419 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1420 state>>, and no element of the pname:pDynamicStates member of 1421 pname:pDynamicState is 1422 ename:VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV, and if 1423 pname:pViewportState->pNext chain includes a 1424 slink:VkPipelineViewportShadingRateImageStateCreateInfoNV structure, 1425 then its pname:pShadingRatePalettes member must: be a valid pointer to 1426 an array of pname:viewportCount valid slink:VkShadingRatePaletteNV 1427 structures 1428endif::VK_NV_shading_rate_image[] 1429ifdef::VK_EXT_discard_rectangles[] 1430 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04058]] 1431 If the pipeline is being created with 1432 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1433 state>>, and no element of the pname:pDynamicStates member of 1434 pname:pDynamicState is ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT, and 1435 if pname:pNext chain includes a 1436 slink:VkPipelineDiscardRectangleStateCreateInfoEXT structure, and if its 1437 pname:discardRectangleCount member is not `0`, then its 1438 pname:pDiscardRectangles member must: be a valid pointer to an array of 1439 pname:discardRectangleCount slink:VkRect2D structures 1440endif::VK_EXT_discard_rectangles[] 1441ifndef::VK_EXT_vertex_input_dynamic_state[] 1442 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02097]] 1443 If the pipeline is being created with 1444 <<pipeline-graphics-subsets-vertex-input, vertex input state>>, 1445 pname:pVertexInputState must: be a valid pointer to a valid 1446 slink:VkPipelineVertexInputStateCreateInfo structure 1447endif::VK_EXT_vertex_input_dynamic_state[] 1448ifndef::VK_EXT_vertex_input_dynamic_state[] 1449 * [[VUID-VkGraphicsPipelineCreateInfo-pVertexInputState-04910]] 1450 If the pipeline is being created with 1451 <<pipeline-graphics-subsets-vertex-input, vertex input state>>, and 1452 ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT is not set, 1453 pname:pVertexInputState must: be a valid pointer to a valid 1454 slink:VkPipelineVertexInputStateCreateInfo structure 1455endif::VK_EXT_vertex_input_dynamic_state[] 1456 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02098]] 1457 If the pipeline is being created with 1458 <<pipeline-graphics-subsets-vertex-input, vertex input state>>, 1459 pname:pInputAssemblyState must: be a valid pointer to a valid 1460 slink:VkPipelineInputAssemblyStateCreateInfo structure 1461ifdef::VK_EXT_transform_feedback[] 1462 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02317]] 1463 If the pipeline is being created with 1464 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1465 state>>, the code:Xfb execution mode can: be specified by no more than 1466 one shader stage in pname:pStages 1467 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02318]] 1468 If the pipeline is being created with 1469 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1470 state>>, and any shader stage in pname:pStages specifies code:Xfb 1471 execution mode it must: be the last 1472 <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 1473 stage>> 1474 * [[VUID-VkGraphicsPipelineCreateInfo-rasterizationStream-02319]] 1475 If the pipeline is being created with 1476 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1477 state>>, and a 1478 slink:VkPipelineRasterizationStateStreamCreateInfoEXT::pname:rasterizationStream 1479 value other than zero is specified, all variables in the output 1480 interface of the entry point being compiled decorated with 1481 code:Position, code:PointSize, code:ClipDistance, or code:CullDistance 1482 must: be decorated with identical code:Stream values that match the 1483 pname:rasterizationStream 1484 * [[VUID-VkGraphicsPipelineCreateInfo-rasterizationStream-02320]] 1485 If the pipeline is being created with 1486 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1487 state>>, and 1488 slink:VkPipelineRasterizationStateStreamCreateInfoEXT::pname:rasterizationStream 1489 is zero, or not specified, all variables in the output interface of the 1490 entry point being compiled decorated with code:Position, code:PointSize, 1491 code:ClipDistance, or code:CullDistance must: be decorated with a 1492 code:Stream value of zero, or must: not specify the code:Stream 1493 decoration 1494 * [[VUID-VkGraphicsPipelineCreateInfo-geometryStreams-02321]] 1495 If the pipeline is being created with 1496 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1497 state>>, and the last 1498 <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader 1499 stage>> is a geometry shader, and that geometry shader uses the 1500 code:GeometryStreams capability, then 1501 sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:geometryStreams 1502 feature must: be enabled 1503ifdef::VK_NV_mesh_shader[] 1504 * [[VUID-VkGraphicsPipelineCreateInfo-None-02322]] 1505 If the pipeline is being created with 1506 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1507 state>>, and there are any mesh shader stages in the pipeline there 1508 must: not be any shader stage in the pipeline with a code:Xfb execution 1509 mode 1510endif::VK_NV_mesh_shader[] 1511endif::VK_EXT_transform_feedback[] 1512ifdef::VK_EXT_line_rasterization[] 1513 * [[VUID-VkGraphicsPipelineCreateInfo-lineRasterizationMode-02766]] 1514 If the pipeline is being created with 1515 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1516 state>> and at least one of <<pipeline-graphics-subsets-fragment-output, 1517 fragment output interface state>> or 1518 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, 1519 the pname:lineRasterizationMode member of a 1520 slink:VkPipelineRasterizationLineStateCreateInfoEXT structure included 1521 in the pname:pNext chain of pname:pRasterizationState is 1522 ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT or 1523 ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, then the 1524 pname:alphaToCoverageEnable, pname:alphaToOneEnable, and 1525 pname:sampleShadingEnable members of pname:pMultisampleState must: all 1526 be ename:VK_FALSE 1527 * [[VUID-VkGraphicsPipelineCreateInfo-stippledLineEnable-02767]] 1528 If the pipeline is being created with 1529 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1530 state>>, the pname:stippledLineEnable member of 1531 slink:VkPipelineRasterizationLineStateCreateInfoEXT is ename:VK_TRUE, 1532 and no element of the pname:pDynamicStates member of pname:pDynamicState 1533 is ename:VK_DYNAMIC_STATE_LINE_STIPPLE_EXT, then the 1534 pname:lineStippleFactor member of 1535 slink:VkPipelineRasterizationLineStateCreateInfoEXT must: be in the 1536 range [eq]#[1,256]# 1537endif::VK_EXT_line_rasterization[] 1538ifdef::VK_KHR_pipeline_library[] 1539 * [[VUID-VkGraphicsPipelineCreateInfo-flags-03371]] 1540 pname:flags must: not include ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR 1541endif::VK_KHR_pipeline_library[] 1542ifdef::VK_KHR_ray_tracing_pipeline[] 1543 * [[VUID-VkGraphicsPipelineCreateInfo-flags-03372]] 1544 pname:flags must: not include 1545 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR 1546 * [[VUID-VkGraphicsPipelineCreateInfo-flags-03373]] 1547 pname:flags must: not include 1548 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR 1549 * [[VUID-VkGraphicsPipelineCreateInfo-flags-03374]] 1550 pname:flags must: not include 1551 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR 1552 * [[VUID-VkGraphicsPipelineCreateInfo-flags-03375]] 1553 pname:flags must: not include 1554 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR 1555 * [[VUID-VkGraphicsPipelineCreateInfo-flags-03376]] 1556 pname:flags must: not include 1557 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR 1558 * [[VUID-VkGraphicsPipelineCreateInfo-flags-03377]] 1559 pname:flags must: not include 1560 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR 1561 * [[VUID-VkGraphicsPipelineCreateInfo-flags-03577]] 1562 pname:flags must: not include 1563 ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR 1564endif::VK_KHR_ray_tracing_pipeline[] 1565ifdef::VK_NV_ray_tracing_motion_blur[] 1566 * [[VUID-VkGraphicsPipelineCreateInfo-flags-04947]] 1567 pname:flags must: not include 1568 ename:VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV 1569endif::VK_NV_ray_tracing_motion_blur[] 1570ifdef::VK_EXT_extended_dynamic_state[] 1571 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03378]] 1572 If the <<features-extendedDynamicState, extendedDynamicState>> feature 1573 is not enabled, there must: be no element of the pname:pDynamicStates 1574 member of pname:pDynamicState set to 1575 ename:VK_DYNAMIC_STATE_CULL_MODE_EXT, 1576 ename:VK_DYNAMIC_STATE_FRONT_FACE_EXT, 1577 ename:VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT, 1578 ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT, 1579 ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT, 1580 ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE_EXT, 1581 ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT, 1582 ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT, 1583 ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT, 1584 ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT, 1585 ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT, or 1586 ename:VK_DYNAMIC_STATE_STENCIL_OP_EXT 1587 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03379]] 1588 If the pipeline is being created with 1589 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1590 state>>, and ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT is included 1591 in the pname:pDynamicStates array then pname:viewportCount must: be zero 1592 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03380]] 1593 If the pipeline is being created with 1594 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1595 state>>, and ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT is included 1596 in the pname:pDynamicStates array then pname:scissorCount must: be zero 1597 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04132]] 1598 If the pipeline is being created with 1599 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1600 state>>, and ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT is included 1601 in the pname:pDynamicStates array then ename:VK_DYNAMIC_STATE_VIEWPORT 1602 must: not be present 1603 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04133]] 1604 If the pipeline is being created with 1605 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1606 state>>, and ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT is included 1607 in the pname:pDynamicStates array then ename:VK_DYNAMIC_STATE_SCISSOR 1608 must: not be present 1609endif::VK_EXT_extended_dynamic_state[] 1610ifdef::VK_EXT_extended_dynamic_state2[] 1611 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04868]] 1612 If the <<features-extendedDynamicState2, extendedDynamicState2>> feature 1613 is not enabled, there must: be no element of the pname:pDynamicStates 1614 member of pname:pDynamicState set to 1615 ename:VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE_EXT, 1616 ename:VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE_EXT, or 1617 ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT 1618 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04869]] 1619 If the <<features-extendedDynamicState2LogicOp, 1620 extendedDynamicState2LogicOp>> feature is not enabled, there must: be no 1621 element of the pname:pDynamicStates member of pname:pDynamicState set to 1622 ename:VK_DYNAMIC_STATE_LOGIC_OP_EXT 1623 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04870]] 1624 If the <<features-extendedDynamicState2PatchControlPoints, 1625 extendedDynamicState2PatchControlPoints>> feature is not enabled, there 1626 must: be no element of the pname:pDynamicStates member of 1627 pname:pDynamicState set to 1628 ename:VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT 1629endif::VK_EXT_extended_dynamic_state2[] 1630ifdef::VK_NV_device_generated_commands[] 1631 * [[VUID-VkGraphicsPipelineCreateInfo-flags-02877]] 1632 If pname:flags includes 1633 ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV, then the 1634 <<features-deviceGeneratedCommands, 1635 sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>> 1636 feature must: be enabled 1637ifdef::VK_EXT_transform_feedback[] 1638 * [[VUID-VkGraphicsPipelineCreateInfo-flags-02966]] 1639 If the pipeline is being created with 1640 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1641 state>> and pname:flags includes 1642 ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV, then all stages must: 1643 not specify code:Xfb execution mode 1644endif::VK_EXT_transform_feedback[] 1645endif::VK_NV_device_generated_commands[] 1646ifdef::VK_EXT_pipeline_creation_cache_control[] 1647 * [[VUID-VkGraphicsPipelineCreateInfo-pipelineCreationCacheControl-02878]] 1648 If the <<features-pipelineCreationCacheControl, 1649 pname:pipelineCreationCacheControl>> feature is not enabled, pname:flags 1650 must: not include 1651 ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT or 1652 ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT 1653endif::VK_EXT_pipeline_creation_cache_control[] 1654ifdef::VK_KHR_fragment_shading_rate[] 1655 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04494]] 1656 If the pipeline is being created with 1657 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1658 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1659 state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1660 included in pname:pDynamicState->pDynamicStates, 1661 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.width 1662 must: be greater than or equal to `1` 1663 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04495]] 1664 If the pipeline is being created with 1665 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1666 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1667 state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1668 included in pname:pDynamicState->pDynamicStates, 1669 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.height 1670 must: be greater than or equal to `1` 1671 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04496]] 1672 If the pipeline is being created with 1673 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1674 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1675 state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1676 included in pname:pDynamicState->pDynamicStates, 1677 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.width 1678 must: be a power-of-two value 1679 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04497]] 1680 If the pipeline is being created with 1681 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1682 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1683 state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1684 included in pname:pDynamicState->pDynamicStates, 1685 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.height 1686 must: be a power-of-two value 1687 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04498]] 1688 If the pipeline is being created with 1689 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1690 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1691 state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1692 included in pname:pDynamicState->pDynamicStates, 1693 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.width 1694 must: be less than or equal to `4` 1695 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04499]] 1696 If the pipeline is being created with 1697 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1698 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1699 state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1700 included in pname:pDynamicState->pDynamicStates, 1701 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.height 1702 must: be less than or equal to `4` 1703 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04500]] 1704 If the pipeline is being created with 1705 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1706 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1707 state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1708 included in pname:pDynamicState->pDynamicStates, and the 1709 <<features-pipelineFragmentShadingRate, 1710 pname:pipelineFragmentShadingRate feature>> is not enabled, 1711 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.width 1712 and 1713 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.height 1714 must: both be equal to `1` 1715 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04501]] 1716 If the pipeline is being created with 1717 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1718 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1719 state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1720 included in pname:pDynamicState->pDynamicStates, and the 1721 <<features-primitiveFragmentShadingRate, 1722 pname:primitiveFragmentShadingRate feature>> is not enabled, 1723 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:combinerOps[0] 1724 must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR 1725 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04502]] 1726 If the pipeline is being created with 1727 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1728 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1729 state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1730 included in pname:pDynamicState->pDynamicStates, and the 1731 <<features-attachmentFragmentShadingRate, 1732 pname:attachmentFragmentShadingRate feature>> is not enabled, 1733 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:combinerOps[1] 1734 must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR 1735ifdef::VK_EXT_extended_dynamic_state[] 1736 * [[VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04503]] 1737 If the pipeline is being created with 1738 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1739 state>> and the 1740 <<limits-primitiveFragmentShadingRateWithMultipleViewports, 1741 pname:primitiveFragmentShadingRateWithMultipleViewports>> limit is not 1742 supported, ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT is not 1743 included in pname:pDynamicState->pDynamicStates, and 1744 slink:VkPipelineViewportStateCreateInfo::pname:viewportCount is greater 1745 than `1`, entry points specified in pname:pStages must: not write to the 1746 code:PrimitiveShadingRateKHR built-in 1747endif::VK_EXT_extended_dynamic_state[] 1748 * [[VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04504]] 1749 If the pipeline is being created with 1750 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1751 state>> and the 1752 <<limits-primitiveFragmentShadingRateWithMultipleViewports, 1753 pname:primitiveFragmentShadingRateWithMultipleViewports>> limit is not 1754 supported, and entry points specified in pname:pStages write to the 1755 code:ViewportIndex built-in, they must: not also write to the 1756 code:PrimitiveShadingRateKHR built-in 1757ifdef::VK_NV_viewport_array2[] 1758 * [[VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04505]] 1759 If the pipeline is being created with 1760 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1761 state>> and the 1762 <<limits-primitiveFragmentShadingRateWithMultipleViewports, 1763 pname:primitiveFragmentShadingRateWithMultipleViewports>> limit is not 1764 supported, and entry points specified in pname:pStages write to the 1765 code:ViewportMaskNV built-in, they must: not also write to the 1766 code:PrimitiveShadingRateKHR built-in 1767endif::VK_NV_viewport_array2[] 1768 * [[VUID-VkGraphicsPipelineCreateInfo-fragmentShadingRateNonTrivialCombinerOps-04506]] 1769 If the pipeline is being created with 1770 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1771 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1772 state>>, the <<limits-fragmentShadingRateNonTrivialCombinerOps, 1773 pname:fragmentShadingRateNonTrivialCombinerOps>> limit is not supported, 1774 and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in 1775 pname:pDynamicState->pDynamicStates, elements of 1776 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:combinerOps 1777 must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or 1778 ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR 1779endif::VK_KHR_fragment_shading_rate[] 1780ifdef::VK_NV_fragment_shading_rate_enums[] 1781 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04569]] 1782 If the pipeline is being created with 1783 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1784 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1785 state>>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1786 included in pname:pDynamicState->pDynamicStates, and the 1787 <<features-fragmentShadingRateEnums, pname:fragmentShadingRateEnums 1788 feature>> is not enabled, 1789 slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:shadingRateType 1790 must: be equal to ename:VK_FRAGMENT_SHADING_RATE_TYPE_FRAGMENT_SIZE_NV 1791 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04570]] 1792 If the pipeline is being created with 1793 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1794 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1795 state>>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1796 included in pname:pDynamicState->pDynamicStates, and the 1797 <<features-pipelineFragmentShadingRate, 1798 pname:pipelineFragmentShadingRate feature>> is not enabled, 1799 slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:shadingRate 1800 must: be equal to 1801 ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NV 1802 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04571]] 1803 If the pipeline is being created with 1804 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1805 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1806 state>>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1807 included in pname:pDynamicState->pDynamicStates, and the 1808 <<features-primitiveFragmentShadingRate, 1809 pname:primitiveFragmentShadingRate feature>> is not enabled, 1810 slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:combinerOps[0] 1811 must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR 1812 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04572]] 1813 If the pipeline is being created with 1814 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1815 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1816 state>>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not 1817 included in pname:pDynamicState->pDynamicStates, and the 1818 <<features-attachmentFragmentShadingRate, 1819 pname:attachmentFragmentShadingRate feature>> is not enabled, 1820 slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:combinerOps[1] 1821 must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR 1822 * [[VUID-VkGraphicsPipelineCreateInfo-fragmentShadingRateNonTrivialCombinerOps-04573]] 1823 If the pipeline is being created with 1824 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1825 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1826 state>>, and the <<limits-fragmentShadingRateNonTrivialCombinerOps, 1827 pname:fragmentShadingRateNonTrivialCombinerOps>> limit is not supported 1828 and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in 1829 pname:pDynamicState->pDynamicStates, elements of 1830 slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:combinerOps 1831 must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or 1832 ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR 1833 * [[VUID-VkGraphicsPipelineCreateInfo-None-04574]] 1834 If the pipeline is being created with 1835 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1836 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1837 state>>, and the <<features-supersampleFragmentShadingRates, 1838 supersampleFragmentShadingRates feature>> is not enabled, 1839 slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:shadingRate 1840 must: not be equal to 1841 ename:VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NV, 1842 ename:VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NV, 1843 ename:VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NV, or 1844 ename:VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NV 1845 * [[VUID-VkGraphicsPipelineCreateInfo-None-04575]] 1846 If the pipeline is being created with 1847 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1848 state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader 1849 state>>, and the <<features-noInvocationFragmentShadingRates, 1850 noInvocationFragmentShadingRates feature>> is not enabled, 1851 slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:shadingRate 1852 must: not be equal to ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV 1853endif::VK_NV_fragment_shading_rate_enums[] 1854ifdef::VK_KHR_ray_tracing_pipeline[] 1855 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03578]] 1856 All elements of the pname:pDynamicStates member of pname:pDynamicState 1857 must: not be ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR 1858endif::VK_KHR_ray_tracing_pipeline[] 1859ifdef::VK_EXT_vertex_input_dynamic_state[] 1860 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04807]] 1861 If the pipeline is being created with 1862 <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader 1863 state>> and the <<features-vertexInputDynamicState, 1864 vertexInputDynamicState>> feature is not enabled, there must: be no 1865 element of the pname:pDynamicStates member of pname:pDynamicState set to 1866 ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT 1867endif::VK_EXT_vertex_input_dynamic_state[] 1868 * [[VUID-VkGraphicsPipelineCreateInfo-None-04893]] 1869 The pipeline must: be created with a 1870 <<pipeline-graphics-subsets-complete, complete set of state>> 1871ifdef::VK_EXT_color_write_enable[] 1872 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04800]] 1873 If the <<features-colorWriteEnable, colorWriteEnable>> feature is not 1874 enabled, there must: be no element of the pname:pDynamicStates member of 1875 pname:pDynamicState set to ename:VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT 1876endif::VK_EXT_color_write_enable[] 1877ifdef::VK_QCOM_render_pass_shader_resolve[] 1878 * [[VUID-VkGraphicsPipelineCreateInfo-rasterizationSamples-04899]] 1879 If the pipeline is being created with fragment shader state, and the 1880 apiext:VK_QCOM_render_pass_shader_resolve extension is enabled, and if 1881 subpass has any input attachments, and if the subpass description 1882 contains ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then the 1883 sample count of the input attachments must: equal 1884 pname:rasterizationSamples 1885 * [[VUID-VkGraphicsPipelineCreateInfo-sampleShadingEnable-04900]] 1886 If the pipeline is being created with fragment shader state, and the 1887 apiext:VK_QCOM_render_pass_shader_resolve extension is enabled, and if 1888 the subpass description contains 1889 ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then 1890 pname:sampleShadingEnable must: be false 1891 * [[VUID-VkGraphicsPipelineCreateInfo-flags-04901]] 1892 If pname:flags includes 1893 ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, then the subpass 1894 must: be the last subpass in a subpass dependency chain 1895 * [[VUID-VkGraphicsPipelineCreateInfo-flags-04902]] 1896 If pname:flags includes 1897 ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if 1898 pname:pResolveAttachments is not `NULL`, then each resolve attachment 1899 must: be ename:VK_ATTACHMENT_UNUSED 1900endif::VK_QCOM_render_pass_shader_resolve[] 1901ifndef::VK_KHR_dynamic_rendering[] 1902 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06051]] 1903 pname:renderPass must: not be dlink:VK_NULL_HANDLE 1904endif::VK_KHR_dynamic_rendering[] 1905ifdef::VK_KHR_dynamic_rendering[] 1906 * [[VUID-VkGraphicsPipelineCreateInfo-dynamicRendering-06052]] 1907 If the <<features-dynamicRendering,pname:dynamicRendering>> feature is 1908 not enabled, pname:renderPass must: not be dlink:VK_NULL_HANDLE 1909 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06053]] 1910 If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being 1911 created with <<pipeline-graphics-subsets-fragment-shader, fragment 1912 shader state>>, and either of 1913 slink:VkPipelineRenderingCreateInfoKHR::depthAttachmentFormat or 1914 slink:VkPipelineRenderingCreateInfoKHR::stencilAttachmentFormat are not 1915 ename:VK_FORMAT_UNDEFINED, pname:pDepthStencilState must: be a valid 1916 pointer to a valid slink:VkPipelineDepthStencilStateCreateInfo structure 1917 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06054]] 1918 If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being 1919 created with <<pipeline-graphics-subsets-fragment-output, fragment 1920 output interface state>>, and 1921 slink:VkPipelineRenderingCreateInfoKHR::colorAttachmentCount is not 1922 equal to `0`, pname:pColorBlendState must: be a valid pointer to a valid 1923 slink:VkPipelineColorBlendStateCreateInfo structure 1924 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06055]] 1925 If pname:renderPass is dlink:VK_NULL_HANDLE and the pipeline is being 1926 created with <<pipeline-graphics-subsets-fragment-output, fragment 1927 output interface state>>, pname:pColorBlendState->attachmentCount must: 1928 be equal to slink:VkPipelineRenderingCreateInfoKHR::colorAttachmentCount 1929 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06056]] 1930 If pname:renderPass is dlink:VK_NULL_HANDLE and the pipeline is being 1931 created with <<pipeline-graphics-subsets-fragment-shader, fragment 1932 shader state>> the fragment shader must: not read from any input 1933 attachment 1934ifdef::VK_KHR_multiview,VK_VERSION_1_1[] 1935 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06057]] 1936 If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being 1937 created with <<pipeline-graphics-subsets-pre-rasterization, 1938 pre-rasterization shader state>>, the pname:viewMask member of a 1939 slink:VkPipelineRenderingCreateInfoKHR structure included in the 1940 pname:pNext chain is not `0`, and the 1941 <<features-multiview-tess,pname:multiviewTessellationShader>> feature is 1942 not enabled, then pname:pStages must: not include tessellation shaders 1943 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06058]] 1944 If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being 1945 created with <<pipeline-graphics-subsets-pre-rasterization, 1946 pre-rasterization shader state>>, the pname:viewMask member of a 1947 slink:VkPipelineRenderingCreateInfoKHR structure included in the 1948 pname:pNext chain is not `0`, and the 1949 <<features-multiview-gs,pname:multiviewGeometryShader>> feature is not 1950 enabled, then pname:pStages must: not include a geometry shader 1951 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06059]] 1952 If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being 1953 created with <<pipeline-graphics-subsets-pre-rasterization, 1954 pre-rasterization shader state>>, and the pname:viewMask member of a 1955 slink:VkPipelineRenderingCreateInfoKHR structure included in the 1956 pname:pNext chain is not `0`, shaders in pname:pStages must: not include 1957 variables decorated with the code:Layer built-in decoration in their 1958 interfaces 1959 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06060]] 1960 If the pipeline is being created with 1961 <<pipeline-graphics-subsets-fragment-output, fragment output interface 1962 state>> and pname:renderPass is dlink:VK_NULL_HANDLE, 1963 pname:pColorBlendState->attachmentCount must: be equal to the 1964 pname:colorAttachmentCount member of the 1965 slink:VkPipelineRenderingCreateInfoKHR structure included in the 1966 pname:pNext chain 1967 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06061]] 1968 If the pipeline is being created with 1969 <<pipeline-graphics-subsets-fragment-shader, fragment shader state>> and 1970 pname:renderPass is dlink:VK_NULL_HANDLE, fragment shaders in 1971 pname:pStages must: not include the code:InputAttachment capability 1972 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06062]] 1973 If the pipeline is being created with 1974 <<pipeline-graphics-subsets-fragment-output, fragment output interface 1975 state>> and pname:renderPass is dlink:VK_NULL_HANDLE, for each color 1976 attachment format defined by the pname:pColorAttachmentFormats member of 1977 slink:VkPipelineRenderingCreateInfoKHR, if its 1978 <<potential-format-features,potential format features>> do not contain 1979 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT, then the 1980 pname:blendEnable member of the corresponding element of the 1981 pname:pAttachments member of pname:pColorBlendState must: be 1982 ename:VK_FALSE 1983endif::VK_KHR_multiview,VK_VERSION_1_1[] 1984ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 1985 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06063]] 1986 If the pipeline is being created with 1987 <<pipeline-graphics-subsets-fragment-output, fragment output interface 1988 state>> and pname:renderPass is dlink:VK_NULL_HANDLE, if the pname:pNext 1989 chain includes slink:VkAttachmentSampleCountInfoAMD or 1990 sname:VkAttachmentSampleCountInfoNV, the pname:colorAttachmentCount 1991 member of that structure must: be equal to the value of 1992 slink:VkPipelineRenderingCreateInfoKHR::pname:colorAttachmentCount 1993endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 1994endif::VK_KHR_dynamic_rendering[] 1995**** 1996 1997include::{generated}/validity/structs/VkGraphicsPipelineCreateInfo.txt[] 1998-- 1999 2000ifdef::VK_KHR_dynamic_rendering[] 2001[open,refpage='VkPipelineRenderingCreateInfoKHR',desc='Structure specifying attachment formats',type='structs'] 2002-- 2003The sname:VkPipelineRenderingCreateInfoKHR structure is defined as: 2004 2005include::{generated}/api/structs/VkPipelineRenderingCreateInfoKHR.txt[] 2006 2007 * pname:sType is the type of this structure. 2008 * pname:pNext is `NULL` or a pointer to a structure extending this 2009 structure. 2010 * pname:viewMask is the viewMask used for rendering. 2011 * pname:colorAttachmentCount is the number of entries in 2012 pname:pColorAttachmentFormats 2013 * pname:pColorAttachmentFormats is an array of elink:VkFormat values 2014 defining the format of color attachments used in this pipeline. 2015 * pname:depthAttachmentFormat is a elink:VkFormat value defining the 2016 format of the depth attachment used in this pipeline. 2017 * pname:stencilAttachmentFormat is a elink:VkFormat value defining the 2018 format of the stencil attachment used in this pipeline. 2019 2020When a pipeline is created without a slink:VkRenderPass, if this structure 2021is present in the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo, 2022it specifies the view mask and format of attachments used for rendering. 2023If this structure is not specified, and the pipeline does not include a 2024slink:VkRenderPass, pname:viewMask and pname:colorAttachmentCount are `0`, 2025and pname:depthAttachmentFormat and pname:stencilAttachmentFormat are 2026ename:VK_FORMAT_UNDEFINED. 2027If a graphics pipeline is created with a valid slink:VkRenderPass, 2028parameters of this structure are ignored. 2029 2030If pname:depthAttachmentFormat, pname:stencilAttachmentFormat, or any 2031element of pname:pColorAttachmentFormats is ename:VK_FORMAT_UNDEFINED, it 2032indicates that the corresponding attachment is unused within the render 2033pass. 2034Valid formats indicate that an attachment can: be used - but it is still 2035valid to set the attachment to `NULL` when beginning rendering. 2036 2037.Valid Usage 2038**** 2039 * [[VUID-VkPipelineRenderingCreateInfoKHR-pColorAttachmentFormats-06064]] 2040 If any element of pname:pColorAttachmentFormats is not 2041 ename:VK_FORMAT_UNDEFINED, it must: be a format with 2042 <<potential-format-features, potential format features>> that include 2043 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT 2044 * [[VUID-VkPipelineRenderingCreateInfoKHR-depthAttachmentFormat-06065]] 2045 If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it 2046 must: be a format with <<potential-format-features, potential format 2047 features>> that include 2048 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 2049 * [[VUID-VkPipelineRenderingCreateInfoKHR-stencilAttachmentFormat-06164]] 2050 If pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it 2051 must: be a format with <<potential-format-features, potential format 2052 features>> that include 2053 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 2054 * [[VUID-VkPipelineRenderingCreateInfoKHR-depthAttachmentFormat-06165]] 2055 If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED and 2056 pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, 2057 pname:depthAttachmentFormat must: equal pname:stencilAttachmentFormat 2058 * [[VUID-VkPipelineRenderingCreateInfoKHR-multiview-06066]] 2059 If the <<features-multiview,pname:multiview>> feature is not enabled, 2060 pname:viewMask must: be `0` 2061ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 2062 * [[VUID-VkPipelineRenderingCreateInfoKHR-viewMask-06067]] 2063 The index of the most significant bit in pname:viewMask must: be less 2064 than <<limits-maxMultiviewViewCount,pname:maxMultiviewViewCount>> 2065endif::VK_VERSION_1_1,VK_KHR_multiview[] 2066**** 2067 2068include::{generated}/validity/structs/VkPipelineRenderingCreateInfoKHR.txt[] 2069-- 2070endif::VK_KHR_dynamic_rendering[] 2071 2072[open,refpage='VkPipelineCreateFlagBits',desc='Bitmask controlling how a pipeline is created',type='enums'] 2073-- 2074Possible values of the pname:flags member of 2075slink:VkGraphicsPipelineCreateInfo, 2076ifdef::VK_KHR_ray_tracing_pipeline[slink:VkRayTracingPipelineCreateInfoKHR,] 2077ifdef::VK_NV_ray_tracing[slink:VkRayTracingPipelineCreateInfoNV,] 2078and slink:VkComputePipelineCreateInfo, specifying how a pipeline is created, 2079are: 2080 2081include::{generated}/api/enums/VkPipelineCreateFlagBits.txt[] 2082 2083 * ename:VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT specifies that the 2084 created pipeline will not be optimized. 2085 Using this flag may: reduce the time taken to create the pipeline. 2086 * ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT specifies that the 2087 pipeline to be created is allowed to be the parent of a pipeline that 2088 will be created in a subsequent pipeline creation call. 2089 * ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT specifies that the pipeline to 2090 be created will be a child of a previously created parent pipeline. 2091ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2092ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 2093 * ename:VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT specifies that 2094 any shader input variables decorated as code:ViewIndex will be assigned 2095 values as if they were decorated as code:DeviceIndex. 2096endif::VK_VERSION_1_1,VK_KHR_multiview[] 2097 * ename:VK_PIPELINE_CREATE_DISPATCH_BASE specifies that a compute pipeline 2098 can: be used with flink:vkCmdDispatchBase with a non-zero base 2099 workgroup. 2100endif::VK_VERSION_1_1,VK_KHR_device_group[] 2101ifdef::VK_NV_ray_tracing[] 2102 * ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV specifies that a pipeline 2103 is created with all shaders in the deferred state. 2104 Before using the pipeline the application must: call 2105 flink:vkCompileDeferredNV exactly once on each shader in the pipeline 2106 before using the pipeline. 2107endif::VK_NV_ray_tracing[] 2108ifdef::VK_KHR_pipeline_executable_properties[] 2109 * ename:VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR specifies that the 2110 shader compiler should capture statistics for the pipeline executables 2111 produced by the compile process which can: later be retrieved by calling 2112 flink:vkGetPipelineExecutableStatisticsKHR. 2113 Enabling this flag must: not affect the final compiled pipeline but may: 2114 disable pipeline caching or otherwise affect pipeline creation time. 2115 * ename:VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR 2116 specifies that the shader compiler should capture the internal 2117 representations of pipeline executables produced by the compile process 2118 which can: later be retrieved by calling 2119 flink:vkGetPipelineExecutableInternalRepresentationsKHR. 2120 Enabling this flag must: not affect the final compiled pipeline but may: 2121 disable pipeline caching or otherwise affect pipeline creation time. 2122endif::VK_KHR_pipeline_executable_properties[] 2123ifdef::VK_KHR_pipeline_library[] 2124 * ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR specifies that the pipeline 2125 cannot: be used directly, and instead defines a _pipeline library_ that 2126 can: be combined with other pipelines using the 2127 slink:VkPipelineLibraryCreateInfoKHR structure. 2128ifdef::VK_KHR_ray_tracing_pipeline[] 2129 This is available in ray tracing pipelines. 2130endif::VK_KHR_ray_tracing_pipeline[] 2131endif::VK_KHR_pipeline_library[] 2132ifdef::VK_KHR_ray_tracing_pipeline[] 2133 * ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR 2134 specifies that an any-hit shader will always be present when an any-hit 2135 shader would be executed. 2136 A NULL any-hit shader is an any-hit shader which is effectively 2137 ename:VK_SHADER_UNUSED_KHR, such as from a shader group consisting 2138 entirely of zeros. 2139 * ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR 2140 specifies that a closest hit shader will always be present when a 2141 closest hit shader would be executed. 2142 A NULL closest hit shader is a closest hit shader which is effectively 2143 ename:VK_SHADER_UNUSED_KHR, such as from a shader group consisting 2144 entirely of zeros. 2145 * ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR 2146 specifies that a miss shader will always be present when a miss shader 2147 would be executed. 2148 A NULL miss shader is a miss shader which is effectively 2149 ename:VK_SHADER_UNUSED_KHR, such as from a shader group consisting 2150 entirely of zeros. 2151 * ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR 2152 specifies that an intersection shader will always be present when an 2153 intersection shader would be executed. 2154 A NULL intersection shader is an intersection shader which is 2155 effectively ename:VK_SHADER_UNUSED_KHR, such as from a shader group 2156 consisting entirely of zeros. 2157 * ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR specifies 2158 that triangle primitives will be skipped during traversal using 2159 code:OpTraceRayKHR. 2160 * ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR specifies that 2161 AABB primitives will be skipped during traversal using 2162 code:OpTraceRayKHR. 2163 * ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR 2164 specifies that the shader group handles can: be saved and reused on a 2165 subsequent run (e.g. for trace capture and replay). 2166endif::VK_KHR_ray_tracing_pipeline[] 2167ifdef::VK_NV_device_generated_commands[] 2168 * ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV specifies that the 2169 pipeline can be used in combination with <<device-generated-commands>>. 2170endif::VK_NV_device_generated_commands[] 2171ifdef::VK_EXT_pipeline_creation_cache_control[] 2172 * ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT 2173 specifies that pipeline creation will fail if a compile is required for 2174 creation of a valid slink:VkPipeline object; 2175 ename:VK_PIPELINE_COMPILE_REQUIRED_EXT will be returned by pipeline 2176 creation, and the slink:VkPipeline will be set to dlink:VK_NULL_HANDLE. 2177 * When creating multiple pipelines, 2178 ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT specifies that 2179 control will be returned to the application on failure of the 2180 corresponding pipeline rather than continuing to create additional 2181 pipelines. 2182endif::VK_EXT_pipeline_creation_cache_control[] 2183ifdef::VK_NV_ray_tracing_motion_blur[] 2184 * ename:VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV specifies that 2185 the pipeline is allowed to use code:OpTraceRayMotionNV. 2186endif::VK_NV_ray_tracing_motion_blur[] 2187ifdef::VK_KHR_dynamic_rendering[] 2188ifdef::VK_KHR_fragment_shading_rate[] 2189 * ename:VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 2190 specifies that the pipeline will be used with a fragment shading rate 2191 attachment. 2192endif::VK_KHR_fragment_shading_rate[] 2193ifdef::VK_EXT_fragment_density_map[] 2194 * ename:VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT 2195 specifies that the pipeline will be used with a fragment density map 2196 attachment. 2197endif::VK_EXT_fragment_density_map[] 2198endif::VK_KHR_dynamic_rendering[] 2199 2200It is valid to set both ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT and 2201ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT. 2202This allows a pipeline to be both a parent and possibly a child in a 2203pipeline hierarchy. 2204See <<pipelines-pipeline-derivatives,Pipeline Derivatives>> for more 2205information. 2206-- 2207 2208[open,refpage='VkPipelineCreateFlags',desc='Bitmask of VkPipelineCreateFlagBits',type='flags'] 2209-- 2210include::{generated}/api/flags/VkPipelineCreateFlags.txt[] 2211 2212tname:VkPipelineCreateFlags is a bitmask type for setting a mask of zero or 2213more elink:VkPipelineCreateFlagBits. 2214-- 2215 2216[open,refpage='VkPipelineDynamicStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline dynamic state',type='structs'] 2217-- 2218The sname:VkPipelineDynamicStateCreateInfo structure is defined as: 2219 2220include::{generated}/api/structs/VkPipelineDynamicStateCreateInfo.txt[] 2221 2222 * pname:sType is the type of this structure. 2223 * pname:pNext is `NULL` or a pointer to a structure extending this 2224 structure. 2225 * pname:flags is reserved for future use. 2226 * pname:dynamicStateCount is the number of elements in the 2227 pname:pDynamicStates array. 2228 * pname:pDynamicStates is a pointer to an array of elink:VkDynamicState 2229 values specifying which pieces of pipeline state will use the values 2230 from dynamic state commands rather than from pipeline state creation 2231 information. 2232 2233.Valid Usage 2234**** 2235 * [[VUID-VkPipelineDynamicStateCreateInfo-pDynamicStates-01442]] 2236 Each element of pname:pDynamicStates must: be unique 2237**** 2238 2239include::{generated}/validity/structs/VkPipelineDynamicStateCreateInfo.txt[] 2240-- 2241 2242[open,refpage='VkPipelineDynamicStateCreateFlags',desc='Reserved for future use',type='flags'] 2243-- 2244include::{generated}/api/flags/VkPipelineDynamicStateCreateFlags.txt[] 2245 2246tname:VkPipelineDynamicStateCreateFlags is a bitmask type for setting a 2247mask, but is currently reserved for future use. 2248-- 2249 2250[open,refpage='VkDynamicState',desc='Indicate which dynamic state is taken from dynamic state commands',type='enums'] 2251-- 2252The source of different pieces of dynamic state is specified by the 2253slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates property of the 2254currently active pipeline, each of whose elements must: be one of the 2255values: 2256 2257include::{generated}/api/enums/VkDynamicState.txt[] 2258 2259 * ename:VK_DYNAMIC_STATE_VIEWPORT specifies that the pname:pViewports 2260 state in slink:VkPipelineViewportStateCreateInfo will be ignored and 2261 must: be set dynamically with flink:vkCmdSetViewport before any drawing 2262 commands. 2263 The number of viewports used by a pipeline is still specified by the 2264 pname:viewportCount member of slink:VkPipelineViewportStateCreateInfo. 2265 * ename:VK_DYNAMIC_STATE_SCISSOR specifies that the pname:pScissors state 2266 in slink:VkPipelineViewportStateCreateInfo will be ignored and must: be 2267 set dynamically with flink:vkCmdSetScissor before any drawing commands. 2268 The number of scissor rectangles used by a pipeline is still specified 2269 by the pname:scissorCount member of 2270 slink:VkPipelineViewportStateCreateInfo. 2271 * ename:VK_DYNAMIC_STATE_LINE_WIDTH specifies that the pname:lineWidth 2272 state in slink:VkPipelineRasterizationStateCreateInfo will be ignored 2273 and must: be set dynamically with flink:vkCmdSetLineWidth before any 2274 drawing commands that generate line primitives for the rasterizer. 2275 * ename:VK_DYNAMIC_STATE_DEPTH_BIAS specifies that the 2276 pname:depthBiasConstantFactor, pname:depthBiasClamp and 2277 pname:depthBiasSlopeFactor states in 2278 slink:VkPipelineRasterizationStateCreateInfo will be ignored and must: 2279 be set dynamically with flink:vkCmdSetDepthBias before any draws are 2280 performed with pname:depthBiasEnable in 2281 slink:VkPipelineRasterizationStateCreateInfo set to ename:VK_TRUE. 2282 * ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS specifies that the 2283 pname:blendConstants state in slink:VkPipelineColorBlendStateCreateInfo 2284 will be ignored and must: be set dynamically with 2285 flink:vkCmdSetBlendConstants before any draws are performed with a 2286 pipeline state with sname:VkPipelineColorBlendAttachmentState member 2287 pname:blendEnable set to ename:VK_TRUE and any of the blend functions 2288 using a constant blend color. 2289 * ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS specifies that the 2290 pname:minDepthBounds and pname:maxDepthBounds states of 2291 slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be 2292 set dynamically with flink:vkCmdSetDepthBounds before any draws are 2293 performed with a pipeline state with 2294 slink:VkPipelineDepthStencilStateCreateInfo member 2295 pname:depthBoundsTestEnable set to ename:VK_TRUE. 2296 * ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK specifies that the 2297 pname:compareMask state in slink:VkPipelineDepthStencilStateCreateInfo 2298 for both pname:front and pname:back will be ignored and must: be set 2299 dynamically with flink:vkCmdSetStencilCompareMask before any draws are 2300 performed with a pipeline state with 2301 slink:VkPipelineDepthStencilStateCreateInfo member 2302 pname:stencilTestEnable set to ename:VK_TRUE 2303 * ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK specifies that the 2304 pname:writeMask state in slink:VkPipelineDepthStencilStateCreateInfo for 2305 both pname:front and pname:back will be ignored and must: be set 2306 dynamically with flink:vkCmdSetStencilWriteMask before any draws are 2307 performed with a pipeline state with 2308 slink:VkPipelineDepthStencilStateCreateInfo member 2309 pname:stencilTestEnable set to ename:VK_TRUE 2310 * ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE specifies that the 2311 pname:reference state in slink:VkPipelineDepthStencilStateCreateInfo for 2312 both pname:front and pname:back will be ignored and must: be set 2313 dynamically with flink:vkCmdSetStencilReference before any draws are 2314 performed with a pipeline state with 2315 slink:VkPipelineDepthStencilStateCreateInfo member 2316 pname:stencilTestEnable set to ename:VK_TRUE 2317ifdef::VK_NV_clip_space_w_scaling[] 2318 * ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV specifies that the 2319 pname:pViewportScalings state in 2320 slink:VkPipelineViewportWScalingStateCreateInfoNV will be ignored and 2321 must: be set dynamically with flink:vkCmdSetViewportWScalingNV before 2322 any draws are performed with a pipeline state with 2323 slink:VkPipelineViewportWScalingStateCreateInfoNV member 2324 pname:viewportScalingEnable set to ename:VK_TRUE 2325endif::VK_NV_clip_space_w_scaling[] 2326ifdef::VK_EXT_discard_rectangles[] 2327 * ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT specifies that the 2328 pname:pDiscardRectangles state in 2329 slink:VkPipelineDiscardRectangleStateCreateInfoEXT will be ignored and 2330 must: be set dynamically with flink:vkCmdSetDiscardRectangleEXT before 2331 any draw or clear commands. 2332 The elink:VkDiscardRectangleModeEXT and the number of active discard 2333 rectangles is still specified by the pname:discardRectangleMode and 2334 pname:discardRectangleCount members of 2335 slink:VkPipelineDiscardRectangleStateCreateInfoEXT. 2336endif::VK_EXT_discard_rectangles[] 2337ifdef::VK_EXT_sample_locations[] 2338 * ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT specifies that the 2339 pname:sampleLocationsInfo state in 2340 slink:VkPipelineSampleLocationsStateCreateInfoEXT will be ignored and 2341 must: be set dynamically with flink:vkCmdSetSampleLocationsEXT before 2342 any draw or clear commands. 2343 Enabling custom sample locations is still indicated by the 2344 pname:sampleLocationsEnable member of 2345 slink:VkPipelineSampleLocationsStateCreateInfoEXT. 2346endif::VK_EXT_sample_locations[] 2347ifdef::VK_NV_scissor_exclusive[] 2348 * ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV specifies that the 2349 pname:pExclusiveScissors state in 2350 slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV will be 2351 ignored and must: be set dynamically with 2352 flink:vkCmdSetExclusiveScissorNV before any drawing commands. 2353 The number of exclusive scissor rectangles used by a pipeline is still 2354 specified by the pname:exclusiveScissorCount member of 2355 slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV. 2356endif::VK_NV_scissor_exclusive[] 2357ifdef::VK_NV_shading_rate_image[] 2358 * ename:VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV specifies that 2359 the pname:pShadingRatePalettes state in 2360 slink:VkPipelineViewportShadingRateImageStateCreateInfoNV will be 2361 ignored and must: be set dynamically with 2362 flink:vkCmdSetViewportShadingRatePaletteNV before any drawing commands. 2363 * ename:VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV specifies that 2364 the coarse sample order state in 2365 slink:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV will be 2366 ignored and must: be set dynamically with 2367 flink:vkCmdSetCoarseSampleOrderNV before any drawing commands. 2368endif::VK_NV_shading_rate_image[] 2369ifdef::VK_EXT_line_rasterization[] 2370 * ename:VK_DYNAMIC_STATE_LINE_STIPPLE_EXT specifies that the 2371 pname:lineStippleFactor and pname:lineStipplePattern state in 2372 slink:VkPipelineRasterizationLineStateCreateInfoEXT will be ignored and 2373 must: be set dynamically with flink:vkCmdSetLineStippleEXT before any 2374 draws are performed with a pipeline state with 2375 slink:VkPipelineRasterizationLineStateCreateInfoEXT member 2376 pname:stippledLineEnable set to ename:VK_TRUE. 2377endif::VK_EXT_line_rasterization[] 2378ifdef::VK_EXT_extended_dynamic_state[] 2379 * ename:VK_DYNAMIC_STATE_CULL_MODE_EXT specifies that the pname:cullMode 2380 state in slink:VkPipelineRasterizationStateCreateInfo will be ignored 2381 and must: be set dynamically with flink:vkCmdSetCullModeEXT before any 2382 drawing commands. 2383 * ename:VK_DYNAMIC_STATE_FRONT_FACE_EXT specifies that the pname:frontFace 2384 state in slink:VkPipelineRasterizationStateCreateInfo will be ignored 2385 and must: be set dynamically with flink:vkCmdSetFrontFaceEXT before any 2386 drawing commands. 2387 * ename:VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT specifies that the 2388 pname:topology state in slink:VkPipelineInputAssemblyStateCreateInfo 2389 only specifies the <<drawing-primitive-topology-class, topology class>>, 2390 and the specific topology order and adjacency must: be set dynamically 2391 with flink:vkCmdSetPrimitiveTopologyEXT before any drawing commands. 2392 * ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT specifies that the 2393 pname:viewportCount and pname:pViewports state in 2394 slink:VkPipelineViewportStateCreateInfo will be ignored and must: be set 2395 dynamically with flink:vkCmdSetViewportWithCountEXT before any draw 2396 call. 2397 * ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT specifies that the 2398 pname:scissorCount and pname:pScissors state in 2399 slink:VkPipelineViewportStateCreateInfo will be ignored and must: be set 2400 dynamically with flink:vkCmdSetScissorWithCountEXT before any draw call. 2401 * ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE_EXT specifies that 2402 the pname:stride state in slink:VkVertexInputBindingDescription will be 2403 ignored and must: be set dynamically with 2404 flink:vkCmdBindVertexBuffers2EXT before any draw call. 2405 * ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT specifies that the 2406 pname:depthTestEnable state in 2407 slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be 2408 set dynamically with flink:vkCmdSetDepthTestEnableEXT before any draw 2409 call. 2410 * ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT specifies that the 2411 pname:depthWriteEnable state in 2412 slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be 2413 set dynamically with flink:vkCmdSetDepthWriteEnableEXT before any draw 2414 call. 2415 * ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT specifies that the 2416 pname:depthCompareOp state in 2417 slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be 2418 set dynamically with flink:vkCmdSetDepthCompareOpEXT before any draw 2419 call. 2420 * ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT specifies that the 2421 pname:depthBoundsTestEnable state in 2422 slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be 2423 set dynamically with flink:vkCmdSetDepthBoundsTestEnableEXT before any 2424 draw call. 2425 * ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT specifies that the 2426 pname:stencilTestEnable state in 2427 slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be 2428 set dynamically with flink:vkCmdSetStencilTestEnableEXT before any draw 2429 call. 2430 * ename:VK_DYNAMIC_STATE_STENCIL_OP_EXT specifies that the pname:failOp, 2431 pname:passOp, pname:depthFailOp, and pname:compareOp states in 2432 sname:VkPipelineDepthStencilStateCreateInfo for both pname:front and 2433 pname:back will be ignored and must: be set dynamically with 2434 flink:vkCmdSetStencilOpEXT before any draws are performed with a 2435 pipeline state with sname:VkPipelineDepthStencilStateCreateInfo member 2436 pname:stencilTestEnable set to ename:VK_TRUE 2437endif::VK_EXT_extended_dynamic_state[] 2438ifdef::VK_EXT_extended_dynamic_state2[] 2439 * ename:VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT specifies that the 2440 pname:patchControlPoints state in 2441 slink:VkPipelineTessellationStateCreateInfo will be ignored and must: be 2442 set dynamically with flink:vkCmdSetPatchControlPointsEXT before any 2443 drawing commands. 2444 * ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT specifies that the 2445 pname:rasterizerDiscardEnable state in 2446 slink:VkPipelineRasterizationStateCreateInfo will be ignored and must: 2447 be set dynamically with flink:vkCmdSetRasterizerDiscardEnableEXT before 2448 any drawing commands. 2449 * ename:VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE_EXT specifies that the 2450 pname:depthBiasEnable state in 2451 slink:VkPipelineRasterizationStateCreateInfo will be ignored and must: 2452 be set dynamically with flink:vkCmdSetDepthBiasEnableEXT before any 2453 drawing commands. 2454 * ename:VK_DYNAMIC_STATE_LOGIC_OP_EXT specifies that the pname:logicOp 2455 state in slink:VkPipelineColorBlendStateCreateInfo will be ignored and 2456 must: be set dynamically with flink:vkCmdSetLogicOpEXT before any 2457 drawing commands. 2458 * ename:VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE_EXT specifies that the 2459 pname:primitiveRestartEnable state in 2460 slink:VkPipelineInputAssemblyStateCreateInfo will be ignored and must: 2461 be set dynamically with flink:vkCmdSetPrimitiveRestartEnableEXT before 2462 any drawing commands. 2463endif::VK_EXT_extended_dynamic_state2[] 2464ifdef::VK_KHR_fragment_shading_rate[] 2465 * ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR specifies that state in 2466 slink:VkPipelineFragmentShadingRateStateCreateInfoKHR 2467ifdef::VK_NV_fragment_shading_rate_enums[] 2468 and slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV 2469endif::VK_NV_fragment_shading_rate_enums[] 2470 will be ignored and must: be set dynamically with 2471 flink:vkCmdSetFragmentShadingRateKHR 2472ifdef::VK_NV_fragment_shading_rate_enums[] 2473 or flink:vkCmdSetFragmentShadingRateEnumNV 2474endif::VK_NV_fragment_shading_rate_enums[] 2475 before any drawing commands. 2476endif::VK_KHR_fragment_shading_rate[] 2477ifdef::VK_KHR_ray_tracing_pipeline[] 2478 * ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR specifies 2479 that the default stack size computation for the pipeline will be ignored 2480 and must: be set dynamically with 2481 flink:vkCmdSetRayTracingPipelineStackSizeKHR before any ray tracing 2482 calls are performed. 2483endif::VK_KHR_ray_tracing_pipeline[] 2484ifdef::VK_EXT_vertex_input_dynamic_state[] 2485 * ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT specifies that the 2486 pname:pVertexInputState state will be ignored and must: be set 2487 dynamically with flink:vkCmdSetVertexInputEXT before any drawing 2488 commands 2489endif::VK_EXT_vertex_input_dynamic_state[] 2490ifdef::VK_EXT_color_write_enable[] 2491 * ename:VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT specifies that the 2492 pname:pColorWriteEnables state in 2493 slink:VkPipelineColorWriteCreateInfoEXT will be ignored and must: be set 2494 dynamically with flink:vkCmdSetColorWriteEnableEXT before any draw call. 2495endif::VK_EXT_color_write_enable[] 2496-- 2497 2498 2499=== Valid Combinations of Stages for Graphics Pipelines 2500 2501ifdef::VK_NV_mesh_shader[] 2502The geometric primitive processing can either be handled on a per primitive 2503basis by the vertex, tessellation, and geometry shader stages, or on a per 2504mesh basis using task and mesh shader stages. 2505If the pipeline includes a mesh shader stage, it uses the mesh pipeline, 2506otherwise it uses the primitive pipeline. 2507 2508If a task shader is omitted, the task shading stage is skipped. 2509endif::VK_NV_mesh_shader[] 2510 2511If tessellation shader stages are omitted, the tessellation shading and 2512fixed-function stages of the pipeline are skipped. 2513 2514If a geometry shader is omitted, the geometry shading stage is skipped. 2515 2516If a fragment shader is omitted, fragment color outputs have undefined: 2517values, and the fragment depth value is unmodified. 2518This can: be useful for depth-only rendering. 2519 2520Presence of a shader stage in a pipeline is indicated by including a valid 2521slink:VkPipelineShaderStageCreateInfo with pname:module and pname:pName 2522selecting an entry point from a shader module, where that entry point is 2523valid for the stage specified by pname:stage. 2524 2525Presence of some of the fixed-function stages in the pipeline is implicitly 2526derived from enabled shaders and provided state. 2527For example, the fixed-function tessellator is always present when the 2528pipeline has valid Tessellation Control and Tessellation Evaluation shaders. 2529 2530.For example: 2531 * Depth/stencil-only rendering in a subpass with no color attachments 2532 ** Active Pipeline Shader Stages 2533 *** Vertex Shader 2534 ** Required: Fixed-Function Pipeline Stages 2535 *** slink:VkPipelineVertexInputStateCreateInfo 2536 *** slink:VkPipelineInputAssemblyStateCreateInfo 2537 *** slink:VkPipelineViewportStateCreateInfo 2538 *** slink:VkPipelineRasterizationStateCreateInfo 2539 *** slink:VkPipelineMultisampleStateCreateInfo 2540 *** slink:VkPipelineDepthStencilStateCreateInfo 2541 * Color-only rendering in a subpass with no depth/stencil attachment 2542 ** Active Pipeline Shader Stages 2543 *** Vertex Shader 2544 *** Fragment Shader 2545 ** Required: Fixed-Function Pipeline Stages 2546 *** slink:VkPipelineVertexInputStateCreateInfo 2547 *** slink:VkPipelineInputAssemblyStateCreateInfo 2548 *** slink:VkPipelineViewportStateCreateInfo 2549 *** slink:VkPipelineRasterizationStateCreateInfo 2550 *** slink:VkPipelineMultisampleStateCreateInfo 2551 *** slink:VkPipelineColorBlendStateCreateInfo 2552 * Rendering pipeline with tessellation and geometry shaders 2553 ** Active Pipeline Shader Stages 2554 *** Vertex Shader 2555 *** Tessellation Control Shader 2556 *** Tessellation Evaluation Shader 2557 *** Geometry Shader 2558 *** Fragment Shader 2559 ** Required: Fixed-Function Pipeline Stages 2560 *** slink:VkPipelineVertexInputStateCreateInfo 2561 *** slink:VkPipelineInputAssemblyStateCreateInfo 2562 *** slink:VkPipelineTessellationStateCreateInfo 2563 *** slink:VkPipelineViewportStateCreateInfo 2564 *** slink:VkPipelineRasterizationStateCreateInfo 2565 *** slink:VkPipelineMultisampleStateCreateInfo 2566 *** slink:VkPipelineDepthStencilStateCreateInfo 2567 *** slink:VkPipelineColorBlendStateCreateInfo 2568ifdef::VK_NV_mesh_shader[] 2569 * Rendering pipeline with task and mesh shaders 2570 ** Active Pipeline Shader Stages 2571 *** Task Shader 2572 *** Mesh Shader 2573 *** Fragment Shader 2574 ** Required: Fixed-Function Pipeline Stages 2575 *** slink:VkPipelineViewportStateCreateInfo 2576 *** slink:VkPipelineRasterizationStateCreateInfo 2577 *** slink:VkPipelineMultisampleStateCreateInfo 2578 *** slink:VkPipelineDepthStencilStateCreateInfo 2579 *** slink:VkPipelineColorBlendStateCreateInfo 2580endif::VK_NV_mesh_shader[] 2581 2582 2583ifdef::VK_NV_device_generated_commands[] 2584[[graphics-shadergroups]] 2585=== Graphics Pipeline Shader Groups 2586 2587Graphics pipelines can contain multiple shader groups that can be bound 2588individually. 2589Each shader group behaves as if it was a pipeline using the shader group's 2590state. 2591When the pipeline is bound by regular means, it behaves as if the state of 2592group `0` is active, use flink:vkCmdBindPipelineShaderGroupNV to bind an 2593invidual shader group. 2594 2595The primary purpose of shader groups is allowing the device to bind 2596different pipeline state using <<device-generated-commands>>. 2597 2598[open,refpage='VkGraphicsPipelineShaderGroupsCreateInfoNV',desc='Structure specifying parameters of a newly created multi shader group pipeline',type='structs'] 2599-- 2600The sname:VkGraphicsPipelineShaderGroupsCreateInfoNV structure is defined 2601as: 2602 2603include::{generated}/api/structs/VkGraphicsPipelineShaderGroupsCreateInfoNV.txt[] 2604 2605 * pname:sType is the type of this structure. 2606 * pname:pNext is `NULL` or a pointer to a structure extending this 2607 structure. 2608 * pname:groupCount is the number of elements in the pname:pGroups array. 2609 * pname:pGroups is a pointer to an array of 2610 slink:VkGraphicsShaderGroupCreateInfoNV structures specifying which 2611 state of the original slink:VkGraphicsPipelineCreateInfo each shader 2612 group overrides. 2613 * pname:pipelineCount is the number of elements in the pname:pPipelines 2614 array. 2615 * pname:pPipelines is a pointer to an array of graphics sname:VkPipeline 2616 structures which are referenced within the created pipeline, including 2617 all their shader groups. 2618 2619When referencing shader groups by index, groups defined in the referenced 2620pipelines are treated as if they were defined as additional entries in 2621pname:pGroups. 2622They are appended in the order they appear in the pname:pPipelines array and 2623in the pname:pGroups array when those pipelines were defined. 2624 2625The application must: maintain the lifetime of all such referenced pipelines 2626based on the pipelines that make use of them. 2627 2628.Valid Usage 2629**** 2630 * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-groupCount-02879]] 2631 pname:groupCount must: be at least `1` and as maximum 2632 sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxGraphicsShaderGroupCount 2633 * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-groupCount-02880]] 2634 The sum of pname:groupCount including those groups added from referenced 2635 pname:pPipelines must: also be as maximum 2636 sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxGraphicsShaderGroupCount 2637 * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02881]] 2638 The state of the first element of pname:pGroups must: match its 2639 equivalent within the parent's slink:VkGraphicsPipelineCreateInfo 2640 * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02882]] 2641 Each element of pname:pGroups must: in combination with the rest of the 2642 pipeline state yield a valid state configuration 2643ifndef::VK_NV_mesh_shader[] 2644 * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02883]] 2645 All elements of pname:pGroups must: use the same shader stage 2646 combinations 2647endif::VK_NV_mesh_shader[] 2648ifdef::VK_NV_mesh_shader[] 2649 * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02884]] 2650 All elements of pname:pGroups must: use the same shader stage 2651 combinations unless any mesh shader stage is used, then either 2652 combination of task and mesh or just mesh shader is valid 2653 * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02885]] 2654 Mesh and regular primitive shading stages cannot be mixed across 2655 pname:pGroups 2656endif::VK_NV_mesh_shader[] 2657 * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pPipelines-02886]] 2658 Each element of pname:pPipelines must: have been created with identical 2659 state to the pipeline currently created except the state that can be 2660 overridden by slink:VkGraphicsShaderGroupCreateInfoNV 2661 * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-deviceGeneratedCommands-02887]] 2662 The <<features-deviceGeneratedCommands, 2663 sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>> 2664 feature must: be enabled 2665**** 2666 2667include::{generated}/validity/structs/VkGraphicsPipelineShaderGroupsCreateInfoNV.txt[] 2668-- 2669 2670[open,refpage='VkGraphicsShaderGroupCreateInfoNV',desc='Structure specifying override parameters for each shader group',type='structs'] 2671-- 2672The sname:VkGraphicsShaderGroupCreateInfoNV structure provides the state 2673overrides for each shader group. 2674Each shader group behaves like a pipeline that was created from its state as 2675well as the remaining parent's state. 2676It is defined as: 2677 2678include::{generated}/api/structs/VkGraphicsShaderGroupCreateInfoNV.txt[] 2679 2680 * pname:sType is the type of this structure. 2681 * pname:pNext is `NULL` or a pointer to a structure extending this 2682 structure. 2683 * pname:stageCount is the number of entries in the pname:pStages array. 2684 * pname:pStages is a pointer to an array 2685 slink:VkPipelineShaderStageCreateInfo structures specifying the set of 2686 the shader stages to be included in this shader group. 2687 * pname:pVertexInputState is a pointer to a 2688 slink:VkPipelineVertexInputStateCreateInfo structure. 2689 * pname:pTessellationState is a pointer to a 2690 slink:VkPipelineTessellationStateCreateInfo structure, and is ignored if 2691 the shader group does not include a tessellation control shader stage 2692 and tessellation evaluation shader stage. 2693 2694.Valid Usage 2695**** 2696 * [[VUID-VkGraphicsShaderGroupCreateInfoNV-stageCount-02888]] 2697 For pname:stageCount, the same restrictions as in 2698 slink:VkGraphicsPipelineCreateInfo::pname:stageCount apply 2699 * [[VUID-VkGraphicsShaderGroupCreateInfoNV-pStages-02889]] 2700 For pname:pStages, the same restrictions as in 2701 slink:VkGraphicsPipelineCreateInfo::pname:pStages apply 2702 * [[VUID-VkGraphicsShaderGroupCreateInfoNV-pVertexInputState-02890]] 2703 For pname:pVertexInputState, the same restrictions as in 2704 slink:VkGraphicsPipelineCreateInfo::pname:pVertexInputState apply 2705 * [[VUID-VkGraphicsShaderGroupCreateInfoNV-pTessellationState-02891]] 2706 For pname:pTessellationState, the same restrictions as in 2707 slink:VkGraphicsPipelineCreateInfo::pname:pTessellationState apply 2708**** 2709 2710include::{generated}/validity/structs/VkGraphicsShaderGroupCreateInfoNV.txt[] 2711-- 2712endif::VK_NV_device_generated_commands[] 2713 2714 2715ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 2716[[pipelines-ray-tracing]] 2717== Ray Tracing Pipelines 2718 2719Ray tracing pipelines consist of multiple shader stages, fixed-function 2720traversal stages, and a pipeline layout. 2721 2722[open,refpage='VK_SHADER_UNUSED_KHR',desc='Sentinel for an unused shader index',type='consts',alias='VK_SHADER_UNUSED_NV'] 2723-- 2724ename:VK_SHADER_UNUSED_KHR is a special shader index used to indicate that a 2725ray generation, miss, or callable shader member is not used. 2726 2727include::{generated}/api/enums/VK_SHADER_UNUSED_KHR.txt[] 2728 2729ifdef::VK_NV_ray_tracing[] 2730or the equivalent 2731 2732include::{generated}/api/enums/VK_SHADER_UNUSED_NV.txt[] 2733endif::VK_NV_ray_tracing[] 2734-- 2735 2736ifdef::VK_NV_ray_tracing[] 2737[open,refpage='vkCreateRayTracingPipelinesNV',desc='Creates a new ray tracing pipeline object',type='protos'] 2738-- 2739:refpage: vkCreateRayTracingPipelinesNV 2740 2741To create ray tracing pipelines, call: 2742 2743include::{generated}/api/protos/vkCreateRayTracingPipelinesNV.txt[] 2744 2745 * pname:device is the logical device that creates the ray tracing 2746 pipelines. 2747 * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that 2748 pipeline caching is disabled, or the handle of a valid 2749 <<pipelines-cache,pipeline cache>> object, in which case use of that 2750 cache is enabled for the duration of the command. 2751 * pname:createInfoCount is the length of the pname:pCreateInfos and 2752 pname:pPipelines arrays. 2753 * pname:pCreateInfos is a pointer to an array of 2754 slink:VkRayTracingPipelineCreateInfoNV structures. 2755 * pname:pAllocator controls host memory allocation as described in the 2756 <<memory-allocation, Memory Allocation>> chapter. 2757 * pname:pPipelines is a pointer to an array in which the resulting ray 2758 tracing pipeline objects are returned. 2759 2760.Valid Usage 2761**** 2762include::{chapters}/commonvalidity/create_ray_tracing_pipelines_common.txt[] 2763**** 2764 2765include::{generated}/validity/protos/vkCreateRayTracingPipelinesNV.txt[] 2766-- 2767endif::VK_NV_ray_tracing[] 2768 2769ifdef::VK_KHR_ray_tracing_pipeline[] 2770[open,refpage='vkCreateRayTracingPipelinesKHR',desc='Creates a new ray tracing pipeline object',type='protos'] 2771-- 2772:refpage: vkCreateRayTracingPipelinesKHR 2773 2774To create ray tracing pipelines, call: 2775 2776include::{generated}/api/protos/vkCreateRayTracingPipelinesKHR.txt[] 2777 2778 * pname:device is the logical device that creates the ray tracing 2779 pipelines. 2780 * pname:deferredOperation is dlink:VK_NULL_HANDLE or the handle of a valid 2781 slink:VkDeferredOperationKHR <<deferred-host-operations-requesting, 2782 request deferral>> object for this command. 2783 * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that 2784 pipeline caching is disabled, or the handle of a valid 2785 <<pipelines-cache,pipeline cache>> object, in which case use of that 2786 cache is enabled for the duration of the command. 2787 * pname:createInfoCount is the length of the pname:pCreateInfos and 2788 pname:pPipelines arrays. 2789 * pname:pCreateInfos is a pointer to an array of 2790 slink:VkRayTracingPipelineCreateInfoKHR structures. 2791 * pname:pAllocator controls host memory allocation as described in the 2792 <<memory-allocation, Memory Allocation>> chapter. 2793 * pname:pPipelines is a pointer to an array in which the resulting ray 2794 tracing pipeline objects are returned. 2795 2796The ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS error is returned if the 2797implementation is unable to re-use the shader group handles provided in 2798slink:VkRayTracingShaderGroupCreateInfoKHR::pname:pShaderGroupCaptureReplayHandle 2799when 2800slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay 2801is enabled. 2802 2803.Valid Usage 2804**** 2805include::{chapters}/commonvalidity/create_ray_tracing_pipelines_common.txt[] 2806include::{chapters}/commonvalidity/deferred_operations_common.txt[] 2807 * [[VUID-vkCreateRayTracingPipelinesKHR-rayTracingPipeline-03586]] 2808 The <<features-rayTracingPipeline, pname:rayTracingPipeline>> feature 2809 must: be enabled 2810ifdef::VK_EXT_pipeline_creation_cache_control+VK_KHR_deferred_host_operations[] 2811 * [[VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-03587]] 2812 If pname:deferredOperation is not dlink:VK_NULL_HANDLE, the pname:flags 2813 member of elements of pname:pCreateInfos must: not include 2814 ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT 2815endif::VK_EXT_pipeline_creation_cache_control+VK_KHR_deferred_host_operations[] 2816**** 2817 2818include::{generated}/validity/protos/vkCreateRayTracingPipelinesKHR.txt[] 2819-- 2820endif::VK_KHR_ray_tracing_pipeline[] 2821 2822ifdef::VK_NV_ray_tracing[] 2823[open,refpage='VkRayTracingPipelineCreateInfoNV',desc='Structure specifying parameters of a newly created ray tracing pipeline',type='structs'] 2824-- 2825:refpage: VkRayTracingPipelineCreateInfoNV 2826 2827The sname:VkRayTracingPipelineCreateInfoNV structure is defined as: 2828 2829include::{generated}/api/structs/VkRayTracingPipelineCreateInfoNV.txt[] 2830 2831 * pname:sType is the type of this structure. 2832 * pname:pNext is `NULL` or a pointer to a structure extending this 2833 structure. 2834 * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying 2835 how the pipeline will be generated. 2836 * pname:stageCount is the number of entries in the pname:pStages array. 2837 * pname:pStages is a pointer to an array of 2838 slink:VkPipelineShaderStageCreateInfo structures specifying the set of 2839 the shader stages to be included in the ray tracing pipeline. 2840 * pname:groupCount is the number of entries in the pname:pGroups array. 2841 * pname:pGroups is a pointer to an array of 2842 slink:VkRayTracingShaderGroupCreateInfoNV structures describing the set 2843 of the shader stages to be included in each shader group in the ray 2844 tracing pipeline. 2845 * pname:maxRecursionDepth is the <<ray-tracing-recursion-depth, maximum 2846 recursion depth>> of shaders executed by this pipeline. 2847 * pname:layout is the description of binding locations used by both the 2848 pipeline and descriptor sets used with the pipeline. 2849 * pname:basePipelineHandle is a pipeline to derive from. 2850 * pname:basePipelineIndex is an index into the pname:pCreateInfos 2851 parameter to use as a pipeline to derive from. 2852 2853The parameters pname:basePipelineHandle and pname:basePipelineIndex are 2854described in more detail in <<pipelines-pipeline-derivatives,Pipeline 2855Derivatives>>. 2856 2857.Valid Usage 2858**** 2859include::{chapters}/commonvalidity/ray_tracing_pipeline_create_info_common.txt[] 2860 * [[VUID-VkRayTracingPipelineCreateInfoNV-stage-06232]] 2861 The pname:stage member of at least one element of pname:pStages must: be 2862 ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR 2863ifdef::VK_KHR_pipeline_library[] 2864 * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03456]] 2865 pname:flags must: not include ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR 2866endif::VK_KHR_pipeline_library[] 2867 * [[VUID-VkRayTracingPipelineCreateInfoNV-maxRecursionDepth-03457]] 2868 pname:maxRecursionDepth must: be less than or equal to 2869 slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxRecursionDepth 2870ifdef::VK_KHR_ray_tracing_pipeline[] 2871 * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03458]] 2872 pname:flags must: not include 2873 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR 2874 * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03459]] 2875 pname:flags must: not include 2876 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR 2877 * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03460]] 2878 pname:flags must: not include 2879 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR 2880 * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03461]] 2881 pname:flags must: not include 2882 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR 2883 * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03462]] 2884 pname:flags must: not include 2885 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR 2886 * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03463]] 2887 pname:flags must: not include 2888 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR 2889 * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03588]] 2890 pname:flags must: not include 2891 ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR 2892endif::VK_KHR_ray_tracing_pipeline[] 2893ifdef::VK_NV_ray_tracing_motion_blur[] 2894 * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-04948]] 2895 pname:flags must: not include 2896 ename:VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV 2897endif::VK_NV_ray_tracing_motion_blur[] 2898ifdef::VK_EXT_pipeline_creation_cache_control[] 2899 * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02957]] 2900 pname:flags must: not include both 2901 ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV and 2902 ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT at 2903 the same time 2904endif::VK_EXT_pipeline_creation_cache_control[] 2905**** 2906 2907include::{generated}/validity/structs/VkRayTracingPipelineCreateInfoNV.txt[] 2908-- 2909endif::VK_NV_ray_tracing[] 2910 2911ifdef::VK_KHR_ray_tracing_pipeline[] 2912[open,refpage='VkRayTracingPipelineCreateInfoKHR',desc='Structure specifying parameters of a newly created ray tracing pipeline',type='structs'] 2913-- 2914:refpage: VkRayTracingPipelineCreateInfoKHR 2915 2916The sname:VkRayTracingPipelineCreateInfoKHR structure is defined as: 2917 2918include::{generated}/api/structs/VkRayTracingPipelineCreateInfoKHR.txt[] 2919 2920 * pname:sType is the type of this structure. 2921 * pname:pNext is `NULL` or a pointer to a structure extending this 2922 structure. 2923 * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying 2924 how the pipeline will be generated. 2925 * pname:stageCount is the number of entries in the pname:pStages array. 2926 * pname:pStages is a pointer to an array of pname:stageCount 2927 slink:VkPipelineShaderStageCreateInfo structures describing the set of 2928 the shader stages to be included in the ray tracing pipeline. 2929 * pname:groupCount is the number of entries in the pname:pGroups array. 2930 * pname:pGroups is a pointer to an array of pname:groupCount 2931 slink:VkRayTracingShaderGroupCreateInfoKHR structures describing the set 2932 of the shader stages to be included in each shader group in the ray 2933 tracing pipeline. 2934 * pname:maxPipelineRayRecursionDepth is the <<ray-tracing-recursion-depth, 2935 maximum recursion depth>> of shaders executed by this pipeline. 2936 * pname:pLibraryInfo is a pointer to a 2937 slink:VkPipelineLibraryCreateInfoKHR structure defining pipeline 2938 libraries to include. 2939 * pname:pLibraryInterface is a pointer to a 2940 slink:VkRayTracingPipelineInterfaceCreateInfoKHR structure defining 2941 additional information when using pipeline libraries. 2942 * pname:pDynamicState is a pointer to a 2943 slink:VkPipelineDynamicStateCreateInfo structure, and is used to 2944 indicate which properties of the pipeline state object are dynamic and 2945 can: be changed independently of the pipeline state. 2946 This can: be `NULL`, which means no state in the pipeline is considered 2947 dynamic. 2948 * pname:layout is the description of binding locations used by both the 2949 pipeline and descriptor sets used with the pipeline. 2950 * pname:basePipelineHandle is a pipeline to derive from. 2951 * pname:basePipelineIndex is an index into the pname:pCreateInfos 2952 parameter to use as a pipeline to derive from. 2953 2954The parameters pname:basePipelineHandle and pname:basePipelineIndex are 2955described in more detail in <<pipelines-pipeline-derivatives,Pipeline 2956Derivatives>>. 2957 2958ifdef::VK_KHR_pipeline_library[] 2959When ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR is specified, this pipeline 2960defines a _pipeline library_ which cannot: be bound as a ray tracing 2961pipeline directly. 2962Instead, pipeline libraries define common shaders and shader groups which 2963can: be included in future pipeline creation. 2964 2965If pipeline libraries are included in pname:pLibraryInfo, shaders defined in 2966those libraries are treated as if they were defined as additional entries in 2967pname:pStages, appended in the order they appear in the pname:pLibraries 2968array and in the pname:pStages array when those libraries were defined. 2969 2970When referencing shader groups in order to obtain a shader group handle, 2971groups defined in those libraries are treated as if they were defined as 2972additional entries in pname:pGroups, appended in the order they appear in 2973the pname:pLibraries array and in the pname:pGroups array when those 2974libraries were defined. 2975The shaders these groups reference are set when the pipeline library is 2976created, referencing those specified in the pipeline library, not in the 2977pipeline that includes it. 2978endif::VK_KHR_pipeline_library[] 2979 2980The default stack size for a pipeline if 2981ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR is not provided 2982is computed as described in <<ray-tracing-pipeline-stack, Ray Tracing 2983Pipeline Stack>>. 2984 2985.Valid Usage 2986**** 2987include::{chapters}/commonvalidity/ray_tracing_pipeline_create_info_common.txt[] 2988 * [[VUID-VkRayTracingPipelineCreateInfoKHR-stage-03425]] 2989 If pname:flags does not include 2990 ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, the pname:stage member of at 2991 least one element of pname:pStages, including those implicitly added by 2992 pname:pLibraryInfo, must: be ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR 2993 * [[VUID-VkRayTracingPipelineCreateInfoKHR-maxPipelineRayRecursionDepth-03589]] 2994 pname:maxPipelineRayRecursionDepth must: be less than or equal to 2995 slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR::pname:maxRayRecursionDepth 2996ifdef::VK_KHR_pipeline_library[] 2997 * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03465]] 2998 If pname:flags includes ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, 2999 pname:pLibraryInterface must: not be `NULL` 3000 * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03590]] 3001 If pname:pLibraryInfo is not `NULL` and its pname:libraryCount member is 3002 greater than `0`, its pname:pLibraryInterface member must: not be `NULL` 3003 * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraries-03591]] 3004 Each element of pname:pLibraryInfo->pLibraries must: have been created 3005 with the value of pname:maxPipelineRayRecursionDepth equal to that in 3006 this pipeline 3007 * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03592]] 3008 If pname:pLibraryInfo is not `NULL`, each element of its 3009 pname:pLibraries member must: have been created with a pname:layout that 3010 is compatible with the pname:layout in this pipeline 3011 * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03593]] 3012 If pname:pLibraryInfo is not `NULL`, each element of its 3013 pname:pLibraries member must: have been created with values of the 3014 pname:maxPipelineRayPayloadSize and pname:maxPipelineRayHitAttributeSize 3015 members of pname:pLibraryInterface equal to those in this pipeline 3016 * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03594]] 3017 If pname:flags includes 3018 ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, 3019 each element of pname:pLibraryInfo->pLibraries must: have been created 3020 with the 3021 ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR 3022 bit set 3023 * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04718]] 3024 If pname:flags includes 3025 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR, each element of 3026 pname:pLibraryInfo->pLibraries must: have been created with the 3027 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR bit set 3028 * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04719]] 3029 If pname:flags includes 3030 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR, each 3031 element of pname:pLibraryInfo->pLibraries must: have been created with 3032 the ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR bit set 3033 * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04720]] 3034 If pname:flags includes 3035 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, 3036 each element of pname:pLibraryInfo->pLibraries must: have been created 3037 with the 3038 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR bit 3039 set 3040 * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04721]] 3041 If pname:flags includes 3042 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, 3043 each element of pname:pLibraryInfo->pLibraries must: have been created 3044 with the 3045 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR 3046 bit set 3047 * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04722]] 3048 If pname:flags includes 3049 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, 3050 each element of pname:pLibraryInfo->pLibraries must: have been created 3051 with the 3052 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR 3053 bit set 3054 * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04723]] 3055 If pname:flags includes 3056 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, each 3057 element of pname:pLibraryInfo->pLibraries must: have been created with 3058 the ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR 3059 bit set 3060endif::VK_KHR_pipeline_library[] 3061 * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03595]] 3062 If the `apiext:VK_KHR_pipeline_library` extension is not enabled, 3063 pname:pLibraryInfo and pname:pLibraryInterface must: be `NULL` 3064 * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03470]] 3065 If pname:flags includes 3066 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, 3067 for any element of pname:pGroups with a pname:type of 3068 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or 3069 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the 3070 pname:anyHitShader of that element must: not be 3071 ename:VK_SHADER_UNUSED_KHR 3072 * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03471]] 3073 If pname:flags includes 3074 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, 3075 for any element of pname:pGroups with a pname:type of 3076 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or 3077 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the 3078 pname:closestHitShader of that element must: not be 3079 ename:VK_SHADER_UNUSED_KHR 3080 * [[VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03596]] 3081 If the <<features-rayTraversalPrimitiveCulling, 3082 pname:rayTraversalPrimitiveCulling>> feature is not enabled, pname:flags 3083 must: not include 3084 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR 3085 * [[VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03597]] 3086 If the <<features-rayTraversalPrimitiveCulling, 3087 pname:rayTraversalPrimitiveCulling>> feature is not enabled, pname:flags 3088 must: not include 3089 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR 3090 * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03598]] 3091 If pname:flags includes 3092 ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, 3093 <<features-rayTracingPipelineShaderGroupHandleCaptureReplay, 3094 pname:rayTracingPipelineShaderGroupHandleCaptureReplay>> must: be 3095 enabled 3096 * [[VUID-VkRayTracingPipelineCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplay-03599]] 3097 If 3098 slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay 3099 is ename:VK_TRUE and the pname:pShaderGroupCaptureReplayHandle member of 3100 any element of pname:pGroups is not `NULL`, pname:flags must: include 3101 ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR 3102 * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03600]] 3103 If pname:pLibraryInfo is not `NULL` and its pname:libraryCount is `0`, 3104 pname:stageCount must: not be `0` 3105 * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03601]] 3106 If pname:pLibraryInfo is not `NULL` and its pname:libraryCount is `0`, 3107 pname:groupCount must: not be `0` 3108 * [[VUID-VkRayTracingPipelineCreateInfoKHR-pDynamicStates-03602]] 3109 Any element of the pname:pDynamicStates member of pname:pDynamicState 3110 must: be ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR 3111**** 3112 3113include::{generated}/validity/structs/VkRayTracingPipelineCreateInfoKHR.txt[] 3114-- 3115endif::VK_KHR_ray_tracing_pipeline[] 3116 3117ifdef::VK_NV_ray_tracing[] 3118[open,refpage='VkRayTracingShaderGroupCreateInfoNV',desc='Structure specifying shaders in a shader group',type='structs'] 3119-- 3120:refpage: VkRayTracingShaderGroupCreateInfoNV 3121 3122The sname:VkRayTracingShaderGroupCreateInfoNV structure is defined as: 3123 3124include::{generated}/api/structs/VkRayTracingShaderGroupCreateInfoNV.txt[] 3125 3126 * pname:sType is the type of this structure. 3127 * pname:pNext is `NULL` or a pointer to a structure extending this 3128 structure. 3129 * pname:type is the type of hit group specified in this structure. 3130 * pname:generalShader is the index of the ray generation, miss, or 3131 callable shader from 3132 slink:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if 3133 the shader group has pname:type of 3134 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV, and 3135 ename:VK_SHADER_UNUSED_NV otherwise. 3136 * pname:closestHitShader is the optional index of the closest hit shader 3137 from slink:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group 3138 if the shader group has pname:type of 3139 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or 3140 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, and 3141 ename:VK_SHADER_UNUSED_NV otherwise. 3142 * pname:anyHitShader is the optional index of the any-hit shader from 3143 slink:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if 3144 the shader group has pname:type of 3145 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or 3146 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, and 3147 ename:VK_SHADER_UNUSED_NV otherwise. 3148 * pname:intersectionShader is the index of the intersection shader from 3149 slink:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if 3150 the shader group has pname:type of 3151 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, and 3152 ename:VK_SHADER_UNUSED_NV otherwise. 3153 3154.Valid Usage 3155**** 3156 * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02413]] 3157 If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then 3158 pname:generalShader must: be a valid index into 3159 slink:VkRayTracingPipelineCreateInfoNV::pname:pStages referring to a 3160 shader of ename:VK_SHADER_STAGE_RAYGEN_BIT_NV, 3161 ename:VK_SHADER_STAGE_MISS_BIT_NV, or 3162 ename:VK_SHADER_STAGE_CALLABLE_BIT_NV 3163 * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02414]] 3164 If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then 3165 pname:closestHitShader, pname:anyHitShader, and pname:intersectionShader 3166 must: be ename:VK_SHADER_UNUSED_NV 3167 * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02415]] 3168 If pname:type is 3169 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV then 3170 pname:intersectionShader must: be a valid index into 3171 slink:VkRayTracingPipelineCreateInfoNV::pname:pStages referring to a 3172 shader of ename:VK_SHADER_STAGE_INTERSECTION_BIT_NV 3173 * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02416]] 3174 If pname:type is 3175 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV then 3176 pname:intersectionShader must: be ename:VK_SHADER_UNUSED_NV 3177 * [[VUID-VkRayTracingShaderGroupCreateInfoNV-closestHitShader-02417]] 3178 pname:closestHitShader must: be either ename:VK_SHADER_UNUSED_NV or a 3179 valid index into slink:VkRayTracingPipelineCreateInfoNV::pname:pStages 3180 referring to a shader of ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV 3181 * [[VUID-VkRayTracingShaderGroupCreateInfoNV-anyHitShader-02418]] 3182 pname:anyHitShader must: be either ename:VK_SHADER_UNUSED_NV or a valid 3183 index into slink:VkRayTracingPipelineCreateInfoNV::pname:pStages 3184 referring to a shader of ename:VK_SHADER_STAGE_ANY_HIT_BIT_NV 3185**** 3186 3187include::{generated}/validity/structs/VkRayTracingShaderGroupCreateInfoNV.txt[] 3188-- 3189 3190endif::VK_NV_ray_tracing[] 3191 3192ifdef::VK_KHR_ray_tracing_pipeline[] 3193[open,refpage='VkRayTracingShaderGroupCreateInfoKHR',desc='Structure specifying shaders in a shader group',type='structs'] 3194-- 3195:refpage: VkRayTracingShaderGroupCreateInfoKHR 3196 3197The sname:VkRayTracingShaderGroupCreateInfoKHR structure is defined as: 3198 3199include::{generated}/api/structs/VkRayTracingShaderGroupCreateInfoKHR.txt[] 3200 3201 * pname:sType is the type of this structure. 3202 * pname:pNext is `NULL` or a pointer to a structure extending this 3203 structure. 3204 * pname:type is the type of hit group specified in this structure. 3205 * pname:generalShader is the index of the ray generation, miss, or 3206 callable shader from 3207 slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages in the group if 3208 the shader group has pname:type of 3209 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR, and 3210 ename:VK_SHADER_UNUSED_KHR otherwise. 3211 * pname:closestHitShader is the optional index of the closest hit shader 3212 from slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages in the group 3213 if the shader group has pname:type of 3214 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or 3215 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and 3216 ename:VK_SHADER_UNUSED_KHR otherwise. 3217 * pname:anyHitShader is the optional index of the any-hit shader from 3218 slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages in the group if 3219 the shader group has pname:type of 3220 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or 3221 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and 3222 ename:VK_SHADER_UNUSED_KHR otherwise. 3223 * pname:intersectionShader is the index of the intersection shader from 3224 slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages in the group if 3225 the shader group has pname:type of 3226 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and 3227 ename:VK_SHADER_UNUSED_KHR otherwise. 3228 * pname:pShaderGroupCaptureReplayHandle is `NULL` or a pointer to replay 3229 information for this shader group. 3230 Ignored if 3231 slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay 3232 is ename:VK_FALSE. 3233 3234.Valid Usage 3235**** 3236 * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03474]] 3237 If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR then 3238 pname:generalShader must: be a valid index into 3239 slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages referring to a 3240 shader of ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR, 3241 ename:VK_SHADER_STAGE_MISS_BIT_KHR, or 3242 ename:VK_SHADER_STAGE_CALLABLE_BIT_KHR 3243 * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03475]] 3244 If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR then 3245 pname:closestHitShader, pname:anyHitShader, and pname:intersectionShader 3246 must: be ename:VK_SHADER_UNUSED_KHR 3247 * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03476]] 3248 If pname:type is 3249 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR then 3250 pname:intersectionShader must: be a valid index into 3251 slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages referring to a 3252 shader of ename:VK_SHADER_STAGE_INTERSECTION_BIT_KHR 3253 * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03477]] 3254 If pname:type is 3255 ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR then 3256 pname:intersectionShader must: be ename:VK_SHADER_UNUSED_KHR 3257 * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-closestHitShader-03478]] 3258 pname:closestHitShader must: be either ename:VK_SHADER_UNUSED_KHR or a 3259 valid index into slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages 3260 referring to a shader of ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR 3261 * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-anyHitShader-03479]] 3262 pname:anyHitShader must: be either ename:VK_SHADER_UNUSED_KHR or a valid 3263 index into slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages 3264 referring to a shader of ename:VK_SHADER_STAGE_ANY_HIT_BIT_KHR 3265 * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplayMixed-03603]] 3266 If 3267 slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplayMixed 3268 is ename:VK_FALSE then pname:pShaderGroupCaptureReplayHandle must: not 3269 be provided if it has not been provided on a previous call to ray 3270 tracing pipeline creation 3271 * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplayMixed-03604]] 3272 If 3273 slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplayMixed 3274 is ename:VK_FALSE then the caller must: guarantee that no ray tracing 3275 pipeline creation commands with pname:pShaderGroupCaptureReplayHandle 3276 provided execute simultaneously with ray tracing pipeline creation 3277 commands without pname:pShaderGroupCaptureReplayHandle provided 3278**** 3279 3280include::{generated}/validity/structs/VkRayTracingShaderGroupCreateInfoKHR.txt[] 3281-- 3282endif::VK_KHR_ray_tracing_pipeline[] 3283 3284[open,refpage='VkRayTracingShaderGroupTypeKHR',desc='Shader group types',type='enums',alias='VkRayTracingShaderGroupTypeNV'] 3285-- 3286:refpage: VkRayTracingShaderGroupTypeKHR 3287 3288Possible values of pname:type in sname:VkRayTracingShaderGroupCreateInfoKHR 3289are: 3290 3291include::{generated}/api/enums/VkRayTracingShaderGroupTypeKHR.txt[] 3292 3293ifdef::VK_NV_ray_tracing[] 3294or the equivalent 3295 3296include::{generated}/api/enums/VkRayTracingShaderGroupTypeNV.txt[] 3297endif::VK_NV_ray_tracing[] 3298 3299 * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR indicates a shader 3300 group with a single ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR, 3301 ename:VK_SHADER_STAGE_MISS_BIT_KHR, or 3302 ename:VK_SHADER_STAGE_CALLABLE_BIT_KHR shader in it. 3303 * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR specifies 3304 a shader group that only hits triangles and must: not contain an 3305 intersection shader, only closest hit and any-hit shaders. 3306 * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR 3307 specifies a shader group that only intersects with custom geometry and 3308 must: contain an intersection shader and may: contain closest hit and 3309 any-hit shaders. 3310 3311[NOTE] 3312.Note 3313==== 3314For current group types, the hit group type could be inferred from the 3315presence or absence of the intersection shader, but we provide the type 3316explicitly for future hit groups that do not have that property. 3317==== 3318-- 3319 3320ifdef::VK_KHR_ray_tracing_pipeline[] 3321[open,refpage='VkRayTracingPipelineInterfaceCreateInfoKHR',desc='Structure specifying additional interface information when using libraries',type='structs'] 3322-- 3323:refpage: VkRayTracingPipelineInterfaceCreateInfoKHR 3324 3325The sname:VkRayTracingPipelineInterfaceCreateInfoKHR structure is defined 3326as: 3327 3328include::{generated}/api/structs/VkRayTracingPipelineInterfaceCreateInfoKHR.txt[] 3329 3330 * pname:sType is the type of this structure. 3331 * pname:pNext is `NULL` or a pointer to a structure extending this 3332 structure. 3333 * pname:maxPipelineRayPayloadSize is the maximum payload size in bytes 3334 used by any shader in the pipeline. 3335 * pname:maxPipelineRayHitAttributeSize is the maximum attribute structure 3336 size in bytes used by any shader in the pipeline. 3337 3338pname:maxPipelineRayPayloadSize is calculated as the maximum number of bytes 3339used by any block declared in the code:RayPayloadKHR or 3340code:IncomingRayPayloadKHR storage classes. 3341pname:maxPipelineRayHitAttributeSize is calculated as the maximum number of 3342bytes used by any block declared in the code:HitAttributeKHR storage class. 3343As variables in these storage classes do not have explicit offsets, the size 3344should be calculated as if each variable has a 3345<<interfaces-alignment-requirements, scalar alignment>> equal to the largest 3346scalar alignment of any of the block's members. 3347 3348[NOTE] 3349.Note 3350==== 3351There is no explicit upper limit for pname:maxPipelineRayPayloadSize, but in 3352practice it should be kept as small as possible. 3353Similar to invocation local memory, it must be allocated for each shader 3354invocation and for devices which support many simultaneous invocations, this 3355storage can rapidly be exhausted, resulting in failure. 3356==== 3357 3358.Valid Usage 3359**** 3360 * [[VUID-VkRayTracingPipelineInterfaceCreateInfoKHR-maxPipelineRayHitAttributeSize-03605]] 3361 pname:maxPipelineRayHitAttributeSize must: be less than or equal to 3362 slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR::pname:maxRayHitAttributeSize 3363**** 3364 3365include::{generated}/validity/structs/VkRayTracingPipelineInterfaceCreateInfoKHR.txt[] 3366-- 3367endif::VK_KHR_ray_tracing_pipeline[] 3368 3369[open,refpage='vkGetRayTracingShaderGroupHandlesKHR',desc='Query ray tracing pipeline shader group handles',type='protos',alias='vkGetRayTracingShaderGroupHandlesNV'] 3370-- 3371:refpage: vkGetRayTracingShaderGroupHandlesKHR 3372 3373To query the opaque handles of shaders in the ray tracing pipeline, call: 3374 3375ifdef::VK_KHR_ray_tracing_pipeline[] 3376include::{generated}/api/protos/vkGetRayTracingShaderGroupHandlesKHR.txt[] 3377endif::VK_KHR_ray_tracing_pipeline[] 3378 3379ifdef::VK_KHR_ray_tracing_pipeline+VK_NV_ray_tracing[or the equivalent command] 3380 3381ifdef::VK_NV_ray_tracing[] 3382include::{generated}/api/protos/vkGetRayTracingShaderGroupHandlesNV.txt[] 3383endif::VK_NV_ray_tracing[] 3384 3385 * pname:device is the logical device containing the ray tracing pipeline. 3386 * pname:pipeline is the ray tracing pipeline object containing the 3387 shaders. 3388 * pname:firstGroup is the index of the first group to retrieve a handle 3389 for from the 3390ifdef::VK_KHR_ray_tracing_pipeline[] 3391slink:VkRayTracingPipelineCreateInfoKHR::pname:pGroups 3392endif::VK_KHR_ray_tracing_pipeline[] 3393ifdef::VK_KHR_ray_tracing_pipeline+VK_NV_ray_tracing[or] 3394ifdef::VK_NV_ray_tracing[] 3395slink:VkRayTracingPipelineCreateInfoNV::pname:pGroups 3396endif::VK_NV_ray_tracing[] 3397 array. 3398 * pname:groupCount is the number of shader handles to retrieve. 3399 * pname:dataSize is the size in bytes of the buffer pointed to by 3400 pname:pData. 3401 * pname:pData is a pointer to a user-allocated buffer where the results 3402 will be written. 3403 3404.Valid Usage 3405**** 3406 * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-04619]] 3407 pname:pipeline must: be a ray tracing pipeline 3408 * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-firstGroup-04050]] 3409 pname:firstGroup must: be less than the number of shader groups in 3410 pname:pipeline 3411 * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-firstGroup-02419]] 3412 The sum of pname:firstGroup and pname:groupCount must: be less than or 3413 equal to the number of shader groups in pname:pipeline 3414 * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-dataSize-02420]] 3415 pname:dataSize must: be at least 3416 [eq]#slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR::pname:shaderGroupHandleSize 3417 {times} pname:groupCount# 3418ifdef::VK_KHR_pipeline_library[] 3419 * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-03482]] 3420 pname:pipeline must: have not been created with 3421 ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR 3422endif::VK_KHR_pipeline_library[] 3423**** 3424 3425include::{generated}/validity/protos/vkGetRayTracingShaderGroupHandlesKHR.txt[] 3426-- 3427 3428ifdef::VK_KHR_ray_tracing_pipeline[] 3429[open,refpage='vkGetRayTracingCaptureReplayShaderGroupHandlesKHR',desc='Query ray tracing capture replay pipeline shader group handles',type='protos'] 3430-- 3431:refpage: vkGetRayTracingCaptureReplayShaderGroupHandlesKHR 3432 3433To query the optional capture handle information of shaders in the ray 3434tracing pipeline, call: 3435 3436include::{generated}/api/protos/vkGetRayTracingCaptureReplayShaderGroupHandlesKHR.txt[] 3437 3438 * pname:device is the logical device containing the ray tracing pipeline. 3439 * pname:pipeline is the ray tracing pipeline object containing the 3440 shaders. 3441 * pname:firstGroup is the index of the first group to retrieve a handle 3442 for from the slink:VkRayTracingPipelineCreateInfoKHR::pname:pGroups 3443 array. 3444 * pname:groupCount is the number of shader handles to retrieve. 3445 * pname:dataSize is the size in bytes of the buffer pointed to by 3446 pname:pData. 3447 * pname:pData is a pointer to a user-allocated buffer where the results 3448 will be written. 3449 3450.Valid Usage 3451**** 3452 * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-04620]] 3453 pname:pipeline must: be a ray tracing pipeline 3454 * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-firstGroup-04051]] 3455 pname:firstGroup must: be less than the number of shader groups in 3456 pname:pipeline 3457 * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-firstGroup-03483]] 3458 The sum of pname:firstGroup and pname:groupCount must: be less than or 3459 equal to the number of shader groups in pname:pipeline 3460 * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-dataSize-03484]] 3461 pname:dataSize must: be at least 3462 [eq]#slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR::pname:shaderGroupHandleCaptureReplaySize 3463 {times} pname:groupCount# 3464 * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-rayTracingPipelineShaderGroupHandleCaptureReplay-03606]] 3465 sname:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay 3466 must: be enabled to call this function 3467 * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-03607]] 3468 pname:pipeline must: have been created with a pname:flags that included 3469 ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR 3470**** 3471 3472include::{generated}/validity/protos/vkGetRayTracingCaptureReplayShaderGroupHandlesKHR.txt[] 3473-- 3474endif::VK_KHR_ray_tracing_pipeline[] 3475 3476ifdef::VK_NV_ray_tracing[] 3477Ray tracing pipelines can: contain more shaders than a graphics or compute 3478pipeline, so to allow parallel compilation of shaders within a pipeline, an 3479application can: choose to defer compilation until a later point in time. 3480 3481[open,refpage='vkCompileDeferredNV',desc='Deferred compilation of shaders',type='protos'] 3482-- 3483:refpage: vkCompileDeferredNV 3484 3485To compile a deferred shader in a pipeline call: 3486 3487include::{generated}/api/protos/vkCompileDeferredNV.txt[] 3488 3489 * pname:device is the logical device containing the ray tracing pipeline. 3490 * pname:pipeline is the ray tracing pipeline object containing the 3491 shaders. 3492 * pname:shader is the index of the shader to compile. 3493 3494.Valid Usage 3495**** 3496 * [[VUID-vkCompileDeferredNV-pipeline-04621]] 3497 pname:pipeline must: be a ray tracing pipeline 3498 * [[VUID-vkCompileDeferredNV-pipeline-02237]] 3499 pname:pipeline must: have been created with 3500 ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV 3501 * [[VUID-vkCompileDeferredNV-shader-02238]] 3502 pname:shader must: not have been called as a deferred compile before 3503**** 3504 3505include::{generated}/validity/protos/vkCompileDeferredNV.txt[] 3506-- 3507endif::VK_NV_ray_tracing[] 3508 3509ifdef::VK_KHR_ray_tracing_pipeline[] 3510[open,refpage='vkGetRayTracingShaderGroupStackSizeKHR',desc='Query ray tracing pipeline shader group shader stack size',type='protos'] 3511-- 3512To query the pipeline stack size of shaders in a shader group in the ray 3513tracing pipeline, call: 3514 3515include::{generated}/api/protos/vkGetRayTracingShaderGroupStackSizeKHR.txt[] 3516 3517 * pname:device is the logical device containing the ray tracing pipeline. 3518 * pname:pipeline is the ray tracing pipeline object containing the shaders 3519 groups. 3520 * pname:group is the index of the shader group to query. 3521 * pname:groupShader is the type of shader from the group to query. 3522 3523The return value is the ray tracing pipeline stack size in bytes for the 3524specified shader as called from the specified shader group. 3525 3526.Valid Usage 3527**** 3528 * [[VUID-vkGetRayTracingShaderGroupStackSizeKHR-pipeline-04622]] 3529 pname:pipeline must: be a ray tracing pipeline 3530 * [[VUID-vkGetRayTracingShaderGroupStackSizeKHR-group-03608]] 3531 The value of pname:group must be less than the number of shader groups 3532 in pname:pipeline 3533 * [[VUID-vkGetRayTracingShaderGroupStackSizeKHR-groupShader-03609]] 3534 The shader identified by pname:groupShader in pname:group must: not be 3535 ename:VK_SHADER_UNUSED_KHR 3536**** 3537 3538include::{generated}/validity/protos/vkGetRayTracingShaderGroupStackSizeKHR.txt[] 3539-- 3540 3541[open,refpage='VkShaderGroupShaderKHR',desc='Shader group shaders',type='enums'] 3542-- 3543Possible values of pname:groupShader in 3544flink:vkGetRayTracingShaderGroupStackSizeKHR are: 3545 3546include::{generated}/api/enums/VkShaderGroupShaderKHR.txt[] 3547 3548 * ename:VK_SHADER_GROUP_SHADER_GENERAL_KHR uses the shader specified in 3549 the group with 3550 slink:VkRayTracingShaderGroupCreateInfoKHR::pname:generalShader 3551 * ename:VK_SHADER_GROUP_SHADER_CLOSEST_HIT_KHR uses the shader specified 3552 in the group with 3553 slink:VkRayTracingShaderGroupCreateInfoKHR::pname:closestHitShader 3554 * ename:VK_SHADER_GROUP_SHADER_ANY_HIT_KHR uses the shader specified in 3555 the group with 3556 slink:VkRayTracingShaderGroupCreateInfoKHR::pname:anyHitShader 3557 * ename:VK_SHADER_GROUP_SHADER_INTERSECTION_KHR uses the shader specified 3558 in the group with 3559 slink:VkRayTracingShaderGroupCreateInfoKHR::pname:intersectionShader 3560-- 3561 3562 3563[open,refpage='vkCmdSetRayTracingPipelineStackSizeKHR',desc='Set the stack size dynamically for a ray tracing pipeline',type='protos'] 3564-- 3565:refpage: vkCmdSetRayTracingPipelineStackSizeKHR 3566 3567To <<pipelines-dynamic-state, dynamically set>> the stack size for a ray 3568tracing pipeline, call: 3569 3570include::{generated}/api/protos/vkCmdSetRayTracingPipelineStackSizeKHR.txt[] 3571 3572 * pname:commandBuffer is the command buffer into which the command will be 3573 recorded. 3574 * pname:pipelineStackSize is the stack size to use for subsequent ray 3575 tracing trace commands. 3576 3577This command sets the stack size for subsequent ray tracing commands when 3578the ray tracing pipeline is created with 3579ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR set in 3580slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. 3581Otherwise, the stack size is computed as described in 3582<<ray-tracing-pipeline-stack, Ray Tracing Pipeline Stack>>. 3583 3584.Valid Usage 3585**** 3586 * [[VUID-vkCmdSetRayTracingPipelineStackSizeKHR-pipelineStackSize-03610]] 3587 pname:pipelineStackSize must: be large enough for any dynamic execution 3588 through the shaders in the ray tracing pipeline used by a subsequent 3589 trace call 3590**** 3591include::{generated}/validity/protos/vkCmdSetRayTracingPipelineStackSizeKHR.txt[] 3592-- 3593endif::VK_KHR_ray_tracing_pipeline[] 3594endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 3595 3596 3597[[pipelines-destruction]] 3598== Pipeline Destruction 3599 3600[open,refpage='vkDestroyPipeline',desc='Destroy a pipeline object',type='protos'] 3601-- 3602To destroy a pipeline, call: 3603 3604include::{generated}/api/protos/vkDestroyPipeline.txt[] 3605 3606 * pname:device is the logical device that destroys the pipeline. 3607 * pname:pipeline is the handle of the pipeline to destroy. 3608 * pname:pAllocator controls host memory allocation as described in the 3609 <<memory-allocation, Memory Allocation>> chapter. 3610 3611.Valid Usage 3612**** 3613 * [[VUID-vkDestroyPipeline-pipeline-00765]] 3614 All submitted commands that refer to pname:pipeline must: have completed 3615 execution 3616 * [[VUID-vkDestroyPipeline-pipeline-00766]] 3617 If sname:VkAllocationCallbacks were provided when pname:pipeline was 3618 created, a compatible set of callbacks must: be provided here 3619 * [[VUID-vkDestroyPipeline-pipeline-00767]] 3620 If no sname:VkAllocationCallbacks were provided when pname:pipeline was 3621 created, pname:pAllocator must: be `NULL` 3622**** 3623 3624include::{generated}/validity/protos/vkDestroyPipeline.txt[] 3625-- 3626 3627 3628[[pipelines-multiple]] 3629== Multiple Pipeline Creation 3630 3631Multiple pipelines can: be created simultaneously by passing an array of 3632slink:VkGraphicsPipelineCreateInfo, 3633ifdef::VK_KHR_ray_tracing_pipeline[slink:VkRayTracingPipelineCreateInfoKHR,] 3634ifdef::VK_NV_ray_tracing[slink:VkRayTracingPipelineCreateInfoNV,] 3635or slink:VkComputePipelineCreateInfo structures into the 3636flink:vkCreateGraphicsPipelines, 3637ifdef::VK_KHR_ray_tracing_pipeline[flink:vkCreateRayTracingPipelinesKHR,] 3638ifdef::VK_NV_ray_tracing[flink:vkCreateRayTracingPipelinesNV,] 3639and flink:vkCreateComputePipelines commands, respectively. 3640Applications can: group together similar pipelines to be created in a single 3641call, and implementations are encouraged to look for reuse opportunities 3642within a group-create. 3643 3644When an application attempts to create many pipelines in a single command, 3645it is possible that some subset may: fail creation. 3646In that case, the corresponding entries in the pname:pPipelines output array 3647will be filled with dlink:VK_NULL_HANDLE values. 3648If any pipeline fails creation despite valid arguments (for example, due to 3649out of memory errors), the elink:VkResult code returned by 3650ftext:vkCreate*Pipelines will indicate why. 3651The implementation will attempt to create all pipelines, and only return 3652dlink:VK_NULL_HANDLE values for those that actually failed. 3653 3654ifdef::VK_EXT_pipeline_creation_cache_control[] 3655If creation fails for a pipeline that had 3656ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT set, pipelines at 3657an index in the pname:pPipelines array greater than or equal to that of the 3658failing pipeline must: be set to dlink:VK_NULL_HANDLE. 3659endif::VK_EXT_pipeline_creation_cache_control[] 3660 3661[[pipelines-pipeline-derivatives]] 3662== Pipeline Derivatives 3663 3664A pipeline derivative is a child pipeline created from a parent pipeline, 3665where the child and parent are expected to have much commonality. 3666The goal of derivative pipelines is that they be cheaper to create using the 3667parent as a starting point, and that it be more efficient (on either host or 3668device) to switch/bind between children of the same parent. 3669 3670A derivative pipeline is created by setting the 3671ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag in the 3672stext:Vk*PipelineCreateInfo structure. 3673If this is set, then exactly one of pname:basePipelineHandle or 3674pname:basePipelineIndex members of the structure must: have a valid 3675handle/index, and specifies the parent pipeline. 3676If pname:basePipelineHandle is used, the parent pipeline must: have already 3677been created. 3678If pname:basePipelineIndex is used, then the parent is being created in the 3679same command. 3680dlink:VK_NULL_HANDLE acts as the invalid handle for 3681pname:basePipelineHandle, and -1 is the invalid index for 3682pname:basePipelineIndex. 3683If pname:basePipelineIndex is used, the base pipeline must: appear earlier 3684in the array. 3685The base pipeline must: have been created with the 3686ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set. 3687 3688 3689[[pipelines-cache]] 3690== Pipeline Cache 3691 3692[open,refpage='VkPipelineCache',desc='Opaque handle to a pipeline cache object',type='handles'] 3693-- 3694Pipeline cache objects allow the result of pipeline construction to be 3695reused between pipelines and between runs of an application. 3696Reuse between pipelines is achieved by passing the same pipeline cache 3697object when creating multiple related pipelines. 3698Reuse across runs of an application is achieved by retrieving pipeline cache 3699contents in one run of an application, saving the contents, and using them 3700to preinitialize a pipeline cache on a subsequent run. 3701The contents of the pipeline cache objects are managed by the 3702implementation. 3703Applications can: manage the host memory consumed by a pipeline cache object 3704and control the amount of data retrieved from a pipeline cache object. 3705 3706Pipeline cache objects are represented by sname:VkPipelineCache handles: 3707 3708include::{generated}/api/handles/VkPipelineCache.txt[] 3709-- 3710 3711[[pipelines-cache-create]] 3712=== Creating a Pipeline Cache 3713 3714[open,refpage='vkCreatePipelineCache',desc='Creates a new pipeline cache',type='protos'] 3715-- 3716To create pipeline cache objects, call: 3717 3718include::{generated}/api/protos/vkCreatePipelineCache.txt[] 3719 3720 * pname:device is the logical device that creates the pipeline cache 3721 object. 3722 * pname:pCreateInfo is a pointer to a slink:VkPipelineCacheCreateInfo 3723 structure containing initial parameters for the pipeline cache object. 3724 * pname:pAllocator controls host memory allocation as described in the 3725 <<memory-allocation, Memory Allocation>> chapter. 3726 * pname:pPipelineCache is a pointer to a slink:VkPipelineCache handle in 3727 which the resulting pipeline cache object is returned. 3728 3729[NOTE] 3730.Note 3731==== 3732Applications can: track and manage the total host memory size of a pipeline 3733cache object using the pname:pAllocator. 3734Applications can: limit the amount of data retrieved from a pipeline cache 3735object in fname:vkGetPipelineCacheData. 3736Implementations should: not internally limit the total number of entries 3737added to a pipeline cache object or the total host memory consumed. 3738==== 3739 3740Once created, a pipeline cache can: be passed to the 3741flink:vkCreateGraphicsPipelines 3742ifdef::VK_KHR_ray_tracing_pipeline[flink:vkCreateRayTracingPipelinesKHR,] 3743ifdef::VK_NV_ray_tracing[flink:vkCreateRayTracingPipelinesNV,] 3744and flink:vkCreateComputePipelines commands. 3745If the pipeline cache passed into these commands is not 3746dlink:VK_NULL_HANDLE, the implementation will query it for possible reuse 3747opportunities and update it with new content. 3748The use of the pipeline cache object in these commands is internally 3749synchronized, and the same pipeline cache object can: be used in multiple 3750threads simultaneously. 3751 3752ifdef::VK_EXT_pipeline_creation_cache_control[] 3753If pname:flags of pname:pCreateInfo includes 3754ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT, all commands 3755that modify the returned pipeline cache object must: be 3756<<fundamentals-threadingbehavior,externally synchronized>>. 3757endif::VK_EXT_pipeline_creation_cache_control[] 3758 3759[NOTE] 3760.Note 3761==== 3762Implementations should: make every effort to limit any critical sections to 3763the actual accesses to the cache, which is expected to be significantly 3764shorter than the duration of the ftext:vkCreate*Pipelines commands. 3765==== 3766 3767include::{generated}/validity/protos/vkCreatePipelineCache.txt[] 3768-- 3769 3770[open,refpage='VkPipelineCacheCreateInfo',desc='Structure specifying parameters of a newly created pipeline cache',type='structs'] 3771-- 3772The sname:VkPipelineCacheCreateInfo structure is defined as: 3773 3774include::{generated}/api/structs/VkPipelineCacheCreateInfo.txt[] 3775 3776 * pname:sType is the type of this structure. 3777 * pname:pNext is `NULL` or a pointer to a structure extending this 3778 structure. 3779ifdef::VK_EXT_pipeline_creation_cache_control[] 3780 * pname:flags is a bitmask of elink:VkPipelineCacheCreateFlagBits 3781 specifying the behavior of the pipeline cache. 3782endif::VK_EXT_pipeline_creation_cache_control[] 3783ifndef::VK_EXT_pipeline_creation_cache_control[] 3784 * pname:flags is reserved for future use. 3785endif::VK_EXT_pipeline_creation_cache_control[] 3786 * pname:initialDataSize is the number of bytes in pname:pInitialData. 3787 If pname:initialDataSize is zero, the pipeline cache will initially be 3788 empty. 3789 * pname:pInitialData is a pointer to previously retrieved pipeline cache 3790 data. 3791 If the pipeline cache data is incompatible (as defined below) with the 3792 device, the pipeline cache will be initially empty. 3793 If pname:initialDataSize is zero, pname:pInitialData is ignored. 3794 3795.Valid Usage 3796**** 3797 * [[VUID-VkPipelineCacheCreateInfo-initialDataSize-00768]] 3798 If pname:initialDataSize is not `0`, it must: be equal to the size of 3799 pname:pInitialData, as returned by fname:vkGetPipelineCacheData when 3800 pname:pInitialData was originally retrieved 3801 * [[VUID-VkPipelineCacheCreateInfo-initialDataSize-00769]] 3802 If pname:initialDataSize is not `0`, pname:pInitialData must: have been 3803 retrieved from a previous call to fname:vkGetPipelineCacheData 3804ifdef::VK_EXT_pipeline_creation_cache_control[] 3805 * [[VUID-VkPipelineCacheCreateInfo-pipelineCreationCacheControl-02892]] 3806 If the <<features-pipelineCreationCacheControl, 3807 pname:pipelineCreationCacheControl>> feature is not enabled, pname:flags 3808 must: not include 3809 ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT 3810endif::VK_EXT_pipeline_creation_cache_control[] 3811**** 3812 3813include::{generated}/validity/structs/VkPipelineCacheCreateInfo.txt[] 3814-- 3815 3816[open,refpage='VkPipelineCacheCreateFlags', desc='Bitmask of VkPipelineCreateFlagBits', type='flags'] 3817-- 3818include::{generated}/api/flags/VkPipelineCacheCreateFlags.txt[] 3819 3820ifdef::VK_EXT_pipeline_creation_cache_control[] 3821tname:VkPipelineCacheCreateFlags is a bitmask type for setting a mask of 3822zero or more elink:VkPipelineCacheCreateFlagBits. 3823endif::VK_EXT_pipeline_creation_cache_control[] 3824ifndef::VK_EXT_pipeline_creation_cache_control[] 3825tname:VkPipelineCacheCreateFlags is a bitmask type for setting a mask, but 3826is currently reserved for future use. 3827endif::VK_EXT_pipeline_creation_cache_control[] 3828-- 3829 3830ifdef::VK_EXT_pipeline_creation_cache_control[] 3831[open,refpage='VkPipelineCacheCreateFlagBits',desc='Bitmask specifying the behavior of the pipeline cache',type='enums'] 3832-- 3833Possible values of the pname:flags member of 3834slink:VkPipelineCacheCreateInfo, specifying the behavior of the pipeline 3835cache, are: 3836 3837include::{generated}/api/enums/VkPipelineCacheCreateFlagBits.txt[] 3838 3839 * ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT specifies 3840 that all commands that modify the created slink:VkPipelineCache will be 3841 <<fundamentals-threadingbehavior,externally synchronized>>. 3842 When set, the implementation may: skip any unnecessary processing needed 3843 to support simultaneous modification from multiple threads where 3844 allowed. 3845-- 3846endif::VK_EXT_pipeline_creation_cache_control[] 3847 3848 3849[[pipelines-cache-merge]] 3850=== Merging Pipeline Caches 3851 3852[open,refpage='vkMergePipelineCaches',desc='Combine the data stores of pipeline caches',type='protos'] 3853-- 3854Pipeline cache objects can: be merged using the command: 3855 3856include::{generated}/api/protos/vkMergePipelineCaches.txt[] 3857 3858 * pname:device is the logical device that owns the pipeline cache objects. 3859 * pname:dstCache is the handle of the pipeline cache to merge results 3860 into. 3861 * pname:srcCacheCount is the length of the pname:pSrcCaches array. 3862 * pname:pSrcCaches is a pointer to an array of pipeline cache handles, 3863 which will be merged into pname:dstCache. 3864 The previous contents of pname:dstCache are included after the merge. 3865 3866[NOTE] 3867.Note 3868==== 3869The details of the merge operation are implementation-dependent, but 3870implementations should: merge the contents of the specified pipelines and 3871prune duplicate entries. 3872==== 3873 3874.Valid Usage 3875**** 3876 * [[VUID-vkMergePipelineCaches-dstCache-00770]] 3877 pname:dstCache must: not appear in the list of source caches 3878**** 3879 3880include::{generated}/validity/protos/vkMergePipelineCaches.txt[] 3881-- 3882 3883[[pipelines-cache-retrieval]] 3884=== Retrieving Pipeline Cache Data 3885 3886[open,refpage='vkGetPipelineCacheData',desc='Get the data store from a pipeline cache',type='protos'] 3887-- 3888Data can: be retrieved from a pipeline cache object using the command: 3889 3890include::{generated}/api/protos/vkGetPipelineCacheData.txt[] 3891 3892 * pname:device is the logical device that owns the pipeline cache. 3893 * pname:pipelineCache is the pipeline cache to retrieve data from. 3894 * pname:pDataSize is a pointer to a code:size_t value related to the 3895 amount of data in the pipeline cache, as described below. 3896 * pname:pData is either `NULL` or a pointer to a buffer. 3897 3898If pname:pData is `NULL`, then the maximum size of the data that can: be 3899retrieved from the pipeline cache, in bytes, is returned in pname:pDataSize. 3900Otherwise, pname:pDataSize must: point to a variable set by the user to the 3901size of the buffer, in bytes, pointed to by pname:pData, and on return the 3902variable is overwritten with the amount of data actually written to 3903pname:pData. 3904If pname:pDataSize is less than the maximum size that can: be retrieved by 3905the pipeline cache, at most pname:pDataSize bytes will be written to 3906pname:pData, and ename:VK_INCOMPLETE will be returned instead of 3907ename:VK_SUCCESS, to indicate that not all of the pipeline cache was 3908returned. 3909 3910Any data written to pname:pData is valid and can: be provided as the 3911pname:pInitialData member of the slink:VkPipelineCacheCreateInfo structure 3912passed to fname:vkCreatePipelineCache. 3913 3914Two calls to fname:vkGetPipelineCacheData with the same parameters must: 3915retrieve the same data unless a command that modifies the contents of the 3916cache is called between them. 3917 3918The initial bytes written to pname:pData must: be a header as described in 3919the <<pipelines-cache-header, Pipeline Cache Header>> section. 3920 3921If pname:pDataSize is less than what is necessary to store this header, 3922nothing will be written to pname:pData and zero will be written to 3923pname:pDataSize. 3924 3925include::{generated}/validity/protos/vkGetPipelineCacheData.txt[] 3926-- 3927 3928[[pipelines-cache-header]] 3929=== Pipeline Cache Header 3930 3931Applications can: store the data retrieved from the pipeline cache, and use 3932these data, possibly in a future run of the application, to populate new 3933pipeline cache objects. 3934The results of pipeline compiles, however, may: depend on the vendor ID, 3935device ID, driver version, and other details of the device. 3936To enable applications to detect when previously retrieved data is 3937incompatible with the device, the pipeline cache data must: begin with a 3938valid pipeline cache header. 3939 3940[open,refpage='VkPipelineCacheHeaderVersionOne',desc='Structure describing the layout of the pipeline cache header',type='structs'] 3941-- 3942Version one of the pipeline cache header is defined as: 3943 3944include::{generated}/api/structs/VkPipelineCacheHeaderVersionOne.txt[] 3945 3946 * pname:headerSize is the length in bytes of the pipeline cache header. 3947 * pname:headerVersion is a elink:VkPipelineCacheHeaderVersion enum value 3948 specifying the version of the header. 3949 A consumer of the pipeline cache should: use the cache version to 3950 interpret the remainder of the cache header. 3951 * pname:vendorID is the sname:VkPhysicalDeviceProperties::pname:vendorID 3952 of the implementation. 3953 * pname:deviceID is the sname:VkPhysicalDeviceProperties::pname:deviceID 3954 of the implementation. 3955 * pname:pipelineCacheUUID is the 3956 sname:VkPhysicalDeviceProperties::pname:pipelineCacheUUID of the 3957 implementation. 3958 3959Unlike most structures declared by the Vulkan API, all fields of this 3960structure are written with the least significant byte first, regardless of 3961host byte-order. 3962 3963The C language specification does not define the packing of structure 3964members. 3965This layout assumes tight structure member packing, with members laid out in 3966the order listed in the structure, and the intended size of the structure is 396732 bytes. 3968If a compiler produces code that diverges from that pattern, applications 3969must: employ another method to set values at the correct offsets. 3970 3971.Valid Usage 3972**** 3973 * [[VUID-VkPipelineCacheHeaderVersionOne-headerSize-04967]] 3974 pname:headerSize must: be 32 3975 * [[VUID-VkPipelineCacheHeaderVersionOne-headerVersion-04968]] 3976 pname:headerVersion must: be ename:VK_PIPELINE_CACHE_HEADER_VERSION_ONE 3977**** 3978 3979include::{generated}/validity/structs/VkPipelineCacheHeaderVersionOne.txt[] 3980-- 3981 3982 3983[open,refpage='VkPipelineCacheHeaderVersion',desc='Encode pipeline cache version',type='enums',xrefs='vkCreatePipelineCache vkGetPipelineCacheData'] 3984-- 3985Possible values of the pname:headerVersion value of the pipeline cache 3986header are: 3987 3988include::{generated}/api/enums/VkPipelineCacheHeaderVersion.txt[] 3989 3990 * ename:VK_PIPELINE_CACHE_HEADER_VERSION_ONE specifies version one of the 3991 pipeline cache. 3992-- 3993 3994[[pipelines-cache-destroy]] 3995=== Destroying a Pipeline Cache 3996 3997[open,refpage='vkDestroyPipelineCache',desc='Destroy a pipeline cache object',type='protos'] 3998-- 3999To destroy a pipeline cache, call: 4000 4001include::{generated}/api/protos/vkDestroyPipelineCache.txt[] 4002 4003 * pname:device is the logical device that destroys the pipeline cache 4004 object. 4005 * pname:pipelineCache is the handle of the pipeline cache to destroy. 4006 * pname:pAllocator controls host memory allocation as described in the 4007 <<memory-allocation, Memory Allocation>> chapter. 4008 4009.Valid Usage 4010**** 4011 * [[VUID-vkDestroyPipelineCache-pipelineCache-00771]] 4012 If sname:VkAllocationCallbacks were provided when pname:pipelineCache 4013 was created, a compatible set of callbacks must: be provided here 4014 * [[VUID-vkDestroyPipelineCache-pipelineCache-00772]] 4015 If no sname:VkAllocationCallbacks were provided when pname:pipelineCache 4016 was created, pname:pAllocator must: be `NULL` 4017**** 4018 4019include::{generated}/validity/protos/vkDestroyPipelineCache.txt[] 4020-- 4021 4022 4023[[pipelines-specialization-constants]] 4024== Specialization Constants 4025 4026Specialization constants are a mechanism whereby constants in a SPIR-V 4027module can: have their constant value specified at the time the 4028sname:VkPipeline is created. 4029This allows a SPIR-V module to have constants that can: be modified while 4030executing an application that uses the Vulkan API. 4031 4032[NOTE] 4033.Note 4034==== 4035Specialization constants are useful to allow a compute shader to have its 4036local workgroup size changed at runtime by the user, for example. 4037==== 4038 4039Each slink:VkPipelineShaderStageCreateInfo structure contains a 4040pname:pSpecializationInfo member, which can: be `NULL` to indicate no 4041specialization constants, or point to a sname:VkSpecializationInfo 4042structure. 4043 4044[open,refpage='VkSpecializationInfo',desc='Structure specifying specialization information',type='structs'] 4045-- 4046The sname:VkSpecializationInfo structure is defined as: 4047 4048include::{generated}/api/structs/VkSpecializationInfo.txt[] 4049 4050 * pname:mapEntryCount is the number of entries in the pname:pMapEntries 4051 array. 4052 * pname:pMapEntries is a pointer to an array of 4053 sname:VkSpecializationMapEntry structures which map constant IDs to 4054 offsets in pname:pData. 4055 * pname:dataSize is the byte size of the pname:pData buffer. 4056 * pname:pData contains the actual constant values to specialize with. 4057 4058.Valid Usage 4059**** 4060 * [[VUID-VkSpecializationInfo-offset-00773]] 4061 The pname:offset member of each element of pname:pMapEntries must: be 4062 less than pname:dataSize 4063 * [[VUID-VkSpecializationInfo-pMapEntries-00774]] 4064 The pname:size member of each element of pname:pMapEntries must: be less 4065 than or equal to pname:dataSize minus pname:offset 4066 * [[VUID-VkSpecializationInfo-constantID-04911]] 4067 The pname:constantID value of each element of pname:pMapEntries must: be 4068 unique within pname:pMapEntries 4069**** 4070 4071include::{generated}/validity/structs/VkSpecializationInfo.txt[] 4072-- 4073 4074[open,refpage='VkSpecializationMapEntry',desc='Structure specifying a specialization map entry',type='structs'] 4075-- 4076The sname:VkSpecializationMapEntry structure is defined as: 4077 4078include::{generated}/api/structs/VkSpecializationMapEntry.txt[] 4079 4080 * pname:constantID is the ID of the specialization constant in SPIR-V. 4081 * pname:offset is the byte offset of the specialization constant value 4082 within the supplied data buffer. 4083 * pname:size is the byte size of the specialization constant value within 4084 the supplied data buffer. 4085 4086If a pname:constantID value is not a specialization constant ID used in the 4087shader, that map entry does not affect the behavior of the pipeline. 4088 4089.Valid Usage 4090**** 4091 * [[VUID-VkSpecializationMapEntry-constantID-00776]] 4092 For a pname:constantID specialization constant declared in a shader, 4093 pname:size must: match the byte size of the pname:constantID. 4094 If the specialization constant is of type code:boolean, pname:size must: 4095 be the byte size of basetype:VkBool32 4096**** 4097 4098include::{generated}/validity/structs/VkSpecializationMapEntry.txt[] 4099-- 4100 4101In human readable SPIR-V: 4102 4103[source,glsl] 4104--------------------------------------------------- 4105OpDecorate %x SpecId 13 ; decorate .x component of WorkgroupSize with ID 13 4106OpDecorate %y SpecId 42 ; decorate .y component of WorkgroupSize with ID 42 4107OpDecorate %z SpecId 3 ; decorate .z component of WorkgroupSize with ID 3 4108OpDecorate %wgsize BuiltIn WorkgroupSize ; decorate WorkgroupSize onto constant 4109%i32 = OpTypeInt 32 0 ; declare an unsigned 32-bit type 4110%uvec3 = OpTypeVector %i32 3 ; declare a 3 element vector type of unsigned 32-bit 4111%x = OpSpecConstant %i32 1 ; declare the .x component of WorkgroupSize 4112%y = OpSpecConstant %i32 1 ; declare the .y component of WorkgroupSize 4113%z = OpSpecConstant %i32 1 ; declare the .z component of WorkgroupSize 4114%wgsize = OpSpecConstantComposite %uvec3 %x %y %z ; declare WorkgroupSize 4115--------------------------------------------------- 4116 4117From the above we have three specialization constants, one for each of the 4118x, y & z elements of the WorkgroupSize vector. 4119 4120Now to specialize the above via the specialization constants mechanism: 4121 4122[source,c++] 4123--------------------------------------------------- 4124const VkSpecializationMapEntry entries[] = 4125{ 4126 { 4127 13, // constantID 4128 0 * sizeof(uint32_t), // offset 4129 sizeof(uint32_t) // size 4130 }, 4131 { 4132 42, // constantID 4133 1 * sizeof(uint32_t), // offset 4134 sizeof(uint32_t) // size 4135 }, 4136 { 4137 3, // constantID 4138 2 * sizeof(uint32_t), // offset 4139 sizeof(uint32_t) // size 4140 } 4141}; 4142 4143const uint32_t data[] = { 16, 8, 4 }; // our workgroup size is 16x8x4 4144 4145const VkSpecializationInfo info = 4146{ 4147 3, // mapEntryCount 4148 entries, // pMapEntries 4149 3 * sizeof(uint32_t), // dataSize 4150 data, // pData 4151}; 4152--------------------------------------------------- 4153 4154Then when calling flink:vkCreateComputePipelines, and passing the 4155sname:VkSpecializationInfo we defined as the pname:pSpecializationInfo 4156parameter of slink:VkPipelineShaderStageCreateInfo, we will create a compute 4157pipeline with the runtime specified local workgroup size. 4158 4159Another example would be that an application has a SPIR-V module that has 4160some platform-dependent constants they wish to use. 4161 4162In human readable SPIR-V: 4163 4164// [source,glsl] 4165[source,glsl] 4166--------------------------------------------------- 4167OpDecorate %1 SpecId 0 ; decorate our signed 32-bit integer constant 4168OpDecorate %2 SpecId 12 ; decorate our 32-bit floating-point constant 4169%i32 = OpTypeInt 32 1 ; declare a signed 32-bit type 4170%float = OpTypeFloat 32 ; declare a 32-bit floating-point type 4171%1 = OpSpecConstant %i32 -1 ; some signed 32-bit integer constant 4172%2 = OpSpecConstant %float 0.5 ; some 32-bit floating-point constant 4173--------------------------------------------------- 4174 4175From the above we have two specialization constants, one is a signed 32-bit 4176integer and the second is a 32-bit floating-point value. 4177 4178Now to specialize the above via the specialization constants mechanism: 4179 4180[source,c++] 4181--------------------------------------------------- 4182struct SpecializationData { 4183 int32_t data0; 4184 float data1; 4185}; 4186 4187const VkSpecializationMapEntry entries[] = 4188{ 4189 { 4190 0, // constantID 4191 offsetof(SpecializationData, data0), // offset 4192 sizeof(SpecializationData::data0) // size 4193 }, 4194 { 4195 12, // constantID 4196 offsetof(SpecializationData, data1), // offset 4197 sizeof(SpecializationData::data1) // size 4198 } 4199}; 4200 4201SpecializationData data; 4202data.data0 = -42; // set the data for the 32-bit integer 4203data.data1 = 42.0f; // set the data for the 32-bit floating-point 4204 4205const VkSpecializationInfo info = 4206{ 4207 2, // mapEntryCount 4208 entries, // pMapEntries 4209 sizeof(data), // dataSize 4210 &data, // pData 4211}; 4212--------------------------------------------------- 4213 4214It is legal for a SPIR-V module with specializations to be compiled into a 4215pipeline where no specialization information was provided. 4216SPIR-V specialization constants contain default values such that if a 4217specialization is not provided, the default value will be used. 4218In the examples above, it would be valid for an application to only 4219specialize some of the specialization constants within the SPIR-V module, 4220and let the other constants use their default values encoded within the 4221OpSpecConstant declarations. 4222 4223 4224ifdef::VK_KHR_pipeline_library[] 4225[[pipeline-library]] 4226== Pipeline Libraries 4227 4228A pipeline library is a special pipeline that was created using the 4229ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and cannot be bound, instead it 4230defines a set of pipeline state which can be linked into other pipelines. 4231ifdef::VK_KHR_ray_tracing_pipeline[] 4232For ray tracing pipelines this includes shaders and shader groups. 4233endif::VK_KHR_ray_tracing_pipeline[] 4234The application must: maintain the lifetime of a pipeline library based on 4235the pipelines that link with it. 4236A pipeline library is considered in-use, as long as one of the linking 4237pipelines is in-use. 4238 4239This linkage is achieved by using the following structure within the 4240appropriate creation mechanisms: 4241 4242[open,refpage='VkPipelineLibraryCreateInfoKHR',desc='Structure specifying pipeline libraries to use when creating a pipeline',type='structs'] 4243-- 4244The sname:VkPipelineLibraryCreateInfoKHR structure is defined as: 4245 4246include::{generated}/api/structs/VkPipelineLibraryCreateInfoKHR.txt[] 4247 4248 * pname:sType is the type of this structure. 4249 * pname:pNext is `NULL` or a pointer to a structure extending this 4250 structure. 4251 * pname:libraryCount is the number of pipeline libraries in 4252 pname:pLibraries. 4253 * pname:pLibraries is a pointer to an array of slink:VkPipeline structures 4254 specifying pipeline libraries to use when creating a pipeline. 4255 4256.Valid Usage 4257**** 4258 * [[VUID-VkPipelineLibraryCreateInfoKHR-pLibraries-03381]] 4259 Each element of pname:pLibraries must: have been created with 4260 ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR 4261**** 4262 4263include::{generated}/validity/structs/VkPipelineLibraryCreateInfoKHR.txt[] 4264-- 4265endif::VK_KHR_pipeline_library[] 4266 4267 4268[[pipelines-binding]] 4269== Pipeline Binding 4270 4271[open,refpage='vkCmdBindPipeline',desc='Bind a pipeline object to a command buffer',type='protos'] 4272-- 4273Once a pipeline has been created, it can: be bound to the command buffer 4274using the command: 4275 4276include::{generated}/api/protos/vkCmdBindPipeline.txt[] 4277 4278 * pname:commandBuffer is the command buffer that the pipeline will be 4279 bound to. 4280 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying 4281 to which bind point the pipeline is bound. 4282 Binding one does not disturb the others. 4283 * pname:pipeline is the pipeline to be bound. 4284 4285[[pipeline-bindpoint-commands]] 4286Once bound, a pipeline binding affects subsequent commands that interact 4287with the given pipeline type in the command buffer until a different 4288pipeline of the same type is bound to the bind point. 4289Commands that do not interact with the given pipeline type must: not be 4290affected by the pipeline state. 4291 4292 * The pipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE controls the 4293 behavior of all <<dispatch, dispatching commands>>. 4294 * The pipeline bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS controls the 4295 behavior of all <<drawing, drawing commands>>. 4296ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 4297 * The pipeline bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR 4298 controls the behavior of flink:vkCmdTraceRaysKHR and 4299 flink:vkCmdTraceRaysIndirectKHR. 4300endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 4301ifdef::VK_HUAWEI_subpass_shading[] 4302 * The pipeline bound to 4303 ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI controls the 4304 behavior of flink:vkCmdSubpassShadingHUAWEI. 4305endif::VK_HUAWEI_subpass_shading[] 4306 4307.Valid Usage 4308**** 4309 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-00777]] 4310 If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE, the 4311 sname:VkCommandPool that pname:commandBuffer was allocated from must: 4312 support compute operations 4313 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-00778]] 4314 If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_GRAPHICS, the 4315 sname:VkCommandPool that pname:commandBuffer was allocated from must: 4316 support graphics operations 4317 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-00779]] 4318 If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE, 4319 pname:pipeline must: be a compute pipeline 4320 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-00780]] 4321 If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_GRAPHICS, 4322 pname:pipeline must: be a graphics pipeline 4323 * [[VUID-vkCmdBindPipeline-pipeline-00781]] 4324 If the <<features-variableMultisampleRate,variable multisample rate>> 4325 feature is not supported, pname:pipeline is a graphics pipeline, the 4326 current subpass <<renderpass-noattachments, uses no attachments>>, and 4327 this is not the first call to this function with a graphics pipeline 4328 after transitioning to the current subpass, then the sample count 4329 specified by this pipeline must: match that set in the previous pipeline 4330ifdef::VK_EXT_sample_locations[] 4331 * [[VUID-vkCmdBindPipeline-variableSampleLocations-01525]] 4332 If 4333 slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations 4334 is ename:VK_FALSE, and pname:pipeline is a graphics pipeline created 4335 with a slink:VkPipelineSampleLocationsStateCreateInfoEXT structure 4336 having its pname:sampleLocationsEnable member set to ename:VK_TRUE but 4337 without ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT enabled then the 4338 current render pass instance must: have been begun by specifying a 4339 slink:VkRenderPassSampleLocationsBeginInfoEXT structure whose 4340 pname:pPostSubpassSampleLocations member contains an element with a 4341 pname:subpassIndex matching the current subpass index and the 4342 pname:sampleLocationsInfo member of that element must: match the 4343 pname:sampleLocationsInfo specified in 4344 slink:VkPipelineSampleLocationsStateCreateInfoEXT when the pipeline was 4345 created 4346endif::VK_EXT_sample_locations[] 4347ifdef::VK_EXT_transform_feedback[] 4348 * [[VUID-vkCmdBindPipeline-None-02323]] 4349 This command must: not be recorded when transform feedback is active 4350endif::VK_EXT_transform_feedback[] 4351ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 4352 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-02391]] 4353 If pname:pipelineBindPoint is 4354 ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, the sname:VkCommandPool 4355 that pname:commandBuffer was allocated from must: support compute 4356 operations 4357 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-02392]] 4358 If pname:pipelineBindPoint is 4359 ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, pname:pipeline must: be a 4360 ray tracing pipeline 4361endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 4362ifdef::VK_KHR_pipeline_library[] 4363 * [[VUID-vkCmdBindPipeline-pipeline-03382]] 4364 pname:pipeline must: not have been created with 4365 ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR set 4366endif::VK_KHR_pipeline_library[] 4367ifdef::VK_NV_inherited_viewport_scissor[] 4368 * [[VUID-vkCmdBindPipeline-commandBuffer-04808]] 4369 If pname:commandBuffer is a secondary command buffer with 4370 slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D 4371 enabled and pname:pipelineBindPoint is 4372 ename:VK_PIPELINE_BIND_POINT_GRAPHICS, then the pname:pipeline must: 4373 have been created with ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT or 4374 ename:VK_DYNAMIC_STATE_VIEWPORT, and 4375 ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT or 4376 ename:VK_DYNAMIC_STATE_SCISSOR enabled 4377endif::VK_NV_inherited_viewport_scissor[] 4378ifdef::VK_NV_inherited_viewport_scissor,VK_EXT_discard_rectangles[] 4379 * [[VUID-vkCmdBindPipeline-commandBuffer-04809]] 4380 If pname:commandBuffer is a secondary command buffer with 4381 slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D 4382 enabled and pname:pipelineBindPoint is 4383 ename:VK_PIPELINE_BIND_POINT_GRAPHICS and pname:pipeline was created 4384 with slink:VkPipelineDiscardRectangleStateCreateInfoEXT structure and 4385 its pname:discardRectangleCount member is not `0`, then the pipeline 4386 must: have been created with 4387 ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT enabled 4388endif::VK_NV_inherited_viewport_scissor,VK_EXT_discard_rectangles[] 4389ifdef::VK_EXT_provoking_vertex[] 4390 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-04881]] 4391 If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_GRAPHICS and 4392 the 4393 <<limits-provokingVertexModePerPipeline,provokingVertexModePerPipeline>> 4394 limit is ename:VK_FALSE, then pipeline's 4395 slink:VkPipelineRasterizationProvokingVertexStateCreateInfoEXT::pname:provokingVertexMode 4396 must: be the same as that of any other pipelines previously bound to 4397 this bind point within the current render pass instance, including any 4398 pipeline already bound when beginning the render pass instance 4399endif::VK_EXT_provoking_vertex[] 4400ifdef::VK_HUAWEI_subpass_shading[] 4401 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-04949]] 4402 If pname:pipelineBindPoint is 4403 ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI, the 4404 sname:VkCommandPool that pname:commandBuffer was allocated from must: 4405 support compute operations 4406 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-04950]] 4407 If pname:pipelineBindPoint is 4408 ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI, pname:pipeline 4409 must: be a subpass shading pipeline 4410endif::VK_HUAWEI_subpass_shading[] 4411ifdef::VK_KHR_dynamic_rendering[] 4412 * [[VUID-vkCmdBindPipeline-pipeline-06195]] 4413 If pname:pipeline is a graphics pipeline, this command has been called 4414 inside a render pass instance started with flink:vkCmdBeginRenderingKHR, 4415 and commands using the previously bound graphics pipeline have been 4416 recorded within the render pass instance, then the value of 4417 slink:VkPipelineRenderingCreateInfoKHR::pname:colorAttachmentCount 4418 specified by this pipeline must: match that set in the previous pipeline 4419 * [[VUID-vkCmdBindPipeline-pipeline-06196]] 4420 If pname:pipeline is a graphics pipeline, this command has been called 4421 inside a render pass instance started with flink:vkCmdBeginRenderingKHR, 4422 and commands using the previously bound graphics pipeline have been 4423 recorded within the render pass instance, then the elements of 4424 slink:VkPipelineRenderingCreateInfoKHR::pname:pColorAttachmentFormats 4425 specified by this pipeline must: match that set in the previous pipeline 4426 * [[VUID-vkCmdBindPipeline-pipeline-06197]] 4427 If pname:pipeline is a graphics pipeline, this command has been called 4428 inside a render pass instance started with flink:vkCmdBeginRenderingKHR, 4429 and commands using the previously bound graphics pipeline have been 4430 recorded within the render pass instance, then the value of 4431 slink:VkPipelineRenderingCreateInfoKHR::pname:depthAttachmentFormat 4432 specified by this pipeline must: match that set in the previous pipeline 4433 * [[VUID-vkCmdBindPipeline-pipeline-06194]] 4434 If pname:pipeline is a graphics pipeline, this command has been called 4435 inside a render pass instance started with flink:vkCmdBeginRenderingKHR, 4436 and commands using the previously bound graphics pipeline have been 4437 recorded within the render pass instance, then the value of 4438 slink:VkPipelineRenderingCreateInfoKHR::pname:stencilAttachmentFormat 4439 specified by this pipeline must: match that set in the previous pipeline 4440endif::VK_KHR_dynamic_rendering[] 4441**** 4442 4443include::{generated}/validity/protos/vkCmdBindPipeline.txt[] 4444-- 4445 4446[open,refpage='VkPipelineBindPoint',desc='Specify the bind point of a pipeline object to a command buffer',type='enums'] 4447-- 4448Possible values of flink:vkCmdBindPipeline::pname:pipelineBindPoint, 4449specifying the bind point of a pipeline object, are: 4450 4451include::{generated}/api/enums/VkPipelineBindPoint.txt[] 4452 4453 * ename:VK_PIPELINE_BIND_POINT_COMPUTE specifies binding as a compute 4454 pipeline. 4455 * ename:VK_PIPELINE_BIND_POINT_GRAPHICS specifies binding as a graphics 4456 pipeline. 4457ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 4458 * ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR specifies binding as a ray 4459 tracing pipeline. 4460endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 4461ifdef::VK_HUAWEI_subpass_shading[] 4462 * ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI specifies binding as 4463 a subpass shading pipeline. 4464endif::VK_HUAWEI_subpass_shading[] 4465-- 4466 4467ifdef::VK_NV_device_generated_commands[] 4468[open,refpage='vkCmdBindPipelineShaderGroupNV',desc='Bind a pipeline object's shader group to a command buffer',type='protos'] 4469-- 4470For pipelines that were created with the support of multiple shader groups 4471(see <<graphics-shadergroups,Graphics Pipeline Shader Groups>>), the regular 4472fname:vkCmdBindPipeline command will bind Shader Group `0`. 4473To explicitly bind a shader group use: 4474 4475include::{generated}/api/protos/vkCmdBindPipelineShaderGroupNV.txt[] 4476 4477 * pname:commandBuffer is the command buffer that the pipeline will be 4478 bound to. 4479 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying 4480 the bind point to which the pipeline will be bound. 4481 * pname:pipeline is the pipeline to be bound. 4482 * pname:groupIndex is the shader group to be bound. 4483 4484 4485.Valid Usage 4486**** 4487 * [[VUID-vkCmdBindPipelineShaderGroupNV-groupIndex-02893]] 4488 pname:groupIndex must: be `0` or less than the effective 4489 slink:VkGraphicsPipelineShaderGroupsCreateInfoNV::pname:groupCount 4490 including the referenced pipelines 4491 * [[VUID-vkCmdBindPipelineShaderGroupNV-pipelineBindPoint-02894]] 4492 The pname:pipelineBindPoint must: be 4493 ename:VK_PIPELINE_BIND_POINT_GRAPHICS 4494 * [[VUID-vkCmdBindPipelineShaderGroupNV-groupIndex-02895]] 4495 The same restrictions as flink:vkCmdBindPipeline apply as if the bound 4496 pipeline was created only with the Shader Group from the 4497 pname:groupIndex information 4498 * [[VUID-vkCmdBindPipelineShaderGroupNV-deviceGeneratedCommands-02896]] 4499 The <<features-deviceGeneratedCommands, 4500 sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>> 4501 feature must: be enabled 4502**** 4503 4504include::{generated}/validity/protos/vkCmdBindPipelineShaderGroupNV.txt[] 4505-- 4506endif::VK_NV_device_generated_commands[] 4507 4508 4509[[pipelines-dynamic-state]] 4510== Dynamic State 4511 4512When a pipeline object is bound, any pipeline object state that is not 4513specified as dynamic is applied to the command buffer state. 4514Pipeline object state that is specified as dynamic is not applied to the 4515command buffer state at this time. 4516Instead, dynamic state can: be modified at any time and persists for the 4517lifetime of the command buffer, or until modified by another dynamic state 4518setting command or another pipeline bind. 4519 4520When a pipeline object is bound, the following applies to each state 4521parameter: 4522 4523 * If the state is not specified as dynamic in the new pipeline object, 4524 then that command buffer state is overwritten by the state in the new 4525 pipeline object. 4526 Before any draw or dispatch call with this pipeline there must: not have 4527 been any calls to any of the corresponding dynamic state setting 4528 commands after this pipeline was bound 4529 * If the state is specified as dynamic in the new pipeline object, then 4530 that command buffer state is not disturbed. 4531 Before any draw or dispatch call with this pipeline there must: have 4532 been at least one call to each of the corresponding dynamic state 4533 setting commands since the command buffer recording was begun, or the 4534 last bound pipeline object with that state specified as static, 4535 whichever was the latter 4536 4537Dynamic state that does not affect the result of operations can: be left 4538undefined:. 4539 4540[NOTE] 4541.Note 4542==== 4543For example, if blending is disabled by the pipeline object state then the 4544dynamic color blend constants do not need to be specified in the command 4545buffer, even if this state is specified as dynamic in the pipeline object. 4546==== 4547 4548ifdef::VK_AMD_shader_info,VK_KHR_pipeline_executable_properties[] 4549[[pipelines-shader-information]] 4550== Pipeline Shader Information 4551endif::VK_AMD_shader_info,VK_KHR_pipeline_executable_properties[] 4552 4553ifdef::VK_KHR_pipeline_executable_properties[] 4554include::VK_KHR_pipeline_executable_properties/pipelines.txt[] 4555endif::VK_KHR_pipeline_executable_properties[] 4556 4557ifdef::VK_AMD_shader_info[] 4558include::VK_AMD_shader_info.txt[] 4559endif::VK_AMD_shader_info[] 4560 4561// These includes have their own section headers 4562 4563ifdef::VK_AMD_pipeline_compiler_control[] 4564include::VK_AMD_pipeline_compiler_control.txt[] 4565endif::VK_AMD_pipeline_compiler_control[] 4566 4567ifdef::VK_EXT_pipeline_creation_feedback[] 4568include::VK_EXT_pipeline_creation_feedback/pipelines.txt[] 4569endif::VK_EXT_pipeline_creation_feedback[] 4570
