1// Copyright 2015-2023 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.adoc[] 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.adoc[] 159-- 160 161[open,refpage='vkCreateCommandPool',desc='Create a new command pool object',type='protos'] 162-- 163:refpage: vkCreateCommandPool 164:objectnameplural: command pools 165:objectnamecamelcase: commandPool 166:objectcount: 1 167 168To create a command pool, call: 169 170include::{generated}/api/protos/vkCreateCommandPool.adoc[] 171 172 * pname:device is the logical device that creates the command pool. 173 * pname:pCreateInfo is a pointer to a slink:VkCommandPoolCreateInfo 174 structure specifying the state of the command pool object. 175 * pname:pAllocator controls host memory allocation as described in the 176 <<memory-allocation, Memory Allocation>> chapter. 177 * pname:pCommandPool is a pointer to a slink:VkCommandPool handle in which 178 the created pool is returned. 179 180include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 181 182.Valid Usage 183**** 184 * [[VUID-vkCreateCommandPool-queueFamilyIndex-01937]] 185 pname:pCreateInfo->queueFamilyIndex must: be the index of a queue family 186 available in the logical device pname:device 187include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] 188**** 189 190include::{generated}/validity/protos/vkCreateCommandPool.adoc[] 191-- 192 193[open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] 194-- 195The sname:VkCommandPoolCreateInfo structure is defined as: 196 197include::{generated}/api/structs/VkCommandPoolCreateInfo.adoc[] 198 199 * pname:sType is a elink:VkStructureType value identifying this structure. 200 * pname:pNext is `NULL` or a pointer to a structure extending this 201 structure. 202 * pname:flags is a bitmask of elink:VkCommandPoolCreateFlagBits indicating 203 usage behavior for the pool and command buffers allocated from it. 204 * pname:queueFamilyIndex designates a queue family as described in section 205 <<devsandqueues-queueprops,Queue Family Properties>>. 206 All command buffers allocated from this command pool must: be submitted 207 on queues from the same queue family. 208 209.Valid Usage 210**** 211ifdef::VK_VERSION_1_1[] 212 * [[VUID-VkCommandPoolCreateInfo-flags-02860]] 213 If the <<features-protectedMemory, pname:protectedMemory>> feature is 214 not enabled, the ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT bit of 215 pname:flags must: not be set 216endif::VK_VERSION_1_1[] 217ifdef::VKSC_VERSION_1_0[] 218 * [[VUID-VkCommandPoolCreateInfo-pNext-05002]] 219 The pname:pNext chain must: include a 220 slink:VkCommandPoolMemoryReservationCreateInfo structure 221endif::VKSC_VERSION_1_0[] 222**** 223ifdef::VKSC_VERSION_1_0[] 224ifdef::hidden[] 225// tag::scdeviation[] 226 * The slink:VkCommandPoolCreateInfo::pname:pNext chain must: include a 227 valid slink:VkCommandPoolMemoryReservationCreateInfo structure 228 <<SCID-4>>. 229// end::scdeviation[] 230endif::hidden[] 231endif::VKSC_VERSION_1_0[] 232 233include::{generated}/validity/structs/VkCommandPoolCreateInfo.adoc[] 234-- 235 236[open,refpage='VkCommandPoolCreateFlagBits',desc='Bitmask specifying usage behavior for a command pool',type='enums'] 237-- 238Bits which can: be set in slink:VkCommandPoolCreateInfo::pname:flags, 239specifying usage behavior for a command pool, are: 240 241include::{generated}/api/enums/VkCommandPoolCreateFlagBits.adoc[] 242 243 * ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT specifies that command 244 buffers allocated from the pool will be short-lived, meaning that they 245 will be reset or freed in a relatively short timeframe. 246 This flag may: be used by the implementation to control memory 247 allocation behavior within the pool. 248 * ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT allows any command 249 buffer allocated from a pool to be individually reset to the 250 <<commandbuffers-lifecycle, initial state>>; either by calling 251 flink:vkResetCommandBuffer, or via the implicit reset when calling 252 flink:vkBeginCommandBuffer. 253 If this flag is not set on a pool, then fname:vkResetCommandBuffer must: 254 not be called for any command buffer allocated from that pool. 255ifdef::VK_VERSION_1_1[] 256 * ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT specifies that command 257 buffers allocated from the pool are protected command buffers. 258endif::VK_VERSION_1_1[] 259-- 260 261[open,refpage='VkCommandPoolCreateFlags',desc='Bitmask of VkCommandPoolCreateFlagBits',type='flags'] 262-- 263include::{generated}/api/flags/VkCommandPoolCreateFlags.adoc[] 264 265tname:VkCommandPoolCreateFlags is a bitmask type for setting a mask of zero 266or more elink:VkCommandPoolCreateFlagBits. 267-- 268 269ifdef::VKSC_VERSION_1_0[] 270 271[open,refpage='VkCommandPoolMemoryReservationCreateInfo',desc='Structure specifying command pool memory reservation info',type='structs'] 272-- 273 274The pname:pNext chain of slink:VkCommandPoolCreateInfo must: include a 275sname:VkCommandPoolMemoryReservationCreateInfo structure. 276This structure controls how much memory is allocated at command pool 277creation time to be used for all command buffers recorded from this pool. 278 279The sname:VkCommandPoolMemoryReservationCreateInfo structure is defined as: 280 281include::{generated}/api/structs/VkCommandPoolMemoryReservationCreateInfo.adoc[] 282 283 * pname:sType is a elink:VkStructureType value identifying this structure. 284 * pname:pNext is `NULL` or a pointer to a structure extending this 285 structure. 286 * pname:commandPoolReservedSize is the number of bytes to be allocated for 287 all command buffer data recorded into this pool. 288 * pname:commandPoolMaxCommandBuffers is the maximum number of command 289 buffers that can be allocated from this command pool. 290 291The number of command buffers reserved using 292pname:commandPoolMaxCommandBuffers is permanently counted against the total 293number of command buffers requested via 294slink:VkDeviceObjectReservationCreateInfo::pname:commandBufferRequestCount 295even if the command buffers are freed at a later time. 296 297Each command recorded into a command buffer has an implementation-dependent 298size that counts against pname:commandPoolReservedSize. 299There is no minimum command pool size, but some sizes may be too small for 300any commands to be recorded in them on a given implementation. 301Applications are expected to estimate their worst-case command buffer memory 302usage at development time using flink:vkGetCommandPoolMemoryConsumption and 303reserve large enough command buffers. 304This command can: also be used at runtime to verify expected memory usage. 305 306While the memory consumption of a particular command is 307implementation-dependent, it is a deterministic function of the parameters 308to the command and of the objects used by the command (including the command 309buffer itself). 310Two command buffers will consume the same amount of pool memory if: 311 312 * all numerical parameters to each command match exactly, 313 * all objects used by each command are 314 <<glossary-identically-defined,identically defined>>, and 315 * the order of the commands is the same. 316 317[NOTE] 318.Note 319==== 320The rules for identically defined objects apply recursively, implying for 321example that if the command buffers are created in different devices that 322those devices must have been created with the same features enabled. 323==== 324 325Each command buffer may: require some base alignment in the pool, so the 326total pool memory will match if each command buffer's consumption matches 327and the command buffers are recorded one at a time and in the same order. 328 329If all these criteria are satisfied, then a command pool memory consumption 330returned by flink:vkGetCommandPoolMemoryConsumption will be sufficient to 331record the same command buffers again. 332 333ifdef::hidden[] 334// tag::scaddition[] 335 * slink:VkCommandPoolMemoryReservationCreateInfo <<SCID-4>> 336// end::scaddition[] 337endif::hidden[] 338 339.Valid Usage 340**** 341 * [[VUID-VkCommandPoolMemoryReservationCreateInfo-commandPoolReservedSize-05003]] 342 pname:commandPoolReservedSize must: be greater than `0` 343 * [[VUID-VkCommandPoolMemoryReservationCreateInfo-commandPoolMaxCommandBuffers-05004]] 344 pname:commandPoolMaxCommandBuffers must: be greater than `0` 345 * [[VUID-VkCommandPoolMemoryReservationCreateInfo-commandPoolMaxCommandBuffers-05090]] 346 pname:commandPoolMaxCommandBuffers must: be less than or equal to 347 slink:VkPhysicalDeviceVulkanSC10Properties::pname:maxCommandPoolCommandBuffers 348 * [[VUID-VkCommandPoolMemoryReservationCreateInfo-commandPoolMaxCommandBuffers-05074]] 349 The number of command buffers reserved by all command pools plus 350 pname:commandPoolMaxCommandBuffers must: be less than or equal to the 351 total number of command buffers requested via 352 slink:VkDeviceObjectReservationCreateInfo::pname:commandBufferRequestCount 353**** 354 355include::{generated}/validity/structs/VkCommandPoolMemoryReservationCreateInfo.adoc[] 356-- 357 358[open,refpage='vkGetCommandPoolMemoryConsumption',desc='Get memory usage information for a command pool object',type='protos'] 359-- 360 361ifdef::hidden[] 362// tag::scaddition[] 363 * flink:vkGetCommandPoolMemoryConsumption <<SCID-1>> 364// end::scaddition[] 365endif::hidden[] 366 367To get memory usage information for a command pool object, call: 368 369include::{generated}/api/protos/vkGetCommandPoolMemoryConsumption.adoc[] 370 371 * pname:device is the logical device that owns the command pool. 372 * pname:commandPool is the command pool from which to query the memory 373 usage. 374 * pname:commandBuffer is an optional command buffer from which to query 375 the memory usage. 376 * pname:pConsumption is a pointer to a 377 sname:VkCommandPoolMemoryConsumption structure where the memory usage is 378 written. 379 380include::{generated}/validity/protos/vkGetCommandPoolMemoryConsumption.adoc[] 381-- 382 383[open,refpage='VkCommandPoolMemoryConsumption',desc='Structure where memory usage information is written',type='structs'] 384-- 385 386The sname:VkCommandPoolMemoryConsumption structure is defined as: 387 388include::{generated}/api/structs/VkCommandPoolMemoryConsumption.adoc[] 389 390 * pname:sType is a elink:VkStructureType value identifying this structure. 391 * pname:pNext is `NULL` or a pointer to a structure extending this 392 structure. 393 * pname:commandPoolAllocated is the number of bytes currently allocated 394 from this pool for command buffer data. 395 * pname:commandPoolReservedSize is the total number of bytes available for 396 all command buffer data recorded into this pool. 397 This is equal to the value requested in 398 slink:VkCommandPoolMemoryReservationCreateInfo::pname:commandPoolReservedSize. 399 * pname:commandBufferAllocated is the number of bytes currently allocated 400 from this pool for the specified command buffer's data. 401 This number will be less than or equal to 402 slink:VkPhysicalDeviceVulkanSC10Properties::pname:maxCommandBufferSize. 403 If no command buffer is specified, then this is set to zero. 404 405ifdef::hidden[] 406// tag::scaddition[] 407 * slink:VkCommandPoolMemoryConsumption <<SCID-1>> 408// end::scaddition[] 409endif::hidden[] 410 411include::{generated}/validity/structs/VkCommandPoolMemoryConsumption.adoc[] 412-- 413 414endif::VKSC_VERSION_1_0[] 415 416ifdef::VKSC_VERSION_1_0[] 417ifdef::hidden[] 418// tag::scremoved[] 419 * fname:vkTrimCommandPool, fname:vkTrimCommandPoolKHR <<SCID-8>> 420 * tname:VkCommandPoolTrimFlags, tname:VkCommandPoolTrimFlagsKHR <<SCID-8>> 421// end::scremoved[] 422endif::hidden[] 423endif::VKSC_VERSION_1_0[] 424ifndef::VKSC_VERSION_1_0[] 425ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 426[open,refpage='vkTrimCommandPool',desc='Trim a command pool',type='protos'] 427-- 428To trim a command pool, call: 429 430ifdef::VK_VERSION_1_1[] 431include::{generated}/api/protos/vkTrimCommandPool.adoc[] 432endif::VK_VERSION_1_1[] 433 434ifdef::VK_VERSION_1_1+VK_KHR_maintenance1[or the equivalent command] 435 436ifdef::VK_KHR_maintenance1[] 437include::{generated}/api/protos/vkTrimCommandPoolKHR.adoc[] 438endif::VK_KHR_maintenance1[] 439 440 * pname:device is the logical device that owns the command pool. 441 * pname:commandPool is the command pool to trim. 442 * pname:flags is reserved for future use. 443 444Trimming a command pool recycles unused memory from the command pool back to 445the system. 446Command buffers allocated from the pool are not affected by the command. 447 448[NOTE] 449.Note 450==== 451This command provides applications with some control over the internal 452memory allocations used by command pools. 453 454Unused memory normally arises from command buffers that have been recorded 455and later reset, such that they are no longer using the memory. 456On reset, a command buffer can return memory to its command pool, but the 457only way to release memory from a command pool to the system requires 458calling flink:vkResetCommandPool, which cannot be executed while any command 459buffers from that pool are still in use. 460Subsequent recording operations into command buffers will reuse this memory 461but since total memory requirements fluctuate over time, unused memory can 462accumulate. 463 464In this situation, trimming a command pool may: be useful to return unused 465memory back to the system, returning the total outstanding memory allocated 466by the pool back to a more "`average`" value. 467 468Implementations utilize many internal allocation strategies that make it 469impossible to guarantee that all unused memory is released back to the 470system. 471For instance, an implementation of a command pool may: involve allocating 472memory in bulk from the system and sub-allocating from that memory. 473In such an implementation any live command buffer that holds a reference to 474a bulk allocation would prevent that allocation from being freed, even if 475only a small proportion of the bulk allocation is in use. 476 477In most cases trimming will result in a reduction in allocated but unused 478memory, but it does not guarantee the "`ideal`" behavior. 479 480Trimming may: be an expensive operation, and should: not be called 481frequently. 482Trimming should: be treated as a way to relieve memory pressure after 483application-known points when there exists enough unused memory that the 484cost of trimming is "`worth`" it. 485==== 486 487include::{generated}/validity/protos/vkTrimCommandPool.adoc[] 488-- 489 490[open,refpage='VkCommandPoolTrimFlags',desc='Reserved for future use',type='flags'] 491-- 492include::{generated}/api/flags/VkCommandPoolTrimFlags.adoc[] 493 494ifdef::VK_KHR_maintenance1[] 495or the equivalent 496 497include::{generated}/api/flags/VkCommandPoolTrimFlagsKHR.adoc[] 498endif::VK_KHR_maintenance1[] 499 500tname:VkCommandPoolTrimFlags is a bitmask type for setting a mask, but is 501currently reserved for future use. 502-- 503endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 504endif::VKSC_VERSION_1_0[] 505 506[open,refpage='vkResetCommandPool',desc='Reset a command pool',type='protos'] 507-- 508To reset a command pool, call: 509 510include::{generated}/api/protos/vkResetCommandPool.adoc[] 511 512 * pname:device is the logical device that owns the command pool. 513 * pname:commandPool is the command pool to reset. 514 * pname:flags is a bitmask of elink:VkCommandPoolResetFlagBits controlling 515 the reset operation. 516 517Resetting a command pool recycles all of the resources from all of the 518command buffers allocated from the command pool back to the command pool. 519All command buffers that have been allocated from the command pool are put 520in the <<commandbuffers-lifecycle, initial state>>. 521 522Any primary command buffer allocated from another slink:VkCommandPool that 523is in the <<commandbuffers-lifecycle, recording or executable state>> and 524has a secondary command buffer allocated from pname:commandPool recorded 525into it, becomes <<commandbuffers-lifecycle, invalid>>. 526 527.Valid Usage 528**** 529 * [[VUID-vkResetCommandPool-commandPool-00040]] 530 All sname:VkCommandBuffer objects allocated from pname:commandPool must: 531 not be in the <<commandbuffers-lifecycle, pending state>> 532**** 533 534include::{generated}/validity/protos/vkResetCommandPool.adoc[] 535-- 536 537[open,refpage='VkCommandPoolResetFlagBits',desc='Bitmask controlling behavior of a command pool reset',type='enums'] 538-- 539Bits which can: be set in flink:vkResetCommandPool::pname:flags, controlling 540the reset operation, are: 541 542include::{generated}/api/enums/VkCommandPoolResetFlagBits.adoc[] 543 544 * ename:VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT 545ifndef::VKSC_VERSION_1_0[] 546 specifies that resetting a command pool recycles all of the resources 547 from the command pool back to the system. 548endif::VKSC_VERSION_1_0[] 549ifdef::VKSC_VERSION_1_0[] 550 is not supported in Vulkan SC <<SCID-4>>. 551ifdef::hidden[] 552// tag::scremoved[] 553 * elink:VkCommandPoolResetFlagBits 554 ** ename:VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT <<SCID-4>> 555// end::scremoved[] 556endif::hidden[] 557endif::VKSC_VERSION_1_0[] 558-- 559 560[open,refpage='VkCommandPoolResetFlags',desc='Bitmask of VkCommandPoolResetFlagBits',type='flags'] 561-- 562include::{generated}/api/flags/VkCommandPoolResetFlags.adoc[] 563 564tname:VkCommandPoolResetFlags is a bitmask type for setting a mask of zero 565or more elink:VkCommandPoolResetFlagBits. 566-- 567 568ifdef::VKSC_VERSION_1_0[] 569ifdef::hidden[] 570// tag::scremoved[] 571 * fname:vkDestroyCommandPool <<SCID-4>> 572// end::scremoved[] 573endif::hidden[] 574 575Command pools cannot: be destroyed or trimmed <<SCID-4>>. 576If 577slink:VkPhysicalDeviceVulkanSC10Properties::<<limits-deviceDestroyFreesMemory,pname:deviceDestroyFreesMemory>> 578is ename:VK_TRUE, then the memory used by command pools is returned to the 579system when the device is destroyed. 580 581endif::VKSC_VERSION_1_0[] 582ifndef::VKSC_VERSION_1_0[] 583 584[open,refpage='vkDestroyCommandPool',desc='Destroy a command pool object',type='protos'] 585-- 586To destroy a command pool, call: 587 588include::{generated}/api/protos/vkDestroyCommandPool.adoc[] 589 590 * pname:device is the logical device that destroys the command pool. 591 * pname:commandPool is the handle of the command pool to destroy. 592 * pname:pAllocator controls host memory allocation as described in the 593 <<memory-allocation, Memory Allocation>> chapter. 594 595When a pool is destroyed, all command buffers allocated from the pool are 596<<vkFreeCommandBuffers, freed>>. 597 598Any primary command buffer allocated from another slink:VkCommandPool that 599is in the <<commandbuffers-lifecycle, recording or executable state>> and 600has a secondary command buffer allocated from pname:commandPool recorded 601into it, becomes <<commandbuffers-lifecycle, invalid>>. 602 603.Valid Usage 604**** 605 * [[VUID-vkDestroyCommandPool-commandPool-00041]] 606 All sname:VkCommandBuffer objects allocated from pname:commandPool must: 607 not be in the <<commandbuffers-lifecycle, pending state>> 608 * [[VUID-vkDestroyCommandPool-commandPool-00042]] 609 If sname:VkAllocationCallbacks were provided when pname:commandPool was 610 created, a compatible set of callbacks must: be provided here 611 * [[VUID-vkDestroyCommandPool-commandPool-00043]] 612 If no sname:VkAllocationCallbacks were provided when pname:commandPool 613 was created, pname:pAllocator must: be `NULL` 614**** 615 616include::{generated}/validity/protos/vkDestroyCommandPool.adoc[] 617-- 618 619endif::VKSC_VERSION_1_0[] 620 621[[commandbuffer-allocation]] 622== Command Buffer Allocation and Management 623 624[open,refpage='vkAllocateCommandBuffers',desc='Allocate command buffers from an existing command pool',type='protos'] 625-- 626:refpage: vkAllocateCommandBuffers 627 628To allocate command buffers, call: 629 630include::{generated}/api/protos/vkAllocateCommandBuffers.adoc[] 631 632 * pname:device is the logical device that owns the command pool. 633 * pname:pAllocateInfo is a pointer to a slink:VkCommandBufferAllocateInfo 634 structure describing parameters of the allocation. 635 * pname:pCommandBuffers is a pointer to an array of slink:VkCommandBuffer 636 handles in which the resulting command buffer objects are returned. 637 The array must: be at least the length specified by the 638 pname:commandBufferCount member of pname:pAllocateInfo. 639 Each allocated command buffer begins in the initial state. 640 641ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 642fname:vkAllocateCommandBuffers can: be used to allocate multiple command 643buffers. 644If the allocation of any of those command buffers fails, the implementation 645must: free all successfully allocated command buffer objects from this 646command, set all entries of the pname:pCommandBuffers array to `NULL` and 647return the error. 648 649[NOTE] 650.Note 651==== 652Filling pname:pCommandBuffers with `NULL` values on failure is an exception 653to the default error behavior that output parameters will have undefined: 654contents. 655==== 656 657endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 658 659When command buffers are first allocated, they are in the 660<<commandbuffers-lifecycle, initial state>>. 661 662include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 663 664include::{generated}/validity/protos/vkAllocateCommandBuffers.adoc[] 665-- 666 667[open,refpage='VkCommandBufferAllocateInfo',desc='Structure specifying the allocation parameters for command buffer object',type='structs'] 668-- 669The sname:VkCommandBufferAllocateInfo structure is defined as: 670 671include::{generated}/api/structs/VkCommandBufferAllocateInfo.adoc[] 672 673 * pname:sType is a elink:VkStructureType value identifying this structure. 674 * pname:pNext is `NULL` or a pointer to a structure extending this 675 structure. 676 * pname:commandPool is the command pool from which the command buffers are 677 allocated. 678 * pname:level is a elink:VkCommandBufferLevel value specifying the command 679 buffer level. 680 * pname:commandBufferCount is the number of command buffers to allocate 681 from the pool. 682 683ifdef::VKSC_VERSION_1_0[] 684The number of command buffers allocated using pname:commandBufferCount 685counts against the maximum number of command buffers reserved via 686slink:VkCommandPoolMemoryReservationCreateInfo::pname:commandPoolMaxCommandBuffers 687specified when pname:commandPool was created. 688Once command buffers are freed with flink:vkFreeCommandBuffers, they can be 689allocated from pname:commandPool again. 690 691.Valid Usage 692**** 693 * [[VUID-VkCommandBufferAllocateInfo-commandPool-05006]] 694 The number of command buffers currently allocated from pname:commandPool 695 plus pname:commandBufferCount must: be less than or equal to the value 696 of 697 slink:VkCommandPoolMemoryReservationCreateInfo::pname:commandPoolMaxCommandBuffers 698 specified when pname:commandPool was created 699**** 700endif::VKSC_VERSION_1_0[] 701 702include::{generated}/validity/structs/VkCommandBufferAllocateInfo.adoc[] 703-- 704 705[open,refpage='VkCommandBufferLevel',desc='Enumerant specifying a command buffer level',type='enums'] 706-- 707Possible values of slink:VkCommandBufferAllocateInfo::pname:level, 708specifying the command buffer level, are: 709 710include::{generated}/api/enums/VkCommandBufferLevel.adoc[] 711 712 * ename:VK_COMMAND_BUFFER_LEVEL_PRIMARY specifies a primary command 713 buffer. 714 * ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY specifies a secondary command 715 buffer. 716-- 717 718[open,refpage='vkResetCommandBuffer',desc='Reset a command buffer to the initial state',type='protos'] 719-- 720To reset a command buffer, call: 721 722include::{generated}/api/protos/vkResetCommandBuffer.adoc[] 723 724 * pname:commandBuffer is the command buffer to reset. 725 The command buffer can: be in any state other than 726 <<commandbuffers-lifecycle, pending>>, and is moved into the 727 <<commandbuffers-lifecycle, initial state>>. 728 * pname:flags is a bitmask of elink:VkCommandBufferResetFlagBits 729 controlling the reset operation. 730 731Any primary command buffer that is in the <<commandbuffers-lifecycle, 732recording or executable state>> and has pname:commandBuffer recorded into 733it, becomes <<commandbuffers-lifecycle, invalid>>. 734 735.Valid Usage 736**** 737 * [[VUID-vkResetCommandBuffer-commandBuffer-00045]] 738 pname:commandBuffer must: not be in the <<commandbuffers-lifecycle, 739 pending state>> 740 * [[VUID-vkResetCommandBuffer-commandBuffer-00046]] 741 pname:commandBuffer must: have been allocated from a pool that was 742 created with the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT 743ifdef::VKSC_VERSION_1_0[] 744 * [[VUID-vkResetCommandBuffer-commandPoolResetCommandBuffer-05135]] 745 <<limits-commandPoolResetCommandBuffer,pname:commandPoolResetCommandBuffer>> 746 must: be supported 747endif::VKSC_VERSION_1_0[] 748**** 749ifdef::VKSC_VERSION_1_0[] 750ifdef::hidden[] 751// tag::scdeviation[] 752 * If 753 <<limits-commandPoolResetCommandBuffer,pname:commandPoolResetCommandBuffer>> 754 is not supported <<SCID-8>>, flink:vkResetCommandBuffer must: not be 755 called. 756// end::scdeviation[] 757endif::hidden[] 758endif::VKSC_VERSION_1_0[] 759 760include::{generated}/validity/protos/vkResetCommandBuffer.adoc[] 761-- 762 763[open,refpage='VkCommandBufferResetFlagBits',desc='Bitmask controlling behavior of a command buffer reset',type='enums'] 764-- 765Bits which can: be set in flink:vkResetCommandBuffer::pname:flags, 766controlling the reset operation, are: 767 768include::{generated}/api/enums/VkCommandBufferResetFlagBits.adoc[] 769 770 * ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT specifies that most 771 or all memory resources currently owned by the command buffer should: be 772 returned to the parent command pool. 773 If this flag is not set, then the command buffer may: hold onto memory 774 resources and reuse them when recording commands. 775 pname:commandBuffer is moved to the <<commandbuffers-lifecycle, initial 776 state>>. 777-- 778 779[open,refpage='VkCommandBufferResetFlags',desc='Bitmask of VkCommandBufferResetFlagBits',type='flags'] 780-- 781include::{generated}/api/flags/VkCommandBufferResetFlags.adoc[] 782 783tname:VkCommandBufferResetFlags is a bitmask type for setting a mask of zero 784or more elink:VkCommandBufferResetFlagBits. 785-- 786 787[open,refpage='vkFreeCommandBuffers',desc='Free command buffers',type='protos'] 788-- 789To free command buffers, call: 790 791include::{generated}/api/protos/vkFreeCommandBuffers.adoc[] 792 793 * pname:device is the logical device that owns the command pool. 794 * pname:commandPool is the command pool from which the command buffers 795 were allocated. 796 * pname:commandBufferCount is the length of the pname:pCommandBuffers 797 array. 798 * pname:pCommandBuffers is a pointer to an array of handles of command 799 buffers to free. 800 801Any primary command buffer that is in the <<commandbuffers-lifecycle, 802recording or executable state>> and has any element of pname:pCommandBuffers 803recorded into it, becomes <<commandbuffers-lifecycle, invalid>>. 804 805ifdef::VKSC_VERSION_1_0[] 806Freeing a command buffer does not return the memory used by command 807recording back to its parent command pool. 808This memory will be reclaimed the next time flink:vkResetCommandPool is 809called. 810ifdef::hidden[] 811// tag::scdeviation[] 812 * flink:vkFreeCommandBuffers does not return the memory used by command 813 recording back to its parent command pool <<SCID-4>>. 814 This memory is reclaimed when flink:vkResetCommandPool is next called. 815// end::scdeviation[] 816endif::hidden[] 817endif::VKSC_VERSION_1_0[] 818 819.Valid Usage 820**** 821 * [[VUID-vkFreeCommandBuffers-pCommandBuffers-00047]] 822 All elements of pname:pCommandBuffers must: not be in the 823 <<commandbuffers-lifecycle, pending state>> 824 * [[VUID-vkFreeCommandBuffers-pCommandBuffers-00048]] 825 pname:pCommandBuffers must: be a valid pointer to an array of 826 pname:commandBufferCount sname:VkCommandBuffer handles, each element of 827 which must: either be a valid handle or `NULL` 828**** 829 830include::{generated}/validity/protos/vkFreeCommandBuffers.adoc[] 831-- 832 833 834[[commandbuffers-recording]] 835== Command Buffer Recording 836 837[open,refpage='vkBeginCommandBuffer',desc='Start recording a command buffer',type='protos'] 838-- 839 840:refpage: vkBeginCommandBuffer 841 842To begin recording a command buffer, call: 843 844include::{generated}/api/protos/vkBeginCommandBuffer.adoc[] 845 846 * pname:commandBuffer is the handle of the command buffer which is to be 847 put in the recording state. 848 * pname:pBeginInfo is a pointer to a slink:VkCommandBufferBeginInfo 849 structure defining additional information about how the command buffer 850 begins recording. 851 852include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 853 854.Valid Usage 855**** 856 * [[VUID-vkBeginCommandBuffer-commandBuffer-00049]] 857 pname:commandBuffer must: not be in the <<commandbuffers-lifecycle, 858 recording or pending state>> 859 * [[VUID-vkBeginCommandBuffer-commandBuffer-00050]] 860 If pname:commandBuffer was allocated from a slink:VkCommandPool which 861 did not have the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT 862 flag set, pname:commandBuffer must: be in the 863 <<commandbuffers-lifecycle, initial state>> 864ifdef::VKSC_VERSION_1_0[] 865 * [[VUID-vkBeginCommandBuffer-commandPoolResetCommandBuffer-05136]] 866 If 867 <<limits-commandPoolResetCommandBuffer,pname:commandPoolResetCommandBuffer>> 868 is not supported, pname:commandBuffer must: be in the 869 <<commandbuffers-lifecycle, initial state>> 870endif::VKSC_VERSION_1_0[] 871 * [[VUID-vkBeginCommandBuffer-commandBuffer-00051]] 872 If pname:commandBuffer is a secondary command buffer, the 873 pname:pInheritanceInfo member of pname:pBeginInfo must: be a valid 874 sname:VkCommandBufferInheritanceInfo structure 875 * [[VUID-vkBeginCommandBuffer-commandBuffer-00052]] 876 If pname:commandBuffer is a secondary command buffer and either the 877 pname:occlusionQueryEnable member of the pname:pInheritanceInfo member 878 of pname:pBeginInfo is ename:VK_FALSE, or the 879 <<features-occlusionQueryPrecise, pname:occlusionQueryPrecise>> feature 880 is not enabled, then pname:pBeginInfo->pInheritanceInfo->queryFlags 881 must: not contain ename:VK_QUERY_CONTROL_PRECISE_BIT 882 * [[VUID-vkBeginCommandBuffer-commandBuffer-02840]] 883 If pname:commandBuffer is a primary command buffer, then 884 pname:pBeginInfo->flags must: not set both the 885 ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT and the 886 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flags 887ifdef::VKSC_VERSION_1_0[] 888 * [[VUID-vkBeginCommandBuffer-commandPoolMultipleCommandBuffersRecording-05007]] 889 If 890 <<limits-commandPoolMultipleCommandBuffersRecording,pname:commandPoolMultipleCommandBuffersRecording>> 891 is ename:VK_FALSE, then the command pool that pname:commandBuffer was 892 created from must: have no other command buffers in the 893 <<commandbuffers-lifecycle, recording state>> 894 * [[VUID-vkBeginCommandBuffer-commandBufferSimultaneousUse-05008]] 895 If 896 <<limits-commandBufferSimultaneousUse,pname:commandBufferSimultaneousUse>> 897 is ename:VK_FALSE, then pname:pBeginInfo->flags must: not include 898 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT 899endif::VKSC_VERSION_1_0[] 900**** 901ifdef::VKSC_VERSION_1_0[] 902ifdef::hidden[] 903// tag::scdeviation[] 904 * If 905 slink:VkPhysicalDeviceVulkanSC10Properties::pname:commandPoolMultipleCommandBuffersRecording 906 is ename:VK_FALSE, then only one command buffer from a command pool can 907 be in the <<commandbuffers-lifecycle, recording state>> at a time 908 <<SCID-8>>. 909 * If 910 slink:VkPhysicalDeviceVulkanSC10Properties::pname:commandBufferSimultaneousUse 911 is ename:VK_FALSE, then slink:VkCommandBufferBeginInfo::pname:flags 912 must: not include ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT 913 <<SCID-8>>. 914 * If 915 <<limits-commandPoolResetCommandBuffer,pname:commandPoolResetCommandBuffer>> 916 is not supported, pname:commandBuffer must: be in the 917 <<commandbuffers-lifecycle, initial state>> when 918 flink:vkBeginCommandBuffer is called <<SCID-8>>. 919// end::scdeviation[] 920endif::hidden[] 921endif::VKSC_VERSION_1_0[] 922 923include::{generated}/validity/protos/vkBeginCommandBuffer.adoc[] 924-- 925 926[open,refpage='VkCommandBufferBeginInfo',desc='Structure specifying a command buffer begin operation',type='structs'] 927-- 928The sname:VkCommandBufferBeginInfo structure is defined as: 929 930include::{generated}/api/structs/VkCommandBufferBeginInfo.adoc[] 931 932 * pname:sType is a elink:VkStructureType value identifying this structure. 933 * pname:pNext is `NULL` or a pointer to a structure extending this 934 structure. 935 * pname:flags is a bitmask of elink:VkCommandBufferUsageFlagBits 936 specifying usage behavior for the command buffer. 937 * pname:pInheritanceInfo is a pointer to a 938 sname:VkCommandBufferInheritanceInfo structure, used if 939 pname:commandBuffer is a secondary command buffer. 940 If this is a primary command buffer, then this value is ignored. 941 942.Valid Usage 943**** 944 * [[VUID-VkCommandBufferBeginInfo-flags-09123]] 945 If pname:flags contains 946 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the 947 slink:VkCommandPool that pname:commandBuffer was allocated from must: 948 support graphics operations 949ifndef::VKSC_VERSION_1_0[] 950 * [[VUID-VkCommandBufferBeginInfo-flags-00055]] 951 If pname:flags contains 952 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the 953 pname:framebuffer member of pname:pInheritanceInfo must: be either 954 dlink:VK_NULL_HANDLE, or a valid sname:VkFramebuffer that is compatible 955 with the pname:renderPass member of pname:pInheritanceInfo 956endif::VKSC_VERSION_1_0[] 957ifdef::VKSC_VERSION_1_0[] 958 * [[VUID-VkCommandBufferBeginInfo-flags-05009]] 959 If pname:flags contains 960 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and 961 pname:secondaryCommandBufferNullOrImagelessFramebuffer is ename:VK_TRUE, 962 the pname:framebuffer member of pname:pInheritanceInfo must: be either 963 dlink:VK_NULL_HANDLE, or a valid sname:VkFramebuffer that is compatible 964 with the pname:renderPass member of pname:pInheritanceInfo 965 * [[VUID-VkCommandBufferBeginInfo-flags-05010]] 966 If pname:flags contains 967 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and 968 pname:secondaryCommandBufferNullOrImagelessFramebuffer is 969 ename:VK_FALSE, the pname:framebuffer member of pname:pInheritanceInfo 970 must: be a valid sname:VkFramebuffer that is compatible with the 971 pname:renderPass member of pname:pInheritanceInfo and must: not have 972 been created with a slink:VkFramebufferCreateInfo::pname:flags value 973 that includes ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT 974endif::VKSC_VERSION_1_0[] 975ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 976 * [[VUID-VkCommandBufferBeginInfo-flags-09240]] 977 If pname:flags contains 978 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the 979 <<features-dynamicRendering,pname:dynamicRendering>> feature is not 980 enabled, the pname:renderPass member of pname:pInheritanceInfo must: not 981 be dlink:VK_NULL_HANDLE 982 * [[VUID-VkCommandBufferBeginInfo-flags-06002]] 983 If pname:flags contains 984 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the 985 pname:renderPass member of pname:pInheritanceInfo is 986 dlink:VK_NULL_HANDLE, the pname:pNext chain of pname:pInheritanceInfo 987 must: include a slink:VkCommandBufferInheritanceRenderingInfo structure 988ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 989 * [[VUID-VkCommandBufferBeginInfo-flags-06003]] 990 If pname:flags contains 991 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the 992 pname:renderPass member of pname:pInheritanceInfo is 993 dlink:VK_NULL_HANDLE, and the pname:pNext chain of 994 pname:pInheritanceInfo includes a slink:VkAttachmentSampleCountInfoAMD 995 or slink:VkAttachmentSampleCountInfoNV structure, the 996 pname:colorAttachmentCount member of that structure must: be equal to 997 the value of 998 slink:VkCommandBufferInheritanceRenderingInfo::pname:colorAttachmentCount 999endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 1000endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 1001 * [[VUID-VkCommandBufferBeginInfo-flags-06000]] 1002 If pname:flags contains 1003 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 1004ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 1005 and the pname:renderPass member of pname:pInheritanceInfo is not 1006 dlink:VK_NULL_HANDLE, 1007endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 1008 the pname:renderPass member of pname:pInheritanceInfo must: be a valid 1009 sname:VkRenderPass 1010 * [[VUID-VkCommandBufferBeginInfo-flags-06001]] 1011 If pname:flags contains 1012 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 1013ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 1014 and the pname:renderPass member of pname:pInheritanceInfo is not 1015 dlink:VK_NULL_HANDLE, 1016endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 1017 the pname:subpass member of pname:pInheritanceInfo must: be a valid 1018 subpass index within the pname:renderPass member of 1019 pname:pInheritanceInfo 1020**** 1021ifdef::VKSC_VERSION_1_0[] 1022ifdef::hidden[] 1023// tag::scdeviation[] 1024 * If 1025 slink:VkPhysicalDeviceVulkanSC10Properties::pname:secondaryCommandBufferNullOrImagelessFramebuffer 1026 is ename:VK_FALSE, then 1027 slink:VkCommandBufferInheritanceInfo:pname:framebuffer must: not be 1028 dlink:VK_NULL_HANDLE and must: not have been created with a 1029 slink:VkFramebufferCreateInfo::pname:flags value that includes 1030 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT if the command buffer will be 1031 executed within a render pass instance <<SCID-8>>. 1032// end::scdeviation[] 1033endif::hidden[] 1034endif::VKSC_VERSION_1_0[] 1035 1036include::{generated}/validity/structs/VkCommandBufferBeginInfo.adoc[] 1037-- 1038 1039[open,refpage='VkCommandBufferUsageFlagBits',desc='Bitmask specifying usage behavior for command buffer',type='enums'] 1040-- 1041Bits which can: be set in slink:VkCommandBufferBeginInfo::pname:flags, 1042specifying usage behavior for a command buffer, are: 1043 1044include::{generated}/api/enums/VkCommandBufferUsageFlagBits.adoc[] 1045 1046 * ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT specifies that each 1047 recording of the command buffer will only be submitted once, and the 1048 command buffer will be reset and recorded again between each submission. 1049 * ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT specifies that a 1050 secondary command buffer is considered to be entirely inside a render 1051 pass. 1052 If this is a primary command buffer, then this bit is ignored. 1053 * ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT specifies that a 1054 command buffer can: be resubmitted to any queue of the same queue family 1055 while it is in the _pending state_, and recorded into multiple primary 1056 command buffers. 1057-- 1058 1059[open,refpage='VkCommandBufferUsageFlags',desc='Bitmask of VkCommandBufferUsageFlagBits',type='flags'] 1060-- 1061include::{generated}/api/flags/VkCommandBufferUsageFlags.adoc[] 1062 1063tname:VkCommandBufferUsageFlags is a bitmask type for setting a mask of zero 1064or more elink:VkCommandBufferUsageFlagBits. 1065-- 1066 1067[open,refpage='VkCommandBufferInheritanceInfo',desc='Structure specifying command buffer inheritance information',type='structs'] 1068-- 1069If the command buffer is a secondary command buffer, then the 1070sname:VkCommandBufferInheritanceInfo structure defines any state that will 1071be inherited from the primary command buffer: 1072 1073include::{generated}/api/structs/VkCommandBufferInheritanceInfo.adoc[] 1074 1075 * pname:sType is a elink:VkStructureType value identifying this structure. 1076 * pname:pNext is `NULL` or a pointer to a structure extending this 1077 structure. 1078 * pname:renderPass is a slink:VkRenderPass object defining which render 1079 passes the sname:VkCommandBuffer will be <<renderpass-compatibility, 1080 compatible>> with and can: be executed within. 1081 * pname:subpass is the index of the subpass within the render pass 1082 instance that the sname:VkCommandBuffer will be executed within. 1083 * pname:framebuffer can: refer to the slink:VkFramebuffer object that the 1084 sname:VkCommandBuffer will be rendering to if it is executed within a 1085 render pass instance. 1086 It can: be dlink:VK_NULL_HANDLE if the framebuffer is not known. 1087+ 1088[NOTE] 1089.Note 1090==== 1091Specifying the exact framebuffer that the secondary command buffer will be 1092executed with may: result in better performance at command buffer execution 1093time. 1094==== 1095 * pname:occlusionQueryEnable specifies whether the command buffer can: be 1096 executed while an occlusion query is active in the primary command 1097 buffer. 1098 If this is ename:VK_TRUE, then this command buffer can: be executed 1099 whether the primary command buffer has an occlusion query active or not. 1100 If this is ename:VK_FALSE, then the primary command buffer must: not 1101 have an occlusion query active. 1102 * pname:queryFlags specifies the query flags that can: be used by an 1103 active occlusion query in the primary command buffer when this secondary 1104 command buffer is executed. 1105 If this value includes the ename:VK_QUERY_CONTROL_PRECISE_BIT bit, then 1106 the active query can: return boolean results or actual sample counts. 1107 If this bit is not set, then the active query must: not use the 1108 ename:VK_QUERY_CONTROL_PRECISE_BIT bit. 1109 * pname:pipelineStatistics is a bitmask of 1110 elink:VkQueryPipelineStatisticFlagBits specifying the set of pipeline 1111 statistics that can: be counted by an active query in the primary 1112 command buffer when this secondary command buffer is executed. 1113 If this value includes a given bit, then this command buffer can: be 1114 executed whether the primary command buffer has a pipeline statistics 1115 query active that includes this bit or not. 1116 If this value excludes a given bit, then the active pipeline statistics 1117 query must: not be from a query pool that counts that statistic. 1118 1119If the slink:VkCommandBuffer will not be executed within a render pass 1120instance, 1121ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 1122or if the render pass instance was begun with flink:vkCmdBeginRendering, 1123endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 1124pname:renderPass, pname:subpass, and pname:framebuffer are ignored. 1125 1126.Valid Usage 1127**** 1128 * [[VUID-VkCommandBufferInheritanceInfo-occlusionQueryEnable-00056]] 1129 If the <<features-inheritedQueries, pname:inheritedQueries>> feature is 1130 not enabled, pname:occlusionQueryEnable must: be ename:VK_FALSE 1131 * [[VUID-VkCommandBufferInheritanceInfo-queryFlags-00057]] 1132 If the <<features-inheritedQueries, pname:inheritedQueries>> feature is 1133 enabled, pname:queryFlags must: be a valid combination of 1134 elink:VkQueryControlFlagBits values 1135 * [[VUID-VkCommandBufferInheritanceInfo-queryFlags-02788]] 1136 If the <<features-inheritedQueries, pname:inheritedQueries>> feature is 1137 not enabled, pname:queryFlags must: be code:0 1138 * [[VUID-VkCommandBufferInheritanceInfo-pipelineStatistics-02789]] 1139 If the <<features-pipelineStatisticsQuery, 1140 pname:pipelineStatisticsQuery>> feature is enabled, 1141 pname:pipelineStatistics must: be a valid combination of 1142 elink:VkQueryPipelineStatisticFlagBits values 1143 * [[VUID-VkCommandBufferInheritanceInfo-pipelineStatistics-00058]] 1144 If the <<features-pipelineStatisticsQuery, 1145 pname:pipelineStatisticsQuery>> feature is not enabled, 1146 pname:pipelineStatistics must: be code:0 1147**** 1148 1149include::{generated}/validity/structs/VkCommandBufferInheritanceInfo.adoc[] 1150-- 1151 1152[NOTE] 1153.Note 1154==== 1155On some implementations, not using the 1156ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT bit enables command 1157buffers to be patched in-place if needed, rather than creating a copy of the 1158command buffer. 1159==== 1160 1161If a command buffer is in the <<commandbuffers-lifecycle, invalid, or 1162executable state>>, and the command buffer was allocated from a command pool 1163with the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, 1164then fname:vkBeginCommandBuffer implicitly resets the command buffer, 1165behaving as if fname:vkResetCommandBuffer had been called with 1166ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT not set. 1167After the implicit reset, pname:commandBuffer is moved to the 1168<<commandbuffers-lifecycle, recording state>>. 1169 1170ifdef::VK_EXT_conditional_rendering[] 1171[open,refpage='VkCommandBufferInheritanceConditionalRenderingInfoEXT',desc='Structure specifying command buffer inheritance information',type='structs'] 1172-- 1173If the pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes a 1174sname:VkCommandBufferInheritanceConditionalRenderingInfoEXT structure, then 1175that structure controls whether a command buffer can: be executed while 1176conditional rendering is <<active-conditional-rendering,active>> in the 1177primary command buffer. 1178 1179The sname:VkCommandBufferInheritanceConditionalRenderingInfoEXT structure is 1180defined as: 1181 1182include::{generated}/api/structs/VkCommandBufferInheritanceConditionalRenderingInfoEXT.adoc[] 1183 1184 * pname:sType is a elink:VkStructureType value identifying this structure. 1185 * pname:pNext is `NULL` or a pointer to a structure extending this 1186 structure. 1187 * pname:conditionalRenderingEnable specifies whether the command buffer 1188 can: be executed while conditional rendering is active in the primary 1189 command buffer. 1190 If this is ename:VK_TRUE, then this command buffer can: be executed 1191 whether the primary command buffer has active conditional rendering or 1192 not. 1193 If this is ename:VK_FALSE, then the primary command buffer must: not 1194 have conditional rendering active. 1195 1196If this structure is not present, the behavior is as if 1197pname:conditionalRenderingEnable is ename:VK_FALSE. 1198 1199.Valid Usage 1200**** 1201 * [[VUID-VkCommandBufferInheritanceConditionalRenderingInfoEXT-conditionalRenderingEnable-01977]] 1202 If the <<features-inheritedConditionalRendering, 1203 pname:inheritedConditionalRendering>> feature is not enabled, 1204 pname:conditionalRenderingEnable must: be ename:VK_FALSE 1205**** 1206 1207include::{generated}/validity/structs/VkCommandBufferInheritanceConditionalRenderingInfoEXT.adoc[] 1208-- 1209endif::VK_EXT_conditional_rendering[] 1210 1211ifdef::VK_QCOM_render_pass_transform[] 1212[open,refpage='VkCommandBufferInheritanceRenderPassTransformInfoQCOM',desc='Structure describing transformed render pass parameters command buffer',type='structs'] 1213-- 1214To begin recording a secondary command buffer compatible with execution 1215inside a render pass using <<vertexpostproc-renderpass-transform, render 1216pass transform>>, add the 1217slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM to the 1218pname:pNext chain of slink:VkCommandBufferInheritanceInfo structure passed 1219to the flink:vkBeginCommandBuffer command specifying the parameters for 1220transformed rasterization. 1221 1222The sname:VkCommandBufferInheritanceRenderPassTransformInfoQCOM structure is 1223defined as: 1224 1225include::{generated}/api/structs/VkCommandBufferInheritanceRenderPassTransformInfoQCOM.adoc[] 1226 1227 * pname:sType is a elink:VkStructureType value identifying this structure. 1228 * pname:pNext is `NULL` or a pointer to a structure extending this 1229 structure. 1230 * pname:transform is a elink:VkSurfaceTransformFlagBitsKHR value 1231 describing the transform to be applied to the render pass. 1232 * pname:renderArea is the render area that is affected by the command 1233 buffer. 1234 1235When the secondary is recorded to execute within a render pass instance 1236using flink:vkCmdExecuteCommands, the render pass transform parameters of 1237the secondary command buffer must: be consistent with the render pass 1238transform parameters specified for the render pass instance. 1239In particular, the pname:transform and pname:renderArea for command buffer 1240must: be identical to the pname:transform and pname:renderArea of the render 1241pass instance. 1242 1243.Valid Usage 1244**** 1245 * [[VUID-VkCommandBufferInheritanceRenderPassTransformInfoQCOM-transform-02864]] 1246 pname:transform must: be ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, 1247 ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, 1248 ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or 1249 ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR 1250**** 1251 1252include::{generated}/validity/structs/VkCommandBufferInheritanceRenderPassTransformInfoQCOM.adoc[] 1253-- 1254endif::VK_QCOM_render_pass_transform[] 1255 1256ifdef::VK_NV_inherited_viewport_scissor[] 1257[open,refpage='VkCommandBufferInheritanceViewportScissorInfoNV',desc='Structure specifying command buffer inheritance information',type='structs'] 1258-- 1259The sname:VkCommandBufferInheritanceViewportScissorInfoNV structure is 1260defined as: 1261 1262include::{generated}/api/structs/VkCommandBufferInheritanceViewportScissorInfoNV.adoc[] 1263 1264 * pname:sType is a elink:VkStructureType value identifying this structure. 1265 * pname:pNext is `NULL` or a pointer to a structure extending this 1266 structure. 1267 * pname:viewportScissor2D specifies whether the listed dynamic state is 1268 inherited. 1269 * pname:viewportDepthCount specifies the maximum number of viewports to 1270 inherit. 1271 When pname:viewportScissor2D is ename:VK_FALSE, the behavior is as if 1272 this value is zero. 1273 * pname:pViewportDepths is a pointer to a slink:VkViewport structure 1274 specifying the expected depth range for each inherited viewport. 1275 1276If the pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes a 1277sname:VkCommandBufferInheritanceViewportScissorInfoNV structure, then that 1278structure controls whether a command buffer can: inherit the following state 1279from other command buffers: 1280 1281 * ename:VK_DYNAMIC_STATE_SCISSOR 1282ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1283 * ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT 1284endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1285ifdef::VK_EXT_discard_rectangles[] 1286 * ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT 1287 * ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT 1288 * ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT 1289endif::VK_EXT_discard_rectangles[] 1290 1291as well as the following state, with restrictions on inherited depth values 1292and viewport count: 1293 1294 * ename:VK_DYNAMIC_STATE_VIEWPORT 1295ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1296 * ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT 1297endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1298 1299If pname:viewportScissor2D is ename:VK_FALSE, then the command buffer does 1300not inherit the listed dynamic state, and should: set this state itself. 1301If this structure is not present, the behavior is as if 1302pname:viewportScissor2D is ename:VK_FALSE. 1303 1304If pname:viewportScissor2D is ename:VK_TRUE, then the listed dynamic state 1305is inherited, and the command buffer must: not set this 1306ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[state.] 1307ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1308state, except that the viewport and scissor count may: be set by binding a 1309graphics pipeline that does not specify this state as dynamic. 1310 1311[NOTE] 1312.Note 1313==== 1314Due to this restriction, applications should: ensure either all or none of 1315the graphics pipelines bound in this secondary command buffer use dynamic 1316viewport/scissor counts. 1317==== 1318endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 1319 1320When the command buffer is executed as part of a the execution of a 1321flink:vkCmdExecuteCommands command, the inherited state (if enabled) is 1322determined by the following procedure, performed separately for each dynamic 1323state, and separately for each value for dynamic state that consists of 1324multiple values (e.g. multiple viewports). 1325 1326 * With [eq]#i# being the index of the executed command buffer in the 1327 pname:pCommandBuffers array of flink:vkCmdExecuteCommands, if [eq]#i > 1328 0# and any secondary command buffer from index [eq]#0# to [eq]#i-1# 1329 modifies the state, the inherited state is provisionally set to the 1330 final value set by the last such secondary command buffer. 1331 Binding a graphics pipeline defining the state statically is equivalent 1332 to setting the state to an undefined: value. 1333 * Otherwise, the tentatative inherited state is that of the primary 1334 command buffer at the point the flink:vkCmdExecuteCommands command was 1335 recorded; if the state is undefined:, then so is the provisional 1336 inherited state. 1337 * If the provisional inherited state is an undefined: value, then the 1338 state is not inherited. 1339 * If the provisional inherited state is a viewport, with [eq]#n# being its 1340 viewport index, then if [eq]#n {geq} pname:viewportDepthCount#, or if 1341 either slink:VkViewport::pname:minDepth or 1342 slink:VkViewport::pname:maxDepth are not equal to the respective values 1343 of the [eq]#n^th^# element of pname:pViewportDepths, then the state is 1344 not inherited. 1345 * If the provisional inherited state passes both checks, then it becomes 1346 the actual inherited state. 1347 1348[NOTE] 1349.Note 1350==== 1351There is no support for inheriting dynamic state from a secondary command 1352buffer executed as part of a different `vkCmdExecuteCommands` command. 1353==== 1354 1355.Valid Usage 1356**** 1357 * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04782]] 1358 If the <<features-inheritedViewportScissor2D, 1359 pname:inheritedViewportScissor2D>> feature is not enabled, 1360 pname:viewportScissor2D must: be ename:VK_FALSE 1361 * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04783]] 1362 If the <<features-multiViewport, pname:multiViewport>> feature is not 1363 enabled and pname:viewportScissor2D is ename:VK_TRUE, then 1364 pname:viewportDepthCount must: be `1` 1365 * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04784]] 1366 If pname:viewportScissor2D is ename:VK_TRUE, then 1367 pname:viewportDepthCount must: be greater than `0` 1368 * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04785]] 1369 If pname:viewportScissor2D is ename:VK_TRUE, then pname:pViewportDepths 1370 must: be a valid pointer to an array of `viewportDepthCount` valid 1371 sname:VkViewport structures, except any requirements on `x`, `y`, 1372 `width`, and `height` do not apply 1373 * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04786]] 1374 If pname:viewportScissor2D is ename:VK_TRUE, then the command buffer 1375 must: be recorded with the 1376 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 1377**** 1378 1379include::{generated}/validity/structs/VkCommandBufferInheritanceViewportScissorInfoNV.adoc[] 1380-- 1381endif::VK_NV_inherited_viewport_scissor[] 1382 1383ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 1384[open,refpage='VkCommandBufferInheritanceRenderingInfo',desc='Structure specifying command buffer inheritance info for dynamic render pass instances',type='structs',alias='VkCommandBufferInheritanceRenderingInfoKHR'] 1385-- 1386The sname:VkCommandBufferInheritanceRenderingInfo structure is defined as: 1387 1388include::{generated}/api/structs/VkCommandBufferInheritanceRenderingInfo.adoc[] 1389 1390ifdef::VK_KHR_dynamic_rendering[] 1391or the equivalent 1392 1393include::{generated}/api/structs/VkCommandBufferInheritanceRenderingInfoKHR.adoc[] 1394endif::VK_KHR_dynamic_rendering[] 1395 1396 * pname:sType is a elink:VkStructureType value identifying this structure. 1397 * pname:pNext is `NULL` or a pointer to a structure extending this 1398 structure 1399 * pname:flags is a bitmask of elink:VkRenderingFlagBits used by the render 1400 pass instance. 1401 * pname:viewMask is the view mask used for rendering. 1402 * pname:colorAttachmentCount is the number of color attachments specified 1403 in the render pass instance. 1404 * pname:pColorAttachmentFormats is a pointer to an array of elink:VkFormat 1405 values defining the format of color attachments. 1406 * pname:depthAttachmentFormat is a elink:VkFormat value defining the 1407 format of the depth attachment. 1408 * pname:stencilAttachmentFormat is a elink:VkFormat value defining the 1409 format of the stencil attachment. 1410 * pname:rasterizationSamples is a elink:VkSampleCountFlagBits specifying 1411 the number of samples used in rasterization. 1412 1413If the pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes a 1414sname:VkCommandBufferInheritanceRenderingInfo structure, then that structure 1415controls parameters of dynamic render pass instances that the 1416slink:VkCommandBuffer can: be executed within. 1417If slink:VkCommandBufferInheritanceInfo::pname:renderPass is not 1418dlink:VK_NULL_HANDLE, or 1419ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not specified in 1420slink:VkCommandBufferBeginInfo::pname:flags, parameters of this structure 1421are ignored. 1422 1423If pname:colorAttachmentCount is `0` and the 1424<<features-variableMultisampleRate, pname:variableMultisampleRate>> feature 1425is enabled, pname:rasterizationSamples is ignored. 1426 1427If pname:depthAttachmentFormat, pname:stencilAttachmentFormat, or any 1428element of pname:pColorAttachmentFormats is ename:VK_FORMAT_UNDEFINED, it 1429indicates that the corresponding attachment is unused within the render pass 1430and writes to those attachments are discarded. 1431 1432.Valid Usage 1433**** 1434 * [[VUID-VkCommandBufferInheritanceRenderingInfo-colorAttachmentCount-06004]] 1435 If pname:colorAttachmentCount is not `0`, pname:rasterizationSamples 1436 must: be a valid elink:VkSampleCountFlagBits value 1437 * [[VUID-VkCommandBufferInheritanceRenderingInfo-variableMultisampleRate-06005]] 1438 If the <<features-variableMultisampleRate, 1439 pname:variableMultisampleRate>> feature is not enabled, 1440 pname:rasterizationSamples must: be a valid elink:VkSampleCountFlagBits 1441 value 1442 * [[VUID-VkCommandBufferInheritanceRenderingInfo-depthAttachmentFormat-06540]] 1443 If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it 1444 must: be a format that includes a depth component 1445 * [[VUID-VkCommandBufferInheritanceRenderingInfo-depthAttachmentFormat-06007]] 1446 If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it 1447 must: be a format with <<potential-format-features, potential format 1448 features>> that include 1449 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 1450 * [[VUID-VkCommandBufferInheritanceRenderingInfo-pColorAttachmentFormats-06492]] 1451 If any element of pname:pColorAttachmentFormats is not 1452 ename:VK_FORMAT_UNDEFINED, it must: be a format with 1453 <<potential-format-features, potential format features>> that include 1454 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT 1455ifdef::VK_NV_linear_color_attachment[] 1456 , or ename:VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV if the 1457 <<features-linearColorAttachment, pname:linearColorAttachment>> feature 1458 is enabled 1459endif::VK_NV_linear_color_attachment[] 1460 * [[VUID-VkCommandBufferInheritanceRenderingInfo-stencilAttachmentFormat-06541]] 1461 If pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it 1462 must: be a format that includes a stencil aspect 1463 * [[VUID-VkCommandBufferInheritanceRenderingInfo-stencilAttachmentFormat-06199]] 1464 If pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it 1465 must: be a format with <<potential-format-features, potential format 1466 features>> that include 1467 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 1468 * [[VUID-VkCommandBufferInheritanceRenderingInfo-depthAttachmentFormat-06200]] 1469 If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED and 1470 pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, 1471 pname:depthAttachmentFormat must: equal pname:stencilAttachmentFormat 1472 * [[VUID-VkCommandBufferInheritanceRenderingInfo-multiview-06008]] 1473 If the <<features-multiview, pname:multiview>> feature is not enabled, 1474 pname:viewMask must: be `0` 1475ifdef::VK_VERSION_1_1,VK_KHR_multiview[] 1476 * [[VUID-VkCommandBufferInheritanceRenderingInfo-viewMask-06009]] 1477 The index of the most significant bit in pname:viewMask must: be less 1478 than <<limits-maxMultiviewViewCount, pname:maxMultiviewViewCount>> 1479endif::VK_VERSION_1_1,VK_KHR_multiview[] 1480**** 1481 1482include::{generated}/validity/structs/VkCommandBufferInheritanceRenderingInfo.adoc[] 1483-- 1484 1485ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 1486[open,refpage='VkAttachmentSampleCountInfoAMD',desc='Structure specifying command buffer inheritance info for dynamic render pass instances',type='structs',alias='VkAttachmentSampleCountInfoNV'] 1487-- 1488The 1489ifdef::VK_AMD_mixed_attachment_samples[sname:VkAttachmentSampleCountInfoAMD] 1490ifdef::VK_AMD_mixed_attachment_samples+VK_NV_framebuffer_mixed_samples[or] 1491ifdef::VK_NV_framebuffer_mixed_samples[sname:VkAttachmentSampleCountInfoNV] 1492structure is defined as: 1493 1494ifdef::VK_AMD_mixed_attachment_samples[] 1495include::{generated}/api/structs/VkAttachmentSampleCountInfoAMD.adoc[] 1496endif::VK_AMD_mixed_attachment_samples[] 1497 1498ifdef::VK_AMD_mixed_attachment_samples+VK_NV_framebuffer_mixed_samples[or the equivalent] 1499 1500ifdef::VK_NV_framebuffer_mixed_samples[] 1501include::{generated}/api/structs/VkAttachmentSampleCountInfoNV.adoc[] 1502endif::VK_NV_framebuffer_mixed_samples[] 1503 1504 * pname:sType is a elink:VkStructureType value identifying this structure. 1505 * pname:pNext is `NULL` or a pointer to a structure extending this 1506 structure 1507 * pname:colorAttachmentCount is the number of color attachments specified 1508 in a render pass instance. 1509 * pname:pColorAttachmentSamples is a pointer to an array of 1510 elink:VkSampleCountFlagBits values defining the sample count of color 1511 attachments. 1512 * pname:depthStencilAttachmentSamples is a elink:VkSampleCountFlagBits 1513 value defining the sample count of a depth/stencil attachment. 1514 1515If slink:VkCommandBufferInheritanceInfo::pname:renderPass is 1516dlink:VK_NULL_HANDLE, ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 1517is specified in slink:VkCommandBufferBeginInfo::pname:flags, and the 1518pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes 1519sname:VkAttachmentSampleCountInfoAMD, then this structure defines the sample 1520counts of each attachment within the render pass instance. 1521If sname:VkAttachmentSampleCountInfoAMD is not included, the value of 1522slink:VkCommandBufferInheritanceRenderingInfo::pname:rasterizationSamples is 1523used as the sample count for each attachment. 1524If slink:VkCommandBufferInheritanceInfo::pname:renderPass is not 1525dlink:VK_NULL_HANDLE, or 1526ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not specified in 1527slink:VkCommandBufferBeginInfo::pname:flags, parameters of this structure 1528are ignored. 1529 1530sname:VkAttachmentSampleCountInfoAMD can: also be included in the 1531pname:pNext chain of slink:VkGraphicsPipelineCreateInfo. 1532When a graphics pipeline is created without a slink:VkRenderPass, if this 1533structure is included in the pname:pNext chain of 1534slink:VkGraphicsPipelineCreateInfo, it specifies the sample count of 1535attachments used for rendering. 1536If this structure is not specified, and the pipeline does not include a 1537slink:VkRenderPass, the value of 1538slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples is 1539used as the sample count for each attachment. 1540If a graphics pipeline is created with a valid slink:VkRenderPass, 1541parameters of this structure are ignored. 1542 1543include::{generated}/validity/structs/VkAttachmentSampleCountInfoAMD.adoc[] 1544-- 1545endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 1546 1547endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 1548 1549Once recording starts, an application records a sequence of commands 1550(ftext:vkCmd*) to set state in the command buffer, draw, dispatch, and other 1551commands. 1552 1553ifdef::VK_NV_device_generated_commands[] 1554Several commands can also be recorded indirectly from sname:VkBuffer 1555content, see <<device-generated-commands>>. 1556endif::VK_NV_device_generated_commands[] 1557 1558[open,refpage='vkEndCommandBuffer',desc='Finish recording a command buffer',type='protos'] 1559-- 1560 1561:refpage: vkEndCommandBuffer 1562 1563To complete recording of a command buffer, call: 1564 1565include::{generated}/api/protos/vkEndCommandBuffer.adoc[] 1566 1567 * pname:commandBuffer is the command buffer to complete recording. 1568 1569The command buffer must: have been in the <<commandbuffers-lifecycle, 1570recording state>>, and, if successful, is moved to the 1571<<commandbuffers-lifecycle, executable state>>. 1572 1573If there was an error during recording, the application will be notified by 1574an unsuccessful return code returned by fname:vkEndCommandBuffer, and the 1575command buffer will be moved to the <<commandbuffers-lifecycle, invalid 1576state>>. 1577 1578ifdef::VK_KHR_video_encode_queue[] 1579In case the application recorded one or more <<video-encode-operations,video 1580encode operations>> into the command buffer, implementations may: return the 1581ename:VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error if any of the 1582specified Video Std parameters do not adhere to the syntactic or semantic 1583requirements of the used video compression standard, or if values derived 1584from parameters according to the rules defined by the used video compression 1585standard do not adhere to the capabilities of the video compression standard 1586or the implementation. 1587 1588[NOTE] 1589.Note 1590==== 1591Applications should: not rely on the 1592ename:VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error being returned by any 1593command as a means to verify Video Std parameters, as implementations are 1594not required to report the error in any specific set of cases. 1595==== 1596endif::VK_KHR_video_encode_queue[] 1597 1598ifdef::VKSC_VERSION_1_0[] 1599If recording a command would exceed the amount of command pool memory 1600reserved by 1601slink:VkCommandPoolMemoryReservationCreateInfo::pname:commandPoolReservedSize, 1602the implementation may: report a ename:VK_FAULT_TYPE_COMMAND_BUFFER_FULL 1603fault. 1604The command buffer remains in the <<commandbuffers-lifecycle, recording 1605state>> until fname:vkEndCommandBuffer is called. 1606When fname:vkEndCommandBuffer is called on a command buffer for which the 1607command pool memory reservation was exceeded during recording, it must: 1608return ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 1609endif::VKSC_VERSION_1_0[] 1610 1611include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 1612 1613.Valid Usage 1614**** 1615 * [[VUID-vkEndCommandBuffer-commandBuffer-00059]] 1616 pname:commandBuffer must: be in the <<commandbuffers-lifecycle, 1617 recording state>> 1618 * [[VUID-vkEndCommandBuffer-commandBuffer-00060]] 1619 If pname:commandBuffer is a primary command buffer, there must: not be 1620 an active render pass instance 1621 * [[VUID-vkEndCommandBuffer-commandBuffer-00061]] 1622 All queries made <<queries-operation-active,active>> during the 1623 recording of pname:commandBuffer must: have been made inactive 1624ifdef::VK_EXT_conditional_rendering[] 1625 * [[VUID-vkEndCommandBuffer-None-01978]] 1626 Conditional rendering must: not be 1627 <<active-conditional-rendering,active>> 1628endif::VK_EXT_conditional_rendering[] 1629ifdef::VK_KHR_video_queue[] 1630 * [[VUID-vkEndCommandBuffer-None-06991]] 1631 There must: be no video session object bound 1632endif::VK_KHR_video_queue[] 1633ifdef::VK_EXT_debug_utils[] 1634 * [[VUID-vkEndCommandBuffer-commandBuffer-01815]] 1635 If pname:commandBuffer is a secondary command buffer, there must: not be 1636 an outstanding flink:vkCmdBeginDebugUtilsLabelEXT command recorded to 1637 pname:commandBuffer that has not previously been ended by a call to 1638 flink:vkCmdEndDebugUtilsLabelEXT 1639endif::VK_EXT_debug_utils[] 1640ifdef::VK_EXT_debug_marker[] 1641 * [[VUID-vkEndCommandBuffer-commandBuffer-00062]] 1642 If pname:commandBuffer is a secondary command buffer, there must: not be 1643 an outstanding flink:vkCmdDebugMarkerBeginEXT command recorded to 1644 pname:commandBuffer that has not previously been ended by a call to 1645 flink:vkCmdDebugMarkerEndEXT 1646endif::VK_EXT_debug_marker[] 1647**** 1648 1649include::{generated}/validity/protos/vkEndCommandBuffer.adoc[] 1650-- 1651 1652When a command buffer is in the executable state, it can: be submitted to a 1653queue for execution. 1654 1655 1656[[commandbuffers-submission]] 1657== Command Buffer Submission 1658 1659[NOTE] 1660.Note 1661==== 1662Submission can be a high overhead operation, and applications should: 1663attempt to batch work together into as few calls to fname:vkQueueSubmit 1664ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 1665or fname:vkQueueSubmit2 1666endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 1667as possible. 1668==== 1669 1670ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 1671[open,refpage='vkQueueSubmit2',desc='Submits command buffers to a queue',type='protos',alias='vkQueueSubmit2KHR'] 1672-- 1673 1674:refpage: vkQueueSubmit2KHR 1675 1676To submit command buffers to a queue, call: 1677 1678ifdef::VK_VERSION_1_3[] 1679include::{generated}/api/protos/vkQueueSubmit2.adoc[] 1680endif::VK_VERSION_1_3[] 1681 1682ifdef::VK_VERSION_1_3+VK_KHR_synchronization2[or the equivalent command] 1683 1684ifdef::VK_KHR_synchronization2[] 1685include::{generated}/api/protos/vkQueueSubmit2KHR.adoc[] 1686endif::VK_KHR_synchronization2[] 1687 1688 * pname:queue is the queue that the command buffers will be submitted to. 1689 * pname:submitCount is the number of elements in the pname:pSubmits array. 1690 * pname:pSubmits is a pointer to an array of slink:VkSubmitInfo2 1691 structures, each specifying a command buffer submission batch. 1692 * pname:fence is an optional: handle to a fence to be signaled once all 1693 submitted command buffers have completed execution. 1694 If pname:fence is not dlink:VK_NULL_HANDLE, it defines a 1695 <<synchronization-fences-signaling, fence signal operation>>. 1696 1697fname:vkQueueSubmit2 is a <<devsandqueues-submission,queue submission 1698command>>, with each batch defined by an element of pname:pSubmits. 1699 1700Semaphore operations submitted with flink:vkQueueSubmit2 have additional 1701ordering constraints compared to other submission commands, with 1702dependencies involving previous and subsequent queue operations. 1703Information about these additional constraints can be found in the 1704<<synchronization-semaphores, semaphore>> section of <<synchronization, the 1705synchronization chapter>>. 1706 1707If any command buffer submitted to this queue is in the 1708<<commandbuffers-lifecycle, executable state>>, it is moved to the 1709<<commandbuffers-lifecycle, pending state>>. 1710Once execution of all submissions of a command buffer complete, it moves 1711from the <<commandbuffers-lifecycle, pending state>>, back to the 1712<<commandbuffers-lifecycle, executable state>>. 1713If a command buffer was recorded with the 1714ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves 1715back to the <<commandbuffers-lifecycle, invalid state>>. 1716 1717If fname:vkQueueSubmit2 fails, it may: return 1718ename:VK_ERROR_OUT_OF_HOST_MEMORY or ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 1719If it does, the implementation must: ensure that the state and contents of 1720any resources or synchronization primitives referenced by the submitted 1721command buffers and any semaphores referenced by pname:pSubmits is 1722unaffected by the call or its failure. 1723If fname:vkQueueSubmit2 fails in such a way that the implementation is 1724unable to make that guarantee, the implementation must: return 1725ename:VK_ERROR_DEVICE_LOST. 1726See <<devsandqueues-lost-device,Lost Device>>. 1727 1728include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 1729 1730.Valid Usage 1731**** 1732 * [[VUID-vkQueueSubmit2-fence-04894]] 1733 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be 1734 unsignaled 1735 * [[VUID-vkQueueSubmit2-fence-04895]] 1736 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be 1737 associated with any other queue command that has not yet completed 1738 execution on that queue 1739 * [[VUID-vkQueueSubmit2-synchronization2-03866]] 1740 The <<features-synchronization2, pname:synchronization2>> feature must: 1741 be enabled 1742 * [[VUID-vkQueueSubmit2-commandBuffer-03867]] 1743 If a command recorded into the pname:commandBuffer member of any element 1744 of the pname:pCommandBufferInfos member of any element of pname:pSubmits 1745 referenced an slink:VkEvent, that event must: not be referenced by a 1746 command that has been submitted to another queue and is still in the 1747 _pending state_ 1748 * [[VUID-vkQueueSubmit2-semaphore-03868]] 1749 The pname:semaphore member of any binary semaphore element of the 1750 pname:pSignalSemaphoreInfos member of any element of pname:pSubmits 1751 must: be unsignaled when the semaphore signal operation it defines is 1752 executed on the device 1753 * [[VUID-vkQueueSubmit2-stageMask-03869]] 1754 The pname:stageMask member of any element of the 1755 pname:pSignalSemaphoreInfos member of any element of pname:pSubmits 1756 must: only include pipeline stages that are supported by the queue 1757 family which pname:queue belongs to 1758 * [[VUID-vkQueueSubmit2-stageMask-03870]] 1759 The pname:stageMask member of any element of the 1760 pname:pWaitSemaphoreInfos member of any element of pname:pSubmits must: 1761 only include pipeline stages that are supported by the queue family 1762 which pname:queue belongs to 1763 * [[VUID-vkQueueSubmit2-semaphore-03871]] 1764 When a semaphore wait operation for a binary semaphore is executed, as 1765 defined by the pname:semaphore member of any element of the 1766 pname:pWaitSemaphoreInfos member of any element of pname:pSubmits, there 1767 must: be no other queues waiting on the same semaphore 1768 * [[VUID-vkQueueSubmit2-semaphore-03873]] 1769 The pname:semaphore member of any element of the 1770 pname:pWaitSemaphoreInfos member of any element of pname:pSubmits 1771ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1772 that was created with a elink:VkSemaphoreTypeKHR of 1773 ename:VK_SEMAPHORE_TYPE_BINARY_KHR 1774endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1775 must: reference a semaphore signal operation that has been submitted for 1776 execution and any <<synchronization-semaphores-signaling, semaphore 1777 signal operations>> on which it depends must: have also been submitted 1778 for execution 1779 * [[VUID-vkQueueSubmit2-commandBuffer-03874]] 1780 The pname:commandBuffer member of any element of the 1781 pname:pCommandBufferInfos member of any element of pname:pSubmits must: 1782 be in the <<commandbuffers-lifecycle, pending or executable state>> 1783 * [[VUID-vkQueueSubmit2-commandBuffer-03875]] 1784 If a command recorded into the pname:commandBuffer member of any element 1785 of the pname:pCommandBufferInfos member of any element of pname:pSubmits 1786 was not recorded with the 1787 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 1788 the <<commandbuffers-lifecycle, pending state>> 1789 * [[VUID-vkQueueSubmit2-commandBuffer-03876]] 1790 Any <<commandbuffers-secondary, secondary command buffers recorded>> 1791 into the pname:commandBuffer member of any element of the 1792 pname:pCommandBufferInfos member of any element of pname:pSubmits must: 1793 be in the <<commandbuffers-lifecycle, pending or executable state>> 1794 * [[VUID-vkQueueSubmit2-commandBuffer-03877]] 1795 If any <<commandbuffers-secondary, secondary command buffers recorded>> 1796 into the pname:commandBuffer member of any element of the 1797 pname:pCommandBufferInfos member of any element of pname:pSubmits was 1798 not recorded with the 1799 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 1800 the <<commandbuffers-lifecycle, pending state>> 1801 * [[VUID-vkQueueSubmit2-commandBuffer-03878]] 1802 The pname:commandBuffer member of any element of the 1803 pname:pCommandBufferInfos member of any element of pname:pSubmits must: 1804 have been allocated from a sname:VkCommandPool that was created for the 1805 same queue family pname:queue belongs to 1806 * [[VUID-vkQueueSubmit2-commandBuffer-03879]] 1807 If a command recorded into the pname:commandBuffer member of any element 1808 of the pname:pCommandBufferInfos member of any element of pname:pSubmits 1809 includes a <<synchronization-queue-transfers-acquire, Queue Family 1810 Transfer Acquire Operation>>, there must: exist a previously submitted 1811 <<synchronization-queue-transfers-release, Queue Family Transfer Release 1812 Operation>> on a queue in the queue family identified by the acquire 1813 operation, with parameters matching the acquire operation as defined in 1814 the definition of such <<synchronization-queue-transfers-acquire, 1815 acquire operations>>, and which happens before the acquire operation 1816ifdef::VK_KHR_performance_query[] 1817 * [[VUID-vkQueueSubmit2-commandBuffer-03880]] 1818 If a command recorded into the pname:commandBuffer member of any element 1819 of the pname:pCommandBufferInfos member of any element of pname:pSubmits 1820 was a flink:vkCmdBeginQuery whose pname:queryPool was created with a 1821 pname:queryType of ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the 1822 <<profiling-lock, profiling lock>> must: have been held continuously on 1823 the sname:VkDevice that pname:queue was retrieved from, throughout 1824 recording of those command buffers 1825endif::VK_KHR_performance_query[] 1826ifdef::VK_VERSION_1_1[] 1827 * [[VUID-vkQueueSubmit2-queue-06447]] 1828 If pname:queue was not created with 1829 ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, the pname:flags member of 1830 any element of pname:pSubmits must: not include 1831 ename:VK_SUBMIT_PROTECTED_BIT_KHR 1832endif::VK_VERSION_1_1[] 1833**** 1834 1835include::{generated}/validity/protos/vkQueueSubmit2.adoc[] 1836-- 1837 1838[open,refpage='VkSubmitInfo2',desc='Structure specifying a queue submit operation',type='structs',alias='VkSubmitInfo2KHR'] 1839-- 1840The sname:VkSubmitInfo2 structure is defined as: 1841 1842include::{generated}/api/structs/VkSubmitInfo2.adoc[] 1843 1844ifdef::VK_KHR_synchronization2[] 1845or the equivalent 1846 1847include::{generated}/api/structs/VkSubmitInfo2KHR.adoc[] 1848endif::VK_KHR_synchronization2[] 1849 1850 * pname:sType is a elink:VkStructureType value identifying this structure. 1851 * pname:pNext is `NULL` or a pointer to a structure extending this 1852 structure. 1853 * pname:flags is a bitmask of elink:VkSubmitFlagBits. 1854 * pname:waitSemaphoreInfoCount is the number of elements in 1855 pname:pWaitSemaphoreInfos. 1856 * pname:pWaitSemaphoreInfos is a pointer to an array of 1857 slink:VkSemaphoreSubmitInfo structures defining 1858 <<synchronization-semaphores-waiting, semaphore wait operations>>. 1859 * pname:commandBufferInfoCount is the number of elements in 1860 pname:pCommandBufferInfos and the number of command buffers to execute 1861 in the batch. 1862 * pname:pCommandBufferInfos is a pointer to an array of 1863 slink:VkCommandBufferSubmitInfo structures describing command buffers to 1864 execute in the batch. 1865 * pname:signalSemaphoreInfoCount is the number of elements in 1866 pname:pSignalSemaphoreInfos. 1867 * pname:pSignalSemaphoreInfos is a pointer to an array of 1868 slink:VkSemaphoreSubmitInfo describing 1869 <<synchronization-semaphores-signaling, semaphore signal operations>>. 1870 1871.Valid Usage 1872**** 1873ifdef::VK_KHR_timeline_semaphore[] 1874 * [[VUID-VkSubmitInfo2-semaphore-03881]] 1875 If the same semaphore is used as the pname:semaphore member of both an 1876 element of pname:pSignalSemaphoreInfos and pname:pWaitSemaphoreInfos, 1877 and that semaphore is a timeline semaphore, the pname:value member of 1878 the pname:pSignalSemaphoreInfos element must: be greater than the 1879 pname:value member of the pname:pWaitSemaphoreInfos element 1880 * [[VUID-VkSubmitInfo2-semaphore-03882]] 1881 If the pname:semaphore member of any element of 1882 pname:pSignalSemaphoreInfos is a timeline semaphore, the pname:value 1883 member of that element must: have a value greater than the current value 1884 of the semaphore when the <<synchronization-semaphores-signaling, 1885 semaphore signal operation>> is executed 1886 * [[VUID-VkSubmitInfo2-semaphore-03883]] 1887 If the pname:semaphore member of any element of 1888 pname:pSignalSemaphoreInfos is a timeline semaphore, the pname:value 1889 member of that element must: have a value which does not differ from the 1890 current value of the semaphore or the value of any outstanding semaphore 1891 wait or signal operation on that semaphore by more than 1892 <<limits-maxTimelineSemaphoreValueDifference, 1893 pname:maxTimelineSemaphoreValueDifference>> 1894 * [[VUID-VkSubmitInfo2-semaphore-03884]] 1895 If the pname:semaphore member of any element of 1896 pname:pWaitSemaphoreInfos is a timeline semaphore, the pname:value 1897 member of that element must: have a value which does not differ from the 1898 current value of the semaphore or the value of any outstanding semaphore 1899 wait or signal operation on that semaphore by more than 1900 <<limits-maxTimelineSemaphoreValueDifference, 1901 pname:maxTimelineSemaphoreValueDifference>> 1902endif::VK_KHR_timeline_semaphore[] 1903ifdef::VK_VERSION_1_1[] 1904 * [[VUID-VkSubmitInfo2-flags-03886]] 1905 If pname:flags includes ename:VK_SUBMIT_PROTECTED_BIT, all elements of 1906 pname:pCommandBuffers must: be protected command buffers 1907 * [[VUID-VkSubmitInfo2-flags-03887]] 1908 If pname:flags does not include ename:VK_SUBMIT_PROTECTED_BIT, each 1909 element of pname:pCommandBuffers must: not be a protected command buffer 1910endif::VK_VERSION_1_1[] 1911ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 1912 * [[VUID-VkSubmitInfo2KHR-commandBuffer-06192]] 1913 If any pname:commandBuffer member of an element of 1914 pname:pCommandBufferInfos contains any <<renderpass-suspension,resumed 1915 render pass instances>>, they must: be suspended by a render pass 1916 instance earlier in submission order within pname:pCommandBufferInfos 1917 * [[VUID-VkSubmitInfo2KHR-commandBuffer-06010]] 1918 If any pname:commandBuffer member of an element of 1919 pname:pCommandBufferInfos contains any <<renderpass-suspension,suspended 1920 render pass instances>>, they must: be resumed by a render pass instance 1921 later in submission order within pname:pCommandBufferInfos 1922 * [[VUID-VkSubmitInfo2KHR-commandBuffer-06011]] 1923 If any pname:commandBuffer member of an element of 1924 pname:pCommandBufferInfos contains any <<renderpass-suspension,suspended 1925 render pass instances>>, there must: be no action or synchronization 1926 commands between that render pass instance and the render pass instance 1927 that resumes it 1928 * [[VUID-VkSubmitInfo2KHR-commandBuffer-06012]] 1929 If any pname:commandBuffer member of an element of 1930 pname:pCommandBufferInfos contains any <<renderpass-suspension,suspended 1931 render pass instances>>, there must: be no render pass instances between 1932 that render pass instance and the render pass instance that resumes it 1933ifdef::VK_EXT_sample_locations[] 1934 * [[VUID-VkSubmitInfo2KHR-variableSampleLocations-06013]] 1935 If the <<limits-variableSampleLocations, pname:variableSampleLocations>> 1936 limit is not supported, and any pname:commandBuffer member of an element 1937 of pname:pCommandBufferInfos contains any <<renderpass-suspension, 1938 suspended render pass instances>>, where a graphics pipeline has been 1939 bound, any pipelines bound in the render pass instance that resumes it, 1940 or any subsequent render pass instances that resume from that one and so 1941 on, must: use the same sample locations 1942endif::VK_EXT_sample_locations[] 1943endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 1944**** 1945 1946include::{generated}/validity/structs/VkSubmitInfo2.adoc[] 1947-- 1948 1949[open,refpage='VkSubmitFlagBits',desc='Bitmask specifying behavior of a submission',type='enums',alias='VkSubmitFlagBitsKHR'] 1950-- 1951Bits which can: be set in slink:VkSubmitInfo2::pname:flags, specifying 1952submission behavior, are: 1953 1954include::{generated}/api/enums/VkSubmitFlagBits.adoc[] 1955 1956ifdef::VK_KHR_synchronization2[] 1957or the equivalent 1958 1959include::{generated}/api/enums/VkSubmitFlagBitsKHR.adoc[] 1960endif::VK_KHR_synchronization2[] 1961 1962 * ename:VK_SUBMIT_PROTECTED_BIT specifies that this batch is a protected 1963 submission. 1964-- 1965 1966[open,refpage='VkSubmitFlags',desc='Bitmask of VkSubmitFlagBits',type='flags',alias='VkSubmitFlagsKHR'] 1967-- 1968include::{generated}/api/flags/VkSubmitFlags.adoc[] 1969 1970ifdef::VK_KHR_synchronization2[] 1971or the equivalent 1972 1973include::{generated}/api/flags/VkSubmitFlagsKHR.adoc[] 1974endif::VK_KHR_synchronization2[] 1975 1976tname:VkSubmitFlags is a bitmask type for setting a mask of zero or more 1977elink:VkSubmitFlagBits. 1978-- 1979 1980[open,refpage='VkSemaphoreSubmitInfo',desc='Structure specifying a semaphore signal or wait operation',type='structs',alias='VkSemaphoreSubmitInfoKHR'] 1981-- 1982:refpage: VkSemaphoreSubmitInfo 1983 1984The sname:VkSemaphoreSubmitInfo structure is defined as: 1985 1986include::{generated}/api/structs/VkSemaphoreSubmitInfo.adoc[] 1987 1988ifdef::VK_KHR_synchronization2[] 1989or the equivalent 1990 1991include::{generated}/api/structs/VkSemaphoreSubmitInfoKHR.adoc[] 1992endif::VK_KHR_synchronization2[] 1993 1994 * pname:sType is a elink:VkStructureType value identifying this structure. 1995 * pname:pNext is `NULL` or a pointer to a structure extending this 1996 structure. 1997 * pname:semaphore is a slink:VkSemaphore affected by this operation. 1998 * pname:value is 1999ifdef::VK_KHR_timeline_semaphore[] 2000 either the value used to signal pname:semaphore or the value waited on 2001 by pname:semaphore, if pname:semaphore is a timeline semaphore. 2002 Otherwise it is 2003endif::VK_KHR_timeline_semaphore[] 2004 ignored. 2005 * pname:stageMask is a tlink:VkPipelineStageFlags2 mask of pipeline stages 2006 which limit the first synchronization scope of a semaphore signal 2007 operation, or second synchronization scope of a semaphore wait operation 2008 as described in the <<synchronization-semaphores-waiting, semaphore wait 2009 operation>> and <<synchronization-semaphores-signaling, semaphore signal 2010 operation>> sections of <<synchronization, the synchronization 2011 chapter>>. 2012 * pname:deviceIndex is the index of the device within a device group that 2013 executes the semaphore wait or signal operation. 2014 2015Whether this structure defines a semaphore wait or signal operation is 2016defined by how it is used. 2017 2018.Valid Usage 2019**** 2020:stageMaskName: stageMask 2021include::{chapters}/commonvalidity/stage_mask_2_common.adoc[] 2022 * [[VUID-VkSemaphoreSubmitInfo-device-03888]] 2023 If the pname:device that pname:semaphore was created on is not a device 2024 group, pname:deviceIndex must: be `0` 2025ifdef::VK_KHR_device_group_creation,VK_VERSION_1_1[] 2026 * [[VUID-VkSemaphoreSubmitInfo-device-03889]] 2027 If the pname:device that pname:semaphore was created on is a device 2028 group, pname:deviceIndex must: be a valid device index 2029endif::VK_KHR_device_group_creation,VK_VERSION_1_1[] 2030ifdef::VK_NV_external_sci_sync,VK_NV_external_sci_sync2[] 2031 * [[VUID-VkSemaphoreSubmitInfoKHR-semaphore-05094]] 2032 If pname:semaphore has a payload of stext:NvSciSyncObj, pname:value 2033 must: be calculated by application via <<NvSciSync-extension-page, 2034 NvSciSync APIs>>. 2035endif::VK_NV_external_sci_sync,VK_NV_external_sci_sync2[] 2036 2037**** 2038 2039include::{generated}/validity/structs/VkSemaphoreSubmitInfo.adoc[] 2040-- 2041 2042[open,refpage='VkCommandBufferSubmitInfo',desc='Structure specifying a command buffer submission',type='structs',alias='VkCommandBufferSubmitInfoKHR'] 2043-- 2044The sname:VkCommandBufferSubmitInfo structure is defined as: 2045 2046include::{generated}/api/structs/VkCommandBufferSubmitInfo.adoc[] 2047 2048ifdef::VK_KHR_synchronization2[] 2049or the equivalent 2050 2051include::{generated}/api/structs/VkCommandBufferSubmitInfoKHR.adoc[] 2052endif::VK_KHR_synchronization2[] 2053 2054 * pname:sType is a elink:VkStructureType value identifying this structure. 2055 * pname:pNext is `NULL` or a pointer to a structure extending this 2056 structure. 2057 * pname:commandBuffer is a slink:VkCommandBuffer to be submitted for 2058 execution. 2059 * pname:deviceMask is a bitmask indicating which devices in a device group 2060 execute the command buffer. 2061 A pname:deviceMask of `0` is equivalent to setting all bits 2062 corresponding to valid devices in the group to `1`. 2063 2064.Valid Usage 2065**** 2066 * [[VUID-VkCommandBufferSubmitInfo-commandBuffer-03890]] 2067 pname:commandBuffer must: not have been allocated with 2068 ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 2069ifdef::VK_KHR_device_group_creation,VK_VERSION_1_1[] 2070 * [[VUID-VkCommandBufferSubmitInfo-deviceMask-03891]] 2071 If pname:deviceMask is not `0`, it must: be a valid device mask 2072endif::VK_KHR_device_group_creation,VK_VERSION_1_1[] 2073**** 2074 2075include::{generated}/validity/structs/VkCommandBufferSubmitInfo.adoc[] 2076-- 2077endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 2078 2079[open,refpage='vkQueueSubmit',desc='Submits a sequence of semaphores or command buffers to a queue',type='protos'] 2080-- 2081 2082:refpage: vkQueueSubmit 2083 2084To submit command buffers to a queue, call: 2085 2086include::{generated}/api/protos/vkQueueSubmit.adoc[] 2087 2088 * pname:queue is the queue that the command buffers will be submitted to. 2089 * pname:submitCount is the number of elements in the pname:pSubmits array. 2090 * pname:pSubmits is a pointer to an array of slink:VkSubmitInfo 2091 structures, each specifying a command buffer submission batch. 2092 * pname:fence is an optional: handle to a fence to be signaled once all 2093 submitted command buffers have completed execution. 2094 If pname:fence is not dlink:VK_NULL_HANDLE, it defines a 2095 <<synchronization-fences-signaling, fence signal operation>>. 2096 2097fname:vkQueueSubmit is a <<devsandqueues-submission,queue submission 2098command>>, with each batch defined by an element of pname:pSubmits. 2099Batches begin execution in the order they appear in pname:pSubmits, but may: 2100complete out of order. 2101 2102Fence and semaphore operations submitted with flink:vkQueueSubmit have 2103additional ordering constraints compared to other submission commands, with 2104dependencies involving previous and subsequent queue operations. 2105Information about these additional constraints can be found in the 2106<<synchronization-semaphores, semaphore>> and <<synchronization-fences, 2107fence>> sections of <<synchronization, the synchronization chapter>>. 2108 2109Details on the interaction of pname:pWaitDstStageMask with synchronization 2110are described in the <<synchronization-semaphores-waiting, semaphore wait 2111operation>> section of <<synchronization, the synchronization chapter>>. 2112 2113The order that batches appear in pname:pSubmits is used to determine 2114<<synchronization-submission-order, submission order>>, and thus all the 2115<<synchronization-implicit, implicit ordering guarantees>> that respect it. 2116Other than these implicit ordering guarantees and any <<synchronization, 2117explicit synchronization primitives>>, these batches may: overlap or 2118otherwise execute out of order. 2119 2120If any command buffer submitted to this queue is in the 2121<<commandbuffers-lifecycle, executable state>>, it is moved to the 2122<<commandbuffers-lifecycle, pending state>>. 2123Once execution of all submissions of a command buffer complete, it moves 2124from the <<commandbuffers-lifecycle, pending state>>, back to the 2125<<commandbuffers-lifecycle, executable state>>. 2126If a command buffer was recorded with the 2127ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves to 2128the <<commandbuffers-lifecycle, invalid state>>. 2129 2130If fname:vkQueueSubmit fails, it may: return 2131ename:VK_ERROR_OUT_OF_HOST_MEMORY or ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 2132If it does, the implementation must: ensure that the state and contents of 2133any resources or synchronization primitives referenced by the submitted 2134command buffers and any semaphores referenced by pname:pSubmits is 2135unaffected by the call or its failure. 2136If fname:vkQueueSubmit fails in such a way that the implementation is unable 2137to make that guarantee, the implementation must: return 2138ename:VK_ERROR_DEVICE_LOST. 2139See <<devsandqueues-lost-device,Lost Device>>. 2140 2141include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 2142 2143.Valid Usage 2144**** 2145 * [[VUID-vkQueueSubmit-fence-00063]] 2146 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be 2147 unsignaled 2148 * [[VUID-vkQueueSubmit-fence-00064]] 2149 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be 2150 associated with any other queue command that has not yet completed 2151 execution on that queue 2152 * [[VUID-vkQueueSubmit-pCommandBuffers-00065]] 2153 Any calls to flink:vkCmdSetEvent, flink:vkCmdResetEvent or 2154 flink:vkCmdWaitEvents that have been recorded into any of the command 2155 buffer elements of the pname:pCommandBuffers member of any element of 2156 pname:pSubmits, must: not reference any slink:VkEvent that is referenced 2157 by any of those commands in a command buffer that has been submitted to 2158 another queue and is still in the _pending state_ 2159 * [[VUID-vkQueueSubmit-pWaitDstStageMask-00066]] 2160 Any stage flag included in any element of the pname:pWaitDstStageMask 2161 member of any element of pname:pSubmits must: be a pipeline stage 2162 supported by one of the capabilities of pname:queue, as specified in the 2163 <<synchronization-pipeline-stages-supported, table of supported pipeline 2164 stages>> 2165 * [[VUID-vkQueueSubmit-pSignalSemaphores-00067]] 2166 Each binary semaphore element of the pname:pSignalSemaphores member of 2167 any element of pname:pSubmits must: be unsignaled when the semaphore 2168 signal operation it defines is executed on the device 2169 * [[VUID-vkQueueSubmit-pWaitSemaphores-00068]] 2170 When a semaphore wait operation referring to a binary semaphore defined 2171 by any element of the pname:pWaitSemaphores member of any element of 2172 pname:pSubmits executes on pname:queue, there must: be no other queues 2173 waiting on the same semaphore 2174 * [[VUID-vkQueueSubmit-pWaitSemaphores-03238]] 2175 All elements of the pname:pWaitSemaphores member of all elements of 2176 pname:pSubmits 2177ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2178 created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY 2179endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2180 must: reference a semaphore signal operation that has been submitted for 2181 execution and any <<synchronization-semaphores-signaling, semaphore 2182 signal operations>> on which it depends must: have also been submitted 2183 for execution 2184 * [[VUID-vkQueueSubmit-pCommandBuffers-00070]] 2185 Each element of the pname:pCommandBuffers member of each element of 2186 pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or 2187 executable state>> 2188 * [[VUID-vkQueueSubmit-pCommandBuffers-00071]] 2189 If any element of the pname:pCommandBuffers member of any element of 2190 pname:pSubmits was not recorded with the 2191 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 2192 the <<commandbuffers-lifecycle, pending state>> 2193 * [[VUID-vkQueueSubmit-pCommandBuffers-00072]] 2194 Any <<commandbuffers-secondary, secondary command buffers recorded>> 2195 into any element of the pname:pCommandBuffers member of any element of 2196 pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or 2197 executable state>> 2198 * [[VUID-vkQueueSubmit-pCommandBuffers-00073]] 2199 If any <<commandbuffers-secondary, secondary command buffers recorded>> 2200 into any element of the pname:pCommandBuffers member of any element of 2201 pname:pSubmits was not recorded with the 2202 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 2203 the <<commandbuffers-lifecycle, pending state>> 2204 * [[VUID-vkQueueSubmit-pCommandBuffers-00074]] 2205 Each element of the pname:pCommandBuffers member of each element of 2206 pname:pSubmits must: have been allocated from a sname:VkCommandPool that 2207 was created for the same queue family pname:queue belongs to 2208 * [[VUID-vkQueueSubmit-pSubmits-02207]] 2209 If any element of pname:pSubmits->pCommandBuffers includes a 2210 <<synchronization-queue-transfers-acquire, Queue Family Transfer Acquire 2211 Operation>>, there must: exist a previously submitted 2212 <<synchronization-queue-transfers-release, Queue Family Transfer Release 2213 Operation>> on a queue in the queue family identified by the acquire 2214 operation, with parameters matching the acquire operation as defined in 2215 the definition of such <<synchronization-queue-transfers-acquire, 2216 acquire operations>>, and which happens-before the acquire operation 2217ifdef::VK_KHR_performance_query[] 2218 * [[VUID-vkQueueSubmit-pCommandBuffers-03220]] 2219 If a command recorded into any element of pname:pCommandBuffers was a 2220 flink:vkCmdBeginQuery whose pname:queryPool was created with a 2221 pname:queryType of ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the 2222 <<profiling-lock, profiling lock>> must: have been held continuously on 2223 the sname:VkDevice that pname:queue was retrieved from, throughout 2224 recording of those command buffers 2225endif::VK_KHR_performance_query[] 2226 * [[VUID-vkQueueSubmit-pSubmits-02808]] 2227 Any resource created with ename:VK_SHARING_MODE_EXCLUSIVE that is read 2228 by an operation specified by pname:pSubmits must: not be owned by any 2229 queue family other than the one which pname:queue belongs to, at the 2230 time it is executed 2231 * [[VUID-vkQueueSubmit-pSubmits-04626]] 2232 Any resource created with ename:VK_SHARING_MODE_CONCURRENT that is 2233 accessed by an operation specified by pname:pSubmits must: have included 2234 the queue family of pname:queue at resource creation time 2235ifdef::VK_VERSION_1_1[] 2236 * [[VUID-vkQueueSubmit-queue-06448]] 2237 If pname:queue was not created with 2238 ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, there must: be no element of 2239 pname:pSubmits that includes an slink:VkProtectedSubmitInfo structure in 2240 its pname:pNext chain with pname:protectedSubmit equal to ename:VK_TRUE 2241endif::VK_VERSION_1_1[] 2242**** 2243 2244include::{generated}/validity/protos/vkQueueSubmit.adoc[] 2245-- 2246 2247[open,refpage='VkSubmitInfo',desc='Structure specifying a queue submit operation',type='structs'] 2248-- 2249:refpage: VkSubmitInfo 2250The sname:VkSubmitInfo structure is defined as: 2251 2252include::{generated}/api/structs/VkSubmitInfo.adoc[] 2253 2254 * pname:sType is a elink:VkStructureType value identifying this structure. 2255 * pname:pNext is `NULL` or a pointer to a structure extending this 2256 structure. 2257 * pname:waitSemaphoreCount is the number of semaphores upon which to wait 2258 before executing the command buffers for the batch. 2259 * pname:pWaitSemaphores is a pointer to an array of slink:VkSemaphore 2260 handles upon which to wait before the command buffers for this batch 2261 begin execution. 2262 If semaphores to wait on are provided, they define a 2263 <<synchronization-semaphores-waiting, semaphore wait operation>>. 2264 * pname:pWaitDstStageMask is a pointer to an array of pipeline stages at 2265 which each corresponding semaphore wait will occur. 2266 * pname:commandBufferCount is the number of command buffers to execute in 2267 the batch. 2268 * pname:pCommandBuffers is a pointer to an array of slink:VkCommandBuffer 2269 handles to execute in the batch. 2270 * pname:signalSemaphoreCount is the number of semaphores to be signaled 2271 once the commands specified in pname:pCommandBuffers have completed 2272 execution. 2273 * pname:pSignalSemaphores is a pointer to an array of slink:VkSemaphore 2274 handles which will be signaled when the command buffers for this batch 2275 have completed execution. 2276 If semaphores to be signaled are provided, they define a 2277 <<synchronization-semaphores-signaling, semaphore signal operation>>. 2278 2279The order that command buffers appear in pname:pCommandBuffers is used to 2280determine <<synchronization-submission-order, submission order>>, and thus 2281all the <<synchronization-implicit, implicit ordering guarantees>> that 2282respect it. 2283Other than these implicit ordering guarantees and any <<synchronization, 2284explicit synchronization primitives>>, these command buffers may: overlap or 2285otherwise execute out of order. 2286 2287 2288.Valid Usage 2289**** 2290:stageMaskName: pWaitDstStageMask 2291include::{chapters}/commonvalidity/stage_mask_common.adoc[] 2292 2293 * [[VUID-VkSubmitInfo-pCommandBuffers-00075]] 2294 Each element of pname:pCommandBuffers must: not have been allocated with 2295 ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 2296 * [[VUID-VkSubmitInfo-pWaitDstStageMask-00078]] 2297 Each element of pname:pWaitDstStageMask must: not include 2298 ename:VK_PIPELINE_STAGE_HOST_BIT 2299ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2300 * [[VUID-VkSubmitInfo-pWaitSemaphores-03239]] 2301 If any element of pname:pWaitSemaphores or pname:pSignalSemaphores was 2302 created with a elink:VkSemaphoreType of 2303 ename:VK_SEMAPHORE_TYPE_TIMELINE, then the pname:pNext chain must: 2304 include a slink:VkTimelineSemaphoreSubmitInfo structure 2305 * [[VUID-VkSubmitInfo-pNext-03240]] 2306 If the pname:pNext chain of this structure includes a 2307 slink:VkTimelineSemaphoreSubmitInfo structure and any element of 2308 pname:pWaitSemaphores was created with a elink:VkSemaphoreType of 2309 ename:VK_SEMAPHORE_TYPE_TIMELINE, then its pname:waitSemaphoreValueCount 2310 member must: equal pname:waitSemaphoreCount 2311 * [[VUID-VkSubmitInfo-pNext-03241]] 2312 If the pname:pNext chain of this structure includes a 2313 slink:VkTimelineSemaphoreSubmitInfo structure and any element of 2314 pname:pSignalSemaphores was created with a elink:VkSemaphoreType of 2315 ename:VK_SEMAPHORE_TYPE_TIMELINE, then its 2316 pname:signalSemaphoreValueCount member must: equal 2317 pname:signalSemaphoreCount 2318 * [[VUID-VkSubmitInfo-pSignalSemaphores-03242]] 2319 For each element of pname:pSignalSemaphores created with a 2320 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 2321 corresponding element of 2322 slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: 2323 have a value greater than the current value of the semaphore when the 2324 <<synchronization-semaphores-signaling,semaphore signal operation>> is 2325 executed 2326 * [[VUID-VkSubmitInfo-pWaitSemaphores-03243]] 2327 For each element of pname:pWaitSemaphores created with a 2328 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 2329 corresponding element of 2330 slink:VkTimelineSemaphoreSubmitInfo::pname:pWaitSemaphoreValues must: 2331 have a value which does not differ from the current value of the 2332 semaphore or the value of any outstanding semaphore wait or signal 2333 operation on that semaphore by more than 2334 <<limits-maxTimelineSemaphoreValueDifference, 2335 pname:maxTimelineSemaphoreValueDifference>> 2336 * [[VUID-VkSubmitInfo-pSignalSemaphores-03244]] 2337 For each element of pname:pSignalSemaphores created with a 2338 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 2339 corresponding element of 2340 slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: 2341 have a value which does not differ from the current value of the 2342 semaphore or the value of any outstanding semaphore wait or signal 2343 operation on that semaphore by more than 2344 <<limits-maxTimelineSemaphoreValueDifference, 2345 pname:maxTimelineSemaphoreValueDifference>> 2346endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2347ifdef::VK_VERSION_1_1[] 2348 * [[VUID-VkSubmitInfo-pNext-04120]] 2349 If the pname:pNext chain of this structure does not include a 2350 sname:VkProtectedSubmitInfo structure with pname:protectedSubmit set to 2351 ename:VK_TRUE, then each element of the pname:pCommandBuffers array 2352 must: be an unprotected command buffer 2353 * [[VUID-VkSubmitInfo-pNext-04148]] 2354 If the pname:pNext chain of this structure includes a 2355 sname:VkProtectedSubmitInfo structure with pname:protectedSubmit set to 2356 ename:VK_TRUE, then each element of the pname:pCommandBuffers array 2357 must: be a protected command buffer 2358endif::VK_VERSION_1_1[] 2359ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 2360 * [[VUID-VkSubmitInfo-pCommandBuffers-06193]] 2361 If pname:pCommandBuffers contains any <<renderpass-suspension,resumed 2362 render pass instances>>, they must: be suspended by a render pass 2363 instance earlier in submission order within pname:pCommandBuffers 2364 * [[VUID-VkSubmitInfo-pCommandBuffers-06014]] 2365 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2366 render pass instances>>, they must: be resumed by a render pass instance 2367 later in submission order within pname:pCommandBuffers 2368 * [[VUID-VkSubmitInfo-pCommandBuffers-06015]] 2369 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2370 render pass instances>>, there must: be no action or synchronization 2371 commands executed in a primary or <<commandbuffers-secondary, 2372 secondary>> command buffer between that render pass instance and the 2373 render pass instance that resumes it 2374 * [[VUID-VkSubmitInfo-pCommandBuffers-06016]] 2375 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2376 render pass instances>>, there must: be no render pass instances between 2377 that render pass instance and the render pass instance that resumes it 2378ifdef::VK_EXT_sample_locations[] 2379 * [[VUID-VkSubmitInfo-variableSampleLocations-06017]] 2380 If the <<limits-variableSampleLocations, pname:variableSampleLocations>> 2381 limit is not supported, and any element of pname:pCommandBuffers 2382 contains any <<renderpass-suspension, suspended render pass instances>>, 2383 where a graphics pipeline has been bound, any pipelines bound in the 2384 render pass instance that resumes it, or any subsequent render pass 2385 instances that resume from that one and so on, must: use the same sample 2386 locations 2387endif::VK_EXT_sample_locations[] 2388endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 2389**** 2390 2391include::{generated}/validity/structs/VkSubmitInfo.adoc[] 2392-- 2393 2394ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2395[open,refpage='VkTimelineSemaphoreSubmitInfo',desc='Structure specifying signal and wait values for timeline semaphores',type='structs',alias='VkTimelineSemaphoreSubmitInfoKHR'] 2396-- 2397To specify the values to use when waiting for and signaling semaphores 2398created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE, 2399add a slink:VkTimelineSemaphoreSubmitInfo structure to the pname:pNext chain 2400of the slink:VkSubmitInfo structure when using flink:vkQueueSubmit 2401ifndef::VKSC_VERSION_1_0[or the slink:VkBindSparseInfo structure when using flink:vkQueueBindSparse] 2402. 2403The sname:VkTimelineSemaphoreSubmitInfo structure is defined as: 2404 2405include::{generated}/api/structs/VkTimelineSemaphoreSubmitInfo.adoc[] 2406 2407ifdef::VK_KHR_timeline_semaphore[] 2408or the equivalent 2409 2410include::{generated}/api/structs/VkTimelineSemaphoreSubmitInfoKHR.adoc[] 2411endif::VK_KHR_timeline_semaphore[] 2412 2413 * pname:sType is a elink:VkStructureType value identifying this structure. 2414 * pname:pNext is `NULL` or a pointer to a structure extending this 2415 structure. 2416 * pname:waitSemaphoreValueCount is the number of semaphore wait values 2417 specified in pname:pWaitSemaphoreValues. 2418 * pname:pWaitSemaphoreValues is a pointer to an array of 2419 pname:waitSemaphoreValueCount values for the corresponding semaphores in 2420 slink:VkSubmitInfo::pname:pWaitSemaphores to wait for. 2421 * pname:signalSemaphoreValueCount is the number of semaphore signal values 2422 specified in pname:pSignalSemaphoreValues. 2423 * pname:pSignalSemaphoreValues is a pointer to an array 2424 pname:signalSemaphoreValueCount values for the corresponding semaphores 2425 in slink:VkSubmitInfo::pname:pSignalSemaphores to set when signaled. 2426 2427If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or 2428slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in 2429pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively was 2430not created with a elink:VkSemaphoreType of 2431ename:VK_SEMAPHORE_TYPE_TIMELINE, the implementation must: ignore the value 2432in the pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry. 2433 2434ifdef::VK_NV_external_sci_sync,VK_NV_external_sci_sync2[] 2435If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or 2436slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in 2437pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively was 2438created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE, 2439and has stext:NvSciSyncObj as the payload, the value in the 2440pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry must: be 2441calculated by application via <<NvSciSync-extension-page, NvSciSync APIs>>. 2442endif::VK_NV_external_sci_sync,VK_NV_external_sci_sync2[] 2443 2444include::{generated}/validity/structs/VkTimelineSemaphoreSubmitInfo.adoc[] 2445-- 2446endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2447 2448ifdef::VK_KHR_external_semaphore_win32[] 2449[open,refpage='VkD3D12FenceSubmitInfoKHR',desc='Structure specifying values for Direct3D 12 fence-backed semaphores',type='structs'] 2450-- 2451To specify the values to use when waiting for and signaling semaphores whose 2452<<synchronization-semaphores-importing,current payload>> refers to a 2453Direct3D 12 fence, add a slink:VkD3D12FenceSubmitInfoKHR structure to the 2454pname:pNext chain of the slink:VkSubmitInfo structure. 2455The sname:VkD3D12FenceSubmitInfoKHR structure is defined as: 2456 2457include::{generated}/api/structs/VkD3D12FenceSubmitInfoKHR.adoc[] 2458 2459 * pname:sType is a elink:VkStructureType value identifying this structure. 2460 * pname:pNext is `NULL` or a pointer to a structure extending this 2461 structure. 2462 * pname:waitSemaphoreValuesCount is the number of semaphore wait values 2463 specified in pname:pWaitSemaphoreValues. 2464 * pname:pWaitSemaphoreValues is a pointer to an array of 2465 pname:waitSemaphoreValuesCount values for the corresponding semaphores 2466 in slink:VkSubmitInfo::pname:pWaitSemaphores to wait for. 2467 * pname:signalSemaphoreValuesCount is the number of semaphore signal 2468 values specified in pname:pSignalSemaphoreValues. 2469 * pname:pSignalSemaphoreValues is a pointer to an array of 2470 pname:signalSemaphoreValuesCount values for the corresponding semaphores 2471 in slink:VkSubmitInfo::pname:pSignalSemaphores to set when signaled. 2472 2473If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or 2474slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in 2475pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively does 2476not currently have a <<synchronization-semaphores-payloads, payload>> 2477referring to a Direct3D 12 fence, the implementation must: ignore the value 2478in the pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry. 2479 2480ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2481[NOTE] 2482.Note 2483==== 2484As the introduction of the external semaphore handle type 2485ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT predates that of 2486timeline semaphores, support for importing semaphore payloads from external 2487handles of that type into semaphores created (implicitly or explicitly) with 2488a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY is preserved for 2489backwards compatibility. 2490However, applications should: prefer importing such handle types into 2491semaphores created with a elink:VkSemaphoreType of 2492ename:VK_SEMAPHORE_TYPE_TIMELINE, and use the 2493slink:VkTimelineSemaphoreSubmitInfo structure instead of the 2494sname:VkD3D12FenceSubmitInfoKHR structure to specify the values to use when 2495waiting for and signaling such semaphores. 2496==== 2497endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2498 2499.Valid Usage 2500**** 2501 * [[VUID-VkD3D12FenceSubmitInfoKHR-waitSemaphoreValuesCount-00079]] 2502 pname:waitSemaphoreValuesCount must: be the same value as 2503 sname:VkSubmitInfo::pname:waitSemaphoreCount, where this structure is in 2504 the pname:pNext chain of a sname:VkSubmitInfo structure 2505 * [[VUID-VkD3D12FenceSubmitInfoKHR-signalSemaphoreValuesCount-00080]] 2506 pname:signalSemaphoreValuesCount must: be the same value as 2507 sname:VkSubmitInfo::pname:signalSemaphoreCount, where this structure is 2508 in the pname:pNext chain of a sname:VkSubmitInfo structure 2509**** 2510 2511include::{generated}/validity/structs/VkD3D12FenceSubmitInfoKHR.adoc[] 2512-- 2513endif::VK_KHR_external_semaphore_win32[] 2514 2515ifdef::VK_KHR_win32_keyed_mutex[] 2516[open,refpage='VkWin32KeyedMutexAcquireReleaseInfoKHR',desc='Use the Windows keyed mutex mechanism to synchronize work',type='structs'] 2517-- 2518When submitting work that operates on memory imported from a Direct3D 11 2519resource to a queue, the keyed mutex mechanism may: be used in addition to 2520Vulkan semaphores to synchronize the work. 2521Keyed mutexes are a property of a properly created shareable Direct3D 11 2522resource. 2523They can: only be used if the imported resource was created with the 2524etext:D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX flag. 2525 2526To acquire keyed mutexes before submitted work and/or release them after, 2527add a slink:VkWin32KeyedMutexAcquireReleaseInfoKHR structure to the 2528pname:pNext chain of the slink:VkSubmitInfo structure. 2529 2530The sname:VkWin32KeyedMutexAcquireReleaseInfoKHR structure is defined as: 2531 2532include::{generated}/api/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.adoc[] 2533 2534 * pname:sType is a elink:VkStructureType value identifying this structure. 2535 * pname:pNext is `NULL` or a pointer to a structure extending this 2536 structure. 2537 * pname:acquireCount is the number of entries in the pname:pAcquireSyncs, 2538 pname:pAcquireKeys, and pname:pAcquireTimeouts arrays. 2539 * pname:pAcquireSyncs is a pointer to an array of slink:VkDeviceMemory 2540 objects which were imported from Direct3D 11 resources. 2541 * pname:pAcquireKeys is a pointer to an array of mutex key values to wait 2542 for prior to beginning the submitted work. 2543 Entries refer to the keyed mutex associated with the corresponding 2544 entries in pname:pAcquireSyncs. 2545 * pname:pAcquireTimeouts is a pointer to an array of timeout values, in 2546 millisecond units, for each acquire specified in pname:pAcquireKeys. 2547 * pname:releaseCount is the number of entries in the pname:pReleaseSyncs 2548 and pname:pReleaseKeys arrays. 2549 * pname:pReleaseSyncs is a pointer to an array of slink:VkDeviceMemory 2550 objects which were imported from Direct3D 11 resources. 2551 * pname:pReleaseKeys is a pointer to an array of mutex key values to set 2552 when the submitted work has completed. 2553 Entries refer to the keyed mutex associated with the corresponding 2554 entries in pname:pReleaseSyncs. 2555 2556.Valid Usage 2557**** 2558 * [[VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireSyncs-00081]] 2559 Each member of pname:pAcquireSyncs and pname:pReleaseSyncs must: be a 2560 device memory object imported by setting 2561 slink:VkImportMemoryWin32HandleInfoKHR::pname:handleType to 2562 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT or 2563 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT 2564**** 2565 2566include::{generated}/validity/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.adoc[] 2567-- 2568endif::VK_KHR_win32_keyed_mutex[] 2569 2570ifdef::VK_NV_win32_keyed_mutex[] 2571include::{chapters}/VK_NV_win32_keyed_mutex/keyed_mutex_submit.adoc[] 2572endif::VK_NV_win32_keyed_mutex[] 2573 2574ifdef::VK_VERSION_1_1[] 2575[open,refpage='VkProtectedSubmitInfo',desc='Structure indicating whether the submission is protected',type='structs'] 2576-- 2577If the pname:pNext chain of slink:VkSubmitInfo includes a 2578sname:VkProtectedSubmitInfo structure, then the structure indicates whether 2579the batch is protected. 2580The sname:VkProtectedSubmitInfo structure is defined as: 2581 2582include::{generated}/api/structs/VkProtectedSubmitInfo.adoc[] 2583 2584 * pname:protectedSubmit specifies whether the batch is protected. 2585 If pname:protectedSubmit is ename:VK_TRUE, the batch is protected. 2586 If pname:protectedSubmit is ename:VK_FALSE, the batch is unprotected. 2587 If the sname:VkSubmitInfo::pname:pNext chain does not include this 2588 structure, the batch is unprotected. 2589 2590include::{generated}/validity/structs/VkProtectedSubmitInfo.adoc[] 2591-- 2592endif::VK_VERSION_1_1[] 2593 2594ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2595[open,refpage='VkDeviceGroupSubmitInfo',desc='Structure indicating which physical devices execute semaphore operations and command buffers',type='structs'] 2596-- 2597If the pname:pNext chain of slink:VkSubmitInfo includes a 2598sname:VkDeviceGroupSubmitInfo structure, then that structure includes device 2599indices and masks specifying which physical devices execute semaphore 2600operations and command buffers. 2601 2602The sname:VkDeviceGroupSubmitInfo structure is defined as: 2603 2604include::{generated}/api/structs/VkDeviceGroupSubmitInfo.adoc[] 2605 2606ifdef::VK_KHR_device_group[] 2607or the equivalent 2608 2609include::{generated}/api/structs/VkDeviceGroupSubmitInfoKHR.adoc[] 2610endif::VK_KHR_device_group[] 2611 2612 * pname:sType is a elink:VkStructureType value identifying this structure. 2613 * pname:pNext is `NULL` or a pointer to a structure extending this 2614 structure. 2615 * pname:waitSemaphoreCount is the number of elements in the 2616 pname:pWaitSemaphoreDeviceIndices array. 2617 * pname:pWaitSemaphoreDeviceIndices is a pointer to an array of 2618 pname:waitSemaphoreCount device indices indicating which physical device 2619 executes the semaphore wait operation in the corresponding element of 2620 slink:VkSubmitInfo::pname:pWaitSemaphores. 2621 * pname:commandBufferCount is the number of elements in the 2622 pname:pCommandBufferDeviceMasks array. 2623 * pname:pCommandBufferDeviceMasks is a pointer to an array of 2624 pname:commandBufferCount device masks indicating which physical devices 2625 execute the command buffer in the corresponding element of 2626 slink:VkSubmitInfo::pname:pCommandBuffers. 2627 A physical device executes the command buffer if the corresponding bit 2628 is set in the mask. 2629 * pname:signalSemaphoreCount is the number of elements in the 2630 pname:pSignalSemaphoreDeviceIndices array. 2631 * pname:pSignalSemaphoreDeviceIndices is a pointer to an array of 2632 pname:signalSemaphoreCount device indices indicating which physical 2633 device executes the semaphore signal operation in the corresponding 2634 element of slink:VkSubmitInfo::pname:pSignalSemaphores. 2635 2636If this structure is not present, semaphore operations and command buffers 2637execute on device index zero. 2638 2639.Valid Usage 2640**** 2641 * [[VUID-VkDeviceGroupSubmitInfo-waitSemaphoreCount-00082]] 2642 pname:waitSemaphoreCount must: equal 2643 slink:VkSubmitInfo::pname:waitSemaphoreCount 2644 * [[VUID-VkDeviceGroupSubmitInfo-commandBufferCount-00083]] 2645 pname:commandBufferCount must: equal 2646 slink:VkSubmitInfo::pname:commandBufferCount 2647 * [[VUID-VkDeviceGroupSubmitInfo-signalSemaphoreCount-00084]] 2648 pname:signalSemaphoreCount must: equal 2649 slink:VkSubmitInfo::pname:signalSemaphoreCount 2650 * [[VUID-VkDeviceGroupSubmitInfo-pWaitSemaphoreDeviceIndices-00085]] 2651 All elements of pname:pWaitSemaphoreDeviceIndices and 2652 pname:pSignalSemaphoreDeviceIndices must: be valid device indices 2653 * [[VUID-VkDeviceGroupSubmitInfo-pCommandBufferDeviceMasks-00086]] 2654 All elements of pname:pCommandBufferDeviceMasks must: be valid device 2655 masks 2656**** 2657 2658include::{generated}/validity/structs/VkDeviceGroupSubmitInfo.adoc[] 2659-- 2660endif::VK_VERSION_1_1,VK_KHR_device_group[] 2661 2662ifdef::VK_KHR_performance_query[] 2663If the pname:pNext chain of slink:VkSubmitInfo includes a 2664slink:VkPerformanceQuerySubmitInfoKHR structure, then the structure 2665indicates which counter pass is active for the batch in that submit. 2666 2667[open,refpage='VkPerformanceQuerySubmitInfoKHR',desc='Structure indicating which counter pass index is active for performance queries',type='structs'] 2668-- 2669The sname:VkPerformanceQuerySubmitInfoKHR structure is defined as: 2670 2671include::{generated}/api/structs/VkPerformanceQuerySubmitInfoKHR.adoc[] 2672 2673 * pname:sType is a elink:VkStructureType value identifying this structure. 2674 * pname:pNext is `NULL` or a pointer to a structure extending this 2675 structure. 2676 * pname:counterPassIndex specifies which counter pass index is active. 2677 2678If the sname:VkSubmitInfo::pname:pNext chain does not include this 2679structure, the batch defaults to use counter pass index 0. 2680 2681.Valid Usage 2682**** 2683 * [[VUID-VkPerformanceQuerySubmitInfoKHR-counterPassIndex-03221]] 2684 pname:counterPassIndex must: be less than the number of counter passes 2685 required by any queries within the batch. 2686 The required number of counter passes for a performance query is 2687 obtained by calling 2688 flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR 2689**** 2690 2691include::{generated}/validity/structs/VkPerformanceQuerySubmitInfoKHR.adoc[] 2692-- 2693endif::VK_KHR_performance_query[] 2694 2695 2696[[commandbuffers-submission-progress]] 2697== Queue Forward Progress 2698 2699When using binary semaphores, the application must: ensure that command 2700buffer submissions will be able to complete without any subsequent 2701operations by the application on any queue. 2702After any call to fname:vkQueueSubmit (or other queue operation), for every 2703queued wait on a semaphore 2704ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2705created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY 2706endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2707there must: be a prior signal of that semaphore that will not be consumed by 2708a different wait on the semaphore. 2709 2710ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2711When using timeline semaphores, wait-before-signal behavior is well-defined 2712and applications can: submit work via fname:vkQueueSubmit defining a 2713<<synchronization-semaphores-waiting, timeline semaphore wait operation>> 2714before submitting a corresponding <<synchronization-semaphores-signaling, 2715semaphore signal operation>>. 2716For each <<synchronization-semaphores-waiting, timeline semaphore wait 2717operation>> defined by a call to fname:vkQueueSubmit, the application must: 2718ensure that a corresponding <<synchronization-semaphores-signaling, 2719semaphore signal operation>> is executed before forward progress can be 2720made. 2721endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2722 2723If a command buffer submission waits for any events to be signaled, the 2724application must: ensure that command buffer submissions will be able to 2725complete without any subsequent operations by the application. 2726Events signaled by the host must: be signaled before the command buffer 2727waits on those events. 2728 2729[NOTE] 2730.Note 2731==== 2732The ability for commands to wait on the host to set an events was originally 2733added to allow low-latency updates to resources between host and device. 2734However, to ensure quality of service, implementations would necessarily 2735detect extended stalls in execution and timeout after a short period. 2736As this period is not defined in the Vulkan specification, it is impossible 2737to correctly validate any application with any wait period. 2738Since the original users of this functionality were highly limited and 2739platform-specific, this functionality is now considered defunct and should 2740not be used. 2741==== 2742 2743 2744[[commandbuffers-secondary]] 2745== Secondary Command Buffer Execution 2746 2747[open,refpage='vkCmdExecuteCommands',desc='Execute a secondary command buffer from a primary command buffer',type='protos'] 2748-- 2749Secondary command buffers must: not be directly submitted to a queue. 2750To record a secondary command buffer to execute as part of a primary command 2751buffer, call: 2752 2753include::{generated}/api/protos/vkCmdExecuteCommands.adoc[] 2754 2755 * pname:commandBuffer is a handle to a primary command buffer that the 2756 secondary command buffers are executed in. 2757 * pname:commandBufferCount is the length of the pname:pCommandBuffers 2758 array. 2759 * pname:pCommandBuffers is a pointer to an array of 2760 pname:commandBufferCount secondary command buffer handles, which are 2761 recorded to execute in the primary command buffer in the order they are 2762 listed in the array. 2763 2764If any element of pname:pCommandBuffers was not recorded with the 2765ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, and it was recorded 2766into any other primary command buffer which is currently in the 2767<<commandbuffers-lifecycle, executable or recording state>>, that primary 2768command buffer becomes <<commandbuffers-lifecycle, invalid>>. 2769 2770ifdef::VK_EXT_nested_command_buffer[] 2771If the <<features-nestedCommandBuffer, pname:nestedCommandBuffer>> feature 2772is enabled it is valid usage for fname:vkCmdExecuteCommands to also be 2773recorded to a <<glossary, secondary command buffer>>. 2774endif::VK_EXT_nested_command_buffer[] 2775 2776.Valid Usage 2777**** 2778 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00088]] 2779 Each element of pname:pCommandBuffers must: have been allocated with a 2780 pname:level of ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 2781 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00089]] 2782 Each element of pname:pCommandBuffers must: be in the 2783 <<commandbuffers-lifecycle, pending or executable state>> 2784 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00091]] 2785 If any element of pname:pCommandBuffers was not recorded with the 2786 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not be 2787 in the <<commandbuffers-lifecycle, pending state>> 2788 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00092]] 2789 If any element of pname:pCommandBuffers was not recorded with the 2790 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not 2791 have already been recorded to pname:commandBuffer 2792 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00093]] 2793 If any element of pname:pCommandBuffers was not recorded with the 2794 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not 2795 appear more than once in pname:pCommandBuffers 2796 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00094]] 2797 Each element of pname:pCommandBuffers must: have been allocated from a 2798 sname:VkCommandPool that was created for the same queue family as the 2799 sname:VkCommandPool from which pname:commandBuffer was allocated 2800 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00096]] 2801 If fname:vkCmdExecuteCommands is being called within a render pass 2802 instance, each element of pname:pCommandBuffers must: have been recorded 2803 with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 2804 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00099]] 2805 If fname:vkCmdExecuteCommands is being called within a render pass 2806 instance, and any element of pname:pCommandBuffers was recorded with 2807 slink:VkCommandBufferInheritanceInfo::pname:framebuffer not equal to 2808 dlink:VK_NULL_HANDLE, that sname:VkFramebuffer must: match the 2809 sname:VkFramebuffer used in the current render pass instance 2810 * [[VUID-vkCmdExecuteCommands-contents-06018]] 2811 If fname:vkCmdExecuteCommands is being called within a render pass 2812 instance begun with flink:vkCmdBeginRenderPass, its pname:contents 2813 parameter must: have been set to 2814 ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS 2815ifdef::VK_EXT_nested_command_buffer[, or ename:VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXT] 2816 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06019]] 2817 If fname:vkCmdExecuteCommands is being called within a render pass 2818 instance begun with flink:vkCmdBeginRenderPass, each element of 2819 pname:pCommandBuffers must: have been recorded with 2820 slink:VkCommandBufferInheritanceInfo::pname:subpass set to the index of 2821 the subpass which the given command buffer will be executed in 2822 * [[VUID-vkCmdExecuteCommands-pBeginInfo-06020]] 2823 If fname:vkCmdExecuteCommands is being called within a render pass 2824 instance begun with flink:vkCmdBeginRenderPass, the render passes 2825 specified in the pname:pBeginInfo->pInheritanceInfo->renderPass members 2826 of the flink:vkBeginCommandBuffer commands used to begin recording each 2827 element of pname:pCommandBuffers must: be 2828 <<renderpass-compatibility,compatible>> with the current render pass 2829ifdef::VK_QCOM_render_pass_transform[] 2830 * [[VUID-vkCmdExecuteCommands-pNext-02865]] 2831 If fname:vkCmdExecuteCommands is being called within a render pass 2832 instance that included slink:VkRenderPassTransformBeginInfoQCOM in the 2833 pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of 2834 pname:pCommandBuffers must: have been recorded with 2835 slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM in the 2836 pname:pNext chain of slink:VkCommandBufferBeginInfo 2837 * [[VUID-vkCmdExecuteCommands-pNext-02866]] 2838 If fname:vkCmdExecuteCommands is being called within a render pass 2839 instance that included slink:VkRenderPassTransformBeginInfoQCOM in the 2840 pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of 2841 pname:pCommandBuffers must: have been recorded with 2842 slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM::pname:transform 2843 identical to slink:VkRenderPassTransformBeginInfoQCOM::pname:transform 2844 * [[VUID-vkCmdExecuteCommands-pNext-02867]] 2845 If fname:vkCmdExecuteCommands is being called within a render pass 2846 instance that included slink:VkRenderPassTransformBeginInfoQCOM in the 2847 pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of 2848 pname:pCommandBuffers must: have been recorded with 2849 slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM::pname:renderArea 2850 identical to slink:VkRenderPassBeginInfo::pname:renderArea 2851endif::VK_QCOM_render_pass_transform[] 2852 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00100]] 2853 If fname:vkCmdExecuteCommands is not being called within a render pass 2854 instance, each element of pname:pCommandBuffers must: not have been 2855 recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 2856 * [[VUID-vkCmdExecuteCommands-commandBuffer-00101]] 2857 If the <<features-inheritedQueries, pname:inheritedQueries>> feature is 2858 not enabled, pname:commandBuffer must: not have any queries 2859 <<queries-operation-active,active>> 2860 * [[VUID-vkCmdExecuteCommands-commandBuffer-00102]] 2861 If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query 2862 <<queries-operation-active,active>>, then each element of 2863 pname:pCommandBuffers must: have been recorded with 2864 sname:VkCommandBufferInheritanceInfo::pname:occlusionQueryEnable set to 2865 ename:VK_TRUE 2866 * [[VUID-vkCmdExecuteCommands-commandBuffer-00103]] 2867 If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query 2868 <<queries-operation-active,active>>, then each element of 2869 pname:pCommandBuffers must: have been recorded with 2870 sname:VkCommandBufferInheritanceInfo::pname:queryFlags having all bits 2871 set that are set for the query 2872 * [[VUID-vkCmdExecuteCommands-commandBuffer-00104]] 2873 If pname:commandBuffer has a ename:VK_QUERY_TYPE_PIPELINE_STATISTICS 2874 query <<queries-operation-active,active>>, then each element of 2875 pname:pCommandBuffers must: have been recorded with 2876 sname:VkCommandBufferInheritanceInfo::pname:pipelineStatistics having 2877 all bits set that are set in the sname:VkQueryPool the query uses 2878 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00105]] 2879 Each element of pname:pCommandBuffers must: not begin any query types 2880 that are <<queries-operation-active,active>> in pname:commandBuffer 2881 * [[VUID-vkCmdExecuteCommands-commandBuffer-07594]] 2882 pname:commandBuffer must: not have any queries other than 2883 ename:VK_QUERY_TYPE_OCCLUSION and 2884 ename:VK_QUERY_TYPE_PIPELINE_STATISTICS 2885 <<queries-operation-active,active>> 2886ifdef::VK_VERSION_1_1[] 2887 * [[VUID-vkCmdExecuteCommands-commandBuffer-01820]] 2888 If pname:commandBuffer is a protected command buffer and 2889 <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, 2890 each element of pname:pCommandBuffers must: be a protected command 2891 buffer 2892 * [[VUID-vkCmdExecuteCommands-commandBuffer-01821]] 2893 If pname:commandBuffer is an unprotected command buffer and 2894 <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, 2895 each element of pname:pCommandBuffers must: be an unprotected command 2896 buffer 2897endif::VK_VERSION_1_1[] 2898ifdef::VK_EXT_transform_feedback[] 2899 * [[VUID-vkCmdExecuteCommands-None-02286]] 2900 This command must: not be recorded when transform feedback is active 2901endif::VK_EXT_transform_feedback[] 2902 * [[VUID-vkCmdExecuteCommands-commandBuffer-06533]] 2903 If fname:vkCmdExecuteCommands is being called within a render pass 2904 instance and any recorded command in pname:commandBuffer in the current 2905 subpass will write to an image subresource as an attachment, commands 2906 recorded in elements of pname:pCommandBuffers must: not read from the 2907 memory backing that image subresource in any other way 2908 * [[VUID-vkCmdExecuteCommands-commandBuffer-06534]] 2909 If fname:vkCmdExecuteCommands is being called within a render pass 2910 instance and any recorded command in pname:commandBuffer in the current 2911 subpass will read from an image subresource used as an attachment in any 2912 way other than as an attachment, commands recorded in elements of 2913 pname:pCommandBuffers must: not write to that image subresource as an 2914 attachment 2915 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06535]] 2916 If fname:vkCmdExecuteCommands is being called within a render pass 2917 instance and any recorded command in a given element of 2918 pname:pCommandBuffers will write to an image subresource as an 2919 attachment, commands recorded in elements of pname:pCommandBuffers at a 2920 higher index must: not read from the memory backing that image 2921 subresource in any other way 2922 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06536]] 2923 If fname:vkCmdExecuteCommands is being called within a render pass 2924 instance and any recorded command in a given element of 2925 pname:pCommandBuffers will read from an image subresource used as an 2926 attachment in any way other than as an attachment, commands recorded in 2927 elements of pname:pCommandBuffers at a higher index must: not write to 2928 that image subresource as an attachment 2929ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 2930 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06021]] 2931 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2932 render pass instances>>, there must: be no action or synchronization 2933 commands between that render pass instance and any render pass instance 2934 that resumes it 2935 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06022]] 2936 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2937 render pass instances>>, there must: be no render pass instances between 2938 that render pass instance and any render pass instance that resumes it 2939ifdef::VK_EXT_sample_locations[] 2940 * [[VUID-vkCmdExecuteCommands-variableSampleLocations-06023]] 2941 If the <<limits-variableSampleLocations, pname:variableSampleLocations>> 2942 limit is not supported, and any element of pname:pCommandBuffers 2943 contains any <<renderpass-suspension, suspended render pass instances>>, 2944 where a graphics pipeline has been bound, any pipelines bound in the 2945 render pass instance that resumes it, or any subsequent render pass 2946 instances that resume from that one and so on, must: use the same sample 2947 locations 2948endif::VK_EXT_sample_locations[] 2949 * [[VUID-vkCmdExecuteCommands-flags-06024]] 2950 If fname:vkCmdExecuteCommands is being called within a render pass 2951 instance begun with flink:vkCmdBeginRendering, its 2952 slink:VkRenderingInfo::pname:flags parameter must: have included 2953 ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT 2954 * [[VUID-vkCmdExecuteCommands-pBeginInfo-06025]] 2955 If fname:vkCmdExecuteCommands is being called within a render pass 2956 instance begun with flink:vkCmdBeginRendering, the render passes 2957 specified in the pname:pBeginInfo->pInheritanceInfo->renderPass members 2958 of the flink:vkBeginCommandBuffer commands used to begin recording each 2959 element of pname:pCommandBuffers must: be dlink:VK_NULL_HANDLE 2960 * [[VUID-vkCmdExecuteCommands-flags-06026]] 2961 If fname:vkCmdExecuteCommands is being called within a render pass 2962 instance begun with flink:vkCmdBeginRendering, the pname:flags member of 2963 the slink:VkCommandBufferInheritanceRenderingInfo structure included in 2964 the pname:pNext chain of 2965 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2966 recording each element of pname:pCommandBuffers must: be equal to the 2967 slink:VkRenderingInfo::pname:flags parameter to 2968 flink:vkCmdBeginRendering, excluding 2969 ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT 2970 * [[VUID-vkCmdExecuteCommands-colorAttachmentCount-06027]] 2971 If fname:vkCmdExecuteCommands is being called within a render pass 2972 instance begun with flink:vkCmdBeginRendering, the 2973 pname:colorAttachmentCount member of the 2974 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 2975 pname:pNext chain of 2976 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2977 recording each element of pname:pCommandBuffers must: be equal to the 2978 slink:VkRenderingInfo::pname:colorAttachmentCount parameter to 2979 flink:vkCmdBeginRendering 2980 * [[VUID-vkCmdExecuteCommands-imageView-06028]] 2981 If fname:vkCmdExecuteCommands is being called within a render pass 2982 instance begun with flink:vkCmdBeginRendering, if the pname:imageView 2983 member of an element of the 2984 slink:VkRenderingInfo::pname:pColorAttachments parameter to 2985 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the corresponding 2986 element of the pname:pColorAttachmentFormats member of the 2987 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 2988 pname:pNext chain of 2989 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 2990 recording each element of pname:pCommandBuffers must: be equal to the 2991 format used to create that image view 2992 * [[VUID-vkCmdExecuteCommands-imageView-07606]] 2993 If fname:vkCmdExecuteCommands is being called within a render pass 2994 instance begun with flink:vkCmdBeginRendering, if the pname:imageView 2995 member of an element of the 2996 slink:VkRenderingInfo::pname:pColorAttachments parameter to 2997 flink:vkCmdBeginRendering is dlink:VK_NULL_HANDLE, the corresponding 2998 element of the pname:pColorAttachmentFormats member of the 2999 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 3000 pname:pNext chain of 3001 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3002 recording each element of pname:pCommandBuffers must: be 3003 ename:VK_FORMAT_UNDEFINED 3004 * [[VUID-vkCmdExecuteCommands-pDepthAttachment-06029]] 3005 If fname:vkCmdExecuteCommands is being called within a render pass 3006 instance begun with flink:vkCmdBeginRendering, if the 3007 slink:VkRenderingInfo::pname:pDepthAttachment->imageView parameter to 3008 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of the 3009 pname:depthAttachmentFormat member of the 3010 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 3011 pname:pNext chain of 3012 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3013 recording each element of pname:pCommandBuffers must: be equal to the 3014 format used to create that image view 3015 * [[VUID-vkCmdExecuteCommands-pStencilAttachment-06030]] 3016 If fname:vkCmdExecuteCommands is being called within a render pass 3017 instance begun with flink:vkCmdBeginRendering, if the 3018 slink:VkRenderingInfo::pname:pStencilAttachment->imageView parameter to 3019 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of the 3020 pname:stencilAttachmentFormat member of the 3021 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 3022 pname:pNext chain of 3023 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3024 recording each element of pname:pCommandBuffers must: be equal to the 3025 format used to create that image view 3026 * [[VUID-vkCmdExecuteCommands-pDepthAttachment-06774]] 3027 If fname:vkCmdExecuteCommands is being called within a render pass 3028 instance begun with flink:vkCmdBeginRendering and the 3029 slink:VkRenderingInfo::pname:pDepthAttachment->imageView parameter to 3030 flink:vkCmdBeginRendering was dlink:VK_NULL_HANDLE, the value of the 3031 pname:depthAttachmentFormat member of the 3032 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 3033 pname:pNext chain of 3034 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3035 recording each element of pname:pCommandBuffers must: be 3036 ename:VK_FORMAT_UNDEFINED 3037 * [[VUID-vkCmdExecuteCommands-pStencilAttachment-06775]] 3038 If fname:vkCmdExecuteCommands is being called within a render pass 3039 instance begun with flink:vkCmdBeginRendering and the 3040 slink:VkRenderingInfo::pname:pStencilAttachment->imageView parameter to 3041 flink:vkCmdBeginRendering was dlink:VK_NULL_HANDLE, the value of the 3042 pname:stencilAttachmentFormat member of the 3043 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 3044 pname:pNext chain of 3045 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3046 recording each element of pname:pCommandBuffers must: be 3047 ename:VK_FORMAT_UNDEFINED 3048ifdef::VK_KHR_multiview,VK_VERSION_1_1[] 3049 * [[VUID-vkCmdExecuteCommands-viewMask-06031]] 3050 If fname:vkCmdExecuteCommands is being called within a render pass 3051 instance begun with flink:vkCmdBeginRendering, the pname:viewMask member 3052 of the slink:VkCommandBufferInheritanceRenderingInfo structure included 3053 in the pname:pNext chain of 3054 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3055 recording each element of pname:pCommandBuffers must: be equal to the 3056 slink:VkRenderingInfo::pname:viewMask parameter to 3057 flink:vkCmdBeginRendering 3058endif::VK_KHR_multiview,VK_VERSION_1_1[] 3059ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 3060 * [[VUID-vkCmdExecuteCommands-pNext-06032]] 3061 If fname:vkCmdExecuteCommands is being called within a render pass 3062 instance begun with flink:vkCmdBeginRendering and the pname:pNext chain 3063 of slink:VkCommandBufferInheritanceInfo includes a 3064 slink:VkAttachmentSampleCountInfoAMD or 3065 slink:VkAttachmentSampleCountInfoNV structure, if the pname:imageView 3066 member of an element of the 3067 slink:VkRenderingInfo::pname:pColorAttachments parameter to 3068 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the corresponding 3069 element of the pname:pColorAttachmentSamples member of the 3070 slink:VkAttachmentSampleCountInfoAMD or 3071 slink:VkAttachmentSampleCountInfoNV structure included in the 3072 pname:pNext chain of 3073 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3074 recording each element of pname:pCommandBuffers must: be equal to the 3075 sample count used to create that image view 3076 * [[VUID-vkCmdExecuteCommands-pNext-06033]] 3077 If fname:vkCmdExecuteCommands is being called within a render pass 3078 instance begun with flink:vkCmdBeginRendering and the pname:pNext chain 3079 of slink:VkCommandBufferInheritanceInfo includes a 3080 slink:VkAttachmentSampleCountInfoAMD or 3081 slink:VkAttachmentSampleCountInfoNV structure, if the 3082 slink:VkRenderingInfo::pname:pDepthAttachment->imageView parameter to 3083 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of the 3084 pname:depthStencilAttachmentSamples member of the 3085 slink:VkAttachmentSampleCountInfoAMD or 3086 slink:VkAttachmentSampleCountInfoNV structure included in the 3087 pname:pNext chain of 3088 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3089 recording each element of pname:pCommandBuffers must: be equal to the 3090 sample count used to create that image view 3091 * [[VUID-vkCmdExecuteCommands-pNext-06034]] 3092 If fname:vkCmdExecuteCommands is being called within a render pass 3093 instance begun with flink:vkCmdBeginRendering and the pname:pNext chain 3094 of slink:VkCommandBufferInheritanceInfo includes a 3095 slink:VkAttachmentSampleCountInfoAMD or 3096 slink:VkAttachmentSampleCountInfoNV structure, if the 3097 slink:VkRenderingInfo::pname:pStencilAttachment->imageView parameter to 3098 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of the 3099 pname:depthStencilAttachmentSamples member of the 3100 slink:VkAttachmentSampleCountInfoAMD or 3101 slink:VkAttachmentSampleCountInfoNV structure included in the 3102 pname:pNext chain of 3103 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3104 recording each element of pname:pCommandBuffers must: be equal to the 3105 sample count used to create that image view 3106 * [[VUID-vkCmdExecuteCommands-pNext-06035]] 3107 If fname:vkCmdExecuteCommands is being called within a render pass 3108 instance begun with flink:vkCmdBeginRendering and the pname:pNext chain 3109 of slink:VkCommandBufferInheritanceInfo does not include a 3110 slink:VkAttachmentSampleCountInfoAMD or 3111 slink:VkAttachmentSampleCountInfoNV structure, if the pname:imageView 3112 member of an element of the 3113 slink:VkRenderingInfo::pname:pColorAttachments parameter to 3114 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of 3115 slink:VkCommandBufferInheritanceRenderingInfo::pname:rasterizationSamples 3116 must: be equal to the sample count used to create that image view 3117 * [[VUID-vkCmdExecuteCommands-pNext-06036]] 3118 If fname:vkCmdExecuteCommands is being called within a render pass 3119 instance begun with flink:vkCmdBeginRendering and the pname:pNext chain 3120 of slink:VkCommandBufferInheritanceInfo does not include a 3121 slink:VkAttachmentSampleCountInfoAMD or 3122 slink:VkAttachmentSampleCountInfoNV structure, if the 3123 slink:VkRenderingInfo::pname:pDepthAttachment->imageView parameter to 3124 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of 3125 slink:VkCommandBufferInheritanceRenderingInfo::pname:rasterizationSamples 3126 must: be equal to the sample count used to create that image view 3127 * [[VUID-vkCmdExecuteCommands-pNext-06037]] 3128 If fname:vkCmdExecuteCommands is being called within a render pass 3129 instance begun with flink:vkCmdBeginRendering and the pname:pNext chain 3130 of slink:VkCommandBufferInheritanceInfo does not include a 3131 slink:VkAttachmentSampleCountInfoAMD or 3132 slink:VkAttachmentSampleCountInfoNV structure, if the 3133 slink:VkRenderingInfo::pname:pStencilAttachment->imageView parameter to 3134 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of 3135 slink:VkCommandBufferInheritanceRenderingInfo::pname:rasterizationSamples 3136 must: be equal to the sample count used to create that image view 3137endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 3138ifdef::VK_ANDROID_external_format_resolve[] 3139 * [[VUID-vkCmdExecuteCommands-pNext-09299]] 3140 If fname:vkCmdExecuteCommands is being called within a render pass 3141 instance begun with flink:vkCmdBeginRendering, with any color attachment 3142 using a resolve mode of 3143 ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, the 3144 pname:pNext chain of slink:VkCommandBufferInheritanceInfo used to create 3145 each element of pname:pCommandBuffers must: include a 3146 slink:VkExternalFormatANDROID structure with a pname:externalFormat 3147 matching that used to create the resolve attachment in the render pass 3148 * [[VUID-vkCmdExecuteCommands-pNext-09300]] 3149 If fname:vkCmdExecuteCommands is being called within a render pass 3150 instance begun with flink:vkCmdBeginRendering with any color attachment 3151 using a resolve mode of 3152 ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, and the 3153 pname:pNext chain of slink:VkCommandBufferInheritanceInfo does not 3154 include a slink:VkAttachmentSampleCountInfoAMD or 3155 slink:VkAttachmentSampleCountInfoNV structure, the value of 3156 slink:VkCommandBufferInheritanceRenderingInfo::pname:rasterizationSamples 3157 must: be ename:VK_SAMPLE_COUNT_1_BIT 3158endif::VK_ANDROID_external_format_resolve[] 3159endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 3160 * [[VUID-vkCmdExecuteCommands-commandBuffer-09375]] 3161 pname:commandBuffer must: not be a <<glossary, secondary command 3162 buffer>> 3163ifdef::VK_EXT_nested_command_buffer[] 3164 unless the <<features-nestedCommandBuffer, pname:nestedCommandBuffer>> 3165 feature is enabled 3166 * [[VUID-vkCmdExecuteCommands-nestedCommandBuffer-09376]] 3167 If the <<features-nestedCommandBuffer, pname:nestedCommandBuffer>> 3168 feature is enabled, the <<glossary, command buffer nesting level>> of 3169 each element of pname:pCommandBuffers must: be less than 3170 <<limits-maxCommandBufferNestingLevel, 3171 pname:maxCommandBufferNestingLevel>> 3172 * [[VUID-vkCmdExecuteCommands-nestedCommandBufferRendering-09377]] 3173 If the <<features-nestedCommandBufferRendering, 3174 pname:nestedCommandBufferRendering>> feature is not enabled, and 3175 pname:commandBuffer is a <<glossary, secondary command buffer>>, 3176 pname:commandBuffer must: not have been recorded with 3177 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 3178 * [[VUID-vkCmdExecuteCommands-nestedCommandBufferSimultaneousUse-09378]] 3179 If the <<features-nestedCommandBufferSimultaneousUse, 3180 pname:nestedCommandBufferSimultaneousUse>> feature is not enabled, and 3181 pname:commandBuffer is a <<glossary, secondary command buffer>>, each 3182 element of pname:pCommandBuffers must: not have been recorded with 3183 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT 3184endif::VK_EXT_nested_command_buffer[] 3185**** 3186 3187include::{generated}/validity/protos/vkCmdExecuteCommands.adoc[] 3188-- 3189 3190ifdef::VK_EXT_nested_command_buffer[] 3191[[commandbuffers-nested]] 3192== Nested Command Buffers 3193 3194In addition to secondary command buffer execution from primary command 3195buffers, an implementation may: support <<glossary, nested command 3196buffers>>, which enable secondary command buffers to be executed from other 3197secondary command buffers. 3198If the <<features-nestedCommandBuffer, pname:nestedCommandBuffer>> feature 3199is enabled, the implementation supports <<glossary, nested command 3200buffers>>. 3201 3202Nested command buffer execution works the same as primary-to-secondary 3203execution, except that it is subject to some additional 3204implementation-defined limits. 3205 3206Each secondary command buffer has a <<glossary, command buffer nesting 3207level>>, which is determined at flink:vkEndCommandBuffer time and evaluated 3208at flink:vkCmdExecuteCommands time. 3209A secondary command buffer that executes no other secondary command buffers 3210has a <<glossary, command buffer nesting level>> of zero. 3211Otherwise, the <<glossary, command buffer nesting level>> of a secondary 3212command buffer is equal to the maximum nesting level of all secondary 3213command buffers executed by that command buffer plus one. 3214Some implementations may: have a limit on the maximum nesting level of 3215secondary command buffers that can: be recorded. 3216This limit is advertised in <<limits-maxCommandBufferNestingLevel, 3217pname:maxCommandBufferNestingLevel>>. 3218 3219If the <<features-nestedCommandBufferRendering, 3220pname:nestedCommandBufferRendering>> feature is enabled, the implementation 3221supports calling flink:vkCmdExecuteCommands inside secondary command buffers 3222recorded with ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT. 3223If the <<features-nestedCommandBufferSimultaneousUse, 3224pname:nestedCommandBufferSimultaneousUse>> feature is enabled, the 3225implementation supports calling flink:vkCmdExecuteCommands with secondary 3226command buffers recorded with 3227ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT. 3228 3229Whenever flink:vkCmdExecuteCommands is recorded inside a secondary command 3230buffer recorded with ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, 3231each member of pname:pCommandBuffers must: have been recorded with a 3232slink:VkCommandBufferBeginInfo with slink:VkCommandBufferInheritanceInfo 3233compatible with the slink:VkCommandBufferInheritanceInfo of the command 3234buffer into which the flink:vkCmdExecuteCommands call is being recorded. 3235The slink:VkCommandBufferInheritanceRenderingInfo structures are compatible 3236when the sname:VkCommandBufferInheritanceRenderingInfo::pname:renderpass are 3237<<renderpass-compatibility, compatible>>, or if they are 3238dlink:VK_NULL_HANDLE then the slink:VkCommandBufferInheritanceRenderingInfo 3239members match, and all other members of 3240sname:VkCommandBufferInheritanceRenderingInfo match. 3241This requirement applies recursively, down to the most nested command buffer 3242and up to the command buffer where the render pass was originally begun. 3243 3244endif::VK_EXT_nested_command_buffer[] 3245 3246ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 3247[[commandbuffers-devicemask]] 3248== Command Buffer Device Mask 3249 3250Each command buffer has a piece of state storing the current device mask of 3251the command buffer. 3252This mask controls which physical devices within the logical device all 3253subsequent commands will execute on, including state-setting commands, 3254action commands, and synchronization commands. 3255 3256ifndef::VK_NV_scissor_exclusive[] 3257Scissor 3258endif::VK_NV_scissor_exclusive[] 3259ifdef::VK_NV_scissor_exclusive[] 3260Scissor, exclusive scissor, 3261endif::VK_NV_scissor_exclusive[] 3262and viewport state 3263ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 3264(excluding the count of each) 3265endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 3266can: be set to different values on each physical device (only when set as 3267dynamic state), and each physical device will render using its local copy of 3268the state. 3269Other state is shared between physical devices, such that all physical 3270devices use the most recently set values for the state. 3271However, when recording an action command that uses a piece of state, the 3272most recent command that set that state must: have included all physical 3273devices that execute the action command in its current device mask. 3274 3275The command buffer's device mask is orthogonal to the 3276pname:pCommandBufferDeviceMasks member of slink:VkDeviceGroupSubmitInfo. 3277Commands only execute on a physical device if the device index is set in 3278both device masks. 3279 3280[open,refpage='VkDeviceGroupCommandBufferBeginInfo',desc='Set the initial device mask for a command buffer',type='structs'] 3281-- 3282If the pname:pNext chain of slink:VkCommandBufferBeginInfo includes a 3283sname:VkDeviceGroupCommandBufferBeginInfo structure, then that structure 3284includes an initial device mask for the command buffer. 3285 3286The sname:VkDeviceGroupCommandBufferBeginInfo structure is defined as: 3287 3288include::{generated}/api/structs/VkDeviceGroupCommandBufferBeginInfo.adoc[] 3289 3290ifdef::VK_KHR_device_group[] 3291or the equivalent 3292 3293include::{generated}/api/structs/VkDeviceGroupCommandBufferBeginInfoKHR.adoc[] 3294endif::VK_KHR_device_group[] 3295 3296 * pname:sType is a elink:VkStructureType value identifying this structure. 3297 * pname:pNext is `NULL` or a pointer to a structure extending this 3298 structure. 3299 * pname:deviceMask is the initial value of the command buffer's device 3300 mask. 3301 3302The initial device mask also acts as an upper bound on the set of devices 3303that can: ever be in the device mask in the command buffer. 3304 3305If this structure is not present, the initial value of a command buffer's 3306device mask is set to include all physical devices in the logical device 3307when the command buffer begins recording. 3308 3309.Valid Usage 3310**** 3311 * [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00106]] 3312 pname:deviceMask must: be a valid device mask value 3313 * [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00107]] 3314 pname:deviceMask must: not be zero 3315**** 3316 3317include::{generated}/validity/structs/VkDeviceGroupCommandBufferBeginInfo.adoc[] 3318-- 3319 3320[open,refpage='vkCmdSetDeviceMask',desc='Modify device mask of a command buffer',type='protos'] 3321-- 3322To update the current device mask of a command buffer, call: 3323 3324ifdef::VK_VERSION_1_1[] 3325include::{generated}/api/protos/vkCmdSetDeviceMask.adoc[] 3326endif::VK_VERSION_1_1[] 3327 3328ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] 3329 3330ifdef::VK_KHR_device_group[] 3331include::{generated}/api/protos/vkCmdSetDeviceMaskKHR.adoc[] 3332endif::VK_KHR_device_group[] 3333 3334 * pname:commandBuffer is command buffer whose current device mask is 3335 modified. 3336 * pname:deviceMask is the new value of the current device mask. 3337 3338pname:deviceMask is used to filter out subsequent commands from executing on 3339all physical devices whose bit indices are not set in the mask, except 3340commands beginning a render pass instance, commands transitioning to the 3341next subpass in the render pass instance, and commands ending a render pass 3342instance, which always execute on the set of physical devices whose bit 3343indices are included in the pname:deviceMask member of the 3344slink:VkDeviceGroupRenderPassBeginInfo structure passed to the command 3345beginning the corresponding render pass instance. 3346 3347.Valid Usage 3348**** 3349 * [[VUID-vkCmdSetDeviceMask-deviceMask-00108]] 3350 pname:deviceMask must: be a valid device mask value 3351 * [[VUID-vkCmdSetDeviceMask-deviceMask-00109]] 3352 pname:deviceMask must: not be zero 3353 * [[VUID-vkCmdSetDeviceMask-deviceMask-00110]] 3354 pname:deviceMask must: not include any set bits that were not in the 3355 slink:VkDeviceGroupCommandBufferBeginInfo::pname:deviceMask value when 3356 the command buffer began recording 3357 * [[VUID-vkCmdSetDeviceMask-deviceMask-00111]] 3358 If fname:vkCmdSetDeviceMask is called inside a render pass instance, 3359 pname:deviceMask must: not include any set bits that were not in the 3360 slink:VkDeviceGroupRenderPassBeginInfo::pname:deviceMask value when the 3361 render pass instance began recording 3362**** 3363 3364include::{generated}/validity/protos/vkCmdSetDeviceMask.adoc[] 3365-- 3366endif::VK_VERSION_1_1,VK_KHR_device_group[] 3367
