vkQueueSubmit2(3)

C Specification

To submit command buffers to a queue, call:

// Provided by VK_VERSION_1_3
VkResult vkQueueSubmit2(
    VkQueue                                     queue,
    uint32_t                                    submitCount,
    const VkSubmitInfo2*                        pSubmits,
    VkFence                                     fence);

// Provided by VK_KHR_synchronization2
// Equivalent to vkQueueSubmit2
VkResult vkQueueSubmit2KHR(
    VkQueue                                     queue,
    uint32_t                                    submitCount,
    const VkSubmitInfo2*                        pSubmits,
    VkFence                                     fence);

Parameters

queue is the queue that the command buffers will be submitted to.
submitCount is the number of elements in the pSubmits array.
pSubmits is a pointer to an array of VkSubmitInfo2 structures, each specifying a command buffer submission batch. Command buffers and semaphores specified in this array may be accessed at any point until the queue operations they define complete execution on the device.
fence is an optional handle to a fence to be signaled once all submitted command buffers have completed execution. If fence is not VK_NULL_HANDLE, it defines a fence signal operation. If it is not VK_NULL_HANDLE, fence may be accessed at any point until this command completes on the device.

Description

vkQueueSubmit2 is a queue submission command, with each batch defined by an element of pSubmits.

The first synchronization scope of each semaphore signal operation defined by this command includes every command in the same batch that the signal operation is defined in, and all commands that occur earlier in submission order. The scope is limited by the stageMask member of the VkSemaphoreSubmitInfo used to define each such operation.

The second synchronization scope of each semaphore wait operation defined by this command includes every command in the same batch that the wait operation is defined in, and all commands that occur later in submission order. The scope is limited by the stageMask member of the VkSemaphoreSubmitInfo used to define each such operation.

If any command buffer submitted to this queue is in the executable state, it is moved to the pending state. Once execution of all submissions of a command buffer complete, it moves from the pending state, back to the executable state. If a command buffer was recorded with the VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag, it instead moves back to the invalid state.

If vkQueueSubmit2 fails, it may return VK_ERROR_OUT_OF_HOST_MEMORY or 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 pSubmits is unaffected by the call or its failure. If vkQueueSubmit2 fails in such a way that the implementation is unable to make that guarantee, the implementation must return VK_ERROR_DEVICE_LOST. See Lost Device.

Valid Usage

VUID-vkQueueSubmit2-fence-04894
If fence is not VK_NULL_HANDLE, fence must be unsignaled
VUID-vkQueueSubmit2-fence-04895
If fence is not VK_NULL_HANDLE, fence must not be associated with any other queue command that has not yet completed execution on that queue
VUID-vkQueueSubmit2-synchronization2-03866
The synchronization2 feature must be enabled
VUID-vkQueueSubmit2-commandBuffer-03867
If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits referenced a 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-vkQueueSubmit2-semaphore-03868
The semaphore member of any binary semaphore element of the pSignalSemaphoreInfos member of any element of pSubmits must be unsignaled when the semaphore signal operation it defines is executed on the device
VUID-vkQueueSubmit2-stageMask-03869
The stageMask member of any element of the pSignalSemaphoreInfos member of any element of pSubmits must only include pipeline stages that are supported by the queue family which queue belongs to
VUID-vkQueueSubmit2-stageMask-03870
The stageMask member of any element of the pWaitSemaphoreInfos member of any element of pSubmits must only include pipeline stages that are supported by the queue family which queue belongs to
VUID-vkQueueSubmit2-semaphore-03871
When a semaphore wait operation for a binary semaphore is executed, as defined by the semaphore member of any element of the pWaitSemaphoreInfos member of any element of pSubmits, there must be no other queues waiting on the same semaphore
VUID-vkQueueSubmit2-semaphore-03873
The semaphore member of any element of the pWaitSemaphoreInfos member of any element of pSubmits that was created with a VkSemaphoreType of 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 must have also been submitted for execution
VUID-vkQueueSubmit2-commandBuffer-03874
The commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits must be in the pending or executable state
VUID-vkQueueSubmit2-commandBuffer-03875
If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must not be in the pending state
VUID-vkQueueSubmit2-commandBuffer-03876
Any secondary command buffers recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits must be in the pending or executable state
VUID-vkQueueSubmit2-commandBuffer-03877
If any secondary command buffers recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits was not recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must not be in the pending state
VUID-vkQueueSubmit2-commandBuffer-03878
The commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits must have been allocated from a VkCommandPool that was created for the same queue family queue belongs to
VUID-vkQueueSubmit2-commandBuffer-03879
If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits includes a Queue Family Ownership Transfer Acquire Operation, there must exist a previously submitted Queue Family Ownership 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 acquire operations, and which happens before the acquire operation
VUID-vkQueueSubmit2-commandBuffer-10910
If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits includes a Queue Family Ownership Transfer Acquire Operation, the affected resource must not be modified in any way between the last matching release operation and the acquire operation
VUID-vkQueueSubmit2-commandBuffer-03880
If a command recorded into the commandBuffer member of any element of the pCommandBufferInfos member of any element of pSubmits was a vkCmdBeginQuery whose queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the profiling lock must have been held continuously on the VkDevice that queue was retrieved from, throughout recording of those command buffers
VUID-vkQueueSubmit2-queue-06447
If queue was not created with VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, the flags member of any element of pSubmits must not include VK_SUBMIT_PROTECTED_BIT_KHR

Valid Usage (Implicit)

VUID-vkQueueSubmit2-queue-parameter
queue must be a valid VkQueue handle
VUID-vkQueueSubmit2-pSubmits-parameter
If submitCount is not 0, pSubmits must be a valid pointer to an array of submitCount valid VkSubmitInfo2 structures
VUID-vkQueueSubmit2-fence-parameter
If fence is not VK_NULL_HANDLE, fence must be a valid VkFence handle
VUID-vkQueueSubmit2-commonparent
Both of fence, and queue that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

Host access to queue must be externally synchronized if it was not created with VK_DEVICE_QUEUE_CREATE_INTERNALLY_SYNCHRONIZED_BIT_KHR
Host access to fence must be externally synchronized