VKBEGINCOMMANDBUFFER(3)

NAME
vkBeginCommandBuffer - Start recording a command buffer

C SPECIFICATION

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

PARAMETERS

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

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

DESCRIPTION

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

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

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

The flags member of 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:

    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;

If the flags member contains 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 flags member contains VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT then the command buffer must be a secondary command buffer (see 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 renderPass, subpass and framebuffer members refer to the renderpass, subpass and framebuffer that will be active when the command buffer is referenced with a call to vkCmdExecuteCommands.

If VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not set, then the renderPass, subpass and framebuffer members are ignored. If the command buffer is a primary command buffer, then new renderpasses may be initiated by calls to 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 flags member contains 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 vkQueueSubmit until the time it is retired (signaling the fence passed to the call to 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 vkCmdExecuteCommands until that primary command buffer is retired.

If 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, VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT implies possible multiple submission of the command buffer, suggesting that 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 VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT is set.

The renderPass and framebuffer members must be 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.

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • pBeginInfo must be a pointer to a valid VkCommandBufferBeginInfo structure

    • 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 valid VkCommandBufferInheritanceInfo 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 contain VK_QUERY_CONTROL_PRECISE_BIT

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

RETURN CODES

On success, this command returns

        • VK_SUCCESS

On failure, this command returns

        • VK_ERROR_OUT_OF_HOST_MEMORY

        • VK_ERROR_OUT_OF_DEVICE_MEMORY

SEE ALSO

vkAllocateCommandBuffers, vkFreeCommandBuffers, vkEndCommandBuffer, vkResetCommandBuffer

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.