Vulkan规范：第五章 5.4～5

5.4. 命令缓冲区的提交

可调用下列的命令把命令缓冲区提交到队列：

VkResult vkQueueSubmit(    VkQueue                                     queue,    uint32_t                                    submitCount,    const VkSubmitInfo*                         pSubmits,    VkFence                                     fence);

• queue 是命令缓冲区被提交到的队列。

• submitCount 是 pSubmits 数组元素的大小。

• pSubmits 是一个指向 元素类型为VkSubmitInfo 的数组的指针，每一个元素都指定了一个命令缓冲区提交batch。

• fence 是一个可选的handle，指向一个将被激发的fence。如果fence 不是 VK_NULL_HANDLE，它定义了一个 fence signal operation。

注意

提交可能是一个代价很高的操作，应用程序应该尝试批量的工作，尽量少的调用vkQueueSubmit。

vkQueueSubmit是一个队列提交命令，每一批任务通过pSubmits中由VkSubmitInfo表示的一批任务定义。 pSubmits中各批次的任务依出现的顺序执行，但是，完成的顺序可能是乱序的。

通过vkQueueSubmit提交的栅栏和信号量操作和其他的命令提交有另外的顺序限制，依赖于队列中前后操作。 关于这些量外的限制的信息可以在“同步”一章的信号量 and 栅栏 小节中看到。

关于pWaitDstStageMask和同步之间的细节在“同步”一章中的 信号量等待操作 小节中描述。

在pSubmits中批次出现的顺序通常由提交顺序决定，故所有的隐式排序保证遵守这点。 除了这些隐式排序保证和任何显式的同步原语，这些工作批次可能重叠或者乱序执行。

正确使用

• If fence is not VK_NULL_HANDLE, fence must be unsignaled

• 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

• Any calls to vkCmdSetEvent, vkCmdResetEvent or vkCmdWaitEvents that have been recorded into any of the command buffer elements of the pCommandBuffers member of any element of pSubmits, must not reference any VkEvent that is referenced by any of those commands that is pending execution on another queue.

• Any stage flag included in any element of the pWaitDstStageMask member of any element of pSubmits must be a pipeline stage supported by one of the capabilities of queue, as specified in the table of supported pipeline stages.

• Any given element of the pSignalSemaphores member of any element of pSubmits must be unsignaled when the semaphore signal operation it defines is executed on the device

• When a semaphore unsignal operation defined by any element of the pWaitSemaphores member of any element of pSubmits executes on queue, no other queue must be waiting on the same semaphore.

• All elements of the pWaitSemaphores member of all elements of pSubmits must be semaphores that are signaled, or have semaphore signal operations previously submitted for execution.

Valid Usage (Implicit)

• queue must be a valid VkQueue handle

• If submitCount is not 0, pSubmits must be a pointer to an array of submitCount valid VkSubmitInfo structures

• If fence is not VK_NULL_HANDLE, fence must be a valid VkFence handle

• Both of fence, and queue that are valid handles must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

• Host access to queue must be externally synchronized

• Host access to pSubmits[].pWaitSemaphores[] must be externally synchronized

• Host access to pSubmits[].pSignalSemaphores[] must be externally synchronized

• Host access to fence must be externally synchronized

Command Properties

Command Buffer LevelsRender Pass ScopeSupported Queue TypesPipeline Type

-

-

Any

-

Return Codes

Success

• VK_SUCCESS

Failure

• VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_DEVICE_LOST

VkSubmitInfo 类型数据结构定义如下：

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;

• sType 是本数据结构的类型。

• pNext 为 NULL 或者指向拓展特定结构的指针。

• 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 semaphores 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 command buffers 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 semaphores 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.

命令缓冲区在pCommandBuffers中出现的顺序决定了submission order， implicit ordering guarantees 也取决于这个顺序。 除了这些隐式的顺序保证 和其他的explicit synchronization primitives，这些命令缓冲区可能重叠或者乱序执行。

正确使用

• Any given element of pCommandBuffers must either have been recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, or not currently be executing on the device

• Any given element of pCommandBuffers must be in the executable state

• If any given element of pCommandBuffers contains commands that execute secondary command buffers, those secondary command buffers must have been recorded with the VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, or not currently be executing on the device

• If any given element of pCommandBuffers was recorded with VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT, it must not have been previously submitted without re-recording that command buffer

• If any given element of pCommandBuffers contains commands that execute secondary command buffers recorded withVK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT, each such secondary command buffer must not have been previously submitted without re-recording that command buffer

• Any given element of pCommandBuffers must not contain commands that execute a secondary command buffer, if that secondary command buffer has been recorded in another primary command buffer after it was recorded into this VkCommandBuffer

• Any given element of pCommandBuffers must have been allocated from a VkCommandPool that was created for the same queue family that the calling command’s queue belongs to

• Any given element of pCommandBuffers must not have been allocated with VK_COMMAND_BUFFER_LEVEL_SECONDARY

• If the geometry shaders feature is not enabled, any given element of pWaitDstStageMask must not contain VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

• If the tessellation shaders feature is not enabled, any given element of pWaitDstStageMask must not containVK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT orVK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

• Any given element of pWaitDstStageMask must not include VK_PIPELINE_STAGE_HOST_BIT.

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_SUBMIT_INFO

• pNext must be NULL

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

• If waitSemaphoreCount is not 0, pWaitDstStageMask must be a 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 pointer to an array of commandBufferCount valid VkCommandBuffer handles

• If signalSemaphoreCount is not 0, pSignalSemaphores must be a pointer to an array of signalSemaphoreCountvalid VkSemaphore handles

• Each of the elements of pCommandBuffers, the elements of pSignalSemaphores, and the elements of pWaitSemaphores that are valid handles must have been created, allocated, or retrieved from the same VkDevice

5.5. 队列发送进度（Queue Forward Progress）

应用程序必须保证在任何队列上没有剩下的操作时命令缓冲区提交将能够完成。 在vkQueueSubmit调用之后，对等待一个信号量的每个排队等待者必须是一个比信号量更早的信号， 该信号量不会被一个不同的等待者消耗。

提交的命令缓冲区可以包含等待不会被队列中更早的命令所激发的事件的vkCmdWaitEvents命令， 这些事件必须通过应用程序使用vkSetEvent来激发，且等待这些事件的vkCmdWaitEvents命令不能在一个render pass内。 Vulkan实现可能对命令缓冲区等待的时长有限制，以避免和设备的其他clients的工作进度有干扰。 如果没有这些限制条件下事件被激发了，结果是未定义的，可能包括设备丢失。