VKQUEUESUBMIT(3)

NAME
vkQueueSubmit - Submits a sequence of semaphores or command buffers to a queue.

C SPECIFICATION

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

PARAMETERS

queue
    The queue to which to submit work.

submitCount
    The number of submissions to make.

pSubmits
    The address of an array of submitCount VkSubmitInfo structures to submit to queue.

fence
    An optional fence object that will be signaled when all command buffers referenced in pSubmits have completed execution.

DESCRIPTION

vkQueueSubmit makes one or more submissions to a the queue specified in queue. Each submision is represented by an element of an array of VkSubmitInfo structures, the address of which is specified in pSubmits. The length of the array is given by submitCount. If submitCount is zero then, pSubmits may be NULL, in which case, no work is submitted to the queue. The definition of VkSubmitInfo is:

    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;

If the waitSemaphoreCount member of VkSubmitInfo is not zero, then pWaitSemaphores is a pointer to an array of waitSemaphoreCount VkSemaphore handles which will be waited on before any further work is performed by the queue.

After all semaphores specified in pWaitSemaphores (if any) have become signaled, the command buffers specified in pCommandBuffers are executed and those semaphores are again reset to the unsignaled state. pCommandBuffers is a pointer to an array of commandBufferCount VkCommandBuffer handles to the command buffers to execute. If commandBufferCount is zero then pCommandBuffers may be NULL and no work is performed on the queue as a result.

After all work specified in pCommandBuffers (if any) has completed, the semaphores specified in pSignalSemaphores are signaled. pSignalSemaphores is a pointer to an array of signalSemaphoreCount VkSemaphore handles. If signalSemaphoreCount is zero then pSignalSemaphores may be NULL.

fence is an optional handle to a fence which, if not VK_NULL_HANDLE, is signaled when execution of the all elements of pCommandBuffers in pSubmits is completed. If submitCount is zero, but fence is not NULL, the fence will still be submitted to the queue and will become signaled when all work previusly submitted to the queue has completed.

An implementation may, at its option, choose to merge the submissions specified in pSubmits, but at least one submission is made to the queue and the work represented by pSubmits is guaranteed to complete in finite time.

VALID USAGE

    • 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

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

    • 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

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 Levels | Render Pass Scope | Supported Queue Types
- | - | Any

RETURN CODES

On success, this command returns

        • VK_SUCCESS

On failure, this command returns

        • VK_ERROR_OUT_OF_HOST_MEMORY

        • VK_ERROR_OUT_OF_DEVICE_MEMORY

        • VK_ERROR_DEVICE_LOST

SEE ALSO

vkBeginCommandBuffer, vkEndCommandBuffer, vkCreateSemaphore

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.