VkSubmitInfo(3)

# VkSubmitInfo(3) Manual Page

## Name

VkSubmitInfo - Structure specifying a queue submit operation

Loading… please wait.

## C Specification

The `VkSubmitInfo` structure is defined as:

    // Provided by VK_VERSION_1_0
    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 a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this 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.

The second synchronization scope of each semaphore wait operation defined by this structure is limited to operations in stages indicated by the corresponding element of `pWaitDstStageMask`.

Note | A common scenario for using `pWaitDstStageMask` with values other than VK_PIPELINE_STAGE_ALL_COMMANDS_BIT is when synchronizing a window system presentation operation against subsequent command buffers which render the next frame. In this case, a presentation image must not be overwritten until the presentation operation completes, but other pipeline stages can execute without waiting. A mask of VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT prevents subsequent color attachment writes from executing until the semaphore signals. Some implementations may be able to execute transfer operations and/or pre-rasterization work before the semaphore is signaled. If an image layout transition needs to be performed on a presentable image before it is used in a framebuffer, that can be performed as the first operation submitted to the queue after acquiring the image, and should not prevent other work from overlapping with the presentation operation. For example, a `VkImageMemoryBarrier` could use: `srcStageMask` = VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT `srcAccessMask` = 0 `dstStageMask` = VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT `dstAccessMask` = VK_ACCESS_COLOR_ATTACHMENT_READ_BIT | VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. `oldLayout` = VK_IMAGE_LAYOUT_PRESENT_SRC_KHR `newLayout` = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL Alternatively, `oldLayout` can be VK_IMAGE_LAYOUT_UNDEFINED, if the image’s contents need not be preserved. This barrier accomplishes a dependency chain between previous presentation operations and subsequent color attachment output operations, with the layout transition performed in between, and does not introduce a dependency between previous work and any pre-rasterization shader stages. More precisely, the semaphore signals after the presentation operation completes, the semaphore wait stalls the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage, and there is a dependency from that same stage to itself with the layout transition performed in between.

Valid Usage

- VUID-VkSubmitInfo-pWaitDstStageMask-04090
  If the `geometryShader` feature is not enabled, `pWaitDstStageMask` must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

- VUID-VkSubmitInfo-pWaitDstStageMask-04091
  If the `tessellationShader` feature is not enabled, `pWaitDstStageMask` must not contain VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

- VUID-VkSubmitInfo-pWaitDstStageMask-04092
  If the `conditionalRendering` feature is not enabled, `pWaitDstStageMask` must not contain VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

- VUID-VkSubmitInfo-pWaitDstStageMask-04093
  If the `fragmentDensityMap` feature is not enabled, `pWaitDstStageMask` must not contain VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

- VUID-VkSubmitInfo-pWaitDstStageMask-04094
  If the `transformFeedback` feature is not enabled, `pWaitDstStageMask` must not contain VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

- VUID-VkSubmitInfo-pWaitDstStageMask-04095
  If the `meshShader` feature is not enabled, `pWaitDstStageMask` must not contain VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

- VUID-VkSubmitInfo-pWaitDstStageMask-04096
  If the `taskShader` feature is not enabled, `pWaitDstStageMask` must not contain VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

- VUID-VkSubmitInfo-pWaitDstStageMask-07318
  If neither of the `shadingRateImage` or the `attachmentFragmentShadingRate` features are enabled, `pWaitDstStageMask` must not contain VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

- VUID-VkSubmitInfo-pWaitDstStageMask-03937
  If the `synchronization2` feature is not enabled, `pWaitDstStageMask` must not be `0`

- VUID-VkSubmitInfo-pWaitDstStageMask-07949
  If neither the VK_NV_ray_tracing extension or the `rayTracingPipeline` feature are enabled, `pWaitDstStageMask` must not contain VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

- VUID-VkSubmitInfo-pWaitDstStageMask-10754
  If the `accelerationStructure` feature is not enabled, `pWaitDstStageMask` must not contain VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

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

- VUID-VkSubmitInfo-pWaitDstStageMask-00078
  Each element of `pWaitDstStageMask` must not include VK_PIPELINE_STAGE_HOST_BIT

- VUID-VkSubmitInfo-pWaitSemaphores-03239
  If any element of `pWaitSemaphores` or `pSignalSemaphores` was created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, then the `pNext` chain must include a VkTimelineSemaphoreSubmitInfo structure

- VUID-VkSubmitInfo-pNext-03240
  If the `pNext` chain of this structure includes a VkTimelineSemaphoreSubmitInfo structure and any element of `pWaitSemaphores` was created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, then its `waitSemaphoreValueCount` member must equal `waitSemaphoreCount`

- VUID-VkSubmitInfo-pNext-03241
  If the `pNext` chain of this structure includes a VkTimelineSemaphoreSubmitInfo structure and any element of `pSignalSemaphores` was created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE, then its `signalSemaphoreValueCount` member must equal `signalSemaphoreCount`

- VUID-VkSubmitInfo-pSignalSemaphores-03242
  For each element of `pSignalSemaphores` created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE the corresponding element of VkTimelineSemaphoreSubmitInfo::`pSignalSemaphoreValues` must have a value greater than the current value of the semaphore when the semaphore signal operation is executed

- VUID-VkSubmitInfo-pWaitSemaphores-03243
  For each element of `pWaitSemaphores` created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE the corresponding element of VkTimelineSemaphoreSubmitInfo::`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`

- VUID-VkSubmitInfo-pSignalSemaphores-03244
  For each element of `pSignalSemaphores` created with a VkSemaphoreType of VK_SEMAPHORE_TYPE_TIMELINE the corresponding element of VkTimelineSemaphoreSubmitInfo::`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`

- VUID-VkSubmitInfo-pNext-04120
  If the `pNext` chain of this structure does not include a `VkProtectedSubmitInfo` structure with `protectedSubmit` set to VK_TRUE, then each element of the `pCommandBuffers` array must be an unprotected command buffer

- VUID-VkSubmitInfo-pNext-04148
  If the `pNext` chain of this structure includes a `VkProtectedSubmitInfo` structure with `protectedSubmit` set to VK_TRUE, then each element of the `pCommandBuffers` array must be a protected command buffer

- VUID-VkSubmitInfo-pCommandBuffers-06193
  If `pCommandBuffers` contains any resumed render pass instances, they must be suspended by a render pass instance earlier in submission order within `pCommandBuffers`

- VUID-VkSubmitInfo-pCommandBuffers-06014
  If `pCommandBuffers` contains any suspended render pass instances, they must be resumed by a render pass instance later in submission order within `pCommandBuffers`

- VUID-VkSubmitInfo-pCommandBuffers-06015
  If `pCommandBuffers` contains any suspended render pass instances, there must be no action or synchronization commands executed in a primary or secondary command buffer between that render pass instance and the render pass instance that resumes it

- VUID-VkSubmitInfo-pCommandBuffers-06016
  If `pCommandBuffers` contains any suspended render pass instances, there must be no render pass instances between that render pass instance and the render pass instance that resumes it

- VUID-VkSubmitInfo-variableSampleLocations-06017
  If the `variableSampleLocations` limit is not supported, and any element of `pCommandBuffers` contains any 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

- VUID-VkSubmitInfo-pNext-09683
  If the `pNext` chain of this structure includes a VkFrameBoundaryTensorsARM structure then it must also include a VkFrameBoundaryEXT structure

- VUID-VkSubmitInfo-pCommandBufferInfos-09942
  If at least one VkCommandBufferSubmitInfo structure in `pCommandBufferInfos` references a `commandBuffer` allocated from a pool that was created with a VkDataGraphProcessingEngineCreateInfoARM structure in the `pNext` chain of VkCommandPoolCreateInfo that included a foreign data graph processing engine in its `pProcessingEngines` member, then `pWaitSemaphoreInfos` and `pSignalSemaphoreInfos` must only reference `semaphore` objects that were created from external handle types reported as supported in a VkQueueFamilyDataGraphProcessingEnginePropertiesARM::`foreignSemaphoreHandleTypes` structure via vkGetPhysicalDeviceQueueFamilyDataGraphProcessingEnginePropertiesARM with a `queueFamilyIndex` matching the one the command pool was created for, for all the foreign data graph processing engines that were part of the VkDataGraphProcessingEngineCreateInfoARM used to create the command pool

Valid Usage (Implicit)

- VUID-VkSubmitInfo-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_SUBMIT_INFO

- VUID-VkSubmitInfo-pNext-pNext
  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 VkAmigoProfilingSubmitInfoSEC, VkD3D12FenceSubmitInfoKHR, VkDeviceGroupSubmitInfo, VkFrameBoundaryEXT, VkFrameBoundaryTensorsARM, VkLatencySubmissionPresentIdNV, VkPerformanceQuerySubmitInfoKHR, VkProtectedSubmitInfo, VkTimelineSemaphoreSubmitInfo, VkWin32KeyedMutexAcquireReleaseInfoKHR, or VkWin32KeyedMutexAcquireReleaseInfoNV

- VUID-VkSubmitInfo-sType-unique
  The `sType` value of each structure in the `pNext` chain must be unique

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

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

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

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

- VUID-VkSubmitInfo-commonparent
  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

VK_VERSION_1_0, 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 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0