Understanding command pool and buffer APIs

This section will explain the different APIs that can be used to manage the command pool and command buffers. Here, we will understand the process of creating a command buffer pool that will be used for command buffer allocation. We will also look at the process of resetting and destroying APIs.

The next section of this chapter will be based on implementing these APIs in a ready-to-use wrapper class. The wrapper implementation will be highly useful in the remaining chapters of this book, where we will extensively make use of the command buffer.

Tip

As a prerequisite for the upcoming chapters, the Implementing the command pool and command buffers, Recording command buffers, and Managing memory in Vulkan sections are important.

Creating a command pool

A command pool is created using the vkCreateCommandPool() API. It accepts a VkCommandPoolCreateInfo control structure, which guides the implementation about the nature of command buffers that are going to be allocated from this pool. It also indicates which queue family it should belong to. This information, which is provided in advance, is useful to allocate compatible command pools; these pools can be used to optimize the command buffer allocation process for a typical queue submission. Here's the syntax of this:

typedef struct VkCommandPoolCreateInfo { 
    VkStructureType             sType; 
    const void*                 next; 
    VkCommandPoolCreateFlags    flags; 
    uint32_t                    queueFamilyIndex; 
  } VkCommandPoolCreateInfo;

The following table describes the various fields of VkCommandPoolCreateInfo:

Parameters

Description

type

This is the type information of this control structure. It must be specified as VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO.

next

This could be a valid pointer to an extension-specific structure or NULL.

flag

This represents a bitwise enum flag that indicates the behavior of the command pool usage and the command buffer being allocated from it. This enum flag is of the type VkCommandPoolFlag, and it can take VK_COMMAND_POOL_CREATE_TRANSIENT_BIT and VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT as possible input values. For more information on these flag values, refer to the following tip.

queueFamily

Index

This indicates the queue family to which the command buffer is intended to be submitted.

Tip

The VK_COMMAND_POOL_CREATE_TRANSIENT_BIT enum flag indicates that the command buffers allocated from this pool will be changed frequently and have a shorter lifespan. This means that the buffers will be reset or freed in a relatively short timeframe. This flag notifies the implementation about the nature of the command buffer, and this can be used to control the memory allocation behavior within the pool.

When the VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag is set, it indicates that a command buffer allocated from the pool can be individually reset in two ways: either explicitly by calling vkResetCommandBuffer or implicitly by calling vkBeginCommandBuffer. If this flag is not set, then these two APIs must not be called on the executable command buffers allocated from the pool. This indicates that they can only be reset in bulk by calling vkResetCommandPool.

The command pool in Vulkan is represented by the VkCommandPool object. It is created using the vkCreateCommandPool() API. The following is the syntax and description of the API:

VkResult vkCreateCommandPool( 
    VkDevice                        device, 
    const VkCommandPoolCreateInfo*  pCreateInfo, 
    const VkAllocationCallbacks*    pAllocator, 
    VkCommandPool*                  pCommandPool);

The following table describes the various fields of this API:

Parameters

Description

device

This is the handle of the device that will create the command pool.

pCreateInfo

This refers to the VkCommandPoolCreateInfo object that indicates the nature of the command buffer in the command pool.

pAllocator

This controls host memory allocation.

pCommandPool

This represents the VkCommandPool object returned by the API.

Note

For more information on how to control host memory allocation using VkAllocationCallbacks* allocator, refer to the Host memory topic in the last section of this chapter, namely Managing memory in Vulkan.

Resetting a command pool

The command pool (VkCommandPool) can be reset using the vkResetCommandPool() API. Here is the syntax of this API:

VkResult vkResetCommandPool ( 
    VkDevice                 device, 
    VkCommandPool            commandPool, 
    VkCommandPoolResetFlags  flags);

The following are the parameters of this API:

Parameters

Description

device

This is the handle of the device that owns the command pool.

commandPool

This refers to the VkCommandPool handle that needs to be reset.

flags

This flag controls the behavior of resetting the pool.

Destroying a command pool

A command pool can be destroyed using the vkDestroyCommandPool() API. Here's the syntax of this:

VkResult vkDestroyCommandPool( 
    VkDevice                      device, 
    VkCommandPool                 commandPool, 
    const VkAllocationCallbacks*  allocator);

The following are the parameters of this API:

Parameters

Description

device

This is the handle of the device that destroys the command pool.

commandPool

This refers to the VkCommandPool handle that needs to be destroyed.

allocator

This controls host memory allocation. For more information, refer to the Host memory section in Chapter 5, Command Buffer and Memory Management in Vulkan.

Command buffer allocation

Command buffers are allocated from the command buffer pool (VkCommandPool) using the vkAllocateCommandBuffers() API. This API needs the VkCommandBufferAllocateInfo control structure object, which specifies the various parameters that will be helpful in the allocation process. Upon successful execution of the API, it returns the VkCommandBuffer object. The following is the syntax of this API:

VkResult vkAllocateCommandBuffers( 
    VkDevice                           device, 
    const VkCommandBufferAllocateInfo* pAllocateInfo, 
    VkCommandBuffer*                   pCommandBuffers);

Let's take a look at the API fields:

Parameters

Description

device

This is the handle of the logical device object that owns the command pool.

pAllocateInfo

This is a pointer to a VkCommandBufferAllocateInfo structure describing the parameters of the allocation; refer to the next table for more information.

pCommandBuffers

This refers to the allocated command buffer object array.

The VkCommandBufferAllocateInfo structure has the following fields.

Parameters

Description

sType

This refers to the type information telling Vulkan that it is a VkCommandBufferAllocate structure, this must be a type of VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO:

pNext

This refers to NULL or an extension-specific structure.

commandPool

This is the command pool handle from which memory needs to be allocated for the requested command buffers.

level

This is the bitwise enum flag of the type VkCommandBufferLevel indicating whether the command buffer is at the primary or secondary level. The following is the syntax of VkCommandBufferLevel: 

     typedef enum VkCommandBufferLevel {   
       VK_COMMAND_BUFFER_LEVEL_PRIMARY=0,   
       VK_COMMAND_BUFFER_LEVEL_SECONDARY=1,   
     } VkCommandBufferLevel;

commandBufferCount

This refers to the number of command buffers that need to be allocated.

Resetting command buffers

The allocated command buffer can be reset using the vkResetCommandBuffer() API. This API accepts the VkCommandBuffer object as the first parameter that needs to be reset. The second parameter is a bitwise mask, VkCommandBufferResetFlag, which controls the behavior of the reset operation. This structure has one enum value, namely VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT. When this value is set, it means that the memory held by the command buffer will be returned to the parent command pool.

The following is the syntax of the API:

VkResult vkResetCommandBuffer( 
    VkCommandBuffer           commandBuffer, 
    VkCommandBufferResetFlags flags);

Freeing command buffers

One or more command buffers can be released using the vkFreeCommandBuffer() API. Here's the syntax of this API:

void vkFreeCommandBuffers( 
    VkDevice               device, 
    VkCommandPool          commandPool, 
    uint32_t               commandBufferCount, 
    const VkCommandBuffer* pCommandBuffers);

The following are the parameters of the vkFreeCommandBuffers() API along with their respective descriptions:

Parameters

Description

device

This refers to the logical device that holds the command pool.

commandPool

This refers to the associated command pool from which the memory has to be released.

commandBufferCount

This refers to the number of command buffers that need to be released.

pCommandBuffers

This is an array of command buffer handles that needs to be released.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.15.221.133