1// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/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_ or a _compute pipeline_. 16 17The first stage of the <<pipelines-graphics,graphics pipeline>> 18(<<drawing,Input Assembler>>) assembles vertices to form geometric 19primitives such as points, lines, and triangles, based on a requested 20primitive topology. 21In the next stage (<<shaders-vertex,Vertex Shader>>) vertices can: be 22transformed, computing positions and attributes for each vertex. 23If <<tessellation,tessellation>> and/or <<geometry,geometry>> shaders are 24supported, they can: then generate multiple primitives from a single input 25primitive, possibly changing the primitive topology or generating additional 26attribute data in the process. 27 28The final resulting primitives are <<vertexpostproc-clipping,clipped>> to a 29clip volume in preparation for the next stage, <<primsrast,Rasterization>>. 30The rasterizer produces a series of framebuffer addresses and values using a 31two-dimensional description of a point, line segment, or triangle. 32Each _fragment_ so produced is fed to the next stage 33(<<shaders-fragment,Fragment Shader>>) that performs operations on 34individual fragments before they finally alter the framebuffer. 35These operations include conditional updates into the framebuffer based on 36incoming and previously stored depth values (to effect <<fragops-depth,depth 37buffering>>), <<framebuffer-blending,blending>> of incoming fragment colors 38with stored colors, as well as <<framebuffer-blendoperations,masking>>, 39<<fragops-stencil,stenciling>>, and other <<framebuffer-logicop,logical 40operations>> on fragment values. 41 42Framebuffer operations read and write the color and depth/stencil 43attachments of the framebuffer for a given subpass of a <<renderpass,render 44pass instance>>. 45The attachments can: be used as input attachments in the fragment shader in 46a later subpass of the same render pass. 47 48The <<pipelines-compute,compute pipeline>> is a separate pipeline from the 49graphics pipeline, which operates on one-, two-, or three-dimensional 50workgroups which can: read from and write to buffer and image memory. 51 52This ordering is meant only as a tool for describing Vulkan, not as a strict 53rule of how Vulkan is implemented, and we present it only as a means to 54organize the various operations of the pipelines. 55Actual ordering guarantees between pipeline stages are explained in detail 56in the <<synchronization-pipeline-stages-order, synchronization chapter>>. 57 58[[pipelines-block-diagram]] 59[%inline] 60image::images/pipeline.svg[title="Block diagram of the Vulkan pipeline",align="center"] 61 62Each pipeline is controlled by a monolithic object created from a 63description of all of the shader stages and any relevant fixed-function 64stages. 65<<interfaces,Linking>> the whole pipeline together allows the optimization 66of shaders based on their input/outputs and eliminates expensive draw time 67state validation. 68 69A pipeline object is bound to the current state using 70flink:vkCmdBindPipeline. 71Any pipeline object state that is specified as <<pipelines-dynamic-state, 72dynamic>> is not applied to the current state when the pipeline object is 73bound, but is instead set by dynamic state setting commands. 74 75No state, including dynamic state, is inherited from one command buffer to 76another. 77 78 79[open,refpage='VkPipeline',desc='Opaque handle to a pipeline object',type='handles'] 80-- 81 82Compute and graphics pipelines are each represented by sname:VkPipeline 83handles: 84 85include::../api/handles/VkPipeline.txt[] 86 87-- 88 89 90[[pipelines-compute]] 91== Compute Pipelines 92 93Compute pipelines consist of a single static compute shader stage and the 94pipeline layout. 95 96The compute pipeline represents a compute shader and is created by calling 97fname:vkCreateComputePipelines with pname:module and pname:pName selecting 98an entry point from a shader module, where that entry point defines a valid 99compute shader, in the sname:VkPipelineShaderStageCreateInfo structure 100contained within the sname:VkComputePipelineCreateInfo structure. 101 102[open,refpage='vkCreateComputePipelines',desc='Creates a new compute pipeline object',type='protos'] 103-- 104 105To create compute pipelines, call: 106 107include::../api/protos/vkCreateComputePipelines.txt[] 108 109 * pname:device is the logical device that creates the compute pipelines. 110 * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that 111 pipeline caching is disabled; or the handle of a valid 112 <<pipelines-cache,pipeline cache>> object, in which case use of that 113 cache is enabled for the duration of the command. 114 * pname:createInfoCount is the length of the pname:pCreateInfos and 115 pname:pPipelines arrays. 116 * pname:pCreateInfos is an array of slink:VkComputePipelineCreateInfo 117 structures. 118 * pname:pAllocator controls host memory allocation as described in the 119 <<memory-allocation, Memory Allocation>> chapter. 120 * pname:pPipelines is a pointer to an array in which the resulting compute 121 pipeline objects are returned. 122ifdef::editing-notes[] 123+ 124[NOTE] 125.editing-note 126==== 127TODO (Jon) - Should we say something like "`the i'th element of the 128pname:pPipelines array is created based on the corresponding element of the 129pname:pCreateInfos array`"? Also for flink:vkCreateGraphicsPipelines below. 130==== 131endif::editing-notes[] 132 133.Valid Usage 134**** 135 * [[VUID-vkCreateComputePipelines-flags-00695]] 136 If the pname:flags member of any element of pname:pCreateInfos contains 137 the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the 138 pname:basePipelineIndex member of that same element is not `-1`, 139 pname:basePipelineIndex must: be less than the index into 140 pname:pCreateInfos that corresponds to that element 141 * [[VUID-vkCreateComputePipelines-flags-00696]] 142 If the pname:flags member of any element of pname:pCreateInfos contains 143 the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline 144 must: have been created with the 145 ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set 146**** 147 148include::../validity/protos/vkCreateComputePipelines.txt[] 149-- 150 151[open,refpage='VkComputePipelineCreateInfo',desc='Structure specifying parameters of a newly created compute pipeline',type='structs'] 152-- 153 154The sname:VkComputePipelineCreateInfo structure is defined as: 155 156include::../api/structs/VkComputePipelineCreateInfo.txt[] 157 158 * pname:sType is the type of this structure. 159 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 160 * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying 161 how the pipeline will be generated. 162 * pname:stage is a slink:VkPipelineShaderStageCreateInfo describing the 163 compute shader. 164 * pname:layout is the description of binding locations used by both the 165 pipeline and descriptor sets used with the pipeline. 166 * pname:basePipelineHandle is a pipeline to derive from 167 * pname:basePipelineIndex is an index into the pname:pCreateInfos 168 parameter to use as a pipeline to derive from 169 170The parameters pname:basePipelineHandle and pname:basePipelineIndex are 171described in more detail in <<pipelines-pipeline-derivatives,Pipeline 172Derivatives>>. 173 174pname:stage points to a structure of type 175sname:VkPipelineShaderStageCreateInfo. 176 177.Valid Usage 178**** 179 * [[VUID-VkComputePipelineCreateInfo-flags-00697]] 180 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 181 flag, and pname:basePipelineIndex is -1, pname:basePipelineHandle must: 182 be a valid handle to a compute sname:VkPipeline 183 * [[VUID-VkComputePipelineCreateInfo-flags-00698]] 184 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 185 flag, and pname:basePipelineHandle is dlink:VK_NULL_HANDLE, 186 pname:basePipelineIndex must: be a valid index into the calling 187 command's pname:pCreateInfos parameter 188 * [[VUID-VkComputePipelineCreateInfo-flags-00699]] 189 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 190 flag, and pname:basePipelineIndex is not -1, pname:basePipelineHandle 191 must: be dlink:VK_NULL_HANDLE 192 * [[VUID-VkComputePipelineCreateInfo-flags-00700]] 193 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 194 flag, and pname:basePipelineHandle is not dlink:VK_NULL_HANDLE, 195 pname:basePipelineIndex must: be -1 196 * [[VUID-VkComputePipelineCreateInfo-stage-00701]] 197 The pname:stage member of pname:stage must: be 198 ename:VK_SHADER_STAGE_COMPUTE_BIT 199 * [[VUID-VkComputePipelineCreateInfo-stage-00702]] 200 The shader code for the entry point identified by pname:stage and the 201 rest of the state identified by this structure must: adhere to the 202 pipeline linking rules described in the <<interfaces,Shader Interfaces>> 203 chapter 204 * [[VUID-VkComputePipelineCreateInfo-layout-00703]] 205 pname:layout must: be 206 <<descriptorsets-pipelinelayout-consistency,consistent>> with the layout 207 of the compute shader specified in pname:stage 208 * [[VUID-VkComputePipelineCreateInfo-layout-01687]] 209 The number of resources in pname:layout accessible to the compute shader 210 stage must: be less than or equal to 211 sname:VkPhysicalDeviceLimits::pname:maxPerStageResources 212**** 213 214include::../validity/structs/VkComputePipelineCreateInfo.txt[] 215-- 216 217[open,refpage='VkPipelineShaderStageCreateInfo',desc='Structure specifying parameters of a newly created pipeline shader stage',type='structs'] 218-- 219 220The sname:VkPipelineShaderStageCreateInfo structure is defined as: 221 222include::../api/structs/VkPipelineShaderStageCreateInfo.txt[] 223 224 * pname:sType is the type of this structure. 225 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 226 * pname:flags is reserved for future use. 227 * pname:stage is a elink:VkShaderStageFlagBits value specifying a single 228 pipeline stage. 229 * pname:module is a slink:VkShaderModule object that contains the shader 230 for this stage. 231 * pname:pName is a pointer to a null-terminated UTF-8 string specifying 232 the entry point name of the shader for this stage. 233 * pname:pSpecializationInfo is a pointer to slink:VkSpecializationInfo, as 234 described in <<pipelines-specialization-constants,Specialization 235 Constants>>, and can: be `NULL`. 236 237.Valid Usage 238**** 239 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00704]] 240 If the <<features-features-geometryShader,geometry shaders>> feature is 241 not enabled, pname:stage must: not be ename:VK_SHADER_STAGE_GEOMETRY_BIT 242 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00705]] 243 If the <<features-features-tessellationShader,tessellation shaders>> 244 feature is not enabled, pname:stage must: not be 245 ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or 246 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT 247 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00706]] 248 pname:stage must: not be ename:VK_SHADER_STAGE_ALL_GRAPHICS, or 249 ename:VK_SHADER_STAGE_ALL 250 * [[VUID-VkPipelineShaderStageCreateInfo-pName-00707]] 251 pname:pName must: be the name of an code:OpEntryPoint in pname:module 252 with an execution model that matches pname:stage 253 * [[VUID-VkPipelineShaderStageCreateInfo-maxClipDistances-00708]] 254 If the identified entry point includes any variable in its interface 255 that is declared with the code:ClipDistance code:BuiltIn decoration, 256 that variable must: not have an array size greater than 257 sname:VkPhysicalDeviceLimits::pname:maxClipDistances 258 * [[VUID-VkPipelineShaderStageCreateInfo-maxCullDistances-00709]] 259 If the identified entry point includes any variable in its interface 260 that is declared with the code:CullDistance code:BuiltIn decoration, 261 that variable must: not have an array size greater than 262 sname:VkPhysicalDeviceLimits::pname:maxCullDistances 263 * [[VUID-VkPipelineShaderStageCreateInfo-maxCombinedClipAndCullDistances-00710]] 264 If the identified entry point includes any variables in its interface 265 that are declared with the code:ClipDistance or code:CullDistance 266 code:BuiltIn decoration, those variables must: not have array sizes 267 which sum to more than 268 sname:VkPhysicalDeviceLimits::pname:maxCombinedClipAndCullDistances 269 * [[VUID-VkPipelineShaderStageCreateInfo-maxSampleMaskWords-00711]] 270 If the identified entry point includes any variable in its interface 271 that is declared with the code:SampleMask code:BuiltIn decoration, that 272 variable must: not have an array size greater than 273 sname:VkPhysicalDeviceLimits::pname:maxSampleMaskWords 274 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00712]] 275 If pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT, the identified entry 276 point must: not include any input variable in its interface that is 277 decorated with code:CullDistance 278 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00713]] 279 If pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or 280 ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and the identified 281 entry point has an code:OpExecutionMode instruction that specifies a 282 patch size with code:OutputVertices, the patch size must: be greater 283 than `0` and less than or equal to 284 sname:VkPhysicalDeviceLimits::pname:maxTessellationPatchSize 285 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00714]] 286 If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, the identified 287 entry point must: have an code:OpExecutionMode instruction that 288 specifies a maximum output vertex count that is greater than `0` and 289 less than or equal to 290 sname:VkPhysicalDeviceLimits::pname:maxGeometryOutputVertices 291 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00715]] 292 If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, the identified 293 entry point must: have an code:OpExecutionMode instruction that 294 specifies an invocation count that is greater than `0` and less than or 295 equal to 296 sname:VkPhysicalDeviceLimits::pname:maxGeometryShaderInvocations 297 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00716]] 298 If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, and the identified 299 entry point writes to code:Layer for any primitive, it must: write the 300 same value to code:Layer for all vertices of a given primitive 301 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00717]] 302 If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, and the identified 303 entry point writes to code:ViewportIndex for any primitive, it must: 304 write the same value to code:ViewportIndex for all vertices of a given 305 primitive 306 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00718]] 307 If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, the identified 308 entry point must: not include any output variables in its interface 309 decorated with code:CullDistance 310 * [[VUID-VkPipelineShaderStageCreateInfo-stage-00719]] 311 If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, and the identified 312 entry point writes to code:FragDepth in any execution path, it must: 313 write to code:FragDepth in all execution paths 314ifdef::VK_EXT_shader_stencil_export[] 315 * [[VUID-VkPipelineShaderStageCreateInfo-stage-01511]] 316 If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, and the identified 317 entry point writes to code:FragStencilRefEXT in any execution path, it 318 must: write to code:FragStencilRefEXT in all execution paths 319endif::VK_EXT_shader_stencil_export[] 320**** 321 322include::../validity/structs/VkPipelineShaderStageCreateInfo.txt[] 323-- 324 325[open,refpage='VkPipelineShaderStageCreateFlags',desc='Reserved for future use',type='enums'] 326-- 327include::../api/flags/VkPipelineShaderStageCreateFlags.txt[] 328 329sname:VkPipelineShaderStageCreateFlags is a bitmask type for setting a mask, 330but is currently reserved for future use. 331-- 332 333[open,refpage='VkShaderStageFlagBits',desc='Bitmask specifying a pipeline stage',type='enums'] 334-- 335 336Commands and structures which need to specify one or more shader stages do 337so using a bitmask whose bits correspond to stages. 338Bits which can: be set to specify shader stages are: 339 340include::../api/enums/VkShaderStageFlagBits.txt[] 341 342 * ename:VK_SHADER_STAGE_VERTEX_BIT specifies the vertex stage. 343 * ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT specifies the 344 tessellation control stage. 345 * ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT specifies the 346 tessellation evaluation stage. 347 * ename:VK_SHADER_STAGE_GEOMETRY_BIT specifies the geometry stage. 348 * ename:VK_SHADER_STAGE_FRAGMENT_BIT specifies the fragment stage. 349 * ename:VK_SHADER_STAGE_COMPUTE_BIT specifies the compute stage. 350 * ename:VK_SHADER_STAGE_ALL_GRAPHICS is a combination of bits used as 351 shorthand to specify all graphics stages defined above (excluding the 352 compute stage). 353 * ename:VK_SHADER_STAGE_ALL is a combination of bits used as shorthand to 354 specify all shader stages supported by the device, including all 355 additional stages which are introduced by extensions. 356 357-- 358 359[open,refpage='VkShaderStageFlags',desc='Bitmask of VkShaderStageFlagBits',type='enums'] 360-- 361include::../api/flags/VkShaderStageFlags.txt[] 362 363sname:VkShaderStageFlags is a bitmask type for setting a mask of zero or 364more slink:VkShaderStageFlagBits. 365-- 366 367 368[[pipelines-graphics]] 369== Graphics Pipelines 370 371Graphics pipelines consist of multiple shader stages, multiple 372fixed-function pipeline stages, and a pipeline layout. 373 374[open,refpage='vkCreateGraphicsPipelines',desc='Create graphics pipelines',type='protos'] 375-- 376 377To create graphics pipelines, call: 378 379include::../api/protos/vkCreateGraphicsPipelines.txt[] 380 381 * pname:device is the logical device that creates the graphics pipelines. 382 * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that 383 pipeline caching is disabled; or the handle of a valid 384 <<pipelines-cache,pipeline cache>> object, in which case use of that 385 cache is enabled for the duration of the command. 386 * pname:createInfoCount is the length of the pname:pCreateInfos and 387 pname:pPipelines arrays. 388 * pname:pCreateInfos is an array of slink:VkGraphicsPipelineCreateInfo 389 structures. 390 * pname:pAllocator controls host memory allocation as described in the 391 <<memory-allocation, Memory Allocation>> chapter. 392 * pname:pPipelines is a pointer to an array in which the resulting 393 graphics pipeline objects are returned. 394 395The slink:VkGraphicsPipelineCreateInfo structure includes an array of shader 396create info structures containing all the desired active shader stages, as 397well as creation info to define all relevant fixed-function stages, and a 398pipeline layout. 399 400.Valid Usage 401**** 402 * [[VUID-vkCreateGraphicsPipelines-flags-00720]] 403 If the pname:flags member of any element of pname:pCreateInfos contains 404 the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the 405 pname:basePipelineIndex member of that same element is not `-1`, 406 pname:basePipelineIndex must: be less than the index into 407 pname:pCreateInfos that corresponds to that element 408 * [[VUID-vkCreateGraphicsPipelines-flags-00721]] 409 If the pname:flags member of any element of pname:pCreateInfos contains 410 the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline 411 must: have been created with the 412 ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set 413**** 414 415include::../validity/protos/vkCreateGraphicsPipelines.txt[] 416-- 417 418[open,refpage='VkGraphicsPipelineCreateInfo',desc='Structure specifying parameters of a newly created graphics pipeline',type='structs'] 419-- 420 421The sname:VkGraphicsPipelineCreateInfo structure is defined as: 422 423include::../api/structs/VkGraphicsPipelineCreateInfo.txt[] 424 425 * pname:sType is the type of this structure. 426 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 427 * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying 428 how the pipeline will be generated. 429 * pname:stageCount is the number of entries in the pname:pStages array. 430 * pname:pStages is an array of size pname:stageCount structures of type 431 slink:VkPipelineShaderStageCreateInfo describing the set of the shader 432 stages to be included in the graphics pipeline. 433 * pname:pVertexInputState is a pointer to an instance of the 434 slink:VkPipelineVertexInputStateCreateInfo structure. 435 * pname:pInputAssemblyState is a pointer to an instance of the 436 slink:VkPipelineInputAssemblyStateCreateInfo structure which determines 437 input assembly behavior, as described in <<drawing, Drawing Commands>>. 438 * pname:pTessellationState is a pointer to an instance of the 439 slink:VkPipelineTessellationStateCreateInfo structure, and is ignored if 440 the pipeline does not include a tessellation control shader stage and 441 tessellation evaluation shader stage. 442 * pname:pViewportState is a pointer to an instance of the 443 slink:VkPipelineViewportStateCreateInfo structure, and is ignored if the 444 pipeline has rasterization disabled. 445 * pname:pRasterizationState is a pointer to an instance of the 446 slink:VkPipelineRasterizationStateCreateInfo structure. 447 * pname:pMultisampleState is a pointer to an instance of the 448 slink:VkPipelineMultisampleStateCreateInfo, and is ignored if the 449 pipeline has rasterization disabled. 450 * pname:pDepthStencilState is a pointer to an instance of the 451 slink:VkPipelineDepthStencilStateCreateInfo structure, and is ignored if 452 the pipeline has rasterization disabled or if the subpass of the render 453 pass the pipeline is created against does not use a depth/stencil 454 attachment. 455 * pname:pColorBlendState is a pointer to an instance of the 456 slink:VkPipelineColorBlendStateCreateInfo structure, and is ignored if 457 the pipeline has rasterization disabled or if the subpass of the render 458 pass the pipeline is created against does not use any color attachments. 459 * pname:pDynamicState is a pointer to 460 slink:VkPipelineDynamicStateCreateInfo and is used to indicate which 461 properties of the pipeline state object are dynamic and can: be changed 462 independently of the pipeline state. 463 This can: be `NULL`, which means no state in the pipeline is considered 464 dynamic. 465 * pname:layout is the description of binding locations used by both the 466 pipeline and descriptor sets used with the pipeline. 467 * pname:renderPass is a handle to a render pass object describing the 468 environment in which the pipeline will be used; the pipeline must: only 469 be used with an instance of any render pass compatible with the one 470 provided. 471 See <<renderpass-compatibility,Render Pass Compatibility>> for more 472 information. 473 * pname:subpass is the index of the subpass in the render pass where this 474 pipeline will be used. 475 * pname:basePipelineHandle is a pipeline to derive from. 476 * pname:basePipelineIndex is an index into the pname:pCreateInfos 477 parameter to use as a pipeline to derive from. 478 479The parameters pname:basePipelineHandle and pname:basePipelineIndex are 480described in more detail in <<pipelines-pipeline-derivatives,Pipeline 481Derivatives>>. 482 483pname:pStages points to an array of slink:VkPipelineShaderStageCreateInfo 484structures, which were previously described in <<pipelines-compute,Compute 485Pipelines>>. 486 487pname:pDynamicState points to a structure of type 488slink:VkPipelineDynamicStateCreateInfo. 489 490ifdef::VK_NV_glsl_shader[] 491If any shader stage fails to compile, 492ifdef::VK_EXT_debug_report[] 493the compile log will be reported back to the application, and 494endif::VK_EXT_debug_report[] 495ename:VK_ERROR_INVALID_SHADER_NV will be generated. 496endif::VK_NV_glsl_shader[] 497 498.Valid Usage 499**** 500 * [[VUID-VkGraphicsPipelineCreateInfo-flags-00722]] 501 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 502 flag, and pname:basePipelineIndex is -1, pname:basePipelineHandle must: 503 be a valid handle to a graphics sname:VkPipeline 504 * [[VUID-VkGraphicsPipelineCreateInfo-flags-00723]] 505 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 506 flag, and pname:basePipelineHandle is dlink:VK_NULL_HANDLE, 507 pname:basePipelineIndex must: be a valid index into the calling 508 command's pname:pCreateInfos parameter 509 * [[VUID-VkGraphicsPipelineCreateInfo-flags-00724]] 510 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 511 flag, and pname:basePipelineIndex is not -1, pname:basePipelineHandle 512 must: be dlink:VK_NULL_HANDLE 513 * [[VUID-VkGraphicsPipelineCreateInfo-flags-00725]] 514 If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT 515 flag, and pname:basePipelineHandle is not dlink:VK_NULL_HANDLE, 516 pname:basePipelineIndex must: be -1 517 * [[VUID-VkGraphicsPipelineCreateInfo-stage-00726]] 518 The pname:stage member of each element of pname:pStages must: be unique 519 * [[VUID-VkGraphicsPipelineCreateInfo-stage-00727]] 520 The pname:stage member of one element of pname:pStages must: be 521 ename:VK_SHADER_STAGE_VERTEX_BIT 522 * [[VUID-VkGraphicsPipelineCreateInfo-stage-00728]] 523 The pname:stage member of each element of pname:pStages must: not be 524 ename:VK_SHADER_STAGE_COMPUTE_BIT 525 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00729]] 526 If pname:pStages includes a tessellation control shader stage, it must: 527 include a tessellation evaluation shader stage 528 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00730]] 529 If pname:pStages includes a tessellation evaluation shader stage, it 530 must: include a tessellation control shader stage 531 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00731]] 532 If pname:pStages includes a tessellation control shader stage and a 533 tessellation evaluation shader stage, pname:pTessellationState must: be 534 a valid pointer to a valid sname:VkPipelineTessellationStateCreateInfo 535 structure 536 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00732]] 537 If pname:pStages includes tessellation shader stages, the shader code of 538 at least one stage must: contain an code:OpExecutionMode instruction 539 that specifies the type of subdivision in the pipeline 540 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00733]] 541 If pname:pStages includes tessellation shader stages, and the shader 542 code of both stages contain an code:OpExecutionMode instruction that 543 specifies the type of subdivision in the pipeline, they must: both 544 specify the same subdivision mode 545 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00734]] 546 If pname:pStages includes tessellation shader stages, the shader code of 547 at least one stage must: contain an code:OpExecutionMode instruction 548 that specifies the output patch size in the pipeline 549 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00735]] 550 If pname:pStages includes tessellation shader stages, and the shader 551 code of both contain an code:OpExecutionMode instruction that specifies 552 the out patch size in the pipeline, they must: both specify the same 553 patch size 554 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00736]] 555 If pname:pStages includes tessellation shader stages, the pname:topology 556 member of pname:pInputAssembly must: be 557 ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST 558 * [[VUID-VkGraphicsPipelineCreateInfo-topology-00737]] 559 If the pname:topology member of pname:pInputAssembly is 560 ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, pname:pStages must: include 561 tessellation shader stages 562 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00738]] 563 If pname:pStages includes a geometry shader stage, and does not include 564 any tessellation shader stages, its shader code must: contain an 565 code:OpExecutionMode instruction that specifies an input primitive type 566 that is <<shaders-geometry-execution, compatible>> with the primitive 567 topology specified in pname:pInputAssembly 568 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00739]] 569 If pname:pStages includes a geometry shader stage, and also includes 570 tessellation shader stages, its shader code must: contain an 571 code:OpExecutionMode instruction that specifies an input primitive type 572 that is <<shaders-geometry-execution, compatible>> with the primitive 573 topology that is output by the tessellation stages 574 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00740]] 575 If pname:pStages includes a fragment shader stage and a geometry shader 576 stage, and the fragment shader code reads from an input variable that is 577 decorated with code:PrimitiveID, then the geometry shader code must: 578 write to a matching output variable, decorated with code:PrimitiveID, in 579 all execution paths 580 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00741]] 581 If pname:pStages includes a fragment shader stage, its shader code must: 582 not read from any input attachment that is defined as 583 ename:VK_ATTACHMENT_UNUSED in pname:subpass 584 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00742]] 585 The shader code for the entry points identified by pname:pStages, and 586 the rest of the state identified by this structure must: adhere to the 587 pipeline linking rules described in the <<interfaces,Shader Interfaces>> 588 chapter 589// The block of VU below come in alternate versions when the extension is 590// enabled. 591ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 592 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00743]] 593 If rasterization is not disabled and pname:subpass uses a depth/stencil 594 attachment in pname:renderPass that has a layout of 595 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL in the 596 sname:VkAttachmentReference defined by pname:subpass, the 597 pname:depthWriteEnable member of pname:pDepthStencilState must: be 598 ename:VK_FALSE 599 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00744]] 600 If rasterization is not disabled and pname:subpass uses a depth/stencil 601 attachment in pname:renderPass that has a layout of 602 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL in the 603 sname:VkAttachmentReference defined by pname:subpass, the pname:failOp, 604 pname:passOp and pname:depthFailOp members of each of the pname:front 605 and pname:back members of pname:pDepthStencilState must: be 606 ename:VK_STENCIL_OP_KEEP 607endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 608// The nested ifdefs are there in anticipation of the hoped-for day when the 609// VU extractor and validation layers can handle VU with imbedded 610// conditionals. They are commented out until then. 611ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 612 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01756]] 613 If rasterization is not disabled and pname:subpass uses a depth/stencil 614 attachment in pname:renderPass that has a layout of 615 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL 616// ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 617 or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 618// endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 619 in the sname:VkAttachmentReference defined by pname:subpass, the 620 pname:depthWriteEnable member of pname:pDepthStencilState must: be 621 ename:VK_FALSE 622 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01757]] 623 If rasterization is not disabled and pname:subpass uses a depth/stencil 624 attachment in pname:renderPass that has a layout of 625 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL 626// ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 627 or ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL 628// endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 629 in the sname:VkAttachmentReference defined by pname:subpass, the 630 pname:failOp, pname:passOp and pname:depthFailOp members of each of the 631 pname:front and pname:back members of pname:pDepthStencilState must: be 632 ename:VK_STENCIL_OP_KEEP 633endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 634 * [[VUID-VkGraphicsPipelineCreateInfo-blendEnable-02023]] 635 If rasterization is not disabled and the subpass uses color attachments, 636 then for each color attachment in the subpass the pname:blendEnable 637 member of the corresponding element of the pname:pAttachment member of 638 pname:pColorBlendState must: be ename:VK_FALSE if the attached image's 639 <<resources-image-format-features,format features>> does not contain the 640 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT. 641 * [[VUID-VkGraphicsPipelineCreateInfo-attachmentCount-00746]] 642 If rasterization is not disabled and the subpass uses color attachments, 643 the pname:attachmentCount member of pname:pColorBlendState must: be 644 equal to the pname:colorAttachmentCount used to create pname:subpass 645 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00747]] 646 If no element of the pname:pDynamicStates member of pname:pDynamicState 647 is ename:VK_DYNAMIC_STATE_VIEWPORT, the pname:pViewports member of 648 pname:pViewportState must: be a valid pointer to an array of 649 pname:pViewportState::pname:viewportCount valid sname:VkViewport 650 structures 651 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00748]] 652 If no element of the pname:pDynamicStates member of pname:pDynamicState 653 is ename:VK_DYNAMIC_STATE_SCISSOR, the pname:pScissors member of 654 pname:pViewportState must: be a valid pointer to an array of 655 pname:pViewportState::pname:scissorCount sname:VkRect2D structures 656 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00749]] 657 If the wide lines feature is not enabled, and no element of the 658 pname:pDynamicStates member of pname:pDynamicState is 659 ename:VK_DYNAMIC_STATE_LINE_WIDTH, the pname:lineWidth member of 660 pname:pRasterizationState must: be `1.0` 661 * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00750]] 662 If the pname:rasterizerDiscardEnable member of pname:pRasterizationState 663 is ename:VK_FALSE, pname:pViewportState must: be a valid pointer to a 664 valid sname:VkPipelineViewportStateCreateInfo structure 665 * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00751]] 666 If the pname:rasterizerDiscardEnable member of pname:pRasterizationState 667 is ename:VK_FALSE, pname:pMultisampleState must: be a valid pointer to a 668 valid sname:VkPipelineMultisampleStateCreateInfo structure 669 * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00752]] 670 If the pname:rasterizerDiscardEnable member of pname:pRasterizationState 671 is ename:VK_FALSE, and pname:subpass uses a depth/stencil attachment, 672 pname:pDepthStencilState must: be a valid pointer to a valid 673 sname:VkPipelineDepthStencilStateCreateInfo structure 674 * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00753]] 675 If the pname:rasterizerDiscardEnable member of pname:pRasterizationState 676 is ename:VK_FALSE, and pname:subpass uses color attachments, 677 pname:pColorBlendState must: be a valid pointer to a valid 678 sname:VkPipelineColorBlendStateCreateInfo structure 679 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00754]] 680 If the depth bias clamping feature is not enabled, no element of the 681 pname:pDynamicStates member of pname:pDynamicState is 682 ename:VK_DYNAMIC_STATE_DEPTH_BIAS, and the pname:depthBiasEnable member 683 of pname:pRasterizationState is ename:VK_TRUE, the pname:depthBiasClamp 684 member of pname:pRasterizationState must: be `0.0` 685ifndef::VK_EXT_depth_range_unrestricted[] 686 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00755]] 687 If no element of the pname:pDynamicStates member of pname:pDynamicState 688 is ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS, and the 689 pname:depthBoundsTestEnable member of pname:pDepthStencilState is 690 ename:VK_TRUE, the pname:minDepthBounds and pname:maxDepthBounds members 691 of pname:pDepthStencilState must: be between `0.0` and `1.0`, inclusive 692endif::VK_EXT_depth_range_unrestricted[] 693ifdef::VK_EXT_depth_range_unrestricted[] 694 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00755]] 695 If the `<<VK_EXT_depth_range_unrestricted>>` extension is not enabled 696 and no element of the pname:pDynamicStates member of pname:pDynamicState 697 is ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS, and the 698 pname:depthBoundsTestEnable member of pname:pDepthStencilState is 699 ename:VK_TRUE, the pname:minDepthBounds and pname:maxDepthBounds members 700 of pname:pDepthStencilState must: be between `0.0` and `1.0`, inclusive 701endif::VK_EXT_depth_range_unrestricted[] 702ifdef::VK_EXT_sample_locations[] 703 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01521]] 704 If no element of the pname:pDynamicStates member of pname:pDynamicState 705 is ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT, and the 706 pname:sampleLocationsEnable member of a 707 slink:VkPipelineSampleLocationsStateCreateInfoEXT structure chained to 708 the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE, 709 pname:sampleLocationsInfo.sampleLocationGridSize.width must: evenly 710 divide 711 slink:VkMultisamplePropertiesEXT::pname:sampleLocationGridSize.width as 712 returned by flink:vkGetPhysicalDeviceMultisamplePropertiesEXT with a 713 pname:samples parameter equaling pname:rasterizationSamples 714 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01522]] 715 If no element of the pname:pDynamicStates member of pname:pDynamicState 716 is ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT, and the 717 pname:sampleLocationsEnable member of a 718 slink:VkPipelineSampleLocationsStateCreateInfoEXT structure chained to 719 the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE, 720 pname:sampleLocationsInfo.sampleLocationGridSize.height must: evenly 721 divide 722 slink:VkMultisamplePropertiesEXT::pname:sampleLocationGridSize.height as 723 returned by flink:vkGetPhysicalDeviceMultisamplePropertiesEXT with a 724 pname:samples parameter equaling pname:rasterizationSamples 725 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01523]] 726 If no element of the pname:pDynamicStates member of pname:pDynamicState 727 is ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT, and the 728 pname:sampleLocationsEnable member of a 729 slink:VkPipelineSampleLocationsStateCreateInfoEXT structure chained to 730 the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE, 731 pname:sampleLocationsInfo.sampleLocationsPerPixel must: equal 732 pname:rasterizationSamples 733 * [[VUID-VkGraphicsPipelineCreateInfo-sampleLocationsEnable-01524]] 734 If the pname:sampleLocationsEnable member of a 735 slink:VkPipelineSampleLocationsStateCreateInfoEXT structure chained to 736 the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE, the 737 fragment shader code must: not statically use the extended instruction 738 code:InterpolateAtSample 739endif::VK_EXT_sample_locations[] 740 * [[VUID-VkGraphicsPipelineCreateInfo-layout-00756]] 741 pname:layout must: be 742 <<descriptorsets-pipelinelayout-consistency,consistent>> with all 743 shaders specified in pname:pStages 744ifndef::VK_AMD_mixed_attachment_samples[] 745ifndef::VK_NV_framebuffer_mixed_samples[] 746 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00757]] 747 If pname:subpass uses color and/or depth/stencil attachments, then the 748 pname:rasterizationSamples member of pname:pMultisampleState must: be 749 the same as the sample count for those subpass attachments 750endif::VK_NV_framebuffer_mixed_samples[] 751endif::VK_AMD_mixed_attachment_samples[] 752ifdef::VK_AMD_mixed_attachment_samples[] 753 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01505]] 754 If pname:subpass uses color and/or depth/stencil attachments, then the 755 pname:rasterizationSamples member of pname:pMultisampleState must: equal 756 the maximum of the sample counts of those subpass attachments 757endif::VK_AMD_mixed_attachment_samples[] 758ifdef::VK_NV_framebuffer_mixed_samples[] 759 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01411]] 760 If pname:subpass has a depth/stencil attachment and depth test, stencil 761 test, or depth bounds test are enabled, then the 762 pname:rasterizationSamples member of pname:pMultisampleState must: be 763 the same as the sample count of the depth/stencil attachment 764 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01412]] 765 If pname:subpass has any color attachments, then the 766 pname:rasterizationSamples member of pname:pMultisampleState must: be 767 greater than or equal to the sample count for those subpass attachments 768endif::VK_NV_framebuffer_mixed_samples[] 769 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00758]] 770 If pname:subpass does not use any color and/or depth/stencil 771 attachments, then the pname:rasterizationSamples member of 772 pname:pMultisampleState must: follow the rules for a 773 <<renderpass-noattachments, zero-attachment subpass>> 774 * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00759]] 775 pname:subpass must: be a valid subpass within pname:renderPass 776ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 777 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00760]] 778 If the pname:renderPass has multiview enabled and pname:subpass has more 779 than one bit set in the view mask and pname:multiviewTessellationShader 780 is not enabled, then pname:pStages must: not include tessellation 781 shaders. 782 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00761]] 783 If the pname:renderPass has multiview enabled and pname:subpass has more 784 than one bit set in the view mask and pname:multiviewGeometryShader is 785 not enabled, then pname:pStages must: not include a geometry shader. 786 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00762]] 787 If the pname:renderPass has multiview enabled and pname:subpass has more 788 than one bit set in the view mask, shaders in the pipeline must: not 789 write to the code:Layer built-in output 790 * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00763]] 791 If the pname:renderPass has multiview enabled, then all shaders must: 792 not include variables decorated with the code:Layer built-in decoration 793 in their interfaces. 794endif::VK_VERSION_1_1,VK_KHR_multiview[] 795ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 796 * [[VUID-VkGraphicsPipelineCreateInfo-flags-00764]] 797 pname:flags must: not contain the ename:VK_PIPELINE_CREATE_DISPATCH_BASE 798 flag. 799endif::VK_VERSION_1_1,VK_KHR_device_group[] 800ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 801 * [[VUID-VkGraphicsPipelineCreateInfo-pStages-01565]] 802 If pname:pStages includes a fragment shader stage and an input 803 attachment was referenced by the 804 slink:VkRenderPassInputAttachmentAspectCreateInfo at pname:renderPass 805 create time, its shader code must: not read from any aspect that was not 806 specified in the pname:aspectMask of the corresponding 807 slink:VkInputAttachmentAspectReference structure. 808endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 809 * [[VUID-VkGraphicsPipelineCreateInfo-layout-01688]] 810 The number of resources in pname:layout accessible to each shader stage 811 that is used by the pipeline must: be less than or equal to 812 sname:VkPhysicalDeviceLimits::pname:maxPerStageResources 813ifdef::VK_NV_clip_space_w_scaling[] 814 * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01715]] 815 If no element of the pname:pDynamicStates member of pname:pDynamicState 816 is ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV, and the 817 pname:viewportWScalingEnable member of a 818 slink:VkPipelineViewportWScalingStateCreateInfoNV structure, chained to 819 the pname:pNext chain of pname:pViewportState, is ename:VK_TRUE, the 820 pname:pViewportWScalings member of the 821 slink:VkPipelineViewportWScalingStateCreateInfoNV must: be a pointer to 822 an array of 823 slink:VkPipelineViewportWScalingStateCreateInfoNV::pname:viewportCount 824 valid slink:VkViewportWScalingNV structures 825endif::VK_NV_clip_space_w_scaling[] 826**** 827 828include::../validity/structs/VkGraphicsPipelineCreateInfo.txt[] 829-- 830 831[open,refpage='VkPipelineCreateFlagBits',desc='Bitmask controlling how a pipeline is created',type='enums'] 832-- 833 834Possible values of the pname:flags member of 835slink:VkGraphicsPipelineCreateInfo and slink:VkComputePipelineCreateInfo, 836specifying how a pipeline is created, are: 837 838include::../api/enums/VkPipelineCreateFlagBits.txt[] 839 840 * ename:VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT specifies that the 841 created pipeline will not be optimized. 842 Using this flag may: reduce the time taken to create the pipeline. 843 * ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT specifies that the 844 pipeline to be created is allowed to be the parent of a pipeline that 845 will be created in a subsequent call to flink:vkCreateGraphicsPipelines 846 or flink:vkCreateComputePipelines. 847 * ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT specifies that the pipeline to 848 be created will be a child of a previously created parent pipeline. 849ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 850ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 851 * ename:VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT specifies that 852 any shader input variables decorated as code:ViewIndex will be assigned 853 values as if they were decorated as code:DeviceIndex. 854endif::VK_VERSION_1_1,VK_KHR_multiview[] 855 * ename:VK_PIPELINE_CREATE_DISPATCH_BASE specifies that a compute pipeline 856 can: be used with flink:vkCmdDispatchBase with a non-zero base 857 workgroup. 858endif::VK_VERSION_1_1,VK_KHR_device_group[] 859 860It is valid to set both ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT and 861ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT. 862This allows a pipeline to be both a parent and possibly a child in a 863pipeline hierarchy. 864See <<pipelines-pipeline-derivatives,Pipeline Derivatives>> for more 865information. 866 867-- 868 869[open,refpage='VkPipelineCreateFlags',desc='Bitmask of VkPipelineCreateFlagBits',type='enums'] 870-- 871include::../api/flags/VkPipelineCreateFlags.txt[] 872 873sname:VkPipelineCreateFlags is a bitmask type for setting a mask of zero or 874more slink:VkPipelineCreateFlagBits. 875-- 876 877[open,refpage='VkPipelineDynamicStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline dynamic state',type='structs'] 878-- 879 880The sname:VkPipelineDynamicStateCreateInfo structure is defined as: 881 882include::../api/structs/VkPipelineDynamicStateCreateInfo.txt[] 883 884 * pname:sType is the type of this structure. 885 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 886 * pname:flags is reserved for future use. 887 * pname:dynamicStateCount is the number of elements in the 888 pname:pDynamicStates array. 889 * pname:pDynamicStates is an array of elink:VkDynamicState values 890 specifying which pieces of pipeline state will use the values from 891 dynamic state commands rather than from pipeline state creation info. 892 893.Valid Usage 894**** 895 * [[VUID-VkPipelineDynamicStateCreateInfo-pDynamicStates-01442]] 896 Each element of pname:pDynamicStates must: be unique 897**** 898 899include::../validity/structs/VkPipelineDynamicStateCreateInfo.txt[] 900-- 901 902[open,refpage='VkPipelineDynamicStateCreateFlags',desc='Reserved for future use',type='enums'] 903-- 904include::../api/flags/VkPipelineDynamicStateCreateFlags.txt[] 905 906sname:VkPipelineDynamicStateCreateFlags is a bitmask type for setting a 907mask, but is currently reserved for future use. 908-- 909 910[open,refpage='VkDynamicState',desc='Indicate which dynamic state is taken from dynamic state commands',type='enums'] 911-- 912 913The source of different pieces of dynamic state is specified by the 914slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates property of the 915currently active pipeline, each of whose elements must: be one of the 916values: 917 918include::../api/enums/VkDynamicState.txt[] 919 920 * ename:VK_DYNAMIC_STATE_VIEWPORT specifies that the pname:pViewports 921 state in sname:VkPipelineViewportStateCreateInfo will be ignored and 922 must: be set dynamically with flink:vkCmdSetViewport before any draw 923 commands. 924 The number of viewports used by a pipeline is still specified by the 925 pname:viewportCount member of sname:VkPipelineViewportStateCreateInfo. 926 * ename:VK_DYNAMIC_STATE_SCISSOR specifies that the pname:pScissors state 927 in sname:VkPipelineViewportStateCreateInfo will be ignored and must: be 928 set dynamically with flink:vkCmdSetScissor before any draw commands. 929 The number of scissor rectangles used by a pipeline is still specified 930 by the pname:scissorCount member of 931 sname:VkPipelineViewportStateCreateInfo. 932 * ename:VK_DYNAMIC_STATE_LINE_WIDTH specifies that the pname:lineWidth 933 state in sname:VkPipelineRasterizationStateCreateInfo will be ignored 934 and must: be set dynamically with flink:vkCmdSetLineWidth before any 935 draw commands that generate line primitives for the rasterizer. 936 * ename:VK_DYNAMIC_STATE_DEPTH_BIAS specifies that the 937 pname:depthBiasConstantFactor, pname:depthBiasClamp and 938 pname:depthBiasSlopeFactor states in 939 sname:VkPipelineRasterizationStateCreateInfo will be ignored and must: 940 be set dynamically with flink:vkCmdSetDepthBias before any draws are 941 performed with pname:depthBiasEnable in 942 sname:VkPipelineRasterizationStateCreateInfo set to ename:VK_TRUE. 943 * ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS specifies that the 944 pname:blendConstants state in sname:VkPipelineColorBlendStateCreateInfo 945 will be ignored and must: be set dynamically with 946 flink:vkCmdSetBlendConstants before any draws are performed with a 947 pipeline state with sname:VkPipelineColorBlendAttachmentState member 948 pname:blendEnable set to ename:VK_TRUE and any of the blend functions 949 using a constant blend color. 950 * ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS specifies that the 951 pname:minDepthBounds and pname:maxDepthBounds states of 952 slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be 953 set dynamically with flink:vkCmdSetDepthBounds before any draws are 954 performed with a pipeline state with 955 sname:VkPipelineDepthStencilStateCreateInfo member 956 pname:depthBoundsTestEnable set to ename:VK_TRUE. 957 * ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK specifies that the 958 pname:compareMask state in sname:VkPipelineDepthStencilStateCreateInfo 959 for both pname:front and pname:back will be ignored and must: be set 960 dynamically with flink:vkCmdSetStencilCompareMask before any draws are 961 performed with a pipeline state with 962 sname:VkPipelineDepthStencilStateCreateInfo member 963 pname:stencilTestEnable set to ename:VK_TRUE 964 * ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK specifies that the 965 pname:writeMask state in sname:VkPipelineDepthStencilStateCreateInfo for 966 both pname:front and pname:back will be ignored and must: be set 967 dynamically with flink:vkCmdSetStencilWriteMask before any draws are 968 performed with a pipeline state with 969 sname:VkPipelineDepthStencilStateCreateInfo member 970 pname:stencilTestEnable set to ename:VK_TRUE 971 * ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE specifies that the 972 pname:reference state in sname:VkPipelineDepthStencilStateCreateInfo for 973 both pname:front and pname:back will be ignored and must: be set 974 dynamically with flink:vkCmdSetStencilReference before any draws are 975 performed with a pipeline state with 976 sname:VkPipelineDepthStencilStateCreateInfo member 977 pname:stencilTestEnable set to ename:VK_TRUE 978ifdef::VK_NV_clip_space_w_scaling[] 979 * ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV specifies that the 980 pname:pViewportScalings state in 981 sname:VkPipelineViewportWScalingStateCreateInfoNV will be ignored and 982 must: be set dynamically with flink:vkCmdSetViewportWScalingNV before 983 any draws are performed with a pipeline state with 984 sname:VkPipelineViewportWScalingStateCreateInfo member 985 pname:viewportScalingEnable set to ename:VK_TRUE 986endif::VK_NV_clip_space_w_scaling[] 987ifdef::VK_EXT_discard_rectangles[] 988 * ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLES_EXT specifies that the 989 pname:pDiscardRectangles state in 990 slink:VkPipelineDiscardRectangleStateCreateInfoEXT will be ignored and 991 must: be set dynamically with flink:vkCmdSetDiscardRectangleEXT before 992 any draw or clear commands. 993 The elink:VkDiscardRectangleModeEXT and the number of active discard 994 rectangles is still specified by the pname:discardRectangleMode and 995 pname:discardRectangleCount members of 996 sname:VkPipelineDiscardRectangleStateCreateInfoEXT. 997endif::VK_EXT_discard_rectangles[] 998ifdef::VK_EXT_sample_locations[] 999 * ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT specifies that the 1000 pname:sampleLocationsInfo state in 1001 slink:VkPipelineSampleLocationsStateCreateInfoEXT will be ignored and 1002 must: be set dynamically with flink:vkCmdSetSampleLocationsEXT before 1003 any draw or clear commands. 1004 Enabling custom sample locations is still indicated by the 1005 pname:sampleLocationsEnable member of 1006 sname:VkPipelineSampleLocationsStateCreateInfoEXT. 1007endif::VK_EXT_sample_locations[] 1008 1009-- 1010 1011 1012=== Valid Combinations of Stages for Graphics Pipelines 1013 1014If tessellation shader stages are omitted, the tessellation shading and 1015fixed-function stages of the pipeline are skipped. 1016 1017If a geometry shader is omitted, the geometry shading stage is skipped. 1018 1019If a fragment shader is omitted, the results of fragment processing are 1020undefined. 1021Specifically, any fragment color outputs are considered to have undefined 1022values, and the fragment depth is considered to be unmodified. 1023This can: be useful for depth-only rendering. 1024 1025Presence of a shader stage in a pipeline is indicated by including a valid 1026sname:VkPipelineShaderStageCreateInfo with pname:module and pname:pName 1027selecting an entry point from a shader module, where that entry point is 1028valid for the stage specified by pname:stage. 1029 1030Presence of some of the fixed-function stages in the pipeline is implicitly 1031derived from enabled shaders and provided state. 1032For example, the fixed-function tessellator is always present when the 1033pipeline has valid Tessellation Control and Tessellation Evaluation shaders. 1034 1035.For example: 1036 * Depth/stencil-only rendering in a subpass with no color attachments 1037 ** Active Pipeline Shader Stages 1038 *** Vertex Shader 1039 ** Required: Fixed-Function Pipeline Stages 1040 *** slink:VkPipelineVertexInputStateCreateInfo 1041 *** slink:VkPipelineInputAssemblyStateCreateInfo 1042 *** slink:VkPipelineViewportStateCreateInfo 1043 *** slink:VkPipelineRasterizationStateCreateInfo 1044 *** slink:VkPipelineMultisampleStateCreateInfo 1045 *** slink:VkPipelineDepthStencilStateCreateInfo 1046 * Color-only rendering in a subpass with no depth/stencil attachment 1047 ** Active Pipeline Shader Stages 1048 *** Vertex Shader 1049 *** Fragment Shader 1050 ** Required: Fixed-Function Pipeline Stages 1051 *** slink:VkPipelineVertexInputStateCreateInfo 1052 *** slink:VkPipelineInputAssemblyStateCreateInfo 1053 *** slink:VkPipelineViewportStateCreateInfo 1054 *** slink:VkPipelineRasterizationStateCreateInfo 1055 *** slink:VkPipelineMultisampleStateCreateInfo 1056 *** slink:VkPipelineColorBlendStateCreateInfo 1057 * Rendering pipeline with tessellation and geometry shaders 1058 ** Active Pipeline Shader Stages 1059 *** Vertex Shader 1060 *** Tessellation Control Shader 1061 *** Tessellation Evaluation Shader 1062 *** Geometry Shader 1063 *** Fragment Shader 1064 ** Required: Fixed-Function Pipeline Stages 1065 *** slink:VkPipelineVertexInputStateCreateInfo 1066 *** slink:VkPipelineInputAssemblyStateCreateInfo 1067 *** slink:VkPipelineTessellationStateCreateInfo 1068 *** slink:VkPipelineViewportStateCreateInfo 1069 *** slink:VkPipelineRasterizationStateCreateInfo 1070 *** slink:VkPipelineMultisampleStateCreateInfo 1071 *** slink:VkPipelineDepthStencilStateCreateInfo 1072 *** slink:VkPipelineColorBlendStateCreateInfo 1073 1074 1075[[pipelines-destruction]] 1076== Pipeline destruction 1077 1078[open,refpage='vkDestroyPipeline',desc='Destroy a pipeline object',type='protos'] 1079-- 1080 1081To destroy a graphics or compute pipeline, call: 1082 1083include::../api/protos/vkDestroyPipeline.txt[] 1084 1085 * pname:device is the logical device that destroys the pipeline. 1086 * pname:pipeline is the handle of the pipeline to destroy. 1087 * pname:pAllocator controls host memory allocation as described in the 1088 <<memory-allocation, Memory Allocation>> chapter. 1089 1090.Valid Usage 1091**** 1092 * [[VUID-vkDestroyPipeline-pipeline-00765]] 1093 All submitted commands that refer to pname:pipeline must: have completed 1094 execution 1095 * [[VUID-vkDestroyPipeline-pipeline-00766]] 1096 If sname:VkAllocationCallbacks were provided when pname:pipeline was 1097 created, a compatible set of callbacks must: be provided here 1098 * [[VUID-vkDestroyPipeline-pipeline-00767]] 1099 If no sname:VkAllocationCallbacks were provided when pname:pipeline was 1100 created, pname:pAllocator must: be `NULL` 1101**** 1102 1103include::../validity/protos/vkDestroyPipeline.txt[] 1104-- 1105 1106 1107[[pipelines-multiple]] 1108== Multiple Pipeline Creation 1109 1110Multiple pipelines can: be created simultaneously by passing an array of 1111sname:VkGraphicsPipelineCreateInfo or sname:VkComputePipelineCreateInfo 1112structures into the flink:vkCreateGraphicsPipelines and 1113flink:vkCreateComputePipelines commands, respectively. 1114Applications can: group together similar pipelines to be created in a single 1115call, and implementations are encouraged to look for reuse opportunities 1116within a group-create. 1117 1118When an application attempts to create many pipelines in a single command, 1119it is possible that some subset may: fail creation. 1120In that case, the corresponding entries in the pname:pPipelines output array 1121will be filled with dlink:VK_NULL_HANDLE values. 1122If any pipeline fails creation (for example, due to out of memory errors), 1123the ftext:vkCreate*Pipelines commands will return an error code. 1124The implementation will attempt to create all pipelines, and only return 1125dlink:VK_NULL_HANDLE values for those that actually failed. 1126 1127 1128[[pipelines-pipeline-derivatives]] 1129== Pipeline Derivatives 1130 1131A pipeline derivative is a child pipeline created from a parent pipeline, 1132where the child and parent are expected to have much commonality. 1133The goal of derivative pipelines is that they be cheaper to create using the 1134parent as a starting point, and that it be more efficient (on either host or 1135device) to switch/bind between children of the same parent. 1136 1137A derivative pipeline is created by setting the 1138ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag in the 1139stext:Vk*PipelineCreateInfo structure. 1140If this is set, then exactly one of pname:basePipelineHandle or 1141pname:basePipelineIndex members of the structure must: have a valid 1142handle/index, and specifies the parent pipeline. 1143If pname:basePipelineHandle is used, the parent pipeline must: have already 1144been created. 1145If pname:basePipelineIndex is used, then the parent is being created in the 1146same command. 1147dlink:VK_NULL_HANDLE acts as the invalid handle for 1148pname:basePipelineHandle, and -1 is the invalid index for 1149pname:basePipelineIndex. 1150If pname:basePipelineIndex is used, the base pipeline must: appear earlier 1151in the array. 1152The base pipeline must: have been created with the 1153ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set. 1154 1155 1156[[pipelines-cache]] 1157== Pipeline Cache 1158 1159[open,refpage='VkPipelineCache',desc='Opaque handle to a pipeline cache object',type='handles'] 1160-- 1161 1162Pipeline cache objects allow the result of pipeline construction to be 1163reused between pipelines and between runs of an application. 1164Reuse between pipelines is achieved by passing the same pipeline cache 1165object when creating multiple related pipelines. 1166Reuse across runs of an application is achieved by retrieving pipeline cache 1167contents in one run of an application, saving the contents, and using them 1168to preinitialize a pipeline cache on a subsequent run. 1169The contents of the pipeline cache objects are managed by the 1170implementation. 1171Applications can: manage the host memory consumed by a pipeline cache object 1172and control the amount of data retrieved from a pipeline cache object. 1173 1174Pipeline cache objects are represented by sname:VkPipelineCache handles: 1175 1176include::../api/handles/VkPipelineCache.txt[] 1177 1178-- 1179 1180[open,refpage='vkCreatePipelineCache',desc='Creates a new pipeline cache',type='protos'] 1181-- 1182 1183To create pipeline cache objects, call: 1184 1185include::../api/protos/vkCreatePipelineCache.txt[] 1186 1187 * pname:device is the logical device that creates the pipeline cache 1188 object. 1189 * pname:pCreateInfo is a pointer to a slink:VkPipelineCacheCreateInfo 1190 structure that contains the initial parameters for the pipeline cache 1191 object. 1192 * pname:pAllocator controls host memory allocation as described in the 1193 <<memory-allocation, Memory Allocation>> chapter. 1194 * pname:pPipelineCache is a pointer to a slink:VkPipelineCache handle in 1195 which the resulting pipeline cache object is returned. 1196 1197[NOTE] 1198.Note 1199==== 1200Applications can: track and manage the total host memory size of a pipeline 1201cache object using the pname:pAllocator. 1202Applications can: limit the amount of data retrieved from a pipeline cache 1203object in fname:vkGetPipelineCacheData. 1204Implementations should: not internally limit the total number of entries 1205added to a pipeline cache object or the total host memory consumed. 1206==== 1207 1208Once created, a pipeline cache can: be passed to the 1209fname:vkCreateGraphicsPipelines and fname:vkCreateComputePipelines commands. 1210If the pipeline cache passed into these commands is not 1211dlink:VK_NULL_HANDLE, the implementation will query it for possible reuse 1212opportunities and update it with new content. 1213The use of the pipeline cache object in these commands is internally 1214synchronized, and the same pipeline cache object can: be used in multiple 1215threads simultaneously. 1216 1217[NOTE] 1218.Note 1219==== 1220Implementations should: make every effort to limit any critical sections to 1221the actual accesses to the cache, which is expected to be significantly 1222shorter than the duration of the fname:vkCreateGraphicsPipelines and 1223fname:vkCreateComputePipelines commands. 1224==== 1225 1226include::../validity/protos/vkCreatePipelineCache.txt[] 1227-- 1228 1229[open,refpage='VkPipelineCacheCreateInfo',desc='Structure specifying parameters of a newly created pipeline cache',type='structs'] 1230-- 1231 1232The sname:VkPipelineCacheCreateInfo structure is defined as: 1233 1234include::../api/structs/VkPipelineCacheCreateInfo.txt[] 1235 1236 * pname:sType is the type of this structure. 1237 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1238 * pname:flags is reserved for future use. 1239 * pname:initialDataSize is the number of bytes in pname:pInitialData. 1240 If pname:initialDataSize is zero, the pipeline cache will initially be 1241 empty. 1242 * pname:pInitialData is a pointer to previously retrieved pipeline cache 1243 data. 1244 If the pipeline cache data is incompatible (as defined below) with the 1245 device, the pipeline cache will be initially empty. 1246 If pname:initialDataSize is zero, pname:pInitialData is ignored. 1247 1248.Valid Usage 1249**** 1250 * [[VUID-VkPipelineCacheCreateInfo-initialDataSize-00768]] 1251 If pname:initialDataSize is not `0`, it must: be equal to the size of 1252 pname:pInitialData, as returned by fname:vkGetPipelineCacheData when 1253 pname:pInitialData was originally retrieved 1254 * [[VUID-VkPipelineCacheCreateInfo-initialDataSize-00769]] 1255 If pname:initialDataSize is not `0`, pname:pInitialData must: have been 1256 retrieved from a previous call to fname:vkGetPipelineCacheData 1257**** 1258 1259include::../validity/structs/VkPipelineCacheCreateInfo.txt[] 1260-- 1261 1262[open,refpage='VkPipelineCacheCreateFlags',desc='Reserved for future use',type='enums'] 1263-- 1264include::../api/flags/VkPipelineCacheCreateFlags.txt[] 1265 1266sname:VkPipelineCacheCreateFlags is a bitmask type for setting a mask, but 1267is currently reserved for future use. 1268-- 1269 1270[open,refpage='vkMergePipelineCaches',desc='Combine the data stores of pipeline caches',type='protos'] 1271-- 1272 1273Pipeline cache objects can: be merged using the command: 1274 1275include::../api/protos/vkMergePipelineCaches.txt[] 1276 1277 * pname:device is the logical device that owns the pipeline cache objects. 1278 * pname:dstCache is the handle of the pipeline cache to merge results 1279 into. 1280 * pname:srcCacheCount is the length of the pname:pSrcCaches array. 1281 * pname:pSrcCaches is an array of pipeline cache handles, which will be 1282 merged into pname:dstCache. 1283 The previous contents of pname:dstCache are included after the merge. 1284 1285[NOTE] 1286.Note 1287==== 1288The details of the merge operation are implementation dependent, but 1289implementations should: merge the contents of the specified pipelines and 1290prune duplicate entries. 1291==== 1292 1293.Valid Usage 1294**** 1295 * [[VUID-vkMergePipelineCaches-dstCache-00770]] 1296 pname:dstCache must: not appear in the list of source caches 1297**** 1298 1299include::../validity/protos/vkMergePipelineCaches.txt[] 1300-- 1301 1302[open,refpage='vkGetPipelineCacheData',desc='Get the data store from a pipeline cache',type='protos'] 1303-- 1304 1305Data can: be retrieved from a pipeline cache object using the command: 1306 1307include::../api/protos/vkGetPipelineCacheData.txt[] 1308 1309 * pname:device is the logical device that owns the pipeline cache. 1310 * pname:pipelineCache is the pipeline cache to retrieve data from. 1311 * pname:pDataSize is a pointer to a value related to the amount of data in 1312 the pipeline cache, as described below. 1313 * pname:pData is either `NULL` or a pointer to a buffer. 1314 1315If pname:pData is `NULL`, then the maximum size of the data that can: be 1316retrieved from the pipeline cache, in bytes, is returned in pname:pDataSize. 1317Otherwise, pname:pDataSize must: point to a variable set by the user to the 1318size of the buffer, in bytes, pointed to by pname:pData, and on return the 1319variable is overwritten with the amount of data actually written to 1320pname:pData. 1321 1322If pname:pDataSize is less than the maximum size that can: be retrieved by 1323the pipeline cache, at most pname:pDataSize bytes will be written to 1324pname:pData, and fname:vkGetPipelineCacheData will return 1325ename:VK_INCOMPLETE. 1326Any data written to pname:pData is valid and can: be provided as the 1327pname:pInitialData member of the sname:VkPipelineCacheCreateInfo structure 1328passed to fname:vkCreatePipelineCache. 1329 1330Two calls to fname:vkGetPipelineCacheData with the same parameters must: 1331retrieve the same data unless a command that modifies the contents of the 1332cache is called between them. 1333 1334[[pipelines-cache-header]] 1335Applications can: store the data retrieved from the pipeline cache, and use 1336these data, possibly in a future run of the application, to populate new 1337pipeline cache objects. 1338The results of pipeline compiles, however, may: depend on the vendor ID, 1339device ID, driver version, and other details of the device. 1340To enable applications to detect when previously retrieved data is 1341incompatible with the device, the initial bytes written to pname:pData must: 1342be a header consisting of the following members: 1343 1344.Layout for pipeline cache header version ename:VK_PIPELINE_CACHE_HEADER_VERSION_ONE 1345[width="85%",cols="8%,21%,71%",options="header"] 1346|==== 1347| Offset | Size | Meaning 1348| 0 | 4 | length in bytes of the entire pipeline cache header 1349 written as a stream of bytes, with the least 1350 significant byte first 1351| 4 | 4 | a elink:VkPipelineCacheHeaderVersion value 1352 written as a stream of bytes, with the least 1353 significant byte first 1354| 8 | 4 | a vendor ID equal to 1355 sname:VkPhysicalDeviceProperties::pname:vendorID 1356 written as a stream of bytes, with the least 1357 significant byte first 1358| 12 | 4 | a device ID equal to 1359 sname:VkPhysicalDeviceProperties::pname:deviceID 1360 written as a stream of bytes, with the least 1361 significant byte first 1362| 16 | ename:VK_UUID_SIZE | a pipeline cache ID equal to 1363 sname:VkPhysicalDeviceProperties::pname:pipelineCacheUUID 1364|==== 1365 1366The first four bytes encode the length of the entire pipeline cache header, 1367in bytes. 1368This value includes all fields in the header including the pipeline cache 1369version field and the size of the length field. 1370 1371The next four bytes encode the pipeline cache version, as described for 1372elink:VkPipelineCacheHeaderVersion. 1373A consumer of the pipeline cache should: use the cache version to interpret 1374the remainder of the cache header. 1375 1376If pname:pDataSize is less than what is necessary to store this header, 1377nothing will be written to pname:pData and zero will be written to 1378pname:pDataSize. 1379 1380include::../validity/protos/vkGetPipelineCacheData.txt[] 1381-- 1382 1383[open,refpage='VkPipelineCacheHeaderVersion',desc='Encode pipeline cache version',type='enums',xrefs='vkCreatePipelineCache vkGetPipelineCacheData'] 1384-- 1385Possible values of the second group of four bytes in the header returned by 1386flink:vkGetPipelineCacheData, encoding the pipeline cache version, are: 1387 1388include::../api/enums/VkPipelineCacheHeaderVersion.txt[] 1389 1390 * ename:VK_PIPELINE_CACHE_HEADER_VERSION_ONE specifies version one of the 1391 pipeline cache. 1392-- 1393 1394[open,refpage='vkDestroyPipelineCache',desc='Destroy a pipeline cache object',type='protos'] 1395-- 1396 1397To destroy a pipeline cache, call: 1398 1399include::../api/protos/vkDestroyPipelineCache.txt[] 1400 1401 * pname:device is the logical device that destroys the pipeline cache 1402 object. 1403 * pname:pipelineCache is the handle of the pipeline cache to destroy. 1404 * pname:pAllocator controls host memory allocation as described in the 1405 <<memory-allocation, Memory Allocation>> chapter. 1406 1407.Valid Usage 1408**** 1409 * [[VUID-vkDestroyPipelineCache-pipelineCache-00771]] 1410 If sname:VkAllocationCallbacks were provided when pname:pipelineCache 1411 was created, a compatible set of callbacks must: be provided here 1412 * [[VUID-vkDestroyPipelineCache-pipelineCache-00772]] 1413 If no sname:VkAllocationCallbacks were provided when pname:pipelineCache 1414 was created, pname:pAllocator must: be `NULL` 1415**** 1416 1417include::../validity/protos/vkDestroyPipelineCache.txt[] 1418-- 1419 1420 1421[[pipelines-specialization-constants]] 1422== Specialization Constants 1423 1424Specialization constants are a mechanism whereby constants in a SPIR-V 1425module can: have their constant value specified at the time the 1426sname:VkPipeline is created. 1427This allows a SPIR-V module to have constants that can: be modified while 1428executing an application that uses the Vulkan API. 1429 1430[NOTE] 1431.Note 1432==== 1433Specialization constants are useful to allow a compute shader to have its 1434local workgroup size changed at runtime by the user, for example. 1435==== 1436 1437Each instance of the sname:VkPipelineShaderStageCreateInfo structure 1438contains a parameter pname:pSpecializationInfo, which can: be `NULL` to 1439indicate no specialization constants, or point to a 1440sname:VkSpecializationInfo structure. 1441 1442[open,refpage='VkSpecializationInfo',desc='Structure specifying specialization info',type='structs'] 1443-- 1444 1445The sname:VkSpecializationInfo structure is defined as: 1446 1447include::../api/structs/VkSpecializationInfo.txt[] 1448 1449 * pname:mapEntryCount is the number of entries in the pname:pMapEntries 1450 array. 1451 * pname:pMapEntries is a pointer to an array of 1452 sname:VkSpecializationMapEntry which maps constant IDs to offsets in 1453 pname:pData. 1454 * pname:dataSize is the byte size of the pname:pData buffer. 1455 * pname:pData contains the actual constant values to specialize with. 1456 1457pname:pMapEntries points to a structure of type 1458slink:VkSpecializationMapEntry. 1459 1460.Valid Usage 1461**** 1462 * [[VUID-VkSpecializationInfo-offset-00773]] 1463 The pname:offset member of each element of pname:pMapEntries must: be 1464 less than pname:dataSize 1465 * [[VUID-VkSpecializationInfo-pMapEntries-00774]] 1466 The pname:size member of each element of pname:pMapEntries must: be less 1467 than or equal to pname:dataSize minus pname:offset 1468**** 1469 1470include::../validity/structs/VkSpecializationInfo.txt[] 1471-- 1472 1473[open,refpage='VkSpecializationMapEntry',desc='Structure specifying a specialization map entry',type='structs'] 1474-- 1475 1476The sname:VkSpecializationMapEntry structure is defined as: 1477 1478include::../api/structs/VkSpecializationMapEntry.txt[] 1479 1480 * pname:constantID is the ID of the specialization constant in SPIR-V. 1481 * pname:offset is the byte offset of the specialization constant value 1482 within the supplied data buffer. 1483 * pname:size is the byte size of the specialization constant value within 1484 the supplied data buffer. 1485 1486If a pname:constantID value is not a specialization constant ID used in the 1487shader, that map entry does not affect the behavior of the pipeline. 1488 1489.Valid Usage 1490**** 1491 * [[VUID-VkSpecializationMapEntry-constantID-00776]] 1492 For a pname:constantID specialization constant declared in a shader, 1493 pname:size must: match the byte size of the pname:constantID. 1494 If the specialization constant is of type code:boolean, pname:size must: 1495 be the byte size of basetype:VkBool32 1496**** 1497 1498include::../validity/structs/VkSpecializationMapEntry.txt[] 1499-- 1500 1501In human readable SPIR-V: 1502 1503[source,glsl] 1504--------------------------------------------------- 1505OpDecorate %x SpecId 13 ; decorate .x component of WorkgroupSize with ID 13 1506OpDecorate %y SpecId 42 ; decorate .y component of WorkgroupSize with ID 42 1507OpDecorate %z SpecId 3 ; decorate .z component of WorkgroupSize with ID 3 1508OpDecorate %wgsize BuiltIn WorkgroupSize ; decorate WorkgroupSize onto constant 1509%i32 = OpTypeInt 32 0 ; declare an unsigned 32-bit type 1510%uvec3 = OpTypeVector %i32 3 ; declare a 3 element vector type of unsigned 32-bit 1511%x = OpSpecConstant %i32 1 ; declare the .x component of WorkgroupSize 1512%y = OpSpecConstant %i32 1 ; declare the .y component of WorkgroupSize 1513%z = OpSpecConstant %i32 1 ; declare the .z component of WorkgroupSize 1514%wgsize = OpSpecConstantComposite %uvec3 %x %y %z ; declare WorkgroupSize 1515--------------------------------------------------- 1516 1517From the above we have three specialization constants, one for each of the 1518x, y & z elements of the WorkgroupSize vector. 1519 1520Now to specialize the above via the specialization constants mechanism: 1521 1522[source,c++] 1523--------------------------------------------------- 1524const VkSpecializationMapEntry entries[] = 1525{ 1526 { 1527 13, // constantID 1528 0 * sizeof(uint32_t), // offset 1529 sizeof(uint32_t) // size 1530 }, 1531 { 1532 42, // constantID 1533 1 * sizeof(uint32_t), // offset 1534 sizeof(uint32_t) // size 1535 }, 1536 { 1537 3, // constantID 1538 2 * sizeof(uint32_t), // offset 1539 sizeof(uint32_t) // size 1540 } 1541}; 1542 1543const uint32_t data[] = { 16, 8, 4 }; // our workgroup size is 16x8x4 1544 1545const VkSpecializationInfo info = 1546{ 1547 3, // mapEntryCount 1548 entries, // pMapEntries 1549 3 * sizeof(uint32_t), // dataSize 1550 data, // pData 1551}; 1552--------------------------------------------------- 1553 1554Then when calling flink:vkCreateComputePipelines, and passing the 1555sname:VkSpecializationInfo we defined as the pname:pSpecializationInfo 1556parameter of slink:VkPipelineShaderStageCreateInfo, we will create a compute 1557pipeline with the runtime specified local workgroup size. 1558 1559Another example would be that an application has a SPIR-V module that has 1560some platform-dependent constants they wish to use. 1561 1562In human readable SPIR-V: 1563 1564// [source,glsl] 1565[source,glsl] 1566--------------------------------------------------- 1567OpDecorate %1 SpecId 0 ; decorate our signed 32-bit integer constant 1568OpDecorate %2 SpecId 12 ; decorate our 32-bit floating-point constant 1569%i32 = OpTypeInt 32 1 ; declare a signed 32-bit type 1570%float = OpTypeFloat 32 ; declare a 32-bit floating-point type 1571%1 = OpSpecConstant %i32 -1 ; some signed 32-bit integer constant 1572%2 = OpSpecConstant %float 0.5 ; some 32-bit floating-point constant 1573--------------------------------------------------- 1574 1575From the above we have two specialization constants, one is a signed 32-bit 1576integer and the second is a 32-bit floating-point. 1577 1578Now to specialize the above via the specialization constants mechanism: 1579 1580[source,c++] 1581--------------------------------------------------- 1582struct SpecializationData { 1583 int32_t data0; 1584 float data1; 1585}; 1586 1587const VkSpecializationMapEntry entries[] = 1588{ 1589 { 1590 0, // constantID 1591 offsetof(SpecializationData, data0), // offset 1592 sizeof(SpecializationData::data0) // size 1593 }, 1594 { 1595 12, // constantID 1596 offsetof(SpecializationData, data1), // offset 1597 sizeof(SpecializationData::data1) // size 1598 } 1599}; 1600 1601SpecializationData data; 1602data.data0 = -42; // set the data for the 32-bit integer 1603data.data1 = 42.0f; // set the data for the 32-bit floating-point 1604 1605const VkSpecializationInfo info = 1606{ 1607 2, // mapEntryCount 1608 entries, // pMapEntries 1609 sizeof(data), // dataSize 1610 &data, // pData 1611}; 1612--------------------------------------------------- 1613 1614It is legal for a SPIR-V module with specializations to be compiled into a 1615pipeline where no specialization info was provided. 1616SPIR-V specialization constants contain default values such that if a 1617specialization is not provided, the default value will be used. 1618In the examples above, it would be valid for an application to only 1619specialize some of the specialization constants within the SPIR-V module, 1620and let the other constants use their default values encoded within the 1621OpSpecConstant declarations. 1622 1623 1624[[pipelines-binding]] 1625== Pipeline Binding 1626 1627[open,refpage='vkCmdBindPipeline',desc='Bind a pipeline object to a command buffer',type='protos'] 1628-- 1629 1630Once a pipeline has been created, it can: be bound to the command buffer 1631using the command: 1632 1633include::../api/protos/vkCmdBindPipeline.txt[] 1634 1635 * pname:commandBuffer is the command buffer that the pipeline will be 1636 bound to. 1637 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying 1638 whether to bind to the compute or graphics bind point. 1639 Binding one does not disturb the other. 1640 * pname:pipeline is the pipeline to be bound. 1641 1642Once bound, a pipeline binding affects subsequent graphics or compute 1643commands in the command buffer until a different pipeline is bound to the 1644bind point. 1645The pipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE controls the 1646behavior of flink:vkCmdDispatch and flink:vkCmdDispatchIndirect. 1647The pipeline bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS controls the 1648behavior of all <<drawing, drawing commands>>. 1649No other commands are affected by the pipeline state. 1650 1651.Valid Usage 1652**** 1653 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-00777]] 1654 If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE, the 1655 sname:VkCommandPool that pname:commandBuffer was allocated from must: 1656 support compute operations 1657 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-00778]] 1658 If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_GRAPHICS, the 1659 sname:VkCommandPool that pname:commandBuffer was allocated from must: 1660 support graphics operations 1661 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-00779]] 1662 If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE, 1663 pname:pipeline must: be a compute pipeline 1664 * [[VUID-vkCmdBindPipeline-pipelineBindPoint-00780]] 1665 If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_GRAPHICS, 1666 pname:pipeline must: be a graphics pipeline 1667 * [[VUID-vkCmdBindPipeline-pipeline-00781]] 1668 If the <<features-features-variableMultisampleRate,variable multisample 1669 rate>> feature is not supported, pname:pipeline is a graphics pipeline, 1670 the current subpass has no attachments, and this is not the first call 1671 to this function with a graphics pipeline after transitioning to the 1672 current subpass, then the sample count specified by this pipeline must: 1673 match that set in the previous pipeline 1674ifdef::VK_EXT_sample_locations[] 1675 * [[VUID-vkCmdBindPipeline-variableSampleLocations-01525]] 1676 If 1677 slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations 1678 is ename:VK_FALSE, and pname:pipeline is a graphics pipeline created 1679 with a slink:VkPipelineSampleLocationsStateCreateInfoEXT structure 1680 having its pname:sampleLocationsEnable member set to ename:VK_TRUE but 1681 without ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT enabled then the 1682 current render pass instance must: have been begun by specifying a 1683 slink:VkRenderPassSampleLocationsBeginInfoEXT structure whose 1684 pname:pPostSubpassSampleLocations member contains an element with a 1685 pname:subpassIndex matching the current subpass index and the 1686 pname:sampleLocationsInfo member of that element must: match the 1687 pname:sampleLocationsInfo specified in 1688 slink:VkPipelineSampleLocationsStateCreateInfoEXT when the pipeline was 1689 created 1690endif::VK_EXT_sample_locations[] 1691**** 1692 1693include::../validity/protos/vkCmdBindPipeline.txt[] 1694-- 1695 1696[open,refpage='VkPipelineBindPoint',desc='Specify the bind point of a pipeline object to a command buffer',type='enums'] 1697-- 1698 1699Possible values of flink:vkCmdBindPipeline::pname:pipelineBindPoint, 1700specifying the bind point of a pipeline object, are: 1701 1702include::../api/enums/VkPipelineBindPoint.txt[] 1703 1704 * ename:VK_PIPELINE_BIND_POINT_COMPUTE specifies binding as a compute 1705 pipeline. 1706 * ename:VK_PIPELINE_BIND_POINT_GRAPHICS specifies binding as a graphics 1707 pipeline. 1708 1709-- 1710 1711 1712[[pipelines-dynamic-state]] 1713== Dynamic State 1714 1715When a pipeline object is bound, any pipeline object state that is not 1716specified as dynamic is applied to the command buffer state. 1717Pipeline object state that is specified as dynamic is not applied to the 1718command buffer state at this time. 1719Instead, dynamic state can: be modified at any time and persists for the 1720lifetime of the command buffer, or until modified by another dynamic state 1721setting command or another pipeline bind. 1722 1723When a pipeline object is bound, the following applies to each state 1724parameter: 1725 1726 * If the state is not specified as dynamic in the new pipeline object, 1727 then that command buffer state is overwritten by the state in the new 1728 pipeline object. 1729 * If the state is specified as dynamic in both the new and the previous 1730 pipeline object, then that command buffer state is not disturbed. 1731 * If the state is specified as dynamic in the new pipeline object but is 1732 not specified as dynamic in the previous pipeline object, then that 1733 command buffer state becomes undefined. 1734 If the state is an array, then the entire array becomes undefined. 1735 * If the state is an array specified as dynamic in both the new and the 1736 previous pipeline object, and the array size is not the same in both 1737 pipeline objects, then that command buffer state becomes undefined. 1738 1739Dynamic state setting commands must: not be issued for state that is not 1740specified as dynamic in the bound pipeline object. 1741 1742Dynamic state that does not affect the result of operations can: be left 1743undefined. 1744 1745[NOTE] 1746.Note 1747==== 1748For example, if blending is disabled by the pipeline object state then the 1749dynamic color blend constants do not need to be specified in the command 1750buffer, even if this state is specified as dynamic in the pipeline object. 1751==== 1752 1753ifdef::VK_AMD_shader_info[] 1754include::VK_AMD_shader_info.txt[] 1755endif::VK_AMD_shader_info[] 1756
