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 that defines the state statically is 985 equivalent 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 an array of elink:VkFormat values 1054 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 an array of elink:VkSampleCountFlagBits 1149 values defining the sample count of color attachments. 1150 * pname:depthStencilAttachmentSamples is a elink:VkSampleCountFlagBits 1151 value defining the sample count of a depth/stencil attachment. 1152 1153If slink:VkCommandBufferInheritanceInfo::pname:renderPass is 1154dlink:VK_NULL_HANDLE, ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 1155is specified in slink:VkCommandBufferBeginInfo::pname:flags, and the 1156pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes 1157sname:VkAttachmentSampleCountInfoAMD, then this structure defines the sample 1158counts of each attachment within the render pass instance. 1159If sname:VkAttachmentSampleCountInfoAMD is not included, the value of 1160slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:rasterizationSamples 1161is used as the sample count for each attachment. 1162If slink:VkCommandBufferInheritanceInfo::pname:renderPass is not 1163dlink:VK_NULL_HANDLE, or 1164ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not specified in 1165slink:VkCommandBufferBeginInfo::pname:flags, parameters of this structure 1166are ignored. 1167 1168sname:VkAttachmentSampleCountInfoAMD can: also be included in the 1169pname:pNext chain of slink:VkGraphicsPipelineCreateInfo. 1170When a graphics pipeline is created without a slink:VkRenderPass, if this 1171structure is present in the pname:pNext chain of 1172slink:VkGraphicsPipelineCreateInfo, it specifies the sample count of 1173attachments used for rendering. 1174If this structure is not specified, and the pipeline does not include a 1175slink:VkRenderPass, the value of 1176slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples is 1177used as the sample count for each attachment. 1178If a graphics pipeline is created with a valid slink:VkRenderPass, 1179parameters of this structure are ignored. 1180 1181include::{generated}/validity/structs/VkAttachmentSampleCountInfoAMD.txt[] 1182-- 1183endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 1184 1185endif::VK_KHR_dynamic_rendering[] 1186 1187Once recording starts, an application records a sequence of commands 1188(ftext:vkCmd*) to set state in the command buffer, draw, dispatch, and other 1189commands. 1190 1191ifdef::VK_NV_device_generated_commands[] 1192Several commands can also be recorded indirectly from sname:VkBuffer 1193content, see <<device-generated-commands>>. 1194endif::VK_NV_device_generated_commands[] 1195 1196[open,refpage='vkEndCommandBuffer',desc='Finish recording a command buffer',type='protos'] 1197-- 1198To complete recording of a command buffer, call: 1199 1200include::{generated}/api/protos/vkEndCommandBuffer.txt[] 1201 1202 * pname:commandBuffer is the command buffer to complete recording. 1203 1204If there was an error during recording, the application will be notified by 1205an unsuccessful return code returned by fname:vkEndCommandBuffer. 1206If the application wishes to further use the command buffer, the command 1207buffer must: be reset. 1208 1209The command buffer must: have been in the <<commandbuffers-lifecycle, 1210recording state>>, and is moved to the <<commandbuffers-lifecycle, 1211executable state>>. 1212 1213.Valid Usage 1214**** 1215 * [[VUID-vkEndCommandBuffer-commandBuffer-00059]] 1216 pname:commandBuffer must: be in the <<commandbuffers-lifecycle, 1217 recording state>> 1218 * [[VUID-vkEndCommandBuffer-commandBuffer-00060]] 1219 If pname:commandBuffer is a primary command buffer, there must: not be 1220 an active render pass instance 1221 * [[VUID-vkEndCommandBuffer-commandBuffer-00061]] 1222 All queries made <<queries-operation-active,active>> during the 1223 recording of pname:commandBuffer must: have been made inactive 1224ifdef::VK_EXT_conditional_rendering[] 1225 * [[VUID-vkEndCommandBuffer-None-01978]] 1226 Conditional rendering must: not be 1227 <<active-conditional-rendering,active>> 1228endif::VK_EXT_conditional_rendering[] 1229ifdef::VK_EXT_debug_utils[] 1230 * [[VUID-vkEndCommandBuffer-commandBuffer-01815]] 1231 If pname:commandBuffer is a secondary command buffer, there must: not be 1232 an outstanding flink:vkCmdBeginDebugUtilsLabelEXT command recorded to 1233 pname:commandBuffer that has not previously been ended by a call to 1234 flink:vkCmdEndDebugUtilsLabelEXT 1235endif::VK_EXT_debug_utils[] 1236ifdef::VK_EXT_debug_marker[] 1237 * [[VUID-vkEndCommandBuffer-commandBuffer-00062]] 1238 If pname:commandBuffer is a secondary command buffer, there must: not be 1239 an outstanding flink:vkCmdDebugMarkerBeginEXT command recorded to 1240 pname:commandBuffer that has not previously been ended by a call to 1241 flink:vkCmdDebugMarkerEndEXT 1242endif::VK_EXT_debug_marker[] 1243**** 1244 1245include::{generated}/validity/protos/vkEndCommandBuffer.txt[] 1246-- 1247 1248When a command buffer is in the executable state, it can: be submitted to a 1249queue for execution. 1250 1251 1252[[commandbuffers-submission]] 1253== Command Buffer Submission 1254 1255[NOTE] 1256.Note 1257==== 1258Submission can be a high overhead operation, and applications should: 1259attempt to batch work together into as few calls to fname:vkQueueSubmit 1260ifdef::VK_KHR_synchronization2[] 1261or fname:vkQueueSubmit2KHR 1262endif::VK_KHR_synchronization2[] 1263as possible. 1264==== 1265 1266ifdef::VK_KHR_synchronization2[] 1267[open,refpage='vkQueueSubmit2KHR',desc='Submits command buffers to a queue',type='protos'] 1268-- 1269To submit command buffers to a queue, call: 1270 1271include::{generated}/api/protos/vkQueueSubmit2KHR.txt[] 1272 1273 * pname:queue is the queue that the command buffers will be submitted to. 1274 * pname:submitCount is the number of elements in the pname:pSubmits array. 1275 * pname:pSubmits is a pointer to an array of slink:VkSubmitInfo2KHR 1276 structures, each specifying a command buffer submission batch. 1277 * pname:fence is an optional: handle to a fence to be signaled once all 1278 submitted command buffers have completed execution. 1279 If pname:fence is not dlink:VK_NULL_HANDLE, it defines a 1280 <<synchronization-fences-signaling, fence signal operation>>. 1281 1282fname:vkQueueSubmit2KHR is a <<devsandqueues-submission,queue submission 1283command>>, with each batch defined by an element of pname:pSubmits. 1284 1285Semaphore operations submitted with flink:vkQueueSubmit2KHR have additional 1286ordering constraints compared to other submission commands, with 1287dependencies involving previous and subsequent queue operations. 1288Information about these additional constraints can be found in the 1289<<synchronization-semaphores, semaphore>> section of <<synchronization, the 1290synchronization chapter>>. 1291 1292If any command buffer submitted to this queue is in the 1293<<commandbuffers-lifecycle, executable state>>, it is moved to the 1294<<commandbuffers-lifecycle, pending state>>. 1295Once execution of all submissions of a command buffer complete, it moves 1296from the <<commandbuffers-lifecycle, pending state>>, back to the 1297<<commandbuffers-lifecycle, executable state>>. 1298If a command buffer was recorded with the 1299ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves 1300back to the <<commandbuffers-lifecycle, invalid state>>. 1301 1302If fname:vkQueueSubmit2KHR fails, it may: return 1303ename:VK_ERROR_OUT_OF_HOST_MEMORY or ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 1304If it does, the implementation must: ensure that the state and contents of 1305any resources or synchronization primitives referenced by the submitted 1306command buffers and any semaphores referenced by pname:pSubmits is 1307unaffected by the call or its failure. 1308If fname:vkQueueSubmit2KHR fails in such a way that the implementation is 1309unable to make that guarantee, the implementation must: return 1310ename:VK_ERROR_DEVICE_LOST. 1311See <<devsandqueues-lost-device,Lost Device>>. 1312 1313.Valid Usage 1314**** 1315 * [[VUID-vkQueueSubmit2KHR-fence-04894]] 1316 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be 1317 unsignaled 1318 * [[VUID-vkQueueSubmit2KHR-fence-04895]] 1319 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be 1320 associated with any other queue command that has not yet completed 1321 execution on that queue 1322 * [[VUID-vkQueueSubmit2KHR-synchronization2-03866]] 1323 The <<features-synchronization2, pname:synchronization2>> feature must: 1324 be enabled 1325 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03867]] 1326 If a command recorded into the pname:commandBuffer member of any element 1327 of the pname:pCommandBufferInfos member of any element of pname:pSubmits 1328 referenced an slink:VkEvent, that event must: not be referenced by a 1329 command that has been submitted to another queue and is still in the 1330 _pending state_ 1331 * [[VUID-vkQueueSubmit2KHR-semaphore-03868]] 1332 The pname:semaphore member of any binary semaphore element of the 1333 pname:pSignalSemaphoreInfos member of any element of pname:pSubmits 1334 must: be unsignaled when the semaphore signal operation it defines is 1335 executed on the device 1336 * [[VUID-vkQueueSubmit2KHR-stageMask-03869]] 1337 The pname:stageMask member of any element of the 1338 pname:pSignalSemaphoreInfos member of any element of pname:pSubmits 1339 must: only include pipeline stages that are supported by the queue 1340 family which pname:queue belongs to 1341 * [[VUID-vkQueueSubmit2KHR-stageMask-03870]] 1342 The pname:stageMask member of any element of the 1343 pname:pWaitSemaphoreInfos member of any element of pname:pSubmits must: 1344 only include pipeline stages that are supported by the queue family 1345 which pname:queue belongs to 1346 * [[VUID-vkQueueSubmit2KHR-semaphore-03871]] 1347 When a semaphore wait operation for a binary semaphore is executed, as 1348 defined by the pname:semaphore member of any element of the 1349 pname:pWaitSemaphoreInfos member of any element of pname:pSubmits, there 1350 must: be no other queues waiting on the same semaphore 1351 * [[VUID-vkQueueSubmit2KHR-semaphore-03872]] 1352 The pname:semaphore member of any element of the 1353 pname:pWaitSemaphoreInfos member of any element of pname:pSubmits must: 1354 be semaphores that are signaled, or have 1355 <<synchronization-semaphores-signaling, semaphore signal operations>> 1356 previously submitted for execution 1357ifdef::VK_KHR_timeline_semaphore[] 1358 * [[VUID-vkQueueSubmit2KHR-semaphore-03873]] 1359 Any pname:semaphore member of any element of the 1360 pname:pWaitSemaphoreInfos member of any element of pname:pSubmits that 1361 was created with a elink:VkSemaphoreTypeKHR of 1362 ename:VK_SEMAPHORE_TYPE_BINARY_KHR must: reference a semaphore signal 1363 operation that has been submitted for execution and any semaphore signal 1364 operations on which it depends (if any) must: have also been submitted 1365 for execution 1366endif::VK_KHR_timeline_semaphore[] 1367 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03874]] 1368 The pname:commandBuffer member of any element of the 1369 pname:pCommandBufferInfos member of any element of pname:pSubmits must: 1370 be in the <<commandbuffers-lifecycle, pending or executable state>> 1371 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03875]] 1372 If a command recorded into the pname:commandBuffer member of any element 1373 of the pname:pCommandBufferInfos member of any element of pname:pSubmits 1374 was not recorded with the 1375 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 1376 the <<commandbuffers-lifecycle, pending state>> 1377 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03876]] 1378 Any <<commandbuffers-secondary, secondary command buffers recorded>> 1379 into the pname:commandBuffer member of any element of the 1380 pname:pCommandBufferInfos member of any element of pname:pSubmits must: 1381 be in the <<commandbuffers-lifecycle, pending or executable state>> 1382 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03877]] 1383 If any <<commandbuffers-secondary, secondary command buffers recorded>> 1384 into the pname:commandBuffer member of any element of the 1385 pname:pCommandBufferInfos member of any element of pname:pSubmits was 1386 not recorded with the 1387 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 1388 the <<commandbuffers-lifecycle, pending state>> 1389 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03878]] 1390 The pname:commandBuffer member of any element of the 1391 pname:pCommandBufferInfos member of any element of pname:pSubmits must: 1392 have been allocated from a sname:VkCommandPool that was created for the 1393 same queue family pname:queue belongs to 1394 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03879]] 1395 If a command recorded into the pname:commandBuffer member of any element 1396 of the pname:pCommandBufferInfos member of any element of pname:pSubmits 1397 includes a <<synchronization-queue-transfers-acquire, Queue Family 1398 Transfer Acquire Operation>>, there must: exist a previously submitted 1399 <<synchronization-queue-transfers-release, Queue Family Transfer Release 1400 Operation>> on a queue in the queue family identified by the acquire 1401 operation, with parameters matching the acquire operation as defined in 1402 the definition of such <<synchronization-queue-transfers-acquire, 1403 acquire operations>>, and which happens before the acquire operation 1404ifdef::VK_KHR_performance_query[] 1405 * [[VUID-vkQueueSubmit2KHR-commandBuffer-03880]] 1406 If a command recorded into the pname:commandBuffer member of any element 1407 of the pname:pCommandBufferInfos member of any element of pname:pSubmits 1408 was a flink:vkCmdBeginQuery whose pname:queryPool was created with a 1409 pname:queryType of ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the 1410 <<profiling-lock, profiling lock>> must: have been held continuously on 1411 the sname:VkDevice that pname:queue was retrieved from, throughout 1412 recording of those command buffers 1413endif::VK_KHR_performance_query[] 1414ifdef::VK_VERSION_1_1[] 1415 * [[VUID-vkQueueSubmit2KHR-queue-06447]] 1416 If pname:queue was not created with 1417 ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, the pname:flags member of 1418 any element of pname:pSubmits must: not include 1419 ename:VK_SUBMIT_PROTECTED_BIT_KHR 1420endif::VK_VERSION_1_1[] 1421**** 1422 1423include::{generated}/validity/protos/vkQueueSubmit2KHR.txt[] 1424-- 1425 1426[open,refpage='VkSubmitInfo2KHR',desc='Structure specifying a queue submit operation',type='structs'] 1427-- 1428The sname:VkSubmitInfo2KHR structure is defined as: 1429 1430include::{generated}/api/structs/VkSubmitInfo2KHR.txt[] 1431 1432 * pname:sType is the type of this structure. 1433 * pname:pNext is `NULL` or a pointer to a structure extending this 1434 structure. 1435 * pname:flags is a bitmask of elink:VkSubmitFlagBitsKHR. 1436 * pname:waitSemaphoreInfoCount is the number of elements in 1437 pname:pWaitSemaphoreInfos. 1438 * pname:pWaitSemaphoreInfos is a pointer to an array of 1439 slink:VkSemaphoreSubmitInfoKHR structures defining 1440 <<synchronization-semaphores-waiting, semaphore wait operations>>. 1441 * pname:commandBufferInfoCount is the number of elements in 1442 pname:pCommandBufferInfos and the number of command buffers to execute 1443 in the batch. 1444 * pname:pCommandBufferInfos is a pointer to an array of 1445 slink:VkCommandBufferSubmitInfoKHR structures describing command buffers 1446 to execute in the batch. 1447 * pname:signalSemaphoreInfoCount is the number of elements in 1448 pname:pSignalSemaphoreInfos. 1449 * pname:pSignalSemaphoreInfos is a pointer to an array of 1450 slink:VkSemaphoreSubmitInfoKHR describing 1451 <<synchronization-semaphores-signaling, semaphore signal operations>>. 1452 1453.Valid Usage 1454**** 1455ifdef::VK_KHR_timeline_semaphore[] 1456 * [[VUID-VkSubmitInfo2KHR-semaphore-03881]] 1457 If the same semaphore is used as the pname:semaphore member of both an 1458 element of pname:pSignalSemaphoreInfos and pname:pWaitSemaphoreInfos, 1459 and that semaphore is a timeline semaphore, the pname:value member of 1460 the pname:pSignalSemaphoreInfos element must: be greater than the 1461 pname:value member of the pname:pWaitSemaphoreInfos element 1462 * [[VUID-VkSubmitInfo2KHR-semaphore-03882]] 1463 If the pname:semaphore member of any element of 1464 pname:pSignalSemaphoreInfos is a timeline semaphore, the pname:value 1465 member of that element must: have a value greater than the current value 1466 of the semaphore when the <<synchronization-semaphores-signaling, 1467 semaphore signal operation>> is executed 1468 * [[VUID-VkSubmitInfo2KHR-semaphore-03883]] 1469 If the pname:semaphore member of any element of 1470 pname:pSignalSemaphoreInfos is a timeline semaphore, the pname:value 1471 member of that element must: have a value which does not differ from the 1472 current value of the semaphore or the value of any outstanding semaphore 1473 wait or signal operation on that semaphore by more than 1474 <<limits-maxTimelineSemaphoreValueDifference, 1475 pname:maxTimelineSemaphoreValueDifference>> 1476 * [[VUID-VkSubmitInfo2KHR-semaphore-03884]] 1477 If the pname:semaphore member of any element of 1478 pname:pWaitSemaphoreInfos is a timeline semaphore, the pname:value 1479 member of that element must: have a value which does not differ from the 1480 current value of the semaphore or the value of any outstanding semaphore 1481 wait or signal operation on that semaphore by more than 1482 <<limits-maxTimelineSemaphoreValueDifference, 1483 pname:maxTimelineSemaphoreValueDifference>> 1484endif::VK_KHR_timeline_semaphore[] 1485ifdef::VK_VERSION_1_1[] 1486 * [[VUID-VkSubmitInfo2KHR-flags-03886]] 1487 If pname:flags includes ename:VK_SUBMIT_PROTECTED_BIT_KHR, all elements 1488 of pname:pCommandBuffers must: be protected command buffers 1489 * [[VUID-VkSubmitInfo2KHR-flags-03887]] 1490 If pname:flags does not include ename:VK_SUBMIT_PROTECTED_BIT_KHR, each 1491 element of pname:pCommandBuffers must: not be a protected command buffer 1492endif::VK_VERSION_1_1[] 1493ifdef::VK_KHR_dynamic_rendering[] 1494 * [[VUID-VkSubmitInfo2KHR-commandBuffer-06192]] 1495 If any pname:commandBuffer member of an element of 1496 pname:pCommandBufferInfos contains any <<renderpass-suspension,resumed 1497 render pass instances>>, they must: be suspended by a render pass 1498 instance earlier in submission order within pname:pCommandBufferInfos 1499 * [[VUID-VkSubmitInfo2KHR-commandBuffer-06010]] 1500 If any pname:commandBuffer member of an element of 1501 pname:pCommandBufferInfos contains any <<renderpass-suspension,suspended 1502 render pass instances>>, they must: be resumed by a render pass instance 1503 later in submission order within pname:pCommandBufferInfos 1504 * [[VUID-VkSubmitInfo2KHR-commandBuffer-06011]] 1505 If any pname:commandBuffer member of an element of 1506 pname:pCommandBufferInfos contains any <<renderpass-suspension,suspended 1507 render pass instances>>, there must: be no action or synchronization 1508 commands between that render pass instance and the render pass instance 1509 that resumes it 1510 * [[VUID-VkSubmitInfo2KHR-commandBuffer-06012]] 1511 If any pname:commandBuffer member of an element of 1512 pname:pCommandBufferInfos contains any <<renderpass-suspension,suspended 1513 render pass instances>>, there must: be no render pass instances between 1514 that render pass instance and the render pass instance that resumes it 1515ifdef::VK_EXT_sample_locations[] 1516 * [[VUID-VkSubmitInfo2KHR-variableSampleLocations-06013]] 1517 If the <<limits-variableSampleLocations, pname:variableSampleLocations>> 1518 limit is not supported, and any pname:commandBuffer member of an element 1519 of pname:pCommandBufferInfos contains any 1520 <<renderpass-suspension,suspended render pass instances>>, where a 1521 graphics pipeline has been bound, any pipelines bound in the render pass 1522 instance that resumes it, or any subsequent render pass instances that 1523 resume from that one and so on, must: use the same sample locations 1524endif::VK_EXT_sample_locations[] 1525endif::VK_KHR_dynamic_rendering[] 1526**** 1527 1528include::{generated}/validity/structs/VkSubmitInfo2KHR.txt[] 1529-- 1530 1531[open,refpage='VkSubmitFlagBitsKHR',desc='Bitmask specifying behavior of a submission',type='enums'] 1532-- 1533Bits which can: be set in slink:VkSubmitInfo2KHR::pname:flags to specify 1534submission behavior are: 1535 1536include::{generated}/api/enums/VkSubmitFlagBitsKHR.txt[] 1537 1538 * ename:VK_SUBMIT_PROTECTED_BIT_KHR specifies that this batch is a 1539 protected submission. 1540-- 1541 1542[open,refpage='VkSubmitFlagsKHR',desc='Bitmask of VkSubmitFlagBitsKHR',type='flags'] 1543-- 1544include::{generated}/api/flags/VkSubmitFlagsKHR.txt[] 1545 1546tname:VkSubmitFlagsKHR is a bitmask type for setting a mask of zero or more 1547elink:VkSubmitFlagBitsKHR. 1548-- 1549 1550[open,refpage='VkSemaphoreSubmitInfoKHR',desc='Structure specifying a semaphore signal or wait operation',type='structs'] 1551-- 1552:refpage: VkSemaphoreSubmitInfoKHR 1553 1554The sname:VkSemaphoreSubmitInfoKHR structure is defined as: 1555 1556include::{generated}/api/structs/VkSemaphoreSubmitInfoKHR.txt[] 1557 1558 * pname:sType is the type of this structure. 1559 * pname:pNext is `NULL` or a pointer to a structure extending this 1560 structure. 1561 * pname:semaphore is a slink:VkSemaphore affected by this operation. 1562 * pname:value is 1563ifdef::VK_KHR_timeline_semaphore[] 1564 either the value used to signal pname:semaphore or the value waited on 1565 by pname:semaphore, if pname:semaphore is a timeline semaphore. 1566 Otherwise it is 1567endif::VK_KHR_timeline_semaphore[] 1568 ignored. 1569 * pname:stageMask is a tlink:VkPipelineStageFlags2KHR mask of pipeline 1570 stages which limit the first synchronization scope of a semaphore signal 1571 operation, or second synchronization scope of a semaphore wait operation 1572 as described in the <<synchronization-semaphores-waiting, semaphore wait 1573 operation>> and <<synchronization-semaphores-signaling, semaphore signal 1574 operation>> sections of <<synchronization, the synchronization 1575 chapter>>. 1576 * pname:deviceIndex is the index of the device within a device group that 1577 executes the semaphore wait or signal operation. 1578 1579Whether this structure defines a semaphore wait or signal operation is 1580defined by how it is used. 1581 1582.Valid Usage 1583**** 1584:stageMaskName: stageMask 1585include::{chapters}/commonvalidity/stage_mask_2_common.txt[] 1586 * [[VUID-VkSemaphoreSubmitInfoKHR-device-03888]] 1587 If the pname:device that pname:semaphore was created on is not a device 1588 group, pname:deviceIndex must: be `0` 1589ifdef::VK_KHR_device_group_creation,VK_VERSION_1_1[] 1590 * [[VUID-VkSemaphoreSubmitInfoKHR-device-03889]] 1591 If the pname:device that pname:semaphore was created on is a device 1592 group, pname:deviceIndex must: be a valid device index 1593endif::VK_KHR_device_group_creation,VK_VERSION_1_1[] 1594**** 1595 1596include::{generated}/validity/structs/VkSemaphoreSubmitInfoKHR.txt[] 1597-- 1598 1599[open,refpage='VkCommandBufferSubmitInfoKHR',desc='Structure specifying a command buffer submission',type='structs'] 1600-- 1601The sname:VkCommandBufferSubmitInfoKHR structure is defined as: 1602 1603include::{generated}/api/structs/VkCommandBufferSubmitInfoKHR.txt[] 1604 1605 * pname:sType is the type of this structure. 1606 * pname:pNext is `NULL` or a pointer to a structure extending this 1607 structure. 1608 * pname:commandBuffer is a slink:VkCommandBuffer to be submitted for 1609 execution. 1610 * pname:deviceMask is a bitmask indicating which devices in a device group 1611 execute the command buffer. 1612 A pname:deviceMask of `0` is equivalent to setting all bits 1613 corresponding to valid devices in the group to `1`. 1614 1615.Valid Usage 1616**** 1617 * [[VUID-VkCommandBufferSubmitInfoKHR-commandBuffer-03890]] 1618 pname:commandBuffer must: not have been allocated with 1619 ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 1620ifdef::VK_KHR_device_group_creation,VK_VERSION_1_1[] 1621 * [[VUID-VkCommandBufferSubmitInfoKHR-deviceMask-03891]] 1622 If pname:deviceMask is not `0`, it must: be a valid device mask 1623endif::VK_KHR_device_group_creation,VK_VERSION_1_1[] 1624**** 1625 1626include::{generated}/validity/structs/VkCommandBufferSubmitInfoKHR.txt[] 1627-- 1628endif::VK_KHR_synchronization2[] 1629 1630[open,refpage='vkQueueSubmit',desc='Submits a sequence of semaphores or command buffers to a queue',type='protos'] 1631-- 1632To submit command buffers to a queue, call: 1633 1634include::{generated}/api/protos/vkQueueSubmit.txt[] 1635 1636 * pname:queue is the queue that the command buffers will be submitted to. 1637 * pname:submitCount is the number of elements in the pname:pSubmits array. 1638 * pname:pSubmits is a pointer to an array of slink:VkSubmitInfo 1639 structures, each specifying a command buffer submission batch. 1640 * pname:fence is an optional: handle to a fence to be signaled once all 1641 submitted command buffers have completed execution. 1642 If pname:fence is not dlink:VK_NULL_HANDLE, it defines a 1643 <<synchronization-fences-signaling, fence signal operation>>. 1644 1645fname:vkQueueSubmit is a <<devsandqueues-submission,queue submission 1646command>>, with each batch defined by an element of pname:pSubmits. 1647Batches begin execution in the order they appear in pname:pSubmits, but may: 1648complete out of order. 1649 1650Fence and semaphore operations submitted with flink:vkQueueSubmit have 1651additional ordering constraints compared to other submission commands, with 1652dependencies involving previous and subsequent queue operations. 1653Information about these additional constraints can be found in the 1654<<synchronization-semaphores, semaphore>> and <<synchronization-fences, 1655fence>> sections of <<synchronization, the synchronization chapter>>. 1656 1657Details on the interaction of pname:pWaitDstStageMask with synchronization 1658are described in the <<synchronization-semaphores-waiting, semaphore wait 1659operation>> section of <<synchronization, the synchronization chapter>>. 1660 1661The order that batches appear in pname:pSubmits is used to determine 1662<<synchronization-submission-order, submission order>>, and thus all the 1663<<synchronization-implicit, implicit ordering guarantees>> that respect it. 1664Other than these implicit ordering guarantees and any <<synchronization, 1665explicit synchronization primitives>>, these batches may: overlap or 1666otherwise execute out of order. 1667 1668If any command buffer submitted to this queue is in the 1669<<commandbuffers-lifecycle, executable state>>, it is moved to the 1670<<commandbuffers-lifecycle, pending state>>. 1671Once execution of all submissions of a command buffer complete, it moves 1672from the <<commandbuffers-lifecycle, pending state>>, back to the 1673<<commandbuffers-lifecycle, executable state>>. 1674If a command buffer was recorded with the 1675ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves to 1676the <<commandbuffers-lifecycle, invalid state>>. 1677 1678If fname:vkQueueSubmit fails, it may: return 1679ename:VK_ERROR_OUT_OF_HOST_MEMORY or ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 1680If it does, the implementation must: ensure that the state and contents of 1681any resources or synchronization primitives referenced by the submitted 1682command buffers and any semaphores referenced by pname:pSubmits is 1683unaffected by the call or its failure. 1684If fname:vkQueueSubmit fails in such a way that the implementation is unable 1685to make that guarantee, the implementation must: return 1686ename:VK_ERROR_DEVICE_LOST. 1687See <<devsandqueues-lost-device,Lost Device>>. 1688 1689.Valid Usage 1690**** 1691 * [[VUID-vkQueueSubmit-fence-00063]] 1692 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be 1693 unsignaled 1694 * [[VUID-vkQueueSubmit-fence-00064]] 1695 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be 1696 associated with any other queue command that has not yet completed 1697 execution on that queue 1698 * [[VUID-vkQueueSubmit-pCommandBuffers-00065]] 1699 Any calls to flink:vkCmdSetEvent, flink:vkCmdResetEvent or 1700 flink:vkCmdWaitEvents that have been recorded into any of the command 1701 buffer elements of the pname:pCommandBuffers member of any element of 1702 pname:pSubmits, must: not reference any slink:VkEvent that is referenced 1703 by any of those commands in a command buffer that has been submitted to 1704 another queue and is still in the _pending state_ 1705 * [[VUID-vkQueueSubmit-pWaitDstStageMask-00066]] 1706 Any stage flag included in any element of the pname:pWaitDstStageMask 1707 member of any element of pname:pSubmits must: be a pipeline stage 1708 supported by one of the capabilities of pname:queue, as specified in the 1709 <<synchronization-pipeline-stages-supported, table of supported pipeline 1710 stages>> 1711 * [[VUID-vkQueueSubmit-pSignalSemaphores-00067]] 1712 Each binary semaphore element of the pname:pSignalSemaphores member of 1713 any element of pname:pSubmits must: be unsignaled when the semaphore 1714 signal operation it defines is executed on the device 1715 * [[VUID-vkQueueSubmit-pWaitSemaphores-00068]] 1716 When a semaphore wait operation referring to a binary semaphore defined 1717 by any element of the pname:pWaitSemaphores member of any element of 1718 pname:pSubmits executes on pname:queue, there must: be no other queues 1719 waiting on the same semaphore 1720ifndef::VK_KHR_timeline_semaphore[] 1721 * [[VUID-vkQueueSubmit-pWaitSemaphores-00069]] 1722 All elements of the pname:pWaitSemaphores member of all elements of 1723 pname:pSubmits must: be semaphores that are signaled, or have 1724 <<synchronization-semaphores-signaling, semaphore signal operations>> 1725 previously submitted for execution 1726endif::VK_KHR_timeline_semaphore[] 1727ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1728 * [[VUID-vkQueueSubmit-pWaitSemaphores-03238]] 1729 All elements of the pname:pWaitSemaphores member of all elements of 1730 pname:pSubmits created with a elink:VkSemaphoreType of 1731 ename:VK_SEMAPHORE_TYPE_BINARY must: reference a semaphore signal 1732 operation that has been submitted for execution and any semaphore signal 1733 operations on which it depends (if any) must: have also been submitted 1734 for execution 1735endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1736 * [[VUID-vkQueueSubmit-pCommandBuffers-00070]] 1737 Each element of the pname:pCommandBuffers member of each element of 1738 pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or 1739 executable state>> 1740 * [[VUID-vkQueueSubmit-pCommandBuffers-00071]] 1741 If any element of the pname:pCommandBuffers member of any element of 1742 pname:pSubmits was not recorded with the 1743 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 1744 the <<commandbuffers-lifecycle, pending state>> 1745 * [[VUID-vkQueueSubmit-pCommandBuffers-00072]] 1746 Any <<commandbuffers-secondary, secondary command buffers recorded>> 1747 into any element of the pname:pCommandBuffers member of any element of 1748 pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or 1749 executable state>> 1750 * [[VUID-vkQueueSubmit-pCommandBuffers-00073]] 1751 If any <<commandbuffers-secondary, secondary command buffers recorded>> 1752 into any element of the pname:pCommandBuffers member of any element of 1753 pname:pSubmits was not recorded with the 1754 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 1755 the <<commandbuffers-lifecycle, pending state>> 1756 * [[VUID-vkQueueSubmit-pCommandBuffers-00074]] 1757 Each element of the pname:pCommandBuffers member of each element of 1758 pname:pSubmits must: have been allocated from a sname:VkCommandPool that 1759 was created for the same queue family pname:queue belongs to 1760 * [[VUID-vkQueueSubmit-pSubmits-02207]] 1761 If any element of pname:pSubmits->pCommandBuffers includes a 1762 <<synchronization-queue-transfers-acquire, Queue Family Transfer Acquire 1763 Operation>>, there must: exist a previously submitted 1764 <<synchronization-queue-transfers-release, Queue Family Transfer Release 1765 Operation>> on a queue in the queue family identified by the acquire 1766 operation, with parameters matching the acquire operation as defined in 1767 the definition of such <<synchronization-queue-transfers-acquire, 1768 acquire operations>>, and which happens-before the acquire operation 1769ifdef::VK_KHR_performance_query[] 1770 * [[VUID-vkQueueSubmit-pCommandBuffers-03220]] 1771 If a command recorded into any element of pname:pCommandBuffers was a 1772 flink:vkCmdBeginQuery whose pname:queryPool was created with a 1773 pname:queryType of ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the 1774 <<profiling-lock, profiling lock>> must: have been held continuously on 1775 the sname:VkDevice that pname:queue was retrieved from, throughout 1776 recording of those command buffers 1777endif::VK_KHR_performance_query[] 1778 * [[VUID-vkQueueSubmit-pSubmits-02808]] 1779 Any resource created with ename:VK_SHARING_MODE_EXCLUSIVE that is read 1780 by an operation specified by pname:pSubmits must: not be owned by any 1781 queue family other than the one which pname:queue belongs to, at the 1782 time it is executed 1783 * [[VUID-vkQueueSubmit-pSubmits-04626]] 1784 Any resource created with ename:VK_SHARING_MODE_CONCURRENT that is 1785 accessed by an operation specified by pname:pSubmits must: have included 1786 the queue family of pname:queue at resource creation time 1787ifdef::VK_VERSION_1_1[] 1788 * [[VUID-vkQueueSubmit-queue-06448]] 1789 If pname:queue was not created with 1790 ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, there must: be no element of 1791 pname:pSubmits that includes an slink:VkProtectedSubmitInfo structure in 1792 its pname:pNext chain with pname:protectedSubmit equal to ename:VK_TRUE 1793endif::VK_VERSION_1_1[] 1794**** 1795 1796include::{generated}/validity/protos/vkQueueSubmit.txt[] 1797-- 1798 1799[open,refpage='VkSubmitInfo',desc='Structure specifying a queue submit operation',type='structs'] 1800-- 1801The sname:VkSubmitInfo structure is defined as: 1802 1803include::{generated}/api/structs/VkSubmitInfo.txt[] 1804 1805 * pname:sType is the type of this structure. 1806 * pname:pNext is `NULL` or a pointer to a structure extending this 1807 structure. 1808 * pname:waitSemaphoreCount is the number of semaphores upon which to wait 1809 before executing the command buffers for the batch. 1810 * pname:pWaitSemaphores is a pointer to an array of slink:VkSemaphore 1811 handles upon which to wait before the command buffers for this batch 1812 begin execution. 1813 If semaphores to wait on are provided, they define a 1814 <<synchronization-semaphores-waiting, semaphore wait operation>>. 1815 * pname:pWaitDstStageMask is a pointer to an array of pipeline stages at 1816 which each corresponding semaphore wait will occur. 1817 * pname:commandBufferCount is the number of command buffers to execute in 1818 the batch. 1819 * pname:pCommandBuffers is a pointer to an array of slink:VkCommandBuffer 1820 handles to execute in the batch. 1821 * pname:signalSemaphoreCount is the number of semaphores to be signaled 1822 once the commands specified in pname:pCommandBuffers have completed 1823 execution. 1824 * pname:pSignalSemaphores is a pointer to an array of slink:VkSemaphore 1825 handles which will be signaled when the command buffers for this batch 1826 have completed execution. 1827 If semaphores to be signaled are provided, they define a 1828 <<synchronization-semaphores-signaling, semaphore signal operation>>. 1829 1830The order that command buffers appear in pname:pCommandBuffers is used to 1831determine <<synchronization-submission-order, submission order>>, and thus 1832all the <<synchronization-implicit, implicit ordering guarantees>> that 1833respect it. 1834Other than these implicit ordering guarantees and any <<synchronization, 1835explicit synchronization primitives>>, these command buffers may: overlap or 1836otherwise execute out of order. 1837 1838 1839.Valid Usage 1840**** 1841 * [[VUID-VkSubmitInfo-pCommandBuffers-00075]] 1842 Each element of pname:pCommandBuffers must: not have been allocated with 1843 ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 1844 * [[VUID-VkSubmitInfo-pWaitDstStageMask-00076]] 1845 If the <<features-geometryShader,geometry shaders>> feature is not 1846 enabled, each element of pname:pWaitDstStageMask must: not contain 1847 ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT 1848 * [[VUID-VkSubmitInfo-pWaitDstStageMask-00077]] 1849 If the <<features-tessellationShader,tessellation shaders>> feature is 1850 not enabled, each element of pname:pWaitDstStageMask must: not contain 1851 ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or 1852 ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT 1853 * [[VUID-VkSubmitInfo-pWaitDstStageMask-00078]] 1854 Each element of pname:pWaitDstStageMask must: not include 1855 ename:VK_PIPELINE_STAGE_HOST_BIT 1856ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1857 * [[VUID-VkSubmitInfo-pWaitSemaphores-03239]] 1858 If any element of pname:pWaitSemaphores or pname:pSignalSemaphores was 1859 created with a elink:VkSemaphoreType of 1860 ename:VK_SEMAPHORE_TYPE_TIMELINE, then the pname:pNext chain must: 1861 include a slink:VkTimelineSemaphoreSubmitInfo structure 1862 * [[VUID-VkSubmitInfo-pNext-03240]] 1863 If the pname:pNext chain of this structure includes a 1864 slink:VkTimelineSemaphoreSubmitInfo structure and any element of 1865 pname:pWaitSemaphores was created with a elink:VkSemaphoreType of 1866 ename:VK_SEMAPHORE_TYPE_TIMELINE, then its pname:waitSemaphoreValueCount 1867 member must: equal pname:waitSemaphoreCount 1868 * [[VUID-VkSubmitInfo-pNext-03241]] 1869 If the pname:pNext chain of this structure includes a 1870 slink:VkTimelineSemaphoreSubmitInfo structure and any element of 1871 pname:pSignalSemaphores was created with a elink:VkSemaphoreType of 1872 ename:VK_SEMAPHORE_TYPE_TIMELINE, then its 1873 pname:signalSemaphoreValueCount member must: equal 1874 pname:signalSemaphoreCount 1875 * [[VUID-VkSubmitInfo-pSignalSemaphores-03242]] 1876 For each element of pname:pSignalSemaphores created with a 1877 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 1878 corresponding element of 1879 slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: 1880 have a value greater than the current value of the semaphore when the 1881 <<synchronization-semaphores-signaling,semaphore signal operation>> is 1882 executed 1883 * [[VUID-VkSubmitInfo-pWaitSemaphores-03243]] 1884 For each element of pname:pWaitSemaphores created with a 1885 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 1886 corresponding element of 1887 slink:VkTimelineSemaphoreSubmitInfo::pname:pWaitSemaphoreValues must: 1888 have a value which does not differ from the current value of the 1889 semaphore or the value of any outstanding semaphore wait or signal 1890 operation on that semaphore by more than 1891 <<limits-maxTimelineSemaphoreValueDifference, 1892 pname:maxTimelineSemaphoreValueDifference>> 1893 * [[VUID-VkSubmitInfo-pSignalSemaphores-03244]] 1894 For each element of pname:pSignalSemaphores created with a 1895 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 1896 corresponding element of 1897 slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: 1898 have a value which does not differ from the current value of the 1899 semaphore or the value of any outstanding semaphore wait or signal 1900 operation on that semaphore by more than 1901 <<limits-maxTimelineSemaphoreValueDifference, 1902 pname:maxTimelineSemaphoreValueDifference>> 1903endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1904ifdef::VK_NV_mesh_shader[] 1905 * [[VUID-VkSubmitInfo-pWaitDstStageMask-02089]] 1906 If the <<features-meshShader,mesh shaders>> feature is not enabled, each 1907 element of pname:pWaitDstStageMask must: not contain 1908 ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV 1909 * [[VUID-VkSubmitInfo-pWaitDstStageMask-02090]] 1910 If the <<features-taskShader,task shaders>> feature is not enabled, each 1911 element of pname:pWaitDstStageMask must: not contain 1912 ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV 1913endif::VK_NV_mesh_shader[] 1914ifdef::VK_VERSION_1_1[] 1915 * [[VUID-VkSubmitInfo-pNext-04120]] 1916 If the pname:pNext chain of this structure does not include a 1917 sname:VkProtectedSubmitInfo structure with pname:protectedSubmit set to 1918 ename:VK_TRUE, then each element of the pname:pCommandBuffers array 1919 must: be an unprotected command buffer 1920 * [[VUID-VkSubmitInfo-pNext-04148]] 1921 If the pname:pNext chain of this structure includes a 1922 sname:VkProtectedSubmitInfo structure with pname:protectedSubmit set to 1923 ename:VK_TRUE, then each element of the pname:pCommandBuffers array 1924 must: be a protected command buffer 1925endif::VK_VERSION_1_1[] 1926ifdef::VK_KHR_dynamic_rendering[] 1927 * [[VUID-VkSubmitInfo-pCommandBuffers-06193]] 1928 If pname:pCommandBuffers contains any <<renderpass-suspension,resumed 1929 render pass instances>>, they must: be suspended by a render pass 1930 instance earlier in submission order within pname:pCommandBuffers 1931 * [[VUID-VkSubmitInfo-pCommandBuffers-06014]] 1932 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 1933 render pass instances>>, they must: be resumed by a render pass instance 1934 later in submission order within pname:pCommandBuffers 1935 * [[VUID-VkSubmitInfo-pCommandBuffers-06015]] 1936 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 1937 render pass instances>>, there must: be no action or synchronization 1938 commands between that render pass instance and the render pass instance 1939 that resumes it 1940 * [[VUID-VkSubmitInfo-pCommandBuffers-06016]] 1941 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 1942 render pass instances>>, there must: be no render pass instances between 1943 that render pass instance and the render pass instance that resumes it 1944ifdef::VK_EXT_sample_locations[] 1945 * [[VUID-VkSubmitInfo-variableSampleLocations-06017]] 1946 If the <<limits-variableSampleLocations, pname:variableSampleLocations>> 1947 limit is not supported, and any element of pname:pCommandBuffers 1948 contains any <<renderpass-suspension,suspended render pass instances>>, 1949 where a graphics pipeline has been bound, any pipelines bound in the 1950 render pass instance that resumes it, or any subsequent render pass 1951 instances that resume from that one and so on, must: use the same sample 1952 locations 1953endif::VK_EXT_sample_locations[] 1954endif::VK_KHR_dynamic_rendering[] 1955**** 1956 1957include::{generated}/validity/structs/VkSubmitInfo.txt[] 1958-- 1959 1960ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1961[open,refpage='VkTimelineSemaphoreSubmitInfo',desc='Structure specifying signal and wait values for timeline semaphores',type='structs',alias='VkTimelineSemaphoreSubmitInfoKHR'] 1962-- 1963To specify the values to use when waiting for and signaling semaphores 1964created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE, 1965add a slink:VkTimelineSemaphoreSubmitInfo structure to the pname:pNext chain 1966of the slink:VkSubmitInfo structure when using flink:vkQueueSubmit or the 1967slink:VkBindSparseInfo structure when using flink:vkQueueBindSparse. 1968The sname:VkTimelineSemaphoreSubmitInfo structure is defined as: 1969 1970include::{generated}/api/structs/VkTimelineSemaphoreSubmitInfo.txt[] 1971 1972ifdef::VK_KHR_timeline_semaphore[] 1973or the equivalent 1974 1975include::{generated}/api/structs/VkTimelineSemaphoreSubmitInfoKHR.txt[] 1976endif::VK_KHR_timeline_semaphore[] 1977 1978 * pname:sType is the type of this structure. 1979 * pname:pNext is `NULL` or a pointer to a structure extending this 1980 structure. 1981 * pname:waitSemaphoreValueCount is the number of semaphore wait values 1982 specified in pname:pWaitSemaphoreValues. 1983 * pname:pWaitSemaphoreValues is a pointer to an array of 1984 pname:waitSemaphoreValueCount values for the corresponding semaphores in 1985 slink:VkSubmitInfo::pname:pWaitSemaphores to wait for. 1986 * pname:signalSemaphoreValueCount is the number of semaphore signal values 1987 specified in pname:pSignalSemaphoreValues. 1988 * pname:pSignalSemaphoreValues is a pointer to an array 1989 pname:signalSemaphoreValueCount values for the corresponding semaphores 1990 in slink:VkSubmitInfo::pname:pSignalSemaphores to set when signaled. 1991 1992If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or 1993slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in 1994pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively was 1995not created with a elink:VkSemaphoreType of 1996ename:VK_SEMAPHORE_TYPE_TIMELINE, the implementation must: ignore the value 1997in the pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry. 1998 1999include::{generated}/validity/structs/VkTimelineSemaphoreSubmitInfo.txt[] 2000-- 2001endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2002 2003ifdef::VK_KHR_external_semaphore_win32[] 2004[open,refpage='VkD3D12FenceSubmitInfoKHR',desc='Structure specifying values for Direct3D 12 fence-backed semaphores',type='structs'] 2005-- 2006To specify the values to use when waiting for and signaling semaphores whose 2007<<synchronization-semaphores-importing,current payload>> refers to a 2008Direct3D 12 fence, add a slink:VkD3D12FenceSubmitInfoKHR structure to the 2009pname:pNext chain of the slink:VkSubmitInfo structure. 2010The sname:VkD3D12FenceSubmitInfoKHR structure is defined as: 2011 2012include::{generated}/api/structs/VkD3D12FenceSubmitInfoKHR.txt[] 2013 2014 * pname:sType is the type of this structure. 2015 * pname:pNext is `NULL` or a pointer to a structure extending this 2016 structure. 2017 * pname:waitSemaphoreValuesCount is the number of semaphore wait values 2018 specified in pname:pWaitSemaphoreValues. 2019 * pname:pWaitSemaphoreValues is a pointer to an array of 2020 pname:waitSemaphoreValuesCount values for the corresponding semaphores 2021 in slink:VkSubmitInfo::pname:pWaitSemaphores to wait for. 2022 * pname:signalSemaphoreValuesCount is the number of semaphore signal 2023 values specified in pname:pSignalSemaphoreValues. 2024 * pname:pSignalSemaphoreValues is a pointer to an array of 2025 pname:signalSemaphoreValuesCount values for the corresponding semaphores 2026 in slink:VkSubmitInfo::pname:pSignalSemaphores to set when signaled. 2027 2028If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or 2029slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in 2030pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively does 2031not currently have a <<synchronization-semaphores-payloads, payload>> 2032referring to a Direct3D 12 fence, the implementation must: ignore the value 2033in the pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry. 2034 2035ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2036[NOTE] 2037.Note 2038==== 2039As the introduction of the external semaphore handle type 2040ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT predates that of 2041timeline semaphores, support for importing semaphore payloads from external 2042handles of that type into semaphores created (implicitly or explicitly) with 2043a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY is preserved for 2044backwards compatibility. 2045However, applications should: prefer importing such handle types into 2046semaphores created with a elink:VkSemaphoreType of 2047ename:VK_SEMAPHORE_TYPE_TIMELINE, and use the 2048slink:VkTimelineSemaphoreSubmitInfo structure instead of the 2049sname:VkD3D12FenceSubmitInfoKHR structure to specify the values to use when 2050waiting for and signaling such semaphores. 2051==== 2052endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2053 2054.Valid Usage 2055**** 2056 * [[VUID-VkD3D12FenceSubmitInfoKHR-waitSemaphoreValuesCount-00079]] 2057 pname:waitSemaphoreValuesCount must: be the same value as 2058 sname:VkSubmitInfo::pname:waitSemaphoreCount, where sname:VkSubmitInfo 2059 is in the pname:pNext chain of this sname:VkD3D12FenceSubmitInfoKHR 2060 structure 2061 * [[VUID-VkD3D12FenceSubmitInfoKHR-signalSemaphoreValuesCount-00080]] 2062 pname:signalSemaphoreValuesCount must: be the same value as 2063 sname:VkSubmitInfo::pname:signalSemaphoreCount, where sname:VkSubmitInfo 2064 is in the pname:pNext chain of this sname:VkD3D12FenceSubmitInfoKHR 2065 structure 2066**** 2067 2068include::{generated}/validity/structs/VkD3D12FenceSubmitInfoKHR.txt[] 2069-- 2070endif::VK_KHR_external_semaphore_win32[] 2071 2072ifdef::VK_KHR_win32_keyed_mutex[] 2073[open,refpage='VkWin32KeyedMutexAcquireReleaseInfoKHR',desc='Use the Windows keyed mutex mechanism to synchronize work',type='structs'] 2074-- 2075When submitting work that operates on memory imported from a Direct3D 11 2076resource to a queue, the keyed mutex mechanism may: be used in addition to 2077Vulkan semaphores to synchronize the work. 2078Keyed mutexes are a property of a properly created shareable Direct3D 11 2079resource. 2080They can: only be used if the imported resource was created with the 2081etext:D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX flag. 2082 2083To acquire keyed mutexes before submitted work and/or release them after, 2084add a slink:VkWin32KeyedMutexAcquireReleaseInfoKHR structure to the 2085pname:pNext chain of the slink:VkSubmitInfo structure. 2086 2087The sname:VkWin32KeyedMutexAcquireReleaseInfoKHR structure is defined as: 2088 2089include::{generated}/api/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.txt[] 2090 2091 * pname:sType is the type of this structure. 2092 * pname:pNext is `NULL` or a pointer to a structure extending this 2093 structure. 2094 * pname:acquireCount is the number of entries in the pname:pAcquireSyncs, 2095 pname:pAcquireKeys, and pname:pAcquireTimeouts arrays. 2096 * pname:pAcquireSyncs is a pointer to an array of slink:VkDeviceMemory 2097 objects which were imported from Direct3D 11 resources. 2098 * pname:pAcquireKeys is a pointer to an array of mutex key values to wait 2099 for prior to beginning the submitted work. 2100 Entries refer to the keyed mutex associated with the corresponding 2101 entries in pname:pAcquireSyncs. 2102 * pname:pAcquireTimeouts is a pointer to an array of timeout values, in 2103 millisecond units, for each acquire specified in pname:pAcquireKeys. 2104 * pname:releaseCount is the number of entries in the pname:pReleaseSyncs 2105 and pname:pReleaseKeys arrays. 2106 * pname:pReleaseSyncs is a pointer to an array of slink:VkDeviceMemory 2107 objects which were imported from Direct3D 11 resources. 2108 * pname:pReleaseKeys is a pointer to an array of mutex key values to set 2109 when the submitted work has completed. 2110 Entries refer to the keyed mutex associated with the corresponding 2111 entries in pname:pReleaseSyncs. 2112 2113.Valid Usage 2114**** 2115 * [[VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireSyncs-00081]] 2116 Each member of pname:pAcquireSyncs and pname:pReleaseSyncs must: be a 2117 device memory object imported by setting 2118 slink:VkImportMemoryWin32HandleInfoKHR::pname:handleType to 2119 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT or 2120 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT 2121**** 2122 2123include::{generated}/validity/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.txt[] 2124-- 2125endif::VK_KHR_win32_keyed_mutex[] 2126 2127ifdef::VK_NV_win32_keyed_mutex[] 2128include::VK_NV_win32_keyed_mutex/keyed_mutex_submit.txt[] 2129endif::VK_NV_win32_keyed_mutex[] 2130 2131ifdef::VK_VERSION_1_1[] 2132[open,refpage='VkProtectedSubmitInfo',desc='Structure indicating whether the submission is protected',type='structs'] 2133-- 2134If the pname:pNext chain of slink:VkSubmitInfo includes a 2135sname:VkProtectedSubmitInfo structure, then the structure indicates whether 2136the batch is protected. 2137The sname:VkProtectedSubmitInfo structure is defined as: 2138 2139include::{generated}/api/structs/VkProtectedSubmitInfo.txt[] 2140 2141 * pname:protectedSubmit specifies whether the batch is protected. 2142 If pname:protectedSubmit is ename:VK_TRUE, the batch is protected. 2143 If pname:protectedSubmit is ename:VK_FALSE, the batch is unprotected. 2144 If the sname:VkSubmitInfo::pname:pNext chain does not include this 2145 structure, the batch is unprotected. 2146 2147include::{generated}/validity/structs/VkProtectedSubmitInfo.txt[] 2148-- 2149endif::VK_VERSION_1_1[] 2150 2151ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2152[open,refpage='VkDeviceGroupSubmitInfo',desc='Structure indicating which physical devices execute semaphore operations and command buffers',type='structs'] 2153-- 2154 2155If the pname:pNext chain of slink:VkSubmitInfo includes a 2156sname:VkDeviceGroupSubmitInfo structure, then that structure includes device 2157indices and masks specifying which physical devices execute semaphore 2158operations and command buffers. 2159 2160The sname:VkDeviceGroupSubmitInfo structure is defined as: 2161 2162include::{generated}/api/structs/VkDeviceGroupSubmitInfo.txt[] 2163 2164ifdef::VK_KHR_device_group[] 2165or the equivalent 2166 2167include::{generated}/api/structs/VkDeviceGroupSubmitInfoKHR.txt[] 2168endif::VK_KHR_device_group[] 2169 2170 * pname:sType is the type of this structure. 2171 * pname:pNext is `NULL` or a pointer to a structure extending this 2172 structure. 2173 * pname:waitSemaphoreCount is the number of elements in the 2174 pname:pWaitSemaphoreDeviceIndices array. 2175 * pname:pWaitSemaphoreDeviceIndices is a pointer to an array of 2176 pname:waitSemaphoreCount device indices indicating which physical device 2177 executes the semaphore wait operation in the corresponding element of 2178 slink:VkSubmitInfo::pname:pWaitSemaphores. 2179 * pname:commandBufferCount is the number of elements in the 2180 pname:pCommandBufferDeviceMasks array. 2181 * pname:pCommandBufferDeviceMasks is a pointer to an array of 2182 pname:commandBufferCount device masks indicating which physical devices 2183 execute the command buffer in the corresponding element of 2184 slink:VkSubmitInfo::pname:pCommandBuffers. 2185 A physical device executes the command buffer if the corresponding bit 2186 is set in the mask. 2187 * pname:signalSemaphoreCount is the number of elements in the 2188 pname:pSignalSemaphoreDeviceIndices array. 2189 * pname:pSignalSemaphoreDeviceIndices is a pointer to an array of 2190 pname:signalSemaphoreCount device indices indicating which physical 2191 device executes the semaphore signal operation in the corresponding 2192 element of slink:VkSubmitInfo::pname:pSignalSemaphores. 2193 2194If this structure is not present, semaphore operations and command buffers 2195execute on device index zero. 2196 2197.Valid Usage 2198**** 2199 * [[VUID-VkDeviceGroupSubmitInfo-waitSemaphoreCount-00082]] 2200 pname:waitSemaphoreCount must: equal 2201 slink:VkSubmitInfo::pname:waitSemaphoreCount 2202 * [[VUID-VkDeviceGroupSubmitInfo-commandBufferCount-00083]] 2203 pname:commandBufferCount must: equal 2204 slink:VkSubmitInfo::pname:commandBufferCount 2205 * [[VUID-VkDeviceGroupSubmitInfo-signalSemaphoreCount-00084]] 2206 pname:signalSemaphoreCount must: equal 2207 slink:VkSubmitInfo::pname:signalSemaphoreCount 2208 * [[VUID-VkDeviceGroupSubmitInfo-pWaitSemaphoreDeviceIndices-00085]] 2209 All elements of pname:pWaitSemaphoreDeviceIndices and 2210 pname:pSignalSemaphoreDeviceIndices must: be valid device indices 2211 * [[VUID-VkDeviceGroupSubmitInfo-pCommandBufferDeviceMasks-00086]] 2212 All elements of pname:pCommandBufferDeviceMasks must: be valid device 2213 masks 2214**** 2215 2216include::{generated}/validity/structs/VkDeviceGroupSubmitInfo.txt[] 2217-- 2218endif::VK_VERSION_1_1,VK_KHR_device_group[] 2219 2220ifdef::VK_KHR_performance_query[] 2221If the pname:pNext chain of slink:VkSubmitInfo includes a 2222slink:VkPerformanceQuerySubmitInfoKHR structure, then the structure 2223indicates which counter pass is active for the batch in that submit. 2224 2225[open,refpage='VkPerformanceQuerySubmitInfoKHR',desc='Structure indicating which counter pass index is active for performance queries',type='structs'] 2226-- 2227The sname:VkPerformanceQuerySubmitInfoKHR structure is defined as: 2228 2229include::{generated}/api/structs/VkPerformanceQuerySubmitInfoKHR.txt[] 2230 2231 * pname:sType is the type of this structure. 2232 * pname:pNext is `NULL` or a pointer to a structure extending this 2233 structure. 2234 * pname:counterPassIndex specifies which counter pass index is active. 2235 2236If the sname:VkSubmitInfo::pname:pNext chain does not include this 2237structure, the batch defaults to use counter pass index 0. 2238 2239.Valid Usage 2240**** 2241 * [[VUID-VkPerformanceQuerySubmitInfoKHR-counterPassIndex-03221]] 2242 pname:counterPassIndex must: be less than the number of counter passes 2243 required by any queries within the batch. 2244 The required number of counter passes for a performance query is 2245 obtained by calling 2246 flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR 2247**** 2248 2249include::{generated}/validity/structs/VkPerformanceQuerySubmitInfoKHR.txt[] 2250-- 2251endif::VK_KHR_performance_query[] 2252 2253 2254[[commandbuffers-submission-progress]] 2255== Queue Forward Progress 2256 2257When using binary semaphores, the application must: ensure that command 2258buffer submissions will be able to complete without any subsequent 2259operations by the application on any queue. 2260After any call to fname:vkQueueSubmit (or other queue operation), for every 2261queued wait on a semaphore 2262ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2263created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY 2264endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2265there must: be a prior signal of that semaphore that will not be consumed by 2266a different wait on the semaphore. 2267 2268ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2269When using timeline semaphores, wait-before-signal behavior is well-defined 2270and applications can: submit work via fname:vkQueueSubmit which defines a 2271<<synchronization-semaphores-waiting, timeline semaphore wait operation>> 2272before submitting a corresponding <<synchronization-semaphores-signaling, 2273semaphore signal operation>>. 2274For each <<synchronization-semaphores-waiting, timeline semaphore wait 2275operation>> defined by a call to fname:vkQueueSubmit, the application must: 2276ensure that a corresponding <<synchronization-semaphores-signaling, 2277semaphore signal operation>> is executed before forward progress can be 2278made. 2279endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2280 2281Command buffers in the submission can: include flink:vkCmdWaitEvents 2282commands that wait on events that will not be signaled by earlier commands 2283in the queue. 2284Such events must: be signaled by the application using flink:vkSetEvent, and 2285the fname:vkCmdWaitEvents commands that wait upon them must: not be inside a 2286render pass instance. 2287The event must: be set before the flink:vkCmdWaitEvents command is executed. 2288 2289[NOTE] 2290.Note 2291==== 2292Implementations may have some tolerance for waiting on events to be set, but 2293this is defined outside of the scope of Vulkan. 2294==== 2295 2296 2297[[commandbuffers-secondary]] 2298== Secondary Command Buffer Execution 2299 2300[open,refpage='vkCmdExecuteCommands',desc='Execute a secondary command buffer from a primary command buffer',type='protos'] 2301-- 2302A secondary command buffer must: not be directly submitted to a queue. 2303Instead, secondary command buffers are recorded to execute as part of a 2304primary command buffer with the command: 2305 2306include::{generated}/api/protos/vkCmdExecuteCommands.txt[] 2307 2308 * pname:commandBuffer is a handle to a primary command buffer that the 2309 secondary command buffers are executed in. 2310 * pname:commandBufferCount is the length of the pname:pCommandBuffers 2311 array. 2312 * pname:pCommandBuffers is a pointer to an array of 2313 pname:commandBufferCount secondary command buffer handles, which are 2314 recorded to execute in the primary command buffer in the order they are 2315 listed in the array. 2316 2317If any element of pname:pCommandBuffers was not recorded with the 2318ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, and it was recorded 2319into any other primary command buffer which is currently in the 2320<<commandbuffers-lifecycle, executable or recording state>>, that primary 2321command buffer becomes <<commandbuffers-lifecycle, invalid>>. 2322 2323.Valid Usage 2324**** 2325 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00088]] 2326 Each element of pname:pCommandBuffers must: have been allocated with a 2327 pname:level of ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 2328 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00089]] 2329 Each element of pname:pCommandBuffers must: be in the 2330 <<commandbuffers-lifecycle, pending or executable state>> 2331 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00091]] 2332 If any element of pname:pCommandBuffers was not recorded with the 2333 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not be 2334 in the <<commandbuffers-lifecycle, pending state>> 2335 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00092]] 2336 If any element of pname:pCommandBuffers was not recorded with the 2337 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not 2338 have already been recorded to pname:commandBuffer 2339 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00093]] 2340 If any element of pname:pCommandBuffers was not recorded with the 2341 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not 2342 appear more than once in pname:pCommandBuffers 2343 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00094]] 2344 Each element of pname:pCommandBuffers must: have been allocated from a 2345 sname:VkCommandPool that was created for the same queue family as the 2346 sname:VkCommandPool from which pname:commandBuffer was allocated 2347 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00096]] 2348 If fname:vkCmdExecuteCommands is being called within a render pass 2349 instance, each element of pname:pCommandBuffers must: have been recorded 2350 with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 2351 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00099]] 2352 If fname:vkCmdExecuteCommands is being called within a render pass 2353 instance, and any element of pname:pCommandBuffers was recorded with 2354 slink:VkCommandBufferInheritanceInfo::pname:framebuffer not equal to 2355 dlink:VK_NULL_HANDLE, that sname:VkFramebuffer must: match the 2356 sname:VkFramebuffer used in the current render pass instance 2357 * [[VUID-vkCmdExecuteCommands-contents-06018]] 2358 If fname:vkCmdExecuteCommands is being called within a render pass 2359 instance begun with flink:vkCmdBeginRenderPass, its pname:contents 2360 parameter must: have been set to 2361 ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS 2362 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06019]] 2363 If fname:vkCmdExecuteCommands is being called within a render pass 2364 instance begun with flink:vkCmdBeginRenderPass, each element of 2365 pname:pCommandBuffers must: have been recorded with 2366 slink:VkCommandBufferInheritanceInfo::pname:subpass set to the index of 2367 the subpass which the given command buffer will be executed in 2368 * [[VUID-vkCmdExecuteCommands-pBeginInfo-06020]] 2369 If fname:vkCmdExecuteCommands is being called within a render pass 2370 instance begun with flink:vkCmdBeginRenderPass, the render passes 2371 specified in the pname:pBeginInfo->pInheritanceInfo->renderPass members 2372 of the flink:vkBeginCommandBuffer commands used to begin recording each 2373 element of pname:pCommandBuffers must: be 2374 <<renderpass-compatibility,compatible>> with the current render pass 2375ifndef::VK_KHR_dynamic_rendering[] 2376 * [[VUID-vkCmdExecuteCommands-contents-00095]] 2377 If fname:vkCmdExecuteCommands is being called within a render pass 2378 instance, that render pass instance must: have been begun with the 2379 pname:contents parameter of fname:vkCmdBeginRenderPass set to 2380 ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS 2381 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00097]] 2382 If fname:vkCmdExecuteCommands is being called within a render pass 2383 instance, each element of pname:pCommandBuffers must: have been recorded 2384 with sname:VkCommandBufferInheritanceInfo::pname:subpass set to the 2385 index of the subpass which the given command buffer will be executed in 2386 * [[VUID-vkCmdExecuteCommands-pInheritanceInfo-00098]] 2387 If fname:vkCmdExecuteCommands is being called within a render pass 2388 instance, the render passes specified in the 2389 pname:pBeginInfo->pInheritanceInfo->renderPass members of the 2390 flink:vkBeginCommandBuffer commands used to begin recording each element 2391 of pname:pCommandBuffers must: be 2392 <<renderpass-compatibility,compatible>> with the current render pass 2393endif::VK_KHR_dynamic_rendering[] 2394ifdef::VK_QCOM_render_pass_transform[] 2395 * [[VUID-vkCmdExecuteCommands-pNext-02865]] 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 in the 2401 pname:pNext chain of slink:VkCommandBufferBeginInfo 2402 * [[VUID-vkCmdExecuteCommands-pNext-02866]] 2403 If fname:vkCmdExecuteCommands is being called within a render pass 2404 instance that included slink:VkRenderPassTransformBeginInfoQCOM in the 2405 pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of 2406 pname:pCommandBuffers must: have been recorded with 2407 slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM::pname:transform 2408 identical to slink:VkRenderPassTransformBeginInfoQCOM::pname:transform 2409 * [[VUID-vkCmdExecuteCommands-pNext-02867]] 2410 If fname:vkCmdExecuteCommands is being called within a render pass 2411 instance that included slink:VkRenderPassTransformBeginInfoQCOM in the 2412 pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of 2413 pname:pCommandBuffers must: have been recorded with 2414 slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM::pname:renderArea 2415 identical to slink:VkRenderPassBeginInfo::pname:renderArea 2416endif::VK_QCOM_render_pass_transform[] 2417 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00100]] 2418 If fname:vkCmdExecuteCommands is not being called within a render pass 2419 instance, each element of pname:pCommandBuffers must: not have been 2420 recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 2421 * [[VUID-vkCmdExecuteCommands-commandBuffer-00101]] 2422 If the <<features-inheritedQueries,inherited queries>> feature is not 2423 enabled, pname:commandBuffer must: not have any queries 2424 <<queries-operation-active,active>> 2425 * [[VUID-vkCmdExecuteCommands-commandBuffer-00102]] 2426 If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query 2427 <<queries-operation-active,active>>, then each element of 2428 pname:pCommandBuffers must: have been recorded with 2429 sname:VkCommandBufferInheritanceInfo::pname:occlusionQueryEnable set to 2430 ename:VK_TRUE 2431 * [[VUID-vkCmdExecuteCommands-commandBuffer-00103]] 2432 If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query 2433 <<queries-operation-active,active>>, then each element of 2434 pname:pCommandBuffers must: have been recorded with 2435 sname:VkCommandBufferInheritanceInfo::pname:queryFlags having all bits 2436 set that are set for the query 2437 * [[VUID-vkCmdExecuteCommands-commandBuffer-00104]] 2438 If pname:commandBuffer has a ename:VK_QUERY_TYPE_PIPELINE_STATISTICS 2439 query <<queries-operation-active,active>>, then each element of 2440 pname:pCommandBuffers must: have been recorded with 2441 sname:VkCommandBufferInheritanceInfo::pname:pipelineStatistics having 2442 all bits set that are set in the sname:VkQueryPool the query uses 2443 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00105]] 2444 Each element of pname:pCommandBuffers must: not begin any query types 2445 that are <<queries-operation-active,active>> in pname:commandBuffer 2446ifdef::VK_VERSION_1_1[] 2447 * [[VUID-vkCmdExecuteCommands-commandBuffer-01820]] 2448 If pname:commandBuffer is a protected command buffer and 2449 <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, 2450 each element of pname:pCommandBuffers must: be a protected command 2451 buffer 2452 * [[VUID-vkCmdExecuteCommands-commandBuffer-01821]] 2453 If pname:commandBuffer is an unprotected command buffer and 2454 <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, 2455 each element of pname:pCommandBuffers must: be an unprotected command 2456 buffer 2457endif::VK_VERSION_1_1[] 2458ifdef::VK_EXT_transform_feedback[] 2459 * [[VUID-vkCmdExecuteCommands-None-02286]] 2460 This command must: not be recorded when transform feedback is active 2461endif::VK_EXT_transform_feedback[] 2462ifdef::VK_KHR_dynamic_rendering[] 2463 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06021]] 2464 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2465 render pass instances>>, there must: be no action or synchronization 2466 commands between that render pass instance and any render pass instance 2467 that resumes it 2468 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06022]] 2469 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2470 render pass instances>>, there must: be no render pass instances between 2471 that render pass instance and any render pass instance that resumes it 2472ifdef::VK_EXT_sample_locations[] 2473 * [[VUID-vkCmdExecuteCommands-variableSampleLocations-06023]] 2474 If the <<limits-variableSampleLocations, pname:variableSampleLocations>> 2475 limit is not supported, and any element of pname:pCommandBuffers 2476 contains any <<renderpass-suspension,suspended render pass instances>>, 2477 where a graphics pipeline has been bound, any pipelines bound in the 2478 render pass instance that resumes it, or any subsequent render pass 2479 instances that resume from that one and so on, must: use the same sample 2480 locations 2481endif::VK_EXT_sample_locations[] 2482 * [[VUID-vkCmdExecuteCommands-flags-06024]] 2483 If fname:vkCmdExecuteCommands is being called within a render pass 2484 instance begun with flink:vkCmdBeginRenderingKHR, its 2485 slink:VkRenderingInfoKHR::pname:flags parameter must: have included 2486 ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR 2487 * [[VUID-vkCmdExecuteCommands-pBeginInfo-06025]] 2488 If fname:vkCmdExecuteCommands is being called within a render pass 2489 instance begun with flink:vkCmdBeginRenderingKHR, the render passes 2490 specified in the pname:pBeginInfo->pInheritanceInfo->renderPass members 2491 of the flink:vkBeginCommandBuffer commands used to begin recording each 2492 element of pname:pCommandBuffers must: be dlink:VK_NULL_HANDLE 2493 * [[VUID-vkCmdExecuteCommands-flags-06026]] 2494 If fname:vkCmdExecuteCommands is being called within a render pass 2495 instance begun with flink:vkCmdBeginRenderingKHR, the pname:flags member 2496 of the slink:VkCommandBufferInheritanceRenderingInfoKHR structure 2497 included in the pname:pNext chain of 2498 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2499 recording each element of pname:pCommandBuffers must: be equal to the 2500 slink:VkRenderingInfoKHR::pname:flags parameter to 2501 flink:vkCmdBeginRenderingKHR, excluding 2502 ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR 2503 * [[VUID-vkCmdExecuteCommands-colorAttachmentCount-06027]] 2504 If fname:vkCmdExecuteCommands is being called within a render pass 2505 instance begun with flink:vkCmdBeginRenderingKHR, the 2506 pname:colorAttachmentCount member of the 2507 slink:VkCommandBufferInheritanceRenderingInfoKHR structure included in 2508 the pname:pNext chain of 2509 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2510 recording each element of pname:pCommandBuffers must: be equal to the 2511 slink:VkRenderingInfoKHR::pname:colorAttachmentCount parameter to 2512 flink:vkCmdBeginRenderingKHR 2513 * [[VUID-vkCmdExecuteCommands-imageView-06028]] 2514 If fname:vkCmdExecuteCommands is being called within a render pass 2515 instance begun with flink:vkCmdBeginRenderingKHR, if the pname:imageView 2516 member of an element of the 2517 slink:VkRenderingInfoKHR::pname:pColorAttachments parameter to 2518 flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the 2519 corresponding element of the pname:pColorAttachmentFormats member of the 2520 slink:VkCommandBufferInheritanceRenderingInfoKHR structure included in 2521 the pname:pNext chain of 2522 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2523 recording each element of pname:pCommandBuffers must: be equal to the 2524 format used to create that image view 2525 * [[VUID-vkCmdExecuteCommands-pDepthAttachment-06029]] 2526 If fname:vkCmdExecuteCommands is being called within a render pass 2527 instance begun with flink:vkCmdBeginRenderingKHR, if the 2528 slink:VkRenderingInfoKHR::pname:pDepthAttachment->imageView parameter to 2529 flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value of 2530 the pname:depthAttachmentFormat member of the 2531 slink:VkCommandBufferInheritanceRenderingInfoKHR structure included in 2532 the pname:pNext chain of 2533 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2534 recording each element of pname:pCommandBuffers must: be equal to the 2535 format used to create that image view 2536 * [[VUID-vkCmdExecuteCommands-pStencilAttachment-06030]] 2537 If fname:vkCmdExecuteCommands is being called within a render pass 2538 instance begun with flink:vkCmdBeginRenderingKHR, if the 2539 slink:VkRenderingInfoKHR::pname:pStencilAttachment->imageView parameter 2540 to flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value 2541 of the pname:stencilAttachmentFormat member of the 2542 slink:VkCommandBufferInheritanceRenderingInfoKHR structure included in 2543 the pname:pNext chain of 2544 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2545 recording each element of pname:pCommandBuffers must: be equal to the 2546 format used to create that image view 2547ifdef::VK_KHR_multiview,VK_VERSION_1_1[] 2548 * [[VUID-vkCmdExecuteCommands-viewMask-06031]] 2549 If fname:vkCmdExecuteCommands is being called within a render pass 2550 instance begun with flink:vkCmdBeginRenderingKHR, the pname:viewMask 2551 member of the slink:VkCommandBufferInheritanceRenderingInfoKHR structure 2552 included in the pname:pNext chain of 2553 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2554 recording each element of pname:pCommandBuffers must: be equal to the 2555 slink:VkRenderingInfoKHR::pname:viewMask parameter to 2556 flink:vkCmdBeginRenderingKHR 2557endif::VK_KHR_multiview,VK_VERSION_1_1[] 2558ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 2559 * [[VUID-vkCmdExecuteCommands-pNext-06032]] 2560 If fname:vkCmdExecuteCommands is being called within a render pass 2561 instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext 2562 chain of slink:VkCommandBufferInheritanceInfo includes a 2563 slink:VkAttachmentSampleCountInfoAMD or 2564 slink:VkAttachmentSampleCountInfoNV structure, if the pname:imageView 2565 member of an element of the 2566 slink:VkRenderingInfoKHR::pname:pColorAttachments parameter to 2567 flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the 2568 corresponding element of the pname:pColorAttachmentSamples member of the 2569 slink:VkAttachmentSampleCountInfoAMD or 2570 slink:VkAttachmentSampleCountInfoNV structure included in the 2571 pname:pNext chain of 2572 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2573 recording each element of pname:pCommandBuffers must: be equal to the 2574 sample count used to create that image view 2575 * [[VUID-vkCmdExecuteCommands-pNext-06033]] 2576 If fname:vkCmdExecuteCommands is being called within a render pass 2577 instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext 2578 chain of slink:VkCommandBufferInheritanceInfo includes a 2579 slink:VkAttachmentSampleCountInfoAMD or 2580 slink:VkAttachmentSampleCountInfoNV structure, if the 2581 slink:VkRenderingInfoKHR::pname:pDepthAttachment->imageView parameter to 2582 flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value of 2583 the pname:depthStencilAttachmentSamples member of the 2584 slink:VkAttachmentSampleCountInfoAMD or 2585 slink:VkAttachmentSampleCountInfoNV structure included in the 2586 pname:pNext chain of 2587 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2588 recording each element of pname:pCommandBuffers must: be equal to the 2589 sample count used to create that image view 2590 * [[VUID-vkCmdExecuteCommands-pNext-06034]] 2591 If fname:vkCmdExecuteCommands is being called within a render pass 2592 instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext 2593 chain of slink:VkCommandBufferInheritanceInfo includes a 2594 slink:VkAttachmentSampleCountInfoAMD or 2595 slink:VkAttachmentSampleCountInfoNV structure, if the 2596 slink:VkRenderingInfoKHR::pname:pStencilAttachment->imageView parameter 2597 to flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value 2598 of the pname:depthStencilAttachmentSamples member of the 2599 slink:VkAttachmentSampleCountInfoAMD or 2600 slink:VkAttachmentSampleCountInfoNV structure included in the 2601 pname:pNext chain of 2602 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2603 recording each element of pname:pCommandBuffers must: be equal to the 2604 sample count used to create that image view 2605 * [[VUID-vkCmdExecuteCommands-pNext-06035]] 2606 If fname:vkCmdExecuteCommands is being called within a render pass 2607 instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext 2608 chain of slink:VkCommandBufferInheritanceInfo does not include a 2609 slink:VkAttachmentSampleCountInfoAMD or 2610 slink:VkAttachmentSampleCountInfoNV structure, if the pname:imageView 2611 member of an element of the 2612 slink:VkRenderingInfoKHR::pname:pColorAttachments parameter to 2613 flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value of 2614 slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:rasterizationSamples 2615 must: be equal to the sample count used to create that image view 2616 * [[VUID-vkCmdExecuteCommands-pNext-06036]] 2617 If fname:vkCmdExecuteCommands is being called within a render pass 2618 instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext 2619 chain of slink:VkCommandBufferInheritanceInfo does not include a 2620 slink:VkAttachmentSampleCountInfoAMD or 2621 slink:VkAttachmentSampleCountInfoNV structure, if the 2622 slink:VkRenderingInfoKHR::pname:pDepthAttachment->imageView parameter to 2623 flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value of 2624 slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:rasterizationSamples 2625 must: be equal to the sample count used to create that image view 2626 * [[VUID-vkCmdExecuteCommands-pNext-06037]] 2627 If fname:vkCmdExecuteCommands is being called within a render pass 2628 instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext 2629 chain of slink:VkCommandBufferInheritanceInfo does not include a 2630 slink:VkAttachmentSampleCountInfoAMD or 2631 slink:VkAttachmentSampleCountInfoNV structure, if the 2632 slink:VkRenderingInfoKHR::pname:pStencilAttachment->imageView parameter 2633 to flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value 2634 of 2635 slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:rasterizationSamples 2636 must: be equal to the sample count used to create that image view 2637endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 2638endif::VK_KHR_dynamic_rendering[] 2639**** 2640 2641include::{generated}/validity/protos/vkCmdExecuteCommands.txt[] 2642-- 2643 2644ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2645[[commandbuffers-devicemask]] 2646== Command Buffer Device Mask 2647 2648Each command buffer has a piece of state storing the current device mask of 2649the command buffer. 2650This mask controls which physical devices within the logical device all 2651subsequent commands will execute on, including state-setting commands, 2652action commands, and synchronization commands. 2653 2654ifndef::VK_NV_scissor_exclusive[] 2655Scissor 2656endif::VK_NV_scissor_exclusive[] 2657ifdef::VK_NV_scissor_exclusive[] 2658Scissor, exclusive scissor, 2659endif::VK_NV_scissor_exclusive[] 2660and viewport state 2661ifdef::VK_EXT_extended_dynamic_state[] 2662(excluding the count of each) 2663endif::VK_EXT_extended_dynamic_state[] 2664can: be set to different values on each physical device (only when set as 2665dynamic state), and each physical device will render using its local copy of 2666the state. 2667Other state is shared between physical devices, such that all physical 2668devices use the most recently set values for the state. 2669However, when recording an action command that uses a piece of state, the 2670most recent command that set that state must: have included all physical 2671devices that execute the action command in its current device mask. 2672 2673The command buffer's device mask is orthogonal to the 2674pname:pCommandBufferDeviceMasks member of slink:VkDeviceGroupSubmitInfo. 2675Commands only execute on a physical device if the device index is set in 2676both device masks. 2677 2678[open,refpage='VkDeviceGroupCommandBufferBeginInfo',desc='Set the initial device mask for a command buffer',type='structs'] 2679-- 2680If the pname:pNext chain of slink:VkCommandBufferBeginInfo includes a 2681sname:VkDeviceGroupCommandBufferBeginInfo structure, then that structure 2682includes an initial device mask for the command buffer. 2683 2684The sname:VkDeviceGroupCommandBufferBeginInfo structure is defined as: 2685 2686include::{generated}/api/structs/VkDeviceGroupCommandBufferBeginInfo.txt[] 2687 2688ifdef::VK_KHR_device_group[] 2689or the equivalent 2690 2691include::{generated}/api/structs/VkDeviceGroupCommandBufferBeginInfoKHR.txt[] 2692endif::VK_KHR_device_group[] 2693 2694 * pname:sType is the type of this structure. 2695 * pname:pNext is `NULL` or a pointer to a structure extending this 2696 structure. 2697 * pname:deviceMask is the initial value of the command buffer's device 2698 mask. 2699 2700The initial device mask also acts as an upper bound on the set of devices 2701that can: ever be in the device mask in the command buffer. 2702 2703If this structure is not present, the initial value of a command buffer's 2704device mask is set to include all physical devices in the logical device 2705when the command buffer begins recording. 2706 2707.Valid Usage 2708**** 2709 * [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00106]] 2710 pname:deviceMask must: be a valid device mask value 2711 * [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00107]] 2712 pname:deviceMask must: not be zero 2713**** 2714 2715include::{generated}/validity/structs/VkDeviceGroupCommandBufferBeginInfo.txt[] 2716-- 2717 2718[open,refpage='vkCmdSetDeviceMask',desc='Modify device mask of a command buffer',type='protos'] 2719-- 2720To update the current device mask of a command buffer, call: 2721 2722ifdef::VK_VERSION_1_1[] 2723include::{generated}/api/protos/vkCmdSetDeviceMask.txt[] 2724endif::VK_VERSION_1_1[] 2725 2726ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] 2727 2728ifdef::VK_KHR_device_group[] 2729include::{generated}/api/protos/vkCmdSetDeviceMaskKHR.txt[] 2730endif::VK_KHR_device_group[] 2731 2732 * pname:commandBuffer is command buffer whose current device mask is 2733 modified. 2734 * pname:deviceMask is the new value of the current device mask. 2735 2736pname:deviceMask is used to filter out subsequent commands from executing on 2737all physical devices whose bit indices are not set in the mask, except 2738commands beginning a render pass instance, commands transitioning to the 2739next subpass in the render pass instance, and commands ending a render pass 2740instance, which always execute on the set of physical devices whose bit 2741indices are included in the pname:deviceMask member of the 2742slink:VkDeviceGroupRenderPassBeginInfo structure passed to the command 2743beginning the corresponding render pass instance. 2744 2745.Valid Usage 2746**** 2747 * [[VUID-vkCmdSetDeviceMask-deviceMask-00108]] 2748 pname:deviceMask must: be a valid device mask value 2749 * [[VUID-vkCmdSetDeviceMask-deviceMask-00109]] 2750 pname:deviceMask must: not be zero 2751 * [[VUID-vkCmdSetDeviceMask-deviceMask-00110]] 2752 pname:deviceMask must: not include any set bits that were not in the 2753 slink:VkDeviceGroupCommandBufferBeginInfo::pname:deviceMask value when 2754 the command buffer began recording 2755 * [[VUID-vkCmdSetDeviceMask-deviceMask-00111]] 2756 If fname:vkCmdSetDeviceMask is called inside a render pass instance, 2757 pname:deviceMask must: not include any set bits that were not in the 2758 slink:VkDeviceGroupRenderPassBeginInfo::pname:deviceMask value when the 2759 render pass instance began recording 2760**** 2761 2762include::{generated}/validity/protos/vkCmdSetDeviceMask.txt[] 2763-- 2764endif::VK_VERSION_1_1,VK_KHR_device_group[] 2765
