1// Copyright 2015-2021 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[commandbuffers]] 6= Command Buffers 7 8[open,refpage='VkCommandBuffer',desc='Opaque handle to a command buffer object',type='handles'] 9-- 10Command buffers are objects used to record commands which can: be 11subsequently submitted to a device queue for execution. 12There are two levels of command buffers - _primary command buffers_, which 13can: execute secondary command buffers, and which are submitted to queues, 14and _secondary command buffers_, which can: be executed by primary command 15buffers, and which are not directly submitted to queues. 16 17Command buffers are represented by sname:VkCommandBuffer handles: 18 19include::{generated}/api/handles/VkCommandBuffer.txt[] 20-- 21 22Recorded commands include commands to bind pipelines and descriptor sets to 23the command buffer, commands to modify dynamic state, commands to draw (for 24graphics rendering), commands to dispatch (for compute), commands to execute 25secondary command buffers (for primary command buffers only), commands to 26copy buffers and images, and other commands. 27 28[[commandbuffers-statereset]] 29Each command buffer manages state independently of other command buffers. 30There is no inheritance of state across primary and secondary command 31buffers, or between secondary command buffers. 32When a command buffer begins recording, all state in that command buffer is 33undefined:. 34When secondary command buffer(s) are recorded to execute on a primary 35command buffer, the secondary command buffer inherits no state from the 36primary command buffer, and all state of the primary command buffer is 37undefined: after an execute secondary command buffer command is recorded. 38There is one exception to this rule - if the primary command buffer is 39inside a render pass instance, then the render pass and subpass state is not 40disturbed by executing secondary command buffers. 41For state dependent commands (such as draws and dispatches), any state 42consumed by those commands must: not be undefined:. 43 44ifdef::VK_NV_inherited_viewport_scissor[] 45slink:VkCommandBufferInheritanceViewportScissorInfoNV defines an exception 46allowing limited inheritance of dynamic viewport and scissor state. 47endif::VK_NV_inherited_viewport_scissor[] 48 49Unless otherwise specified, and without explicit synchronization, the 50various commands submitted to a queue via command buffers may: execute in 51arbitrary order relative to each other, and/or concurrently. 52Also, the memory side effects of those commands may: not be directly visible 53to other commands without explicit memory dependencies. 54This is true within a command buffer, and across command buffers submitted 55to a given queue. 56See <<synchronization, the synchronization chapter>> for information on 57<<synchronization-implicit, implicit>> and explicit synchronization between 58commands. 59 60 61[[commandbuffers-lifecycle]] 62== Command Buffer Lifecycle 63 64Each command buffer is always in one of the following states: 65 66Initial:: 67 When a command buffer is <<vkAllocateCommandBuffers, allocated>>, it is 68 in the _initial state_. 69 Some commands are able to _reset_ a command buffer (or a set of command 70 buffers) back to this state from any of the executable, recording or 71 invalid state. 72 Command buffers in the initial state can: only be moved to the recording 73 state, or freed. 74Recording:: 75 flink:vkBeginCommandBuffer changes the state of a command buffer from 76 the initial state to the _recording state_. 77 Once a command buffer is in the recording state, ftext:vkCmd* commands 78 can: be used to record to the command buffer. 79Executable:: 80 flink:vkEndCommandBuffer ends the recording of a command buffer, and 81 moves it from the recording state to the _executable state_. 82 Executable command buffers can: be <<commandbuffers-submission, 83 submitted>>, reset, or <<commandbuffers-secondary, recorded to another 84 command buffer>>. 85Pending:: 86 <<commandbuffers-submission, Queue submission>> of a command buffer 87 changes the state of a command buffer from the executable state to the 88 _pending state_. 89 Whilst in the pending state, applications must: not attempt to modify 90 the command buffer in any way - as the device may: be processing the 91 commands recorded to it. 92 Once execution of a command buffer completes, the command buffer either 93 reverts back to the _executable state_, or if it was recorded with 94 ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT, it moves to the 95 _invalid state_. 96 A <<synchronization, synchronization>> command should: be used to detect 97 when this occurs. 98Invalid:: 99 Some operations, such as <<fundamentals-objectmodel-lifetime-cmdbuffers, 100 modifying or deleting a resource>> that was used in a command recorded 101 to a command buffer, will transition the state of that command buffer 102 into the _invalid state_. 103 Command buffers in the invalid state can: only be reset or freed. 104 105[[commandbuffer-lifecycle-diagram]] 106image::{images}/commandbuffer_lifecycle.svg[title="Lifecycle of a command buffer",align="center",opts="{imageopts}"] 107 108Any given command that operates on a command buffer has its own requirements 109on what state a command buffer must: be in, which are detailed in the valid 110usage constraints for that command. 111 112Resetting a command buffer is an operation that discards any previously 113recorded commands and puts a command buffer in the _initial state_. 114Resetting occurs as a result of flink:vkResetCommandBuffer or 115flink:vkResetCommandPool, or as part of flink:vkBeginCommandBuffer (which 116additionally puts the command buffer in the _recording state_). 117 118<<commandbuffers-secondary, Secondary command buffers>> can: be recorded to 119a primary command buffer via flink:vkCmdExecuteCommands. 120This partially ties the lifecycle of the two command buffers together - if 121the primary is submitted to a queue, both the primary and any secondaries 122recorded to it move to the _pending state_. 123Once execution of the primary completes, so it does for any secondary 124recorded within it. 125After all executions of each command buffer complete, they each move to 126their appropriate completion state (either to the _executable state_ or the 127_invalid state_, as specified above). 128 129If a secondary moves to the _invalid state_ or the _initial state_, then all 130primary buffers it is recorded in move to the _invalid state_. 131A primary moving to any other state does not affect the state of a secondary 132recorded in it. 133 134[NOTE] 135.Note 136==== 137Resetting or freeing a primary command buffer removes the lifecycle linkage 138to all secondary command buffers that were recorded into it. 139==== 140 141 142[[commandbuffers-pools]] 143== Command Pools 144 145[open,refpage='VkCommandPool',desc='Opaque handle to a command pool object',type='handles'] 146-- 147Command pools are opaque objects that command buffer memory is allocated 148from, and which allow the implementation to amortize the cost of resource 149creation across multiple command buffers. 150Command pools are externally synchronized, meaning that a command pool must: 151not be used concurrently in multiple threads. 152That includes use via recording commands on any command buffers allocated 153from the pool, as well as operations that allocate, free, and reset command 154buffers or the pool itself. 155 156Command pools are represented by sname:VkCommandPool handles: 157 158include::{generated}/api/handles/VkCommandPool.txt[] 159-- 160 161[open,refpage='vkCreateCommandPool',desc='Create a new command pool object',type='protos'] 162-- 163To create a command pool, call: 164 165include::{generated}/api/protos/vkCreateCommandPool.txt[] 166 167 * pname:device is the logical device that creates the command pool. 168 * pname:pCreateInfo is a pointer to a slink:VkCommandPoolCreateInfo 169 structure specifying the state of the command pool object. 170 * pname:pAllocator controls host memory allocation as described in the 171 <<memory-allocation, Memory Allocation>> chapter. 172 * pname:pCommandPool is a pointer to a slink:VkCommandPool handle in which 173 the created pool is returned. 174 175.Valid Usage 176**** 177 * [[VUID-vkCreateCommandPool-queueFamilyIndex-01937]] 178 pname:pCreateInfo->queueFamilyIndex must: be the index of a queue family 179 available in the logical device pname:device 180**** 181 182include::{generated}/validity/protos/vkCreateCommandPool.txt[] 183-- 184 185[open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] 186-- 187The sname:VkCommandPoolCreateInfo structure is defined as: 188 189include::{generated}/api/structs/VkCommandPoolCreateInfo.txt[] 190 191 * pname:sType is the type of this structure. 192 * pname:pNext is `NULL` or a pointer to a structure extending this 193 structure. 194 * pname:flags is a bitmask of elink:VkCommandPoolCreateFlagBits indicating 195 usage behavior for the pool and command buffers allocated from it. 196 * pname:queueFamilyIndex designates a queue family as described in section 197 <<devsandqueues-queueprops,Queue Family Properties>>. 198 All command buffers allocated from this command pool must: be submitted 199 on queues from the same queue family. 200 201.Valid Usage 202**** 203ifdef::VK_VERSION_1_1[] 204 * [[VUID-VkCommandPoolCreateInfo-flags-02860]] 205 If the protected memory feature is not enabled, the 206 ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT bit of pname:flags must: not 207 be set 208endif::VK_VERSION_1_1[] 209**** 210 211include::{generated}/validity/structs/VkCommandPoolCreateInfo.txt[] 212-- 213 214[open,refpage='VkCommandPoolCreateFlagBits',desc='Bitmask specifying usage behavior for a command pool',type='enums'] 215-- 216Bits which can: be set in slink:VkCommandPoolCreateInfo::pname:flags to 217specify usage behavior for a command pool are: 218 219include::{generated}/api/enums/VkCommandPoolCreateFlagBits.txt[] 220 221 * ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT specifies that command 222 buffers allocated from the pool will be short-lived, meaning that they 223 will be reset or freed in a relatively short timeframe. 224 This flag may: be used by the implementation to control memory 225 allocation behavior within the pool. 226 * ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT allows any command 227 buffer allocated from a pool to be individually reset to the 228 <<commandbuffers-lifecycle, initial state>>; either by calling 229 flink:vkResetCommandBuffer, or via the implicit reset when calling 230 flink:vkBeginCommandBuffer. 231 If this flag is not set on a pool, then fname:vkResetCommandBuffer must: 232 not be called for any command buffer allocated from that pool. 233ifdef::VK_VERSION_1_1[] 234 * ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT specifies that command 235 buffers allocated from the pool are protected command buffers. 236endif::VK_VERSION_1_1[] 237-- 238 239[open,refpage='VkCommandPoolCreateFlags',desc='Bitmask of VkCommandPoolCreateFlagBits',type='flags'] 240-- 241include::{generated}/api/flags/VkCommandPoolCreateFlags.txt[] 242 243tname:VkCommandPoolCreateFlags is a bitmask type for setting a mask of zero 244or more elink:VkCommandPoolCreateFlagBits. 245-- 246 247ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 248[open,refpage='vkTrimCommandPool',desc='Trim a command pool',type='protos'] 249-- 250To trim a command pool, call: 251 252ifdef::VK_VERSION_1_1[] 253include::{generated}/api/protos/vkTrimCommandPool.txt[] 254endif::VK_VERSION_1_1[] 255 256ifdef::VK_VERSION_1_1+VK_KHR_maintenance1[or the equivalent command] 257 258ifdef::VK_KHR_maintenance1[] 259include::{generated}/api/protos/vkTrimCommandPoolKHR.txt[] 260endif::VK_KHR_maintenance1[] 261 262 * pname:device is the logical device that owns the command pool. 263 * pname:commandPool is the command pool to trim. 264 * pname:flags is reserved for future use. 265 266Trimming a command pool recycles unused memory from the command pool back to 267the system. 268Command buffers allocated from the pool are not affected by the command. 269 270[NOTE] 271.Note 272==== 273This command provides applications with some control over the internal 274memory allocations used by command pools. 275 276Unused memory normally arises from command buffers that have been recorded 277and later reset, such that they are no longer using the memory. 278On reset, a command buffer can return memory to its command pool, but the 279only way to release memory from a command pool to the system requires 280calling flink:vkResetCommandPool, which cannot be executed while any command 281buffers from that pool are still in use. 282Subsequent recording operations into command buffers will re-use this memory 283but since total memory requirements fluctuate over time, unused memory can 284accumulate. 285 286In this situation, trimming a command pool may: be useful to return unused 287memory back to the system, returning the total outstanding memory allocated 288by the pool back to a more "`average`" value. 289 290Implementations utilize many internal allocation strategies that make it 291impossible to guarantee that all unused memory is released back to the 292system. 293For instance, an implementation of a command pool may: involve allocating 294memory in bulk from the system and sub-allocating from that memory. 295In such an implementation any live command buffer that holds a reference to 296a bulk allocation would prevent that allocation from being freed, even if 297only a small proportion of the bulk allocation is in use. 298 299In most cases trimming will result in a reduction in allocated but unused 300memory, but it does not guarantee the "`ideal`" behavior. 301 302Trimming may: be an expensive operation, and should: not be called 303frequently. 304Trimming should: be treated as a way to relieve memory pressure after 305application-known points when there exists enough unused memory that the 306cost of trimming is "`worth`" it. 307==== 308 309include::{generated}/validity/protos/vkTrimCommandPool.txt[] 310-- 311 312[open,refpage='VkCommandPoolTrimFlags',desc='Reserved for future use',type='flags'] 313-- 314include::{generated}/api/flags/VkCommandPoolTrimFlags.txt[] 315 316ifdef::VK_KHR_maintenance1[] 317or the equivalent 318 319include::{generated}/api/flags/VkCommandPoolTrimFlagsKHR.txt[] 320endif::VK_KHR_maintenance1[] 321 322tname:VkCommandPoolTrimFlags is a bitmask type for setting a mask, but is 323currently reserved for future use. 324-- 325endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 326 327[open,refpage='vkResetCommandPool',desc='Reset a command pool',type='protos'] 328-- 329To reset a command pool, call: 330 331include::{generated}/api/protos/vkResetCommandPool.txt[] 332 333 * pname:device is the logical device that owns the command pool. 334 * pname:commandPool is the command pool to reset. 335 * pname:flags is a bitmask of elink:VkCommandPoolResetFlagBits controlling 336 the reset operation. 337 338Resetting a command pool recycles all of the resources from all of the 339command buffers allocated from the command pool back to the command pool. 340All command buffers that have been allocated from the command pool are put 341in the <<commandbuffers-lifecycle, initial state>>. 342 343Any primary command buffer allocated from another slink:VkCommandPool that 344is in the <<commandbuffers-lifecycle, recording or executable state>> and 345has a secondary command buffer allocated from pname:commandPool recorded 346into it, becomes <<commandbuffers-lifecycle, invalid>>. 347 348.Valid Usage 349**** 350 * [[VUID-vkResetCommandPool-commandPool-00040]] 351 All sname:VkCommandBuffer objects allocated from pname:commandPool must: 352 not be in the <<commandbuffers-lifecycle, pending state>> 353**** 354 355include::{generated}/validity/protos/vkResetCommandPool.txt[] 356-- 357 358[open,refpage='VkCommandPoolResetFlagBits',desc='Bitmask controlling behavior of a command pool reset',type='enums'] 359-- 360Bits which can: be set in flink:vkResetCommandPool::pname:flags to control 361the reset operation are: 362 363include::{generated}/api/enums/VkCommandPoolResetFlagBits.txt[] 364 365 * ename:VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT specifies that 366 resetting a command pool recycles all of the resources from the command 367 pool back to the system. 368-- 369 370[open,refpage='VkCommandPoolResetFlags',desc='Bitmask of VkCommandPoolResetFlagBits',type='flags'] 371-- 372include::{generated}/api/flags/VkCommandPoolResetFlags.txt[] 373 374tname:VkCommandPoolResetFlags is a bitmask type for setting a mask of zero 375or more elink:VkCommandPoolResetFlagBits. 376-- 377 378[open,refpage='vkDestroyCommandPool',desc='Destroy a command pool object',type='protos'] 379-- 380To destroy a command pool, call: 381 382include::{generated}/api/protos/vkDestroyCommandPool.txt[] 383 384 * pname:device is the logical device that destroys the command pool. 385 * pname:commandPool is the handle of the command pool to destroy. 386 * pname:pAllocator controls host memory allocation as described in the 387 <<memory-allocation, Memory Allocation>> chapter. 388 389When a pool is destroyed, all command buffers allocated from the pool are 390<<vkFreeCommandBuffers, freed>>. 391 392Any primary command buffer allocated from another slink:VkCommandPool that 393is in the <<commandbuffers-lifecycle, recording or executable state>> and 394has a secondary command buffer allocated from pname:commandPool recorded 395into it, becomes <<commandbuffers-lifecycle, invalid>>. 396 397.Valid Usage 398**** 399 * [[VUID-vkDestroyCommandPool-commandPool-00041]] 400 All sname:VkCommandBuffer objects allocated from pname:commandPool must: 401 not be in the <<commandbuffers-lifecycle, pending state>> 402 * [[VUID-vkDestroyCommandPool-commandPool-00042]] 403 If sname:VkAllocationCallbacks were provided when pname:commandPool was 404 created, a compatible set of callbacks must: be provided here 405 * [[VUID-vkDestroyCommandPool-commandPool-00043]] 406 If no sname:VkAllocationCallbacks were provided when pname:commandPool 407 was created, pname:pAllocator must: be `NULL` 408**** 409 410include::{generated}/validity/protos/vkDestroyCommandPool.txt[] 411-- 412 413 414[[commandbuffer-allocation]] 415== Command Buffer Allocation and Management 416 417[open,refpage='vkAllocateCommandBuffers',desc='Allocate command buffers from an existing command pool',type='protos'] 418-- 419To allocate command buffers, call: 420 421include::{generated}/api/protos/vkAllocateCommandBuffers.txt[] 422 423 * pname:device is the logical device that owns the command pool. 424 * pname:pAllocateInfo is a pointer to a sname:VkCommandBufferAllocateInfo 425 structure describing parameters of the allocation. 426 * pname:pCommandBuffers is a pointer to an array of slink:VkCommandBuffer 427 handles in which the resulting command buffer objects are returned. 428 The array must: be at least the length specified by the 429 pname:commandBufferCount member of pname:pAllocateInfo. 430 Each allocated command buffer begins in the initial state. 431 432ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 433fname:vkAllocateCommandBuffers can: be used to allocate multiple command 434buffers. 435If the allocation of any of those command buffers fails, the implementation 436must: free all successfully allocated command buffer objects from this 437command, set all entries of the pname:pCommandBuffers array to `NULL` and 438return the error. 439 440[NOTE] 441.Note 442==== 443Filling pname:pCommandBuffers with `NULL` values on failure is an exception 444to the default error behavior that output parameters will have undefined: 445contents. 446==== 447 448endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 449 450When command buffers are first allocated, they are in the 451<<commandbuffers-lifecycle, initial state>>. 452 453include::{generated}/validity/protos/vkAllocateCommandBuffers.txt[] 454-- 455 456[open,refpage='VkCommandBufferAllocateInfo',desc='Structure specifying the allocation parameters for command buffer object',type='structs'] 457-- 458The sname:VkCommandBufferAllocateInfo structure is defined as: 459 460include::{generated}/api/structs/VkCommandBufferAllocateInfo.txt[] 461 462 * pname:sType is the type of this structure. 463 * pname:pNext is `NULL` or a pointer to a structure extending this 464 structure. 465 * pname:commandPool is the command pool from which the command buffers are 466 allocated. 467 * pname:level is a elink:VkCommandBufferLevel value specifying the command 468 buffer level. 469 * pname:commandBufferCount is the number of command buffers to allocate 470 from the pool. 471 472include::{generated}/validity/structs/VkCommandBufferAllocateInfo.txt[] 473-- 474 475[open,refpage='VkCommandBufferLevel',desc='Enumerant specifying a command buffer level',type='enums'] 476-- 477Possible values of slink:VkCommandBufferAllocateInfo::pname:level, 478specifying the command buffer level, are: 479 480include::{generated}/api/enums/VkCommandBufferLevel.txt[] 481 482 * ename:VK_COMMAND_BUFFER_LEVEL_PRIMARY specifies a primary command 483 buffer. 484 * ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY specifies a secondary command 485 buffer. 486-- 487 488[open,refpage='vkResetCommandBuffer',desc='Reset a command buffer to the initial state',type='protos'] 489-- 490To reset a command buffer, call: 491 492include::{generated}/api/protos/vkResetCommandBuffer.txt[] 493 494 * pname:commandBuffer is the command buffer to reset. 495 The command buffer can: be in any state other than 496 <<commandbuffers-lifecycle, pending>>, and is moved into the 497 <<commandbuffers-lifecycle, initial state>>. 498 * pname:flags is a bitmask of elink:VkCommandBufferResetFlagBits 499 controlling the reset operation. 500 501Any primary command buffer that is in the <<commandbuffers-lifecycle, 502recording or executable state>> and has pname:commandBuffer recorded into 503it, becomes <<commandbuffers-lifecycle, invalid>>. 504 505.Valid Usage 506**** 507 * [[VUID-vkResetCommandBuffer-commandBuffer-00045]] 508 pname:commandBuffer must: not be in the <<commandbuffers-lifecycle, 509 pending state>> 510 * [[VUID-vkResetCommandBuffer-commandBuffer-00046]] 511 pname:commandBuffer must: have been allocated from a pool that was 512 created with the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT 513**** 514 515include::{generated}/validity/protos/vkResetCommandBuffer.txt[] 516-- 517 518[open,refpage='VkCommandBufferResetFlagBits',desc='Bitmask controlling behavior of a command buffer reset',type='enums'] 519-- 520Bits which can: be set in flink:vkResetCommandBuffer::pname:flags to control 521the reset operation are: 522 523include::{generated}/api/enums/VkCommandBufferResetFlagBits.txt[] 524 525 * ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT specifies that most 526 or all memory resources currently owned by the command buffer should: be 527 returned to the parent command pool. 528 If this flag is not set, then the command buffer may: hold onto memory 529 resources and reuse them when recording commands. 530 pname:commandBuffer is moved to the <<commandbuffers-lifecycle, initial 531 state>>. 532-- 533 534[open,refpage='VkCommandBufferResetFlags',desc='Bitmask of VkCommandBufferResetFlagBits',type='flags'] 535-- 536include::{generated}/api/flags/VkCommandBufferResetFlags.txt[] 537 538tname:VkCommandBufferResetFlags is a bitmask type for setting a mask of zero 539or more elink:VkCommandBufferResetFlagBits. 540-- 541 542[open,refpage='vkFreeCommandBuffers',desc='Free command buffers',type='protos'] 543-- 544To free command buffers, call: 545 546include::{generated}/api/protos/vkFreeCommandBuffers.txt[] 547 548 * pname:device is the logical device that owns the command pool. 549 * pname:commandPool is the command pool from which the command buffers 550 were allocated. 551 * pname:commandBufferCount is the length of the pname:pCommandBuffers 552 array. 553 * pname:pCommandBuffers is a pointer to an array of handles of command 554 buffers to free. 555 556Any primary command buffer that is in the <<commandbuffers-lifecycle, 557recording or executable state>> and has any element of pname:pCommandBuffers 558recorded into it, becomes <<commandbuffers-lifecycle, invalid>>. 559 560.Valid Usage 561**** 562 * [[VUID-vkFreeCommandBuffers-pCommandBuffers-00047]] 563 All elements of pname:pCommandBuffers must: not be in the 564 <<commandbuffers-lifecycle, pending state>> 565 * [[VUID-vkFreeCommandBuffers-pCommandBuffers-00048]] 566 pname:pCommandBuffers must: be a valid pointer to an array of 567 pname:commandBufferCount sname:VkCommandBuffer handles, each element of 568 which must: either be a valid handle or `NULL` 569**** 570 571include::{generated}/validity/protos/vkFreeCommandBuffers.txt[] 572-- 573 574 575[[commandbuffers-recording]] 576== Command Buffer Recording 577 578[open,refpage='vkBeginCommandBuffer',desc='Start recording a command buffer',type='protos'] 579-- 580To begin recording a command buffer, call: 581 582include::{generated}/api/protos/vkBeginCommandBuffer.txt[] 583 584 * pname:commandBuffer is the handle of the command buffer which is to be 585 put in the recording state. 586 * pname:pBeginInfo is a pointer to a slink:VkCommandBufferBeginInfo 587 structure defining additional information about how the command buffer 588 begins recording. 589 590.Valid Usage 591**** 592 * [[VUID-vkBeginCommandBuffer-commandBuffer-00049]] 593 pname:commandBuffer must: not be in the <<commandbuffers-lifecycle, 594 recording or pending state>> 595 * [[VUID-vkBeginCommandBuffer-commandBuffer-00050]] 596 If pname:commandBuffer was allocated from a slink:VkCommandPool which 597 did not have the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT 598 flag set, pname:commandBuffer must: be in the 599 <<commandbuffers-lifecycle, initial state>> 600 * [[VUID-vkBeginCommandBuffer-commandBuffer-00051]] 601 If pname:commandBuffer is a secondary command buffer, the 602 pname:pInheritanceInfo member of pname:pBeginInfo must: be a valid 603 sname:VkCommandBufferInheritanceInfo structure 604 * [[VUID-vkBeginCommandBuffer-commandBuffer-00052]] 605 If pname:commandBuffer is a secondary command buffer and either the 606 pname:occlusionQueryEnable member of the pname:pInheritanceInfo member 607 of pname:pBeginInfo is ename:VK_FALSE, or the precise occlusion queries 608 feature is not enabled, then 609 pname:pBeginInfo->pInheritanceInfo->queryFlags must: not contain 610 ename:VK_QUERY_CONTROL_PRECISE_BIT 611 * [[VUID-vkBeginCommandBuffer-commandBuffer-02840]] 612 If pname:commandBuffer is a primary command buffer, then 613 pname:pBeginInfo->flags must: not set both the 614 ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT and the 615 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flags 616**** 617 618include::{generated}/validity/protos/vkBeginCommandBuffer.txt[] 619-- 620 621[open,refpage='VkCommandBufferBeginInfo',desc='Structure specifying a command buffer begin operation',type='structs'] 622-- 623The sname:VkCommandBufferBeginInfo structure is defined as: 624 625include::{generated}/api/structs/VkCommandBufferBeginInfo.txt[] 626 627 * pname:sType is the type of this structure. 628 * pname:pNext is `NULL` or a pointer to a structure extending this 629 structure. 630 * pname:flags is a bitmask of elink:VkCommandBufferUsageFlagBits 631 specifying usage behavior for the command buffer. 632 * pname:pInheritanceInfo is a pointer to a 633 sname:VkCommandBufferInheritanceInfo structure, used if 634 pname:commandBuffer is a secondary command buffer. 635 If this is a primary command buffer, then this value is ignored. 636 637.Valid Usage 638**** 639ifndef::VK_KHR_dynamic_rendering[] 640 * [[VUID-VkCommandBufferBeginInfo-flags-00053]] 641 If pname:flags contains 642 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the 643 pname:renderPass member of pname:pInheritanceInfo must: be a valid 644 sname:VkRenderPass 645 * [[VUID-VkCommandBufferBeginInfo-flags-00054]] 646 If pname:flags contains 647 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the 648 pname:subpass member of pname:pInheritanceInfo must: be a valid subpass 649 index within the pname:renderPass member of pname:pInheritanceInfo 650endif::VK_KHR_dynamic_rendering[] 651 * [[VUID-VkCommandBufferBeginInfo-flags-00055]] 652 If pname:flags contains 653 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the 654 pname:framebuffer member of pname:pInheritanceInfo must: be either 655 dlink:VK_NULL_HANDLE, or a valid sname:VkFramebuffer that is compatible 656 with the pname:renderPass member of pname:pInheritanceInfo 657ifdef::VK_KHR_dynamic_rendering[] 658 * [[VUID-VkCommandBufferBeginInfo-flags-06000]] 659 If pname:flags contains 660 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the 661 pname:renderPass member of pname:pInheritanceInfo is not 662 dlink:VK_NULL_HANDLE, pname:renderPass must: be a valid 663 sname:VkRenderPass 664 * [[VUID-VkCommandBufferBeginInfo-flags-06001]] 665 If pname:flags contains 666 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the 667 pname:renderPass member of pname:pInheritanceInfo is not 668 dlink:VK_NULL_HANDLE, the pname:subpass member of pname:pInheritanceInfo 669 must: be a valid subpass index within the pname:renderPass member of 670 pname:pInheritanceInfo 671 * [[VUID-VkCommandBufferBeginInfo-flags-06002]] 672 If pname:flags contains 673 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the 674 pname:renderPass member of pname:pInheritanceInfo is 675 dlink:VK_NULL_HANDLE, the pname:pNext chain of pname:pInheritanceInfo 676 must: include a slink:VkCommandBufferInheritanceRenderingInfoKHR 677 structure 678ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 679 * [[VUID-VkCommandBufferBeginInfo-flags-06003]] 680 If pname:flags contains 681 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the 682 pname:renderPass member of pname:pInheritanceInfo is 683 dlink:VK_NULL_HANDLE, and the pname:pNext chain of 684 pname:pInheritanceInfo includes a slink:VkAttachmentSampleCountInfoAMD 685 or slink:VkAttachmentSampleCountInfoNV structure, the 686 pname:colorAttachmentCount member of that structure must: be equal to 687 the value of 688 slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:colorAttachmentCount 689endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 690endif::VK_KHR_dynamic_rendering[] 691**** 692 693include::{generated}/validity/structs/VkCommandBufferBeginInfo.txt[] 694-- 695 696[open,refpage='VkCommandBufferUsageFlagBits',desc='Bitmask specifying usage behavior for command buffer',type='enums'] 697-- 698Bits which can: be set in slink:VkCommandBufferBeginInfo::pname:flags to 699specify usage behavior for a command buffer are: 700 701include::{generated}/api/enums/VkCommandBufferUsageFlagBits.txt[] 702 703 * ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT specifies that each 704 recording of the command buffer will only be submitted once, and the 705 command buffer will be reset and recorded again between each submission. 706 * ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT specifies that a 707 secondary command buffer is considered to be entirely inside a render 708 pass. 709 If this is a primary command buffer, then this bit is ignored. 710 * ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT specifies that a 711 command buffer can: be resubmitted to a queue while it is in the 712 _pending state_, and recorded into multiple primary command buffers. 713-- 714 715[open,refpage='VkCommandBufferUsageFlags',desc='Bitmask of VkCommandBufferUsageFlagBits',type='flags'] 716-- 717include::{generated}/api/flags/VkCommandBufferUsageFlags.txt[] 718 719tname:VkCommandBufferUsageFlags is a bitmask type for setting a mask of zero 720or more elink:VkCommandBufferUsageFlagBits. 721-- 722 723[open,refpage='VkCommandBufferInheritanceInfo',desc='Structure specifying command buffer inheritance information',type='structs'] 724-- 725If the command buffer is a secondary command buffer, then the 726sname:VkCommandBufferInheritanceInfo structure defines any state that will 727be inherited from the primary command buffer: 728 729include::{generated}/api/structs/VkCommandBufferInheritanceInfo.txt[] 730 731 * pname:sType is the type of this structure. 732 * pname:pNext is `NULL` or a pointer to a structure extending this 733 structure. 734 * pname:renderPass is a slink:VkRenderPass object defining which render 735 passes the sname:VkCommandBuffer will be <<renderpass-compatibility, 736 compatible>> with and can: be executed within. 737 * pname:subpass is the index of the subpass within the render pass 738 instance that the sname:VkCommandBuffer will be executed within. 739 * pname:framebuffer can: refer to the slink:VkFramebuffer object that the 740 sname:VkCommandBuffer will be rendering to if it is executed within a 741 render pass instance. 742 It can: be dlink:VK_NULL_HANDLE if the framebuffer is not known. 743+ 744[NOTE] 745.Note 746==== 747Specifying the exact framebuffer that the secondary command buffer will be 748executed with may: result in better performance at command buffer execution 749time. 750==== 751 * pname:occlusionQueryEnable specifies whether the command buffer can: be 752 executed while an occlusion query is active in the primary command 753 buffer. 754 If this is ename:VK_TRUE, then this command buffer can: be executed 755 whether the primary command buffer has an occlusion query active or not. 756 If this is ename:VK_FALSE, then the primary command buffer must: not 757 have an occlusion query active. 758 * pname:queryFlags specifies the query flags that can: be used by an 759 active occlusion query in the primary command buffer when this secondary 760 command buffer is executed. 761 If this value includes the ename:VK_QUERY_CONTROL_PRECISE_BIT bit, then 762 the active query can: return boolean results or actual sample counts. 763 If this bit is not set, then the active query must: not use the 764 ename:VK_QUERY_CONTROL_PRECISE_BIT bit. 765 * pname:pipelineStatistics is a bitmask of 766 elink:VkQueryPipelineStatisticFlagBits specifying the set of pipeline 767 statistics that can: be counted by an active query in the primary 768 command buffer when this secondary command buffer is executed. 769 If this value includes a given bit, then this command buffer can: be 770 executed whether the primary command buffer has a pipeline statistics 771 query active that includes this bit or not. 772 If this value excludes a given bit, then the active pipeline statistics 773 query must: not be from a query pool that counts that statistic. 774 775If the slink:VkCommandBuffer will not be executed within a render pass 776instance, 777ifdef::VK_KHR_dynamic_rendering[] 778or if the render pass instance was begun with flink:vkCmdBeginRenderingKHR, 779endif::VK_KHR_dynamic_rendering[] 780pname:renderPass, pname:subpass, and pname:framebuffer are ignored. 781 782.Valid Usage 783**** 784 * [[VUID-VkCommandBufferInheritanceInfo-occlusionQueryEnable-00056]] 785 If the <<features-inheritedQueries,inherited queries>> feature is not 786 enabled, pname:occlusionQueryEnable must: be ename:VK_FALSE 787 * [[VUID-VkCommandBufferInheritanceInfo-queryFlags-00057]] 788 If the <<features-inheritedQueries,inherited queries>> feature is 789 enabled, pname:queryFlags must: be a valid combination of 790 elink:VkQueryControlFlagBits values 791 * [[VUID-VkCommandBufferInheritanceInfo-queryFlags-02788]] 792 If the <<features-inheritedQueries,inherited queries>> feature is not 793 enabled, pname:queryFlags must: be code:0 794 * [[VUID-VkCommandBufferInheritanceInfo-pipelineStatistics-02789]] 795 If the <<features-pipelineStatisticsQuery,pipeline statistics queries>> 796 feature is enabled, pname:pipelineStatistics must: be a valid 797 combination of elink:VkQueryPipelineStatisticFlagBits values 798 * [[VUID-VkCommandBufferInheritanceInfo-pipelineStatistics-00058]] 799 If the <<features-pipelineStatisticsQuery,pipeline statistics queries>> 800 feature is not enabled, pname:pipelineStatistics must: be code:0 801**** 802 803include::{generated}/validity/structs/VkCommandBufferInheritanceInfo.txt[] 804-- 805 806[NOTE] 807.Note 808==== 809On some implementations, not using the 810ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT bit enables command 811buffers to be patched in-place if needed, rather than creating a copy of the 812command buffer. 813==== 814 815If a command buffer is in the <<commandbuffers-lifecycle, invalid, or 816executable state>>, and the command buffer was allocated from a command pool 817with the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, 818then fname:vkBeginCommandBuffer implicitly resets the command buffer, 819behaving as if fname:vkResetCommandBuffer had been called with 820ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT not set. 821After the implicit reset, pname:commandBuffer is moved to the 822<<commandbuffers-lifecycle, recording state>>. 823 824ifdef::VK_EXT_conditional_rendering[] 825[open,refpage='VkCommandBufferInheritanceConditionalRenderingInfoEXT',desc='Structure specifying command buffer inheritance information',type='structs'] 826-- 827If the pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes a 828sname:VkCommandBufferInheritanceConditionalRenderingInfoEXT structure, then 829that structure controls whether a command buffer can: be executed while 830conditional rendering is <<active-conditional-rendering,active>> in the 831primary command buffer. 832 833The sname:VkCommandBufferInheritanceConditionalRenderingInfoEXT structure is 834defined as: 835 836include::{generated}/api/structs/VkCommandBufferInheritanceConditionalRenderingInfoEXT.txt[] 837 838 * pname:sType is the type of this structure. 839 * pname:pNext is `NULL` or a pointer to a structure extending this 840 structure. 841 * pname:conditionalRenderingEnable specifies whether the command buffer 842 can: be executed while conditional rendering is active in the primary 843 command buffer. 844 If this is ename:VK_TRUE, then this command buffer can: be executed 845 whether the primary command buffer has active conditional rendering or 846 not. 847 If this is ename:VK_FALSE, then the primary command buffer must: not 848 have conditional rendering active. 849 850If this structure is not present, the behavior is as if 851pname:conditionalRenderingEnable is ename:VK_FALSE. 852 853.Valid Usage 854**** 855 * [[VUID-VkCommandBufferInheritanceConditionalRenderingInfoEXT-conditionalRenderingEnable-01977]] 856 If the <<features-inheritedConditionalRendering, inherited conditional 857 rendering>> feature is not enabled, pname:conditionalRenderingEnable 858 must: be ename:VK_FALSE 859**** 860 861include::{generated}/validity/structs/VkCommandBufferInheritanceConditionalRenderingInfoEXT.txt[] 862-- 863endif::VK_EXT_conditional_rendering[] 864 865ifdef::VK_QCOM_render_pass_transform[] 866[open,refpage='VkCommandBufferInheritanceRenderPassTransformInfoQCOM',desc='Structure describing transformed render pass parameters command buffer',type='structs'] 867-- 868 869To begin recording a secondary command buffer compatible with execution 870inside a render pass using <<vertexpostproc-renderpass-transform, render 871pass transform>>, add the 872slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM to the 873pname:pNext chain of slink:VkCommandBufferInheritanceInfo structure passed 874to the flink:vkBeginCommandBuffer command specifying the parameters for 875transformed rasterization. 876 877The sname:VkCommandBufferInheritanceRenderPassTransformInfoQCOM structure is 878defined as: 879 880include::{generated}/api/structs/VkCommandBufferInheritanceRenderPassTransformInfoQCOM.txt[] 881 882 * pname:sType is the type of this structure. 883 * pname:pNext is `NULL` or a pointer to a structure extending this 884 structure. 885 * pname:transform is a elink:VkSurfaceTransformFlagBitsKHR value 886 describing the transform to be applied to the render pass. 887 * pname:renderArea is the render area that is affected by the command 888 buffer. 889 890When the secondary is recorded to execute within a render pass instance 891using flink:vkCmdExecuteCommands, the render pass transform parameters of 892the secondary command buffer must: be consistent with the render pass 893transform parameters specified for the render pass instance. 894In particular, the pname:transform and pname:renderArea for command buffer 895must: be identical to the pname:transform and pname:renderArea of the render 896pass instance. 897 898.Valid Usage 899**** 900 * [[VUID-VkCommandBufferInheritanceRenderPassTransformInfoQCOM-transform-02864]] 901 pname:transform must: be ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, 902 ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, 903 ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or 904 ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR 905**** 906 907include::{generated}/validity/structs/VkCommandBufferInheritanceRenderPassTransformInfoQCOM.txt[] 908-- 909endif::VK_QCOM_render_pass_transform[] 910 911ifdef::VK_NV_inherited_viewport_scissor[] 912[open,refpage='VkCommandBufferInheritanceViewportScissorInfoNV',desc='Structure specifying command buffer inheritance information',type='structs'] 913-- 914The sname:VkCommandBufferInheritanceViewportScissorInfoNV structure is 915defined as: 916 917include::{generated}/api/structs/VkCommandBufferInheritanceViewportScissorInfoNV.txt[] 918 919 * pname:sType is the type of this structure. 920 * pname:pNext is `NULL` or a pointer to a structure extending this 921 structure. 922 * pname:viewportScissor2D specifies whether the listed dynamic state is 923 inherited. 924 * pname:viewportDepthCount specifies the maximum number of viewports to 925 inherit. 926 When pname:viewportScissor2D is ename:VK_FALSE, the behavior is as if 927 this value is zero. 928 * pname:pViewportDepths is a pointer to a slink:VkViewport structure 929 specifying the expected depth range for each inherited viewport. 930 931If the pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes a 932sname:VkCommandBufferInheritanceViewportScissorInfoNV structure, then that 933structure controls whether a command buffer can: inherit the following state 934from other command buffers: 935 936 * ename:VK_DYNAMIC_STATE_SCISSOR 937ifdef::VK_EXT_extended_dynamic_state[] 938 * ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT 939endif::VK_EXT_extended_dynamic_state[] 940ifdef::VK_EXT_discard_rectangles[] 941 * ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT 942endif::VK_EXT_discard_rectangles[] 943 944as well as the following state, with restrictions on inherited depth values 945and viewport count: 946 947 * ename:VK_DYNAMIC_STATE_VIEWPORT 948ifdef::VK_EXT_extended_dynamic_state[] 949 * ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT 950endif::VK_EXT_extended_dynamic_state[] 951 952If pname:viewportScissor2D is ename:VK_FALSE, then the command buffer does 953not inherit the listed dynamic state, and should: set this state itself. 954If this structure is not present, the behavior is as if 955pname:viewportScissor2D is ename:VK_FALSE. 956 957If pname:viewportScissor2D is ename:VK_TRUE, then the listed dynamic state 958is inherited, and the command buffer must: not set this 959ifndef::VK_EXT_extended_dynamic_state[state.] 960ifdef::VK_EXT_extended_dynamic_state[] 961state, except that the viewport and scissor count may: be set by binding a 962graphics pipeline that does not specify this state as dynamic. 963 964[NOTE] 965.Note 966==== 967Due to this restriction, applications should: ensure either all or none of 968the graphics pipelines bound in this secondary command buffer use dynamic 969viewport/scissor counts. 970==== 971endif::VK_EXT_extended_dynamic_state[] 972 973When the command buffer is executed as part of a the execution of a 974flink:vkCmdExecuteCommands command, the inherited state (if enabled) is 975determined by the following procedure, performed separately for each dynamic 976state, and separately for each value for dynamic state that consists of 977multiple values (e.g. multiple viewports). 978 979 * With [eq]#i# being the index of the executed command buffer in the 980 pname:pCommandBuffers array of flink:vkCmdExecuteCommands, if [eq]#i > 981 0# and any secondary command buffer from index [eq]#0# to [eq]#i-1# 982 modifies the state, the inherited state is provisionally set to the 983 final value set by the last such secondary command buffer. 984 Binding a graphics pipeline defining the state statically is equivalent 985 to setting the state to an undefined: value. 986 * Otherwise, the tentatative inherited state is that of the primary 987 command buffer at the point the flink:vkCmdExecuteCommands command was 988 recorded; if the state is undefined:, then so is the provisional 989 inherited state. 990 * If the provisional inherited state is an undefined: value, then the 991 state is not inherited. 992 * If the provisional inherited state is a viewport, with [eq]#n# being its 993 viewport index, then if [eq]#n {geq} pname:viewportDepthCount#, or if 994 either slink:VkViewport::pname:minDepth or 995 slink:VkViewport::pname:maxDepth are not equal to the respective values 996 of the [eq]#n^th^# element of pname:pViewportDepths, then the state is 997 not inherited. 998 * If the provisional inherited state passes both checks, then it becomes 999 the actual inherited state. 1000 1001[NOTE] 1002.Note 1003==== 1004There is no support for inheriting dynamic state from a secondary command 1005buffer executed as part of a different `vkCmdExecuteCommands` command. 1006==== 1007 1008.Valid Usage 1009**** 1010 * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04782]] 1011 If the <<features-inheritedViewportScissor2D, inherited viewport 1012 scissor>> feature is not enabled, pname:viewportScissor2D must: be 1013 ename:VK_FALSE 1014 * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04783]] 1015 If the <<features-multiViewport,multiple viewports>> feature is not 1016 enabled and pname:viewportScissor2D is ename:VK_TRUE, then 1017 pname:viewportDepthCount must: be `1` 1018 * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04784]] 1019 If pname:viewportScissor2D is ename:VK_TRUE, then 1020 pname:viewportDepthCount must: be greater than `0` 1021 * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04785]] 1022 If pname:viewportScissor2D is ename:VK_TRUE, then pname:pViewportDepths 1023 must: be a valid pointer to an array of `viewportDepthCount` valid 1024 sname:VkViewport structures, except any requirements on `x`, `y`, 1025 `width`, and `height` do not apply 1026 * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04786]] 1027 If pname:viewportScissor2D is ename:VK_TRUE, then the command buffer 1028 must: be recorded with the 1029 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 1030**** 1031 1032include::{generated}/validity/structs/VkCommandBufferInheritanceViewportScissorInfoNV.txt[] 1033-- 1034endif::VK_NV_inherited_viewport_scissor[] 1035 1036ifdef::VK_KHR_dynamic_rendering[] 1037[open,refpage='VkCommandBufferInheritanceRenderingInfoKHR',desc='Structure specifying command buffer inheritance info for dynamic render pass instances',type='structs'] 1038-- 1039 1040The sname:VkCommandBufferInheritanceRenderingInfoKHR structure is defined 1041as: 1042 1043include::{generated}/api/structs/VkCommandBufferInheritanceRenderingInfoKHR.txt[] 1044 1045 * pname:sType is the type of this structure 1046 * pname:pNext is `NULL` or a pointer to a structure extending this 1047 structure 1048 * pname:flags is a bitmask of elink:VkRenderingFlagBitsKHR used by the 1049 render pass instance. 1050 * pname:viewMask is the view mask used for rendering. 1051 * pname:colorAttachmentCount is the number of color attachments specified 1052 in the render pass instance. 1053 * pname:pColorAttachmentFormats is a pointer to an array of elink:VkFormat 1054 values defining the format of color attachments. 1055 * pname:depthAttachmentFormat is a elink:VkFormat value defining the 1056 format of the depth attachment. 1057 * pname:stencilAttachmentFormat is a elink:VkFormat value defining the 1058 format of the stencil attachment. 1059 * pname:rasterizationSamples is a elink:VkSampleCountFlagBits specifying 1060 the number of samples used in rasterization. 1061 1062If the pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes a 1063sname:VkCommandBufferInheritanceRenderingInfoKHR structure, then that 1064structure controls parameters of dynamic render pass instances that the 1065slink:VkCommandBuffer can: be executed within. 1066If slink:VkCommandBufferInheritanceInfo::pname:renderPass is not 1067dlink:VK_NULL_HANDLE, or 1068ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not specified in 1069slink:VkCommandBufferBeginInfo::pname:flags, parameters of this structure 1070are ignored. 1071 1072If pname:colorAttachmentCount is `0` and the 1073<<features-variableMultisampleRate,pname:variableMultisampleRate>> feature 1074is enabled, pname:rasterizationSamples is ignored. 1075 1076If pname:depthAttachmentFormat, pname:stencilAttachmentFormat, or any 1077element of pname:pColorAttachmentFormats is ename:VK_FORMAT_UNDEFINED, it 1078indicates that the corresponding attachment is unused within the render 1079pass. 1080 1081.Valid Usage 1082**** 1083 * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-colorAttachmentCount-06004]] 1084 If pname:colorAttachmentCount is not `0`, pname:rasterizationSamples 1085 must: be a valid elink:VkSampleCountFlagBits value 1086 * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-variableMultisampleRate-06005]] 1087 If the 1088 <<features-variableMultisampleRate,pname:variableMultisampleRate>> 1089 feature is not enabled, pname:rasterizationSamples must: be a valid 1090 elink:VkSampleCountFlagBits value 1091 * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-pColorAttachmentFormats-06006]] 1092 If any element of pname:pColorAttachmentFormats is not 1093 ename:VK_FORMAT_UNDEFINED, it must: be a format with 1094 <<potential-format-features, potential format features>> that include 1095 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT 1096 * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-depthAttachmentFormat-06007]] 1097 If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it 1098 must: be a format with <<potential-format-features, potential format 1099 features>> that include 1100 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 1101 * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-stencilAttachmentFormat-06199]] 1102 If pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it 1103 must: be a format with <<potential-format-features, potential format 1104 features>> that include 1105 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 1106 * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-depthAttachmentFormat-06200]] 1107 If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED and 1108 pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, 1109 pname:depthAttachmentFormat must: equal pname:stencilAttachmentFormat 1110 * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-multiview-06008]] 1111 If the <<features-multiview,pname:multiview>> feature is not enabled, 1112 pname:viewMask must: be `0` 1113ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1114 * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-viewMask-06009]] 1115 The index of the most significant bit in pname:viewMask must: be less 1116 than <<limits-maxMultiviewViewCount,pname:maxMultiviewViewCount>> 1117endif::VK_VERSION_1_1,VK_KHR_multiview[] 1118**** 1119 1120include::{generated}/validity/structs/VkCommandBufferInheritanceRenderingInfoKHR.txt[] 1121-- 1122 1123ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 1124[open,refpage='VkAttachmentSampleCountInfoAMD',desc='Structure specifying command buffer inheritance info for dynamic render pass instances',type='structs',alias='VkAttachmentSampleCountInfoNV'] 1125-- 1126 1127The 1128ifdef::VK_AMD_mixed_attachment_samples[sname:VkAttachmentSampleCountInfoAMD] 1129ifdef::VK_AMD_mixed_attachment_samples+VK_NV_framebuffer_mixed_samples[or] 1130ifdef::VK_NV_framebuffer_mixed_samples[sname:VkAttachmentSampleCountInfoNV] 1131structure is defined as: 1132 1133ifdef::VK_AMD_mixed_attachment_samples[] 1134include::{generated}/api/structs/VkAttachmentSampleCountInfoAMD.txt[] 1135endif::VK_AMD_mixed_attachment_samples[] 1136 1137ifdef::VK_AMD_mixed_attachment_samples+VK_NV_framebuffer_mixed_samples[or the equivalent] 1138 1139ifdef::VK_NV_framebuffer_mixed_samples[] 1140include::{generated}/api/structs/VkAttachmentSampleCountInfoNV.txt[] 1141endif::VK_NV_framebuffer_mixed_samples[] 1142 1143 * pname:sType is the type of this structure 1144 * pname:pNext is `NULL` or a pointer to a structure extending this 1145 structure 1146 * pname:colorAttachmentCount is the number of color attachments specified 1147 in a render pass instance. 1148 * pname:pColorAttachmentSamples is a pointer to an array of 1149 elink:VkSampleCountFlagBits values defining the sample count of color 1150 attachments. 1151 * pname:depthStencilAttachmentSamples is a elink:VkSampleCountFlagBits 1152 value defining the sample count of a depth/stencil attachment. 1153 1154If slink:VkCommandBufferInheritanceInfo::pname:renderPass is 1155dlink:VK_NULL_HANDLE, ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 1156is specified in slink:VkCommandBufferBeginInfo::pname:flags, and the 1157pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes 1158sname:VkAttachmentSampleCountInfoAMD, then this structure defines the sample 1159counts of each attachment within the render pass instance. 1160If sname:VkAttachmentSampleCountInfoAMD is not included, the value of 1161slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:rasterizationSamples 1162is used as the sample count for each attachment. 1163If slink:VkCommandBufferInheritanceInfo::pname:renderPass is not 1164dlink:VK_NULL_HANDLE, or 1165ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not specified in 1166slink:VkCommandBufferBeginInfo::pname:flags, parameters of this structure 1167are ignored. 1168 1169sname:VkAttachmentSampleCountInfoAMD can: also be included in the 1170pname:pNext chain of slink:VkGraphicsPipelineCreateInfo. 1171When a graphics pipeline is created without a slink:VkRenderPass, if this 1172structure is present in the pname:pNext chain of 1173slink:VkGraphicsPipelineCreateInfo, it specifies the sample count of 1174attachments used for rendering. 1175If this structure is not specified, and the pipeline does not include a 1176slink:VkRenderPass, the value of 1177slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples is 1178used as the sample count for each attachment. 1179If a graphics pipeline is created with a valid slink:VkRenderPass, 1180parameters of this structure are ignored. 1181 1182include::{generated}/validity/structs/VkAttachmentSampleCountInfoAMD.txt[] 1183-- 1184endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 1185 1186endif::VK_KHR_dynamic_rendering[] 1187 1188Once recording starts, an application records a sequence of commands 1189(ftext:vkCmd*) to set state in the command buffer, draw, dispatch, and other 1190commands. 1191 1192ifdef::VK_NV_device_generated_commands[] 1193Several commands can also be recorded indirectly from sname:VkBuffer 1194content, see <<device-generated-commands>>. 1195endif::VK_NV_device_generated_commands[] 1196 1197[open,refpage='vkEndCommandBuffer',desc='Finish recording a command buffer',type='protos'] 1198-- 1199To complete recording of a command buffer, call: 1200 1201include::{generated}/api/protos/vkEndCommandBuffer.txt[] 1202 1203 * pname:commandBuffer is the command buffer to complete recording. 1204 1205If there was an error during recording, the application will be notified by 1206an unsuccessful return code returned by fname:vkEndCommandBuffer. 1207If the application wishes to further use the command buffer, the command 1208buffer must: be reset. 1209 1210The command buffer must: have been in the <<commandbuffers-lifecycle, 1211recording state>>, and is moved to the <<commandbuffers-lifecycle, 1212executable state>>. 1213 1214.Valid Usage 1215**** 1216 * [[VUID-vkEndCommandBuffer-commandBuffer-00059]] 1217 pname:commandBuffer must: be in the <<commandbuffers-lifecycle, 1218 recording state>> 1219 * [[VUID-vkEndCommandBuffer-commandBuffer-00060]] 1220 If pname:commandBuffer is a primary command buffer, there must: not be 1221 an active render pass instance 1222 * [[VUID-vkEndCommandBuffer-commandBuffer-00061]] 1223 All queries made <<queries-operation-active,active>> during the 1224 recording of pname:commandBuffer must: have been made inactive 1225ifdef::VK_EXT_conditional_rendering[] 1226 * [[VUID-vkEndCommandBuffer-None-01978]] 1227 Conditional rendering must: not be 1228 <<active-conditional-rendering,active>> 1229endif::VK_EXT_conditional_rendering[] 1230ifdef::VK_EXT_debug_utils[] 1231 * [[VUID-vkEndCommandBuffer-commandBuffer-01815]] 1232 If pname:commandBuffer is a secondary command buffer, there must: not be 1233 an outstanding flink:vkCmdBeginDebugUtilsLabelEXT command recorded to 1234 pname:commandBuffer that has not previously been ended by a call to 1235 flink:vkCmdEndDebugUtilsLabelEXT 1236endif::VK_EXT_debug_utils[] 1237ifdef::VK_EXT_debug_marker[] 1238 * [[VUID-vkEndCommandBuffer-commandBuffer-00062]] 1239 If pname:commandBuffer is a secondary command buffer, there must: not be 1240 an outstanding flink:vkCmdDebugMarkerBeginEXT command recorded to 1241 pname:commandBuffer that has not previously been ended by a call to 1242 flink:vkCmdDebugMarkerEndEXT 1243endif::VK_EXT_debug_marker[] 1244**** 1245 1246include::{generated}/validity/protos/vkEndCommandBuffer.txt[] 1247-- 1248 1249When a command buffer is in the executable state, it can: be submitted to a 1250queue for execution. 1251 1252 1253[[commandbuffers-submission]] 1254== Command Buffer Submission 1255 1256[NOTE] 1257.Note 1258==== 1259Submission can be a high overhead operation, and applications should: 1260attempt to batch work together into as few calls to fname:vkQueueSubmit 1261ifdef::VK_KHR_synchronization2[] 1262or fname:vkQueueSubmit2KHR 1263endif::VK_KHR_synchronization2[] 1264as possible. 1265==== 1266 1267ifdef::VK_KHR_synchronization2[] 1268[open,refpage='vkQueueSubmit2KHR',desc='Submits command buffers to a queue',type='protos'] 1269-- 1270To submit command buffers to a queue, call: 1271 1272include::{generated}/api/protos/vkQueueSubmit2KHR.txt[] 1273 1274 * pname:queue is the queue that the command buffers will be submitted to. 1275 * pname:submitCount is the number of elements in the pname:pSubmits array. 1276 * pname:pSubmits is a pointer to an array of slink:VkSubmitInfo2KHR 1277 structures, each specifying a command buffer submission batch. 1278 * pname:fence is an optional: handle to a fence to be signaled once all 1279 submitted command buffers have completed execution. 1280 If pname:fence is not dlink:VK_NULL_HANDLE, it defines a 1281 <<synchronization-fences-signaling, fence signal operation>>. 1282 1283fname:vkQueueSubmit2KHR is a <<devsandqueues-submission,queue submission 1284command>>, with each batch defined by an element of pname:pSubmits. 1285 1286Semaphore operations submitted with flink:vkQueueSubmit2KHR have additional 1287ordering constraints compared to other submission commands, with 1288dependencies involving previous and subsequent queue operations. 1289Information about these additional constraints can be found in the 1290<<synchronization-semaphores, semaphore>> section of <<synchronization, the 1291synchronization chapter>>. 1292 1293If any command buffer submitted to this queue is in the 1294<<commandbuffers-lifecycle, executable state>>, it is moved to the 1295<<commandbuffers-lifecycle, pending state>>. 1296Once execution of all submissions of a command buffer complete, it moves 1297from the <<commandbuffers-lifecycle, pending state>>, back to the 1298<<commandbuffers-lifecycle, executable state>>. 1299If a command buffer was recorded with the 1300ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves 1301back to the <<commandbuffers-lifecycle, invalid state>>. 1302 1303If fname:vkQueueSubmit2KHR fails, it may: return 1304ename:VK_ERROR_OUT_OF_HOST_MEMORY or ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 1305If it does, the implementation must: ensure that the state and contents of 1306any resources or synchronization primitives referenced by the submitted 1307command buffers and any semaphores referenced by pname:pSubmits is 1308unaffected by the call or its failure. 1309If fname:vkQueueSubmit2KHR fails in such a way that the implementation is 1310unable to make that guarantee, the implementation must: return 1311ename:VK_ERROR_DEVICE_LOST. 1312See <<devsandqueues-lost-device,Lost Device>>. 1313 1314.Valid Usage 1315**** 1316 * [[VUID-vkQueueSubmit2KHR-fence-04894]] 1317 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be 1318 unsignaled 1319 * [[VUID-vkQueueSubmit2KHR-fence-04895]] 1320 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be 1321 associated with any other queue command that has not yet completed 1322 execution on that queue 1323 * [[VUID-vkQueueSubmit2KHR-synchronization2-03866]] 1324 The <<features-synchronization2, pname:synchronization2>> feature must: 1325 be enabled 1326 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03867]] 1327 If a command recorded into the pname:commandBuffer member of any element 1328 of the pname:pCommandBufferInfos member of any element of pname:pSubmits 1329 referenced an slink:VkEvent, that event must: not be referenced by a 1330 command that has been submitted to another queue and is still in the 1331 _pending state_ 1332 * [[VUID-vkQueueSubmit2KHR-semaphore-03868]] 1333 The pname:semaphore member of any binary semaphore element of the 1334 pname:pSignalSemaphoreInfos member of any element of pname:pSubmits 1335 must: be unsignaled when the semaphore signal operation it defines is 1336 executed on the device 1337 * [[VUID-vkQueueSubmit2KHR-stageMask-03869]] 1338 The pname:stageMask member of any element of the 1339 pname:pSignalSemaphoreInfos member of any element of pname:pSubmits 1340 must: only include pipeline stages that are supported by the queue 1341 family which pname:queue belongs to 1342 * [[VUID-vkQueueSubmit2KHR-stageMask-03870]] 1343 The pname:stageMask member of any element of the 1344 pname:pWaitSemaphoreInfos member of any element of pname:pSubmits must: 1345 only include pipeline stages that are supported by the queue family 1346 which pname:queue belongs to 1347 * [[VUID-vkQueueSubmit2KHR-semaphore-03871]] 1348 When a semaphore wait operation for a binary semaphore is executed, as 1349 defined by the pname:semaphore member of any element of the 1350 pname:pWaitSemaphoreInfos member of any element of pname:pSubmits, there 1351 must: be no other queues waiting on the same semaphore 1352 * [[VUID-vkQueueSubmit2KHR-semaphore-03872]] 1353 The pname:semaphore member of any element of the 1354 pname:pWaitSemaphoreInfos member of any element of pname:pSubmits must: 1355 be semaphores that are signaled, or have 1356 <<synchronization-semaphores-signaling, semaphore signal operations>> 1357 previously submitted for execution 1358ifdef::VK_KHR_timeline_semaphore[] 1359 * [[VUID-vkQueueSubmit2KHR-semaphore-03873]] 1360 Any pname:semaphore member of any element of the 1361 pname:pWaitSemaphoreInfos member of any element of pname:pSubmits that 1362 was created with a elink:VkSemaphoreTypeKHR of 1363 ename:VK_SEMAPHORE_TYPE_BINARY_KHR must: reference a semaphore signal 1364 operation that has been submitted for execution and any semaphore signal 1365 operations on which it depends (if any) must: have also been submitted 1366 for execution 1367endif::VK_KHR_timeline_semaphore[] 1368 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03874]] 1369 The pname:commandBuffer member of any element of the 1370 pname:pCommandBufferInfos member of any element of pname:pSubmits must: 1371 be in the <<commandbuffers-lifecycle, pending or executable state>> 1372 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03875]] 1373 If a command recorded into the pname:commandBuffer member of any element 1374 of the pname:pCommandBufferInfos member of any element of pname:pSubmits 1375 was not recorded with the 1376 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 1377 the <<commandbuffers-lifecycle, pending state>> 1378 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03876]] 1379 Any <<commandbuffers-secondary, secondary command buffers recorded>> 1380 into the pname:commandBuffer member of any element of the 1381 pname:pCommandBufferInfos member of any element of pname:pSubmits must: 1382 be in the <<commandbuffers-lifecycle, pending or executable state>> 1383 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03877]] 1384 If any <<commandbuffers-secondary, secondary command buffers recorded>> 1385 into the pname:commandBuffer member of any element of the 1386 pname:pCommandBufferInfos member of any element of pname:pSubmits was 1387 not recorded with the 1388 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 1389 the <<commandbuffers-lifecycle, pending state>> 1390 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03878]] 1391 The pname:commandBuffer member of any element of the 1392 pname:pCommandBufferInfos member of any element of pname:pSubmits must: 1393 have been allocated from a sname:VkCommandPool that was created for the 1394 same queue family pname:queue belongs to 1395 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03879]] 1396 If a command recorded into the pname:commandBuffer member of any element 1397 of the pname:pCommandBufferInfos member of any element of pname:pSubmits 1398 includes a <<synchronization-queue-transfers-acquire, Queue Family 1399 Transfer Acquire Operation>>, there must: exist a previously submitted 1400 <<synchronization-queue-transfers-release, Queue Family Transfer Release 1401 Operation>> on a queue in the queue family identified by the acquire 1402 operation, with parameters matching the acquire operation as defined in 1403 the definition of such <<synchronization-queue-transfers-acquire, 1404 acquire operations>>, and which happens before the acquire operation 1405ifdef::VK_KHR_performance_query[] 1406 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03880]] 1407 If a command recorded into the pname:commandBuffer member of any element 1408 of the pname:pCommandBufferInfos member of any element of pname:pSubmits 1409 was a flink:vkCmdBeginQuery whose pname:queryPool was created with a 1410 pname:queryType of ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the 1411 <<profiling-lock, profiling lock>> must: have been held continuously on 1412 the sname:VkDevice that pname:queue was retrieved from, throughout 1413 recording of those command buffers 1414endif::VK_KHR_performance_query[] 1415ifdef::VK_VERSION_1_1[] 1416 * [[VUID-vkQueueSubmit2KHR-queue-06447]] 1417 If pname:queue was not created with 1418 ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, the pname:flags member of 1419 any element of pname:pSubmits must: not include 1420 ename:VK_SUBMIT_PROTECTED_BIT_KHR 1421endif::VK_VERSION_1_1[] 1422**** 1423 1424include::{generated}/validity/protos/vkQueueSubmit2KHR.txt[] 1425-- 1426 1427[open,refpage='VkSubmitInfo2KHR',desc='Structure specifying a queue submit operation',type='structs'] 1428-- 1429The sname:VkSubmitInfo2KHR structure is defined as: 1430 1431include::{generated}/api/structs/VkSubmitInfo2KHR.txt[] 1432 1433 * pname:sType is the type of this structure. 1434 * pname:pNext is `NULL` or a pointer to a structure extending this 1435 structure. 1436 * pname:flags is a bitmask of elink:VkSubmitFlagBitsKHR. 1437 * pname:waitSemaphoreInfoCount is the number of elements in 1438 pname:pWaitSemaphoreInfos. 1439 * pname:pWaitSemaphoreInfos is a pointer to an array of 1440 slink:VkSemaphoreSubmitInfoKHR structures defining 1441 <<synchronization-semaphores-waiting, semaphore wait operations>>. 1442 * pname:commandBufferInfoCount is the number of elements in 1443 pname:pCommandBufferInfos and the number of command buffers to execute 1444 in the batch. 1445 * pname:pCommandBufferInfos is a pointer to an array of 1446 slink:VkCommandBufferSubmitInfoKHR structures describing command buffers 1447 to execute in the batch. 1448 * pname:signalSemaphoreInfoCount is the number of elements in 1449 pname:pSignalSemaphoreInfos. 1450 * pname:pSignalSemaphoreInfos is a pointer to an array of 1451 slink:VkSemaphoreSubmitInfoKHR describing 1452 <<synchronization-semaphores-signaling, semaphore signal operations>>. 1453 1454.Valid Usage 1455**** 1456ifdef::VK_KHR_timeline_semaphore[] 1457 * [[VUID-VkSubmitInfo2KHR-semaphore-03881]] 1458 If the same semaphore is used as the pname:semaphore member of both an 1459 element of pname:pSignalSemaphoreInfos and pname:pWaitSemaphoreInfos, 1460 and that semaphore is a timeline semaphore, the pname:value member of 1461 the pname:pSignalSemaphoreInfos element must: be greater than the 1462 pname:value member of the pname:pWaitSemaphoreInfos element 1463 * [[VUID-VkSubmitInfo2KHR-semaphore-03882]] 1464 If the pname:semaphore member of any element of 1465 pname:pSignalSemaphoreInfos is a timeline semaphore, the pname:value 1466 member of that element must: have a value greater than the current value 1467 of the semaphore when the <<synchronization-semaphores-signaling, 1468 semaphore signal operation>> is executed 1469 * [[VUID-VkSubmitInfo2KHR-semaphore-03883]] 1470 If the pname:semaphore member of any element of 1471 pname:pSignalSemaphoreInfos is a timeline semaphore, the pname:value 1472 member of that element must: have a value which does not differ from the 1473 current value of the semaphore or the value of any outstanding semaphore 1474 wait or signal operation on that semaphore by more than 1475 <<limits-maxTimelineSemaphoreValueDifference, 1476 pname:maxTimelineSemaphoreValueDifference>> 1477 * [[VUID-VkSubmitInfo2KHR-semaphore-03884]] 1478 If the pname:semaphore member of any element of 1479 pname:pWaitSemaphoreInfos is a timeline semaphore, the pname:value 1480 member of that element must: have a value which does not differ from the 1481 current value of the semaphore or the value of any outstanding semaphore 1482 wait or signal operation on that semaphore by more than 1483 <<limits-maxTimelineSemaphoreValueDifference, 1484 pname:maxTimelineSemaphoreValueDifference>> 1485endif::VK_KHR_timeline_semaphore[] 1486ifdef::VK_VERSION_1_1[] 1487 * [[VUID-VkSubmitInfo2KHR-flags-03886]] 1488 If pname:flags includes ename:VK_SUBMIT_PROTECTED_BIT_KHR, all elements 1489 of pname:pCommandBuffers must: be protected command buffers 1490 * [[VUID-VkSubmitInfo2KHR-flags-03887]] 1491 If pname:flags does not include ename:VK_SUBMIT_PROTECTED_BIT_KHR, each 1492 element of pname:pCommandBuffers must: not be a protected command buffer 1493endif::VK_VERSION_1_1[] 1494ifdef::VK_KHR_dynamic_rendering[] 1495 * [[VUID-VkSubmitInfo2KHR-commandBuffer-06192]] 1496 If any pname:commandBuffer member of an element of 1497 pname:pCommandBufferInfos contains any <<renderpass-suspension,resumed 1498 render pass instances>>, they must: be suspended by a render pass 1499 instance earlier in submission order within pname:pCommandBufferInfos 1500 * [[VUID-VkSubmitInfo2KHR-commandBuffer-06010]] 1501 If any pname:commandBuffer member of an element of 1502 pname:pCommandBufferInfos contains any <<renderpass-suspension,suspended 1503 render pass instances>>, they must: be resumed by a render pass instance 1504 later in submission order within pname:pCommandBufferInfos 1505 * [[VUID-VkSubmitInfo2KHR-commandBuffer-06011]] 1506 If any pname:commandBuffer member of an element of 1507 pname:pCommandBufferInfos contains any <<renderpass-suspension,suspended 1508 render pass instances>>, there must: be no action or synchronization 1509 commands between that render pass instance and the render pass instance 1510 that resumes it 1511 * [[VUID-VkSubmitInfo2KHR-commandBuffer-06012]] 1512 If any pname:commandBuffer member of an element of 1513 pname:pCommandBufferInfos contains any <<renderpass-suspension,suspended 1514 render pass instances>>, there must: be no render pass instances between 1515 that render pass instance and the render pass instance that resumes it 1516ifdef::VK_EXT_sample_locations[] 1517 * [[VUID-VkSubmitInfo2KHR-variableSampleLocations-06013]] 1518 If the <<limits-variableSampleLocations, pname:variableSampleLocations>> 1519 limit is not supported, and any pname:commandBuffer member of an element 1520 of pname:pCommandBufferInfos contains any 1521 <<renderpass-suspension,suspended render pass instances>>, where a 1522 graphics pipeline has been bound, any pipelines bound in the render pass 1523 instance that resumes it, or any subsequent render pass instances that 1524 resume from that one and so on, must: use the same sample locations 1525endif::VK_EXT_sample_locations[] 1526endif::VK_KHR_dynamic_rendering[] 1527**** 1528 1529include::{generated}/validity/structs/VkSubmitInfo2KHR.txt[] 1530-- 1531 1532[open,refpage='VkSubmitFlagBitsKHR',desc='Bitmask specifying behavior of a submission',type='enums'] 1533-- 1534Bits which can: be set in slink:VkSubmitInfo2KHR::pname:flags to specify 1535submission behavior are: 1536 1537include::{generated}/api/enums/VkSubmitFlagBitsKHR.txt[] 1538 1539 * ename:VK_SUBMIT_PROTECTED_BIT_KHR specifies that this batch is a 1540 protected submission. 1541-- 1542 1543[open,refpage='VkSubmitFlagsKHR',desc='Bitmask of VkSubmitFlagBitsKHR',type='flags'] 1544-- 1545include::{generated}/api/flags/VkSubmitFlagsKHR.txt[] 1546 1547tname:VkSubmitFlagsKHR is a bitmask type for setting a mask of zero or more 1548elink:VkSubmitFlagBitsKHR. 1549-- 1550 1551[open,refpage='VkSemaphoreSubmitInfoKHR',desc='Structure specifying a semaphore signal or wait operation',type='structs'] 1552-- 1553:refpage: VkSemaphoreSubmitInfoKHR 1554 1555The sname:VkSemaphoreSubmitInfoKHR structure is defined as: 1556 1557include::{generated}/api/structs/VkSemaphoreSubmitInfoKHR.txt[] 1558 1559 * pname:sType is the type of this structure. 1560 * pname:pNext is `NULL` or a pointer to a structure extending this 1561 structure. 1562 * pname:semaphore is a slink:VkSemaphore affected by this operation. 1563 * pname:value is 1564ifdef::VK_KHR_timeline_semaphore[] 1565 either the value used to signal pname:semaphore or the value waited on 1566 by pname:semaphore, if pname:semaphore is a timeline semaphore. 1567 Otherwise it is 1568endif::VK_KHR_timeline_semaphore[] 1569 ignored. 1570 * pname:stageMask is a tlink:VkPipelineStageFlags2KHR mask of pipeline 1571 stages which limit the first synchronization scope of a semaphore signal 1572 operation, or second synchronization scope of a semaphore wait operation 1573 as described in the <<synchronization-semaphores-waiting, semaphore wait 1574 operation>> and <<synchronization-semaphores-signaling, semaphore signal 1575 operation>> sections of <<synchronization, the synchronization 1576 chapter>>. 1577 * pname:deviceIndex is the index of the device within a device group that 1578 executes the semaphore wait or signal operation. 1579 1580Whether this structure defines a semaphore wait or signal operation is 1581defined by how it is used. 1582 1583.Valid Usage 1584**** 1585:stageMaskName: stageMask 1586include::{chapters}/commonvalidity/stage_mask_2_common.txt[] 1587 * [[VUID-VkSemaphoreSubmitInfoKHR-device-03888]] 1588 If the pname:device that pname:semaphore was created on is not a device 1589 group, pname:deviceIndex must: be `0` 1590ifdef::VK_KHR_device_group_creation,VK_VERSION_1_1[] 1591 * [[VUID-VkSemaphoreSubmitInfoKHR-device-03889]] 1592 If the pname:device that pname:semaphore was created on is a device 1593 group, pname:deviceIndex must: be a valid device index 1594endif::VK_KHR_device_group_creation,VK_VERSION_1_1[] 1595**** 1596 1597include::{generated}/validity/structs/VkSemaphoreSubmitInfoKHR.txt[] 1598-- 1599 1600[open,refpage='VkCommandBufferSubmitInfoKHR',desc='Structure specifying a command buffer submission',type='structs'] 1601-- 1602The sname:VkCommandBufferSubmitInfoKHR structure is defined as: 1603 1604include::{generated}/api/structs/VkCommandBufferSubmitInfoKHR.txt[] 1605 1606 * pname:sType is the type of this structure. 1607 * pname:pNext is `NULL` or a pointer to a structure extending this 1608 structure. 1609 * pname:commandBuffer is a slink:VkCommandBuffer to be submitted for 1610 execution. 1611 * pname:deviceMask is a bitmask indicating which devices in a device group 1612 execute the command buffer. 1613 A pname:deviceMask of `0` is equivalent to setting all bits 1614 corresponding to valid devices in the group to `1`. 1615 1616.Valid Usage 1617**** 1618 * [[VUID-VkCommandBufferSubmitInfoKHR-commandBuffer-03890]] 1619 pname:commandBuffer must: not have been allocated with 1620 ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 1621ifdef::VK_KHR_device_group_creation,VK_VERSION_1_1[] 1622 * [[VUID-VkCommandBufferSubmitInfoKHR-deviceMask-03891]] 1623 If pname:deviceMask is not `0`, it must: be a valid device mask 1624endif::VK_KHR_device_group_creation,VK_VERSION_1_1[] 1625**** 1626 1627include::{generated}/validity/structs/VkCommandBufferSubmitInfoKHR.txt[] 1628-- 1629endif::VK_KHR_synchronization2[] 1630 1631[open,refpage='vkQueueSubmit',desc='Submits a sequence of semaphores or command buffers to a queue',type='protos'] 1632-- 1633To submit command buffers to a queue, call: 1634 1635include::{generated}/api/protos/vkQueueSubmit.txt[] 1636 1637 * pname:queue is the queue that the command buffers will be submitted to. 1638 * pname:submitCount is the number of elements in the pname:pSubmits array. 1639 * pname:pSubmits is a pointer to an array of slink:VkSubmitInfo 1640 structures, each specifying a command buffer submission batch. 1641 * pname:fence is an optional: handle to a fence to be signaled once all 1642 submitted command buffers have completed execution. 1643 If pname:fence is not dlink:VK_NULL_HANDLE, it defines a 1644 <<synchronization-fences-signaling, fence signal operation>>. 1645 1646fname:vkQueueSubmit is a <<devsandqueues-submission,queue submission 1647command>>, with each batch defined by an element of pname:pSubmits. 1648Batches begin execution in the order they appear in pname:pSubmits, but may: 1649complete out of order. 1650 1651Fence and semaphore operations submitted with flink:vkQueueSubmit have 1652additional ordering constraints compared to other submission commands, with 1653dependencies involving previous and subsequent queue operations. 1654Information about these additional constraints can be found in the 1655<<synchronization-semaphores, semaphore>> and <<synchronization-fences, 1656fence>> sections of <<synchronization, the synchronization chapter>>. 1657 1658Details on the interaction of pname:pWaitDstStageMask with synchronization 1659are described in the <<synchronization-semaphores-waiting, semaphore wait 1660operation>> section of <<synchronization, the synchronization chapter>>. 1661 1662The order that batches appear in pname:pSubmits is used to determine 1663<<synchronization-submission-order, submission order>>, and thus all the 1664<<synchronization-implicit, implicit ordering guarantees>> that respect it. 1665Other than these implicit ordering guarantees and any <<synchronization, 1666explicit synchronization primitives>>, these batches may: overlap or 1667otherwise execute out of order. 1668 1669If any command buffer submitted to this queue is in the 1670<<commandbuffers-lifecycle, executable state>>, it is moved to the 1671<<commandbuffers-lifecycle, pending state>>. 1672Once execution of all submissions of a command buffer complete, it moves 1673from the <<commandbuffers-lifecycle, pending state>>, back to the 1674<<commandbuffers-lifecycle, executable state>>. 1675If a command buffer was recorded with the 1676ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves to 1677the <<commandbuffers-lifecycle, invalid state>>. 1678 1679If fname:vkQueueSubmit fails, it may: return 1680ename:VK_ERROR_OUT_OF_HOST_MEMORY or ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 1681If it does, the implementation must: ensure that the state and contents of 1682any resources or synchronization primitives referenced by the submitted 1683command buffers and any semaphores referenced by pname:pSubmits is 1684unaffected by the call or its failure. 1685If fname:vkQueueSubmit fails in such a way that the implementation is unable 1686to make that guarantee, the implementation must: return 1687ename:VK_ERROR_DEVICE_LOST. 1688See <<devsandqueues-lost-device,Lost Device>>. 1689 1690.Valid Usage 1691**** 1692 * [[VUID-vkQueueSubmit-fence-00063]] 1693 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be 1694 unsignaled 1695 * [[VUID-vkQueueSubmit-fence-00064]] 1696 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be 1697 associated with any other queue command that has not yet completed 1698 execution on that queue 1699 * [[VUID-vkQueueSubmit-pCommandBuffers-00065]] 1700 Any calls to flink:vkCmdSetEvent, flink:vkCmdResetEvent or 1701 flink:vkCmdWaitEvents that have been recorded into any of the command 1702 buffer elements of the pname:pCommandBuffers member of any element of 1703 pname:pSubmits, must: not reference any slink:VkEvent that is referenced 1704 by any of those commands in a command buffer that has been submitted to 1705 another queue and is still in the _pending state_ 1706 * [[VUID-vkQueueSubmit-pWaitDstStageMask-00066]] 1707 Any stage flag included in any element of the pname:pWaitDstStageMask 1708 member of any element of pname:pSubmits must: be a pipeline stage 1709 supported by one of the capabilities of pname:queue, as specified in the 1710 <<synchronization-pipeline-stages-supported, table of supported pipeline 1711 stages>> 1712 * [[VUID-vkQueueSubmit-pSignalSemaphores-00067]] 1713 Each binary semaphore element of the pname:pSignalSemaphores member of 1714 any element of pname:pSubmits must: be unsignaled when the semaphore 1715 signal operation it defines is executed on the device 1716 * [[VUID-vkQueueSubmit-pWaitSemaphores-00068]] 1717 When a semaphore wait operation referring to a binary semaphore defined 1718 by any element of the pname:pWaitSemaphores member of any element of 1719 pname:pSubmits executes on pname:queue, there must: be no other queues 1720 waiting on the same semaphore 1721ifndef::VK_KHR_timeline_semaphore[] 1722 * [[VUID-vkQueueSubmit-pWaitSemaphores-00069]] 1723 All elements of the pname:pWaitSemaphores member of all elements of 1724 pname:pSubmits must: be semaphores that are signaled, or have 1725 <<synchronization-semaphores-signaling, semaphore signal operations>> 1726 previously submitted for execution 1727endif::VK_KHR_timeline_semaphore[] 1728ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1729 * [[VUID-vkQueueSubmit-pWaitSemaphores-03238]] 1730 All elements of the pname:pWaitSemaphores member of all elements of 1731 pname:pSubmits created with a elink:VkSemaphoreType of 1732 ename:VK_SEMAPHORE_TYPE_BINARY must: reference a semaphore signal 1733 operation that has been submitted for execution and any semaphore signal 1734 operations on which it depends (if any) must: have also been submitted 1735 for execution 1736endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1737 * [[VUID-vkQueueSubmit-pCommandBuffers-00070]] 1738 Each element of the pname:pCommandBuffers member of each element of 1739 pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or 1740 executable state>> 1741 * [[VUID-vkQueueSubmit-pCommandBuffers-00071]] 1742 If any element of the pname:pCommandBuffers member of any element of 1743 pname:pSubmits was not recorded with the 1744 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 1745 the <<commandbuffers-lifecycle, pending state>> 1746 * [[VUID-vkQueueSubmit-pCommandBuffers-00072]] 1747 Any <<commandbuffers-secondary, secondary command buffers recorded>> 1748 into any element of the pname:pCommandBuffers member of any element of 1749 pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or 1750 executable state>> 1751 * [[VUID-vkQueueSubmit-pCommandBuffers-00073]] 1752 If any <<commandbuffers-secondary, secondary command buffers recorded>> 1753 into any element of the pname:pCommandBuffers member of any element of 1754 pname:pSubmits was not recorded with the 1755 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 1756 the <<commandbuffers-lifecycle, pending state>> 1757 * [[VUID-vkQueueSubmit-pCommandBuffers-00074]] 1758 Each element of the pname:pCommandBuffers member of each element of 1759 pname:pSubmits must: have been allocated from a sname:VkCommandPool that 1760 was created for the same queue family pname:queue belongs to 1761 * [[VUID-vkQueueSubmit-pSubmits-02207]] 1762 If any element of pname:pSubmits->pCommandBuffers includes a 1763 <<synchronization-queue-transfers-acquire, Queue Family Transfer Acquire 1764 Operation>>, there must: exist a previously submitted 1765 <<synchronization-queue-transfers-release, Queue Family Transfer Release 1766 Operation>> on a queue in the queue family identified by the acquire 1767 operation, with parameters matching the acquire operation as defined in 1768 the definition of such <<synchronization-queue-transfers-acquire, 1769 acquire operations>>, and which happens-before the acquire operation 1770ifdef::VK_KHR_performance_query[] 1771 * [[VUID-vkQueueSubmit-pCommandBuffers-03220]] 1772 If a command recorded into any element of pname:pCommandBuffers was a 1773 flink:vkCmdBeginQuery whose pname:queryPool was created with a 1774 pname:queryType of ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the 1775 <<profiling-lock, profiling lock>> must: have been held continuously on 1776 the sname:VkDevice that pname:queue was retrieved from, throughout 1777 recording of those command buffers 1778endif::VK_KHR_performance_query[] 1779 * [[VUID-vkQueueSubmit-pSubmits-02808]] 1780 Any resource created with ename:VK_SHARING_MODE_EXCLUSIVE that is read 1781 by an operation specified by pname:pSubmits must: not be owned by any 1782 queue family other than the one which pname:queue belongs to, at the 1783 time it is executed 1784 * [[VUID-vkQueueSubmit-pSubmits-04626]] 1785 Any resource created with ename:VK_SHARING_MODE_CONCURRENT that is 1786 accessed by an operation specified by pname:pSubmits must: have included 1787 the queue family of pname:queue at resource creation time 1788ifdef::VK_VERSION_1_1[] 1789 * [[VUID-vkQueueSubmit-queue-06448]] 1790 If pname:queue was not created with 1791 ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, there must: be no element of 1792 pname:pSubmits that includes an slink:VkProtectedSubmitInfo structure in 1793 its pname:pNext chain with pname:protectedSubmit equal to ename:VK_TRUE 1794endif::VK_VERSION_1_1[] 1795**** 1796 1797include::{generated}/validity/protos/vkQueueSubmit.txt[] 1798-- 1799 1800[open,refpage='VkSubmitInfo',desc='Structure specifying a queue submit operation',type='structs'] 1801-- 1802:refpage: VkSubmitInfo 1803The sname:VkSubmitInfo structure is defined as: 1804 1805include::{generated}/api/structs/VkSubmitInfo.txt[] 1806 1807 * pname:sType is the type of this structure. 1808 * pname:pNext is `NULL` or a pointer to a structure extending this 1809 structure. 1810 * pname:waitSemaphoreCount is the number of semaphores upon which to wait 1811 before executing the command buffers for the batch. 1812 * pname:pWaitSemaphores is a pointer to an array of slink:VkSemaphore 1813 handles upon which to wait before the command buffers for this batch 1814 begin execution. 1815 If semaphores to wait on are provided, they define a 1816 <<synchronization-semaphores-waiting, semaphore wait operation>>. 1817 * pname:pWaitDstStageMask is a pointer to an array of pipeline stages at 1818 which each corresponding semaphore wait will occur. 1819 * pname:commandBufferCount is the number of command buffers to execute in 1820 the batch. 1821 * pname:pCommandBuffers is a pointer to an array of slink:VkCommandBuffer 1822 handles to execute in the batch. 1823 * pname:signalSemaphoreCount is the number of semaphores to be signaled 1824 once the commands specified in pname:pCommandBuffers have completed 1825 execution. 1826 * pname:pSignalSemaphores is a pointer to an array of slink:VkSemaphore 1827 handles which will be signaled when the command buffers for this batch 1828 have completed execution. 1829 If semaphores to be signaled are provided, they define a 1830 <<synchronization-semaphores-signaling, semaphore signal operation>>. 1831 1832The order that command buffers appear in pname:pCommandBuffers is used to 1833determine <<synchronization-submission-order, submission order>>, and thus 1834all the <<synchronization-implicit, implicit ordering guarantees>> that 1835respect it. 1836Other than these implicit ordering guarantees and any <<synchronization, 1837explicit synchronization primitives>>, these command buffers may: overlap or 1838otherwise execute out of order. 1839 1840 1841.Valid Usage 1842**** 1843:stageMaskName: pWaitDstStageMask 1844include::{chapters}/commonvalidity/stage_mask_common.txt[] 1845 1846 * [[VUID-VkSubmitInfo-pCommandBuffers-00075]] 1847 Each element of pname:pCommandBuffers must: not have been allocated with 1848 ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 1849 * [[VUID-VkSubmitInfo-pWaitDstStageMask-00078]] 1850 Each element of pname:pWaitDstStageMask must: not include 1851 ename:VK_PIPELINE_STAGE_HOST_BIT 1852ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1853 * [[VUID-VkSubmitInfo-pWaitSemaphores-03239]] 1854 If any element of pname:pWaitSemaphores or pname:pSignalSemaphores was 1855 created with a elink:VkSemaphoreType of 1856 ename:VK_SEMAPHORE_TYPE_TIMELINE, then the pname:pNext chain must: 1857 include a slink:VkTimelineSemaphoreSubmitInfo structure 1858 * [[VUID-VkSubmitInfo-pNext-03240]] 1859 If the pname:pNext chain of this structure includes a 1860 slink:VkTimelineSemaphoreSubmitInfo structure and any element of 1861 pname:pWaitSemaphores was created with a elink:VkSemaphoreType of 1862 ename:VK_SEMAPHORE_TYPE_TIMELINE, then its pname:waitSemaphoreValueCount 1863 member must: equal pname:waitSemaphoreCount 1864 * [[VUID-VkSubmitInfo-pNext-03241]] 1865 If the pname:pNext chain of this structure includes a 1866 slink:VkTimelineSemaphoreSubmitInfo structure and any element of 1867 pname:pSignalSemaphores was created with a elink:VkSemaphoreType of 1868 ename:VK_SEMAPHORE_TYPE_TIMELINE, then its 1869 pname:signalSemaphoreValueCount member must: equal 1870 pname:signalSemaphoreCount 1871 * [[VUID-VkSubmitInfo-pSignalSemaphores-03242]] 1872 For each element of pname:pSignalSemaphores created with a 1873 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 1874 corresponding element of 1875 slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: 1876 have a value greater than the current value of the semaphore when the 1877 <<synchronization-semaphores-signaling,semaphore signal operation>> is 1878 executed 1879 * [[VUID-VkSubmitInfo-pWaitSemaphores-03243]] 1880 For each element of pname:pWaitSemaphores created with a 1881 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 1882 corresponding element of 1883 slink:VkTimelineSemaphoreSubmitInfo::pname:pWaitSemaphoreValues must: 1884 have a value which does not differ from the current value of the 1885 semaphore or the value of any outstanding semaphore wait or signal 1886 operation on that semaphore by more than 1887 <<limits-maxTimelineSemaphoreValueDifference, 1888 pname:maxTimelineSemaphoreValueDifference>> 1889 * [[VUID-VkSubmitInfo-pSignalSemaphores-03244]] 1890 For each element of pname:pSignalSemaphores created with a 1891 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 1892 corresponding element of 1893 slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: 1894 have a value which does not differ from the current value of the 1895 semaphore or the value of any outstanding semaphore wait or signal 1896 operation on that semaphore by more than 1897 <<limits-maxTimelineSemaphoreValueDifference, 1898 pname:maxTimelineSemaphoreValueDifference>> 1899endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1900ifdef::VK_VERSION_1_1[] 1901 * [[VUID-VkSubmitInfo-pNext-04120]] 1902 If the pname:pNext chain of this structure does not include a 1903 sname:VkProtectedSubmitInfo structure with pname:protectedSubmit set to 1904 ename:VK_TRUE, then each element of the pname:pCommandBuffers array 1905 must: be an unprotected command buffer 1906 * [[VUID-VkSubmitInfo-pNext-04148]] 1907 If the pname:pNext chain of this structure includes a 1908 sname:VkProtectedSubmitInfo structure with pname:protectedSubmit set to 1909 ename:VK_TRUE, then each element of the pname:pCommandBuffers array 1910 must: be a protected command buffer 1911endif::VK_VERSION_1_1[] 1912ifdef::VK_KHR_dynamic_rendering[] 1913 * [[VUID-VkSubmitInfo-pCommandBuffers-06193]] 1914 If pname:pCommandBuffers contains any <<renderpass-suspension,resumed 1915 render pass instances>>, they must: be suspended by a render pass 1916 instance earlier in submission order within pname:pCommandBuffers 1917 * [[VUID-VkSubmitInfo-pCommandBuffers-06014]] 1918 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 1919 render pass instances>>, they must: be resumed by a render pass instance 1920 later in submission order within pname:pCommandBuffers 1921 * [[VUID-VkSubmitInfo-pCommandBuffers-06015]] 1922 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 1923 render pass instances>>, there must: be no action or synchronization 1924 commands between that render pass instance and the render pass instance 1925 that resumes it 1926 * [[VUID-VkSubmitInfo-pCommandBuffers-06016]] 1927 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 1928 render pass instances>>, there must: be no render pass instances between 1929 that render pass instance and the render pass instance that resumes it 1930ifdef::VK_EXT_sample_locations[] 1931 * [[VUID-VkSubmitInfo-variableSampleLocations-06017]] 1932 If the <<limits-variableSampleLocations, pname:variableSampleLocations>> 1933 limit is not supported, and any element of pname:pCommandBuffers 1934 contains any <<renderpass-suspension,suspended render pass instances>>, 1935 where a graphics pipeline has been bound, any pipelines bound in the 1936 render pass instance that resumes it, or any subsequent render pass 1937 instances that resume from that one and so on, must: use the same sample 1938 locations 1939endif::VK_EXT_sample_locations[] 1940endif::VK_KHR_dynamic_rendering[] 1941**** 1942 1943include::{generated}/validity/structs/VkSubmitInfo.txt[] 1944-- 1945 1946ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1947[open,refpage='VkTimelineSemaphoreSubmitInfo',desc='Structure specifying signal and wait values for timeline semaphores',type='structs',alias='VkTimelineSemaphoreSubmitInfoKHR'] 1948-- 1949To specify the values to use when waiting for and signaling semaphores 1950created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE, 1951add a slink:VkTimelineSemaphoreSubmitInfo structure to the pname:pNext chain 1952of the slink:VkSubmitInfo structure when using flink:vkQueueSubmit or the 1953slink:VkBindSparseInfo structure when using flink:vkQueueBindSparse. 1954The sname:VkTimelineSemaphoreSubmitInfo structure is defined as: 1955 1956include::{generated}/api/structs/VkTimelineSemaphoreSubmitInfo.txt[] 1957 1958ifdef::VK_KHR_timeline_semaphore[] 1959or the equivalent 1960 1961include::{generated}/api/structs/VkTimelineSemaphoreSubmitInfoKHR.txt[] 1962endif::VK_KHR_timeline_semaphore[] 1963 1964 * pname:sType is the type of this structure. 1965 * pname:pNext is `NULL` or a pointer to a structure extending this 1966 structure. 1967 * pname:waitSemaphoreValueCount is the number of semaphore wait values 1968 specified in pname:pWaitSemaphoreValues. 1969 * pname:pWaitSemaphoreValues is a pointer to an array of 1970 pname:waitSemaphoreValueCount values for the corresponding semaphores in 1971 slink:VkSubmitInfo::pname:pWaitSemaphores to wait for. 1972 * pname:signalSemaphoreValueCount is the number of semaphore signal values 1973 specified in pname:pSignalSemaphoreValues. 1974 * pname:pSignalSemaphoreValues is a pointer to an array 1975 pname:signalSemaphoreValueCount values for the corresponding semaphores 1976 in slink:VkSubmitInfo::pname:pSignalSemaphores to set when signaled. 1977 1978If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or 1979slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in 1980pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively was 1981not created with a elink:VkSemaphoreType of 1982ename:VK_SEMAPHORE_TYPE_TIMELINE, the implementation must: ignore the value 1983in the pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry. 1984 1985include::{generated}/validity/structs/VkTimelineSemaphoreSubmitInfo.txt[] 1986-- 1987endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1988 1989ifdef::VK_KHR_external_semaphore_win32[] 1990[open,refpage='VkD3D12FenceSubmitInfoKHR',desc='Structure specifying values for Direct3D 12 fence-backed semaphores',type='structs'] 1991-- 1992To specify the values to use when waiting for and signaling semaphores whose 1993<<synchronization-semaphores-importing,current payload>> refers to a 1994Direct3D 12 fence, add a slink:VkD3D12FenceSubmitInfoKHR structure to the 1995pname:pNext chain of the slink:VkSubmitInfo structure. 1996The sname:VkD3D12FenceSubmitInfoKHR structure is defined as: 1997 1998include::{generated}/api/structs/VkD3D12FenceSubmitInfoKHR.txt[] 1999 2000 * pname:sType is the type of this structure. 2001 * pname:pNext is `NULL` or a pointer to a structure extending this 2002 structure. 2003 * pname:waitSemaphoreValuesCount is the number of semaphore wait values 2004 specified in pname:pWaitSemaphoreValues. 2005 * pname:pWaitSemaphoreValues is a pointer to an array of 2006 pname:waitSemaphoreValuesCount values for the corresponding semaphores 2007 in slink:VkSubmitInfo::pname:pWaitSemaphores to wait for. 2008 * pname:signalSemaphoreValuesCount is the number of semaphore signal 2009 values specified in pname:pSignalSemaphoreValues. 2010 * pname:pSignalSemaphoreValues is a pointer to an array of 2011 pname:signalSemaphoreValuesCount values for the corresponding semaphores 2012 in slink:VkSubmitInfo::pname:pSignalSemaphores to set when signaled. 2013 2014If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or 2015slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in 2016pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively does 2017not currently have a <<synchronization-semaphores-payloads, payload>> 2018referring to a Direct3D 12 fence, the implementation must: ignore the value 2019in the pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry. 2020 2021ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2022[NOTE] 2023.Note 2024==== 2025As the introduction of the external semaphore handle type 2026ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT predates that of 2027timeline semaphores, support for importing semaphore payloads from external 2028handles of that type into semaphores created (implicitly or explicitly) with 2029a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY is preserved for 2030backwards compatibility. 2031However, applications should: prefer importing such handle types into 2032semaphores created with a elink:VkSemaphoreType of 2033ename:VK_SEMAPHORE_TYPE_TIMELINE, and use the 2034slink:VkTimelineSemaphoreSubmitInfo structure instead of the 2035sname:VkD3D12FenceSubmitInfoKHR structure to specify the values to use when 2036waiting for and signaling such semaphores. 2037==== 2038endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2039 2040.Valid Usage 2041**** 2042 * [[VUID-VkD3D12FenceSubmitInfoKHR-waitSemaphoreValuesCount-00079]] 2043 pname:waitSemaphoreValuesCount must: be the same value as 2044 sname:VkSubmitInfo::pname:waitSemaphoreCount, where sname:VkSubmitInfo 2045 is in the pname:pNext chain of this sname:VkD3D12FenceSubmitInfoKHR 2046 structure 2047 * [[VUID-VkD3D12FenceSubmitInfoKHR-signalSemaphoreValuesCount-00080]] 2048 pname:signalSemaphoreValuesCount must: be the same value as 2049 sname:VkSubmitInfo::pname:signalSemaphoreCount, where sname:VkSubmitInfo 2050 is in the pname:pNext chain of this sname:VkD3D12FenceSubmitInfoKHR 2051 structure 2052**** 2053 2054include::{generated}/validity/structs/VkD3D12FenceSubmitInfoKHR.txt[] 2055-- 2056endif::VK_KHR_external_semaphore_win32[] 2057 2058ifdef::VK_KHR_win32_keyed_mutex[] 2059[open,refpage='VkWin32KeyedMutexAcquireReleaseInfoKHR',desc='Use the Windows keyed mutex mechanism to synchronize work',type='structs'] 2060-- 2061When submitting work that operates on memory imported from a Direct3D 11 2062resource to a queue, the keyed mutex mechanism may: be used in addition to 2063Vulkan semaphores to synchronize the work. 2064Keyed mutexes are a property of a properly created shareable Direct3D 11 2065resource. 2066They can: only be used if the imported resource was created with the 2067etext:D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX flag. 2068 2069To acquire keyed mutexes before submitted work and/or release them after, 2070add a slink:VkWin32KeyedMutexAcquireReleaseInfoKHR structure to the 2071pname:pNext chain of the slink:VkSubmitInfo structure. 2072 2073The sname:VkWin32KeyedMutexAcquireReleaseInfoKHR structure is defined as: 2074 2075include::{generated}/api/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.txt[] 2076 2077 * pname:sType is the type of this structure. 2078 * pname:pNext is `NULL` or a pointer to a structure extending this 2079 structure. 2080 * pname:acquireCount is the number of entries in the pname:pAcquireSyncs, 2081 pname:pAcquireKeys, and pname:pAcquireTimeouts arrays. 2082 * pname:pAcquireSyncs is a pointer to an array of slink:VkDeviceMemory 2083 objects which were imported from Direct3D 11 resources. 2084 * pname:pAcquireKeys is a pointer to an array of mutex key values to wait 2085 for prior to beginning the submitted work. 2086 Entries refer to the keyed mutex associated with the corresponding 2087 entries in pname:pAcquireSyncs. 2088 * pname:pAcquireTimeouts is a pointer to an array of timeout values, in 2089 millisecond units, for each acquire specified in pname:pAcquireKeys. 2090 * pname:releaseCount is the number of entries in the pname:pReleaseSyncs 2091 and pname:pReleaseKeys arrays. 2092 * pname:pReleaseSyncs is a pointer to an array of slink:VkDeviceMemory 2093 objects which were imported from Direct3D 11 resources. 2094 * pname:pReleaseKeys is a pointer to an array of mutex key values to set 2095 when the submitted work has completed. 2096 Entries refer to the keyed mutex associated with the corresponding 2097 entries in pname:pReleaseSyncs. 2098 2099.Valid Usage 2100**** 2101 * [[VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireSyncs-00081]] 2102 Each member of pname:pAcquireSyncs and pname:pReleaseSyncs must: be a 2103 device memory object imported by setting 2104 slink:VkImportMemoryWin32HandleInfoKHR::pname:handleType to 2105 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT or 2106 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT 2107**** 2108 2109include::{generated}/validity/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.txt[] 2110-- 2111endif::VK_KHR_win32_keyed_mutex[] 2112 2113ifdef::VK_NV_win32_keyed_mutex[] 2114include::{chapters}/VK_NV_win32_keyed_mutex/keyed_mutex_submit.txt[] 2115endif::VK_NV_win32_keyed_mutex[] 2116 2117ifdef::VK_VERSION_1_1[] 2118[open,refpage='VkProtectedSubmitInfo',desc='Structure indicating whether the submission is protected',type='structs'] 2119-- 2120If the pname:pNext chain of slink:VkSubmitInfo includes a 2121sname:VkProtectedSubmitInfo structure, then the structure indicates whether 2122the batch is protected. 2123The sname:VkProtectedSubmitInfo structure is defined as: 2124 2125include::{generated}/api/structs/VkProtectedSubmitInfo.txt[] 2126 2127 * pname:protectedSubmit specifies whether the batch is protected. 2128 If pname:protectedSubmit is ename:VK_TRUE, the batch is protected. 2129 If pname:protectedSubmit is ename:VK_FALSE, the batch is unprotected. 2130 If the sname:VkSubmitInfo::pname:pNext chain does not include this 2131 structure, the batch is unprotected. 2132 2133include::{generated}/validity/structs/VkProtectedSubmitInfo.txt[] 2134-- 2135endif::VK_VERSION_1_1[] 2136 2137ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2138[open,refpage='VkDeviceGroupSubmitInfo',desc='Structure indicating which physical devices execute semaphore operations and command buffers',type='structs'] 2139-- 2140 2141If the pname:pNext chain of slink:VkSubmitInfo includes a 2142sname:VkDeviceGroupSubmitInfo structure, then that structure includes device 2143indices and masks specifying which physical devices execute semaphore 2144operations and command buffers. 2145 2146The sname:VkDeviceGroupSubmitInfo structure is defined as: 2147 2148include::{generated}/api/structs/VkDeviceGroupSubmitInfo.txt[] 2149 2150ifdef::VK_KHR_device_group[] 2151or the equivalent 2152 2153include::{generated}/api/structs/VkDeviceGroupSubmitInfoKHR.txt[] 2154endif::VK_KHR_device_group[] 2155 2156 * pname:sType is the type of this structure. 2157 * pname:pNext is `NULL` or a pointer to a structure extending this 2158 structure. 2159 * pname:waitSemaphoreCount is the number of elements in the 2160 pname:pWaitSemaphoreDeviceIndices array. 2161 * pname:pWaitSemaphoreDeviceIndices is a pointer to an array of 2162 pname:waitSemaphoreCount device indices indicating which physical device 2163 executes the semaphore wait operation in the corresponding element of 2164 slink:VkSubmitInfo::pname:pWaitSemaphores. 2165 * pname:commandBufferCount is the number of elements in the 2166 pname:pCommandBufferDeviceMasks array. 2167 * pname:pCommandBufferDeviceMasks is a pointer to an array of 2168 pname:commandBufferCount device masks indicating which physical devices 2169 execute the command buffer in the corresponding element of 2170 slink:VkSubmitInfo::pname:pCommandBuffers. 2171 A physical device executes the command buffer if the corresponding bit 2172 is set in the mask. 2173 * pname:signalSemaphoreCount is the number of elements in the 2174 pname:pSignalSemaphoreDeviceIndices array. 2175 * pname:pSignalSemaphoreDeviceIndices is a pointer to an array of 2176 pname:signalSemaphoreCount device indices indicating which physical 2177 device executes the semaphore signal operation in the corresponding 2178 element of slink:VkSubmitInfo::pname:pSignalSemaphores. 2179 2180If this structure is not present, semaphore operations and command buffers 2181execute on device index zero. 2182 2183.Valid Usage 2184**** 2185 * [[VUID-VkDeviceGroupSubmitInfo-waitSemaphoreCount-00082]] 2186 pname:waitSemaphoreCount must: equal 2187 slink:VkSubmitInfo::pname:waitSemaphoreCount 2188 * [[VUID-VkDeviceGroupSubmitInfo-commandBufferCount-00083]] 2189 pname:commandBufferCount must: equal 2190 slink:VkSubmitInfo::pname:commandBufferCount 2191 * [[VUID-VkDeviceGroupSubmitInfo-signalSemaphoreCount-00084]] 2192 pname:signalSemaphoreCount must: equal 2193 slink:VkSubmitInfo::pname:signalSemaphoreCount 2194 * [[VUID-VkDeviceGroupSubmitInfo-pWaitSemaphoreDeviceIndices-00085]] 2195 All elements of pname:pWaitSemaphoreDeviceIndices and 2196 pname:pSignalSemaphoreDeviceIndices must: be valid device indices 2197 * [[VUID-VkDeviceGroupSubmitInfo-pCommandBufferDeviceMasks-00086]] 2198 All elements of pname:pCommandBufferDeviceMasks must: be valid device 2199 masks 2200**** 2201 2202include::{generated}/validity/structs/VkDeviceGroupSubmitInfo.txt[] 2203-- 2204endif::VK_VERSION_1_1,VK_KHR_device_group[] 2205 2206ifdef::VK_KHR_performance_query[] 2207If the pname:pNext chain of slink:VkSubmitInfo includes a 2208slink:VkPerformanceQuerySubmitInfoKHR structure, then the structure 2209indicates which counter pass is active for the batch in that submit. 2210 2211[open,refpage='VkPerformanceQuerySubmitInfoKHR',desc='Structure indicating which counter pass index is active for performance queries',type='structs'] 2212-- 2213The sname:VkPerformanceQuerySubmitInfoKHR structure is defined as: 2214 2215include::{generated}/api/structs/VkPerformanceQuerySubmitInfoKHR.txt[] 2216 2217 * pname:sType is the type of this structure. 2218 * pname:pNext is `NULL` or a pointer to a structure extending this 2219 structure. 2220 * pname:counterPassIndex specifies which counter pass index is active. 2221 2222If the sname:VkSubmitInfo::pname:pNext chain does not include this 2223structure, the batch defaults to use counter pass index 0. 2224 2225.Valid Usage 2226**** 2227 * [[VUID-VkPerformanceQuerySubmitInfoKHR-counterPassIndex-03221]] 2228 pname:counterPassIndex must: be less than the number of counter passes 2229 required by any queries within the batch. 2230 The required number of counter passes for a performance query is 2231 obtained by calling 2232 flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR 2233**** 2234 2235include::{generated}/validity/structs/VkPerformanceQuerySubmitInfoKHR.txt[] 2236-- 2237endif::VK_KHR_performance_query[] 2238 2239 2240[[commandbuffers-submission-progress]] 2241== Queue Forward Progress 2242 2243When using binary semaphores, the application must: ensure that command 2244buffer submissions will be able to complete without any subsequent 2245operations by the application on any queue. 2246After any call to fname:vkQueueSubmit (or other queue operation), for every 2247queued wait on a semaphore 2248ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2249created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY 2250endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2251there must: be a prior signal of that semaphore that will not be consumed by 2252a different wait on the semaphore. 2253 2254ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2255When using timeline semaphores, wait-before-signal behavior is well-defined 2256and applications can: submit work via fname:vkQueueSubmit defining a 2257<<synchronization-semaphores-waiting, timeline semaphore wait operation>> 2258before submitting a corresponding <<synchronization-semaphores-signaling, 2259semaphore signal operation>>. 2260For each <<synchronization-semaphores-waiting, timeline semaphore wait 2261operation>> defined by a call to fname:vkQueueSubmit, the application must: 2262ensure that a corresponding <<synchronization-semaphores-signaling, 2263semaphore signal operation>> is executed before forward progress can be 2264made. 2265endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2266 2267Command buffers in the submission can: include flink:vkCmdWaitEvents 2268commands that wait on events that will not be signaled by earlier commands 2269in the queue. 2270Such events must: be signaled by the application using flink:vkSetEvent, and 2271the fname:vkCmdWaitEvents commands that wait upon them must: not be inside a 2272render pass instance. 2273The event must: be set before the flink:vkCmdWaitEvents command is executed. 2274 2275[NOTE] 2276.Note 2277==== 2278Implementations may have some tolerance for waiting on events to be set, but 2279this is defined outside of the scope of Vulkan. 2280==== 2281 2282 2283[[commandbuffers-secondary]] 2284== Secondary Command Buffer Execution 2285 2286[open,refpage='vkCmdExecuteCommands',desc='Execute a secondary command buffer from a primary command buffer',type='protos'] 2287-- 2288A secondary command buffer must: not be directly submitted to a queue. 2289Instead, secondary command buffers are recorded to execute as part of a 2290primary command buffer with the command: 2291 2292include::{generated}/api/protos/vkCmdExecuteCommands.txt[] 2293 2294 * pname:commandBuffer is a handle to a primary command buffer that the 2295 secondary command buffers are executed in. 2296 * pname:commandBufferCount is the length of the pname:pCommandBuffers 2297 array. 2298 * pname:pCommandBuffers is a pointer to an array of 2299 pname:commandBufferCount secondary command buffer handles, which are 2300 recorded to execute in the primary command buffer in the order they are 2301 listed in the array. 2302 2303If any element of pname:pCommandBuffers was not recorded with the 2304ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, and it was recorded 2305into any other primary command buffer which is currently in the 2306<<commandbuffers-lifecycle, executable or recording state>>, that primary 2307command buffer becomes <<commandbuffers-lifecycle, invalid>>. 2308 2309.Valid Usage 2310**** 2311 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00088]] 2312 Each element of pname:pCommandBuffers must: have been allocated with a 2313 pname:level of ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 2314 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00089]] 2315 Each element of pname:pCommandBuffers must: be in the 2316 <<commandbuffers-lifecycle, pending or executable state>> 2317 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00091]] 2318 If any element of pname:pCommandBuffers was not recorded with the 2319 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not be 2320 in the <<commandbuffers-lifecycle, pending state>> 2321 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00092]] 2322 If any element of pname:pCommandBuffers was not recorded with the 2323 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not 2324 have already been recorded to pname:commandBuffer 2325 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00093]] 2326 If any element of pname:pCommandBuffers was not recorded with the 2327 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not 2328 appear more than once in pname:pCommandBuffers 2329 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00094]] 2330 Each element of pname:pCommandBuffers must: have been allocated from a 2331 sname:VkCommandPool that was created for the same queue family as the 2332 sname:VkCommandPool from which pname:commandBuffer was allocated 2333 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00096]] 2334 If fname:vkCmdExecuteCommands is being called within a render pass 2335 instance, each element of pname:pCommandBuffers must: have been recorded 2336 with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 2337 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00099]] 2338 If fname:vkCmdExecuteCommands is being called within a render pass 2339 instance, and any element of pname:pCommandBuffers was recorded with 2340 slink:VkCommandBufferInheritanceInfo::pname:framebuffer not equal to 2341 dlink:VK_NULL_HANDLE, that sname:VkFramebuffer must: match the 2342 sname:VkFramebuffer used in the current render pass instance 2343 * [[VUID-vkCmdExecuteCommands-contents-06018]] 2344 If fname:vkCmdExecuteCommands is being called within a render pass 2345 instance begun with flink:vkCmdBeginRenderPass, its pname:contents 2346 parameter must: have been set to 2347 ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS 2348 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06019]] 2349 If fname:vkCmdExecuteCommands is being called within a render pass 2350 instance begun with flink:vkCmdBeginRenderPass, each element of 2351 pname:pCommandBuffers must: have been recorded with 2352 slink:VkCommandBufferInheritanceInfo::pname:subpass set to the index of 2353 the subpass which the given command buffer will be executed in 2354 * [[VUID-vkCmdExecuteCommands-pBeginInfo-06020]] 2355 If fname:vkCmdExecuteCommands is being called within a render pass 2356 instance begun with flink:vkCmdBeginRenderPass, the render passes 2357 specified in the pname:pBeginInfo->pInheritanceInfo->renderPass members 2358 of the flink:vkBeginCommandBuffer commands used to begin recording each 2359 element of pname:pCommandBuffers must: be 2360 <<renderpass-compatibility,compatible>> with the current render pass 2361ifndef::VK_KHR_dynamic_rendering[] 2362 * [[VUID-vkCmdExecuteCommands-contents-00095]] 2363 If fname:vkCmdExecuteCommands is being called within a render pass 2364 instance, that render pass instance must: have been begun with the 2365 pname:contents parameter of fname:vkCmdBeginRenderPass set to 2366 ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS 2367 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00097]] 2368 If fname:vkCmdExecuteCommands is being called within a render pass 2369 instance, each element of pname:pCommandBuffers must: have been recorded 2370 with sname:VkCommandBufferInheritanceInfo::pname:subpass set to the 2371 index of the subpass which the given command buffer will be executed in 2372 * [[VUID-vkCmdExecuteCommands-pInheritanceInfo-00098]] 2373 If fname:vkCmdExecuteCommands is being called within a render pass 2374 instance, the render passes specified in the 2375 pname:pBeginInfo->pInheritanceInfo->renderPass members of the 2376 flink:vkBeginCommandBuffer commands used to begin recording each element 2377 of pname:pCommandBuffers must: be 2378 <<renderpass-compatibility,compatible>> with the current render pass 2379endif::VK_KHR_dynamic_rendering[] 2380ifdef::VK_QCOM_render_pass_transform[] 2381 * [[VUID-vkCmdExecuteCommands-pNext-02865]] 2382 If fname:vkCmdExecuteCommands is being called within a render pass 2383 instance that included slink:VkRenderPassTransformBeginInfoQCOM in the 2384 pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of 2385 pname:pCommandBuffers must: have been recorded with 2386 slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM in the 2387 pname:pNext chain of slink:VkCommandBufferBeginInfo 2388 * [[VUID-vkCmdExecuteCommands-pNext-02866]] 2389 If fname:vkCmdExecuteCommands is being called within a render pass 2390 instance that included slink:VkRenderPassTransformBeginInfoQCOM in the 2391 pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of 2392 pname:pCommandBuffers must: have been recorded with 2393 slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM::pname:transform 2394 identical to slink:VkRenderPassTransformBeginInfoQCOM::pname:transform 2395 * [[VUID-vkCmdExecuteCommands-pNext-02867]] 2396 If fname:vkCmdExecuteCommands is being called within a render pass 2397 instance that included slink:VkRenderPassTransformBeginInfoQCOM in the 2398 pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of 2399 pname:pCommandBuffers must: have been recorded with 2400 slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM::pname:renderArea 2401 identical to slink:VkRenderPassBeginInfo::pname:renderArea 2402endif::VK_QCOM_render_pass_transform[] 2403 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00100]] 2404 If fname:vkCmdExecuteCommands is not being called within a render pass 2405 instance, each element of pname:pCommandBuffers must: not have been 2406 recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 2407 * [[VUID-vkCmdExecuteCommands-commandBuffer-00101]] 2408 If the <<features-inheritedQueries,inherited queries>> feature is not 2409 enabled, pname:commandBuffer must: not have any queries 2410 <<queries-operation-active,active>> 2411 * [[VUID-vkCmdExecuteCommands-commandBuffer-00102]] 2412 If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query 2413 <<queries-operation-active,active>>, then each element of 2414 pname:pCommandBuffers must: have been recorded with 2415 sname:VkCommandBufferInheritanceInfo::pname:occlusionQueryEnable set to 2416 ename:VK_TRUE 2417 * [[VUID-vkCmdExecuteCommands-commandBuffer-00103]] 2418 If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query 2419 <<queries-operation-active,active>>, then each element of 2420 pname:pCommandBuffers must: have been recorded with 2421 sname:VkCommandBufferInheritanceInfo::pname:queryFlags having all bits 2422 set that are set for the query 2423 * [[VUID-vkCmdExecuteCommands-commandBuffer-00104]] 2424 If pname:commandBuffer has a ename:VK_QUERY_TYPE_PIPELINE_STATISTICS 2425 query <<queries-operation-active,active>>, then each element of 2426 pname:pCommandBuffers must: have been recorded with 2427 sname:VkCommandBufferInheritanceInfo::pname:pipelineStatistics having 2428 all bits set that are set in the sname:VkQueryPool the query uses 2429 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00105]] 2430 Each element of pname:pCommandBuffers must: not begin any query types 2431 that are <<queries-operation-active,active>> in pname:commandBuffer 2432ifdef::VK_VERSION_1_1[] 2433 * [[VUID-vkCmdExecuteCommands-commandBuffer-01820]] 2434 If pname:commandBuffer is a protected command buffer and 2435 <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, 2436 each element of pname:pCommandBuffers must: be a protected command 2437 buffer 2438 * [[VUID-vkCmdExecuteCommands-commandBuffer-01821]] 2439 If pname:commandBuffer is an unprotected command buffer and 2440 <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, 2441 each element of pname:pCommandBuffers must: be an unprotected command 2442 buffer 2443endif::VK_VERSION_1_1[] 2444ifdef::VK_EXT_transform_feedback[] 2445 * [[VUID-vkCmdExecuteCommands-None-02286]] 2446 This command must: not be recorded when transform feedback is active 2447endif::VK_EXT_transform_feedback[] 2448ifdef::VK_KHR_dynamic_rendering[] 2449 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06021]] 2450 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2451 render pass instances>>, there must: be no action or synchronization 2452 commands between that render pass instance and any render pass instance 2453 that resumes it 2454 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06022]] 2455 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2456 render pass instances>>, there must: be no render pass instances between 2457 that render pass instance and any render pass instance that resumes it 2458ifdef::VK_EXT_sample_locations[] 2459 * [[VUID-vkCmdExecuteCommands-variableSampleLocations-06023]] 2460 If the <<limits-variableSampleLocations, pname:variableSampleLocations>> 2461 limit is not supported, and any element of pname:pCommandBuffers 2462 contains any <<renderpass-suspension,suspended render pass instances>>, 2463 where a graphics pipeline has been bound, any pipelines bound in the 2464 render pass instance that resumes it, or any subsequent render pass 2465 instances that resume from that one and so on, must: use the same sample 2466 locations 2467endif::VK_EXT_sample_locations[] 2468 * [[VUID-vkCmdExecuteCommands-flags-06024]] 2469 If fname:vkCmdExecuteCommands is being called within a render pass 2470 instance begun with flink:vkCmdBeginRenderingKHR, its 2471 slink:VkRenderingInfoKHR::pname:flags parameter must: have included 2472 ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR 2473 * [[VUID-vkCmdExecuteCommands-pBeginInfo-06025]] 2474 If fname:vkCmdExecuteCommands is being called within a render pass 2475 instance begun with flink:vkCmdBeginRenderingKHR, the render passes 2476 specified in the pname:pBeginInfo->pInheritanceInfo->renderPass members 2477 of the flink:vkBeginCommandBuffer commands used to begin recording each 2478 element of pname:pCommandBuffers must: be dlink:VK_NULL_HANDLE 2479 * [[VUID-vkCmdExecuteCommands-flags-06026]] 2480 If fname:vkCmdExecuteCommands is being called within a render pass 2481 instance begun with flink:vkCmdBeginRenderingKHR, the pname:flags member 2482 of the slink:VkCommandBufferInheritanceRenderingInfoKHR structure 2483 included in the pname:pNext chain of 2484 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2485 recording each element of pname:pCommandBuffers must: be equal to the 2486 slink:VkRenderingInfoKHR::pname:flags parameter to 2487 flink:vkCmdBeginRenderingKHR, excluding 2488 ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR 2489 * [[VUID-vkCmdExecuteCommands-colorAttachmentCount-06027]] 2490 If fname:vkCmdExecuteCommands is being called within a render pass 2491 instance begun with flink:vkCmdBeginRenderingKHR, the 2492 pname:colorAttachmentCount member of the 2493 slink:VkCommandBufferInheritanceRenderingInfoKHR structure included in 2494 the pname:pNext chain of 2495 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2496 recording each element of pname:pCommandBuffers must: be equal to the 2497 slink:VkRenderingInfoKHR::pname:colorAttachmentCount parameter to 2498 flink:vkCmdBeginRenderingKHR 2499 * [[VUID-vkCmdExecuteCommands-imageView-06028]] 2500 If fname:vkCmdExecuteCommands is being called within a render pass 2501 instance begun with flink:vkCmdBeginRenderingKHR, if the pname:imageView 2502 member of an element of the 2503 slink:VkRenderingInfoKHR::pname:pColorAttachments parameter to 2504 flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the 2505 corresponding element of the pname:pColorAttachmentFormats member of the 2506 slink:VkCommandBufferInheritanceRenderingInfoKHR structure included in 2507 the pname:pNext chain of 2508 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2509 recording each element of pname:pCommandBuffers must: be equal to the 2510 format used to create that image view 2511 * [[VUID-vkCmdExecuteCommands-pDepthAttachment-06029]] 2512 If fname:vkCmdExecuteCommands is being called within a render pass 2513 instance begun with flink:vkCmdBeginRenderingKHR, if the 2514 slink:VkRenderingInfoKHR::pname:pDepthAttachment->imageView parameter to 2515 flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value of 2516 the pname:depthAttachmentFormat member of the 2517 slink:VkCommandBufferInheritanceRenderingInfoKHR structure included in 2518 the pname:pNext chain of 2519 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2520 recording each element of pname:pCommandBuffers must: be equal to the 2521 format used to create that image view 2522 * [[VUID-vkCmdExecuteCommands-pStencilAttachment-06030]] 2523 If fname:vkCmdExecuteCommands is being called within a render pass 2524 instance begun with flink:vkCmdBeginRenderingKHR, if the 2525 slink:VkRenderingInfoKHR::pname:pStencilAttachment->imageView parameter 2526 to flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value 2527 of the pname:stencilAttachmentFormat member of the 2528 slink:VkCommandBufferInheritanceRenderingInfoKHR structure included in 2529 the pname:pNext chain of 2530 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2531 recording each element of pname:pCommandBuffers must: be equal to the 2532 format used to create that image view 2533ifdef::VK_KHR_multiview,VK_VERSION_1_1[] 2534 * [[VUID-vkCmdExecuteCommands-viewMask-06031]] 2535 If fname:vkCmdExecuteCommands is being called within a render pass 2536 instance begun with flink:vkCmdBeginRenderingKHR, the pname:viewMask 2537 member of the slink:VkCommandBufferInheritanceRenderingInfoKHR structure 2538 included in the pname:pNext chain of 2539 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2540 recording each element of pname:pCommandBuffers must: be equal to the 2541 slink:VkRenderingInfoKHR::pname:viewMask parameter to 2542 flink:vkCmdBeginRenderingKHR 2543endif::VK_KHR_multiview,VK_VERSION_1_1[] 2544ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 2545 * [[VUID-vkCmdExecuteCommands-pNext-06032]] 2546 If fname:vkCmdExecuteCommands is being called within a render pass 2547 instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext 2548 chain of slink:VkCommandBufferInheritanceInfo includes a 2549 slink:VkAttachmentSampleCountInfoAMD or 2550 slink:VkAttachmentSampleCountInfoNV structure, if the pname:imageView 2551 member of an element of the 2552 slink:VkRenderingInfoKHR::pname:pColorAttachments parameter to 2553 flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the 2554 corresponding element of the pname:pColorAttachmentSamples member of the 2555 slink:VkAttachmentSampleCountInfoAMD or 2556 slink:VkAttachmentSampleCountInfoNV structure included in the 2557 pname:pNext chain of 2558 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2559 recording each element of pname:pCommandBuffers must: be equal to the 2560 sample count used to create that image view 2561 * [[VUID-vkCmdExecuteCommands-pNext-06033]] 2562 If fname:vkCmdExecuteCommands is being called within a render pass 2563 instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext 2564 chain of slink:VkCommandBufferInheritanceInfo includes a 2565 slink:VkAttachmentSampleCountInfoAMD or 2566 slink:VkAttachmentSampleCountInfoNV structure, if the 2567 slink:VkRenderingInfoKHR::pname:pDepthAttachment->imageView parameter to 2568 flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value of 2569 the pname:depthStencilAttachmentSamples member of the 2570 slink:VkAttachmentSampleCountInfoAMD or 2571 slink:VkAttachmentSampleCountInfoNV structure included in the 2572 pname:pNext chain of 2573 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2574 recording each element of pname:pCommandBuffers must: be equal to the 2575 sample count used to create that image view 2576 * [[VUID-vkCmdExecuteCommands-pNext-06034]] 2577 If fname:vkCmdExecuteCommands is being called within a render pass 2578 instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext 2579 chain of slink:VkCommandBufferInheritanceInfo includes a 2580 slink:VkAttachmentSampleCountInfoAMD or 2581 slink:VkAttachmentSampleCountInfoNV structure, if the 2582 slink:VkRenderingInfoKHR::pname:pStencilAttachment->imageView parameter 2583 to flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value 2584 of the pname:depthStencilAttachmentSamples member of the 2585 slink:VkAttachmentSampleCountInfoAMD or 2586 slink:VkAttachmentSampleCountInfoNV structure included in the 2587 pname:pNext chain of 2588 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2589 recording each element of pname:pCommandBuffers must: be equal to the 2590 sample count used to create that image view 2591 * [[VUID-vkCmdExecuteCommands-pNext-06035]] 2592 If fname:vkCmdExecuteCommands is being called within a render pass 2593 instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext 2594 chain of slink:VkCommandBufferInheritanceInfo does not include a 2595 slink:VkAttachmentSampleCountInfoAMD or 2596 slink:VkAttachmentSampleCountInfoNV structure, if the pname:imageView 2597 member of an element of the 2598 slink:VkRenderingInfoKHR::pname:pColorAttachments parameter to 2599 flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value of 2600 slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:rasterizationSamples 2601 must: be equal to the sample count used to create that image view 2602 * [[VUID-vkCmdExecuteCommands-pNext-06036]] 2603 If fname:vkCmdExecuteCommands is being called within a render pass 2604 instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext 2605 chain of slink:VkCommandBufferInheritanceInfo does not include a 2606 slink:VkAttachmentSampleCountInfoAMD or 2607 slink:VkAttachmentSampleCountInfoNV structure, if the 2608 slink:VkRenderingInfoKHR::pname:pDepthAttachment->imageView parameter to 2609 flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value of 2610 slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:rasterizationSamples 2611 must: be equal to the sample count used to create that image view 2612 * [[VUID-vkCmdExecuteCommands-pNext-06037]] 2613 If fname:vkCmdExecuteCommands is being called within a render pass 2614 instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext 2615 chain of slink:VkCommandBufferInheritanceInfo does not include a 2616 slink:VkAttachmentSampleCountInfoAMD or 2617 slink:VkAttachmentSampleCountInfoNV structure, if the 2618 slink:VkRenderingInfoKHR::pname:pStencilAttachment->imageView parameter 2619 to flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value 2620 of 2621 slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:rasterizationSamples 2622 must: be equal to the sample count used to create that image view 2623endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 2624endif::VK_KHR_dynamic_rendering[] 2625**** 2626 2627include::{generated}/validity/protos/vkCmdExecuteCommands.txt[] 2628-- 2629 2630ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2631[[commandbuffers-devicemask]] 2632== Command Buffer Device Mask 2633 2634Each command buffer has a piece of state storing the current device mask of 2635the command buffer. 2636This mask controls which physical devices within the logical device all 2637subsequent commands will execute on, including state-setting commands, 2638action commands, and synchronization commands. 2639 2640ifndef::VK_NV_scissor_exclusive[] 2641Scissor 2642endif::VK_NV_scissor_exclusive[] 2643ifdef::VK_NV_scissor_exclusive[] 2644Scissor, exclusive scissor, 2645endif::VK_NV_scissor_exclusive[] 2646and viewport state 2647ifdef::VK_EXT_extended_dynamic_state[] 2648(excluding the count of each) 2649endif::VK_EXT_extended_dynamic_state[] 2650can: be set to different values on each physical device (only when set as 2651dynamic state), and each physical device will render using its local copy of 2652the state. 2653Other state is shared between physical devices, such that all physical 2654devices use the most recently set values for the state. 2655However, when recording an action command that uses a piece of state, the 2656most recent command that set that state must: have included all physical 2657devices that execute the action command in its current device mask. 2658 2659The command buffer's device mask is orthogonal to the 2660pname:pCommandBufferDeviceMasks member of slink:VkDeviceGroupSubmitInfo. 2661Commands only execute on a physical device if the device index is set in 2662both device masks. 2663 2664[open,refpage='VkDeviceGroupCommandBufferBeginInfo',desc='Set the initial device mask for a command buffer',type='structs'] 2665-- 2666If the pname:pNext chain of slink:VkCommandBufferBeginInfo includes a 2667sname:VkDeviceGroupCommandBufferBeginInfo structure, then that structure 2668includes an initial device mask for the command buffer. 2669 2670The sname:VkDeviceGroupCommandBufferBeginInfo structure is defined as: 2671 2672include::{generated}/api/structs/VkDeviceGroupCommandBufferBeginInfo.txt[] 2673 2674ifdef::VK_KHR_device_group[] 2675or the equivalent 2676 2677include::{generated}/api/structs/VkDeviceGroupCommandBufferBeginInfoKHR.txt[] 2678endif::VK_KHR_device_group[] 2679 2680 * pname:sType is the type of this structure. 2681 * pname:pNext is `NULL` or a pointer to a structure extending this 2682 structure. 2683 * pname:deviceMask is the initial value of the command buffer's device 2684 mask. 2685 2686The initial device mask also acts as an upper bound on the set of devices 2687that can: ever be in the device mask in the command buffer. 2688 2689If this structure is not present, the initial value of a command buffer's 2690device mask is set to include all physical devices in the logical device 2691when the command buffer begins recording. 2692 2693.Valid Usage 2694**** 2695 * [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00106]] 2696 pname:deviceMask must: be a valid device mask value 2697 * [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00107]] 2698 pname:deviceMask must: not be zero 2699**** 2700 2701include::{generated}/validity/structs/VkDeviceGroupCommandBufferBeginInfo.txt[] 2702-- 2703 2704[open,refpage='vkCmdSetDeviceMask',desc='Modify device mask of a command buffer',type='protos'] 2705-- 2706To update the current device mask of a command buffer, call: 2707 2708ifdef::VK_VERSION_1_1[] 2709include::{generated}/api/protos/vkCmdSetDeviceMask.txt[] 2710endif::VK_VERSION_1_1[] 2711 2712ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] 2713 2714ifdef::VK_KHR_device_group[] 2715include::{generated}/api/protos/vkCmdSetDeviceMaskKHR.txt[] 2716endif::VK_KHR_device_group[] 2717 2718 * pname:commandBuffer is command buffer whose current device mask is 2719 modified. 2720 * pname:deviceMask is the new value of the current device mask. 2721 2722pname:deviceMask is used to filter out subsequent commands from executing on 2723all physical devices whose bit indices are not set in the mask, except 2724commands beginning a render pass instance, commands transitioning to the 2725next subpass in the render pass instance, and commands ending a render pass 2726instance, which always execute on the set of physical devices whose bit 2727indices are included in the pname:deviceMask member of the 2728slink:VkDeviceGroupRenderPassBeginInfo structure passed to the command 2729beginning the corresponding render pass instance. 2730 2731.Valid Usage 2732**** 2733 * [[VUID-vkCmdSetDeviceMask-deviceMask-00108]] 2734 pname:deviceMask must: be a valid device mask value 2735 * [[VUID-vkCmdSetDeviceMask-deviceMask-00109]] 2736 pname:deviceMask must: not be zero 2737 * [[VUID-vkCmdSetDeviceMask-deviceMask-00110]] 2738 pname:deviceMask must: not include any set bits that were not in the 2739 slink:VkDeviceGroupCommandBufferBeginInfo::pname:deviceMask value when 2740 the command buffer began recording 2741 * [[VUID-vkCmdSetDeviceMask-deviceMask-00111]] 2742 If fname:vkCmdSetDeviceMask is called inside a render pass instance, 2743 pname:deviceMask must: not include any set bits that were not in the 2744 slink:VkDeviceGroupRenderPassBeginInfo::pname:deviceMask value when the 2745 render pass instance began recording 2746**** 2747 2748include::{generated}/validity/protos/vkCmdSetDeviceMask.txt[] 2749-- 2750endif::VK_VERSION_1_1,VK_KHR_device_group[] 2751
