Vulkan规范：第五章 5.3

5.3. 命令缓冲区的记录

可调用下列命令来开始记录命令缓冲区：

VkResult vkBeginCommandBuffer(
    VkCommandBuffer                             commandBuffer,
    const VkCommandBufferBeginInfo*             pBeginInfo);

• commandBuffer 是需要被置为记录状态的命令缓冲区的handle。

• pBeginInfo is an instance of the VkCommandBufferBeginInfo structure, which defines additional information about how the command buffer begins recording.

正确使用

• commandBuffer must not be in the recording state

• commandBuffer must not currently be pending execution

• If commandBuffer was allocated from a VkCommandPool which did not have the VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, commandBuffer must be in the initial state

• If commandBuffer is a secondary command buffer, the pInheritanceInfo member of pBeginInfo must be a validVkCommandBufferInheritanceInfo structure

• If commandBuffer is a secondary command buffer and either the occlusionQueryEnable member of the pInheritanceInfo member of pBeginInfo is VK_FALSE, or the precise occlusion queries feature is not enabled, the queryFlags member of the pInheritanceInfo member pBeginInfo must not containVK_QUERY_CONTROL_PRECISE_BIT

Valid Usage (Implicit)

• commandBuffer must be a valid VkCommandBuffer handle

• pBeginInfo must be a pointer to a valid VkCommandBufferBeginInfo structure

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Return Codes

Success

• VK_SUCCESS

Failure

• VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

VkCommandBufferBeginInfo 数据类型定义如下：

typedef struct VkCommandBufferBeginInfo {
    VkStructureType                          sType;
    const void*                              pNext;
    VkCommandBufferUsageFlags                flags;
    const VkCommandBufferInheritanceInfo*    pInheritanceInfo;
} VkCommandBufferBeginInfo;

• sType 是这个数据结构的类型。

• pNext 为 NULL 或者指向拓展特定结构的指针

• flags 是一个标志位，用来表示命令缓冲区被使用时的行为。 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 ifcommandBuffer is a secondary command buffer. If this is a primary command buffer, then this value is ignored.

正确使用

• If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the renderPass member of pInheritanceInfo must be a valid VkRenderPass

• If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the subpass member of pInheritanceInfo must be a valid subpass index within the renderPass member of pInheritanceInfo

• If flags contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT, the framebuffer member of pInheritanceInfo must be either VK_NULL_HANDLE, or a valid VkFramebuffer that is compatible with the renderPass member of pInheritanceInfo

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO

• pNext must be NULL

• flags must be a valid combination of VkCommandBufferUsageFlagBits values

若命令缓冲区是次级命令缓冲区，那么VkCommandBufferInheritanceInfo 数据结构定义了从主命令缓冲区继承而来的任何状态：

typedef struct VkCommandBufferInheritanceInfo {
    VkStructureType                  sType;
    const void*                      pNext;
    VkRenderPass                     renderPass;
    uint32_t                         subpass;
    VkFramebuffer                    framebuffer;
    VkBool32                         occlusionQueryEnable;
    VkQueryControlFlags              queryFlags;
    VkQueryPipelineStatisticFlags    pipelineStatistics;
} VkCommandBufferInheritanceInfo;

• sType 是数据结构的类型。

• pNext 是 NULL 或者一个指向拓展特定的数据结构的指针。

• 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, renderPassis 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.

  注意 指定次级命令缓冲区将被执行的命令缓冲区将导致该缓冲区执行时有更好的性能。

• 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.

正确使用

• If the inherited queries feature is not enabled, occlusionQueryEnable must be VK_FALSE

• If the inherited queries feature is enabled, queryFlags must be a valid combination of VkQueryControlFlagBitsvalues

• If the pipeline statistics queries feature is not enabled, pipelineStatistics must be 0

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_INFO

• pNext must be NULL

• Both of framebuffer, and renderPass that are valid handles must have been created, allocated, or retrieved from the same VkDevice

主命令缓冲区被认为是从使用vkQueueSubmit提交命令开始、直到提交操作完成之前，都处于暂停执行的状态。

次命令缓冲区被认为从它的执行被记录到主缓冲区（）到主缓冲区提交到队列完成的最终时刻，是出于暂停执行状态的。 如果，在主缓冲区完成了，次缓冲区被记录到另外一个主缓冲区上执行，第一个主缓冲区不能被再次提交，直到通过vkResetCommandBuffer 被重置，除非次命令缓冲区以VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT 标志被记录。

如果没有在次命令缓冲区上设置VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT，那么那个命令缓冲区就不能在 指定主命令缓冲区上使用多次。 还有，如果不带有VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT的次命令缓冲区被记录到一个带有 VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT标志位的主命令缓冲区上执行，那么这个主缓冲区不能被多次暂停执行。

注意 在一些Vulkan实现上，不使用VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT 标志位将导致命令缓冲区在有需求的情况下被部分的替代， 而不是创建创建一份新的命令缓冲区复制。

如果一个命令缓冲区处于可执行状态，且命令缓冲区带有VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT标志位 从缓存池中分配而来，那么vkBeginCommandBuffer将隐式的重置命令缓冲区，就如同不带有VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT参数调用了vkResetCommandBuffer。 然而它把命令缓冲区置为记录中的状态。

Once recording starts, an application records a sequence of commands (vkCmd*) to set state in the command buffer, draw, dispatch, and other commands.

可调用下来命令来结束记录命令缓冲区：

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.

正确使用

• commandBuffer must be in the recording state

• If commandBuffer is a primary command buffer, there must not be an active render pass instance

• All queries made active during the recording of commandBuffer must have been made inactive

Valid Usage (Implicit)

• commandBuffer must be a valid VkCommandBuffer handle

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Return Codes

Success

• VK_SUCCESS

Failure

• VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

当命令缓冲区处于可执行状态时，它可以被提交到队列等待执行。