## 5.3. Command Buffer Recording

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.
  - Setting `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 `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 `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.