Structures

VkSubmitInfo

Structure specifying a queue submit operation

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;

pub struct SubmitInfo {
    s_type: vk::StructureType,
    p_next: *const c_void,
    wait_semaphore_count: u32,
    p_wait_semaphores: *const vk::Semaphore,
    p_wait_dst_stage_mask: *const vk::PipelineStageFlags,
    command_buffer_count: u32,
    p_command_buffers: *const vk::CommandBuffer,
    signal_semaphore_count: u32,
    p_signal_semaphores: *const vk::Semaphore,
}

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.

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.

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, oldLayoutcan 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 pSignalSemaphoreInfosmust 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

VK_VERSION_1_0

Type