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