vkQueueSubmit2(3)

# vkQueueSubmit2(3) Manual Page

## Name

vkQueueSubmit2 - Submits command buffers to a queue

Loading… please wait.

## 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);

or the equivalent command

    // Provided by VK_KHR_synchronization2
    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.

- `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.

## Description

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

Semaphore operations submitted with vkQueueSubmit2 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 semaphore section of the synchronization chapter.

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 an 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-03872
  The `semaphore` member of any element of the `pWaitSemaphoreInfos` member of any element of `pSubmits` must be semaphores that are signaled, or have semaphore signal operations previously submitted for execution

- VUID-vkQueueSubmit2-semaphore-03873
  Any `semaphore` member of any element of the `pWaitSemaphoreInfos` member of any element of `pSubmits` that was created with a VkSemaphoreTypeKHR of `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

- 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 Transfer Acquire Operation, there must exist a previously submitted 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 acquire operations, and which happens before 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

- Host access to `fence` must be externally synchronized

Command Properties

Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type
--- | --- | --- | --- | ---

Return Codes

On success, this command returns

  - `VK_SUCCESS`

On failure, this command returns

  - `VK_ERROR_OUT_OF_HOST_MEMORY`

  - `VK_ERROR_OUT_OF_DEVICE_MEMORY`

  - `VK_ERROR_DEVICE_LOST`

## See Also

VK_KHR_synchronization2, VK_VERSION_1_3, VkFence, VkQueue, VkSubmitInfo2

## Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

## Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0