801 lines
35 KiB
Plaintext
801 lines
35 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
|
|
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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:queueFamilyIndex must: be the index of a queue family available in
|
|
the calling command's pname:device parameter
|
|
****
|
|
|
|
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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* All sname:VkCommandBuffer objects allocated from pname:commandPool must:
|
|
not currently be pending execution
|
|
****
|
|
|
|
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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* All sname:VkCommandBuffer objects allocated from pname:commandPool must:
|
|
not be pending execution
|
|
* If sname:VkAllocationCallbacks were provided when pname:commandPool was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* If no sname:VkAllocationCallbacks were provided when pname:commandPool
|
|
was created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:commandBufferCount must: be greater than `0`
|
|
****
|
|
|
|
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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:commandBuffer must: not currently be pending execution
|
|
* pname:commandBuffer must: have been allocated from a pool that was
|
|
created with the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT
|
|
****
|
|
|
|
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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* All elements of pname:pCommandBuffers must: not be pending execution
|
|
* pname:pCommandBuffers must: be a pointer to an array of
|
|
pname:commandBufferCount sname:VkCommandBuffer handles, each element of
|
|
which must: either be a valid handle or code:NULL
|
|
****
|
|
|
|
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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:commandBuffer must: not be in the recording state
|
|
* pname:commandBuffer must: not currently be pending execution
|
|
* If pname:commandBuffer was allocated from a sname:VkCommandPool which
|
|
did not have the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT
|
|
flag set, pname:commandBuffer must: be in the initial state
|
|
* If pname:commandBuffer is a secondary command buffer, the
|
|
pname:pInheritanceInfo member of pname:pBeginInfo must: be a valid
|
|
sname:VkCommandBufferInheritanceInfo structure
|
|
* If pname:commandBuffer is a secondary command buffer and either the
|
|
pname:occlusionQueryEnable member of the pname:pInheritanceInfo member
|
|
of pname:pBeginInfo is ename:VK_FALSE, or the precise occlusion queries
|
|
feature is not enabled, the pname:queryFlags member of the
|
|
pname:pInheritanceInfo member pname:pBeginInfo must: not contain
|
|
ename:VK_QUERY_CONTROL_PRECISE_BIT
|
|
****
|
|
|
|
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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* If pname:flags contains
|
|
ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the
|
|
pname:renderPass member of pname:pInheritanceInfo must: be a valid
|
|
sname:VkRenderPass
|
|
* If pname:flags contains
|
|
ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the
|
|
pname:subpass member of pname:pInheritanceInfo must: be a valid subpass
|
|
index within the pname:renderPass member of pname:pInheritanceInfo
|
|
* If pname:flags contains
|
|
ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the
|
|
pname:framebuffer member of pname:pInheritanceInfo must: be either
|
|
dlink:VK_NULL_HANDLE, or a valid sname:VkFramebuffer that is compatible
|
|
with the pname:renderPass member of pname:pInheritanceInfo
|
|
****
|
|
|
|
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:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* 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 the render pass
|
|
instance 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.
|
|
* 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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* If the <<features-features-inheritedQueries,inherited queries>> feature
|
|
is not enabled, pname:occlusionQueryEnable must: be ename:VK_FALSE
|
|
* If the <<features-features-inheritedQueries,inherited queries>> feature
|
|
is enabled, pname:queryFlags must: be a valid combination of
|
|
elink:VkQueryControlFlagBits values
|
|
* If the <<features-features-pipelineStatisticsQuery,pipeline statistics
|
|
queries>> feature is not enabled, pname:pipelineStatistics must: be
|
|
code:0
|
|
****
|
|
|
|
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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:commandBuffer must: be in the recording state
|
|
* If pname:commandBuffer is a primary command buffer, there must: not be
|
|
an active render pass instance
|
|
* All queries made <<queries-operation-active,active>> during the
|
|
recording of pname:commandBuffer must: have been made inactive
|
|
****
|
|
|
|
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>>.
|
|
|
|
.Valid Usage
|
|
****
|
|
* If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be
|
|
unsignaled
|
|
* If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be
|
|
associated with any other queue command that has not yet completed
|
|
execution on that queue
|
|
****
|
|
|
|
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>>.
|
|
|
|
.Valid Usage
|
|
****
|
|
* Any given element of pname:pSignalSemaphores must: currently be
|
|
unsignaled
|
|
* Any given element of pname:pCommandBuffers must: either have been
|
|
recorded with the ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, or
|
|
not currently be executing on the device
|
|
* Any given element of pname:pCommandBuffers must: be in the executable
|
|
state
|
|
* If any given element of pname:pCommandBuffers contains commands that
|
|
execute secondary command buffers, those secondary command buffers must:
|
|
have been recorded with the
|
|
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, or not currently be
|
|
executing on the device
|
|
* If any given element of pname:pCommandBuffers was recorded with
|
|
ename: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 pname:pCommandBuffers contains commands that
|
|
execute secondary command buffers recorded with
|
|
ename:VK_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 pname: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 sname:VkCommandBuffer
|
|
* Any given element of pname:pCommandBuffers must: have been allocated
|
|
from a sname:VkCommandPool that was created for the same queue family
|
|
that the calling command's pname:queue belongs to
|
|
* Any given element of pname:pCommandBuffers must: not have been allocated
|
|
with ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY
|
|
* Any given element of sname:VkSemaphore in pname:pWaitSemaphores must:
|
|
refer to a prior signal of that sname:VkSemaphore that will not be
|
|
consumed by any other wait on that semaphore
|
|
* If the <<features-features-geometryShader,geometry shaders>> feature is
|
|
not enabled, any given element of pname:pWaitDstStageMask must: not
|
|
contain ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
|
|
* If the <<features-features-tessellationShader,tessellation shaders>>
|
|
feature is not enabled, any given element of pname:pWaitDstStageMask
|
|
must: not contain
|
|
ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or
|
|
ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
|
|
****
|
|
|
|
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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:commandBuffer must: have been allocated with a pname:level of
|
|
ename:VK_COMMAND_BUFFER_LEVEL_PRIMARY
|
|
* Any given element of pname:pCommandBuffers must: have been allocated
|
|
with a pname:level of ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY
|
|
* Any given element of pname:pCommandBuffers must: not be already pending
|
|
execution in pname:commandBuffer, or appear twice in
|
|
pname:pCommandBuffers, unless it was recorded with the
|
|
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag
|
|
* Any given element of pname:pCommandBuffers must: not be already pending
|
|
execution in any other sname:VkCommandBuffer, unless it was recorded
|
|
with the ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag
|
|
* Any given element of pname:pCommandBuffers must: be in the executable
|
|
state
|
|
* Any given element of pname:pCommandBuffers must: have been allocated
|
|
from a sname:VkCommandPool that was created for the same queue family as
|
|
the sname:VkCommandPool from which pname:commandBuffer was allocated
|
|
* If fname:vkCmdExecuteCommands is being called within a render pass
|
|
instance, that render pass instance must: have been begun with the
|
|
pname:contents parameter of fname:vkCmdBeginRenderPass set to
|
|
ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS
|
|
* If fname:vkCmdExecuteCommands is being called within a render pass
|
|
instance, any given element of pname:pCommandBuffers must: have been
|
|
recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
|
|
* If fname:vkCmdExecuteCommands is being called within a render pass
|
|
instance, any given element of pname:pCommandBuffers must: have been
|
|
recorded with sname:VkCommandBufferInheritanceInfo::pname:subpass set to
|
|
the index of the subpass which the given command buffer will be executed
|
|
in
|
|
* If fname:vkCmdExecuteCommands is being called within a render pass
|
|
instance, any given element of pname:pCommandBuffers must: have been
|
|
recorded with a render pass that is compatible with the current render
|
|
pass - see <<renderpass-compatibility>>
|
|
* If fname:vkCmdExecuteCommands is being called within a render pass
|
|
instance, and any given element of pname:pCommandBuffers was recorded
|
|
with sname:VkCommandBufferInheritanceInfo::pname:framebuffer not equal
|
|
to dlink:VK_NULL_HANDLE, that sname:VkFramebuffer must: match the
|
|
sname:VkFramebuffer used in the current render pass instance
|
|
* If fname:vkCmdExecuteCommands is not being called within a render pass
|
|
instance, any given element of pname:pCommandBuffers must: not have been
|
|
recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
|
|
* If the <<features-features-inheritedQueries,inherited queries>> feature
|
|
is not enabled, pname:commandBuffer must: not have any queries
|
|
<<queries-operation-active,active>>
|
|
* If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query
|
|
<<queries-operation-active,active>>, then each element of
|
|
pname:pCommandBuffers must: have been recorded with
|
|
sname:VkCommandBufferInheritanceInfo::pname:occlusionQueryEnable set to
|
|
ename:VK_TRUE
|
|
* If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query
|
|
<<queries-operation-active,active>>, then each element of
|
|
pname:pCommandBuffers must: have been recorded with
|
|
sname:VkCommandBufferInheritanceInfo::pname:queryFlags having all bits
|
|
set that are set for the query
|
|
* If pname:commandBuffer has a ename:VK_QUERY_TYPE_PIPELINE_STATISTICS
|
|
query <<queries-operation-active,active>>, then each element of
|
|
pname:pCommandBuffers must: have been recorded with
|
|
sname:VkCommandBufferInheritanceInfo::pname:pipelineStatistics having
|
|
all bits set that are set in the sname:VkQueryPool the query uses
|
|
* Any given element of pname:pCommandBuffers must: not begin any query
|
|
types that are <<queries-operation-active,active>> in
|
|
pname:commandBuffer
|
|
****
|
|
|
|
include::../validity/protos/vkCmdExecuteCommands.txt[]
|