VkSubmitInfo(3)

# VkSubmitInfo(3) Manual Page

## Name

VkSubmitInfo - Structure specifying a queue submit operation

## C Specification

The `VkSubmitInfo` structure is defined as:

    typedef struct VkSubmitInfo {
        VkStructureType                sType;
        const void*                    pNext;
        uint32_t                       waitSemaphoreCount;
        const VkSemaphore*             pWaitSemaphores;
        const VkPipelineStageFlags*    pWaitDstStageMask;
        uint32_t                       commandBufferCount;
        const VkCommandBuffer*         pCommandBuffers;
        uint32_t                       signalSemaphoreCount;
        const VkSemaphore*             pSignalSemaphores;
    } VkSubmitInfo;

## Members

- `sType` is the type of this structure.

- `pNext` is `NULL` or a pointer to an extension-specific structure.

- `waitSemaphoreCount` is the number of semaphores upon which to wait before executing the command buffers for the batch.

- `pWaitSemaphores` is a pointer to an array of 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 semaphore wait operation.

- `pWaitDstStageMask` is a pointer to an array of pipeline stages at which each corresponding semaphore wait will occur.

- `commandBufferCount` is the number of command buffers to execute in the batch.

- `pCommandBuffers` is a pointer to an array of VkCommandBuffer handles to execute in the batch.

- `signalSemaphoreCount` is the number of semaphores to be signaled once the commands specified in `pCommandBuffers` have completed execution.

- `pSignalSemaphores` is a pointer to an array of 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 semaphore signal operation.

## Description

The order that command buffers appear in `pCommandBuffers` is used to determine submission order, and thus all the implicit ordering guarantees that respect it. Other than these implicit ordering guarantees and any explicit synchronization primitives, these command buffers may overlap or otherwise execute out of order.

Valid Usage

- Each element of `pCommandBuffers` must not have been allocated with `VK_COMMAND_BUFFER_LEVEL_SECONDARY`

- If the geometry shaders feature is not enabled, each element of `pWaitDstStageMask` must not contain `VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT`

- If the tessellation shaders feature is not enabled, each element of `pWaitDstStageMask` must not contain `VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT` or `VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT`

- Each element of `pWaitDstStageMask` must not include `VK_PIPELINE_STAGE_HOST_BIT`.

- If any element of `pWaitSemaphores` or `pSignalSemaphores` was created with a VkSemaphoreTypeKHR of `VK_SEMAPHORE_TYPE_TIMELINE_KHR`, then the `pNext` chain must include a VkTimelineSemaphoreSubmitInfoKHR structure

- If the `pNext` chain of this structure includes a VkTimelineSemaphoreSubmitInfoKHR structure and any element of `pWaitSemaphores` was created with a VkSemaphoreTypeKHR of `VK_SEMAPHORE_TYPE_TIMELINE_KHR`, then its `waitSemaphoreValueCount` member must equal `waitSemaphoreCount`

- If the `pNext` chain of this structure includes a VkTimelineSemaphoreSubmitInfoKHR structure and any element of `pSignalSemaphores` was created with a VkSemaphoreTypeKHR of `VK_SEMAPHORE_TYPE_TIMELINE_KHR`, then its `signalSemaphoreValueCount` member must equal `signalSemaphoreCount`

- For each element of `pSignalSemaphores` created with a VkSemaphoreTypeKHR of `VK_SEMAPHORE_TYPE_TIMELINE_KHR` the corresponding element of VkTimelineSemaphoreSubmitInfoKHR::pSignalSemaphoreValues must have a value greater than the current value of the semaphore when the semaphore signal operation is executed

- For each element of `pWaitSemaphores` created with a VkSemaphoreTypeKHR of `VK_SEMAPHORE_TYPE_TIMELINE_KHR` the corresponding element of VkTimelineSemaphoreSubmitInfoKHR::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 `maxTimelineSemaphoreValueDifference`.

- For each element of `pSignalSemaphores` created with a VkSemaphoreTypeKHR of `VK_SEMAPHORE_TYPE_TIMELINE_KHR` the corresponding element of VkTimelineSemaphoreSubmitInfoKHR::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 `maxTimelineSemaphoreValueDifference`.

- If the mesh shaders feature is not enabled, each element of `pWaitDstStageMask` must not contain `VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV`

- If the task shaders feature is not enabled, each element of `pWaitDstStageMask` must not contain `VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV`

Valid Usage (Implicit)

- `sType` must be `VK_STRUCTURE_TYPE_SUBMIT_INFO`

- Each `pNext` member of any structure (including this one) in the `pNext` chain must be either `NULL` or a pointer to a valid instance of VkD3D12FenceSubmitInfoKHR, VkDeviceGroupSubmitInfo, VkPerformanceQuerySubmitInfoKHR, VkProtectedSubmitInfo, VkTimelineSemaphoreSubmitInfoKHR, VkWin32KeyedMutexAcquireReleaseInfoKHR, or VkWin32KeyedMutexAcquireReleaseInfoNV

- Each `sType` member in the `pNext` chain must be unique

- If `waitSemaphoreCount` is not `0`, `pWaitSemaphores` must be a valid pointer to an array of `waitSemaphoreCount` valid VkSemaphore handles

- If `waitSemaphoreCount` is not `0`, `pWaitDstStageMask` must be a valid pointer to an array of `waitSemaphoreCount` valid combinations of VkPipelineStageFlagBits values

- Each element of `pWaitDstStageMask` must not be `0`

- If `commandBufferCount` is not `0`, `pCommandBuffers` must be a valid pointer to an array of `commandBufferCount` valid VkCommandBuffer handles

- If `signalSemaphoreCount` is not `0`, `pSignalSemaphores` must be a valid pointer to an array of `signalSemaphoreCount` valid VkSemaphore handles

- Each of the elements of `pCommandBuffers`, the elements of `pSignalSemaphores`, and the elements of `pWaitSemaphores` that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

## See Also

VkCommandBuffer, VkPipelineStageFlags, VkSemaphore, VkStructureType, vkQueueSubmit

## 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 (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.