cmdbuffers.txt
1 // Copyright (c) 2015-2019 Khronos Group. This work is licensed under a 2 // Creative Commons Attribution 4.0 International License; see 3 // http://creativecommons.org/licenses/by/4.0/ 4 5 [[commandbuffers]] 6 = Command Buffers 7 8 [open,refpage='VkCommandBuffer',desc='Opaque handle to a command buffer object',type='handles'] 9 -- 10 11 Command buffers are objects used to record commands which can: be 12 subsequently submitted to a device queue for execution. 13 There are two levels of command buffers - _primary command buffers_, which 14 can: execute secondary command buffers, and which are submitted to queues, 15 and _secondary command buffers_, which can: be executed by primary command 16 buffers, and which are not directly submitted to queues. 17 18 Command buffers are represented by sname:VkCommandBuffer handles: 19 20 include::{generated}/api/handles/VkCommandBuffer.txt[] 21 22 -- 23 24 Recorded commands include commands to bind pipelines and descriptor sets to 25 the command buffer, commands to modify dynamic state, commands to draw (for 26 graphics rendering), commands to dispatch (for compute), commands to execute 27 secondary command buffers (for primary command buffers only), commands to 28 copy buffers and images, and other commands. 29 30 [[commandbuffers-statereset]] 31 Each command buffer manages state independently of other command buffers. 32 There is no inheritance of state across primary and secondary command 33 buffers, or between secondary command buffers. 34 When a command buffer begins recording, all state in that command buffer is 35 undefined:. 36 When secondary command buffer(s) are recorded to execute on a primary 37 command buffer, the secondary command buffer inherits no state from the 38 primary command buffer, and all state of the primary command buffer is 39 undefined: after an execute secondary command buffer command is recorded. 40 There is one exception to this rule - if the primary command buffer is 41 inside a render pass instance, then the render pass and subpass state is not 42 disturbed by executing secondary command buffers. 43 For state dependent commands (such as draws and dispatches), any state 44 consumed by those commands must: not be undefined:. 45 46 Unless otherwise specified, and without explicit synchronization, the 47 various commands submitted to a queue via command buffers may: execute in 48 arbitrary order relative to each other, and/or concurrently. 49 Also, the memory side-effects of those commands may: not be directly visible 50 to other commands without explicit memory dependencies. 51 This is true within a command buffer, and across command buffers submitted 52 to a given queue. 53 See <<synchronization, the synchronization chapter>> for information on 54 <<synchronization-implicit, implicit>> and explicit synchronization between 55 commands. 56 57 58 [[commandbuffers-lifecycle]] 59 == Command Buffer Lifecycle 60 61 Each command buffer is always in one of the following states: 62 63 Initial:: 64 When a command buffer is <<vkAllocateCommandBuffers, allocated>>, it is 65 in the _initial state_. 66 Some commands are able to _reset_ a command buffer, or a set of command 67 buffers, back to this state from any of the executable, recording or 68 invalid state. 69 Command buffers in the initial state can: only be moved to the recording 70 state, or freed. 71 Recording:: 72 flink:vkBeginCommandBuffer changes the state of a command buffer from 73 the initial state to the _recording state_. 74 Once a command buffer is in the recording state, ftext:vkCmd* commands 75 can: be used to record to the command buffer. 76 Executable:: 77 flink:vkEndCommandBuffer ends the recording of a command buffer, and 78 moves it from the recording state to the _executable state_. 79 Executable command buffers can: be <<commandbuffers-submission, 80 submitted>>, reset, or <<commandbuffers-secondary, recorded to another 81 command buffer>>. 82 Pending:: 83 <<commandbuffers-submission, Queue submission>> of a command buffer 84 changes the state of a command buffer from the executable state to the 85 _pending state_. 86 Whilst in the pending state, applications must: not attempt to modify 87 the command buffer in any way - as the device may: be processing the 88 commands recorded to it. 89 Once execution of a command buffer completes, the command buffer reverts 90 back to either the _executable state_, or the _invalid state_ if it was 91 recorded with ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT. 92 A <<synchronization, synchronization>> command should: be used to detect 93 when this occurs. 94 Invalid:: 95 Some operations, such as <<fundamentals-objectmodel-lifetime-cmdbuffers, 96 modifying or deleting a resource>> that was used in a command recorded 97 to a command buffer, will transition the state of that command buffer 98 into the _invalid state_. 99 Command buffers in the invalid state can: only be reset or freed. 100 101 [[commandbuffer-lifecycle-diagram]] 102 image::{images}/commandbuffer_lifecycle.svg[title="Lifecycle of a command buffer",align="center",opts="{imageopts}"] 103 104 Any given command that operates on a command buffer has its own requirements 105 on what state a command buffer must: be in, which are detailed in the valid 106 usage constraints for that command. 107 108 Resetting a command buffer is an operation that discards any previously 109 recorded commands and puts a command buffer in the initial state. 110 Resetting occurs as a result of flink:vkResetCommandBuffer or 111 flink:vkResetCommandPool, or as part of flink:vkBeginCommandBuffer (which 112 additionally puts the command buffer in the recording state). 113 114 <<commandbuffers-secondary, Secondary command buffers>> can: be recorded to 115 a primary command buffer via flink:vkCmdExecuteCommands. 116 This partially ties the lifecycle of the two command buffers together - if 117 the primary is submitted to a queue, both the primary and any secondaries 118 recorded to it move to the pending state. 119 Once execution of the primary completes, so does any secondary recorded 120 within it, and once all executions of each command buffer complete, they 121 move to the executable state. 122 If a secondary moves to any other state whilst it is recorded to another 123 command buffer, the primary moves to the invalid state. 124 A primary moving to any other state does not affect the state of the 125 secondary. 126 Resetting or freeing a primary command buffer removes the linkage to any 127 secondary command buffers that were recorded to it. 128 129 130 [[commandbuffers-pools]] 131 == Command Pools 132 133 [open,refpage='VkCommandPool',desc='Opaque handle to a command pool object',type='handles'] 134 -- 135 136 Command pools are opaque objects that command buffer memory is allocated 137 from, and which allow the implementation to amortize the cost of resource 138 creation across multiple command buffers. 139 Command pools are externally synchronized, meaning that a command pool must: 140 not be used concurrently in multiple threads. 141 That includes use via recording commands on any command buffers allocated 142 from the pool, as well as operations that allocate, free, and reset command 143 buffers or the pool itself. 144 145 Command pools are represented by sname:VkCommandPool handles: 146 147 include::{generated}/api/handles/VkCommandPool.txt[] 148 149 -- 150 151 [open,refpage='vkCreateCommandPool',desc='Create a new command pool object',type='protos'] 152 -- 153 154 To create a command pool, call: 155 156 include::{generated}/api/protos/vkCreateCommandPool.txt[] 157 158 * pname:device is the logical device that creates the command pool. 159 * pname:pCreateInfo is a pointer to an instance of the 160 slink:VkCommandPoolCreateInfo structure specifying the state of the 161 command pool object. 162 * pname:pAllocator controls host memory allocation as described in the 163 <<memory-allocation, Memory Allocation>> chapter. 164 * pname:pCommandPool points to a slink:VkCommandPool handle in which the 165 created pool is returned. 166 167 .Valid Usage 168 **** 169 * [[VUID-vkCreateCommandPool-queueFamilyIndex-01937]] 170 pname:pCreateInfo::pname:queueFamilyIndex must: be the index of a queue 171 family available in the logical device pname:device. 172 **** 173 174 include::{generated}/validity/protos/vkCreateCommandPool.txt[] 175 -- 176 177 [open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] 178 -- 179 180 The sname:VkCommandPoolCreateInfo structure is defined as: 181 182 include::{generated}/api/structs/VkCommandPoolCreateInfo.txt[] 183 184 * pname:sType is the type of this structure. 185 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 186 * pname:flags is a bitmask of elink:VkCommandPoolCreateFlagBits indicating 187 usage behavior for the pool and command buffers allocated from it. 188 * pname:queueFamilyIndex designates a queue family as described in section 189 <<devsandqueues-queueprops,Queue Family Properties>>. 190 All command buffers allocated from this command pool must: be submitted 191 on queues from the same queue family. 192 193 include::{generated}/validity/structs/VkCommandPoolCreateInfo.txt[] 194 -- 195 196 [open,refpage='VkCommandPoolCreateFlagBits',desc='Bitmask specifying usage behavior for a command pool',type='enums'] 197 -- 198 199 Bits which can: be set in slink:VkCommandPoolCreateInfo::pname:flags to 200 specify usage behavior for a command pool are: 201 202 include::{generated}/api/enums/VkCommandPoolCreateFlagBits.txt[] 203 204 * ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT specifies that command 205 buffers allocated from the pool will be short-lived, meaning that they 206 will be reset or freed in a relatively short timeframe. 207 This flag may: be used by the implementation to control memory 208 allocation behavior within the pool. 209 * ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT allows any command 210 buffer allocated from a pool to be individually reset to the 211 <<commandbuffers-lifecycle, initial state>>; either by calling 212 flink:vkResetCommandBuffer, or via the implicit reset when calling 213 flink:vkBeginCommandBuffer. 214 If this flag is not set on a pool, then fname:vkResetCommandBuffer must: 215 not be called for any command buffer allocated from that pool. 216 ifdef::VK_VERSION_1_1[] 217 * ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT specifies that command 218 buffers allocated from the pool are protected command buffers. 219 If the protected memory feature is not enabled, the 220 ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT bit of pname:flags must: not 221 be set. 222 endif::VK_VERSION_1_1[] 223 224 -- 225 226 [open,refpage='VkCommandPoolCreateFlags',desc='Bitmask of VkCommandPoolCreateFlagBits',type='flags'] 227 -- 228 include::{generated}/api/flags/VkCommandPoolCreateFlags.txt[] 229 230 tname:VkCommandPoolCreateFlags is a bitmask type for setting a mask of zero 231 or more elink:VkCommandPoolCreateFlagBits. 232 -- 233 234 ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 235 236 [open,refpage='vkTrimCommandPool',desc='Trim a command pool',type='protos'] 237 -- 238 239 To trim a command pool, call: 240 241 ifdef::VK_VERSION_1_1[] 242 include::{generated}/api/protos/vkTrimCommandPool.txt[] 243 endif::VK_VERSION_1_1[] 244 245 ifdef::VK_VERSION_1_1+VK_KHR_maintenance1[or the equivalent command] 246 247 ifdef::VK_KHR_maintenance1[] 248 include::{generated}/api/protos/vkTrimCommandPoolKHR.txt[] 249 endif::VK_KHR_maintenance1[] 250 251 * pname:device is the logical device that owns the command pool. 252 * pname:commandPool is the command pool to trim. 253 * pname:flags is reserved for future use. 254 255 Trimming a command pool recycles unused memory from the command pool back to 256 the system. 257 Command buffers allocated from the pool are not affected by the command. 258 259 [NOTE] 260 .Note 261 ==== 262 This command provides applications with some control over the internal 263 memory allocations used by command pools. 264 265 Unused memory normally arises from command buffers that have been recorded 266 and later reset, such that they are no longer using the memory. 267 On reset, a command buffer can return memory to its command pool, but the 268 only way to release memory from a command pool to the system requires 269 calling flink:vkResetCommandPool, which cannot be executed while any command 270 buffers from that pool are still in use. 271 Subsequent recording operations into command buffers will re-use this memory 272 but since total memory requirements fluctuate over time, unused memory can 273 accumulate. 274 275 In this situation, trimming a command pool may: be useful to return unused 276 memory back to the system, returning the total outstanding memory allocated 277 by the pool back to a more "`average`" value. 278 279 Implementations utilize many internal allocation strategies that make it 280 impossible to guarantee that all unused memory is released back to the 281 system. 282 For instance, an implementation of a command pool may: involve allocating 283 memory in bulk from the system and sub-allocating from that memory. 284 In such an implementation any live command buffer that holds a reference to 285 a bulk allocation would prevent that allocation from being freed, even if 286 only a small proportion of the bulk allocation is in use. 287 288 In most cases trimming will result in a reduction in allocated but unused 289 memory, but it does not guarantee the "`ideal`" behavior. 290 291 Trimming may: be an expensive operation, and should: not be called 292 frequently. 293 Trimming should: be treated as a way to relieve memory pressure after 294 application-known points when there exists enough unused memory that the 295 cost of trimming is "`worth`" it. 296 ==== 297 298 include::{generated}/validity/protos/vkTrimCommandPool.txt[] 299 -- 300 301 [open,refpage='VkCommandPoolTrimFlags',desc='Reserved for future use',type='flags'] 302 -- 303 include::{generated}/api/flags/VkCommandPoolTrimFlags.txt[] 304 305 ifdef::VK_KHR_maintenance1[] 306 or the equivalent 307 308 include::{generated}/api/flags/VkCommandPoolTrimFlagsKHR.txt[] 309 endif::VK_KHR_maintenance1[] 310 311 tname:VkCommandPoolTrimFlags is a bitmask type for setting a mask, but is 312 currently reserved for future use. 313 -- 314 315 endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 316 317 [open,refpage='vkResetCommandPool',desc='Reset a command pool',type='protos'] 318 -- 319 320 To reset a command pool, call: 321 322 include::{generated}/api/protos/vkResetCommandPool.txt[] 323 324 * pname:device is the logical device that owns the command pool. 325 * pname:commandPool is the command pool to reset. 326 * pname:flags is a bitmask of elink:VkCommandPoolResetFlagBits controlling 327 the reset operation. 328 329 Resetting a command pool recycles all of the resources from all of the 330 command buffers allocated from the command pool back to the command pool. 331 All command buffers that have been allocated from the command pool are put 332 in the <<commandbuffers-lifecycle, initial state>>. 333 334 Any primary command buffer allocated from another slink:VkCommandPool that 335 is in the <<commandbuffers-lifecycle, recording or executable state>> and 336 has a secondary command buffer allocated from pname:commandPool recorded 337 into it, becomes <<commandbuffers-lifecycle, invalid>>. 338 339 .Valid Usage 340 **** 341 * [[VUID-vkResetCommandPool-commandPool-00040]] 342 All sname:VkCommandBuffer objects allocated from pname:commandPool must: 343 not be in the <<commandbuffers-lifecycle, pending state>> 344 **** 345 346 include::{generated}/validity/protos/vkResetCommandPool.txt[] 347 -- 348 349 [open,refpage='VkCommandPoolResetFlagBits',desc='Bitmask controlling behavior of a command pool reset',type='enums'] 350 -- 351 352 Bits which can: be set in flink:vkResetCommandPool::pname:flags to control 353 the reset operation are: 354 355 include::{generated}/api/enums/VkCommandPoolResetFlagBits.txt[] 356 357 * ename:VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT specifies that 358 resetting a command pool recycles all of the resources from the command 359 pool back to the system. 360 361 -- 362 363 [open,refpage='VkCommandPoolResetFlags',desc='Bitmask of VkCommandPoolResetFlagBits',type='flags'] 364 -- 365 include::{generated}/api/flags/VkCommandPoolResetFlags.txt[] 366 367 tname:VkCommandPoolResetFlags is a bitmask type for setting a mask of zero 368 or more elink:VkCommandPoolResetFlagBits. 369 -- 370 371 [open,refpage='vkDestroyCommandPool',desc='Destroy a command pool object',type='protos'] 372 -- 373 374 To destroy a command pool, call: 375 376 include::{generated}/api/protos/vkDestroyCommandPool.txt[] 377 378 * pname:device is the logical device that destroys the command pool. 379 * pname:commandPool is the handle of the command pool to destroy. 380 * pname:pAllocator controls host memory allocation as described in the 381 <<memory-allocation, Memory Allocation>> chapter. 382 383 When a pool is destroyed, all command buffers allocated from the pool are 384 <<vkFreeCommandBuffers, freed>>. 385 386 Any primary command buffer allocated from another slink:VkCommandPool that 387 is in the <<commandbuffers-lifecycle, recording or executable state>> and 388 has a secondary command buffer allocated from pname:commandPool recorded 389 into it, becomes <<commandbuffers-lifecycle, invalid>>. 390 391 .Valid Usage 392 **** 393 * [[VUID-vkDestroyCommandPool-commandPool-00041]] 394 All sname:VkCommandBuffer objects allocated from pname:commandPool must: 395 not be in the <<commandbuffers-lifecycle, pending state>>. 396 * [[VUID-vkDestroyCommandPool-commandPool-00042]] 397 If sname:VkAllocationCallbacks were provided when pname:commandPool was 398 created, a compatible set of callbacks must: be provided here 399 * [[VUID-vkDestroyCommandPool-commandPool-00043]] 400 If no sname:VkAllocationCallbacks were provided when pname:commandPool 401 was created, pname:pAllocator must: be `NULL` 402 **** 403 404 include::{generated}/validity/protos/vkDestroyCommandPool.txt[] 405 -- 406 407 408 [[commandbuffer-allocation]] 409 == Command Buffer Allocation and Management 410 411 [open,refpage='vkAllocateCommandBuffers',desc='Allocate command buffers from an existing command pool',type='protos'] 412 -- 413 414 To allocate command buffers, call: 415 416 include::{generated}/api/protos/vkAllocateCommandBuffers.txt[] 417 418 * pname:device is the logical device that owns the command pool. 419 * pname:pAllocateInfo is a pointer to an instance of the 420 sname:VkCommandBufferAllocateInfo structure describing parameters of the 421 allocation. 422 * pname:pCommandBuffers is a pointer to an array of slink:VkCommandBuffer 423 handles in which the resulting command buffer objects are returned. 424 The array must: be at least the length specified by the 425 pname:commandBufferCount member of pname:pAllocateInfo. 426 Each allocated command buffer begins in the initial state. 427 428 ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 429 fname:vkAllocateCommandBuffers can: be used to create multiple command 430 buffers. 431 If the creation of any of those command buffers fails, the implementation 432 must: destroy all successfully created command buffer objects from this 433 command, set all entries of the pname:pCommandBuffers array to `NULL` and 434 return the error. 435 endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 436 437 When command buffers are first allocated, they are in the 438 <<commandbuffers-lifecycle, initial state>>. 439 440 include::{generated}/validity/protos/vkAllocateCommandBuffers.txt[] 441 -- 442 443 [open,refpage='VkCommandBufferAllocateInfo',desc='Structure specifying the allocation parameters for command buffer object',type='structs'] 444 -- 445 446 The sname:VkCommandBufferAllocateInfo structure is defined as: 447 448 include::{generated}/api/structs/VkCommandBufferAllocateInfo.txt[] 449 450 * pname:sType is the type of this structure. 451 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 452 * pname:commandPool is the command pool from which the command buffers are 453 allocated. 454 * pname:level is a elink:VkCommandBufferLevel value specifying the command 455 buffer level. 456 * pname:commandBufferCount is the number of command buffers to allocate 457 from the pool. 458 459 .Valid Usage 460 **** 461 * [[VUID-VkCommandBufferAllocateInfo-commandBufferCount-00044]] 462 pname:commandBufferCount must: be greater than `0` 463 **** 464 465 include::{generated}/validity/structs/VkCommandBufferAllocateInfo.txt[] 466 -- 467 468 [open,refpage='VkCommandBufferLevel',desc='Enumerant specifying a command buffer level',type='enums'] 469 -- 470 471 Possible values of slink:VkCommandBufferAllocateInfo::pname:level, 472 specifying the command buffer level, are: 473 474 include::{generated}/api/enums/VkCommandBufferLevel.txt[] 475 476 * ename:VK_COMMAND_BUFFER_LEVEL_PRIMARY specifies a primary command 477 buffer. 478 * ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY specifies a secondary command 479 buffer. 480 481 -- 482 483 [open,refpage='vkResetCommandBuffer',desc='Reset a command buffer to the initial state',type='protos'] 484 -- 485 486 To reset command buffers, call: 487 488 include::{generated}/api/protos/vkResetCommandBuffer.txt[] 489 490 * pname:commandBuffer is the command buffer to reset. 491 The command buffer can: be in any state other than 492 <<commandbuffers-lifecycle, pending>>, and is moved into the 493 <<commandbuffers-lifecycle, initial state>>. 494 * pname:flags is a bitmask of elink:VkCommandBufferResetFlagBits 495 controlling the reset operation. 496 497 Any primary command buffer that is in the <<commandbuffers-lifecycle, 498 recording or executable state>> and has pname:commandBuffer recorded into 499 it, becomes <<commandbuffers-lifecycle, invalid>>. 500 501 .Valid Usage 502 **** 503 * [[VUID-vkResetCommandBuffer-commandBuffer-00045]] 504 pname:commandBuffer must: not be in the <<commandbuffers-lifecycle, 505 pending state>> 506 * [[VUID-vkResetCommandBuffer-commandBuffer-00046]] 507 pname:commandBuffer must: have been allocated from a pool that was 508 created with the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT 509 **** 510 511 include::{generated}/validity/protos/vkResetCommandBuffer.txt[] 512 -- 513 514 [open,refpage='VkCommandBufferResetFlagBits',desc='Bitmask controlling behavior of a command buffer reset',type='enums'] 515 -- 516 517 Bits which can: be set in flink:vkResetCommandBuffer::pname:flags to control 518 the reset operation are: 519 520 include::{generated}/api/enums/VkCommandBufferResetFlagBits.txt[] 521 522 * ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT specifies that most 523 or all memory resources currently owned by the command buffer should: be 524 returned to the parent command pool. 525 If this flag is not set, then the command buffer may: hold onto memory 526 resources and reuse them when recording commands. 527 pname:commandBuffer is moved to the <<commandbuffers-lifecycle, initial 528 state>>. 529 530 -- 531 532 [open,refpage='VkCommandBufferResetFlags',desc='Bitmask of VkCommandBufferResetFlagBits',type='flags'] 533 -- 534 include::{generated}/api/flags/VkCommandBufferResetFlags.txt[] 535 536 tname:VkCommandBufferResetFlags is a bitmask type for setting a mask of zero 537 or more elink:VkCommandBufferResetFlagBits. 538 -- 539 540 [open,refpage='vkFreeCommandBuffers',desc='Free command buffers',type='protos'] 541 -- 542 543 To free command buffers, call: 544 545 include::{generated}/api/protos/vkFreeCommandBuffers.txt[] 546 547 * pname:device is the logical device that owns the command pool. 548 * pname:commandPool is the command pool from which the command buffers 549 were allocated. 550 * pname:commandBufferCount is the length of the pname:pCommandBuffers 551 array. 552 * pname:pCommandBuffers is an array of handles of command buffers to free. 553 554 Any primary command buffer that is in the <<commandbuffers-lifecycle, 555 recording or executable state>> and has any element of pname:pCommandBuffers 556 recorded into it, becomes <<commandbuffers-lifecycle, invalid>>. 557 558 .Valid Usage 559 **** 560 * [[VUID-vkFreeCommandBuffers-pCommandBuffers-00047]] 561 All elements of pname:pCommandBuffers must: not be in the 562 <<commandbuffers-lifecycle, pending state>> 563 * [[VUID-vkFreeCommandBuffers-pCommandBuffers-00048]] 564 pname:pCommandBuffers must: be a valid pointer to an array of 565 pname:commandBufferCount sname:VkCommandBuffer handles, each element of 566 which must: either be a valid handle or `NULL` 567 **** 568 569 include::{generated}/validity/protos/vkFreeCommandBuffers.txt[] 570 -- 571 572 573 [[commandbuffers-recording]] 574 == Command Buffer Recording 575 576 [open,refpage='vkBeginCommandBuffer',desc='Start recording a command buffer',type='protos'] 577 -- 578 579 To begin recording a command buffer, call: 580 581 include::{generated}/api/protos/vkBeginCommandBuffer.txt[] 582 583 * pname:commandBuffer is the handle of the command buffer which is to be 584 put in the recording state. 585 * pname:pBeginInfo is an instance of the slink:VkCommandBufferBeginInfo 586 structure, which defines additional information about how the command 587 buffer begins recording. 588 589 .Valid Usage 590 **** 591 * [[VUID-vkBeginCommandBuffer-commandBuffer-00049]] 592 pname:commandBuffer must: not be in the <<commandbuffers-lifecycle, 593 recording or pending state>>. 594 * [[VUID-vkBeginCommandBuffer-commandBuffer-00050]] 595 If pname:commandBuffer was allocated from a slink:VkCommandPool which 596 did not have the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT 597 flag set, pname:commandBuffer must: be in the 598 <<commandbuffers-lifecycle, initial state>>. 599 * [[VUID-vkBeginCommandBuffer-commandBuffer-00051]] 600 If pname:commandBuffer is a secondary command buffer, the 601 pname:pInheritanceInfo member of pname:pBeginInfo must: be a valid 602 sname:VkCommandBufferInheritanceInfo structure 603 * [[VUID-vkBeginCommandBuffer-commandBuffer-00052]] 604 If pname:commandBuffer is a secondary command buffer and either the 605 pname:occlusionQueryEnable member of the pname:pInheritanceInfo member 606 of pname:pBeginInfo is ename:VK_FALSE, or the precise occlusion queries 607 feature is not enabled, the pname:queryFlags member of the 608 pname:pInheritanceInfo member pname:pBeginInfo must: not contain 609 ename:VK_QUERY_CONTROL_PRECISE_BIT 610 **** 611 612 include::{generated}/validity/protos/vkBeginCommandBuffer.txt[] 613 -- 614 615 [open,refpage='VkCommandBufferBeginInfo',desc='Structure specifying a command buffer begin operation',type='structs'] 616 -- 617 618 The sname:VkCommandBufferBeginInfo structure is defined as: 619 620 include::{generated}/api/structs/VkCommandBufferBeginInfo.txt[] 621 622 * pname:sType is the type of this structure. 623 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 624 * pname:flags is a bitmask of elink:VkCommandBufferUsageFlagBits 625 specifying usage behavior for the command buffer. 626 * pname:pInheritanceInfo is a pointer to a 627 sname:VkCommandBufferInheritanceInfo structure, which is used if 628 pname:commandBuffer is a secondary command buffer. 629 If this is a primary command buffer, then this value is ignored. 630 631 .Valid Usage 632 **** 633 * [[VUID-VkCommandBufferBeginInfo-flags-00053]] 634 If pname:flags contains 635 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the 636 pname:renderPass member of pname:pInheritanceInfo must: be a valid 637 sname:VkRenderPass 638 * [[VUID-VkCommandBufferBeginInfo-flags-00054]] 639 If pname:flags contains 640 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the 641 pname:subpass member of pname:pInheritanceInfo must: be a valid subpass 642 index within the pname:renderPass member of pname:pInheritanceInfo 643 * [[VUID-VkCommandBufferBeginInfo-flags-00055]] 644 If pname:flags contains 645 ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the 646 pname:framebuffer member of pname:pInheritanceInfo must: be either 647 dlink:VK_NULL_HANDLE, or a valid sname:VkFramebuffer that is compatible 648 with the pname:renderPass member of pname:pInheritanceInfo 649 **** 650 651 include::{generated}/validity/structs/VkCommandBufferBeginInfo.txt[] 652 -- 653 654 [open,refpage='VkCommandBufferUsageFlagBits',desc='Bitmask specifying usage behavior for command buffer',type='enums'] 655 -- 656 657 Bits which can: be set in slink:VkCommandBufferBeginInfo::pname:flags to 658 specify usage behavior for a command buffer are: 659 660 include::{generated}/api/enums/VkCommandBufferUsageFlagBits.txt[] 661 662 * ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT specifies that each 663 recording of the command buffer will only be submitted once, and the 664 command buffer will be reset and recorded again between each submission. 665 * ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT specifies that a 666 secondary command buffer is considered to be entirely inside a render 667 pass. 668 If this is a primary command buffer, then this bit is ignored. 669 * ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT specifies that a 670 command buffer can: be resubmitted to a queue while it is in the 671 _pending state_, and recorded into multiple primary command buffers. 672 673 -- 674 675 [open,refpage='VkCommandBufferUsageFlags',desc='Bitmask of VkCommandBufferUsageFlagBits',type='flags'] 676 -- 677 include::{generated}/api/flags/VkCommandBufferUsageFlags.txt[] 678 679 tname:VkCommandBufferUsageFlags is a bitmask type for setting a mask of zero 680 or more elink:VkCommandBufferUsageFlagBits. 681 -- 682 683 [open,refpage='VkCommandBufferInheritanceInfo',desc='Structure specifying command buffer inheritance info',type='structs'] 684 -- 685 686 If the command buffer is a secondary command buffer, then the 687 sname:VkCommandBufferInheritanceInfo structure defines any state that will 688 be inherited from the primary command buffer: 689 690 include::{generated}/api/structs/VkCommandBufferInheritanceInfo.txt[] 691 692 * pname:sType is the type of this structure. 693 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 694 * pname:renderPass is a slink:VkRenderPass object defining which render 695 passes the sname:VkCommandBuffer will be <<renderpass-compatibility, 696 compatible>> with and can: be executed within. 697 If the sname:VkCommandBuffer will not be executed within a render pass 698 instance, pname:renderPass is ignored. 699 * pname:subpass is the index of the subpass within the render pass 700 instance that the sname:VkCommandBuffer will be executed within. 701 If the sname:VkCommandBuffer will not be executed within a render pass 702 instance, pname:subpass is ignored. 703 * pname:framebuffer optionally refers to the slink:VkFramebuffer object 704 that the sname:VkCommandBuffer will be rendering to if it is executed 705 within a render pass instance. 706 It can: be dlink:VK_NULL_HANDLE if the framebuffer is not known, or if 707 the sname:VkCommandBuffer will not be executed within a render pass 708 instance. 709 + 710 [NOTE] 711 .Note 712 ==== 713 Specifying the exact framebuffer that the secondary command buffer will be 714 executed with may: result in better performance at command buffer execution 715 time. 716 ==== 717 * pname:occlusionQueryEnable specifies whether the command buffer can: be 718 executed while an occlusion query is active in the primary command 719 buffer. 720 If this is ename:VK_TRUE, then this command buffer can: be executed 721 whether the primary command buffer has an occlusion query active or not. 722 If this is ename:VK_FALSE, then the primary command buffer must: not 723 have an occlusion query active. 724 * pname:queryFlags specifies the query flags that can: be used by an 725 active occlusion query in the primary command buffer when this secondary 726 command buffer is executed. 727 If this value includes the ename:VK_QUERY_CONTROL_PRECISE_BIT bit, then 728 the active query can: return boolean results or actual sample counts. 729 If this bit is not set, then the active query must: not use the 730 ename:VK_QUERY_CONTROL_PRECISE_BIT bit. 731 * pname:pipelineStatistics is a bitmask of 732 elink:VkQueryPipelineStatisticFlagBits specifying the set of pipeline 733 statistics that can: be counted by an active query in the primary 734 command buffer when this secondary command buffer is executed. 735 If this value includes a given bit, then this command buffer can: be 736 executed whether the primary command buffer has a pipeline statistics 737 query active that includes this bit or not. 738 If this value excludes a given bit, then the active pipeline statistics 739 query must: not be from a query pool that counts that statistic. 740 741 .Valid Usage 742 **** 743 * [[VUID-VkCommandBufferInheritanceInfo-occlusionQueryEnable-00056]] 744 If the <<features-inheritedQueries,inherited queries>> feature is not 745 enabled, pname:occlusionQueryEnable must: be ename:VK_FALSE 746 * [[VUID-VkCommandBufferInheritanceInfo-queryFlags-00057]] 747 If the <<features-inheritedQueries,inherited queries>> feature is 748 enabled, pname:queryFlags must: be a valid combination of 749 elink:VkQueryControlFlagBits values 750 * [[VUID-VkCommandBufferInheritanceInfo-pipelineStatistics-00058]] 751 If the <<features-pipelineStatisticsQuery,pipeline statistics queries>> 752 feature is not enabled, pname:pipelineStatistics must: be code:0 753 **** 754 755 include::{generated}/validity/structs/VkCommandBufferInheritanceInfo.txt[] 756 -- 757 758 If ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT was not set when 759 creating a command buffer, that command buffer must: not be submitted to a 760 queue whilst it is already in the <<commandbuffers-lifecycle, pending 761 state>>. 762 If ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT is not set on a 763 secondary command buffer, that command buffer must: not be used more than 764 once in a given primary command buffer. 765 766 [NOTE] 767 .Note 768 ==== 769 On some implementations, not using the 770 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT bit enables command 771 buffers to be patched in-place if needed, rather than creating a copy of the 772 command buffer. 773 ==== 774 775 If a command buffer is in the <<commandbuffers-lifecycle, invalid, or 776 executable state>>, and the command buffer was allocated from a command pool 777 with the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, 778 then fname:vkBeginCommandBuffer implicitly resets the command buffer, 779 behaving as if fname:vkResetCommandBuffer had been called with 780 ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT not set. 781 After the implicit reset, pname:commandBuffer is moved to the 782 <<commandbuffers-lifecycle, recording state>>. 783 784 ifdef::VK_EXT_conditional_rendering[] 785 786 [open,refpage='VkCommandBufferInheritanceConditionalRenderingInfoEXT',desc='Structure specifying command buffer inheritance info',type='structs'] 787 -- 788 789 If the pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes a 790 sname:VkCommandBufferInheritanceConditionalRenderingInfoEXT structure, then 791 that structure controls whether a command buffer can: be executed while 792 conditional rendering is <<active-conditional-rendering,active>> in the 793 primary command buffer. 794 795 The sname:VkCommandBufferInheritanceConditionalRenderingInfoEXT structure is 796 defined as: 797 798 include::{generated}/api/structs/VkCommandBufferInheritanceConditionalRenderingInfoEXT.txt[] 799 800 * pname:sType is the type of this structure 801 * pname:pNext is `NULL` or a pointer to an extension-specific structure 802 * pname:conditionalRenderingEnable specifies whether the command buffer 803 can: be executed while conditional rendering is active in the primary 804 command buffer. 805 If this is ename:VK_TRUE, then this command buffer can: be executed 806 whether the primary command buffer has active conditional rendering or 807 not. 808 If this is ename:VK_FALSE, then the primary command buffer must: not 809 have conditional rendering active. 810 811 If this structure is not present, the behavior is as if 812 pname:conditionalRenderingEnable is ename:VK_FALSE. 813 814 .Valid Usage 815 **** 816 * [[VUID-VkCommandBufferInheritanceConditionalRenderingInfoEXT-conditionalRenderingEnable-01977]] 817 If the <<features-inheritedConditionalRendering, inherited conditional 818 rendering>> feature is not enabled, pname:conditionalRenderingEnable 819 must: be ename:VK_FALSE 820 **** 821 822 include::{generated}/validity/structs/VkCommandBufferInheritanceConditionalRenderingInfoEXT.txt[] 823 -- 824 825 endif::VK_EXT_conditional_rendering[] 826 Once recording starts, an application records a sequence of commands 827 (ftext:vkCmd*) to set state in the command buffer, draw, dispatch, and other 828 commands. 829 830 ifdef::VK_NVX_device_generated_commands[] 831 Several commands can also be recorded indirectly from sname:VkBuffer 832 content, see <<device-generated-commands>>. 833 endif::VK_NVX_device_generated_commands[] 834 835 [open,refpage='vkEndCommandBuffer',desc='Finish recording a command buffer',type='protos'] 836 -- 837 838 To complete recording of a command buffer, call: 839 840 include::{generated}/api/protos/vkEndCommandBuffer.txt[] 841 842 * pname:commandBuffer is the command buffer to complete recording. 843 844 If there was an error during recording, the application will be notified by 845 an unsuccessful return code returned by fname:vkEndCommandBuffer. 846 If the application wishes to further use the command buffer, the command 847 buffer must: be reset. 848 The command buffer must: have been in the <<commandbuffers-lifecycle, 849 recording state>>, and is moved to the <<commandbuffers-lifecycle, 850 executable state>>. 851 852 .Valid Usage 853 **** 854 * [[VUID-vkEndCommandBuffer-commandBuffer-00059]] 855 pname:commandBuffer must: be in the <<commandbuffers-lifecycle, 856 recording state>>. 857 * [[VUID-vkEndCommandBuffer-commandBuffer-00060]] 858 If pname:commandBuffer is a primary command buffer, there must: not be 859 an active render pass instance 860 * [[VUID-vkEndCommandBuffer-commandBuffer-00061]] 861 All queries made <<queries-operation-active,active>> during the 862 recording of pname:commandBuffer must: have been made inactive 863 ifdef::VK_EXT_conditional_rendering[] 864 * [[VUID-vkEndCommandBuffer-None-01978]] 865 Conditional rendering must not be 866 <<active-conditional-rendering,active>> 867 endif::VK_EXT_conditional_rendering[] 868 ifdef::VK_EXT_debug_utils[] 869 * [[VUID-vkEndCommandBuffer-commandBuffer-01815]] 870 If pname:commandBuffer is a secondary command buffer, there must: not be 871 an outstanding flink:vkCmdBeginDebugUtilsLabelEXT command recorded to 872 pname:commandBuffer that has not previously been ended by a call to 873 flink:vkCmdEndDebugUtilsLabelEXT. 874 endif::VK_EXT_debug_utils[] 875 ifdef::VK_EXT_debug_marker[] 876 * [[VUID-vkEndCommandBuffer-commandBuffer-00062]] 877 If pname:commandBuffer is a secondary command buffer, there must: not be 878 an outstanding flink:vkCmdDebugMarkerBeginEXT command recorded to 879 pname:commandBuffer that has not previously been ended by a call to 880 flink:vkCmdDebugMarkerEndEXT. 881 endif::VK_EXT_debug_marker[] 882 **** 883 884 include::{generated}/validity/protos/vkEndCommandBuffer.txt[] 885 -- 886 887 When a command buffer is in the executable state, it can: be submitted to a 888 queue for execution. 889 890 891 [[commandbuffers-submission]] 892 == Command Buffer Submission 893 894 [open,refpage='vkQueueSubmit',desc='Submits a sequence of semaphores or command buffers to a queue',type='protos'] 895 -- 896 897 To submit command buffers to a queue, call: 898 899 include::{generated}/api/protos/vkQueueSubmit.txt[] 900 901 * pname:queue is the queue that the command buffers will be submitted to. 902 * pname:submitCount is the number of elements in the pname:pSubmits array. 903 * pname:pSubmits is a pointer to an array of slink:VkSubmitInfo 904 structures, each specifying a command buffer submission batch. 905 * pname:fence is an optional: handle to a fence to be signaled once all 906 submitted command buffers have completed execution. 907 If pname:fence is not dlink:VK_NULL_HANDLE, it defines a 908 <<synchronization-fences-signaling, fence signal operation>>. 909 910 [NOTE] 911 .Note 912 ==== 913 Submission can be a high overhead operation, and applications should: 914 attempt to batch work together into as few calls to fname:vkQueueSubmit as 915 possible. 916 ==== 917 918 fname:vkQueueSubmit is a <<devsandqueues-submission,queue submission 919 command>>, with each batch defined by an element of pname:pSubmits as an 920 instance of the slink:VkSubmitInfo structure. 921 Batches begin execution in the order they appear in pname:pSubmits, but may: 922 complete out of order. 923 924 Fence and semaphore operations submitted with flink:vkQueueSubmit have 925 additional ordering constraints compared to other submission commands, with 926 dependencies involving previous and subsequent queue operations. 927 Information about these additional constraints can be found in the 928 <<synchronization-semaphores, semaphore>> and <<synchronization-fences, 929 fence>> sections of <<synchronization, the synchronization chapter>>. 930 931 Details on the interaction of pname:pWaitDstStageMask with synchronization 932 are described in the <<synchronization-semaphores-waiting, semaphore wait 933 operation>> section of <<synchronization, the synchronization chapter>>. 934 935 The order that batches appear in pname:pSubmits is used to determine 936 <<synchronization-submission-order, submission order>>, and thus all the 937 <<synchronization-implicit, implicit ordering guarantees>> that respect it. 938 Other than these implicit ordering guarantees and any <<synchronization, 939 explicit synchronization primitives>>, these batches may: overlap or 940 otherwise execute out of order. 941 942 If any command buffer submitted to this queue is in the 943 <<commandbuffers-lifecycle, executable state>>, it is moved to the 944 <<commandbuffers-lifecycle, pending state>>. 945 Once execution of all submissions of a command buffer complete, it moves 946 from the <<commandbuffers-lifecycle, pending state>>, back to the 947 <<commandbuffers-lifecycle, executable state>>. 948 If a command buffer was recorded with the 949 ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves 950 back to the <<commandbuffers-lifecycle, invalid state>>. 951 952 If fname:vkQueueSubmit fails, it may: return 953 ename:VK_ERROR_OUT_OF_HOST_MEMORY or ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 954 If it does, the implementation must: ensure that the state and contents of 955 any resources or synchronization primitives referenced by the submitted 956 command buffers and any semaphores referenced by pname:pSubmits is 957 unaffected by the call or its failure. 958 If fname:vkQueueSubmit fails in such a way that the implementation is unable 959 to make that guarantee, the implementation must: return 960 ename:VK_ERROR_DEVICE_LOST. 961 See <<devsandqueues-lost-device,Lost Device>>. 962 963 .Valid Usage 964 **** 965 * [[VUID-vkQueueSubmit-fence-00063]] 966 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be 967 unsignaled 968 * [[VUID-vkQueueSubmit-fence-00064]] 969 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be 970 associated with any other queue command that has not yet completed 971 execution on that queue 972 * [[VUID-vkQueueSubmit-pCommandBuffers-00065]] 973 Any calls to flink:vkCmdSetEvent, flink:vkCmdResetEvent or 974 flink:vkCmdWaitEvents that have been recorded into any of the command 975 buffer elements of the pname:pCommandBuffers member of any element of 976 pname:pSubmits, must: not reference any slink:VkEvent that is referenced 977 by any of those commands in a command buffer that has been submitted to 978 another queue and is still in the _pending state_. 979 * [[VUID-vkQueueSubmit-pWaitDstStageMask-00066]] 980 Any stage flag included in any element of the pname:pWaitDstStageMask 981 member of any element of pname:pSubmits must: be a pipeline stage 982 supported by one of the capabilities of pname:queue, as specified in the 983 <<synchronization-pipeline-stages-supported, table of supported pipeline 984 stages>>. 985 * [[VUID-vkQueueSubmit-pSignalSemaphores-00067]] 986 Each element of the pname:pSignalSemaphores member of any element of 987 pname:pSubmits must: be unsignaled when the semaphore signal operation 988 it defines is executed on the device 989 * [[VUID-vkQueueSubmit-pWaitSemaphores-00068]] 990 When a semaphore unsignal operation defined by any element of the 991 pname:pWaitSemaphores member of any element of pname:pSubmits executes 992 on pname:queue, no other queue must: be waiting on the same semaphore. 993 * [[VUID-vkQueueSubmit-pWaitSemaphores-00069]] 994 All elements of the pname:pWaitSemaphores member of all elements of 995 pname:pSubmits must: be semaphores that are signaled, or have 996 <<synchronization-semaphores-signaling, semaphore signal operations>> 997 previously submitted for execution. 998 * [[VUID-vkQueueSubmit-pCommandBuffers-00070]] 999 Each element of the pname:pCommandBuffers member of each element of 1000 pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or 1001 executable state>>. 1002 * [[VUID-vkQueueSubmit-pCommandBuffers-00071]] 1003 If any element of the pname:pCommandBuffers member of any element of 1004 pname:pSubmits was not recorded with the 1005 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 1006 the <<commandbuffers-lifecycle, pending state>>. 1007 * [[VUID-vkQueueSubmit-pCommandBuffers-00072]] 1008 Any <<commandbuffers-secondary, secondary command buffers recorded>> 1009 into any element of the pname:pCommandBuffers member of any element of 1010 pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or 1011 executable state>>. 1012 * [[VUID-vkQueueSubmit-pCommandBuffers-00073]] 1013 If any <<commandbuffers-secondary, secondary command buffers recorded>> 1014 into any element of the pname:pCommandBuffers member of any element of 1015 pname:pSubmits was not recorded with the 1016 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 1017 the <<commandbuffers-lifecycle, pending state>>. 1018 * [[VUID-vkQueueSubmit-pCommandBuffers-00074]] 1019 Each element of the pname:pCommandBuffers member of each element of 1020 pname:pSubmits must: have been allocated from a sname:VkCommandPool that 1021 was created for the same queue family pname:queue belongs to. 1022 * [[VUID-vkQueueSubmit-pSubmits-02207]] 1023 If any element of pname:pSubmits\->pname:pCommandBuffers includes a 1024 <<synchronization-queue-transfers-acquire, Queue Family Transfer Acquire 1025 Operation>>, there must: exist a previously submitted 1026 <<synchronization-queue-transfers-release, Queue Family Transfer Release 1027 Operation>> on a queue in the queue family identified by the acquire 1028 operation, with parameters matching the acquire operation as defined in 1029 the definition of such <<synchronization-queue-transfers-acquire, 1030 acquire operations>>, and which happens before the acquire operation. 1031 1032 **** 1033 1034 include::{generated}/validity/protos/vkQueueSubmit.txt[] 1035 -- 1036 1037 [open,refpage='VkSubmitInfo',desc='Structure specifying a queue submit operation',type='structs'] 1038 -- 1039 1040 The sname:VkSubmitInfo structure is defined as: 1041 1042 include::{generated}/api/structs/VkSubmitInfo.txt[] 1043 1044 * pname:sType is the type of this structure. 1045 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1046 * pname:waitSemaphoreCount is the number of semaphores upon which to wait 1047 before executing the command buffers for the batch. 1048 * pname:pWaitSemaphores is a pointer to an array of semaphores upon which 1049 to wait before the command buffers for this batch begin execution. 1050 If semaphores to wait on are provided, they define a 1051 <<synchronization-semaphores-waiting, semaphore wait operation>>. 1052 * pname:pWaitDstStageMask is a pointer to an array of pipeline stages at 1053 which each corresponding semaphore wait will occur. 1054 * pname:commandBufferCount is the number of command buffers to execute in 1055 the batch. 1056 * pname:pCommandBuffers is a pointer to an array of command buffers to 1057 execute in the batch. 1058 * pname:signalSemaphoreCount is the number of semaphores to be signaled 1059 once the commands specified in pname:pCommandBuffers have completed 1060 execution. 1061 * pname:pSignalSemaphores is a pointer to an array of semaphores which 1062 will be signaled when the command buffers for this batch have completed 1063 execution. 1064 If semaphores to be signaled are provided, they define a 1065 <<synchronization-semaphores-signaling, semaphore signal operation>>. 1066 1067 The order that command buffers appear in pname:pCommandBuffers is used to 1068 determine <<synchronization-submission-order, submission order>>, and thus 1069 all the <<synchronization-implicit, implicit ordering guarantees>> that 1070 respect it. 1071 Other than these implicit ordering guarantees and any <<synchronization, 1072 explicit synchronization primitives>>, these command buffers may: overlap or 1073 otherwise execute out of order. 1074 1075 1076 .Valid Usage 1077 **** 1078 * [[VUID-VkSubmitInfo-pCommandBuffers-00075]] 1079 Each element of pname:pCommandBuffers must: not have been allocated with 1080 ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 1081 * [[VUID-VkSubmitInfo-pWaitDstStageMask-00076]] 1082 If the <<features-geometryShader,geometry shaders>> feature is not 1083 enabled, each element of pname:pWaitDstStageMask must: not contain 1084 ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT 1085 * [[VUID-VkSubmitInfo-pWaitDstStageMask-00077]] 1086 If the <<features-tessellationShader,tessellation shaders>> feature is 1087 not enabled, each element of pname:pWaitDstStageMask must: not contain 1088 ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or 1089 ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT 1090 * [[VUID-VkSubmitInfo-pWaitDstStageMask-00078]] 1091 Each element of pname:pWaitDstStageMask must: not include 1092 ename:VK_PIPELINE_STAGE_HOST_BIT. 1093 ifdef::VK_NV_mesh_shader[] 1094 * [[VUID-VkSubmitInfo-pWaitDstStageMask-02089]] 1095 If the <<features-meshShader,mesh shaders>> feature is not enabled, each 1096 element of pname:pWaitDstStageMask must: not contain 1097 ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV 1098 * [[VUID-VkSubmitInfo-pWaitDstStageMask-02090]] 1099 If the <<features-taskShader,task shaders>> feature is not enabled, each 1100 element of pname:pWaitDstStageMask must: not contain 1101 ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV 1102 endif::VK_NV_mesh_shader[] 1103 **** 1104 1105 include::{generated}/validity/structs/VkSubmitInfo.txt[] 1106 -- 1107 1108 ifdef::VK_KHR_external_semaphore_win32[] 1109 1110 [open,refpage='VkD3D12FenceSubmitInfoKHR',desc='Structure specifying values for Direct3D 12 fence-backed semaphores',type='structs'] 1111 -- 1112 1113 To specify the values to use when waiting for and signaling semaphores whose 1114 <<synchronization-semaphores-importing,current payload>> refers to a 1115 Direct3D 12 fence, add the slink:VkD3D12FenceSubmitInfoKHR structure to the 1116 pname:pNext chain of the slink:VkSubmitInfo structure. 1117 The sname:VkD3D12FenceSubmitInfoKHR structure is defined as: 1118 1119 include::{generated}/api/structs/VkD3D12FenceSubmitInfoKHR.txt[] 1120 1121 * pname:sType is the type of this structure. 1122 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1123 * pname:waitSemaphoreValuesCount is the number of semaphore wait values 1124 specified in pname:pWaitSemaphoreValues. 1125 * pname:pWaitSemaphoreValues is an array of length 1126 pname:waitSemaphoreValuesCount containing values for the corresponding 1127 semaphores in slink:VkSubmitInfo::pname:pWaitSemaphores to wait for. 1128 * pname:signalSemaphoreValuesCount is the number of semaphore signal 1129 values specified in pname:pSignalSemaphoreValues. 1130 * pname:pSignalSemaphoreValues is an array of length 1131 pname:signalSemaphoreValuesCount containing values for the corresponding 1132 semaphores in slink:VkSubmitInfo::pname:pSignalSemaphores to set when 1133 signaled. 1134 1135 If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or 1136 slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in 1137 pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively does 1138 not currently have a <<synchronization-semaphores-payloads, payload>> 1139 referring to a Direct3D 12 fence, the implementation must: ignore the value 1140 in the pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry. 1141 1142 .Valid Usage 1143 **** 1144 * [[VUID-VkD3D12FenceSubmitInfoKHR-waitSemaphoreValuesCount-00079]] 1145 pname:waitSemaphoreValuesCount must: be the same value as 1146 sname:VkSubmitInfo::pname:waitSemaphoreCount, where sname:VkSubmitInfo 1147 is in the pname:pNext chain of this sname:VkD3D12FenceSubmitInfoKHR 1148 structure. 1149 * [[VUID-VkD3D12FenceSubmitInfoKHR-signalSemaphoreValuesCount-00080]] 1150 pname:signalSemaphoreValuesCount must: be the same value as 1151 sname:VkSubmitInfo::pname:signalSemaphoreCount, where sname:VkSubmitInfo 1152 is in the pname:pNext chain of this sname:VkD3D12FenceSubmitInfoKHR 1153 structure. 1154 **** 1155 1156 include::{generated}/validity/structs/VkD3D12FenceSubmitInfoKHR.txt[] 1157 -- 1158 1159 endif::VK_KHR_external_semaphore_win32[] 1160 1161 ifdef::VK_KHR_win32_keyed_mutex[] 1162 1163 [open,refpage='VkWin32KeyedMutexAcquireReleaseInfoKHR',desc='Use the Windows keyed mutex mechanism to synchronize work',type='structs'] 1164 -- 1165 1166 When submitting work that operates on memory imported from a Direct3D 11 1167 resource to a queue, the keyed mutex mechanism may: be used in addition to 1168 Vulkan semaphores to synchronize the work. 1169 Keyed mutexes are a property of a properly created shareable Direct3D 11 1170 resource. 1171 They can: only be used if the imported resource was created with the 1172 etext:D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX flag. 1173 1174 To acquire keyed mutexes before submitted work and/or release them after, 1175 add a slink:VkWin32KeyedMutexAcquireReleaseInfoKHR structure to the 1176 pname:pNext chain of the slink:VkSubmitInfo structure. 1177 1178 The sname:VkWin32KeyedMutexAcquireReleaseInfoKHR structure is defined as: 1179 1180 include::{generated}/api/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.txt[] 1181 1182 * pname:acquireCount is the number of entries in the pname:pAcquireSyncs, 1183 pname:pAcquireKeys, and pname:pAcquireTimeoutMilliseconds arrays. 1184 * pname:pAcquireSyncs is a pointer to an array of slink:VkDeviceMemory 1185 objects which were imported from Direct3D 11 resources. 1186 * pname:pAcquireKeys is a pointer to an array of mutex key values to wait 1187 for prior to beginning the submitted work. 1188 Entries refer to the keyed mutex associated with the corresponding 1189 entries in pname:pAcquireSyncs. 1190 * pname:pAcquireTimeoutMilliseconds is an array of timeout values, in 1191 millisecond units, for each acquire specified in pname:pAcquireKeys. 1192 * pname:releaseCount is the number of entries in the pname:pReleaseSyncs 1193 and pname:pReleaseKeys arrays. 1194 * pname:pReleaseSyncs is a pointer to an array of slink:VkDeviceMemory 1195 objects which were imported from Direct3D 11 resources. 1196 * pname:pReleaseKeys is a pointer to an array of mutex key values to set 1197 when the submitted work has completed. 1198 Entries refer to the keyed mutex associated with the corresponding 1199 entries in pname:pReleaseSyncs. 1200 1201 .Valid Usage 1202 **** 1203 * [[VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireSyncs-00081]] 1204 Each member of pname:pAcquireSyncs and pname:pReleaseSyncs must: be a 1205 device memory object imported by setting 1206 slink:VkImportMemoryWin32HandleInfoKHR::pname:handleType to 1207 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT or 1208 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT. 1209 **** 1210 1211 include::{generated}/validity/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.txt[] 1212 -- 1213 1214 endif::VK_KHR_win32_keyed_mutex[] 1215 1216 ifdef::VK_NV_win32_keyed_mutex[] 1217 include::VK_NV_win32_keyed_mutex/keyed_mutex_submit.txt[] 1218 endif::VK_NV_win32_keyed_mutex[] 1219 1220 ifdef::VK_VERSION_1_1[] 1221 1222 [open,refpage='VkProtectedSubmitInfo',desc='Structure indicating whether the submission is protected',type='structs'] 1223 -- 1224 1225 If the pname:pNext chain of slink:VkSubmitInfo includes a 1226 sname:VkProtectedSubmitInfo structure, then the structure indicates whether 1227 the batch is protected. 1228 The sname:VkProtectedSubmitInfo structure is defined as: 1229 1230 include::{generated}/api/structs/VkProtectedSubmitInfo.txt[] 1231 1232 * pname:protectedSubmit specifies whether the batch is protected. 1233 If pname:protectedSubmit is ename:VK_TRUE, the batch is protected. 1234 If pname:protectedSubmit is ename:VK_FALSE, the batch is unprotected. 1235 If the sname:VkSubmitInfo::pname:pNext chain does not contain this 1236 structure, the batch is unprotected. 1237 1238 .Valid Usage 1239 **** 1240 * [[VUID-VkProtectedSubmitInfo-protectedSubmit-01816]] 1241 If the protected memory feature is not enabled, pname:protectedSubmit 1242 must: not be ename:VK_TRUE. 1243 * [[VUID-VkProtectedSubmitInfo-protectedSubmit-01817]] 1244 If pname:protectedSubmit is ename:VK_TRUE, then each element of the 1245 pname:pCommandBuffers array must: be a protected command buffer. 1246 * [[VUID-VkProtectedSubmitInfo-protectedSubmit-01818]] 1247 If pname:protectedSubmit is ename:VK_FALSE, then each element of the 1248 pname:pCommandBuffers array must: be an unprotected command buffer. 1249 * [[VUID-VkProtectedSubmitInfo-pNext-01819]] 1250 If the sname:VkSubmitInfo::pname:pNext chain does not include a 1251 sname:VkProtectedSubmitInfo structure, then each element of the command 1252 buffer of the pname:pCommandBuffers array must: be an unprotected 1253 command buffer. 1254 **** 1255 1256 include::{generated}/validity/structs/VkProtectedSubmitInfo.txt[] 1257 1258 -- 1259 1260 endif::VK_VERSION_1_1[] 1261 1262 ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1263 1264 [open,refpage='VkDeviceGroupSubmitInfo',desc='Structure indicating which physical devices execute semaphore operations and command buffers',type='structs'] 1265 -- 1266 1267 If the pname:pNext chain of slink:VkSubmitInfo includes a 1268 sname:VkDeviceGroupSubmitInfo structure, then that structure includes device 1269 indices and masks specifying which physical devices execute semaphore 1270 operations and command buffers. 1271 1272 The sname:VkDeviceGroupSubmitInfo structure is defined as: 1273 1274 include::{generated}/api/structs/VkDeviceGroupSubmitInfo.txt[] 1275 1276 ifdef::VK_KHR_device_group[] 1277 or the equivalent 1278 1279 include::{generated}/api/structs/VkDeviceGroupSubmitInfoKHR.txt[] 1280 endif::VK_KHR_device_group[] 1281 1282 * pname:sType is the type of this structure. 1283 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1284 * pname:waitSemaphoreCount is the number of elements in the 1285 pname:pWaitSemaphoreDeviceIndices array. 1286 * pname:pWaitSemaphoreDeviceIndices is an array of device indices 1287 indicating which physical device executes the semaphore wait operation 1288 in the corresponding element of 1289 slink:VkSubmitInfo::pname:pWaitSemaphores. 1290 * pname:commandBufferCount is the number of elements in the 1291 pname:pCommandBufferDeviceMasks array. 1292 * pname:pCommandBufferDeviceMasks is an array of device masks indicating 1293 which physical devices execute the command buffer in the corresponding 1294 element of slink:VkSubmitInfo::pname:pCommandBuffers. 1295 A physical device executes the command buffer if the corresponding bit 1296 is set in the mask. 1297 * pname:signalSemaphoreCount is the number of elements in the 1298 pname:pSignalSemaphoreDeviceIndices array. 1299 * pname:pSignalSemaphoreDeviceIndices is an array of device indices 1300 indicating which physical device executes the semaphore signal operation 1301 in the corresponding element of 1302 slink:VkSubmitInfo::pname:pSignalSemaphores. 1303 1304 If this structure is not present, semaphore operations and command buffers 1305 execute on device index zero. 1306 1307 .Valid Usage 1308 **** 1309 * [[VUID-VkDeviceGroupSubmitInfo-waitSemaphoreCount-00082]] 1310 pname:waitSemaphoreCount must: equal 1311 slink:VkSubmitInfo::pname:waitSemaphoreCount 1312 * [[VUID-VkDeviceGroupSubmitInfo-commandBufferCount-00083]] 1313 pname:commandBufferCount must: equal 1314 slink:VkSubmitInfo::pname:commandBufferCount 1315 * [[VUID-VkDeviceGroupSubmitInfo-signalSemaphoreCount-00084]] 1316 pname:signalSemaphoreCount must: equal 1317 slink:VkSubmitInfo::pname:signalSemaphoreCount 1318 * [[VUID-VkDeviceGroupSubmitInfo-pWaitSemaphoreDeviceIndices-00085]] 1319 All elements of pname:pWaitSemaphoreDeviceIndices and 1320 pname:pSignalSemaphoreDeviceIndices must: be valid device indices 1321 * [[VUID-VkDeviceGroupSubmitInfo-pCommandBufferDeviceMasks-00086]] 1322 All elements of pname:pCommandBufferDeviceMasks must: be valid device 1323 masks 1324 **** 1325 1326 include::{generated}/validity/structs/VkDeviceGroupSubmitInfo.txt[] 1327 1328 -- 1329 1330 endif::VK_VERSION_1_1,VK_KHR_device_group[] 1331 1332 1333 [[commandbuffers-submission-progress]] 1334 == Queue Forward Progress 1335 1336 The application must: ensure that command buffer submissions will be able to 1337 complete without any subsequent operations by the application on any queue. 1338 After any call to fname:vkQueueSubmit, for every queued wait on a semaphore 1339 there must: be a prior signal of that semaphore that will not be consumed by 1340 a different wait on the semaphore. 1341 1342 Command buffers in the submission can: include flink:vkCmdWaitEvents 1343 commands that wait on events that will not be signaled by earlier commands 1344 in the queue. 1345 Such events must: be signaled by the application using flink:vkSetEvent, and 1346 the fname:vkCmdWaitEvents commands that wait upon them must: not be inside a 1347 render pass instance. 1348 The event must: be set before the flink:vkCmdWaitEvents command is executed. 1349 1350 [NOTE] 1351 .Note 1352 ==== 1353 Implementations may have some tolerance for waiting on events to be set, but 1354 this is defined outside of the scope of Vulkan. 1355 ==== 1356 1357 1358 [[commandbuffers-secondary]] 1359 == Secondary Command Buffer Execution 1360 1361 [open,refpage='vkCmdExecuteCommands',desc='Execute a secondary command buffer from a primary command buffer',type='protos'] 1362 -- 1363 1364 A secondary command buffer must: not be directly submitted to a queue. 1365 Instead, secondary command buffers are recorded to execute as part of a 1366 primary command buffer with the command: 1367 1368 include::{generated}/api/protos/vkCmdExecuteCommands.txt[] 1369 1370 * pname:commandBuffer is a handle to a primary command buffer that the 1371 secondary command buffers are executed in. 1372 * pname:commandBufferCount is the length of the pname:pCommandBuffers 1373 array. 1374 * pname:pCommandBuffers is an array of secondary command buffer handles, 1375 which are recorded to execute in the primary command buffer in the order 1376 they are listed in the array. 1377 1378 If any element of pname:pCommandBuffers was not recorded with the 1379 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, and it was recorded 1380 into any other primary command buffer which is currently in the 1381 <<commandbuffers-lifecycle, executable or recording state>>, that primary 1382 command buffer becomes <<commandbuffers-lifecycle, invalid>>. 1383 1384 .Valid Usage 1385 **** 1386 * [[VUID-vkCmdExecuteCommands-commandBuffer-00087]] 1387 pname:commandBuffer must: have been allocated with a pname:level of 1388 ename:VK_COMMAND_BUFFER_LEVEL_PRIMARY 1389 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00088]] 1390 Each element of pname:pCommandBuffers must: have been allocated with a 1391 pname:level of ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY 1392 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00089]] 1393 Each element of pname:pCommandBuffers must: be in the 1394 <<commandbuffers-lifecycle, pending or executable state>>. 1395 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00090]] 1396 If any element of pname:pCommandBuffers was not recorded with the 1397 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, and it was 1398 recorded into any other primary command buffer, that primary command 1399 buffer must: not be in the <<commandbuffers-lifecycle, pending state>> 1400 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00091]] 1401 If any element of pname:pCommandBuffers was not recorded with the 1402 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not be 1403 in the <<commandbuffers-lifecycle, pending state>>. 1404 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00092]] 1405 If any element of pname:pCommandBuffers was not recorded with the 1406 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not 1407 have already been recorded to pname:commandBuffer. 1408 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00093]] 1409 If any element of pname:pCommandBuffers was not recorded with the 1410 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not 1411 appear more than once in pname:pCommandBuffers. 1412 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00094]] 1413 Each element of pname:pCommandBuffers must: have been allocated from a 1414 sname:VkCommandPool that was created for the same queue family as the 1415 sname:VkCommandPool from which pname:commandBuffer was allocated 1416 * [[VUID-vkCmdExecuteCommands-contents-00095]] 1417 If fname:vkCmdExecuteCommands is being called within a render pass 1418 instance, that render pass instance must: have been begun with the 1419 pname:contents parameter of fname:vkCmdBeginRenderPass set to 1420 ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS 1421 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00096]] 1422 If fname:vkCmdExecuteCommands is being called within a render pass 1423 instance, each element of pname:pCommandBuffers must: have been recorded 1424 with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 1425 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00097]] 1426 If fname:vkCmdExecuteCommands is being called within a render pass 1427 instance, each element of pname:pCommandBuffers must: have been recorded 1428 with sname:VkCommandBufferInheritanceInfo::pname:subpass set to the 1429 index of the subpass which the given command buffer will be executed in 1430 * [[VUID-vkCmdExecuteCommands-pInheritanceInfo-00098]] 1431 If fname:vkCmdExecuteCommands is being called within a render pass 1432 instance, the render passes specified in the 1433 pname:pBeginInfo::pname:pInheritanceInfo::pname:renderPass members of 1434 the flink:vkBeginCommandBuffer commands used to begin recording each 1435 element of pname:pCommandBuffers must: be 1436 <<renderpass-compatibility,compatible>> with the current render pass. 1437 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00099]] 1438 If fname:vkCmdExecuteCommands is being called within a render pass 1439 instance, and any element of pname:pCommandBuffers was recorded with 1440 sname:VkCommandBufferInheritanceInfo::pname:framebuffer not equal to 1441 dlink:VK_NULL_HANDLE, that sname:VkFramebuffer must: match the 1442 sname:VkFramebuffer used in the current render pass instance 1443 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00100]] 1444 If fname:vkCmdExecuteCommands is not being called within a render pass 1445 instance, each element of pname:pCommandBuffers must: not have been 1446 recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT 1447 * [[VUID-vkCmdExecuteCommands-commandBuffer-00101]] 1448 If the <<features-inheritedQueries,inherited queries>> feature is not 1449 enabled, pname:commandBuffer must: not have any queries 1450 <<queries-operation-active,active>> 1451 * [[VUID-vkCmdExecuteCommands-commandBuffer-00102]] 1452 If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query 1453 <<queries-operation-active,active>>, then each element of 1454 pname:pCommandBuffers must: have been recorded with 1455 sname:VkCommandBufferInheritanceInfo::pname:occlusionQueryEnable set to 1456 ename:VK_TRUE 1457 * [[VUID-vkCmdExecuteCommands-commandBuffer-00103]] 1458 If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query 1459 <<queries-operation-active,active>>, then each element of 1460 pname:pCommandBuffers must: have been recorded with 1461 sname:VkCommandBufferInheritanceInfo::pname:queryFlags having all bits 1462 set that are set for the query 1463 * [[VUID-vkCmdExecuteCommands-commandBuffer-00104]] 1464 If pname:commandBuffer has a ename:VK_QUERY_TYPE_PIPELINE_STATISTICS 1465 query <<queries-operation-active,active>>, then each element of 1466 pname:pCommandBuffers must: have been recorded with 1467 sname:VkCommandBufferInheritanceInfo::pname:pipelineStatistics having 1468 all bits set that are set in the sname:VkQueryPool the query uses 1469 * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00105]] 1470 Each element of pname:pCommandBuffers must: not begin any query types 1471 that are <<queries-operation-active,active>> in pname:commandBuffer 1472 ifdef::VK_VERSION_1_1[] 1473 * [[VUID-vkCmdExecuteCommands-commandBuffer-01820]] 1474 If pname:commandBuffer is a protected command buffer, then each element 1475 of pname:pCommandBuffers must: be a protected command buffer. 1476 * [[VUID-vkCmdExecuteCommands-commandBuffer-01821]] 1477 If pname:commandBuffer is an unprotected command buffer, then each 1478 element of pname:pCommandBuffers must: be an unprotected command buffer. 1479 endif::VK_VERSION_1_1[] 1480 ifdef::VK_EXT_transform_feedback[] 1481 * [[VUID-vkCmdExecuteCommands-None-02286]] 1482 This command must: not be recorded when transform feedback is active 1483 endif::VK_EXT_transform_feedback[] 1484 1485 **** 1486 1487 include::{generated}/validity/protos/vkCmdExecuteCommands.txt[] 1488 -- 1489 1490 ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1491 1492 [[commandbuffers-devicemask]] 1493 == Command Buffer Device Mask 1494 1495 Each command buffer has a piece of state storing the current device mask of 1496 the command buffer. 1497 This mask controls which physical devices within the logical device all 1498 subsequent commands will execute on, including state-setting commands, 1499 action commands, and synchronization commands. 1500 1501 ifndef::VK_NV_scissor_exclusive[] 1502 Scissor 1503 endif::VK_NV_scissor_exclusive[] 1504 ifdef::VK_NV_scissor_exclusive[] 1505 Scissor, exclusive scissor, 1506 endif::VK_NV_scissor_exclusive[] 1507 and viewport state can: be set to different values on each physical device 1508 (only when set as dynamic state), and each physical device will render using 1509 its local copy of the state. 1510 Other state is shared between physical devices, such that all physical 1511 devices use the most recently set values for the state. 1512 However, when recording an action command that uses a piece of state, the 1513 most recent command that set that state must: have included all physical 1514 devices that execute the action command in its current device mask. 1515 1516 The command buffer's device mask is orthogonal to the 1517 pname:pCommandBufferDeviceMasks member of slink:VkDeviceGroupSubmitInfo. 1518 Commands only execute on a physical device if the device index is set in 1519 both device masks. 1520 1521 [open,refpage='VkDeviceGroupCommandBufferBeginInfo',desc='Set the initial device mask for a command buffer',type='structs'] 1522 -- 1523 1524 If the pname:pNext chain of slink:VkCommandBufferBeginInfo includes a 1525 sname:VkDeviceGroupCommandBufferBeginInfo structure, then that structure 1526 includes an initial device mask for the command buffer. 1527 1528 The sname:VkDeviceGroupCommandBufferBeginInfo structure is defined as: 1529 1530 include::{generated}/api/structs/VkDeviceGroupCommandBufferBeginInfo.txt[] 1531 1532 ifdef::VK_KHR_device_group[] 1533 or the equivalent 1534 1535 include::{generated}/api/structs/VkDeviceGroupCommandBufferBeginInfoKHR.txt[] 1536 endif::VK_KHR_device_group[] 1537 1538 * pname:sType is the type of this structure. 1539 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1540 * pname:deviceMask is the initial value of the command buffer's device 1541 mask. 1542 1543 The initial device mask also acts as an upper bound on the set of devices 1544 that can: ever be in the device mask in the command buffer. 1545 1546 If this structure is not present, the initial value of a command buffer's 1547 device mask is set to include all physical devices in the logical device 1548 when the command buffer begins recording. 1549 1550 .Valid Usage 1551 **** 1552 * [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00106]] 1553 pname:deviceMask must: be a valid device mask value 1554 * [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00107]] 1555 pname:deviceMask must: not be zero 1556 **** 1557 1558 include::{generated}/validity/structs/VkDeviceGroupCommandBufferBeginInfo.txt[] 1559 -- 1560 1561 1562 [open,refpage='vkCmdSetDeviceMask',desc='Modify device mask of a command buffer',type='protos'] 1563 -- 1564 1565 To update the current device mask of a command buffer, call: 1566 1567 ifdef::VK_VERSION_1_1[] 1568 include::{generated}/api/protos/vkCmdSetDeviceMask.txt[] 1569 endif::VK_VERSION_1_1[] 1570 1571 ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] 1572 1573 ifdef::VK_KHR_device_group[] 1574 include::{generated}/api/protos/vkCmdSetDeviceMaskKHR.txt[] 1575 endif::VK_KHR_device_group[] 1576 1577 * pname:commandBuffer is command buffer whose current device mask is 1578 modified. 1579 * pname:deviceMask is the new value of the current device mask. 1580 1581 pname:deviceMask is used to filter out subsequent commands from executing on 1582 all physical devices whose bit indices are not set in the mask, except 1583 commands beginning a render pass instance, commands transitioning to the 1584 next subpass in the render pass instance, and commands ending a render pass 1585 instance, which always execute on the set of physical devices whose bit 1586 indices are included in the pname:deviceMask member of the instance of the 1587 slink:VkDeviceGroupRenderPassBeginInfoKHR structure passed to the command 1588 beginning the corresponding render pass instance. 1589 1590 .Valid Usage 1591 **** 1592 * [[VUID-vkCmdSetDeviceMask-deviceMask-00108]] 1593 pname:deviceMask must: be a valid device mask value 1594 * [[VUID-vkCmdSetDeviceMask-deviceMask-00109]] 1595 pname:deviceMask must: not be zero 1596 * [[VUID-vkCmdSetDeviceMask-deviceMask-00110]] 1597 pname:deviceMask must: not include any set bits that were not in the 1598 slink:VkDeviceGroupCommandBufferBeginInfo::pname:deviceMask value when 1599 the command buffer began recording. 1600 * [[VUID-vkCmdSetDeviceMask-deviceMask-00111]] 1601 If fname:vkCmdSetDeviceMask is called inside a render pass instance, 1602 pname:deviceMask must: not include any set bits that were not in the 1603 slink:VkDeviceGroupRenderPassBeginInfo::pname:deviceMask value when the 1604 render pass instance began recording. 1605 **** 1606 1607 include::{generated}/validity/protos/vkCmdSetDeviceMask.txt[] 1608 -- 1609 1610 endif::VK_VERSION_1_1,VK_KHR_device_group[]