To begin recording a command buffer, call:
VkResult vkBeginCommandBuffer( VkCommandBuffer commandBuffer, const VkCommandBufferBeginInfo* pBeginInfo);
commandBuffer
is the handle of the command buffer which is to be
put in the recording state.
pBeginInfo
is an instance of the VkCommandBufferBeginInfo
structure, which defines additional information about how the command
buffer begins recording.
The VkCommandBufferBeginInfo
structure is defined as:
typedef struct VkCommandBufferBeginInfo { VkStructureType sType; const void* pNext; VkCommandBufferUsageFlags flags; const VkCommandBufferInheritanceInfo* pInheritanceInfo; } VkCommandBufferBeginInfo;
sType
is the type of this structure.
pNext
is NULL
or a pointer to an extension-specific structure.
flags
is a bitmask indicating usage behavior for the command
buffer.
Bits which can be set include:
typedef enum VkCommandBufferUsageFlagBits { VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT = 0x00000001, VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT = 0x00000002, VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT = 0x00000004, } VkCommandBufferUsageFlagBits;
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.
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.
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.
pInheritanceInfo
is a pointer to a
VkCommandBufferInheritanceInfo
structure, which is used if
commandBuffer
is a secondary command buffer.
If this is a primary command buffer, then this value is ignored.
If the command buffer is a secondary command buffer, then the
VkCommandBufferInheritanceInfo
structure defines any state that will
be inherited from the primary command buffer:
typedef struct VkCommandBufferInheritanceInfo { VkStructureType sType; const void* pNext; VkRenderPass renderPass; uint32_t subpass; VkFramebuffer framebuffer; VkBool32 occlusionQueryEnable; VkQueryControlFlags queryFlags; VkQueryPipelineStatisticFlags pipelineStatistics; } VkCommandBufferInheritanceInfo;
sType
is the type of this structure.
pNext
is NULL
or a pointer to an extension-specific structure.
renderPass
is a VkRenderPass
object defining which render
passes the VkCommandBuffer
will be compatible with and can be executed within.
If the VkCommandBuffer
will not be executed within a render pass
instance, renderPass
is ignored.
subpass
is the index of the subpass within the render pass
instance that the VkCommandBuffer
will be executed within.
If the VkCommandBuffer
will not be executed within a render pass
instance, subpass
is ignored.
framebuffer
optionally refers to the VkFramebuffer
object
that the VkCommandBuffer
will be rendering to if it is executed
within a render pass instance.
It can be VK_NULL_HANDLE
if the framebuffer is not known, or if
the VkCommandBuffer
will not be executed within a render pass
instance.
![]() | Note |
---|---|
Specifying the exact framebuffer that the secondary command buffer will be executed with may result in better performance at command buffer execution time. |
occlusionQueryEnable
indicates whether the command buffer can be
executed while an occlusion query is active in the primary command
buffer.
If this is VK_TRUE
, then this command buffer can be executed
whether the primary command buffer has an occlusion query active or not.
If this is VK_FALSE
, then the primary command buffer must not
have an occlusion query active.
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 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
VK_QUERY_CONTROL_PRECISE_BIT
bit.
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.
A primary command buffer is considered to be pending execution from the time
it is submitted via 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
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
vkResetCommandBuffer
unless the secondary command buffer was recorded
with VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
.
If 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
VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
set is recorded to
execute in a primary command buffer with
VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT
set, the primary command
buffer must not be pending execution more than once at a time.
![]() | Note |
---|---|
On some implementations, not using the
|
If a command buffer is in the executable state and the command buffer was
allocated from a command pool with the
VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT
flag set, then
vkBeginCommandBuffer
implicitly resets the command buffer, behaving as
if vkResetCommandBuffer
had been called with
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
(vkCmd*
) to set state in the command buffer, draw, dispatch, and other
commands.
To complete recording of a command buffer, call:
VkResult vkEndCommandBuffer( VkCommandBuffer commandBuffer);
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 vkEndCommandBuffer
.
If the application wishes to further use the command buffer, the command
buffer must be reset.
When a command buffer is in the executable state, it can be submitted to a queue for execution.