Command pools are opaque objects that command buffer memory is allocated from, and which allow the implementation to amortize the cost of resource creation across multiple command buffers. Command pools are application-synchronized, meaning that a command pool must not be used concurrently in multiple threads. That includes use via recording commands on any command buffers allocated from the pool, as well as operations that allocate, free, and reset command buffers or the pool itself.
Command pools are represented by VkCommandPool
handles:
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCommandPool)
To create a command pool, call:
VkResult vkCreateCommandPool( VkDevice device, const VkCommandPoolCreateInfo* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkCommandPool* pCommandPool);
device
is the logical device that creates the command pool.
pCreateInfo
contains information used to create the command pool.
pAllocator
controls host memory allocation as described in the
Memory Allocation chapter.
pCommandPool
points to a VkCommandPool
handle in which the
created pool is returned.
The VkCommandPoolCreateInfo
structure is defined as:
typedef struct VkCommandPoolCreateInfo { VkStructureType sType; const void* pNext; VkCommandPoolCreateFlags flags; uint32_t queueFamilyIndex; } VkCommandPoolCreateInfo;
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 pool and
command buffers allocated from it.
Bits which can be set include:
typedef enum VkCommandPoolCreateFlagBits { VK_COMMAND_POOL_CREATE_TRANSIENT_BIT = 0x00000001, VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT = 0x00000002, } VkCommandPoolCreateFlagBits;
VK_COMMAND_POOL_CREATE_TRANSIENT_BIT
indicates that command
buffers allocated from the pool will be short-lived, meaning that they
will be reset or freed in a relatively short timeframe.
This flag may be used by the implementation to control memory
allocation behavior within the pool.
VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT
controls whether
command buffers allocated from the pool can be individually reset.
If this flag is set, individual command buffers allocated from the pool
can be reset either explicitly, by calling vkResetCommandBuffer
,
or implicitly, by calling vkBeginCommandBuffer
on an executable
command buffer.
If this flag is not set, then vkResetCommandBuffer
and
vkBeginCommandBuffer
(on an executable command buffer) must not
be called on the command buffers allocated from the pool, and they can
only be reset in bulk by calling vkResetCommandPool
.
queueFamilyIndex
designates a queue family as described in section
Queue Family Properties.
All command buffers allocated from this command pool must be submitted
on queues from the same queue family.
To reset a command pool, call:
VkResult vkResetCommandPool( VkDevice device, VkCommandPool commandPool, VkCommandPoolResetFlags flags);
device
is the logical device that owns the command pool.
commandPool
is the command pool to reset.
flags
contains additional flags controlling the behavior of the
reset.
Bits which can be set include:
typedef enum VkCommandPoolResetFlagBits { VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT = 0x00000001, } VkCommandPoolResetFlagBits;
If flags
includes VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT
,
resetting a command pool recycles all of the resources from the command pool
back to the system.
Resetting a command pool recycles all of the resources from all of the command buffers allocated from the command pool back to the command pool. All command buffers that have been allocated from the command pool are put in the initial state.
To destroy a command pool, call:
void vkDestroyCommandPool( VkDevice device, VkCommandPool commandPool, const VkAllocationCallbacks* pAllocator);
device
is the logical device that destroys the command pool.
commandPool
is the handle of the command pool to destroy.
pAllocator
controls host memory allocation as described in the
Memory Allocation chapter.
When a pool is destroyed, all command buffers allocated from the pool are implicitly freed and become invalid. Command buffers allocated from a given pool do not need to be freed before destroying that command pool.