status-im
/
Vulkan-Docs
mirror of https://github.com/status-im/Vulkan-Docs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/chapters/cmdbuffers.txt

584 lines
25 KiB
Plaintext
Raw Blame History

// 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
must: not 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) must: not
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 must: not
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 must: not 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 must: not 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
must: not 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 must: not 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 must: not 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-fences,
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[]
ifdef::VK_NV_win32_keyed_mutex[]
include::VK_NV_win32_keyed_mutex/keyed_mutex_submit.txt[]
endif::VK_NV_win32_keyed_mutex[]
[[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 must: not 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 must: not 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[]
Reference in New Issue View Git Blame Copy Permalink