1// Copyright 2015-2024 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 slink: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[] 2073ifdef::VK_ARM_render_pass_striped[] 2074 * [[VUID-VkCommandBufferSubmitInfo-commandBuffer-09445]] 2075 If any render pass instance in pname:commandBuffer was recorded with a 2076 slink:VkRenderPassStripeBeginInfoARM structure in its pNext chain, a 2077 slink:VkRenderPassStripeSubmitInfoARM must: be included in the 2078 pname:pNext chain 2079 * [[VUID-VkCommandBufferSubmitInfo-pNext-09446]] 2080 If a slink:VkRenderPassStripeSubmitInfoARM is included in the 2081 pname:pNext chain, the value of 2082 slink:VkRenderPassStripeSubmitInfoARM::pname:stripeSemaphoreInfoCount 2083 must: be equal to the sum of the 2084 slink:VkRenderPassStripeBeginInfoARM::pname:stripeInfoCount parameters 2085 provided to render pass instances recorded in pname:commandBuffer 2086endif::VK_ARM_render_pass_striped[] 2087**** 2088 2089include::{generated}/validity/structs/VkCommandBufferSubmitInfo.adoc[] 2090-- 2091endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 2092 2093ifdef::VK_ARM_render_pass_striped[] 2094[open,refpage='VkRenderPassStripeSubmitInfoARM',desc='Structure specifying striped rendering submit information',type='structs'] 2095-- 2096The sname:VkRenderPassStripeSubmitInfoARM structure is defined as: 2097 2098include::{generated}/api/structs/VkRenderPassStripeSubmitInfoARM.adoc[] 2099 2100 * pname:sType is a elink:VkStructureType value identifying this structure. 2101 * pname:pNext is `NULL` or a pointer to a structure extending this 2102 structure. 2103 * pname:stripeSemaphoreInfoCount is the number of semaphores used to 2104 signal stripe completion in the render pass instances in the submitted 2105 command buffer. 2106 * pname:pStripeSemaphoreInfos is a pointer to an array of 2107 pname:stripeSemaphoreInfoCount slink:VkSemaphoreSubmitInfo structures 2108 describing the semaphores used to signal stripe completion. 2109 2110This structure can be included in the pname:pNext chain of 2111slink:VkCommandBufferSubmitInfo to provide a set of semaphores to be 2112signaled for each striped render pass instance. 2113 2114The elements of pname:pStripeSemaphoreInfos are mapped to render pass 2115instances in slink:VkCommandBufferSubmitInfo::pname:commandBuffer in 2116submission order and in stripe order within each render pass instance. 2117Each semaphore in pname:pStripeSemaphoreInfos is signaled when the 2118implementation has completed execution of the associated stripe. 2119In a render pass instance that has multiview enabled, the stripe includes 2120all views in the view mask. 2121In a render pass instance with pname:layerCount greater than 1, the stripe 2122includes all layers. 2123 2124.Valid Usage 2125**** 2126 * [[VUID-VkRenderPassStripeSubmitInfoARM-semaphore-09447]] 2127 The pname:semaphore member of each element of 2128 pname:pStripeSemaphoreInfos must: have been created with a 2129 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY 2130**** 2131 2132include::{generated}/validity/structs/VkRenderPassStripeSubmitInfoARM.adoc[] 2133-- 2134endif::VK_ARM_render_pass_striped[] 2135 2136[open,refpage='vkQueueSubmit',desc='Submits a sequence of semaphores or command buffers to a queue',type='protos'] 2137-- 2138 2139:refpage: vkQueueSubmit 2140 2141To submit command buffers to a queue, call: 2142 2143include::{generated}/api/protos/vkQueueSubmit.adoc[] 2144 2145 * pname:queue is the queue that the command buffers will be submitted to. 2146 * pname:submitCount is the number of elements in the pname:pSubmits array. 2147 * pname:pSubmits is a pointer to an array of slink:VkSubmitInfo 2148 structures, each specifying a command buffer submission batch. 2149 * pname:fence is an optional: handle to a fence to be signaled once all 2150 submitted command buffers have completed execution. 2151 If pname:fence is not dlink:VK_NULL_HANDLE, it defines a 2152 <<synchronization-fences-signaling, fence signal operation>>. 2153 2154fname:vkQueueSubmit is a <<devsandqueues-submission,queue submission 2155command>>, with each batch defined by an element of pname:pSubmits. 2156Batches begin execution in the order they appear in pname:pSubmits, but may: 2157complete out of order. 2158 2159Fence and semaphore operations submitted with flink:vkQueueSubmit have 2160additional ordering constraints compared to other submission commands, with 2161dependencies involving previous and subsequent queue operations. 2162Information about these additional constraints can be found in the 2163<<synchronization-semaphores, semaphore>> and <<synchronization-fences, 2164fence>> sections of <<synchronization, the synchronization chapter>>. 2165 2166Details on the interaction of pname:pWaitDstStageMask with synchronization 2167are described in the <<synchronization-semaphores-waiting, semaphore wait 2168operation>> section of <<synchronization, the synchronization chapter>>. 2169 2170The order that batches appear in pname:pSubmits is used to determine 2171<<synchronization-submission-order, submission order>>, and thus all the 2172<<synchronization-implicit, implicit ordering guarantees>> that respect it. 2173Other than these implicit ordering guarantees and any <<synchronization, 2174explicit synchronization primitives>>, these batches may: overlap or 2175otherwise execute out of order. 2176 2177If any command buffer submitted to this queue is in the 2178<<commandbuffers-lifecycle, executable state>>, it is moved to the 2179<<commandbuffers-lifecycle, pending state>>. 2180Once execution of all submissions of a command buffer complete, it moves 2181from the <<commandbuffers-lifecycle, pending state>>, back to the 2182<<commandbuffers-lifecycle, executable state>>. 2183If a command buffer was recorded with the 2184ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves to 2185the <<commandbuffers-lifecycle, invalid state>>. 2186 2187If fname:vkQueueSubmit fails, it may: return 2188ename:VK_ERROR_OUT_OF_HOST_MEMORY or ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 2189If it does, the implementation must: ensure that the state and contents of 2190any resources or synchronization primitives referenced by the submitted 2191command buffers and any semaphores referenced by pname:pSubmits is 2192unaffected by the call or its failure. 2193If fname:vkQueueSubmit fails in such a way that the implementation is unable 2194to make that guarantee, the implementation must: return 2195ename:VK_ERROR_DEVICE_LOST. 2196See <<devsandqueues-lost-device,Lost Device>>. 2197 2198include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 2199 2200.Valid Usage 2201**** 2202 * [[VUID-vkQueueSubmit-fence-00063]] 2203 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be 2204 unsignaled 2205 * [[VUID-vkQueueSubmit-fence-00064]] 2206 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be 2207 associated with any other queue command that has not yet completed 2208 execution on that queue 2209 * [[VUID-vkQueueSubmit-pCommandBuffers-00065]] 2210 Any calls to flink:vkCmdSetEvent, flink:vkCmdResetEvent or 2211 flink:vkCmdWaitEvents that have been recorded into any of the command 2212 buffer elements of the pname:pCommandBuffers member of any element of 2213 pname:pSubmits, must: not reference any slink:VkEvent that is referenced 2214 by any of those commands in a command buffer that has been submitted to 2215 another queue and is still in the _pending state_ 2216 * [[VUID-vkQueueSubmit-pWaitDstStageMask-00066]] 2217 Any stage flag included in any element of the pname:pWaitDstStageMask 2218 member of any element of pname:pSubmits must: be a pipeline stage 2219 supported by one of the capabilities of pname:queue, as specified in the 2220 <<synchronization-pipeline-stages-supported, table of supported pipeline 2221 stages>> 2222 * [[VUID-vkQueueSubmit-pSignalSemaphores-00067]] 2223 Each binary semaphore element of the pname:pSignalSemaphores member of 2224 any element of pname:pSubmits must: be unsignaled when the semaphore 2225 signal operation it defines is executed on the device 2226 * [[VUID-vkQueueSubmit-pWaitSemaphores-00068]] 2227 When a semaphore wait operation referring to a binary semaphore defined 2228 by any element of the pname:pWaitSemaphores member of any element of 2229 pname:pSubmits executes on pname:queue, there must: be no other queues 2230 waiting on the same semaphore 2231 * [[VUID-vkQueueSubmit-pWaitSemaphores-03238]] 2232 All elements of the pname:pWaitSemaphores member of all elements of 2233 pname:pSubmits 2234ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2235 created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY 2236endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2237 must: reference a semaphore signal operation that has been submitted for 2238 execution and any <<synchronization-semaphores-signaling, semaphore 2239 signal operations>> on which it depends must: have also been submitted 2240 for execution 2241 * [[VUID-vkQueueSubmit-pCommandBuffers-00070]] 2242 Each element of the pname:pCommandBuffers member of each element of 2243 pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or 2244 executable state>> 2245 * [[VUID-vkQueueSubmit-pCommandBuffers-00071]] 2246 If any element of the pname:pCommandBuffers member of any element of 2247 pname:pSubmits was not recorded with the 2248 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 2249 the <<commandbuffers-lifecycle, pending state>> 2250 * [[VUID-vkQueueSubmit-pCommandBuffers-00072]] 2251 Any <<commandbuffers-secondary, secondary command buffers recorded>> 2252 into any element of the pname:pCommandBuffers member of any element of 2253 pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or 2254 executable state>> 2255 * [[VUID-vkQueueSubmit-pCommandBuffers-00073]] 2256 If any <<commandbuffers-secondary, secondary command buffers recorded>> 2257 into any element of the pname:pCommandBuffers member of any element of 2258 pname:pSubmits was not recorded with the 2259 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 2260 the <<commandbuffers-lifecycle, pending state>> 2261 * [[VUID-vkQueueSubmit-pCommandBuffers-00074]] 2262 Each element of the pname:pCommandBuffers member of each element of 2263 pname:pSubmits must: have been allocated from a sname:VkCommandPool that 2264 was created for the same queue family pname:queue belongs to 2265 * [[VUID-vkQueueSubmit-pSubmits-02207]] 2266 If any element of pname:pSubmits->pCommandBuffers includes a 2267 <<synchronization-queue-transfers-acquire, Queue Family Transfer Acquire 2268 Operation>>, there must: exist a previously submitted 2269 <<synchronization-queue-transfers-release, Queue Family Transfer Release 2270 Operation>> on a queue in the queue family identified by the acquire 2271 operation, with parameters matching the acquire operation as defined in 2272 the definition of such <<synchronization-queue-transfers-acquire, 2273 acquire operations>>, and which happens-before the acquire operation 2274ifdef::VK_KHR_performance_query[] 2275 * [[VUID-vkQueueSubmit-pCommandBuffers-03220]] 2276 If a command recorded into any element of pname:pCommandBuffers was a 2277 flink:vkCmdBeginQuery whose pname:queryPool was created with a 2278 pname:queryType of ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the 2279 <<profiling-lock, profiling lock>> must: have been held continuously on 2280 the sname:VkDevice that pname:queue was retrieved from, throughout 2281 recording of those command buffers 2282endif::VK_KHR_performance_query[] 2283 * [[VUID-vkQueueSubmit-pSubmits-02808]] 2284 Any resource created with ename:VK_SHARING_MODE_EXCLUSIVE that is read 2285 by an operation specified by pname:pSubmits must: not be owned by any 2286 queue family other than the one which pname:queue belongs to, at the 2287 time it is executed 2288 * [[VUID-vkQueueSubmit-pSubmits-04626]] 2289 Any resource created with ename:VK_SHARING_MODE_CONCURRENT that is 2290 accessed by an operation specified by pname:pSubmits must: have included 2291 the queue family of pname:queue at resource creation time 2292ifdef::VK_VERSION_1_1[] 2293 * [[VUID-vkQueueSubmit-queue-06448]] 2294 If pname:queue was not created with 2295 ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, there must: be no element of 2296 pname:pSubmits that includes an slink:VkProtectedSubmitInfo structure in 2297 its pname:pNext chain with pname:protectedSubmit equal to ename:VK_TRUE 2298endif::VK_VERSION_1_1[] 2299**** 2300 2301include::{generated}/validity/protos/vkQueueSubmit.adoc[] 2302-- 2303 2304[open,refpage='VkSubmitInfo',desc='Structure specifying a queue submit operation',type='structs'] 2305-- 2306:refpage: VkSubmitInfo 2307The sname:VkSubmitInfo structure is defined as: 2308 2309include::{generated}/api/structs/VkSubmitInfo.adoc[] 2310 2311 * pname:sType is a elink:VkStructureType value identifying this structure. 2312 * pname:pNext is `NULL` or a pointer to a structure extending this 2313 structure. 2314 * pname:waitSemaphoreCount is the number of semaphores upon which to wait 2315 before executing the command buffers for the batch. 2316 * pname:pWaitSemaphores is a pointer to an array of slink:VkSemaphore 2317 handles upon which to wait before the command buffers for this batch 2318 begin execution. 2319 If semaphores to wait on are provided, they define a 2320 <<synchronization-semaphores-waiting, semaphore wait operation>>. 2321 * pname:pWaitDstStageMask is a pointer to an array of pipeline stages at 2322 which each corresponding semaphore wait will occur. 2323 * pname:commandBufferCount is the number of command buffers to execute in 2324 the batch. 2325 * pname:pCommandBuffers is a pointer to an array of slink:VkCommandBuffer 2326 handles to execute in the batch. 2327 * pname:signalSemaphoreCount is the number of semaphores to be signaled 2328 once the commands specified in pname:pCommandBuffers have completed 2329 execution. 2330 * pname:pSignalSemaphores is a pointer to an array of slink:VkSemaphore 2331 handles which will be signaled when the command buffers for this batch 2332 have completed execution. 2333 If semaphores to be signaled are provided, they define a 2334 <<synchronization-semaphores-signaling, semaphore signal operation>>. 2335 2336The order that command buffers appear in pname:pCommandBuffers is used to 2337determine <<synchronization-submission-order, submission order>>, and thus 2338all the <<synchronization-implicit, implicit ordering guarantees>> that 2339respect it. 2340Other than these implicit ordering guarantees and any <<synchronization, 2341explicit synchronization primitives>>, these command buffers may: overlap or 2342otherwise execute out of order. 2343 2344 2345.Valid Usage 2346**** 2347:stageMaskName: pWaitDstStageMask 2348include::{chapters}/commonvalidity/stage_mask_common.adoc[] 2349 2350 * [[VUID-VkSubmitInfo-pCommandBuffers-00075]] 2351 Each element of pname:pCommandBuffers must: not have been allocated with 2352 ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 2353 * [[VUID-VkSubmitInfo-pWaitDstStageMask-00078]] 2354 Each element of pname:pWaitDstStageMask must: not include 2355 ename:VK_PIPELINE_STAGE_HOST_BIT 2356ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2357 * [[VUID-VkSubmitInfo-pWaitSemaphores-03239]] 2358 If any element of pname:pWaitSemaphores or pname:pSignalSemaphores was 2359 created with a elink:VkSemaphoreType of 2360 ename:VK_SEMAPHORE_TYPE_TIMELINE, then the pname:pNext chain must: 2361 include a slink:VkTimelineSemaphoreSubmitInfo structure 2362 * [[VUID-VkSubmitInfo-pNext-03240]] 2363 If the pname:pNext chain of this structure includes a 2364 slink:VkTimelineSemaphoreSubmitInfo structure and any element of 2365 pname:pWaitSemaphores was created with a elink:VkSemaphoreType of 2366 ename:VK_SEMAPHORE_TYPE_TIMELINE, then its pname:waitSemaphoreValueCount 2367 member must: equal pname:waitSemaphoreCount 2368 * [[VUID-VkSubmitInfo-pNext-03241]] 2369 If the pname:pNext chain of this structure includes a 2370 slink:VkTimelineSemaphoreSubmitInfo structure and any element of 2371 pname:pSignalSemaphores was created with a elink:VkSemaphoreType of 2372 ename:VK_SEMAPHORE_TYPE_TIMELINE, then its 2373 pname:signalSemaphoreValueCount member must: equal 2374 pname:signalSemaphoreCount 2375 * [[VUID-VkSubmitInfo-pSignalSemaphores-03242]] 2376 For each element of pname:pSignalSemaphores created with a 2377 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 2378 corresponding element of 2379 slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: 2380 have a value greater than the current value of the semaphore when the 2381 <<synchronization-semaphores-signaling,semaphore signal operation>> is 2382 executed 2383 * [[VUID-VkSubmitInfo-pWaitSemaphores-03243]] 2384 For each element of pname:pWaitSemaphores created with a 2385 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 2386 corresponding element of 2387 slink:VkTimelineSemaphoreSubmitInfo::pname:pWaitSemaphoreValues must: 2388 have a value which does not differ from the current value of the 2389 semaphore or the value of any outstanding semaphore wait or signal 2390 operation on that semaphore by more than 2391 <<limits-maxTimelineSemaphoreValueDifference, 2392 pname:maxTimelineSemaphoreValueDifference>> 2393 * [[VUID-VkSubmitInfo-pSignalSemaphores-03244]] 2394 For each element of pname:pSignalSemaphores created with a 2395 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 2396 corresponding element of 2397 slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: 2398 have a value which does not differ from the current value of the 2399 semaphore or the value of any outstanding semaphore wait or signal 2400 operation on that semaphore by more than 2401 <<limits-maxTimelineSemaphoreValueDifference, 2402 pname:maxTimelineSemaphoreValueDifference>> 2403endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2404ifdef::VK_VERSION_1_1[] 2405 * [[VUID-VkSubmitInfo-pNext-04120]] 2406 If the pname:pNext chain of this structure does not include a 2407 sname:VkProtectedSubmitInfo structure with pname:protectedSubmit set to 2408 ename:VK_TRUE, then each element of the pname:pCommandBuffers array 2409 must: be an unprotected command buffer 2410 * [[VUID-VkSubmitInfo-pNext-04148]] 2411 If the pname:pNext chain of this structure includes a 2412 sname:VkProtectedSubmitInfo structure with pname:protectedSubmit set to 2413 ename:VK_TRUE, then each element of the pname:pCommandBuffers array 2414 must: be a protected command buffer 2415endif::VK_VERSION_1_1[] 2416ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 2417 * [[VUID-VkSubmitInfo-pCommandBuffers-06193]] 2418 If pname:pCommandBuffers contains any <<renderpass-suspension,resumed 2419 render pass instances>>, they must: be suspended by a render pass 2420 instance earlier in submission order within pname:pCommandBuffers 2421 * [[VUID-VkSubmitInfo-pCommandBuffers-06014]] 2422 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2423 render pass instances>>, they must: be resumed by a render pass instance 2424 later in submission order within pname:pCommandBuffers 2425 * [[VUID-VkSubmitInfo-pCommandBuffers-06015]] 2426 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2427 render pass instances>>, there must: be no action or synchronization 2428 commands executed in a primary or <<commandbuffers-secondary, 2429 secondary>> command buffer between that render pass instance and the 2430 render pass instance that resumes it 2431 * [[VUID-VkSubmitInfo-pCommandBuffers-06016]] 2432 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2433 render pass instances>>, there must: be no render pass instances between 2434 that render pass instance and the render pass instance that resumes it 2435ifdef::VK_EXT_sample_locations[] 2436 * [[VUID-VkSubmitInfo-variableSampleLocations-06017]] 2437 If the <<limits-variableSampleLocations, pname:variableSampleLocations>> 2438 limit is not supported, and any element of pname:pCommandBuffers 2439 contains any <<renderpass-suspension, suspended render pass instances>>, 2440 where a graphics pipeline has been bound, any pipelines bound in the 2441 render pass instance that resumes it, or any subsequent render pass 2442 instances that resume from that one and so on, must: use the same sample 2443 locations 2444endif::VK_EXT_sample_locations[] 2445endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 2446**** 2447 2448include::{generated}/validity/structs/VkSubmitInfo.adoc[] 2449-- 2450 2451ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2452[open,refpage='VkTimelineSemaphoreSubmitInfo',desc='Structure specifying signal and wait values for timeline semaphores',type='structs',alias='VkTimelineSemaphoreSubmitInfoKHR'] 2453-- 2454To specify the values to use when waiting for and signaling semaphores 2455created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE, 2456add a slink:VkTimelineSemaphoreSubmitInfo structure to the pname:pNext chain 2457of the slink:VkSubmitInfo structure when using flink:vkQueueSubmit 2458ifndef::VKSC_VERSION_1_0[or the slink:VkBindSparseInfo structure when using flink:vkQueueBindSparse] 2459. 2460The sname:VkTimelineSemaphoreSubmitInfo structure is defined as: 2461 2462include::{generated}/api/structs/VkTimelineSemaphoreSubmitInfo.adoc[] 2463 2464ifdef::VK_KHR_timeline_semaphore[] 2465or the equivalent 2466 2467include::{generated}/api/structs/VkTimelineSemaphoreSubmitInfoKHR.adoc[] 2468endif::VK_KHR_timeline_semaphore[] 2469 2470 * pname:sType is a elink:VkStructureType value identifying this structure. 2471 * pname:pNext is `NULL` or a pointer to a structure extending this 2472 structure. 2473 * pname:waitSemaphoreValueCount is the number of semaphore wait values 2474 specified in pname:pWaitSemaphoreValues. 2475 * pname:pWaitSemaphoreValues is a pointer to an array of 2476 pname:waitSemaphoreValueCount values for the corresponding semaphores in 2477 slink:VkSubmitInfo::pname:pWaitSemaphores to wait for. 2478 * pname:signalSemaphoreValueCount is the number of semaphore signal values 2479 specified in pname:pSignalSemaphoreValues. 2480 * pname:pSignalSemaphoreValues is a pointer to an array 2481 pname:signalSemaphoreValueCount values for the corresponding semaphores 2482 in slink:VkSubmitInfo::pname:pSignalSemaphores to set when signaled. 2483 2484If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or 2485slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in 2486pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively was 2487not created with a elink:VkSemaphoreType of 2488ename:VK_SEMAPHORE_TYPE_TIMELINE, the implementation must: ignore the value 2489in the pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry. 2490 2491ifdef::VK_NV_external_sci_sync,VK_NV_external_sci_sync2[] 2492If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or 2493slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in 2494pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively was 2495created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE, 2496and has stext:NvSciSyncObj as the payload, the value in the 2497pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry must: be 2498calculated by application via <<NvSciSync-extension-page, NvSciSync APIs>>. 2499endif::VK_NV_external_sci_sync,VK_NV_external_sci_sync2[] 2500 2501include::{generated}/validity/structs/VkTimelineSemaphoreSubmitInfo.adoc[] 2502-- 2503endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2504 2505ifdef::VK_KHR_external_semaphore_win32[] 2506[open,refpage='VkD3D12FenceSubmitInfoKHR',desc='Structure specifying values for Direct3D 12 fence-backed semaphores',type='structs'] 2507-- 2508To specify the values to use when waiting for and signaling semaphores whose 2509<<synchronization-semaphores-importing,current payload>> refers to a 2510Direct3D 12 fence, add a slink:VkD3D12FenceSubmitInfoKHR structure to the 2511pname:pNext chain of the slink:VkSubmitInfo structure. 2512The sname:VkD3D12FenceSubmitInfoKHR structure is defined as: 2513 2514include::{generated}/api/structs/VkD3D12FenceSubmitInfoKHR.adoc[] 2515 2516 * pname:sType is a elink:VkStructureType value identifying this structure. 2517 * pname:pNext is `NULL` or a pointer to a structure extending this 2518 structure. 2519 * pname:waitSemaphoreValuesCount is the number of semaphore wait values 2520 specified in pname:pWaitSemaphoreValues. 2521 * pname:pWaitSemaphoreValues is a pointer to an array of 2522 pname:waitSemaphoreValuesCount values for the corresponding semaphores 2523 in slink:VkSubmitInfo::pname:pWaitSemaphores to wait for. 2524 * pname:signalSemaphoreValuesCount is the number of semaphore signal 2525 values specified in pname:pSignalSemaphoreValues. 2526 * pname:pSignalSemaphoreValues is a pointer to an array of 2527 pname:signalSemaphoreValuesCount values for the corresponding semaphores 2528 in slink:VkSubmitInfo::pname:pSignalSemaphores to set when signaled. 2529 2530If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or 2531slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in 2532pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively does 2533not currently have a <<synchronization-semaphores-payloads, payload>> 2534referring to a Direct3D 12 fence, the implementation must: ignore the value 2535in the pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry. 2536 2537ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2538[NOTE] 2539.Note 2540==== 2541As the introduction of the external semaphore handle type 2542ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT predates that of 2543timeline semaphores, support for importing semaphore payloads from external 2544handles of that type into semaphores created (implicitly or explicitly) with 2545a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY is preserved for 2546backwards compatibility. 2547However, applications should: prefer importing such handle types into 2548semaphores created with a elink:VkSemaphoreType of 2549ename:VK_SEMAPHORE_TYPE_TIMELINE, and use the 2550slink:VkTimelineSemaphoreSubmitInfo structure instead of the 2551sname:VkD3D12FenceSubmitInfoKHR structure to specify the values to use when 2552waiting for and signaling such semaphores. 2553==== 2554endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2555 2556.Valid Usage 2557**** 2558 * [[VUID-VkD3D12FenceSubmitInfoKHR-waitSemaphoreValuesCount-00079]] 2559 pname:waitSemaphoreValuesCount must: be the same value as 2560 sname:VkSubmitInfo::pname:waitSemaphoreCount, where this structure is in 2561 the pname:pNext chain of a sname:VkSubmitInfo structure 2562 * [[VUID-VkD3D12FenceSubmitInfoKHR-signalSemaphoreValuesCount-00080]] 2563 pname:signalSemaphoreValuesCount must: be the same value as 2564 sname:VkSubmitInfo::pname:signalSemaphoreCount, where this structure is 2565 in the pname:pNext chain of a sname:VkSubmitInfo structure 2566**** 2567 2568include::{generated}/validity/structs/VkD3D12FenceSubmitInfoKHR.adoc[] 2569-- 2570endif::VK_KHR_external_semaphore_win32[] 2571 2572ifdef::VK_KHR_win32_keyed_mutex[] 2573[open,refpage='VkWin32KeyedMutexAcquireReleaseInfoKHR',desc='Use the Windows keyed mutex mechanism to synchronize work',type='structs'] 2574-- 2575When submitting work that operates on memory imported from a Direct3D 11 2576resource to a queue, the keyed mutex mechanism may: be used in addition to 2577Vulkan semaphores to synchronize the work. 2578Keyed mutexes are a property of a properly created shareable Direct3D 11 2579resource. 2580They can: only be used if the imported resource was created with the 2581etext:D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX flag. 2582 2583To acquire keyed mutexes before submitted work and/or release them after, 2584add a slink:VkWin32KeyedMutexAcquireReleaseInfoKHR structure to the 2585pname:pNext chain of the slink:VkSubmitInfo structure. 2586 2587The sname:VkWin32KeyedMutexAcquireReleaseInfoKHR structure is defined as: 2588 2589include::{generated}/api/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.adoc[] 2590 2591 * pname:sType is a elink:VkStructureType value identifying this structure. 2592 * pname:pNext is `NULL` or a pointer to a structure extending this 2593 structure. 2594 * pname:acquireCount is the number of entries in the pname:pAcquireSyncs, 2595 pname:pAcquireKeys, and pname:pAcquireTimeouts arrays. 2596 * pname:pAcquireSyncs is a pointer to an array of slink:VkDeviceMemory 2597 objects which were imported from Direct3D 11 resources. 2598 * pname:pAcquireKeys is a pointer to an array of mutex key values to wait 2599 for prior to beginning the submitted work. 2600 Entries refer to the keyed mutex associated with the corresponding 2601 entries in pname:pAcquireSyncs. 2602 * pname:pAcquireTimeouts is a pointer to an array of timeout values, in 2603 millisecond units, for each acquire specified in pname:pAcquireKeys. 2604 * pname:releaseCount is the number of entries in the pname:pReleaseSyncs 2605 and pname:pReleaseKeys arrays. 2606 * pname:pReleaseSyncs is a pointer to an array of slink:VkDeviceMemory 2607 objects which were imported from Direct3D 11 resources. 2608 * pname:pReleaseKeys is a pointer to an array of mutex key values to set 2609 when the submitted work has completed. 2610 Entries refer to the keyed mutex associated with the corresponding 2611 entries in pname:pReleaseSyncs. 2612 2613.Valid Usage 2614**** 2615 * [[VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireSyncs-00081]] 2616 Each member of pname:pAcquireSyncs and pname:pReleaseSyncs must: be a 2617 device memory object imported by setting 2618 slink:VkImportMemoryWin32HandleInfoKHR::pname:handleType to 2619 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT or 2620 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT 2621**** 2622 2623include::{generated}/validity/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.adoc[] 2624-- 2625endif::VK_KHR_win32_keyed_mutex[] 2626 2627ifdef::VK_NV_win32_keyed_mutex[] 2628include::{chapters}/VK_NV_win32_keyed_mutex/keyed_mutex_submit.adoc[] 2629endif::VK_NV_win32_keyed_mutex[] 2630 2631ifdef::VK_VERSION_1_1[] 2632[open,refpage='VkProtectedSubmitInfo',desc='Structure indicating whether the submission is protected',type='structs'] 2633-- 2634If the pname:pNext chain of slink:VkSubmitInfo includes a 2635sname:VkProtectedSubmitInfo structure, then the structure indicates whether 2636the batch is protected. 2637The sname:VkProtectedSubmitInfo structure is defined as: 2638 2639include::{generated}/api/structs/VkProtectedSubmitInfo.adoc[] 2640 2641 * pname:protectedSubmit specifies whether the batch is protected. 2642 If pname:protectedSubmit is ename:VK_TRUE, the batch is protected. 2643 If pname:protectedSubmit is ename:VK_FALSE, the batch is unprotected. 2644 If the sname:VkSubmitInfo::pname:pNext chain does not include this 2645 structure, the batch is unprotected. 2646 2647include::{generated}/validity/structs/VkProtectedSubmitInfo.adoc[] 2648-- 2649endif::VK_VERSION_1_1[] 2650 2651ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2652[open,refpage='VkDeviceGroupSubmitInfo',desc='Structure indicating which physical devices execute semaphore operations and command buffers',type='structs'] 2653-- 2654If the pname:pNext chain of slink:VkSubmitInfo includes a 2655sname:VkDeviceGroupSubmitInfo structure, then that structure includes device 2656indices and masks specifying which physical devices execute semaphore 2657operations and command buffers. 2658 2659The sname:VkDeviceGroupSubmitInfo structure is defined as: 2660 2661include::{generated}/api/structs/VkDeviceGroupSubmitInfo.adoc[] 2662 2663ifdef::VK_KHR_device_group[] 2664or the equivalent 2665 2666include::{generated}/api/structs/VkDeviceGroupSubmitInfoKHR.adoc[] 2667endif::VK_KHR_device_group[] 2668 2669 * pname:sType is a elink:VkStructureType value identifying this structure. 2670 * pname:pNext is `NULL` or a pointer to a structure extending this 2671 structure. 2672 * pname:waitSemaphoreCount is the number of elements in the 2673 pname:pWaitSemaphoreDeviceIndices array. 2674 * pname:pWaitSemaphoreDeviceIndices is a pointer to an array of 2675 pname:waitSemaphoreCount device indices indicating which physical device 2676 executes the semaphore wait operation in the corresponding element of 2677 slink:VkSubmitInfo::pname:pWaitSemaphores. 2678 * pname:commandBufferCount is the number of elements in the 2679 pname:pCommandBufferDeviceMasks array. 2680 * pname:pCommandBufferDeviceMasks is a pointer to an array of 2681 pname:commandBufferCount device masks indicating which physical devices 2682 execute the command buffer in the corresponding element of 2683 slink:VkSubmitInfo::pname:pCommandBuffers. 2684 A physical device executes the command buffer if the corresponding bit 2685 is set in the mask. 2686 * pname:signalSemaphoreCount is the number of elements in the 2687 pname:pSignalSemaphoreDeviceIndices array. 2688 * pname:pSignalSemaphoreDeviceIndices is a pointer to an array of 2689 pname:signalSemaphoreCount device indices indicating which physical 2690 device executes the semaphore signal operation in the corresponding 2691 element of slink:VkSubmitInfo::pname:pSignalSemaphores. 2692 2693If this structure is not present, semaphore operations and command buffers 2694execute on device index zero. 2695 2696.Valid Usage 2697**** 2698 * [[VUID-VkDeviceGroupSubmitInfo-waitSemaphoreCount-00082]] 2699 pname:waitSemaphoreCount must: equal 2700 slink:VkSubmitInfo::pname:waitSemaphoreCount 2701 * [[VUID-VkDeviceGroupSubmitInfo-commandBufferCount-00083]] 2702 pname:commandBufferCount must: equal 2703 slink:VkSubmitInfo::pname:commandBufferCount 2704 * [[VUID-VkDeviceGroupSubmitInfo-signalSemaphoreCount-00084]] 2705 pname:signalSemaphoreCount must: equal 2706 slink:VkSubmitInfo::pname:signalSemaphoreCount 2707 * [[VUID-VkDeviceGroupSubmitInfo-pWaitSemaphoreDeviceIndices-00085]] 2708 All elements of pname:pWaitSemaphoreDeviceIndices and 2709 pname:pSignalSemaphoreDeviceIndices must: be valid device indices 2710 * [[VUID-VkDeviceGroupSubmitInfo-pCommandBufferDeviceMasks-00086]] 2711 All elements of pname:pCommandBufferDeviceMasks must: be valid device 2712 masks 2713**** 2714 2715include::{generated}/validity/structs/VkDeviceGroupSubmitInfo.adoc[] 2716-- 2717endif::VK_VERSION_1_1,VK_KHR_device_group[] 2718 2719ifdef::VK_KHR_performance_query[] 2720If the pname:pNext chain of slink:VkSubmitInfo includes a 2721slink:VkPerformanceQuerySubmitInfoKHR structure, then the structure 2722indicates which counter pass is active for the batch in that submit. 2723 2724[open,refpage='VkPerformanceQuerySubmitInfoKHR',desc='Structure indicating which counter pass index is active for performance queries',type='structs'] 2725-- 2726The sname:VkPerformanceQuerySubmitInfoKHR structure is defined as: 2727 2728include::{generated}/api/structs/VkPerformanceQuerySubmitInfoKHR.adoc[] 2729 2730 * pname:sType is a elink:VkStructureType value identifying this structure. 2731 * pname:pNext is `NULL` or a pointer to a structure extending this 2732 structure. 2733 * pname:counterPassIndex specifies which counter pass index is active. 2734 2735If the sname:VkSubmitInfo::pname:pNext chain does not include this 2736structure, the batch defaults to use counter pass index 0. 2737 2738.Valid Usage 2739**** 2740 * [[VUID-VkPerformanceQuerySubmitInfoKHR-counterPassIndex-03221]] 2741 pname:counterPassIndex must: be less than the number of counter passes 2742 required by any queries within the batch. 2743 The required number of counter passes for a performance query is 2744 obtained by calling 2745 flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR 2746**** 2747 2748include::{generated}/validity/structs/VkPerformanceQuerySubmitInfoKHR.adoc[] 2749-- 2750endif::VK_KHR_performance_query[] 2751 2752 2753[[commandbuffers-submission-progress]] 2754== Queue Forward Progress 2755 2756When using binary semaphores, the application must: ensure that command 2757buffer submissions will be able to complete without any subsequent 2758operations by the application on any queue. 2759After any call to fname:vkQueueSubmit (or other queue operation), for every 2760queued wait on a semaphore 2761ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2762created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY 2763endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2764there must: be a prior signal of that semaphore that will not be consumed by 2765a different wait on the semaphore. 2766 2767ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2768When using timeline semaphores, wait-before-signal behavior is well-defined 2769and applications can: submit work via fname:vkQueueSubmit defining a 2770<<synchronization-semaphores-waiting, timeline semaphore wait operation>> 2771before submitting a corresponding <<synchronization-semaphores-signaling, 2772semaphore signal operation>>. 2773For each <<synchronization-semaphores-waiting, timeline semaphore wait 2774operation>> defined by a call to fname:vkQueueSubmit, the application must: 2775ensure that a corresponding <<synchronization-semaphores-signaling, 2776semaphore signal operation>> is executed before forward progress can be 2777made. 2778endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 2779 2780If a command buffer submission waits for any events to be signaled, the 2781application must: ensure that command buffer submissions will be able to 2782complete without any subsequent operations by the application. 2783Events signaled by the host must: be signaled before the command buffer 2784waits on those events. 2785 2786[NOTE] 2787.Note 2788==== 2789The ability for commands to wait on the host to set an events was originally 2790added to allow low-latency updates to resources between host and device. 2791However, to ensure quality of service, implementations would necessarily 2792detect extended stalls in execution and timeout after a short period. 2793As this period is not defined in the Vulkan specification, it is impossible 2794to correctly validate any application with any wait period. 2795Since the original users of this functionality were highly limited and 2796platform-specific, this functionality is now considered defunct and should 2797not be used. 2798==== 2799 2800 2801[[commandbuffers-secondary]] 2802== Secondary Command Buffer Execution 2803 2804[open,refpage='vkCmdExecuteCommands',desc='Execute a secondary command buffer from a primary command buffer',type='protos'] 2805-- 2806Secondary command buffers must: not be directly submitted to a queue. 2807To record a secondary command buffer to execute as part of a primary command 2808buffer, call: 2809 2810include::{generated}/api/protos/vkCmdExecuteCommands.adoc[] 2811 2812 * pname:commandBuffer is a handle to a primary command buffer that the 2813 secondary command buffers are executed in. 2814 * pname:commandBufferCount is the length of the pname:pCommandBuffers 2815 array. 2816 * pname:pCommandBuffers is a pointer to an array of 2817 pname:commandBufferCount secondary command buffer handles, which are 2818 recorded to execute in the primary command buffer in the order they are 2819 listed in the array. 2820 2821If any element of pname:pCommandBuffers was not recorded with the 2822ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, and it was recorded 2823into any other primary command buffer which is currently in the 2824<<commandbuffers-lifecycle, executable or recording state>>, that primary 2825command buffer becomes <<commandbuffers-lifecycle, invalid>>. 2826 2827ifdef::VK_EXT_nested_command_buffer[] 2828If the <<features-nestedCommandBuffer, pname:nestedCommandBuffer>> feature 2829is enabled it is valid usage for fname:vkCmdExecuteCommands to also be 2830recorded to a <<glossary, secondary command buffer>>. 2831endif::VK_EXT_nested_command_buffer[] 2832 2833.Valid Usage 2834**** 2835 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00088]] 2836 Each element of pname:pCommandBuffers must: have been allocated with a 2837 pname:level of ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 2838 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00089]] 2839 Each element of pname:pCommandBuffers must: be in the 2840 <<commandbuffers-lifecycle, pending or executable state>> 2841 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00091]] 2842 If any element of pname:pCommandBuffers was not recorded with the 2843 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not be 2844 in the <<commandbuffers-lifecycle, pending state>> 2845 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00092]] 2846 If any element of pname:pCommandBuffers was not recorded with the 2847 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not 2848 have already been recorded to pname:commandBuffer 2849 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00093]] 2850 If any element of pname:pCommandBuffers was not recorded with the 2851 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not 2852 appear more than once in pname:pCommandBuffers 2853 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00094]] 2854 Each element of pname:pCommandBuffers must: have been allocated from a 2855 sname:VkCommandPool that was created for the same queue family as the 2856 sname:VkCommandPool from which pname:commandBuffer was allocated 2857 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00096]] 2858 If fname:vkCmdExecuteCommands is being called within a render pass 2859 instance, each element of pname:pCommandBuffers must: have been recorded 2860 with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 2861 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00099]] 2862 If fname:vkCmdExecuteCommands is being called within a render pass 2863 instance, and any element of pname:pCommandBuffers was recorded with 2864 slink:VkCommandBufferInheritanceInfo::pname:framebuffer not equal to 2865 dlink:VK_NULL_HANDLE, that sname:VkFramebuffer must: match the 2866 sname:VkFramebuffer used in the current render pass instance 2867 * [[VUID-vkCmdExecuteCommands-contents-06018]] 2868 If fname:vkCmdExecuteCommands is being called within a render pass 2869 instance begun with flink:vkCmdBeginRenderPass, its pname:contents 2870 parameter must: have been set to 2871 ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS 2872ifdef::VK_EXT_nested_command_buffer[, or ename:VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_EXT] 2873 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06019]] 2874 If fname:vkCmdExecuteCommands is being called within a render pass 2875 instance begun with flink:vkCmdBeginRenderPass, each element of 2876 pname:pCommandBuffers must: have been recorded with 2877 slink:VkCommandBufferInheritanceInfo::pname:subpass set to the index of 2878 the subpass which the given command buffer will be executed in 2879 * [[VUID-vkCmdExecuteCommands-pBeginInfo-06020]] 2880 If fname:vkCmdExecuteCommands is being called within a render pass 2881 instance begun with flink:vkCmdBeginRenderPass, the render passes 2882 specified in the pname:pBeginInfo->pInheritanceInfo->renderPass members 2883 of the flink:vkBeginCommandBuffer commands used to begin recording each 2884 element of pname:pCommandBuffers must: be 2885 <<renderpass-compatibility,compatible>> with the current render pass 2886ifdef::VK_QCOM_render_pass_transform[] 2887 * [[VUID-vkCmdExecuteCommands-pNext-02865]] 2888 If fname:vkCmdExecuteCommands is being called within a render pass 2889 instance that included slink:VkRenderPassTransformBeginInfoQCOM in the 2890 pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of 2891 pname:pCommandBuffers must: have been recorded with 2892 slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM in the 2893 pname:pNext chain of slink:VkCommandBufferBeginInfo 2894 * [[VUID-vkCmdExecuteCommands-pNext-02866]] 2895 If fname:vkCmdExecuteCommands is being called within a render pass 2896 instance that included slink:VkRenderPassTransformBeginInfoQCOM in the 2897 pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of 2898 pname:pCommandBuffers must: have been recorded with 2899 slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM::pname:transform 2900 identical to slink:VkRenderPassTransformBeginInfoQCOM::pname:transform 2901 * [[VUID-vkCmdExecuteCommands-pNext-02867]] 2902 If fname:vkCmdExecuteCommands is being called within a render pass 2903 instance that included slink:VkRenderPassTransformBeginInfoQCOM in the 2904 pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of 2905 pname:pCommandBuffers must: have been recorded with 2906 slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM::pname:renderArea 2907 identical to slink:VkRenderPassBeginInfo::pname:renderArea 2908endif::VK_QCOM_render_pass_transform[] 2909 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00100]] 2910 If fname:vkCmdExecuteCommands is not being called within a render pass 2911 instance, each element of pname:pCommandBuffers must: not have been 2912 recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 2913 * [[VUID-vkCmdExecuteCommands-commandBuffer-00101]] 2914 If the <<features-inheritedQueries, pname:inheritedQueries>> feature is 2915 not enabled, pname:commandBuffer must: not have any queries 2916 <<queries-operation-active,active>> 2917 * [[VUID-vkCmdExecuteCommands-commandBuffer-00102]] 2918 If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query 2919 <<queries-operation-active,active>>, then each element of 2920 pname:pCommandBuffers must: have been recorded with 2921 sname:VkCommandBufferInheritanceInfo::pname:occlusionQueryEnable set to 2922 ename:VK_TRUE 2923 * [[VUID-vkCmdExecuteCommands-commandBuffer-00103]] 2924 If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query 2925 <<queries-operation-active,active>>, then each element of 2926 pname:pCommandBuffers must: have been recorded with 2927 sname:VkCommandBufferInheritanceInfo::pname:queryFlags having all bits 2928 set that are set for the query 2929 * [[VUID-vkCmdExecuteCommands-commandBuffer-00104]] 2930 If pname:commandBuffer has a ename:VK_QUERY_TYPE_PIPELINE_STATISTICS 2931 query <<queries-operation-active,active>>, then each element of 2932 pname:pCommandBuffers must: have been recorded with 2933 sname:VkCommandBufferInheritanceInfo::pname:pipelineStatistics having 2934 all bits set that are set in the sname:VkQueryPool the query uses 2935 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00105]] 2936 Each element of pname:pCommandBuffers must: not begin any query types 2937 that are <<queries-operation-active,active>> in pname:commandBuffer 2938 * [[VUID-vkCmdExecuteCommands-commandBuffer-07594]] 2939 pname:commandBuffer must: not have any queries other than 2940 ename:VK_QUERY_TYPE_OCCLUSION and 2941 ename:VK_QUERY_TYPE_PIPELINE_STATISTICS 2942 <<queries-operation-active,active>> 2943ifdef::VK_VERSION_1_1[] 2944 * [[VUID-vkCmdExecuteCommands-commandBuffer-01820]] 2945 If pname:commandBuffer is a protected command buffer and 2946 <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, 2947 each element of pname:pCommandBuffers must: be a protected command 2948 buffer 2949 * [[VUID-vkCmdExecuteCommands-commandBuffer-01821]] 2950 If pname:commandBuffer is an unprotected command buffer and 2951 <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, 2952 each element of pname:pCommandBuffers must: be an unprotected command 2953 buffer 2954endif::VK_VERSION_1_1[] 2955ifdef::VK_EXT_transform_feedback[] 2956 * [[VUID-vkCmdExecuteCommands-None-02286]] 2957 This command must: not be recorded when transform feedback is active 2958endif::VK_EXT_transform_feedback[] 2959 * [[VUID-vkCmdExecuteCommands-commandBuffer-06533]] 2960 If fname:vkCmdExecuteCommands is being called within a render pass 2961 instance and any recorded command in pname:commandBuffer in the current 2962 subpass will write to an image subresource as an attachment, commands 2963 recorded in elements of pname:pCommandBuffers must: not read from the 2964 memory backing that image subresource in any other way 2965 * [[VUID-vkCmdExecuteCommands-commandBuffer-06534]] 2966 If fname:vkCmdExecuteCommands is being called within a render pass 2967 instance and any recorded command in pname:commandBuffer in the current 2968 subpass will read from an image subresource used as an attachment in any 2969 way other than as an attachment, commands recorded in elements of 2970 pname:pCommandBuffers must: not write to that image subresource as an 2971 attachment 2972 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06535]] 2973 If fname:vkCmdExecuteCommands is being called within a render pass 2974 instance and any recorded command in a given element of 2975 pname:pCommandBuffers will write to an image subresource as an 2976 attachment, commands recorded in elements of pname:pCommandBuffers at a 2977 higher index must: not read from the memory backing that image 2978 subresource in any other way 2979 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06536]] 2980 If fname:vkCmdExecuteCommands is being called within a render pass 2981 instance and any recorded command in a given element of 2982 pname:pCommandBuffers will read from an image subresource used as an 2983 attachment in any way other than as an attachment, commands recorded in 2984 elements of pname:pCommandBuffers at a higher index must: not write to 2985 that image subresource as an attachment 2986ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 2987 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06021]] 2988 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2989 render pass instances>>, there must: be no action or synchronization 2990 commands between that render pass instance and any render pass instance 2991 that resumes it 2992 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06022]] 2993 If pname:pCommandBuffers contains any <<renderpass-suspension,suspended 2994 render pass instances>>, there must: be no render pass instances between 2995 that render pass instance and any render pass instance that resumes it 2996ifdef::VK_EXT_sample_locations[] 2997 * [[VUID-vkCmdExecuteCommands-variableSampleLocations-06023]] 2998 If the <<limits-variableSampleLocations, pname:variableSampleLocations>> 2999 limit is not supported, and any element of pname:pCommandBuffers 3000 contains any <<renderpass-suspension, suspended render pass instances>>, 3001 where a graphics pipeline has been bound, any pipelines bound in the 3002 render pass instance that resumes it, or any subsequent render pass 3003 instances that resume from that one and so on, must: use the same sample 3004 locations 3005endif::VK_EXT_sample_locations[] 3006 * [[VUID-vkCmdExecuteCommands-flags-06024]] 3007 If fname:vkCmdExecuteCommands is being called within a render pass 3008 instance begun with flink:vkCmdBeginRendering, its 3009 slink:VkRenderingInfo::pname:flags parameter must: have included 3010 ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT 3011 * [[VUID-vkCmdExecuteCommands-pBeginInfo-06025]] 3012 If fname:vkCmdExecuteCommands is being called within a render pass 3013 instance begun with flink:vkCmdBeginRendering, the render passes 3014 specified in the pname:pBeginInfo->pInheritanceInfo->renderPass members 3015 of the flink:vkBeginCommandBuffer commands used to begin recording each 3016 element of pname:pCommandBuffers must: be dlink:VK_NULL_HANDLE 3017 * [[VUID-vkCmdExecuteCommands-flags-06026]] 3018 If fname:vkCmdExecuteCommands is being called within a render pass 3019 instance begun with flink:vkCmdBeginRendering, the pname:flags member of 3020 the slink:VkCommandBufferInheritanceRenderingInfo structure included in 3021 the pname:pNext chain of 3022 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3023 recording each element of pname:pCommandBuffers must: be equal to the 3024 slink:VkRenderingInfo::pname:flags parameter to 3025 flink:vkCmdBeginRendering, excluding 3026 ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT 3027 * [[VUID-vkCmdExecuteCommands-colorAttachmentCount-06027]] 3028 If fname:vkCmdExecuteCommands is being called within a render pass 3029 instance begun with flink:vkCmdBeginRendering, the 3030 pname:colorAttachmentCount member of the 3031 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 3032 pname:pNext chain of 3033 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3034 recording each element of pname:pCommandBuffers must: be equal to the 3035 slink:VkRenderingInfo::pname:colorAttachmentCount parameter to 3036 flink:vkCmdBeginRendering 3037 * [[VUID-vkCmdExecuteCommands-imageView-06028]] 3038 If fname:vkCmdExecuteCommands is being called within a render pass 3039 instance begun with flink:vkCmdBeginRendering, if the pname:imageView 3040 member of an element of the 3041 slink:VkRenderingInfo::pname:pColorAttachments parameter to 3042 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the corresponding 3043 element of the pname:pColorAttachmentFormats member of the 3044 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 3045 pname:pNext chain of 3046 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3047 recording each element of pname:pCommandBuffers must: be equal to the 3048 format used to create that image view 3049 * [[VUID-vkCmdExecuteCommands-imageView-07606]] 3050 If fname:vkCmdExecuteCommands is being called within a render pass 3051 instance begun with flink:vkCmdBeginRendering, if the pname:imageView 3052 member of an element of the 3053 slink:VkRenderingInfo::pname:pColorAttachments parameter to 3054 flink:vkCmdBeginRendering is dlink:VK_NULL_HANDLE, the corresponding 3055 element of the pname:pColorAttachmentFormats member of the 3056 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 3057 pname:pNext chain of 3058 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3059 recording each element of pname:pCommandBuffers must: be 3060 ename:VK_FORMAT_UNDEFINED 3061 * [[VUID-vkCmdExecuteCommands-pDepthAttachment-06029]] 3062 If fname:vkCmdExecuteCommands is being called within a render pass 3063 instance begun with flink:vkCmdBeginRendering, if the 3064 slink:VkRenderingInfo::pname:pDepthAttachment->imageView parameter to 3065 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of the 3066 pname:depthAttachmentFormat member of the 3067 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 3068 pname:pNext chain of 3069 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3070 recording each element of pname:pCommandBuffers must: be equal to the 3071 format used to create that image view 3072 * [[VUID-vkCmdExecuteCommands-pStencilAttachment-06030]] 3073 If fname:vkCmdExecuteCommands is being called within a render pass 3074 instance begun with flink:vkCmdBeginRendering, if the 3075 slink:VkRenderingInfo::pname:pStencilAttachment->imageView parameter to 3076 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of the 3077 pname:stencilAttachmentFormat member of the 3078 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 3079 pname:pNext chain of 3080 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3081 recording each element of pname:pCommandBuffers must: be equal to the 3082 format used to create that image view 3083 * [[VUID-vkCmdExecuteCommands-pDepthAttachment-06774]] 3084 If fname:vkCmdExecuteCommands is being called within a render pass 3085 instance begun with flink:vkCmdBeginRendering and the 3086 slink:VkRenderingInfo::pname:pDepthAttachment->imageView parameter to 3087 flink:vkCmdBeginRendering was dlink:VK_NULL_HANDLE, the value of the 3088 pname:depthAttachmentFormat member of the 3089 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 3090 pname:pNext chain of 3091 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3092 recording each element of pname:pCommandBuffers must: be 3093 ename:VK_FORMAT_UNDEFINED 3094 * [[VUID-vkCmdExecuteCommands-pStencilAttachment-06775]] 3095 If fname:vkCmdExecuteCommands is being called within a render pass 3096 instance begun with flink:vkCmdBeginRendering and the 3097 slink:VkRenderingInfo::pname:pStencilAttachment->imageView parameter to 3098 flink:vkCmdBeginRendering was dlink:VK_NULL_HANDLE, the value of the 3099 pname:stencilAttachmentFormat member of the 3100 slink:VkCommandBufferInheritanceRenderingInfo structure included in the 3101 pname:pNext chain of 3102 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3103 recording each element of pname:pCommandBuffers must: be 3104 ename:VK_FORMAT_UNDEFINED 3105ifdef::VK_KHR_multiview,VK_VERSION_1_1[] 3106 * [[VUID-vkCmdExecuteCommands-viewMask-06031]] 3107 If fname:vkCmdExecuteCommands is being called within a render pass 3108 instance begun with flink:vkCmdBeginRendering, the pname:viewMask member 3109 of the slink:VkCommandBufferInheritanceRenderingInfo structure included 3110 in the pname:pNext chain of 3111 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3112 recording each element of pname:pCommandBuffers must: be equal to the 3113 slink:VkRenderingInfo::pname:viewMask parameter to 3114 flink:vkCmdBeginRendering 3115endif::VK_KHR_multiview,VK_VERSION_1_1[] 3116ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 3117 * [[VUID-vkCmdExecuteCommands-pNext-06032]] 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 includes a 3121 slink:VkAttachmentSampleCountInfoAMD or 3122 slink:VkAttachmentSampleCountInfoNV structure, if the pname:imageView 3123 member of an element of the 3124 slink:VkRenderingInfo::pname:pColorAttachments parameter to 3125 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the corresponding 3126 element of the pname:pColorAttachmentSamples member of the 3127 slink:VkAttachmentSampleCountInfoAMD or 3128 slink:VkAttachmentSampleCountInfoNV structure included in the 3129 pname:pNext chain of 3130 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3131 recording each element of pname:pCommandBuffers must: be equal to the 3132 sample count used to create that image view 3133 * [[VUID-vkCmdExecuteCommands-pNext-06033]] 3134 If fname:vkCmdExecuteCommands is being called within a render pass 3135 instance begun with flink:vkCmdBeginRendering and the pname:pNext chain 3136 of slink:VkCommandBufferInheritanceInfo includes a 3137 slink:VkAttachmentSampleCountInfoAMD or 3138 slink:VkAttachmentSampleCountInfoNV structure, if the 3139 slink:VkRenderingInfo::pname:pDepthAttachment->imageView parameter to 3140 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of the 3141 pname:depthStencilAttachmentSamples member of the 3142 slink:VkAttachmentSampleCountInfoAMD or 3143 slink:VkAttachmentSampleCountInfoNV structure included in the 3144 pname:pNext chain of 3145 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3146 recording each element of pname:pCommandBuffers must: be equal to the 3147 sample count used to create that image view 3148 * [[VUID-vkCmdExecuteCommands-pNext-06034]] 3149 If fname:vkCmdExecuteCommands is being called within a render pass 3150 instance begun with flink:vkCmdBeginRendering and the pname:pNext chain 3151 of slink:VkCommandBufferInheritanceInfo includes a 3152 slink:VkAttachmentSampleCountInfoAMD or 3153 slink:VkAttachmentSampleCountInfoNV structure, if the 3154 slink:VkRenderingInfo::pname:pStencilAttachment->imageView parameter to 3155 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of the 3156 pname:depthStencilAttachmentSamples member of the 3157 slink:VkAttachmentSampleCountInfoAMD or 3158 slink:VkAttachmentSampleCountInfoNV structure included in the 3159 pname:pNext chain of 3160 slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin 3161 recording each element of pname:pCommandBuffers must: be equal to the 3162 sample count used to create that image view 3163 * [[VUID-vkCmdExecuteCommands-pNext-06035]] 3164 If fname:vkCmdExecuteCommands is being called within a render pass 3165 instance begun with flink:vkCmdBeginRendering and the pname:pNext chain 3166 of slink:VkCommandBufferInheritanceInfo does not include a 3167 slink:VkAttachmentSampleCountInfoAMD or 3168 slink:VkAttachmentSampleCountInfoNV structure, if the pname:imageView 3169 member of an element of the 3170 slink:VkRenderingInfo::pname:pColorAttachments parameter to 3171 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of 3172 slink:VkCommandBufferInheritanceRenderingInfo::pname:rasterizationSamples 3173 must: be equal to the sample count used to create that image view 3174 * [[VUID-vkCmdExecuteCommands-pNext-06036]] 3175 If fname:vkCmdExecuteCommands is being called within a render pass 3176 instance begun with flink:vkCmdBeginRendering and the pname:pNext chain 3177 of slink:VkCommandBufferInheritanceInfo does not include a 3178 slink:VkAttachmentSampleCountInfoAMD or 3179 slink:VkAttachmentSampleCountInfoNV structure, if the 3180 slink:VkRenderingInfo::pname:pDepthAttachment->imageView parameter to 3181 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of 3182 slink:VkCommandBufferInheritanceRenderingInfo::pname:rasterizationSamples 3183 must: be equal to the sample count used to create that image view 3184 * [[VUID-vkCmdExecuteCommands-pNext-06037]] 3185 If fname:vkCmdExecuteCommands is being called within a render pass 3186 instance begun with flink:vkCmdBeginRendering and the pname:pNext chain 3187 of slink:VkCommandBufferInheritanceInfo does not include a 3188 slink:VkAttachmentSampleCountInfoAMD or 3189 slink:VkAttachmentSampleCountInfoNV structure, if the 3190 slink:VkRenderingInfo::pname:pStencilAttachment->imageView parameter to 3191 flink:vkCmdBeginRendering is not dlink:VK_NULL_HANDLE, the value of 3192 slink:VkCommandBufferInheritanceRenderingInfo::pname:rasterizationSamples 3193 must: be equal to the sample count used to create that image view 3194endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] 3195ifdef::VK_ANDROID_external_format_resolve[] 3196 * [[VUID-vkCmdExecuteCommands-pNext-09299]] 3197 If fname:vkCmdExecuteCommands is being called within a render pass 3198 instance begun with flink:vkCmdBeginRendering, with any color attachment 3199 using a resolve mode of 3200 ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, the 3201 pname:pNext chain of slink:VkCommandBufferInheritanceInfo used to create 3202 each element of pname:pCommandBuffers must: include a 3203 slink:VkExternalFormatANDROID structure with a pname:externalFormat 3204 matching that used to create the resolve attachment in the render pass 3205 * [[VUID-vkCmdExecuteCommands-pNext-09300]] 3206 If fname:vkCmdExecuteCommands is being called within a render pass 3207 instance begun with flink:vkCmdBeginRendering with any color attachment 3208 using a resolve mode of 3209 ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, and the 3210 pname:pNext chain of slink:VkCommandBufferInheritanceInfo does not 3211 include a slink:VkAttachmentSampleCountInfoAMD or 3212 slink:VkAttachmentSampleCountInfoNV structure, the value of 3213 slink:VkCommandBufferInheritanceRenderingInfo::pname:rasterizationSamples 3214 must: be ename:VK_SAMPLE_COUNT_1_BIT 3215endif::VK_ANDROID_external_format_resolve[] 3216endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] 3217 * [[VUID-vkCmdExecuteCommands-commandBuffer-09375]] 3218 pname:commandBuffer must: not be a <<glossary, secondary command 3219 buffer>> 3220ifdef::VK_EXT_nested_command_buffer[] 3221 unless the <<features-nestedCommandBuffer, pname:nestedCommandBuffer>> 3222 feature is enabled 3223 * [[VUID-vkCmdExecuteCommands-nestedCommandBuffer-09376]] 3224 If the <<features-nestedCommandBuffer, pname:nestedCommandBuffer>> 3225 feature is enabled, the <<glossary, command buffer nesting level>> of 3226 each element of pname:pCommandBuffers must: be less than 3227 <<limits-maxCommandBufferNestingLevel, 3228 pname:maxCommandBufferNestingLevel>> 3229 * [[VUID-vkCmdExecuteCommands-nestedCommandBufferRendering-09377]] 3230 If the <<features-nestedCommandBufferRendering, 3231 pname:nestedCommandBufferRendering>> feature is not enabled, and 3232 pname:commandBuffer is a <<glossary, secondary command buffer>>, 3233 pname:commandBuffer must: not have been recorded with 3234 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 3235 * [[VUID-vkCmdExecuteCommands-nestedCommandBufferSimultaneousUse-09378]] 3236 If the <<features-nestedCommandBufferSimultaneousUse, 3237 pname:nestedCommandBufferSimultaneousUse>> feature is not enabled, and 3238 pname:commandBuffer is a <<glossary, secondary command buffer>>, each 3239 element of pname:pCommandBuffers must: not have been recorded with 3240 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT 3241endif::VK_EXT_nested_command_buffer[] 3242**** 3243 3244include::{generated}/validity/protos/vkCmdExecuteCommands.adoc[] 3245-- 3246 3247ifdef::VK_EXT_nested_command_buffer[] 3248[[commandbuffers-nested]] 3249== Nested Command Buffers 3250 3251In addition to secondary command buffer execution from primary command 3252buffers, an implementation may: support <<glossary, nested command 3253buffers>>, which enable secondary command buffers to be executed from other 3254secondary command buffers. 3255If the <<features-nestedCommandBuffer, pname:nestedCommandBuffer>> feature 3256is enabled, the implementation supports <<glossary, nested command 3257buffers>>. 3258 3259Nested command buffer execution works the same as primary-to-secondary 3260execution, except that it is subject to some additional 3261implementation-defined limits. 3262 3263Each secondary command buffer has a <<glossary, command buffer nesting 3264level>>, which is determined at flink:vkEndCommandBuffer time and evaluated 3265at flink:vkCmdExecuteCommands time. 3266A secondary command buffer that executes no other secondary command buffers 3267has a <<glossary, command buffer nesting level>> of zero. 3268Otherwise, the <<glossary, command buffer nesting level>> of a secondary 3269command buffer is equal to the maximum nesting level of all secondary 3270command buffers executed by that command buffer plus one. 3271Some implementations may: have a limit on the maximum nesting level of 3272secondary command buffers that can: be recorded. 3273This limit is advertised in <<limits-maxCommandBufferNestingLevel, 3274pname:maxCommandBufferNestingLevel>>. 3275 3276If the <<features-nestedCommandBufferRendering, 3277pname:nestedCommandBufferRendering>> feature is enabled, the implementation 3278supports calling flink:vkCmdExecuteCommands inside secondary command buffers 3279recorded with ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT. 3280If the <<features-nestedCommandBufferSimultaneousUse, 3281pname:nestedCommandBufferSimultaneousUse>> feature is enabled, the 3282implementation supports calling flink:vkCmdExecuteCommands with secondary 3283command buffers recorded with 3284ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT. 3285 3286Whenever flink:vkCmdExecuteCommands is recorded inside a secondary command 3287buffer recorded with ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, 3288each member of pname:pCommandBuffers must: have been recorded with a 3289slink:VkCommandBufferBeginInfo with slink:VkCommandBufferInheritanceInfo 3290compatible with the slink:VkCommandBufferInheritanceInfo of the command 3291buffer into which the flink:vkCmdExecuteCommands call is being recorded. 3292The slink:VkCommandBufferInheritanceRenderingInfo structures are compatible 3293when the sname:VkCommandBufferInheritanceRenderingInfo::pname:renderpass are 3294<<renderpass-compatibility, compatible>>, or if they are 3295dlink:VK_NULL_HANDLE then the slink:VkCommandBufferInheritanceRenderingInfo 3296members match, and all other members of 3297sname:VkCommandBufferInheritanceRenderingInfo match. 3298This requirement applies recursively, down to the most nested command buffer 3299and up to the command buffer where the render pass was originally begun. 3300 3301endif::VK_EXT_nested_command_buffer[] 3302 3303ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 3304[[commandbuffers-devicemask]] 3305== Command Buffer Device Mask 3306 3307Each command buffer has a piece of state storing the current device mask of 3308the command buffer. 3309This mask controls which physical devices within the logical device all 3310subsequent commands will execute on, including state-setting commands, 3311action commands, and synchronization commands. 3312 3313ifndef::VK_NV_scissor_exclusive[] 3314Scissor 3315endif::VK_NV_scissor_exclusive[] 3316ifdef::VK_NV_scissor_exclusive[] 3317Scissor, exclusive scissor, 3318endif::VK_NV_scissor_exclusive[] 3319and viewport state 3320ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 3321(excluding the count of each) 3322endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 3323can: be set to different values on each physical device (only when set as 3324dynamic state), and each physical device will render using its local copy of 3325the state. 3326Other state is shared between physical devices, such that all physical 3327devices use the most recently set values for the state. 3328However, when recording an action command that uses a piece of state, the 3329most recent command that set that state must: have included all physical 3330devices that execute the action command in its current device mask. 3331 3332The command buffer's device mask is orthogonal to the 3333pname:pCommandBufferDeviceMasks member of slink:VkDeviceGroupSubmitInfo. 3334Commands only execute on a physical device if the device index is set in 3335both device masks. 3336 3337[open,refpage='VkDeviceGroupCommandBufferBeginInfo',desc='Set the initial device mask for a command buffer',type='structs'] 3338-- 3339If the pname:pNext chain of slink:VkCommandBufferBeginInfo includes a 3340sname:VkDeviceGroupCommandBufferBeginInfo structure, then that structure 3341includes an initial device mask for the command buffer. 3342 3343The sname:VkDeviceGroupCommandBufferBeginInfo structure is defined as: 3344 3345include::{generated}/api/structs/VkDeviceGroupCommandBufferBeginInfo.adoc[] 3346 3347ifdef::VK_KHR_device_group[] 3348or the equivalent 3349 3350include::{generated}/api/structs/VkDeviceGroupCommandBufferBeginInfoKHR.adoc[] 3351endif::VK_KHR_device_group[] 3352 3353 * pname:sType is a elink:VkStructureType value identifying this structure. 3354 * pname:pNext is `NULL` or a pointer to a structure extending this 3355 structure. 3356 * pname:deviceMask is the initial value of the command buffer's device 3357 mask. 3358 3359The initial device mask also acts as an upper bound on the set of devices 3360that can: ever be in the device mask in the command buffer. 3361 3362If this structure is not present, the initial value of a command buffer's 3363device mask is set to include all physical devices in the logical device 3364when the command buffer begins recording. 3365 3366.Valid Usage 3367**** 3368 * [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00106]] 3369 pname:deviceMask must: be a valid device mask value 3370 * [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00107]] 3371 pname:deviceMask must: not be zero 3372**** 3373 3374include::{generated}/validity/structs/VkDeviceGroupCommandBufferBeginInfo.adoc[] 3375-- 3376 3377[open,refpage='vkCmdSetDeviceMask',desc='Modify device mask of a command buffer',type='protos'] 3378-- 3379To update the current device mask of a command buffer, call: 3380 3381ifdef::VK_VERSION_1_1[] 3382include::{generated}/api/protos/vkCmdSetDeviceMask.adoc[] 3383endif::VK_VERSION_1_1[] 3384 3385ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] 3386 3387ifdef::VK_KHR_device_group[] 3388include::{generated}/api/protos/vkCmdSetDeviceMaskKHR.adoc[] 3389endif::VK_KHR_device_group[] 3390 3391 * pname:commandBuffer is command buffer whose current device mask is 3392 modified. 3393 * pname:deviceMask is the new value of the current device mask. 3394 3395pname:deviceMask is used to filter out subsequent commands from executing on 3396all physical devices whose bit indices are not set in the mask, except 3397commands beginning a render pass instance, commands transitioning to the 3398next subpass in the render pass instance, and commands ending a render pass 3399instance, which always execute on the set of physical devices whose bit 3400indices are included in the pname:deviceMask member of the 3401slink:VkDeviceGroupRenderPassBeginInfo structure passed to the command 3402beginning the corresponding render pass instance. 3403 3404.Valid Usage 3405**** 3406 * [[VUID-vkCmdSetDeviceMask-deviceMask-00108]] 3407 pname:deviceMask must: be a valid device mask value 3408 * [[VUID-vkCmdSetDeviceMask-deviceMask-00109]] 3409 pname:deviceMask must: not be zero 3410 * [[VUID-vkCmdSetDeviceMask-deviceMask-00110]] 3411 pname:deviceMask must: not include any set bits that were not in the 3412 slink:VkDeviceGroupCommandBufferBeginInfo::pname:deviceMask value when 3413 the command buffer began recording 3414 * [[VUID-vkCmdSetDeviceMask-deviceMask-00111]] 3415 If fname:vkCmdSetDeviceMask is called inside a render pass instance, 3416 pname:deviceMask must: not include any set bits that were not in the 3417 slink:VkDeviceGroupRenderPassBeginInfo::pname:deviceMask value when the 3418 render pass instance began recording 3419**** 3420 3421include::{generated}/validity/protos/vkCmdSetDeviceMask.adoc[] 3422-- 3423endif::VK_VERSION_1_1,VK_KHR_device_group[] 3424
