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.

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 the `shadingRateImage` or `attachmentFragmentShadingRate` 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 `rayTracingPipeline` feature are enabled, `pWaitDstStageMask` must not contain `VK_PIPELINE_STAGE_RAY_TRACING_SHADER_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

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, VkLatencySubmissionPresentIdNV, VkPerformanceQuerySubmitInfoKHR, VkProtectedSubmitInfo, VkTimelineSemaphoreSubmitInfo, VkWin32KeyedMutexAcquireReleaseInfoKHR, or VkWin32KeyedMutexAcquireReleaseInfoNV

- VUID-VkSubmitInfo-sType-unique
  The `sType` value of each struct 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-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0