C Specification

The pNext chain of VkCommandPoolCreateInfo must include a VkCommandPoolMemoryReservationCreateInfo structure. This structure controls how much memory is allocated at command pool creation time to be used for all command buffers recorded from this pool.

The VkCommandPoolMemoryReservationCreateInfo structure is defined as:

// Provided by VKSC_VERSION_1_0
typedef struct VkCommandPoolMemoryReservationCreateInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceSize       commandPoolReservedSize;
    uint32_t           commandPoolMaxCommandBuffers;
} VkCommandPoolMemoryReservationCreateInfo;

Members

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • commandPoolReservedSize is the number of bytes to be allocated for all command buffer data recorded into this pool.

  • commandPoolMaxCommandBuffers is the maximum number of command buffers that can be allocated from this command pool.

Description

The number of command buffers reserved using commandPoolMaxCommandBuffers is permanently counted against the total number of command buffers requested via VkDeviceObjectReservationCreateInfo::commandBufferRequestCount even if the command buffers are freed at a later time.

Each command recorded into a command buffer has an implementation-dependent size that counts against commandPoolReservedSize. There is no minimum command pool size, but some sizes may be too small for any commands to be recorded in them on a given implementation. Applications are expected to estimate their worst-case command buffer memory usage at development time using vkGetCommandPoolMemoryConsumption and reserve large enough command buffers. This command can also be used at runtime to verify expected memory usage.

While the memory consumption of a particular command is implementation-dependent, it is a deterministic function of the parameters to the command and of the objects used by the command (including the command buffer itself). Two command buffers will consume the same amount of pool memory if:

  • all numerical parameters to each command match exactly,

  • all objects used by each command are identically defined, and

  • the order of the commands is the same.

Note

The rules for identically defined objects apply recursively, implying for example that if the command buffers are created in different devices that those devices must have been created with the same features enabled.

Each command buffer may require some base alignment in the pool, so the total pool memory will match if each command buffer’s consumption matches and the command buffers are recorded one at a time and in the same order.

If all these criteria are satisfied, then a command pool memory consumption returned by vkGetCommandPoolMemoryConsumption will be sufficient to record the same command buffers again.

Valid Usage

  • VUID-VkCommandPoolMemoryReservationCreateInfo-commandPoolReservedSize-05003
    commandPoolReservedSize must be greater than 0

  • VUID-VkCommandPoolMemoryReservationCreateInfo-commandPoolMaxCommandBuffers-05004
    commandPoolMaxCommandBuffers must be greater than 0

  • VUID-VkCommandPoolMemoryReservationCreateInfo-commandPoolMaxCommandBuffers-05090
    commandPoolMaxCommandBuffers must be less than or equal to VkPhysicalDeviceVulkanSC10Properties::maxCommandPoolCommandBuffers

  • VUID-VkCommandPoolMemoryReservationCreateInfo-commandPoolMaxCommandBuffers-05074
    The number of command buffers reserved by all command pools plus commandPoolMaxCommandBuffers must be less than or equal to the total number of command buffers requested via VkDeviceObjectReservationCreateInfo::commandBufferRequestCount

Valid Usage (Implicit)

  • VUID-VkCommandPoolMemoryReservationCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_COMMAND_POOL_MEMORY_RESERVATION_CREATE_INFO

See Also

VKSC_VERSION_1_0, VkDeviceSize, VkStructureType

Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0