Vulkan-Docs/doc/specs/vulkan/man/vkBeginCommandBuffer.txt

vkBeginCommandBuffer(3)
=======================

Name
----
vkBeginCommandBuffer - Start recording a command buffer

C Specification
---------------

include::../protos/vkBeginCommandBuffer.txt[]

Parameters
----------

pname:commandBuffer::
    A handle to the command buffer that is to be recorded.

pname:pBeginInfo::
    A pointer to an instance of slink:VkCommandBufferBeginInfo containing information about the command buffer.

Description
-----------

fname:vkBeginCommandBuffer begins recording the command buffer whose handle is
specified in pname:commandBuffer. pname:pBeginInfo is a pointer to an instance of the slink:VkCommandBufferBeginInfo
structure whose definition is:

include::../structs/VkCommandBufferBeginInfo.txt[]

The ptext:sType member of slink:VkCommandBufferBeginInfo should be set to
ename:VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO and the ptext:pNext member of the structure
is reserved for extensions and should be set to code:NULL if none are in use.

The pname:flags member of pname:pBeginInfo may be used to indicate the type of workload
expected to be placed in the command buffer, which may allow implementations
to optimize command buffer contents more appropriately. The available flags for use
in this member are:

include::../enums/VkCommandBufferUsageFlagBits.txt[]

If the pname:flags member contains ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT,
then the command buffer may only be submitted to a queue for execution once,
after which time it must be reset or destroyed. If this flag is not included,
then it is legal to submit the command buffer many times.

If the pname:flags member contains ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
then the command buffer must be a secondary command buffer (see flink:vkAllocateCommandBuffers
for more information) and is considered to be entirely contained inside a renderpass
that is begun in the calling primary command buffer. In such a case, the pname:renderPass,
pname:subpass and pname:framebuffer members refer to the renderpass, subpass and framebuffer
that will be active when the command buffer is referenced with a call to flink:vkCmdExecuteCommands.

If ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not set, then the pname:renderPass,
pname:subpass and pname:framebuffer members are ignored. If the command buffer is a primary
command buffer, then new renderpasses may be initiated by calls to flink:vkCmdBeginRenderPass.
If the command buffer is a secondary command buffer, then it may not contain commands that
are legal only inside a renderpass, and may not be called from a primary command buffer
while a renderpass is active.

If the pname:flags member contains ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT,
then multiple submissions of the command buffer may be in flight simultaneously.

* A primary command buffer is considered to be in flight from the time it is submitted
to a queue by a call to flink:vkQueueSubmit until the time it is retired (signaling
the fence passed to the call to flink:vkQueueSubmit).

* A secondary command buffer is considered to be in flight from a reference to it
it is made from a primary command buffer using a call to flink:vkCmdExecuteCommands
until that primary command buffer is retired.

If ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT is not set,
then only one invocation of the command buffer may be in flight at any time.

It should be noted that for primary command buffers,
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT implies possible multiple submission
of the command buffer, suggesting that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
should be clear. Secondary command buffers may be referenced at most once from
a primary command buffer (even the same primary command buffer) unless
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT is set.

The pname:renderPass and pname:framebuffer members must be sname:VK_NULL_HANDLE
for primary command buffers. For secondary command buffers, they must refer to
the render pass and framebuffer that will be active when the secondary command
buffer is called.

include::../validity/protos/vkBeginCommandBuffer.txt[]

See Also
--------

flink:vkAllocateCommandBuffers, flink:vkFreeCommandBuffers, flink:vkEndCommandBuffer, flink:vkResetCommandBuffer

include::footer.txt[]