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