vkQueueSubmit - Submits a sequence of semaphores or command buffers to a
queue
Description
queueSubmit is a
queue submission command,
with each batch defined by an element of pSubmits. Batches begin
execution in the order they appear in pSubmits, but may complete out
of order.
The order that batches appear in pSubmits 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 batches may overlap or otherwise execute out of order.
Fence operations submitted with queueSubmit have additional ordering
constraints compared to other submission commands, with dependencies
involving previous and subsequent queue operations. Information about
these additional constraints can be found in the
fence
sections of
the synchronization chapter.
The first
synchronization scope
of each
semaphore signal operation
defined by this command includes every command in the same batch that
the signal operation is defined in, and all commands that occur earlier
in
submission order.
The second
synchronization scope
of each
semaphore wait operation
defined by this command includes every command in the same batch that
the wait operation is defined in, and all commands that occur later in
submission order.
The scope is limited by the pWaitDstStageMask for each batch, as
described in SubmitInfo.
If any command buffer submitted to this queue is in the
executable state,
it is moved to the
pending state.
Once execution of all submissions of a command buffer complete, it moves
from the
pending state,
back to the
executable state.
If a command buffer was recorded with the
COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
flag, it instead moves to the
invalid state.
If queueSubmit fails, it may return
ERROR_OUT_OF_HOST_MEMORY or
ERROR_OUT_OF_DEVICE_MEMORY. If it does, the
implementation must ensure that the state and contents of any
resources or synchronization primitives referenced by the submitted
command buffers and any semaphores referenced by pSubmits is
unaffected by the call or its failure. If queueSubmit fails in such a
way that the implementation is unable to make that guarantee, the
implementation must return
ERROR_DEVICE_LOST. See
Lost Device.
Valid Usage
If fence is not
NULL_HANDLE, fence must not be
associated with any other queue command that has not yet completed
execution on that queue
Any calls to
cmdSetEvent,
cmdResetEvent or
cmdWaitEvents that have been
recorded into any of the command buffer elements of the
pCommandBuffers member of any element of pSubmits, must not
reference any Event that is referenced by
any of those commands in a command buffer that has been submitted to
another queue and is still in the pending state
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
Each binary semaphore
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 wait
operation referring to a binary semaphore defined by any element of
the pWaitSemaphores member of any element of pSubmits executes
on queue, there must be no other queues waiting on the same
semaphore
All elements of the
pWaitSemaphores member of all elements of pSubmits created with
a SemaphoreType of
SEMAPHORE_TYPE_BINARY must
reference a semaphore signal operation that has been submitted for
execution and any
semaphore signal operations
on which it depends must have also been submitted for execution
Each element of the
pCommandBuffers member of each element of pSubmits must be in
the
pending or executable state
If any element of the
pCommandBuffers member of any element of pSubmits was not
recorded with the
COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT,
it must not be in the
pending state
Any
secondary command buffers recorded
into any element of the pCommandBuffers member of any element of
pSubmits must be in the
pending or executable state
If any
secondary command buffers recorded
into any element of the pCommandBuffers member of any element of
pSubmits was not recorded with the
COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT,
it must not be in the
pending state
Each element of the
pCommandBuffers member of each element of pSubmits must have
been allocated from a CommandPool that was
created for the same queue family queue belongs to
If any element of
pSubmits->pCommandBuffers includes a
Queue Family Ownership Transfer Acquire Operation,
there must exist a previously submitted
Queue Family Ownership Transfer Release Operation
on a queue in the queue family identified by the acquire operation,
with parameters matching the acquire operation as defined in the
definition of such
acquire operations,
and which happens-before the acquire operation
If any element of
pSubmits->pCommandBuffers includes a
Queue Family Ownership Transfer Acquire Operation,
the affected resource must not be modified in any way between the
last matching release operation and the acquire operation
If a command recorded
into any element of pCommandBuffers was a
cmdBeginQuery whose
queryPool was created with a queryType of
QUERY_TYPE_PERFORMANCE_QUERY_KHR,
the
profiling lock
must have been held continuously on the
Device that queue was retrieved from,
throughout recording of those command buffers
Any resource created with
SHARING_MODE_EXCLUSIVE that is
read by an operation specified by pSubmits must not be owned by
any queue family other than the one which queue belongs to, at the
time it is executed
Any resource created with
SHARING_MODE_CONCURRENT that is
accessed by an operation specified by pSubmits must have
included the queue family of queue at resource creation time
If queue was not created with
DEVICE_QUEUE_CREATE_PROTECTED_BIT,
there must be no element of pSubmits that includes a
ProtectedSubmitInfo
structure in its pNext chain with protectedSubmit equal to
TRUE
Valid Usage (Implicit)
If submitCount is not 0,
pSubmits must be a valid pointer to an array of submitCount
valid SubmitInfo structures
If fence is not
NULL_HANDLE, fence must be a valid
Fence handle
Both of fence, and queue that
are valid handles of non-ignored parameters must have been
created, allocated, or retrieved from the same
Device
Host Synchronization
Command Properties
'
Return Codes
- Success
- Failure
See Also
VK_VERSION_1_0,
Fence, Queue,
SubmitInfo