563 lines
25 KiB
Plaintext
563 lines
25 KiB
Plaintext
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[[commandbuffers]]
|
|
= Command Buffers
|
|
|
|
// refBegin VkCommandBuffer - Opaque handle to a command buffer object
|
|
|
|
Command buffers are objects used to record commands which can: be
|
|
subsequently submitted to a device queue for execution. There are two levels
|
|
of command buffers - _primary command buffers_, which can: execute secondary
|
|
command buffers, and which are submitted to queues, and _secondary command
|
|
buffers_, which can: be executed by primary command buffers, and which are
|
|
not directly submitted to queues.
|
|
|
|
Command buffers are represented by sname:VkCommandBuffer handles:
|
|
|
|
include::../api/handles/VkCommandBuffer.txt[]
|
|
|
|
// refEnd VkCommandBuffer
|
|
|
|
Recorded commands include commands to bind pipelines and descriptor sets to
|
|
the command buffer, commands to modify dynamic state, commands to draw (for
|
|
graphics rendering), commands to dispatch (for compute), commands to execute
|
|
secondary command buffers (for primary command buffers only), commands to
|
|
copy buffers and images, and other commands.
|
|
|
|
[[commandbuffers-statereset]]
|
|
Each command buffer manages state independently of other command buffers.
|
|
There is no inheritance of state across primary and secondary command
|
|
buffers, or between secondary command buffers. When a command buffer begins
|
|
recording, all state in that command buffer is undefined. When secondary
|
|
command buffer(s) are recorded to execute on a primary command buffer, the
|
|
secondary command buffer inherits no state from the primary command buffer,
|
|
and all state of the primary command buffer is undefined after an execute
|
|
secondary command buffer command is recorded. There is one exception to this
|
|
rule - if the primary command buffer is inside a render pass instance, then
|
|
the render pass and subpass state is not disturbed by executing secondary
|
|
command buffers. Whenever the state of a command buffer is undefined, the
|
|
application must: set all relevant state on the command buffer before any
|
|
state dependent commands such as draws and dispatches are recorded,
|
|
otherwise the behavior of executing that command buffer is undefined.
|
|
|
|
Unless otherwise specified, and without explicit synchronization, the
|
|
various commands submitted to a queue via command buffers may: execute in
|
|
arbitrary order relative to each other, and/or concurrently. Also, the
|
|
memory side-effects of those commands may: not be directly visible to other
|
|
commands without memory barriers. This is true within a command buffer, and
|
|
across command buffers submitted to a given queue. See
|
|
<<synchronization-events>>, <<synchronization-pipeline-barriers>> and
|
|
<<synchronization-memory-barriers>> about synchronization primitives
|
|
suitable to guarantee execution order and side-effect visibility between
|
|
commands on a given queue.
|
|
|
|
Each command buffer is always in one of three states:
|
|
|
|
* _Initial state_: Before flink:vkBeginCommandBuffer. Either
|
|
flink:vkBeginCommandBuffer has never been called, or the command buffer
|
|
has been reset since it last recorded commands.
|
|
* _Recording state_: Between flink:vkBeginCommandBuffer and
|
|
flink:vkEndCommandBuffer. The command buffer is in a state where it can:
|
|
record commands.
|
|
* _Executable state_: After flink:vkEndCommandBuffer. The command buffer
|
|
is in a state where it has finished recording commands and can: be
|
|
executed.
|
|
|
|
_Resetting_ a command buffer is an operation that discards any previously
|
|
recorded commands and puts a command buffer in the initial state. Resetting
|
|
occurs as a result of flink:vkResetCommandBuffer or
|
|
flink:vkResetCommandPool, or as part of flink:vkBeginCommandBuffer (which
|
|
additionally puts the command buffer in the recording state).
|
|
|
|
|
|
[[commandbuffers-pools]]
|
|
== Command Pools
|
|
|
|
// refBegin VkCommandPool - Opaque handle to a command pool object
|
|
|
|
Command pools are opaque objects that command buffer memory is allocated
|
|
from, and which allow the implementation to amortize the cost of resource
|
|
creation across multiple command buffers. Command pools are
|
|
application-synchronized, meaning that a command pool mustnot: be used
|
|
concurrently in multiple threads. That includes use via recording commands
|
|
on any command buffers allocated from the pool, as well as operations that
|
|
allocate, free, and reset command buffers or the pool itself.
|
|
|
|
Command pools are represented by sname:VkCommandPool handles:
|
|
|
|
include::../api/handles/VkCommandPool.txt[]
|
|
|
|
// refEnd VkCommandPool
|
|
|
|
// refBegin vkCreateCommandPool Create a new command pool object.
|
|
|
|
To create a command pool, call:
|
|
|
|
include::../api/protos/vkCreateCommandPool.txt[]
|
|
|
|
* pname:device is the logical device that creates the command pool.
|
|
* pname:pCreateInfo contains information used to create the command pool.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pCommandPool points to a sname:VkCommandPool handle in which the
|
|
created pool is returned.
|
|
|
|
include::../validity/protos/vkCreateCommandPool.txt[]
|
|
|
|
// refBegin VkCommandPoolCreateInfo - Structure specifying parameters of a newly created command pool
|
|
|
|
The sname:VkCommandPoolCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkCommandPoolCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is a bitmask indicating usage behavior for the pool and
|
|
command buffers allocated from it. Bits which can: be set include:
|
|
+
|
|
--
|
|
// refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool
|
|
include::../api/enums/VkCommandPoolCreateFlagBits.txt[]
|
|
--
|
|
+
|
|
** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT indicates that command buffers
|
|
allocated from the pool will be short-lived, meaning that they will be
|
|
reset or freed in a relatively short timeframe. This flag may: be used by
|
|
the implementation to control memory allocation behavior within the pool.
|
|
** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT controls whether
|
|
command buffers allocated from the pool can: be individually reset. If
|
|
this flag is set, individual command buffers allocated from the pool can:
|
|
be reset either explicitly, by calling fname:vkResetCommandBuffer, or
|
|
implicitly, by calling fname:vkBeginCommandBuffer on an executable
|
|
command buffer. If this flag is not set, then fname:vkResetCommandBuffer
|
|
and fname:vkBeginCommandBuffer (on an executable command buffer) mustnot:
|
|
be called on the command buffers allocated from the pool, and they can:
|
|
only be reset in bulk by calling fname:vkResetCommandPool.
|
|
* pname:queueFamilyIndex designates a queue family as described in section
|
|
<<devsandqueues-queueprops,Queue Family Properties>>. All command
|
|
buffers allocated from this command pool must: be submitted on queues
|
|
from the same queue family.
|
|
|
|
include::../validity/structs/VkCommandPoolCreateInfo.txt[]
|
|
|
|
// refBegin vkResetCommandPool Reset a command pool.
|
|
|
|
To reset a command pool, call:
|
|
|
|
include::../api/protos/vkResetCommandPool.txt[]
|
|
|
|
* pname:device is the logical device that owns the command pool.
|
|
* pname:commandPool is the command pool to reset.
|
|
* pname:flags contains additional flags controlling the behavior of the
|
|
reset. Bits which can: be set include:
|
|
+
|
|
--
|
|
// refBegin VkCommandPoolResetFlagBits - Bitmask controlling behavior of a command pool reset
|
|
include::../api/enums/VkCommandPoolResetFlagBits.txt[]
|
|
--
|
|
+
|
|
If pname:flags includes ename:VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT,
|
|
resetting a command pool recycles all of the resources from the command pool
|
|
back to the system.
|
|
|
|
Resetting a command pool recycles all of the resources from all of the
|
|
command buffers allocated from the command pool back to the command pool.
|
|
All command buffers that have been allocated from the command pool are put
|
|
in the initial state.
|
|
|
|
include::../validity/protos/vkResetCommandPool.txt[]
|
|
|
|
// refBegin vkDestroyCommandPool Destroy a command pool object
|
|
|
|
To destroy a command pool, call:
|
|
|
|
include::../api/protos/vkDestroyCommandPool.txt[]
|
|
|
|
* pname:device is the logical device that destroys the command pool.
|
|
* pname:commandPool is the handle of the command pool to destroy.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
|
|
When a pool is destroyed, all command buffers allocated from the pool are
|
|
implicitly freed and become invalid. Command buffers allocated from a given
|
|
pool do not need to be freed before destroying that command pool.
|
|
|
|
include::../validity/protos/vkDestroyCommandPool.txt[]
|
|
|
|
|
|
[[commandbuffer-allocation]]
|
|
== Command Buffer Allocation and Management
|
|
|
|
// refBegin vkAllocateCommandBuffers Allocate command buffers from an existing command pool
|
|
|
|
To allocate command buffers, call:
|
|
|
|
include::../api/protos/vkAllocateCommandBuffers.txt[]
|
|
|
|
* pname:device is the logical device that owns the command pool.
|
|
* pname:pAllocateInfo is a pointer to an instance of the
|
|
sname:VkCommandBufferAllocateInfo structure describing parameters of the
|
|
allocation.
|
|
* pname:pCommandBuffers is a pointer to an array of sname:VkCommandBuffer
|
|
handles in which the resulting command buffer objects are returned. The
|
|
array must: be at least the length specified by the
|
|
pname:commandBufferCount member of pname:pAllocateInfo. Each allocated
|
|
command buffer begins in the initial state.
|
|
|
|
include::../validity/protos/vkAllocateCommandBuffers.txt[]
|
|
|
|
// refBegin VkCommandBufferAllocateInfo Structure specifying the allocation parameters for command buffer object.
|
|
|
|
The sname:VkCommandBufferAllocateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkCommandBufferAllocateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:commandPool is the name of the command pool that the command
|
|
buffers allocate their memory from.
|
|
* pname:level determines whether the command buffers are primary or
|
|
secondary command buffers. Possible values include:
|
|
+
|
|
--
|
|
// refBegin VkCommandBufferLevel - Structure specifying a command buffer level
|
|
include::../api/enums/VkCommandBufferLevel.txt[]
|
|
--
|
|
+
|
|
* pname:commandBufferCount is the number of command buffers to allocate
|
|
from the pool.
|
|
|
|
include::../validity/structs/VkCommandBufferAllocateInfo.txt[]
|
|
|
|
// refBegin vkResetCommandBuffer Reset a command buffer.
|
|
|
|
To reset command buffers, call:
|
|
|
|
include::../api/protos/vkResetCommandBuffer.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer to reset. The command buffer
|
|
can: be in any state, and is put in the initial state.
|
|
* pname:flags is a bitmask controlling the reset operation. Bits which
|
|
can: be set include:
|
|
+
|
|
--
|
|
// refBegin VkCommandBufferResetFlagBits - Bitmask controlling behavior of a command buffer reset
|
|
include::../api/enums/VkCommandBufferResetFlagBits.txt[]
|
|
--
|
|
+
|
|
If pname:flags includes ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT,
|
|
then most or all memory resources currently owned by the command buffer
|
|
should: be returned to the parent command pool. If this flag is not set,
|
|
then the command buffer may: hold onto memory resources and reuse them when
|
|
recording commands.
|
|
|
|
include::../validity/protos/vkResetCommandBuffer.txt[]
|
|
|
|
// refBegin vkFreeCommandBuffers Free command buffers.
|
|
|
|
To free command buffers, call:
|
|
|
|
include::../api/protos/vkFreeCommandBuffers.txt[]
|
|
|
|
* pname:device is the logical device that owns the command pool.
|
|
* pname:commandPool is the handle of the command pool that the command
|
|
buffers were allocated from.
|
|
* pname:commandBufferCount is the length of the pname:pCommandBuffers
|
|
array.
|
|
* pname:pCommandBuffers is an array of handles of command buffers to free.
|
|
|
|
include::../validity/protos/vkFreeCommandBuffers.txt[]
|
|
|
|
|
|
[[commandbuffers-recording]]
|
|
== Command Buffer Recording
|
|
|
|
// refBegin vkBeginCommandBuffer Start recording a command buffer
|
|
|
|
To begin recording a command buffer, call:
|
|
|
|
include::../api/protos/vkBeginCommandBuffer.txt[]
|
|
|
|
* pname:commandBuffer is the handle of the command buffer which is to be
|
|
put in the recording state.
|
|
* pname:pBeginInfo is an instance of the sname:VkCommandBufferBeginInfo
|
|
structure, which defines additional information about how the command
|
|
buffer begins recording.
|
|
|
|
include::../validity/protos/vkBeginCommandBuffer.txt[]
|
|
|
|
// refBegin VkCommandBufferBeginInfo - Structure specifying a command buffer begin operation
|
|
|
|
The sname:VkCommandBufferBeginInfo structure is defined as:
|
|
|
|
include::../api/structs/VkCommandBufferBeginInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is a bitmask indicating usage behavior for the command
|
|
buffer. Bits which can: be set include:
|
|
+
|
|
--
|
|
// refBegin VkCommandBufferUsageFlagBits - Bitmask specifying usage behavior for command buffer
|
|
include::../api/enums/VkCommandBufferUsageFlagBits.txt[]
|
|
--
|
|
+
|
|
** ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT indicates that each
|
|
recording of the command buffer will only be submitted once, and the
|
|
command buffer will be reset and recorded again between each submission.
|
|
** ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT indicates that
|
|
a secondary command buffer is considered to be entirely inside a render
|
|
pass. If this is a primary command buffer, then this bit is ignored.
|
|
** Setting ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT allows the
|
|
command buffer to be resubmitted to a queue or recorded into a primary
|
|
command buffer while it is pending execution.
|
|
* pname:pInheritanceInfo is a pointer to a
|
|
sname:VkCommandBufferInheritanceInfo structure, which is used if
|
|
pname:commandBuffer is a secondary command buffer. If this is a primary
|
|
command buffer, then this value is ignored.
|
|
|
|
include::../validity/structs/VkCommandBufferBeginInfo.txt[]
|
|
|
|
// refBegin VkCommandBufferInheritanceInfo - Structure specifying command buffer inheritance info
|
|
|
|
If the command buffer is a secondary command buffer, then the
|
|
sname:VkCommandBufferInheritanceInfo structure defines any state that will
|
|
be inherited from the primary command buffer:
|
|
|
|
include::../api/structs/VkCommandBufferInheritanceInfo.txt[]
|
|
|
|
* pname:renderPass is a sname:VkRenderPass object defining which
|
|
render passes the sname:VkCommandBuffer will be
|
|
<<renderpass-compatibility, compatible>> with and can: be executed
|
|
within. If the sname:VkCommandBuffer will not be executed within a
|
|
render pass instance, pname:renderPass is ignored.
|
|
* pname:subpass is the index of the subpass within pname:renderPass that
|
|
the sname:VkCommandBuffer will be executed within. If the
|
|
sname:VkCommandBuffer will not be executed within a render pass
|
|
instance, pname:subpass is ignored.
|
|
* pname:framebuffer optionally refers to the sname:VkFramebuffer
|
|
object that the sname:VkCommandBuffer will be rendering to if it is
|
|
executed within a render pass instance. It can:
|
|
be dlink:VK_NULL_HANDLE if the framebuffer is not known, or if the
|
|
sname:VkCommandBuffer will not be executed within a render pass
|
|
instance.
|
|
+
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Specifying the exact framebuffer that the secondary command buffer will be
|
|
executed with may: result in better performance at command buffer execution
|
|
time.
|
|
====
|
|
* pname:occlusionQueryEnable indicates whether the command buffer can: be
|
|
executed while an occlusion query is active in the primary command
|
|
buffer. If this is ename:VK_TRUE, then this command buffer can: be
|
|
executed whether the primary command buffer has an occlusion query
|
|
active or not. If this is ename:VK_FALSE, then the primary command
|
|
buffer mustnot: have an occlusion query active.
|
|
* pname:queryFlags indicates the query flags that can: be used by an
|
|
active occlusion query in the primary command buffer when this secondary
|
|
command buffer is executed. If this value includes the
|
|
ename:VK_QUERY_CONTROL_PRECISE_BIT bit, then the active query can:
|
|
return boolean results or actual sample counts. If this bit is not set,
|
|
then the active query mustnot: use the
|
|
ename:VK_QUERY_CONTROL_PRECISE_BIT bit. If this is a primary command
|
|
buffer, then this value is ignored.
|
|
* pname:pipelineStatistics indicates the set of pipeline statistics that
|
|
can: be counted by an active query in the primary command buffer when
|
|
this secondary command buffer is executed. If this value includes a
|
|
given bit, then this command buffer can: be executed whether the primary
|
|
command buffer has a pipeline statistics query active that includes this
|
|
bit or not. If this value excludes a given bit, then the active pipeline
|
|
statistics query mustnot: be from a query pool that counts that
|
|
statistic.
|
|
|
|
include::../validity/structs/VkCommandBufferInheritanceInfo.txt[]
|
|
|
|
A primary command buffer is considered to be pending execution from the time
|
|
it is submitted via fname:vkQueueSubmit until that submission completes.
|
|
|
|
A secondary command buffer is considered to be pending execution from the
|
|
time its execution is recorded into a primary buffer (via
|
|
fname:vkCmdExecuteCommands) until the final time that primary buffer's
|
|
submission to a queue completes. If, after the primary buffer completes, the
|
|
secondary command buffer is recorded to execute on a different primary
|
|
buffer, the first primary buffer mustnot: be resubmitted until after it is
|
|
reset with flink:vkResetCommandBuffer unless the secondary command buffer
|
|
was recorded with ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT.
|
|
|
|
If ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT is not set on a
|
|
secondary command buffer, that command buffer mustnot: be used more than
|
|
once in a given primary command buffer. Furthermore, if a secondary command
|
|
buffer without ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT set is
|
|
recorded to execute in a primary command buffer with
|
|
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT set, the primary command
|
|
buffer mustnot: be pending execution more than once at a time.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
On some implementations, not using the
|
|
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT bit enables command
|
|
buffers to be patched in-place if needed, rather than creating a copy of the
|
|
command buffer.
|
|
====
|
|
|
|
If a command buffer is in the executable state and the command buffer was
|
|
allocated from a command pool with the
|
|
ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, then
|
|
fname:vkBeginCommandBuffer implicitly resets the command buffer, behaving as
|
|
if fname:vkResetCommandBuffer had been called with
|
|
ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT not set. It then puts
|
|
the command buffer in the recording state.
|
|
|
|
Once recording starts, an application records a sequence of commands
|
|
(ftext:vkCmd*) to set state in the command buffer, draw, dispatch, and other
|
|
commands.
|
|
|
|
// refBegin vkEndCommandBuffer Finish recording a command buffer
|
|
|
|
To complete recording of a command buffer, call:
|
|
|
|
include::../api/protos/vkEndCommandBuffer.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer to complete recording. The
|
|
command buffer must: have been in the recording state, and is moved to
|
|
the executable state.
|
|
|
|
If there was an error during recording, the application will be notified by
|
|
an unsuccessful return code returned by fname:vkEndCommandBuffer. If the
|
|
application wishes to further use the command buffer, the command buffer
|
|
must: be reset.
|
|
|
|
include::../validity/protos/vkEndCommandBuffer.txt[]
|
|
|
|
When a command buffer is in the executable state, it can: be submitted to a
|
|
queue for execution.
|
|
|
|
|
|
[[commandbuffers-submission]]
|
|
== Command Buffer Submission
|
|
|
|
// refBegin vkQueueSubmit Submits a sequence of semaphores or command buffers to a queue.
|
|
|
|
To submit command buffers to a queue, call:
|
|
|
|
include::../api/protos/vkQueueSubmit.txt[]
|
|
|
|
* pname:queue is the queue that the command buffers will be submitted to.
|
|
* pname:submitCount is the number of elements in the pname:pSubmits array.
|
|
* pname:pSubmits is a pointer to an array of slink:VkSubmitInfo structures,
|
|
each specifying a command buffer submission batch.
|
|
* pname:fence is an optional handle to a fence to be signaled. If
|
|
pname:fence is not dlink:VK_NULL_HANDLE, it defines a
|
|
<<synchronization-fences-signaling, fence signal operation>>.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Submission can be a high overhead operation, and applications should:
|
|
attempt to batch work together into as few calls to fname:vkQueueSubmit as
|
|
possible.
|
|
====
|
|
|
|
fname:vkQueueSubmit is a
|
|
<<devsandqueues-submission,queue submission command>>, with each batch
|
|
defined by an element of pname:pSubmits as an instance of the
|
|
slink:VkSubmitInfo structure.
|
|
|
|
Fence and semaphore operations submitted with flink:vkQueueSubmit 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
|
|
<<synchronization-semaphores, semaphore>> and
|
|
<<synchronization-semaphores, fence>> sections of
|
|
<<synchronization, the synchronization chapter>>.
|
|
|
|
Details on the interaction of pname:pWaitDstStageMask with synchronization
|
|
are described in the
|
|
<<synchronization-semaphores-waiting, semaphore wait operation>> section of
|
|
<<synchronization, the synchronization chapter>>.
|
|
|
|
include::../validity/protos/vkQueueSubmit.txt[]
|
|
|
|
// refBegin VkSubmitInfo - Structure specifying a queue submit operation
|
|
|
|
The sname:VkSubmitInfo structure is defined as:
|
|
|
|
include::../api/structs/VkSubmitInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:waitSemaphoreCount is the number of semaphores upon which
|
|
to wait before executing the command buffers for the batch.
|
|
* pname: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
|
|
<<synchronization-semaphores-waiting, semaphore wait operation>>.
|
|
* pname:pWaitDstStageMask is a pointer to an array of pipeline stages at
|
|
which each corresponding semaphore wait will occur.
|
|
* pname:commandBufferCount is the number of command buffers to
|
|
execute in the batch.
|
|
* pname:pCommandBuffers is a pointer to an array of command buffers to
|
|
execute in the batch. The command buffers submitted in a batch begin
|
|
execution in the order they appear in pname:pCommandBuffers, but may:
|
|
complete out of order.
|
|
* pname:signalSemaphoreCount is the number of semaphores to be
|
|
signaled once the commands specified in pname:pCommandBuffers have
|
|
completed execution.
|
|
* pname: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
|
|
<<synchronization-semaphores-signaling, semaphore signal operation>>.
|
|
|
|
include::../validity/structs/VkSubmitInfo.txt[]
|
|
|
|
|
|
[[commandbuffers-submission-progress]]
|
|
== Queue Forward Progress
|
|
|
|
The application must: ensure that command buffer submissions will be able to
|
|
complete without any subsequent operations by the application on any queue.
|
|
After any call to fname:vkQueueSubmit, for every queued wait on a semaphore
|
|
there must: be a prior signal of that semaphore that will not be consumed by a
|
|
different wait on the semaphore.
|
|
|
|
Command buffers in the submission can: include flink:vkCmdWaitEvents
|
|
commands that wait on events that will not be signaled by earlier commands in
|
|
the queue. Such events must: be signaled by the application using
|
|
flink:vkSetEvent, and the fname:vkCmdWaitEvents commands that wait upon them
|
|
mustnot: be inside a render pass instance. Implementations may: have limits
|
|
on how long the command buffer will wait, in order to avoid interfering with
|
|
progress of other clients of the device. If the event is not signaled within
|
|
these limits, results are undefined and may: include device loss.
|
|
|
|
|
|
[[commandbuffers-secondary]]
|
|
== Secondary Command Buffer Execution
|
|
|
|
// refBegin vkCmdExecuteCommands Execute a secondary command buffer from a primary command buffer.
|
|
|
|
A secondary command buffer mustnot: be directly submitted to a queue.
|
|
Instead, secondary command buffers are recorded to execute as part of a
|
|
primary command buffer with the command:
|
|
|
|
include::../api/protos/vkCmdExecuteCommands.txt[]
|
|
|
|
* pname:commandBuffer is a handle to a primary command buffer that the
|
|
secondary command buffers are executed in.
|
|
* pname:commandBufferCount is the length of the pname:pCommandBuffers
|
|
array.
|
|
* pname:pCommandBuffers is an array of secondary command buffer handles,
|
|
which are recorded to execute in the primary command buffer in the order
|
|
they are listed in the array.
|
|
|
|
Once fname:vkCmdExecuteCommands has been called, any prior executions of the
|
|
secondary command buffers specified by pname:pCommandBuffers in any other
|
|
primary command buffer become invalidated, unless those secondary command
|
|
buffers were recorded with
|
|
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT.
|
|
|
|
include::../validity/protos/vkCmdExecuteCommands.txt[]
|