| // Copyright 2015-2021 The Khronos Group, Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| [[commandbuffers]] |
| = Command Buffers |
| |
| [open,refpage='VkCommandBuffer',desc='Opaque handle to a command buffer object',type='handles'] |
| -- |
| Command buffers are objects used to record commands which can: be |
| subsequently submitted to a device queue for execution. |
| There are two levels of command buffers - _primary command buffers_, which |
| can: execute secondary command buffers, and which are submitted to queues, |
| and _secondary command buffers_, which can: be executed by primary command |
| buffers, and which are not directly submitted to queues. |
| |
| Command buffers are represented by sname:VkCommandBuffer handles: |
| |
| include::{generated}/api/handles/VkCommandBuffer.txt[] |
| -- |
| |
| Recorded commands include commands to bind pipelines and descriptor sets to |
| the command buffer, commands to modify dynamic state, commands to draw (for |
| graphics rendering), commands to dispatch (for compute), commands to execute |
| secondary command buffers (for primary command buffers only), commands to |
| copy buffers and images, and other commands. |
| |
| [[commandbuffers-statereset]] |
| Each command buffer manages state independently of other command buffers. |
| There is no inheritance of state across primary and secondary command |
| buffers, or between secondary command buffers. |
| When a command buffer begins recording, all state in that command buffer is |
| undefined:. |
| When secondary command buffer(s) are recorded to execute on a primary |
| command buffer, the secondary command buffer inherits no state from the |
| primary command buffer, and all state of the primary command buffer is |
| undefined: after an execute secondary command buffer command is recorded. |
| There is one exception to this rule - if the primary command buffer is |
| inside a render pass instance, then the render pass and subpass state is not |
| disturbed by executing secondary command buffers. |
| For state dependent commands (such as draws and dispatches), any state |
| consumed by those commands must: not be undefined:. |
| |
| ifdef::VK_NV_inherited_viewport_scissor[] |
| slink:VkCommandBufferInheritanceViewportScissorInfoNV defines an exception |
| allowing limited inheritance of dynamic viewport and scissor state. |
| endif::VK_NV_inherited_viewport_scissor[] |
| |
| Unless otherwise specified, and without explicit synchronization, the |
| various commands submitted to a queue via command buffers may: execute in |
| arbitrary order relative to each other, and/or concurrently. |
| Also, the memory side effects of those commands may: not be directly visible |
| to other commands without explicit memory dependencies. |
| This is true within a command buffer, and across command buffers submitted |
| to a given queue. |
| See <<synchronization, the synchronization chapter>> for information on |
| <<synchronization-implicit, implicit>> and explicit synchronization between |
| commands. |
| |
| |
| [[commandbuffers-lifecycle]] |
| == Command Buffer Lifecycle |
| |
| Each command buffer is always in one of the following states: |
| |
| Initial:: |
| When a command buffer is <<vkAllocateCommandBuffers, allocated>>, it is |
| in the _initial state_. |
| Some commands are able to _reset_ a command buffer (or a set of command |
| buffers) back to this state from any of the executable, recording or |
| invalid state. |
| Command buffers in the initial state can: only be moved to the recording |
| state, or freed. |
| Recording:: |
| flink:vkBeginCommandBuffer changes the state of a command buffer from |
| the initial state to the _recording state_. |
| Once a command buffer is in the recording state, ftext:vkCmd* commands |
| can: be used to record to the command buffer. |
| Executable:: |
| flink:vkEndCommandBuffer ends the recording of a command buffer, and |
| moves it from the recording state to the _executable state_. |
| Executable command buffers can: be <<commandbuffers-submission, |
| submitted>>, reset, or <<commandbuffers-secondary, recorded to another |
| command buffer>>. |
| Pending:: |
| <<commandbuffers-submission, Queue submission>> of a command buffer |
| changes the state of a command buffer from the executable state to the |
| _pending state_. |
| Whilst in the pending state, applications must: not attempt to modify |
| the command buffer in any way - as the device may: be processing the |
| commands recorded to it. |
| Once execution of a command buffer completes, the command buffer either |
| reverts back to the _executable state_, or if it was recorded with |
| ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT, it moves to the |
| _invalid state_. |
| A <<synchronization, synchronization>> command should: be used to detect |
| when this occurs. |
| Invalid:: |
| Some operations, such as <<fundamentals-objectmodel-lifetime-cmdbuffers, |
| modifying or deleting a resource>> that was used in a command recorded |
| to a command buffer, will transition the state of that command buffer |
| into the _invalid state_. |
| Command buffers in the invalid state can: only be reset or freed. |
| |
| [[commandbuffer-lifecycle-diagram]] |
| image::{images}/commandbuffer_lifecycle.svg[title="Lifecycle of a command buffer",align="center",opts="{imageopts}"] |
| |
| Any given command that operates on a command buffer has its own requirements |
| on what state a command buffer must: be in, which are detailed in the valid |
| usage constraints for that command. |
| |
| Resetting a command buffer is an operation that discards any previously |
| recorded commands and puts a command buffer in the _initial state_. |
| Resetting occurs as a result of flink:vkResetCommandBuffer or |
| flink:vkResetCommandPool, or as part of flink:vkBeginCommandBuffer (which |
| additionally puts the command buffer in the _recording state_). |
| |
| <<commandbuffers-secondary, Secondary command buffers>> can: be recorded to |
| a primary command buffer via flink:vkCmdExecuteCommands. |
| This partially ties the lifecycle of the two command buffers together - if |
| the primary is submitted to a queue, both the primary and any secondaries |
| recorded to it move to the _pending state_. |
| Once execution of the primary completes, so it does for any secondary |
| recorded within it. |
| After all executions of each command buffer complete, they each move to |
| their appropriate completion state (either to the _executable state_ or the |
| _invalid state_, as specified above). |
| |
| If a secondary moves to the _invalid state_ or the _initial state_, then all |
| primary buffers it is recorded in move to the _invalid state_. |
| A primary moving to any other state does not affect the state of a secondary |
| recorded in it. |
| |
| [NOTE] |
| .Note |
| ==== |
| Resetting or freeing a primary command buffer removes the lifecycle linkage |
| to all secondary command buffers that were recorded into it. |
| ==== |
| |
| |
| [[commandbuffers-pools]] |
| == Command Pools |
| |
| [open,refpage='VkCommandPool',desc='Opaque handle to a command pool object',type='handles'] |
| -- |
| Command pools are opaque objects that command buffer memory is allocated |
| from, and which allow the implementation to amortize the cost of resource |
| creation across multiple command buffers. |
| Command pools are externally synchronized, meaning that a command pool must: |
| not be used concurrently in multiple threads. |
| That includes use via recording commands on any command buffers allocated |
| from the pool, as well as operations that allocate, free, and reset command |
| buffers or the pool itself. |
| |
| Command pools are represented by sname:VkCommandPool handles: |
| |
| include::{generated}/api/handles/VkCommandPool.txt[] |
| -- |
| |
| [open,refpage='vkCreateCommandPool',desc='Create a new command pool object',type='protos'] |
| -- |
| To create a command pool, call: |
| |
| include::{generated}/api/protos/vkCreateCommandPool.txt[] |
| |
| * pname:device is the logical device that creates the command pool. |
| * pname:pCreateInfo is a pointer to a slink:VkCommandPoolCreateInfo |
| structure specifying the state of the command pool object. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| * pname:pCommandPool is a pointer to a slink:VkCommandPool handle in which |
| the created pool is returned. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCreateCommandPool-queueFamilyIndex-01937]] |
| pname:pCreateInfo->queueFamilyIndex must: be the index of a queue family |
| available in the logical device pname:device |
| **** |
| |
| include::{generated}/validity/protos/vkCreateCommandPool.txt[] |
| -- |
| |
| [open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] |
| -- |
| The sname:VkCommandPoolCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkCommandPoolCreateInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkCommandPoolCreateFlagBits indicating |
| usage behavior for the pool and command buffers allocated from it. |
| * pname:queueFamilyIndex designates a queue family as described in section |
| <<devsandqueues-queueprops,Queue Family Properties>>. |
| All command buffers allocated from this command pool must: be submitted |
| on queues from the same queue family. |
| |
| .Valid Usage |
| **** |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-VkCommandPoolCreateInfo-flags-02860]] |
| If the protected memory feature is not enabled, the |
| ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT bit of pname:flags must: not |
| be set |
| endif::VK_VERSION_1_1[] |
| **** |
| |
| include::{generated}/validity/structs/VkCommandPoolCreateInfo.txt[] |
| -- |
| |
| [open,refpage='VkCommandPoolCreateFlagBits',desc='Bitmask specifying usage behavior for a command pool',type='enums'] |
| -- |
| Bits which can: be set in slink:VkCommandPoolCreateInfo::pname:flags to |
| specify usage behavior for a command pool are: |
| |
| include::{generated}/api/enums/VkCommandPoolCreateFlagBits.txt[] |
| |
| * ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT specifies that command |
| buffers allocated from the pool will be short-lived, meaning that they |
| will be reset or freed in a relatively short timeframe. |
| This flag may: be used by the implementation to control memory |
| allocation behavior within the pool. |
| * ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT allows any command |
| buffer allocated from a pool to be individually reset to the |
| <<commandbuffers-lifecycle, initial state>>; either by calling |
| flink:vkResetCommandBuffer, or via the implicit reset when calling |
| flink:vkBeginCommandBuffer. |
| If this flag is not set on a pool, then fname:vkResetCommandBuffer must: |
| not be called for any command buffer allocated from that pool. |
| ifdef::VK_VERSION_1_1[] |
| * ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT specifies that command |
| buffers allocated from the pool are protected command buffers. |
| endif::VK_VERSION_1_1[] |
| -- |
| |
| [open,refpage='VkCommandPoolCreateFlags',desc='Bitmask of VkCommandPoolCreateFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkCommandPoolCreateFlags.txt[] |
| |
| tname:VkCommandPoolCreateFlags is a bitmask type for setting a mask of zero |
| or more elink:VkCommandPoolCreateFlagBits. |
| -- |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| [open,refpage='vkTrimCommandPool',desc='Trim a command pool',type='protos'] |
| -- |
| To trim a command pool, call: |
| |
| ifdef::VK_VERSION_1_1[] |
| include::{generated}/api/protos/vkTrimCommandPool.txt[] |
| endif::VK_VERSION_1_1[] |
| |
| ifdef::VK_VERSION_1_1+VK_KHR_maintenance1[or the equivalent command] |
| |
| ifdef::VK_KHR_maintenance1[] |
| include::{generated}/api/protos/vkTrimCommandPoolKHR.txt[] |
| endif::VK_KHR_maintenance1[] |
| |
| * pname:device is the logical device that owns the command pool. |
| * pname:commandPool is the command pool to trim. |
| * pname:flags is reserved for future use. |
| |
| Trimming a command pool recycles unused memory from the command pool back to |
| the system. |
| Command buffers allocated from the pool are not affected by the command. |
| |
| [NOTE] |
| .Note |
| ==== |
| This command provides applications with some control over the internal |
| memory allocations used by command pools. |
| |
| Unused memory normally arises from command buffers that have been recorded |
| and later reset, such that they are no longer using the memory. |
| On reset, a command buffer can return memory to its command pool, but the |
| only way to release memory from a command pool to the system requires |
| calling flink:vkResetCommandPool, which cannot be executed while any command |
| buffers from that pool are still in use. |
| Subsequent recording operations into command buffers will re-use this memory |
| but since total memory requirements fluctuate over time, unused memory can |
| accumulate. |
| |
| In this situation, trimming a command pool may: be useful to return unused |
| memory back to the system, returning the total outstanding memory allocated |
| by the pool back to a more "`average`" value. |
| |
| Implementations utilize many internal allocation strategies that make it |
| impossible to guarantee that all unused memory is released back to the |
| system. |
| For instance, an implementation of a command pool may: involve allocating |
| memory in bulk from the system and sub-allocating from that memory. |
| In such an implementation any live command buffer that holds a reference to |
| a bulk allocation would prevent that allocation from being freed, even if |
| only a small proportion of the bulk allocation is in use. |
| |
| In most cases trimming will result in a reduction in allocated but unused |
| memory, but it does not guarantee the "`ideal`" behavior. |
| |
| Trimming may: be an expensive operation, and should: not be called |
| frequently. |
| Trimming should: be treated as a way to relieve memory pressure after |
| application-known points when there exists enough unused memory that the |
| cost of trimming is "`worth`" it. |
| ==== |
| |
| include::{generated}/validity/protos/vkTrimCommandPool.txt[] |
| -- |
| |
| [open,refpage='VkCommandPoolTrimFlags',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkCommandPoolTrimFlags.txt[] |
| |
| ifdef::VK_KHR_maintenance1[] |
| or the equivalent |
| |
| include::{generated}/api/flags/VkCommandPoolTrimFlagsKHR.txt[] |
| endif::VK_KHR_maintenance1[] |
| |
| tname:VkCommandPoolTrimFlags is a bitmask type for setting a mask, but is |
| currently reserved for future use. |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| |
| [open,refpage='vkResetCommandPool',desc='Reset a command pool',type='protos'] |
| -- |
| To reset a command pool, call: |
| |
| include::{generated}/api/protos/vkResetCommandPool.txt[] |
| |
| * pname:device is the logical device that owns the command pool. |
| * pname:commandPool is the command pool to reset. |
| * pname:flags is a bitmask of elink:VkCommandPoolResetFlagBits controlling |
| the reset operation. |
| |
| Resetting a command pool recycles all of the resources from all of the |
| command buffers allocated from the command pool back to the command pool. |
| All command buffers that have been allocated from the command pool are put |
| in the <<commandbuffers-lifecycle, initial state>>. |
| |
| Any primary command buffer allocated from another slink:VkCommandPool that |
| is in the <<commandbuffers-lifecycle, recording or executable state>> and |
| has a secondary command buffer allocated from pname:commandPool recorded |
| into it, becomes <<commandbuffers-lifecycle, invalid>>. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkResetCommandPool-commandPool-00040]] |
| All sname:VkCommandBuffer objects allocated from pname:commandPool must: |
| not be in the <<commandbuffers-lifecycle, pending state>> |
| **** |
| |
| include::{generated}/validity/protos/vkResetCommandPool.txt[] |
| -- |
| |
| [open,refpage='VkCommandPoolResetFlagBits',desc='Bitmask controlling behavior of a command pool reset',type='enums'] |
| -- |
| Bits which can: be set in flink:vkResetCommandPool::pname:flags to control |
| the reset operation are: |
| |
| include::{generated}/api/enums/VkCommandPoolResetFlagBits.txt[] |
| |
| * ename:VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT specifies that |
| resetting a command pool recycles all of the resources from the command |
| pool back to the system. |
| -- |
| |
| [open,refpage='VkCommandPoolResetFlags',desc='Bitmask of VkCommandPoolResetFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkCommandPoolResetFlags.txt[] |
| |
| tname:VkCommandPoolResetFlags is a bitmask type for setting a mask of zero |
| or more elink:VkCommandPoolResetFlagBits. |
| -- |
| |
| [open,refpage='vkDestroyCommandPool',desc='Destroy a command pool object',type='protos'] |
| -- |
| To destroy a command pool, call: |
| |
| include::{generated}/api/protos/vkDestroyCommandPool.txt[] |
| |
| * pname:device is the logical device that destroys the command pool. |
| * pname:commandPool is the handle of the command pool to destroy. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| |
| When a pool is destroyed, all command buffers allocated from the pool are |
| <<vkFreeCommandBuffers, freed>>. |
| |
| Any primary command buffer allocated from another slink:VkCommandPool that |
| is in the <<commandbuffers-lifecycle, recording or executable state>> and |
| has a secondary command buffer allocated from pname:commandPool recorded |
| into it, becomes <<commandbuffers-lifecycle, invalid>>. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkDestroyCommandPool-commandPool-00041]] |
| All sname:VkCommandBuffer objects allocated from pname:commandPool must: |
| not be in the <<commandbuffers-lifecycle, pending state>> |
| * [[VUID-vkDestroyCommandPool-commandPool-00042]] |
| If sname:VkAllocationCallbacks were provided when pname:commandPool was |
| created, a compatible set of callbacks must: be provided here |
| * [[VUID-vkDestroyCommandPool-commandPool-00043]] |
| If no sname:VkAllocationCallbacks were provided when pname:commandPool |
| was created, pname:pAllocator must: be `NULL` |
| **** |
| |
| include::{generated}/validity/protos/vkDestroyCommandPool.txt[] |
| -- |
| |
| |
| [[commandbuffer-allocation]] |
| == Command Buffer Allocation and Management |
| |
| [open,refpage='vkAllocateCommandBuffers',desc='Allocate command buffers from an existing command pool',type='protos'] |
| -- |
| To allocate command buffers, call: |
| |
| include::{generated}/api/protos/vkAllocateCommandBuffers.txt[] |
| |
| * pname:device is the logical device that owns the command pool. |
| * pname:pAllocateInfo is a pointer to a sname:VkCommandBufferAllocateInfo |
| structure describing parameters of the allocation. |
| * pname:pCommandBuffers is a pointer to an array of slink:VkCommandBuffer |
| handles in which the resulting command buffer objects are returned. |
| The array must: be at least the length specified by the |
| pname:commandBufferCount member of pname:pAllocateInfo. |
| Each allocated command buffer begins in the initial state. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| fname:vkAllocateCommandBuffers can: be used to allocate multiple command |
| buffers. |
| If the allocation of any of those command buffers fails, the implementation |
| must: free all successfully allocated command buffer objects from this |
| command, set all entries of the pname:pCommandBuffers array to `NULL` and |
| return the error. |
| |
| [NOTE] |
| .Note |
| ==== |
| Filling pname:pCommandBuffers with `NULL` values on failure is an exception |
| to the default error behavior that output parameters will have undefined: |
| contents. |
| ==== |
| |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| |
| When command buffers are first allocated, they are in the |
| <<commandbuffers-lifecycle, initial state>>. |
| |
| include::{generated}/validity/protos/vkAllocateCommandBuffers.txt[] |
| -- |
| |
| [open,refpage='VkCommandBufferAllocateInfo',desc='Structure specifying the allocation parameters for command buffer object',type='structs'] |
| -- |
| The sname:VkCommandBufferAllocateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkCommandBufferAllocateInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:commandPool is the command pool from which the command buffers are |
| allocated. |
| * pname:level is a elink:VkCommandBufferLevel value specifying the command |
| buffer level. |
| * pname:commandBufferCount is the number of command buffers to allocate |
| from the pool. |
| |
| include::{generated}/validity/structs/VkCommandBufferAllocateInfo.txt[] |
| -- |
| |
| [open,refpage='VkCommandBufferLevel',desc='Enumerant specifying a command buffer level',type='enums'] |
| -- |
| Possible values of slink:VkCommandBufferAllocateInfo::pname:level, |
| specifying the command buffer level, are: |
| |
| include::{generated}/api/enums/VkCommandBufferLevel.txt[] |
| |
| * ename:VK_COMMAND_BUFFER_LEVEL_PRIMARY specifies a primary command |
| buffer. |
| * ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY specifies a secondary command |
| buffer. |
| -- |
| |
| [open,refpage='vkResetCommandBuffer',desc='Reset a command buffer to the initial state',type='protos'] |
| -- |
| To reset a command buffer, call: |
| |
| include::{generated}/api/protos/vkResetCommandBuffer.txt[] |
| |
| * pname:commandBuffer is the command buffer to reset. |
| The command buffer can: be in any state other than |
| <<commandbuffers-lifecycle, pending>>, and is moved into the |
| <<commandbuffers-lifecycle, initial state>>. |
| * pname:flags is a bitmask of elink:VkCommandBufferResetFlagBits |
| controlling the reset operation. |
| |
| Any primary command buffer that is in the <<commandbuffers-lifecycle, |
| recording or executable state>> and has pname:commandBuffer recorded into |
| it, becomes <<commandbuffers-lifecycle, invalid>>. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkResetCommandBuffer-commandBuffer-00045]] |
| pname:commandBuffer must: not be in the <<commandbuffers-lifecycle, |
| pending state>> |
| * [[VUID-vkResetCommandBuffer-commandBuffer-00046]] |
| pname:commandBuffer must: have been allocated from a pool that was |
| created with the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT |
| **** |
| |
| include::{generated}/validity/protos/vkResetCommandBuffer.txt[] |
| -- |
| |
| [open,refpage='VkCommandBufferResetFlagBits',desc='Bitmask controlling behavior of a command buffer reset',type='enums'] |
| -- |
| Bits which can: be set in flink:vkResetCommandBuffer::pname:flags to control |
| the reset operation are: |
| |
| include::{generated}/api/enums/VkCommandBufferResetFlagBits.txt[] |
| |
| * ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT specifies that most |
| or all memory resources currently owned by the command buffer should: be |
| returned to the parent command pool. |
| If this flag is not set, then the command buffer may: hold onto memory |
| resources and reuse them when recording commands. |
| pname:commandBuffer is moved to the <<commandbuffers-lifecycle, initial |
| state>>. |
| -- |
| |
| [open,refpage='VkCommandBufferResetFlags',desc='Bitmask of VkCommandBufferResetFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkCommandBufferResetFlags.txt[] |
| |
| tname:VkCommandBufferResetFlags is a bitmask type for setting a mask of zero |
| or more elink:VkCommandBufferResetFlagBits. |
| -- |
| |
| [open,refpage='vkFreeCommandBuffers',desc='Free command buffers',type='protos'] |
| -- |
| To free command buffers, call: |
| |
| include::{generated}/api/protos/vkFreeCommandBuffers.txt[] |
| |
| * pname:device is the logical device that owns the command pool. |
| * pname:commandPool is the command pool from which the command buffers |
| were allocated. |
| * pname:commandBufferCount is the length of the pname:pCommandBuffers |
| array. |
| * pname:pCommandBuffers is a pointer to an array of handles of command |
| buffers to free. |
| |
| Any primary command buffer that is in the <<commandbuffers-lifecycle, |
| recording or executable state>> and has any element of pname:pCommandBuffers |
| recorded into it, becomes <<commandbuffers-lifecycle, invalid>>. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkFreeCommandBuffers-pCommandBuffers-00047]] |
| All elements of pname:pCommandBuffers must: not be in the |
| <<commandbuffers-lifecycle, pending state>> |
| * [[VUID-vkFreeCommandBuffers-pCommandBuffers-00048]] |
| pname:pCommandBuffers must: be a valid pointer to an array of |
| pname:commandBufferCount sname:VkCommandBuffer handles, each element of |
| which must: either be a valid handle or `NULL` |
| **** |
| |
| include::{generated}/validity/protos/vkFreeCommandBuffers.txt[] |
| -- |
| |
| |
| [[commandbuffers-recording]] |
| == Command Buffer Recording |
| |
| [open,refpage='vkBeginCommandBuffer',desc='Start recording a command buffer',type='protos'] |
| -- |
| To begin recording a command buffer, call: |
| |
| include::{generated}/api/protos/vkBeginCommandBuffer.txt[] |
| |
| * pname:commandBuffer is the handle of the command buffer which is to be |
| put in the recording state. |
| * pname:pBeginInfo is a pointer to a slink:VkCommandBufferBeginInfo |
| structure defining additional information about how the command buffer |
| begins recording. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkBeginCommandBuffer-commandBuffer-00049]] |
| pname:commandBuffer must: not be in the <<commandbuffers-lifecycle, |
| recording or pending state>> |
| * [[VUID-vkBeginCommandBuffer-commandBuffer-00050]] |
| If pname:commandBuffer was allocated from a slink:VkCommandPool which |
| did not have the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT |
| flag set, pname:commandBuffer must: be in the |
| <<commandbuffers-lifecycle, initial state>> |
| * [[VUID-vkBeginCommandBuffer-commandBuffer-00051]] |
| If pname:commandBuffer is a secondary command buffer, the |
| pname:pInheritanceInfo member of pname:pBeginInfo must: be a valid |
| sname:VkCommandBufferInheritanceInfo structure |
| * [[VUID-vkBeginCommandBuffer-commandBuffer-00052]] |
| If pname:commandBuffer is a secondary command buffer and either the |
| pname:occlusionQueryEnable member of the pname:pInheritanceInfo member |
| of pname:pBeginInfo is ename:VK_FALSE, or the precise occlusion queries |
| feature is not enabled, then |
| pname:pBeginInfo->pInheritanceInfo->queryFlags must: not contain |
| ename:VK_QUERY_CONTROL_PRECISE_BIT |
| * [[VUID-vkBeginCommandBuffer-commandBuffer-02840]] |
| If pname:commandBuffer is a primary command buffer, then |
| pname:pBeginInfo->flags must: not set both the |
| ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT and the |
| ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flags |
| **** |
| |
| include::{generated}/validity/protos/vkBeginCommandBuffer.txt[] |
| -- |
| |
| [open,refpage='VkCommandBufferBeginInfo',desc='Structure specifying a command buffer begin operation',type='structs'] |
| -- |
| The sname:VkCommandBufferBeginInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkCommandBufferBeginInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkCommandBufferUsageFlagBits |
| specifying usage behavior for the command buffer. |
| * pname:pInheritanceInfo is a pointer to a |
| sname:VkCommandBufferInheritanceInfo structure, used if |
| pname:commandBuffer is a secondary command buffer. |
| If this is a primary command buffer, then this value is ignored. |
| |
| .Valid Usage |
| **** |
| ifndef::VK_KHR_dynamic_rendering[] |
| * [[VUID-VkCommandBufferBeginInfo-flags-00053]] |
| If pname:flags contains |
| ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the |
| pname:renderPass member of pname:pInheritanceInfo must: be a valid |
| sname:VkRenderPass |
| * [[VUID-VkCommandBufferBeginInfo-flags-00054]] |
| If pname:flags contains |
| ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the |
| pname:subpass member of pname:pInheritanceInfo must: be a valid subpass |
| index within the pname:renderPass member of pname:pInheritanceInfo |
| endif::VK_KHR_dynamic_rendering[] |
| * [[VUID-VkCommandBufferBeginInfo-flags-00055]] |
| If pname:flags contains |
| ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the |
| pname:framebuffer member of pname:pInheritanceInfo must: be either |
| dlink:VK_NULL_HANDLE, or a valid sname:VkFramebuffer that is compatible |
| with the pname:renderPass member of pname:pInheritanceInfo |
| ifdef::VK_KHR_dynamic_rendering[] |
| * [[VUID-VkCommandBufferBeginInfo-flags-06000]] |
| If pname:flags contains |
| ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the |
| pname:renderPass member of pname:pInheritanceInfo is not |
| dlink:VK_NULL_HANDLE, pname:renderPass must: be a valid |
| sname:VkRenderPass |
| * [[VUID-VkCommandBufferBeginInfo-flags-06001]] |
| If pname:flags contains |
| ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the |
| pname:renderPass member of pname:pInheritanceInfo is not |
| dlink:VK_NULL_HANDLE, the pname:subpass member of pname:pInheritanceInfo |
| must: be a valid subpass index within the pname:renderPass member of |
| pname:pInheritanceInfo |
| * [[VUID-VkCommandBufferBeginInfo-flags-06002]] |
| If pname:flags contains |
| ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT and the |
| pname:renderPass member of pname:pInheritanceInfo is |
| dlink:VK_NULL_HANDLE, the pname:pNext chain of pname:pInheritanceInfo |
| must: include a slink:VkCommandBufferInheritanceRenderingInfoKHR |
| structure |
| ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] |
| * [[VUID-VkCommandBufferBeginInfo-flags-06003]] |
| If pname:flags contains |
| ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the |
| pname:renderPass member of pname:pInheritanceInfo is |
| dlink:VK_NULL_HANDLE, and the pname:pNext chain of |
| pname:pInheritanceInfo includes a slink:VkAttachmentSampleCountInfoAMD |
| or slink:VkAttachmentSampleCountInfoNV structure, the |
| pname:colorAttachmentCount member of that structure must: be equal to |
| the value of |
| slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:colorAttachmentCount |
| endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] |
| endif::VK_KHR_dynamic_rendering[] |
| **** |
| |
| include::{generated}/validity/structs/VkCommandBufferBeginInfo.txt[] |
| -- |
| |
| [open,refpage='VkCommandBufferUsageFlagBits',desc='Bitmask specifying usage behavior for command buffer',type='enums'] |
| -- |
| Bits which can: be set in slink:VkCommandBufferBeginInfo::pname:flags to |
| specify usage behavior for a command buffer are: |
| |
| include::{generated}/api/enums/VkCommandBufferUsageFlagBits.txt[] |
| |
| * ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT specifies that each |
| recording of the command buffer will only be submitted once, and the |
| command buffer will be reset and recorded again between each submission. |
| * ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT specifies that a |
| secondary command buffer is considered to be entirely inside a render |
| pass. |
| If this is a primary command buffer, then this bit is ignored. |
| * ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT specifies that a |
| command buffer can: be resubmitted to a queue while it is in the |
| _pending state_, and recorded into multiple primary command buffers. |
| -- |
| |
| [open,refpage='VkCommandBufferUsageFlags',desc='Bitmask of VkCommandBufferUsageFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkCommandBufferUsageFlags.txt[] |
| |
| tname:VkCommandBufferUsageFlags is a bitmask type for setting a mask of zero |
| or more elink:VkCommandBufferUsageFlagBits. |
| -- |
| |
| [open,refpage='VkCommandBufferInheritanceInfo',desc='Structure specifying command buffer inheritance information',type='structs'] |
| -- |
| If the command buffer is a secondary command buffer, then the |
| sname:VkCommandBufferInheritanceInfo structure defines any state that will |
| be inherited from the primary command buffer: |
| |
| include::{generated}/api/structs/VkCommandBufferInheritanceInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:renderPass is a slink:VkRenderPass object defining which render |
| passes the sname:VkCommandBuffer will be <<renderpass-compatibility, |
| compatible>> with and can: be executed within. |
| * pname:subpass is the index of the subpass within the render pass |
| instance that the sname:VkCommandBuffer will be executed within. |
| * pname:framebuffer can: refer to the slink:VkFramebuffer object that the |
| sname:VkCommandBuffer will be rendering to if it is executed within a |
| render pass instance. |
| It can: be dlink:VK_NULL_HANDLE if the framebuffer is not known. |
| + |
| [NOTE] |
| .Note |
| ==== |
| Specifying the exact framebuffer that the secondary command buffer will be |
| executed with may: result in better performance at command buffer execution |
| time. |
| ==== |
| * pname:occlusionQueryEnable specifies whether the command buffer can: be |
| executed while an occlusion query is active in the primary command |
| buffer. |
| If this is ename:VK_TRUE, then this command buffer can: be executed |
| whether the primary command buffer has an occlusion query active or not. |
| If this is ename:VK_FALSE, then the primary command buffer must: not |
| have an occlusion query active. |
| * pname:queryFlags specifies the query flags that can: be used by an |
| active occlusion query in the primary command buffer when this secondary |
| command buffer is executed. |
| If this value includes the ename:VK_QUERY_CONTROL_PRECISE_BIT bit, then |
| the active query can: return boolean results or actual sample counts. |
| If this bit is not set, then the active query must: not use the |
| ename:VK_QUERY_CONTROL_PRECISE_BIT bit. |
| * pname:pipelineStatistics is a bitmask of |
| elink:VkQueryPipelineStatisticFlagBits specifying the set of pipeline |
| statistics that can: be counted by an active query in the primary |
| command buffer when this secondary command buffer is executed. |
| If this value includes a given bit, then this command buffer can: be |
| executed whether the primary command buffer has a pipeline statistics |
| query active that includes this bit or not. |
| If this value excludes a given bit, then the active pipeline statistics |
| query must: not be from a query pool that counts that statistic. |
| |
| If the slink:VkCommandBuffer will not be executed within a render pass |
| instance, |
| ifdef::VK_KHR_dynamic_rendering[] |
| or if the render pass instance was begun with flink:vkCmdBeginRenderingKHR, |
| endif::VK_KHR_dynamic_rendering[] |
| pname:renderPass, pname:subpass, and pname:framebuffer are ignored. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkCommandBufferInheritanceInfo-occlusionQueryEnable-00056]] |
| If the <<features-inheritedQueries,inherited queries>> feature is not |
| enabled, pname:occlusionQueryEnable must: be ename:VK_FALSE |
| * [[VUID-VkCommandBufferInheritanceInfo-queryFlags-00057]] |
| If the <<features-inheritedQueries,inherited queries>> feature is |
| enabled, pname:queryFlags must: be a valid combination of |
| elink:VkQueryControlFlagBits values |
| * [[VUID-VkCommandBufferInheritanceInfo-queryFlags-02788]] |
| If the <<features-inheritedQueries,inherited queries>> feature is not |
| enabled, pname:queryFlags must: be code:0 |
| * [[VUID-VkCommandBufferInheritanceInfo-pipelineStatistics-02789]] |
| If the <<features-pipelineStatisticsQuery,pipeline statistics queries>> |
| feature is enabled, pname:pipelineStatistics must: be a valid |
| combination of elink:VkQueryPipelineStatisticFlagBits values |
| * [[VUID-VkCommandBufferInheritanceInfo-pipelineStatistics-00058]] |
| If the <<features-pipelineStatisticsQuery,pipeline statistics queries>> |
| feature is not enabled, pname:pipelineStatistics must: be code:0 |
| **** |
| |
| include::{generated}/validity/structs/VkCommandBufferInheritanceInfo.txt[] |
| -- |
| |
| [NOTE] |
| .Note |
| ==== |
| On some implementations, not using the |
| ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT bit enables command |
| buffers to be patched in-place if needed, rather than creating a copy of the |
| command buffer. |
| ==== |
| |
| If a command buffer is in the <<commandbuffers-lifecycle, invalid, or |
| executable state>>, and the command buffer was allocated from a command pool |
| with the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, |
| then fname:vkBeginCommandBuffer implicitly resets the command buffer, |
| behaving as if fname:vkResetCommandBuffer had been called with |
| ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT not set. |
| After the implicit reset, pname:commandBuffer is moved to the |
| <<commandbuffers-lifecycle, recording state>>. |
| |
| ifdef::VK_EXT_conditional_rendering[] |
| [open,refpage='VkCommandBufferInheritanceConditionalRenderingInfoEXT',desc='Structure specifying command buffer inheritance information',type='structs'] |
| -- |
| If the pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes a |
| sname:VkCommandBufferInheritanceConditionalRenderingInfoEXT structure, then |
| that structure controls whether a command buffer can: be executed while |
| conditional rendering is <<active-conditional-rendering,active>> in the |
| primary command buffer. |
| |
| The sname:VkCommandBufferInheritanceConditionalRenderingInfoEXT structure is |
| defined as: |
| |
| include::{generated}/api/structs/VkCommandBufferInheritanceConditionalRenderingInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:conditionalRenderingEnable specifies whether the command buffer |
| can: be executed while conditional rendering is active in the primary |
| command buffer. |
| If this is ename:VK_TRUE, then this command buffer can: be executed |
| whether the primary command buffer has active conditional rendering or |
| not. |
| If this is ename:VK_FALSE, then the primary command buffer must: not |
| have conditional rendering active. |
| |
| If this structure is not present, the behavior is as if |
| pname:conditionalRenderingEnable is ename:VK_FALSE. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkCommandBufferInheritanceConditionalRenderingInfoEXT-conditionalRenderingEnable-01977]] |
| If the <<features-inheritedConditionalRendering, inherited conditional |
| rendering>> feature is not enabled, pname:conditionalRenderingEnable |
| must: be ename:VK_FALSE |
| **** |
| |
| include::{generated}/validity/structs/VkCommandBufferInheritanceConditionalRenderingInfoEXT.txt[] |
| -- |
| endif::VK_EXT_conditional_rendering[] |
| |
| ifdef::VK_QCOM_render_pass_transform[] |
| [open,refpage='VkCommandBufferInheritanceRenderPassTransformInfoQCOM',desc='Structure describing transformed render pass parameters command buffer',type='structs'] |
| -- |
| |
| To begin recording a secondary command buffer compatible with execution |
| inside a render pass using <<vertexpostproc-renderpass-transform, render |
| pass transform>>, add the |
| slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM to the |
| pname:pNext chain of slink:VkCommandBufferInheritanceInfo structure passed |
| to the flink:vkBeginCommandBuffer command specifying the parameters for |
| transformed rasterization. |
| |
| The sname:VkCommandBufferInheritanceRenderPassTransformInfoQCOM structure is |
| defined as: |
| |
| include::{generated}/api/structs/VkCommandBufferInheritanceRenderPassTransformInfoQCOM.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:transform is a elink:VkSurfaceTransformFlagBitsKHR value |
| describing the transform to be applied to the render pass. |
| * pname:renderArea is the render area that is affected by the command |
| buffer. |
| |
| When the secondary is recorded to execute within a render pass instance |
| using flink:vkCmdExecuteCommands, the render pass transform parameters of |
| the secondary command buffer must: be consistent with the render pass |
| transform parameters specified for the render pass instance. |
| In particular, the pname:transform and pname:renderArea for command buffer |
| must: be identical to the pname:transform and pname:renderArea of the render |
| pass instance. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkCommandBufferInheritanceRenderPassTransformInfoQCOM-transform-02864]] |
| pname:transform must: be ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, |
| ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, |
| ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or |
| ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR |
| **** |
| |
| include::{generated}/validity/structs/VkCommandBufferInheritanceRenderPassTransformInfoQCOM.txt[] |
| -- |
| endif::VK_QCOM_render_pass_transform[] |
| |
| ifdef::VK_NV_inherited_viewport_scissor[] |
| [open,refpage='VkCommandBufferInheritanceViewportScissorInfoNV',desc='Structure specifying command buffer inheritance information',type='structs'] |
| -- |
| The sname:VkCommandBufferInheritanceViewportScissorInfoNV structure is |
| defined as: |
| |
| include::{generated}/api/structs/VkCommandBufferInheritanceViewportScissorInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:viewportScissor2D specifies whether the listed dynamic state is |
| inherited. |
| * pname:viewportDepthCount specifies the maximum number of viewports to |
| inherit. |
| When pname:viewportScissor2D is ename:VK_FALSE, the behavior is as if |
| this value is zero. |
| * pname:pViewportDepths is a pointer to a slink:VkViewport structure |
| specifying the expected depth range for each inherited viewport. |
| |
| If the pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes a |
| sname:VkCommandBufferInheritanceViewportScissorInfoNV structure, then that |
| structure controls whether a command buffer can: inherit the following state |
| from other command buffers: |
| |
| * ename:VK_DYNAMIC_STATE_SCISSOR |
| ifdef::VK_EXT_extended_dynamic_state[] |
| * ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT |
| endif::VK_EXT_extended_dynamic_state[] |
| ifdef::VK_EXT_discard_rectangles[] |
| * ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT |
| endif::VK_EXT_discard_rectangles[] |
| |
| as well as the following state, with restrictions on inherited depth values |
| and viewport count: |
| |
| * ename:VK_DYNAMIC_STATE_VIEWPORT |
| ifdef::VK_EXT_extended_dynamic_state[] |
| * ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT |
| endif::VK_EXT_extended_dynamic_state[] |
| |
| If pname:viewportScissor2D is ename:VK_FALSE, then the command buffer does |
| not inherit the listed dynamic state, and should: set this state itself. |
| If this structure is not present, the behavior is as if |
| pname:viewportScissor2D is ename:VK_FALSE. |
| |
| If pname:viewportScissor2D is ename:VK_TRUE, then the listed dynamic state |
| is inherited, and the command buffer must: not set this |
| ifndef::VK_EXT_extended_dynamic_state[state.] |
| ifdef::VK_EXT_extended_dynamic_state[] |
| state, except that the viewport and scissor count may: be set by binding a |
| graphics pipeline that does not specify this state as dynamic. |
| |
| [NOTE] |
| .Note |
| ==== |
| Due to this restriction, applications should: ensure either all or none of |
| the graphics pipelines bound in this secondary command buffer use dynamic |
| viewport/scissor counts. |
| ==== |
| endif::VK_EXT_extended_dynamic_state[] |
| |
| When the command buffer is executed as part of a the execution of a |
| flink:vkCmdExecuteCommands command, the inherited state (if enabled) is |
| determined by the following procedure, performed separately for each dynamic |
| state, and separately for each value for dynamic state that consists of |
| multiple values (e.g. multiple viewports). |
| |
| * With [eq]#i# being the index of the executed command buffer in the |
| pname:pCommandBuffers array of flink:vkCmdExecuteCommands, if [eq]#i > |
| 0# and any secondary command buffer from index [eq]#0# to [eq]#i-1# |
| modifies the state, the inherited state is provisionally set to the |
| final value set by the last such secondary command buffer. |
| Binding a graphics pipeline that defines the state statically is |
| equivalent to setting the state to an undefined: value. |
| * Otherwise, the tentatative inherited state is that of the primary |
| command buffer at the point the flink:vkCmdExecuteCommands command was |
| recorded; if the state is undefined:, then so is the provisional |
| inherited state. |
| * If the provisional inherited state is an undefined: value, then the |
| state is not inherited. |
| * If the provisional inherited state is a viewport, with [eq]#n# being its |
| viewport index, then if [eq]#n {geq} pname:viewportDepthCount#, or if |
| either slink:VkViewport::pname:minDepth or |
| slink:VkViewport::pname:maxDepth are not equal to the respective values |
| of the [eq]#n^th^# element of pname:pViewportDepths, then the state is |
| not inherited. |
| * If the provisional inherited state passes both checks, then it becomes |
| the actual inherited state. |
| |
| [NOTE] |
| .Note |
| ==== |
| There is no support for inheriting dynamic state from a secondary command |
| buffer executed as part of a different `vkCmdExecuteCommands` command. |
| ==== |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04782]] |
| If the <<features-inheritedViewportScissor2D, inherited viewport |
| scissor>> feature is not enabled, pname:viewportScissor2D must: be |
| ename:VK_FALSE |
| * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04783]] |
| If the <<features-multiViewport,multiple viewports>> feature is not |
| enabled and pname:viewportScissor2D is ename:VK_TRUE, then |
| pname:viewportDepthCount must: be `1` |
| * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04784]] |
| If pname:viewportScissor2D is ename:VK_TRUE, then |
| pname:viewportDepthCount must: be greater than `0` |
| * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04785]] |
| If pname:viewportScissor2D is ename:VK_TRUE, then pname:pViewportDepths |
| must: be a valid pointer to an array of `viewportDepthCount` valid |
| sname:VkViewport structures, except any requirements on `x`, `y`, |
| `width`, and `height` do not apply |
| * [[VUID-VkCommandBufferInheritanceViewportScissorInfoNV-viewportScissor2D-04786]] |
| If pname:viewportScissor2D is ename:VK_TRUE, then the command buffer |
| must: be recorded with the |
| ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT |
| **** |
| |
| include::{generated}/validity/structs/VkCommandBufferInheritanceViewportScissorInfoNV.txt[] |
| -- |
| endif::VK_NV_inherited_viewport_scissor[] |
| |
| ifdef::VK_KHR_dynamic_rendering[] |
| [open,refpage='VkCommandBufferInheritanceRenderingInfoKHR',desc='Structure specifying command buffer inheritance info for dynamic render pass instances',type='structs'] |
| -- |
| |
| The sname:VkCommandBufferInheritanceRenderingInfoKHR structure is defined |
| as: |
| |
| include::{generated}/api/structs/VkCommandBufferInheritanceRenderingInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure |
| * pname:flags is a bitmask of elink:VkRenderingFlagBitsKHR used by the |
| render pass instance. |
| * pname:viewMask is the view mask used for rendering. |
| * pname:colorAttachmentCount is the number of color attachments specified |
| in the render pass instance. |
| * pname:pColorAttachmentFormats is an array of elink:VkFormat values |
| defining the format of color attachments. |
| * pname:depthAttachmentFormat is a elink:VkFormat value defining the |
| format of the depth attachment. |
| * pname:stencilAttachmentFormat is a elink:VkFormat value defining the |
| format of the stencil attachment. |
| * pname:rasterizationSamples is a elink:VkSampleCountFlagBits specifying |
| the number of samples used in rasterization. |
| |
| If the pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes a |
| sname:VkCommandBufferInheritanceRenderingInfoKHR structure, then that |
| structure controls parameters of dynamic render pass instances that the |
| slink:VkCommandBuffer can: be executed within. |
| If slink:VkCommandBufferInheritanceInfo::pname:renderPass is not |
| dlink:VK_NULL_HANDLE, or |
| ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not specified in |
| slink:VkCommandBufferBeginInfo::pname:flags, parameters of this structure |
| are ignored. |
| |
| If pname:colorAttachmentCount is `0` and the |
| <<features-variableMultisampleRate,pname:variableMultisampleRate>> feature |
| is enabled, pname:rasterizationSamples is ignored. |
| |
| If pname:depthAttachmentFormat, pname:stencilAttachmentFormat, or any |
| element of pname:pColorAttachmentFormats is ename:VK_FORMAT_UNDEFINED, it |
| indicates that the corresponding attachment is unused within the render |
| pass. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-colorAttachmentCount-06004]] |
| If pname:colorAttachmentCount is not `0`, pname:rasterizationSamples |
| must: be a valid elink:VkSampleCountFlagBits value |
| * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-variableMultisampleRate-06005]] |
| If the |
| <<features-variableMultisampleRate,pname:variableMultisampleRate>> |
| feature is not enabled, pname:rasterizationSamples must: be a valid |
| elink:VkSampleCountFlagBits value |
| * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-pColorAttachmentFormats-06006]] |
| If any element of pname:pColorAttachmentFormats is not |
| ename:VK_FORMAT_UNDEFINED, it must: be a format with |
| <<potential-format-features, potential format features>> that include |
| ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT |
| * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-depthAttachmentFormat-06007]] |
| If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it |
| must: be a format with <<potential-format-features, potential format |
| features>> that include |
| ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT |
| * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-stencilAttachmentFormat-06199]] |
| If pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it |
| must: be a format with <<potential-format-features, potential format |
| features>> that include |
| ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT |
| * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-depthAttachmentFormat-06200]] |
| If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED and |
| pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, |
| pname:depthAttachmentFormat must: equal pname:stencilAttachmentFormat |
| * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-multiview-06008]] |
| If the <<features-multiview,pname:multiview>> feature is not enabled, |
| pname:viewMask must: be `0` |
| ifdef::VK_VERSION_1_1,VK_KHR_multiview[] |
| * [[VUID-VkCommandBufferInheritanceRenderingInfoKHR-viewMask-06009]] |
| The index of the most significant bit in pname:viewMask must: be less |
| than <<limits-maxMultiviewViewCount,pname:maxMultiviewViewCount>> |
| endif::VK_VERSION_1_1,VK_KHR_multiview[] |
| **** |
| |
| include::{generated}/validity/structs/VkCommandBufferInheritanceRenderingInfoKHR.txt[] |
| -- |
| |
| ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] |
| [open,refpage='VkAttachmentSampleCountInfoAMD',desc='Structure specifying command buffer inheritance info for dynamic render pass instances',type='structs',alias='VkAttachmentSampleCountInfoNV'] |
| -- |
| |
| The |
| ifdef::VK_AMD_mixed_attachment_samples[sname:VkAttachmentSampleCountInfoAMD] |
| ifdef::VK_AMD_mixed_attachment_samples+VK_NV_framebuffer_mixed_samples[or] |
| ifdef::VK_NV_framebuffer_mixed_samples[sname:VkAttachmentSampleCountInfoNV] |
| structure is defined as: |
| |
| ifdef::VK_AMD_mixed_attachment_samples[] |
| include::{generated}/api/structs/VkAttachmentSampleCountInfoAMD.txt[] |
| endif::VK_AMD_mixed_attachment_samples[] |
| |
| ifdef::VK_AMD_mixed_attachment_samples+VK_NV_framebuffer_mixed_samples[or the equivalent] |
| |
| ifdef::VK_NV_framebuffer_mixed_samples[] |
| include::{generated}/api/structs/VkAttachmentSampleCountInfoNV.txt[] |
| endif::VK_NV_framebuffer_mixed_samples[] |
| |
| * pname:sType is the type of this structure |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure |
| * pname:colorAttachmentCount is the number of color attachments specified |
| in a render pass instance. |
| * pname:pColorAttachmentSamples is an array of elink:VkSampleCountFlagBits |
| values defining the sample count of color attachments. |
| * pname:depthStencilAttachmentSamples is a elink:VkSampleCountFlagBits |
| value defining the sample count of a depth/stencil attachment. |
| |
| If slink:VkCommandBufferInheritanceInfo::pname:renderPass is |
| dlink:VK_NULL_HANDLE, ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT |
| is specified in slink:VkCommandBufferBeginInfo::pname:flags, and the |
| pname:pNext chain of slink:VkCommandBufferInheritanceInfo includes |
| sname:VkAttachmentSampleCountInfoAMD, then this structure defines the sample |
| counts of each attachment within the render pass instance. |
| If sname:VkAttachmentSampleCountInfoAMD is not included, the value of |
| slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:rasterizationSamples |
| is used as the sample count for each attachment. |
| If slink:VkCommandBufferInheritanceInfo::pname:renderPass is not |
| dlink:VK_NULL_HANDLE, or |
| ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not specified in |
| slink:VkCommandBufferBeginInfo::pname:flags, parameters of this structure |
| are ignored. |
| |
| sname:VkAttachmentSampleCountInfoAMD can: also be included in the |
| pname:pNext chain of slink:VkGraphicsPipelineCreateInfo. |
| When a graphics pipeline is created without a slink:VkRenderPass, if this |
| structure is present in the pname:pNext chain of |
| slink:VkGraphicsPipelineCreateInfo, it specifies the sample count of |
| attachments used for rendering. |
| If this structure is not specified, and the pipeline does not include a |
| slink:VkRenderPass, the value of |
| slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples is |
| used as the sample count for each attachment. |
| If a graphics pipeline is created with a valid slink:VkRenderPass, |
| parameters of this structure are ignored. |
| |
| include::{generated}/validity/structs/VkAttachmentSampleCountInfoAMD.txt[] |
| -- |
| endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] |
| |
| endif::VK_KHR_dynamic_rendering[] |
| |
| Once recording starts, an application records a sequence of commands |
| (ftext:vkCmd*) to set state in the command buffer, draw, dispatch, and other |
| commands. |
| |
| ifdef::VK_NV_device_generated_commands[] |
| Several commands can also be recorded indirectly from sname:VkBuffer |
| content, see <<device-generated-commands>>. |
| endif::VK_NV_device_generated_commands[] |
| |
| [open,refpage='vkEndCommandBuffer',desc='Finish recording a command buffer',type='protos'] |
| -- |
| To complete recording of a command buffer, call: |
| |
| include::{generated}/api/protos/vkEndCommandBuffer.txt[] |
| |
| * pname:commandBuffer is the command buffer to complete recording. |
| |
| If there was an error during recording, the application will be notified by |
| an unsuccessful return code returned by fname:vkEndCommandBuffer. |
| If the application wishes to further use the command buffer, the command |
| buffer must: be reset. |
| |
| The command buffer must: have been in the <<commandbuffers-lifecycle, |
| recording state>>, and is moved to the <<commandbuffers-lifecycle, |
| executable state>>. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkEndCommandBuffer-commandBuffer-00059]] |
| pname:commandBuffer must: be in the <<commandbuffers-lifecycle, |
| recording state>> |
| * [[VUID-vkEndCommandBuffer-commandBuffer-00060]] |
| If pname:commandBuffer is a primary command buffer, there must: not be |
| an active render pass instance |
| * [[VUID-vkEndCommandBuffer-commandBuffer-00061]] |
| All queries made <<queries-operation-active,active>> during the |
| recording of pname:commandBuffer must: have been made inactive |
| ifdef::VK_EXT_conditional_rendering[] |
| * [[VUID-vkEndCommandBuffer-None-01978]] |
| Conditional rendering must: not be |
| <<active-conditional-rendering,active>> |
| endif::VK_EXT_conditional_rendering[] |
| ifdef::VK_EXT_debug_utils[] |
| * [[VUID-vkEndCommandBuffer-commandBuffer-01815]] |
| If pname:commandBuffer is a secondary command buffer, there must: not be |
| an outstanding flink:vkCmdBeginDebugUtilsLabelEXT command recorded to |
| pname:commandBuffer that has not previously been ended by a call to |
| flink:vkCmdEndDebugUtilsLabelEXT |
| endif::VK_EXT_debug_utils[] |
| ifdef::VK_EXT_debug_marker[] |
| * [[VUID-vkEndCommandBuffer-commandBuffer-00062]] |
| If pname:commandBuffer is a secondary command buffer, there must: not be |
| an outstanding flink:vkCmdDebugMarkerBeginEXT command recorded to |
| pname:commandBuffer that has not previously been ended by a call to |
| flink:vkCmdDebugMarkerEndEXT |
| endif::VK_EXT_debug_marker[] |
| **** |
| |
| include::{generated}/validity/protos/vkEndCommandBuffer.txt[] |
| -- |
| |
| When a command buffer is in the executable state, it can: be submitted to a |
| queue for execution. |
| |
| |
| [[commandbuffers-submission]] |
| == Command Buffer Submission |
| |
| [NOTE] |
| .Note |
| ==== |
| Submission can be a high overhead operation, and applications should: |
| attempt to batch work together into as few calls to fname:vkQueueSubmit |
| ifdef::VK_KHR_synchronization2[] |
| or fname:vkQueueSubmit2KHR |
| endif::VK_KHR_synchronization2[] |
| as possible. |
| ==== |
| |
| ifdef::VK_KHR_synchronization2[] |
| [open,refpage='vkQueueSubmit2KHR',desc='Submits command buffers to a queue',type='protos'] |
| -- |
| To submit command buffers to a queue, call: |
| |
| include::{generated}/api/protos/vkQueueSubmit2KHR.txt[] |
| |
| * pname:queue is the queue that the command buffers will be submitted to. |
| * pname:submitCount is the number of elements in the pname:pSubmits array. |
| * pname:pSubmits is a pointer to an array of slink:VkSubmitInfo2KHR |
| structures, each specifying a command buffer submission batch. |
| * pname:fence is an optional: handle to a fence to be signaled once all |
| submitted command buffers have completed execution. |
| If pname:fence is not dlink:VK_NULL_HANDLE, it defines a |
| <<synchronization-fences-signaling, fence signal operation>>. |
| |
| fname:vkQueueSubmit2KHR is a <<devsandqueues-submission,queue submission |
| command>>, with each batch defined by an element of pname:pSubmits. |
| |
| Semaphore operations submitted with flink:vkQueueSubmit2KHR have additional |
| ordering constraints compared to other submission commands, with |
| dependencies involving previous and subsequent queue operations. |
| Information about these additional constraints can be found in the |
| <<synchronization-semaphores, semaphore>> section of <<synchronization, the |
| synchronization chapter>>. |
| |
| If any command buffer submitted to this queue is in the |
| <<commandbuffers-lifecycle, executable state>>, it is moved to the |
| <<commandbuffers-lifecycle, pending state>>. |
| Once execution of all submissions of a command buffer complete, it moves |
| from the <<commandbuffers-lifecycle, pending state>>, back to the |
| <<commandbuffers-lifecycle, executable state>>. |
| If a command buffer was recorded with the |
| ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves |
| back to the <<commandbuffers-lifecycle, invalid state>>. |
| |
| If fname:vkQueueSubmit2KHR fails, it may: return |
| ename:VK_ERROR_OUT_OF_HOST_MEMORY or ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. |
| If it does, the implementation must: ensure that the state and contents of |
| any resources or synchronization primitives referenced by the submitted |
| command buffers and any semaphores referenced by pname:pSubmits is |
| unaffected by the call or its failure. |
| If fname:vkQueueSubmit2KHR fails in such a way that the implementation is |
| unable to make that guarantee, the implementation must: return |
| ename:VK_ERROR_DEVICE_LOST. |
| See <<devsandqueues-lost-device,Lost Device>>. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkQueueSubmit2KHR-fence-04894]] |
| If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be |
| unsignaled |
| * [[VUID-vkQueueSubmit2KHR-fence-04895]] |
| If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be |
| associated with any other queue command that has not yet completed |
| execution on that queue |
| * [[VUID-vkQueueSubmit2KHR-synchronization2-03866]] |
| The <<features-synchronization2, pname:synchronization2>> feature must: |
| be enabled |
| * [[VUID-vkQueueSubmit2KHR-commandBuffer-03867]] |
| If a command recorded into the pname:commandBuffer member of any element |
| of the pname:pCommandBufferInfos member of any element of pname:pSubmits |
| referenced an slink:VkEvent, that event must: not be referenced by a |
| command that has been submitted to another queue and is still in the |
| _pending state_ |
| * [[VUID-vkQueueSubmit2KHR-semaphore-03868]] |
| The pname:semaphore member of any binary semaphore element of the |
| pname:pSignalSemaphoreInfos member of any element of pname:pSubmits |
| must: be unsignaled when the semaphore signal operation it defines is |
| executed on the device |
| * [[VUID-vkQueueSubmit2KHR-stageMask-03869]] |
| The pname:stageMask member of any element of the |
| pname:pSignalSemaphoreInfos member of any element of pname:pSubmits |
| must: only include pipeline stages that are supported by the queue |
| family which pname:queue belongs to |
| * [[VUID-vkQueueSubmit2KHR-stageMask-03870]] |
| The pname:stageMask member of any element of the |
| pname:pWaitSemaphoreInfos member of any element of pname:pSubmits must: |
| only include pipeline stages that are supported by the queue family |
| which pname:queue belongs to |
| * [[VUID-vkQueueSubmit2KHR-semaphore-03871]] |
| When a semaphore wait operation for a binary semaphore is executed, as |
| defined by the pname:semaphore member of any element of the |
| pname:pWaitSemaphoreInfos member of any element of pname:pSubmits, there |
| must: be no other queues waiting on the same semaphore |
| * [[VUID-vkQueueSubmit2KHR-semaphore-03872]] |
| The pname:semaphore member of any element of the |
| pname:pWaitSemaphoreInfos member of any element of pname:pSubmits must: |
| be semaphores that are signaled, or have |
| <<synchronization-semaphores-signaling, semaphore signal operations>> |
| previously submitted for execution |
| ifdef::VK_KHR_timeline_semaphore[] |
| * [[VUID-vkQueueSubmit2KHR-semaphore-03873]] |
| Any pname:semaphore member of any element of the |
| pname:pWaitSemaphoreInfos member of any element of pname:pSubmits that |
| was created with a elink:VkSemaphoreTypeKHR of |
| ename:VK_SEMAPHORE_TYPE_BINARY_KHR must: reference a semaphore signal |
| operation that has been submitted for execution and any semaphore signal |
| operations on which it depends (if any) must: have also been submitted |
| for execution |
| endif::VK_KHR_timeline_semaphore[] |
| * [[VUID-vkQueueSubmit2KHR-commandBuffer-03874]] |
| The pname:commandBuffer member of any element of the |
| pname:pCommandBufferInfos member of any element of pname:pSubmits must: |
| be in the <<commandbuffers-lifecycle, pending or executable state>> |
| * [[VUID-vkQueueSubmit2KHR-commandBuffer-03875]] |
| If a command recorded into the pname:commandBuffer member of any element |
| of the pname:pCommandBufferInfos member of any element of pname:pSubmits |
| was not recorded with the |
| ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in |
| the <<commandbuffers-lifecycle, pending state>> |
| * [[VUID-vkQueueSubmit2KHR-commandBuffer-03876]] |
| Any <<commandbuffers-secondary, secondary command buffers recorded>> |
| into the pname:commandBuffer member of any element of the |
| pname:pCommandBufferInfos member of any element of pname:pSubmits must: |
| be in the <<commandbuffers-lifecycle, pending or executable state>> |
| * [[VUID-vkQueueSubmit2KHR-commandBuffer-03877]] |
| If any <<commandbuffers-secondary, secondary command buffers recorded>> |
| into the pname:commandBuffer member of any element of the |
| pname:pCommandBufferInfos member of any element of pname:pSubmits was |
| not recorded with the |
| ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in |
| the <<commandbuffers-lifecycle, pending state>> |
| * [[VUID-vkQueueSubmit2KHR-commandBuffer-03878]] |
| The pname:commandBuffer member of any element of the |
| pname:pCommandBufferInfos member of any element of pname:pSubmits must: |
| have been allocated from a sname:VkCommandPool that was created for the |
| same queue family pname:queue belongs to |
| * [[VUID-vkQueueSubmit2KHR-commandBuffer-03879]] |
| If a command recorded into the pname:commandBuffer member of any element |
| of the pname:pCommandBufferInfos member of any element of pname:pSubmits |
| includes a <<synchronization-queue-transfers-acquire, Queue Family |
| Transfer Acquire Operation>>, there must: exist a previously submitted |
| <<synchronization-queue-transfers-release, Queue Family Transfer Release |
| Operation>> on a queue in the queue family identified by the acquire |
| operation, with parameters matching the acquire operation as defined in |
| the definition of such <<synchronization-queue-transfers-acquire, |
| acquire operations>>, and which happens before the acquire operation |
| ifdef::VK_KHR_performance_query[] |
| * [[VUID-vkQueueSubmit2KHR-commandBuffer-03880]] |
| If a command recorded into the pname:commandBuffer member of any element |
| of the pname:pCommandBufferInfos member of any element of pname:pSubmits |
| was a flink:vkCmdBeginQuery whose pname:queryPool was created with a |
| pname:queryType of ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the |
| <<profiling-lock, profiling lock>> must: have been held continuously on |
| the sname:VkDevice that pname:queue was retrieved from, throughout |
| recording of those command buffers |
| endif::VK_KHR_performance_query[] |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkQueueSubmit2KHR-queue-06447]] |
| If pname:queue was not created with |
| ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, the pname:flags member of |
| any element of pname:pSubmits must: not include |
| ename:VK_SUBMIT_PROTECTED_BIT_KHR |
| endif::VK_VERSION_1_1[] |
| **** |
| |
| include::{generated}/validity/protos/vkQueueSubmit2KHR.txt[] |
| -- |
| |
| [open,refpage='VkSubmitInfo2KHR',desc='Structure specifying a queue submit operation',type='structs'] |
| -- |
| The sname:VkSubmitInfo2KHR structure is defined as: |
| |
| include::{generated}/api/structs/VkSubmitInfo2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkSubmitFlagBitsKHR. |
| * pname:waitSemaphoreInfoCount is the number of elements in |
| pname:pWaitSemaphoreInfos. |
| * pname:pWaitSemaphoreInfos is a pointer to an array of |
| slink:VkSemaphoreSubmitInfoKHR structures defining |
| <<synchronization-semaphores-waiting, semaphore wait operations>>. |
| * pname:commandBufferInfoCount is the number of elements in |
| pname:pCommandBufferInfos and the number of command buffers to execute |
| in the batch. |
| * pname:pCommandBufferInfos is a pointer to an array of |
| slink:VkCommandBufferSubmitInfoKHR structures describing command buffers |
| to execute in the batch. |
| * pname:signalSemaphoreInfoCount is the number of elements in |
| pname:pSignalSemaphoreInfos. |
| * pname:pSignalSemaphoreInfos is a pointer to an array of |
| slink:VkSemaphoreSubmitInfoKHR describing |
| <<synchronization-semaphores-signaling, semaphore signal operations>>. |
| |
| .Valid Usage |
| **** |
| ifdef::VK_KHR_timeline_semaphore[] |
| * [[VUID-VkSubmitInfo2KHR-semaphore-03881]] |
| If the same semaphore is used as the pname:semaphore member of both an |
| element of pname:pSignalSemaphoreInfos and pname:pWaitSemaphoreInfos, |
| and that semaphore is a timeline semaphore, the pname:value member of |
| the pname:pSignalSemaphoreInfos element must: be greater than the |
| pname:value member of the pname:pWaitSemaphoreInfos element |
| * [[VUID-VkSubmitInfo2KHR-semaphore-03882]] |
| If the pname:semaphore member of any element of |
| pname:pSignalSemaphoreInfos is a timeline semaphore, the pname:value |
| member of that element must: have a value greater than the current value |
| of the semaphore when the <<synchronization-semaphores-signaling, |
| semaphore signal operation>> is executed |
| * [[VUID-VkSubmitInfo2KHR-semaphore-03883]] |
| If the pname:semaphore member of any element of |
| pname:pSignalSemaphoreInfos is a timeline semaphore, the pname:value |
| member of that element must: have a value which does not differ from the |
| current value of the semaphore or the value of any outstanding semaphore |
| wait or signal operation on that semaphore by more than |
| <<limits-maxTimelineSemaphoreValueDifference, |
| pname:maxTimelineSemaphoreValueDifference>> |
| * [[VUID-VkSubmitInfo2KHR-semaphore-03884]] |
| If the pname:semaphore member of any element of |
| pname:pWaitSemaphoreInfos is a timeline semaphore, the pname:value |
| member of that element must: have a value which does not differ from the |
| current value of the semaphore or the value of any outstanding semaphore |
| wait or signal operation on that semaphore by more than |
| <<limits-maxTimelineSemaphoreValueDifference, |
| pname:maxTimelineSemaphoreValueDifference>> |
| endif::VK_KHR_timeline_semaphore[] |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-VkSubmitInfo2KHR-flags-03886]] |
| If pname:flags includes ename:VK_SUBMIT_PROTECTED_BIT_KHR, all elements |
| of pname:pCommandBuffers must: be protected command buffers |
| * [[VUID-VkSubmitInfo2KHR-flags-03887]] |
| If pname:flags does not include ename:VK_SUBMIT_PROTECTED_BIT_KHR, each |
| element of pname:pCommandBuffers must: not be a protected command buffer |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_KHR_dynamic_rendering[] |
| * [[VUID-VkSubmitInfo2KHR-commandBuffer-06192]] |
| If any pname:commandBuffer member of an element of |
| pname:pCommandBufferInfos contains any <<renderpass-suspension,resumed |
| render pass instances>>, they must: be suspended by a render pass |
| instance earlier in submission order within pname:pCommandBufferInfos |
| * [[VUID-VkSubmitInfo2KHR-commandBuffer-06010]] |
| If any pname:commandBuffer member of an element of |
| pname:pCommandBufferInfos contains any <<renderpass-suspension,suspended |
| render pass instances>>, they must: be resumed by a render pass instance |
| later in submission order within pname:pCommandBufferInfos |
| * [[VUID-VkSubmitInfo2KHR-commandBuffer-06011]] |
| If any pname:commandBuffer member of an element of |
| pname:pCommandBufferInfos contains any <<renderpass-suspension,suspended |
| render pass instances>>, there must: be no action or synchronization |
| commands between that render pass instance and the render pass instance |
| that resumes it |
| * [[VUID-VkSubmitInfo2KHR-commandBuffer-06012]] |
| If any pname:commandBuffer member of an element of |
| pname:pCommandBufferInfos contains any <<renderpass-suspension,suspended |
| render pass instances>>, there must: be no render pass instances between |
| that render pass instance and the render pass instance that resumes it |
| ifdef::VK_EXT_sample_locations[] |
| * [[VUID-VkSubmitInfo2KHR-variableSampleLocations-06013]] |
| If the <<limits-variableSampleLocations, pname:variableSampleLocations>> |
| limit is not supported, and any pname:commandBuffer member of an element |
| of pname:pCommandBufferInfos contains any |
| <<renderpass-suspension,suspended render pass instances>>, where a |
| graphics pipeline has been bound, any pipelines bound in the render pass |
| instance that resumes it, or any subsequent render pass instances that |
| resume from that one and so on, must: use the same sample locations |
| endif::VK_EXT_sample_locations[] |
| endif::VK_KHR_dynamic_rendering[] |
| **** |
| |
| include::{generated}/validity/structs/VkSubmitInfo2KHR.txt[] |
| -- |
| |
| [open,refpage='VkSubmitFlagBitsKHR',desc='Bitmask specifying behavior of a submission',type='enums'] |
| -- |
| Bits which can: be set in slink:VkSubmitInfo2KHR::pname:flags to specify |
| submission behavior are: |
| |
| include::{generated}/api/enums/VkSubmitFlagBitsKHR.txt[] |
| |
| * ename:VK_SUBMIT_PROTECTED_BIT_KHR specifies that this batch is a |
| protected submission. |
| -- |
| |
| [open,refpage='VkSubmitFlagsKHR',desc='Bitmask of VkSubmitFlagBitsKHR',type='flags'] |
| -- |
| include::{generated}/api/flags/VkSubmitFlagsKHR.txt[] |
| |
| tname:VkSubmitFlagsKHR is a bitmask type for setting a mask of zero or more |
| elink:VkSubmitFlagBitsKHR. |
| -- |
| |
| [open,refpage='VkSemaphoreSubmitInfoKHR',desc='Structure specifying a semaphore signal or wait operation',type='structs'] |
| -- |
| :refpage: VkSemaphoreSubmitInfoKHR |
| |
| The sname:VkSemaphoreSubmitInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkSemaphoreSubmitInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:semaphore is a slink:VkSemaphore affected by this operation. |
| * pname:value is |
| ifdef::VK_KHR_timeline_semaphore[] |
| either the value used to signal pname:semaphore or the value waited on |
| by pname:semaphore, if pname:semaphore is a timeline semaphore. |
| Otherwise it is |
| endif::VK_KHR_timeline_semaphore[] |
| ignored. |
| * pname:stageMask is a tlink:VkPipelineStageFlags2KHR mask of pipeline |
| stages which limit the first synchronization scope of a semaphore signal |
| operation, or second synchronization scope of a semaphore wait operation |
| as described in the <<synchronization-semaphores-waiting, semaphore wait |
| operation>> and <<synchronization-semaphores-signaling, semaphore signal |
| operation>> sections of <<synchronization, the synchronization |
| chapter>>. |
| * pname:deviceIndex is the index of the device within a device group that |
| executes the semaphore wait or signal operation. |
| |
| Whether this structure defines a semaphore wait or signal operation is |
| defined by how it is used. |
| |
| .Valid Usage |
| **** |
| :stageMaskName: stageMask |
| include::{chapters}/commonvalidity/stage_mask_2_common.txt[] |
| * [[VUID-VkSemaphoreSubmitInfoKHR-device-03888]] |
| If the pname:device that pname:semaphore was created on is not a device |
| group, pname:deviceIndex must: be `0` |
| ifdef::VK_KHR_device_group_creation,VK_VERSION_1_1[] |
| * [[VUID-VkSemaphoreSubmitInfoKHR-device-03889]] |
| If the pname:device that pname:semaphore was created on is a device |
| group, pname:deviceIndex must: be a valid device index |
| endif::VK_KHR_device_group_creation,VK_VERSION_1_1[] |
| **** |
| |
| include::{generated}/validity/structs/VkSemaphoreSubmitInfoKHR.txt[] |
| -- |
| |
| [open,refpage='VkCommandBufferSubmitInfoKHR',desc='Structure specifying a command buffer submission',type='structs'] |
| -- |
| The sname:VkCommandBufferSubmitInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkCommandBufferSubmitInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:commandBuffer is a slink:VkCommandBuffer to be submitted for |
| execution. |
| * pname:deviceMask is a bitmask indicating which devices in a device group |
| execute the command buffer. |
| A pname:deviceMask of `0` is equivalent to setting all bits |
| corresponding to valid devices in the group to `1`. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkCommandBufferSubmitInfoKHR-commandBuffer-03890]] |
| pname:commandBuffer must: not have been allocated with |
| ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY |
| ifdef::VK_KHR_device_group_creation,VK_VERSION_1_1[] |
| * [[VUID-VkCommandBufferSubmitInfoKHR-deviceMask-03891]] |
| If pname:deviceMask is not `0`, it must: be a valid device mask |
| endif::VK_KHR_device_group_creation,VK_VERSION_1_1[] |
| **** |
| |
| include::{generated}/validity/structs/VkCommandBufferSubmitInfoKHR.txt[] |
| -- |
| endif::VK_KHR_synchronization2[] |
| |
| [open,refpage='vkQueueSubmit',desc='Submits a sequence of semaphores or command buffers to a queue',type='protos'] |
| -- |
| To submit command buffers to a queue, call: |
| |
| include::{generated}/api/protos/vkQueueSubmit.txt[] |
| |
| * pname:queue is the queue that the command buffers will be submitted to. |
| * pname:submitCount is the number of elements in the pname:pSubmits array. |
| * pname:pSubmits is a pointer to an array of slink:VkSubmitInfo |
| structures, each specifying a command buffer submission batch. |
| * pname:fence is an optional: handle to a fence to be signaled once all |
| submitted command buffers have completed execution. |
| If pname:fence is not dlink:VK_NULL_HANDLE, it defines a |
| <<synchronization-fences-signaling, fence signal operation>>. |
| |
| fname:vkQueueSubmit is a <<devsandqueues-submission,queue submission |
| command>>, with each batch defined by an element of pname:pSubmits. |
| Batches begin execution in the order they appear in pname:pSubmits, but may: |
| complete out of order. |
| |
| Fence and semaphore operations submitted with flink:vkQueueSubmit have |
| additional ordering constraints compared to other submission commands, with |
| dependencies involving previous and subsequent queue operations. |
| Information about these additional constraints can be found in the |
| <<synchronization-semaphores, semaphore>> and <<synchronization-fences, |
| fence>> sections of <<synchronization, the synchronization chapter>>. |
| |
| Details on the interaction of pname:pWaitDstStageMask with synchronization |
| are described in the <<synchronization-semaphores-waiting, semaphore wait |
| operation>> section of <<synchronization, the synchronization chapter>>. |
| |
| The order that batches appear in pname:pSubmits is used to determine |
| <<synchronization-submission-order, submission order>>, and thus all the |
| <<synchronization-implicit, implicit ordering guarantees>> that respect it. |
| Other than these implicit ordering guarantees and any <<synchronization, |
| explicit synchronization primitives>>, these batches may: overlap or |
| otherwise execute out of order. |
| |
| If any command buffer submitted to this queue is in the |
| <<commandbuffers-lifecycle, executable state>>, it is moved to the |
| <<commandbuffers-lifecycle, pending state>>. |
| Once execution of all submissions of a command buffer complete, it moves |
| from the <<commandbuffers-lifecycle, pending state>>, back to the |
| <<commandbuffers-lifecycle, executable state>>. |
| If a command buffer was recorded with the |
| ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves to |
| the <<commandbuffers-lifecycle, invalid state>>. |
| |
| If fname:vkQueueSubmit fails, it may: return |
| ename:VK_ERROR_OUT_OF_HOST_MEMORY or ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. |
| If it does, the implementation must: ensure that the state and contents of |
| any resources or synchronization primitives referenced by the submitted |
| command buffers and any semaphores referenced by pname:pSubmits is |
| unaffected by the call or its failure. |
| If fname:vkQueueSubmit fails in such a way that the implementation is unable |
| to make that guarantee, the implementation must: return |
| ename:VK_ERROR_DEVICE_LOST. |
| See <<devsandqueues-lost-device,Lost Device>>. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkQueueSubmit-fence-00063]] |
| If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be |
| unsignaled |
| * [[VUID-vkQueueSubmit-fence-00064]] |
| If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be |
| associated with any other queue command that has not yet completed |
| execution on that queue |
| * [[VUID-vkQueueSubmit-pCommandBuffers-00065]] |
| Any calls to flink:vkCmdSetEvent, flink:vkCmdResetEvent or |
| flink:vkCmdWaitEvents that have been recorded into any of the command |
| buffer elements of the pname:pCommandBuffers member of any element of |
| pname:pSubmits, must: not reference any slink:VkEvent that is referenced |
| by any of those commands in a command buffer that has been submitted to |
| another queue and is still in the _pending state_ |
| * [[VUID-vkQueueSubmit-pWaitDstStageMask-00066]] |
| Any stage flag included in any element of the pname:pWaitDstStageMask |
| member of any element of pname:pSubmits must: be a pipeline stage |
| supported by one of the capabilities of pname:queue, as specified in the |
| <<synchronization-pipeline-stages-supported, table of supported pipeline |
| stages>> |
| * [[VUID-vkQueueSubmit-pSignalSemaphores-00067]] |
| Each binary semaphore element of the pname:pSignalSemaphores member of |
| any element of pname:pSubmits must: be unsignaled when the semaphore |
| signal operation it defines is executed on the device |
| * [[VUID-vkQueueSubmit-pWaitSemaphores-00068]] |
| When a semaphore wait operation referring to a binary semaphore defined |
| by any element of the pname:pWaitSemaphores member of any element of |
| pname:pSubmits executes on pname:queue, there must: be no other queues |
| waiting on the same semaphore |
| ifndef::VK_KHR_timeline_semaphore[] |
| * [[VUID-vkQueueSubmit-pWaitSemaphores-00069]] |
| All elements of the pname:pWaitSemaphores member of all elements of |
| pname:pSubmits must: be semaphores that are signaled, or have |
| <<synchronization-semaphores-signaling, semaphore signal operations>> |
| previously submitted for execution |
| endif::VK_KHR_timeline_semaphore[] |
| ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] |
| * [[VUID-vkQueueSubmit-pWaitSemaphores-03238]] |
| All elements of the pname:pWaitSemaphores member of all elements of |
| pname:pSubmits created with a elink:VkSemaphoreType of |
| ename:VK_SEMAPHORE_TYPE_BINARY must: reference a semaphore signal |
| operation that has been submitted for execution and any semaphore signal |
| operations on which it depends (if any) must: have also been submitted |
| for execution |
| endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] |
| * [[VUID-vkQueueSubmit-pCommandBuffers-00070]] |
| Each element of the pname:pCommandBuffers member of each element of |
| pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or |
| executable state>> |
| * [[VUID-vkQueueSubmit-pCommandBuffers-00071]] |
| If any element of the pname:pCommandBuffers member of any element of |
| pname:pSubmits was not recorded with the |
| ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in |
| the <<commandbuffers-lifecycle, pending state>> |
| * [[VUID-vkQueueSubmit-pCommandBuffers-00072]] |
| Any <<commandbuffers-secondary, secondary command buffers recorded>> |
| into any element of the pname:pCommandBuffers member of any element of |
| pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or |
| executable state>> |
| * [[VUID-vkQueueSubmit-pCommandBuffers-00073]] |
| If any <<commandbuffers-secondary, secondary command buffers recorded>> |
| into any element of the pname:pCommandBuffers member of any element of |
| pname:pSubmits was not recorded with the |
| ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in |
| the <<commandbuffers-lifecycle, pending state>> |
| * [[VUID-vkQueueSubmit-pCommandBuffers-00074]] |
| Each element of the pname:pCommandBuffers member of each element of |
| pname:pSubmits must: have been allocated from a sname:VkCommandPool that |
| was created for the same queue family pname:queue belongs to |
| * [[VUID-vkQueueSubmit-pSubmits-02207]] |
| If any element of pname:pSubmits->pCommandBuffers includes a |
| <<synchronization-queue-transfers-acquire, Queue Family Transfer Acquire |
| Operation>>, there must: exist a previously submitted |
| <<synchronization-queue-transfers-release, Queue Family Transfer Release |
| Operation>> on a queue in the queue family identified by the acquire |
| operation, with parameters matching the acquire operation as defined in |
| the definition of such <<synchronization-queue-transfers-acquire, |
| acquire operations>>, and which happens-before the acquire operation |
| ifdef::VK_KHR_performance_query[] |
| * [[VUID-vkQueueSubmit-pCommandBuffers-03220]] |
| If a command recorded into any element of pname:pCommandBuffers was a |
| flink:vkCmdBeginQuery whose pname:queryPool was created with a |
| pname:queryType of ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the |
| <<profiling-lock, profiling lock>> must: have been held continuously on |
| the sname:VkDevice that pname:queue was retrieved from, throughout |
| recording of those command buffers |
| endif::VK_KHR_performance_query[] |
| * [[VUID-vkQueueSubmit-pSubmits-02808]] |
| Any resource created with ename:VK_SHARING_MODE_EXCLUSIVE that is read |
| by an operation specified by pname:pSubmits must: not be owned by any |
| queue family other than the one which pname:queue belongs to, at the |
| time it is executed |
| * [[VUID-vkQueueSubmit-pSubmits-04626]] |
| Any resource created with ename:VK_SHARING_MODE_CONCURRENT that is |
| accessed by an operation specified by pname:pSubmits must: have included |
| the queue family of pname:queue at resource creation time |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkQueueSubmit-queue-06448]] |
| If pname:queue was not created with |
| ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, there must: be no element of |
| pname:pSubmits that includes an slink:VkProtectedSubmitInfo structure in |
| its pname:pNext chain with pname:protectedSubmit equal to ename:VK_TRUE |
| endif::VK_VERSION_1_1[] |
| **** |
| |
| include::{generated}/validity/protos/vkQueueSubmit.txt[] |
| -- |
| |
| [open,refpage='VkSubmitInfo',desc='Structure specifying a queue submit operation',type='structs'] |
| -- |
| The sname:VkSubmitInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkSubmitInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:waitSemaphoreCount is the number of semaphores upon which to wait |
| before executing the command buffers for the batch. |
| * pname:pWaitSemaphores is a pointer to an array of slink:VkSemaphore |
| handles upon which to wait before the command buffers for this batch |
| begin execution. |
| If semaphores to wait on are provided, they define a |
| <<synchronization-semaphores-waiting, semaphore wait operation>>. |
| * pname:pWaitDstStageMask is a pointer to an array of pipeline stages at |
| which each corresponding semaphore wait will occur. |
| * pname:commandBufferCount is the number of command buffers to execute in |
| the batch. |
| * pname:pCommandBuffers is a pointer to an array of slink:VkCommandBuffer |
| handles to execute in the batch. |
| * pname:signalSemaphoreCount is the number of semaphores to be signaled |
| once the commands specified in pname:pCommandBuffers have completed |
| execution. |
| * pname:pSignalSemaphores is a pointer to an array of slink:VkSemaphore |
| handles which will be signaled when the command buffers for this batch |
| have completed execution. |
| If semaphores to be signaled are provided, they define a |
| <<synchronization-semaphores-signaling, semaphore signal operation>>. |
| |
| The order that command buffers appear in pname:pCommandBuffers is used to |
| determine <<synchronization-submission-order, submission order>>, and thus |
| all the <<synchronization-implicit, implicit ordering guarantees>> that |
| respect it. |
| Other than these implicit ordering guarantees and any <<synchronization, |
| explicit synchronization primitives>>, these command buffers may: overlap or |
| otherwise execute out of order. |
| |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkSubmitInfo-pCommandBuffers-00075]] |
| Each element of pname:pCommandBuffers must: not have been allocated with |
| ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY |
| * [[VUID-VkSubmitInfo-pWaitDstStageMask-00076]] |
| If the <<features-geometryShader,geometry shaders>> feature is not |
| enabled, each element of pname:pWaitDstStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT |
| * [[VUID-VkSubmitInfo-pWaitDstStageMask-00077]] |
| If the <<features-tessellationShader,tessellation shaders>> feature is |
| not enabled, each element of pname:pWaitDstStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or |
| ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT |
| * [[VUID-VkSubmitInfo-pWaitDstStageMask-00078]] |
| Each element of pname:pWaitDstStageMask must: not include |
| ename:VK_PIPELINE_STAGE_HOST_BIT |
| ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] |
| * [[VUID-VkSubmitInfo-pWaitSemaphores-03239]] |
| If any element of pname:pWaitSemaphores or pname:pSignalSemaphores was |
| created with a elink:VkSemaphoreType of |
| ename:VK_SEMAPHORE_TYPE_TIMELINE, then the pname:pNext chain must: |
| include a slink:VkTimelineSemaphoreSubmitInfo structure |
| * [[VUID-VkSubmitInfo-pNext-03240]] |
| If the pname:pNext chain of this structure includes a |
| slink:VkTimelineSemaphoreSubmitInfo structure and any element of |
| pname:pWaitSemaphores was created with a elink:VkSemaphoreType of |
| ename:VK_SEMAPHORE_TYPE_TIMELINE, then its pname:waitSemaphoreValueCount |
| member must: equal pname:waitSemaphoreCount |
| * [[VUID-VkSubmitInfo-pNext-03241]] |
| If the pname:pNext chain of this structure includes a |
| slink:VkTimelineSemaphoreSubmitInfo structure and any element of |
| pname:pSignalSemaphores was created with a elink:VkSemaphoreType of |
| ename:VK_SEMAPHORE_TYPE_TIMELINE, then its |
| pname:signalSemaphoreValueCount member must: equal |
| pname:signalSemaphoreCount |
| * [[VUID-VkSubmitInfo-pSignalSemaphores-03242]] |
| For each element of pname:pSignalSemaphores created with a |
| elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the |
| corresponding element of |
| slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: |
| have a value greater than the current value of the semaphore when the |
| <<synchronization-semaphores-signaling,semaphore signal operation>> is |
| executed |
| * [[VUID-VkSubmitInfo-pWaitSemaphores-03243]] |
| For each element of pname:pWaitSemaphores created with a |
| elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the |
| corresponding element of |
| slink:VkTimelineSemaphoreSubmitInfo::pname:pWaitSemaphoreValues must: |
| have a value which does not differ from the current value of the |
| semaphore or the value of any outstanding semaphore wait or signal |
| operation on that semaphore by more than |
| <<limits-maxTimelineSemaphoreValueDifference, |
| pname:maxTimelineSemaphoreValueDifference>> |
| * [[VUID-VkSubmitInfo-pSignalSemaphores-03244]] |
| For each element of pname:pSignalSemaphores created with a |
| elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the |
| corresponding element of |
| slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: |
| have a value which does not differ from the current value of the |
| semaphore or the value of any outstanding semaphore wait or signal |
| operation on that semaphore by more than |
| <<limits-maxTimelineSemaphoreValueDifference, |
| pname:maxTimelineSemaphoreValueDifference>> |
| endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] |
| ifdef::VK_NV_mesh_shader[] |
| * [[VUID-VkSubmitInfo-pWaitDstStageMask-02089]] |
| If the <<features-meshShader,mesh shaders>> feature is not enabled, each |
| element of pname:pWaitDstStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV |
| * [[VUID-VkSubmitInfo-pWaitDstStageMask-02090]] |
| If the <<features-taskShader,task shaders>> feature is not enabled, each |
| element of pname:pWaitDstStageMask must: not contain |
| ename:VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV |
| endif::VK_NV_mesh_shader[] |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-VkSubmitInfo-pNext-04120]] |
| If the pname:pNext chain of this structure does not include a |
| sname:VkProtectedSubmitInfo structure with pname:protectedSubmit set to |
| ename:VK_TRUE, then each element of the pname:pCommandBuffers array |
| must: be an unprotected command buffer |
| * [[VUID-VkSubmitInfo-pNext-04148]] |
| If the pname:pNext chain of this structure includes a |
| sname:VkProtectedSubmitInfo structure with pname:protectedSubmit set to |
| ename:VK_TRUE, then each element of the pname:pCommandBuffers array |
| must: be a protected command buffer |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_KHR_dynamic_rendering[] |
| * [[VUID-VkSubmitInfo-pCommandBuffers-06193]] |
| If pname:pCommandBuffers contains any <<renderpass-suspension,resumed |
| render pass instances>>, they must: be suspended by a render pass |
| instance earlier in submission order within pname:pCommandBuffers |
| * [[VUID-VkSubmitInfo-pCommandBuffers-06014]] |
| If pname:pCommandBuffers contains any <<renderpass-suspension,suspended |
| render pass instances>>, they must: be resumed by a render pass instance |
| later in submission order within pname:pCommandBuffers |
| * [[VUID-VkSubmitInfo-pCommandBuffers-06015]] |
| If pname:pCommandBuffers contains any <<renderpass-suspension,suspended |
| render pass instances>>, there must: be no action or synchronization |
| commands between that render pass instance and the render pass instance |
| that resumes it |
| * [[VUID-VkSubmitInfo-pCommandBuffers-06016]] |
| If pname:pCommandBuffers contains any <<renderpass-suspension,suspended |
| render pass instances>>, there must: be no render pass instances between |
| that render pass instance and the render pass instance that resumes it |
| ifdef::VK_EXT_sample_locations[] |
| * [[VUID-VkSubmitInfo-variableSampleLocations-06017]] |
| If the <<limits-variableSampleLocations, pname:variableSampleLocations>> |
| limit is not supported, and any element of pname:pCommandBuffers |
| contains any <<renderpass-suspension,suspended render pass instances>>, |
| where a graphics pipeline has been bound, any pipelines bound in the |
| render pass instance that resumes it, or any subsequent render pass |
| instances that resume from that one and so on, must: use the same sample |
| locations |
| endif::VK_EXT_sample_locations[] |
| endif::VK_KHR_dynamic_rendering[] |
| **** |
| |
| include::{generated}/validity/structs/VkSubmitInfo.txt[] |
| -- |
| |
| ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] |
| [open,refpage='VkTimelineSemaphoreSubmitInfo',desc='Structure specifying signal and wait values for timeline semaphores',type='structs',alias='VkTimelineSemaphoreSubmitInfoKHR'] |
| -- |
| To specify the values to use when waiting for and signaling semaphores |
| created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE, |
| add a slink:VkTimelineSemaphoreSubmitInfo structure to the pname:pNext chain |
| of the slink:VkSubmitInfo structure when using flink:vkQueueSubmit or the |
| slink:VkBindSparseInfo structure when using flink:vkQueueBindSparse. |
| The sname:VkTimelineSemaphoreSubmitInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkTimelineSemaphoreSubmitInfo.txt[] |
| |
| ifdef::VK_KHR_timeline_semaphore[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkTimelineSemaphoreSubmitInfoKHR.txt[] |
| endif::VK_KHR_timeline_semaphore[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:waitSemaphoreValueCount is the number of semaphore wait values |
| specified in pname:pWaitSemaphoreValues. |
| * pname:pWaitSemaphoreValues is a pointer to an array of |
| pname:waitSemaphoreValueCount values for the corresponding semaphores in |
| slink:VkSubmitInfo::pname:pWaitSemaphores to wait for. |
| * pname:signalSemaphoreValueCount is the number of semaphore signal values |
| specified in pname:pSignalSemaphoreValues. |
| * pname:pSignalSemaphoreValues is a pointer to an array |
| pname:signalSemaphoreValueCount values for the corresponding semaphores |
| in slink:VkSubmitInfo::pname:pSignalSemaphores to set when signaled. |
| |
| If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or |
| slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in |
| pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively was |
| not created with a elink:VkSemaphoreType of |
| ename:VK_SEMAPHORE_TYPE_TIMELINE, the implementation must: ignore the value |
| in the pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry. |
| |
| include::{generated}/validity/structs/VkTimelineSemaphoreSubmitInfo.txt[] |
| -- |
| endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] |
| |
| ifdef::VK_KHR_external_semaphore_win32[] |
| [open,refpage='VkD3D12FenceSubmitInfoKHR',desc='Structure specifying values for Direct3D 12 fence-backed semaphores',type='structs'] |
| -- |
| To specify the values to use when waiting for and signaling semaphores whose |
| <<synchronization-semaphores-importing,current payload>> refers to a |
| Direct3D 12 fence, add a slink:VkD3D12FenceSubmitInfoKHR structure to the |
| pname:pNext chain of the slink:VkSubmitInfo structure. |
| The sname:VkD3D12FenceSubmitInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkD3D12FenceSubmitInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:waitSemaphoreValuesCount is the number of semaphore wait values |
| specified in pname:pWaitSemaphoreValues. |
| * pname:pWaitSemaphoreValues is a pointer to an array of |
| pname:waitSemaphoreValuesCount values for the corresponding semaphores |
| in slink:VkSubmitInfo::pname:pWaitSemaphores to wait for. |
| * pname:signalSemaphoreValuesCount is the number of semaphore signal |
| values specified in pname:pSignalSemaphoreValues. |
| * pname:pSignalSemaphoreValues is a pointer to an array of |
| pname:signalSemaphoreValuesCount values for the corresponding semaphores |
| in slink:VkSubmitInfo::pname:pSignalSemaphores to set when signaled. |
| |
| If the semaphore in slink:VkSubmitInfo::pname:pWaitSemaphores or |
| slink:VkSubmitInfo::pname:pSignalSemaphores corresponding to an entry in |
| pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues respectively does |
| not currently have a <<synchronization-semaphores-payloads, payload>> |
| referring to a Direct3D 12 fence, the implementation must: ignore the value |
| in the pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry. |
| |
| ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] |
| [NOTE] |
| .Note |
| ==== |
| As the introduction of the external semaphore handle type |
| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT predates that of |
| timeline semaphores, support for importing semaphore payloads from external |
| handles of that type into semaphores created (implicitly or explicitly) with |
| a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY is preserved for |
| backwards compatibility. |
| However, applications should: prefer importing such handle types into |
| semaphores created with a elink:VkSemaphoreType of |
| ename:VK_SEMAPHORE_TYPE_TIMELINE, and use the |
| slink:VkTimelineSemaphoreSubmitInfo structure instead of the |
| sname:VkD3D12FenceSubmitInfoKHR structure to specify the values to use when |
| waiting for and signaling such semaphores. |
| ==== |
| endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkD3D12FenceSubmitInfoKHR-waitSemaphoreValuesCount-00079]] |
| pname:waitSemaphoreValuesCount must: be the same value as |
| sname:VkSubmitInfo::pname:waitSemaphoreCount, where sname:VkSubmitInfo |
| is in the pname:pNext chain of this sname:VkD3D12FenceSubmitInfoKHR |
| structure |
| * [[VUID-VkD3D12FenceSubmitInfoKHR-signalSemaphoreValuesCount-00080]] |
| pname:signalSemaphoreValuesCount must: be the same value as |
| sname:VkSubmitInfo::pname:signalSemaphoreCount, where sname:VkSubmitInfo |
| is in the pname:pNext chain of this sname:VkD3D12FenceSubmitInfoKHR |
| structure |
| **** |
| |
| include::{generated}/validity/structs/VkD3D12FenceSubmitInfoKHR.txt[] |
| -- |
| endif::VK_KHR_external_semaphore_win32[] |
| |
| ifdef::VK_KHR_win32_keyed_mutex[] |
| [open,refpage='VkWin32KeyedMutexAcquireReleaseInfoKHR',desc='Use the Windows keyed mutex mechanism to synchronize work',type='structs'] |
| -- |
| When submitting work that operates on memory imported from a Direct3D 11 |
| resource to a queue, the keyed mutex mechanism may: be used in addition to |
| Vulkan semaphores to synchronize the work. |
| Keyed mutexes are a property of a properly created shareable Direct3D 11 |
| resource. |
| They can: only be used if the imported resource was created with the |
| etext:D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX flag. |
| |
| To acquire keyed mutexes before submitted work and/or release them after, |
| add a slink:VkWin32KeyedMutexAcquireReleaseInfoKHR structure to the |
| pname:pNext chain of the slink:VkSubmitInfo structure. |
| |
| The sname:VkWin32KeyedMutexAcquireReleaseInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:acquireCount is the number of entries in the pname:pAcquireSyncs, |
| pname:pAcquireKeys, and pname:pAcquireTimeouts arrays. |
| * pname:pAcquireSyncs is a pointer to an array of slink:VkDeviceMemory |
| objects which were imported from Direct3D 11 resources. |
| * pname:pAcquireKeys is a pointer to an array of mutex key values to wait |
| for prior to beginning the submitted work. |
| Entries refer to the keyed mutex associated with the corresponding |
| entries in pname:pAcquireSyncs. |
| * pname:pAcquireTimeouts is a pointer to an array of timeout values, in |
| millisecond units, for each acquire specified in pname:pAcquireKeys. |
| * pname:releaseCount is the number of entries in the pname:pReleaseSyncs |
| and pname:pReleaseKeys arrays. |
| * pname:pReleaseSyncs is a pointer to an array of slink:VkDeviceMemory |
| objects which were imported from Direct3D 11 resources. |
| * pname:pReleaseKeys is a pointer to an array of mutex key values to set |
| when the submitted work has completed. |
| Entries refer to the keyed mutex associated with the corresponding |
| entries in pname:pReleaseSyncs. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkWin32KeyedMutexAcquireReleaseInfoKHR-pAcquireSyncs-00081]] |
| Each member of pname:pAcquireSyncs and pname:pReleaseSyncs must: be a |
| device memory object imported by setting |
| slink:VkImportMemoryWin32HandleInfoKHR::pname:handleType to |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT or |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT |
| **** |
| |
| include::{generated}/validity/structs/VkWin32KeyedMutexAcquireReleaseInfoKHR.txt[] |
| -- |
| endif::VK_KHR_win32_keyed_mutex[] |
| |
| ifdef::VK_NV_win32_keyed_mutex[] |
| include::VK_NV_win32_keyed_mutex/keyed_mutex_submit.txt[] |
| endif::VK_NV_win32_keyed_mutex[] |
| |
| ifdef::VK_VERSION_1_1[] |
| [open,refpage='VkProtectedSubmitInfo',desc='Structure indicating whether the submission is protected',type='structs'] |
| -- |
| If the pname:pNext chain of slink:VkSubmitInfo includes a |
| sname:VkProtectedSubmitInfo structure, then the structure indicates whether |
| the batch is protected. |
| The sname:VkProtectedSubmitInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkProtectedSubmitInfo.txt[] |
| |
| * pname:protectedSubmit specifies whether the batch is protected. |
| If pname:protectedSubmit is ename:VK_TRUE, the batch is protected. |
| If pname:protectedSubmit is ename:VK_FALSE, the batch is unprotected. |
| If the sname:VkSubmitInfo::pname:pNext chain does not include this |
| structure, the batch is unprotected. |
| |
| include::{generated}/validity/structs/VkProtectedSubmitInfo.txt[] |
| -- |
| endif::VK_VERSION_1_1[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| [open,refpage='VkDeviceGroupSubmitInfo',desc='Structure indicating which physical devices execute semaphore operations and command buffers',type='structs'] |
| -- |
| |
| If the pname:pNext chain of slink:VkSubmitInfo includes a |
| sname:VkDeviceGroupSubmitInfo structure, then that structure includes device |
| indices and masks specifying which physical devices execute semaphore |
| operations and command buffers. |
| |
| The sname:VkDeviceGroupSubmitInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkDeviceGroupSubmitInfo.txt[] |
| |
| ifdef::VK_KHR_device_group[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkDeviceGroupSubmitInfoKHR.txt[] |
| endif::VK_KHR_device_group[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:waitSemaphoreCount is the number of elements in the |
| pname:pWaitSemaphoreDeviceIndices array. |
| * pname:pWaitSemaphoreDeviceIndices is a pointer to an array of |
| pname:waitSemaphoreCount device indices indicating which physical device |
| executes the semaphore wait operation in the corresponding element of |
| slink:VkSubmitInfo::pname:pWaitSemaphores. |
| * pname:commandBufferCount is the number of elements in the |
| pname:pCommandBufferDeviceMasks array. |
| * pname:pCommandBufferDeviceMasks is a pointer to an array of |
| pname:commandBufferCount device masks indicating which physical devices |
| execute the command buffer in the corresponding element of |
| slink:VkSubmitInfo::pname:pCommandBuffers. |
| A physical device executes the command buffer if the corresponding bit |
| is set in the mask. |
| * pname:signalSemaphoreCount is the number of elements in the |
| pname:pSignalSemaphoreDeviceIndices array. |
| * pname:pSignalSemaphoreDeviceIndices is a pointer to an array of |
| pname:signalSemaphoreCount device indices indicating which physical |
| device executes the semaphore signal operation in the corresponding |
| element of slink:VkSubmitInfo::pname:pSignalSemaphores. |
| |
| If this structure is not present, semaphore operations and command buffers |
| execute on device index zero. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDeviceGroupSubmitInfo-waitSemaphoreCount-00082]] |
| pname:waitSemaphoreCount must: equal |
| slink:VkSubmitInfo::pname:waitSemaphoreCount |
| * [[VUID-VkDeviceGroupSubmitInfo-commandBufferCount-00083]] |
| pname:commandBufferCount must: equal |
| slink:VkSubmitInfo::pname:commandBufferCount |
| * [[VUID-VkDeviceGroupSubmitInfo-signalSemaphoreCount-00084]] |
| pname:signalSemaphoreCount must: equal |
| slink:VkSubmitInfo::pname:signalSemaphoreCount |
| * [[VUID-VkDeviceGroupSubmitInfo-pWaitSemaphoreDeviceIndices-00085]] |
| All elements of pname:pWaitSemaphoreDeviceIndices and |
| pname:pSignalSemaphoreDeviceIndices must: be valid device indices |
| * [[VUID-VkDeviceGroupSubmitInfo-pCommandBufferDeviceMasks-00086]] |
| All elements of pname:pCommandBufferDeviceMasks must: be valid device |
| masks |
| **** |
| |
| include::{generated}/validity/structs/VkDeviceGroupSubmitInfo.txt[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| |
| ifdef::VK_KHR_performance_query[] |
| If the pname:pNext chain of slink:VkSubmitInfo includes a |
| slink:VkPerformanceQuerySubmitInfoKHR structure, then the structure |
| indicates which counter pass is active for the batch in that submit. |
| |
| [open,refpage='VkPerformanceQuerySubmitInfoKHR',desc='Structure indicating which counter pass index is active for performance queries',type='structs'] |
| -- |
| The sname:VkPerformanceQuerySubmitInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkPerformanceQuerySubmitInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:counterPassIndex specifies which counter pass index is active. |
| |
| If the sname:VkSubmitInfo::pname:pNext chain does not include this |
| structure, the batch defaults to use counter pass index 0. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkPerformanceQuerySubmitInfoKHR-counterPassIndex-03221]] |
| pname:counterPassIndex must: be less than the number of counter passes |
| required by any queries within the batch. |
| The required number of counter passes for a performance query is |
| obtained by calling |
| flink:vkGetPhysicalDeviceQueueFamilyPerformanceQueryPassesKHR |
| **** |
| |
| include::{generated}/validity/structs/VkPerformanceQuerySubmitInfoKHR.txt[] |
| -- |
| endif::VK_KHR_performance_query[] |
| |
| |
| [[commandbuffers-submission-progress]] |
| == Queue Forward Progress |
| |
| When using binary semaphores, the application must: ensure that command |
| buffer submissions will be able to complete without any subsequent |
| operations by the application on any queue. |
| After any call to fname:vkQueueSubmit (or other queue operation), for every |
| queued wait on a semaphore |
| ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] |
| created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY |
| endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] |
| there must: be a prior signal of that semaphore that will not be consumed by |
| a different wait on the semaphore. |
| |
| ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] |
| When using timeline semaphores, wait-before-signal behavior is well-defined |
| and applications can: submit work via fname:vkQueueSubmit which defines a |
| <<synchronization-semaphores-waiting, timeline semaphore wait operation>> |
| before submitting a corresponding <<synchronization-semaphores-signaling, |
| semaphore signal operation>>. |
| For each <<synchronization-semaphores-waiting, timeline semaphore wait |
| operation>> defined by a call to fname:vkQueueSubmit, the application must: |
| ensure that a corresponding <<synchronization-semaphores-signaling, |
| semaphore signal operation>> is executed before forward progress can be |
| made. |
| endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] |
| |
| Command buffers in the submission can: include flink:vkCmdWaitEvents |
| commands that wait on events that will not be signaled by earlier commands |
| in the queue. |
| Such events must: be signaled by the application using flink:vkSetEvent, and |
| the fname:vkCmdWaitEvents commands that wait upon them must: not be inside a |
| render pass instance. |
| The event must: be set before the flink:vkCmdWaitEvents command is executed. |
| |
| [NOTE] |
| .Note |
| ==== |
| Implementations may have some tolerance for waiting on events to be set, but |
| this is defined outside of the scope of Vulkan. |
| ==== |
| |
| |
| [[commandbuffers-secondary]] |
| == Secondary Command Buffer Execution |
| |
| [open,refpage='vkCmdExecuteCommands',desc='Execute a secondary command buffer from a primary command buffer',type='protos'] |
| -- |
| A secondary command buffer must: not be directly submitted to a queue. |
| Instead, secondary command buffers are recorded to execute as part of a |
| primary command buffer with the command: |
| |
| include::{generated}/api/protos/vkCmdExecuteCommands.txt[] |
| |
| * pname:commandBuffer is a handle to a primary command buffer that the |
| secondary command buffers are executed in. |
| * pname:commandBufferCount is the length of the pname:pCommandBuffers |
| array. |
| * pname:pCommandBuffers is a pointer to an array of |
| pname:commandBufferCount secondary command buffer handles, which are |
| recorded to execute in the primary command buffer in the order they are |
| listed in the array. |
| |
| If any element of pname:pCommandBuffers was not recorded with the |
| ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, and it was recorded |
| into any other primary command buffer which is currently in the |
| <<commandbuffers-lifecycle, executable or recording state>>, that primary |
| command buffer becomes <<commandbuffers-lifecycle, invalid>>. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00088]] |
| Each element of pname:pCommandBuffers must: have been allocated with a |
| pname:level of ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00089]] |
| Each element of pname:pCommandBuffers must: be in the |
| <<commandbuffers-lifecycle, pending or executable state>> |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00091]] |
| If any element of pname:pCommandBuffers was not recorded with the |
| ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not be |
| in the <<commandbuffers-lifecycle, pending state>> |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00092]] |
| If any element of pname:pCommandBuffers was not recorded with the |
| ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not |
| have already been recorded to pname:commandBuffer |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00093]] |
| If any element of pname:pCommandBuffers was not recorded with the |
| ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag, it must: not |
| appear more than once in pname:pCommandBuffers |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00094]] |
| Each element of pname:pCommandBuffers must: have been allocated from a |
| sname:VkCommandPool that was created for the same queue family as the |
| sname:VkCommandPool from which pname:commandBuffer was allocated |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00096]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance, each element of pname:pCommandBuffers must: have been recorded |
| with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00099]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance, and any element of pname:pCommandBuffers was recorded with |
| slink:VkCommandBufferInheritanceInfo::pname:framebuffer not equal to |
| dlink:VK_NULL_HANDLE, that sname:VkFramebuffer must: match the |
| sname:VkFramebuffer used in the current render pass instance |
| * [[VUID-vkCmdExecuteCommands-contents-06018]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderPass, its pname:contents |
| parameter must: have been set to |
| ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06019]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderPass, each element of |
| pname:pCommandBuffers must: have been recorded with |
| slink:VkCommandBufferInheritanceInfo::pname:subpass set to the index of |
| the subpass which the given command buffer will be executed in |
| * [[VUID-vkCmdExecuteCommands-pBeginInfo-06020]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderPass, the render passes |
| specified in the pname:pBeginInfo->pInheritanceInfo->renderPass members |
| of the flink:vkBeginCommandBuffer commands used to begin recording each |
| element of pname:pCommandBuffers must: be |
| <<renderpass-compatibility,compatible>> with the current render pass |
| ifndef::VK_KHR_dynamic_rendering[] |
| * [[VUID-vkCmdExecuteCommands-contents-00095]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance, that render pass instance must: have been begun with the |
| pname:contents parameter of fname:vkCmdBeginRenderPass set to |
| ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00097]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance, each element of pname:pCommandBuffers must: have been recorded |
| with sname:VkCommandBufferInheritanceInfo::pname:subpass set to the |
| index of the subpass which the given command buffer will be executed in |
| * [[VUID-vkCmdExecuteCommands-pInheritanceInfo-00098]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance, the render passes specified in the |
| pname:pBeginInfo->pInheritanceInfo->renderPass members of the |
| flink:vkBeginCommandBuffer commands used to begin recording each element |
| of pname:pCommandBuffers must: be |
| <<renderpass-compatibility,compatible>> with the current render pass |
| endif::VK_KHR_dynamic_rendering[] |
| ifdef::VK_QCOM_render_pass_transform[] |
| * [[VUID-vkCmdExecuteCommands-pNext-02865]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance that included slink:VkRenderPassTransformBeginInfoQCOM in the |
| pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of |
| pname:pCommandBuffers must: have been recorded with |
| slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM in the |
| pname:pNext chain of slink:VkCommandBufferBeginInfo |
| * [[VUID-vkCmdExecuteCommands-pNext-02866]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance that included slink:VkRenderPassTransformBeginInfoQCOM in the |
| pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of |
| pname:pCommandBuffers must: have been recorded with |
| slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM::pname:transform |
| identical to slink:VkRenderPassTransformBeginInfoQCOM::pname:transform |
| * [[VUID-vkCmdExecuteCommands-pNext-02867]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance that included slink:VkRenderPassTransformBeginInfoQCOM in the |
| pname:pNext chain of slink:VkRenderPassBeginInfo, then each element of |
| pname:pCommandBuffers must: have been recorded with |
| slink:VkCommandBufferInheritanceRenderPassTransformInfoQCOM::pname:renderArea |
| identical to slink:VkRenderPassBeginInfo::pname:renderArea |
| endif::VK_QCOM_render_pass_transform[] |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00100]] |
| If fname:vkCmdExecuteCommands is not being called within a render pass |
| instance, each element of pname:pCommandBuffers must: not have been |
| recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT |
| * [[VUID-vkCmdExecuteCommands-commandBuffer-00101]] |
| If the <<features-inheritedQueries,inherited queries>> feature is not |
| enabled, pname:commandBuffer must: not have any queries |
| <<queries-operation-active,active>> |
| * [[VUID-vkCmdExecuteCommands-commandBuffer-00102]] |
| If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query |
| <<queries-operation-active,active>>, then each element of |
| pname:pCommandBuffers must: have been recorded with |
| sname:VkCommandBufferInheritanceInfo::pname:occlusionQueryEnable set to |
| ename:VK_TRUE |
| * [[VUID-vkCmdExecuteCommands-commandBuffer-00103]] |
| If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query |
| <<queries-operation-active,active>>, then each element of |
| pname:pCommandBuffers must: have been recorded with |
| sname:VkCommandBufferInheritanceInfo::pname:queryFlags having all bits |
| set that are set for the query |
| * [[VUID-vkCmdExecuteCommands-commandBuffer-00104]] |
| If pname:commandBuffer has a ename:VK_QUERY_TYPE_PIPELINE_STATISTICS |
| query <<queries-operation-active,active>>, then each element of |
| pname:pCommandBuffers must: have been recorded with |
| sname:VkCommandBufferInheritanceInfo::pname:pipelineStatistics having |
| all bits set that are set in the sname:VkQueryPool the query uses |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-00105]] |
| Each element of pname:pCommandBuffers must: not begin any query types |
| that are <<queries-operation-active,active>> in pname:commandBuffer |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkCmdExecuteCommands-commandBuffer-01820]] |
| If pname:commandBuffer is a protected command buffer and |
| <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, |
| each element of pname:pCommandBuffers must: be a protected command |
| buffer |
| * [[VUID-vkCmdExecuteCommands-commandBuffer-01821]] |
| If pname:commandBuffer is an unprotected command buffer and |
| <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, |
| each element of pname:pCommandBuffers must: be an unprotected command |
| buffer |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_EXT_transform_feedback[] |
| * [[VUID-vkCmdExecuteCommands-None-02286]] |
| This command must: not be recorded when transform feedback is active |
| endif::VK_EXT_transform_feedback[] |
| ifdef::VK_KHR_dynamic_rendering[] |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06021]] |
| If pname:pCommandBuffers contains any <<renderpass-suspension,suspended |
| render pass instances>>, there must: be no action or synchronization |
| commands between that render pass instance and any render pass instance |
| that resumes it |
| * [[VUID-vkCmdExecuteCommands-pCommandBuffers-06022]] |
| If pname:pCommandBuffers contains any <<renderpass-suspension,suspended |
| render pass instances>>, there must: be no render pass instances between |
| that render pass instance and any render pass instance that resumes it |
| ifdef::VK_EXT_sample_locations[] |
| * [[VUID-vkCmdExecuteCommands-variableSampleLocations-06023]] |
| If the <<limits-variableSampleLocations, pname:variableSampleLocations>> |
| limit is not supported, and any element of pname:pCommandBuffers |
| contains any <<renderpass-suspension,suspended render pass instances>>, |
| where a graphics pipeline has been bound, any pipelines bound in the |
| render pass instance that resumes it, or any subsequent render pass |
| instances that resume from that one and so on, must: use the same sample |
| locations |
| endif::VK_EXT_sample_locations[] |
| * [[VUID-vkCmdExecuteCommands-flags-06024]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR, its |
| slink:VkRenderingInfoKHR::pname:flags parameter must: have included |
| ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR |
| * [[VUID-vkCmdExecuteCommands-pBeginInfo-06025]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR, the render passes |
| specified in the pname:pBeginInfo->pInheritanceInfo->renderPass members |
| of the flink:vkBeginCommandBuffer commands used to begin recording each |
| element of pname:pCommandBuffers must: be dlink:VK_NULL_HANDLE |
| * [[VUID-vkCmdExecuteCommands-flags-06026]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR, the pname:flags member |
| of the slink:VkCommandBufferInheritanceRenderingInfoKHR structure |
| included in the pname:pNext chain of |
| slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin |
| recording each element of pname:pCommandBuffers must: be equal to the |
| slink:VkRenderingInfoKHR::pname:flags parameter to |
| flink:vkCmdBeginRenderingKHR, excluding |
| ename:VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT_KHR |
| * [[VUID-vkCmdExecuteCommands-colorAttachmentCount-06027]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR, the |
| pname:colorAttachmentCount member of the |
| slink:VkCommandBufferInheritanceRenderingInfoKHR structure included in |
| the pname:pNext chain of |
| slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin |
| recording each element of pname:pCommandBuffers must: be equal to the |
| slink:VkRenderingInfoKHR::pname:colorAttachmentCount parameter to |
| flink:vkCmdBeginRenderingKHR |
| * [[VUID-vkCmdExecuteCommands-imageView-06028]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR, if the pname:imageView |
| member of an element of the |
| slink:VkRenderingInfoKHR::pname:pColorAttachments parameter to |
| flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the |
| corresponding element of the pname:pColorAttachmentFormats member of the |
| slink:VkCommandBufferInheritanceRenderingInfoKHR structure included in |
| the pname:pNext chain of |
| slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin |
| recording each element of pname:pCommandBuffers must: be equal to the |
| format used to create that image view |
| * [[VUID-vkCmdExecuteCommands-pDepthAttachment-06029]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR, if the |
| slink:VkRenderingInfoKHR::pname:pDepthAttachment->imageView parameter to |
| flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value of |
| the pname:depthAttachmentFormat member of the |
| slink:VkCommandBufferInheritanceRenderingInfoKHR structure included in |
| the pname:pNext chain of |
| slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin |
| recording each element of pname:pCommandBuffers must: be equal to the |
| format used to create that image view |
| * [[VUID-vkCmdExecuteCommands-pStencilAttachment-06030]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR, if the |
| slink:VkRenderingInfoKHR::pname:pStencilAttachment->imageView parameter |
| to flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value |
| of the pname:stencilAttachmentFormat member of the |
| slink:VkCommandBufferInheritanceRenderingInfoKHR structure included in |
| the pname:pNext chain of |
| slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin |
| recording each element of pname:pCommandBuffers must: be equal to the |
| format used to create that image view |
| ifdef::VK_KHR_multiview,VK_VERSION_1_1[] |
| * [[VUID-vkCmdExecuteCommands-viewMask-06031]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR, the pname:viewMask |
| member of the slink:VkCommandBufferInheritanceRenderingInfoKHR structure |
| included in the pname:pNext chain of |
| slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin |
| recording each element of pname:pCommandBuffers must: be equal to the |
| slink:VkRenderingInfoKHR::pname:viewMask parameter to |
| flink:vkCmdBeginRenderingKHR |
| endif::VK_KHR_multiview,VK_VERSION_1_1[] |
| ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] |
| * [[VUID-vkCmdExecuteCommands-pNext-06032]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext |
| chain of slink:VkCommandBufferInheritanceInfo includes a |
| slink:VkAttachmentSampleCountInfoAMD or |
| slink:VkAttachmentSampleCountInfoNV structure, if the pname:imageView |
| member of an element of the |
| slink:VkRenderingInfoKHR::pname:pColorAttachments parameter to |
| flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the |
| corresponding element of the pname:pColorAttachmentSamples member of the |
| slink:VkAttachmentSampleCountInfoAMD or |
| slink:VkAttachmentSampleCountInfoNV structure included in the |
| pname:pNext chain of |
| slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin |
| recording each element of pname:pCommandBuffers must: be equal to the |
| sample count used to create that image view |
| * [[VUID-vkCmdExecuteCommands-pNext-06033]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext |
| chain of slink:VkCommandBufferInheritanceInfo includes a |
| slink:VkAttachmentSampleCountInfoAMD or |
| slink:VkAttachmentSampleCountInfoNV structure, if the |
| slink:VkRenderingInfoKHR::pname:pDepthAttachment->imageView parameter to |
| flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value of |
| the pname:depthStencilAttachmentSamples member of the |
| slink:VkAttachmentSampleCountInfoAMD or |
| slink:VkAttachmentSampleCountInfoNV structure included in the |
| pname:pNext chain of |
| slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin |
| recording each element of pname:pCommandBuffers must: be equal to the |
| sample count used to create that image view |
| * [[VUID-vkCmdExecuteCommands-pNext-06034]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext |
| chain of slink:VkCommandBufferInheritanceInfo includes a |
| slink:VkAttachmentSampleCountInfoAMD or |
| slink:VkAttachmentSampleCountInfoNV structure, if the |
| slink:VkRenderingInfoKHR::pname:pStencilAttachment->imageView parameter |
| to flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value |
| of the pname:depthStencilAttachmentSamples member of the |
| slink:VkAttachmentSampleCountInfoAMD or |
| slink:VkAttachmentSampleCountInfoNV structure included in the |
| pname:pNext chain of |
| slink:VkCommandBufferBeginInfo::pname:pInheritanceInfo used to begin |
| recording each element of pname:pCommandBuffers must: be equal to the |
| sample count used to create that image view |
| * [[VUID-vkCmdExecuteCommands-pNext-06035]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext |
| chain of slink:VkCommandBufferInheritanceInfo does not include a |
| slink:VkAttachmentSampleCountInfoAMD or |
| slink:VkAttachmentSampleCountInfoNV structure, if the pname:imageView |
| member of an element of the |
| slink:VkRenderingInfoKHR::pname:pColorAttachments parameter to |
| flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value of |
| slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:rasterizationSamples |
| must: be equal to the sample count used to create that image view |
| * [[VUID-vkCmdExecuteCommands-pNext-06036]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext |
| chain of slink:VkCommandBufferInheritanceInfo does not include a |
| slink:VkAttachmentSampleCountInfoAMD or |
| slink:VkAttachmentSampleCountInfoNV structure, if the |
| slink:VkRenderingInfoKHR::pname:pDepthAttachment->imageView parameter to |
| flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value of |
| slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:rasterizationSamples |
| must: be equal to the sample count used to create that image view |
| * [[VUID-vkCmdExecuteCommands-pNext-06037]] |
| If fname:vkCmdExecuteCommands is being called within a render pass |
| instance begun with flink:vkCmdBeginRenderingKHR and the pname:pNext |
| chain of slink:VkCommandBufferInheritanceInfo does not include a |
| slink:VkAttachmentSampleCountInfoAMD or |
| slink:VkAttachmentSampleCountInfoNV structure, if the |
| slink:VkRenderingInfoKHR::pname:pStencilAttachment->imageView parameter |
| to flink:vkCmdBeginRenderingKHR is not dlink:VK_NULL_HANDLE, the value |
| of |
| slink:VkCommandBufferInheritanceRenderingInfoKHR::pname:rasterizationSamples |
| must: be equal to the sample count used to create that image view |
| endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] |
| endif::VK_KHR_dynamic_rendering[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdExecuteCommands.txt[] |
| -- |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| [[commandbuffers-devicemask]] |
| == Command Buffer Device Mask |
| |
| Each command buffer has a piece of state storing the current device mask of |
| the command buffer. |
| This mask controls which physical devices within the logical device all |
| subsequent commands will execute on, including state-setting commands, |
| action commands, and synchronization commands. |
| |
| ifndef::VK_NV_scissor_exclusive[] |
| Scissor |
| endif::VK_NV_scissor_exclusive[] |
| ifdef::VK_NV_scissor_exclusive[] |
| Scissor, exclusive scissor, |
| endif::VK_NV_scissor_exclusive[] |
| and viewport state |
| ifdef::VK_EXT_extended_dynamic_state[] |
| (excluding the count of each) |
| endif::VK_EXT_extended_dynamic_state[] |
| can: be set to different values on each physical device (only when set as |
| dynamic state), and each physical device will render using its local copy of |
| the state. |
| Other state is shared between physical devices, such that all physical |
| devices use the most recently set values for the state. |
| However, when recording an action command that uses a piece of state, the |
| most recent command that set that state must: have included all physical |
| devices that execute the action command in its current device mask. |
| |
| The command buffer's device mask is orthogonal to the |
| pname:pCommandBufferDeviceMasks member of slink:VkDeviceGroupSubmitInfo. |
| Commands only execute on a physical device if the device index is set in |
| both device masks. |
| |
| [open,refpage='VkDeviceGroupCommandBufferBeginInfo',desc='Set the initial device mask for a command buffer',type='structs'] |
| -- |
| If the pname:pNext chain of slink:VkCommandBufferBeginInfo includes a |
| sname:VkDeviceGroupCommandBufferBeginInfo structure, then that structure |
| includes an initial device mask for the command buffer. |
| |
| The sname:VkDeviceGroupCommandBufferBeginInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkDeviceGroupCommandBufferBeginInfo.txt[] |
| |
| ifdef::VK_KHR_device_group[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkDeviceGroupCommandBufferBeginInfoKHR.txt[] |
| endif::VK_KHR_device_group[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:deviceMask is the initial value of the command buffer's device |
| mask. |
| |
| The initial device mask also acts as an upper bound on the set of devices |
| that can: ever be in the device mask in the command buffer. |
| |
| If this structure is not present, the initial value of a command buffer's |
| device mask is set to include all physical devices in the logical device |
| when the command buffer begins recording. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00106]] |
| pname:deviceMask must: be a valid device mask value |
| * [[VUID-VkDeviceGroupCommandBufferBeginInfo-deviceMask-00107]] |
| pname:deviceMask must: not be zero |
| **** |
| |
| include::{generated}/validity/structs/VkDeviceGroupCommandBufferBeginInfo.txt[] |
| -- |
| |
| [open,refpage='vkCmdSetDeviceMask',desc='Modify device mask of a command buffer',type='protos'] |
| -- |
| To update the current device mask of a command buffer, call: |
| |
| ifdef::VK_VERSION_1_1[] |
| include::{generated}/api/protos/vkCmdSetDeviceMask.txt[] |
| endif::VK_VERSION_1_1[] |
| |
| ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] |
| |
| ifdef::VK_KHR_device_group[] |
| include::{generated}/api/protos/vkCmdSetDeviceMaskKHR.txt[] |
| endif::VK_KHR_device_group[] |
| |
| * pname:commandBuffer is command buffer whose current device mask is |
| modified. |
| * pname:deviceMask is the new value of the current device mask. |
| |
| pname:deviceMask is used to filter out subsequent commands from executing on |
| all physical devices whose bit indices are not set in the mask, except |
| commands beginning a render pass instance, commands transitioning to the |
| next subpass in the render pass instance, and commands ending a render pass |
| instance, which always execute on the set of physical devices whose bit |
| indices are included in the pname:deviceMask member of the |
| slink:VkDeviceGroupRenderPassBeginInfo structure passed to the command |
| beginning the corresponding render pass instance. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdSetDeviceMask-deviceMask-00108]] |
| pname:deviceMask must: be a valid device mask value |
| * [[VUID-vkCmdSetDeviceMask-deviceMask-00109]] |
| pname:deviceMask must: not be zero |
| * [[VUID-vkCmdSetDeviceMask-deviceMask-00110]] |
| pname:deviceMask must: not include any set bits that were not in the |
| slink:VkDeviceGroupCommandBufferBeginInfo::pname:deviceMask value when |
| the command buffer began recording |
| * [[VUID-vkCmdSetDeviceMask-deviceMask-00111]] |
| If fname:vkCmdSetDeviceMask is called inside a render pass instance, |
| pname:deviceMask must: not include any set bits that were not in the |
| slink:VkDeviceGroupRenderPassBeginInfo::pname:deviceMask value when the |
| render pass instance began recording |
| **** |
| |
| include::{generated}/validity/protos/vkCmdSetDeviceMask.txt[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
