<divclass="textblock"><p>A memory pool contains a number of <code>VkDeviceMemory</code> blocks. The library automatically creates and manages default pool for each memory type available on the device. Default memory pool automatically grows in size. Size of allocated blocks is also variable and managed automatically.</p>
<p>You can create custom pool and allocate memory out of it. It can be useful if you want to:</p>
<li>Use extra parameters for a set of your allocations that are available in <aclass="el"href="struct_vma_pool_create_info.html"title="Describes parameter of created VmaPool.">VmaPoolCreateInfo</a> but not in <aclass="el"href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> - e.g., custom minimum alignment, custom <code>pNext</code> chain.</li>
<li>When making an allocation, set <aclass="el"href="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150"title="Pool that this allocation should be created in.">VmaAllocationCreateInfo::pool</a> to this handle. You don't need to specify any other parameters of this structure, like <code>usage</code>.</li>
<divclass="ttc"id="astruct_vma_allocation_create_info_html_a6272c0555cfd1fe28bff1afeb6190150"><divclass="ttname"><ahref="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150">VmaAllocationCreateInfo::pool</a></div><divclass="ttdeci">VmaPool pool</div><divclass="ttdoc">Pool that this allocation should be created in.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1019</div></div>
<divclass="ttc"id="astruct_vma_allocation_html"><divclass="ttname"><ahref="struct_vma_allocation.html">VmaAllocation</a></div><divclass="ttdoc">Represents single memory allocation.</div></div>
<divclass="ttc"id="astruct_vma_allocation_info_html"><divclass="ttname"><ahref="struct_vma_allocation_info.html">VmaAllocationInfo</a></div><divclass="ttdoc">Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1352</div></div>
<divclass="ttc"id="astruct_vma_pool_create_info_html"><divclass="ttname"><ahref="struct_vma_pool_create_info.html">VmaPoolCreateInfo</a></div><divclass="ttdoc">Describes parameter of created VmaPool.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1153</div></div>
<divclass="ttc"id="astruct_vma_pool_create_info_html_a596fa76b685d3f1f688f84a709a5b319"><divclass="ttname"><ahref="struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319">VmaPoolCreateInfo::memoryTypeIndex</a></div><divclass="ttdeci">uint32_t memoryTypeIndex</div><divclass="ttdoc">Vulkan memory type index to allocate this pool from.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1156</div></div>
<divclass="ttc"id="astruct_vma_pool_create_info_html_ae41142f2834fcdc82baa4883c187b75c"><divclass="ttname"><ahref="struct_vma_pool_create_info.html#ae41142f2834fcdc82baa4883c187b75c">VmaPoolCreateInfo::maxBlockCount</a></div><divclass="ttdeci">size_t maxBlockCount</div><divclass="ttdoc">Maximum number of blocks that can be allocated in this pool. Optional.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1181</div></div>
<p>When creating a pool, you must explicitly specify memory type index. To find the one suitable for your buffers or images, you can use helper functions <aclass="el"href="vk__mem__alloc_8h.html#ae790ab9ffaf7667fb8f62523e6897888"title="Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.">vmaFindMemoryTypeIndexForBufferInfo()</a>, <aclass="el"href="vk__mem__alloc_8h.html#a088da83d8eaf3ce9056d9ea0b981d472"title="Helps to find memoryTypeIndex, given VkImageCreateInfo and VmaAllocationCreateInfo.">vmaFindMemoryTypeIndexForImageInfo()</a>. You need to provide structures with example parameters of buffers or images that you are going to create in that pool.</p>
<li><code>VkBufferCreateInfo</code>: Prefer to pass same parameters as above. Otherwise you risk creating resources in a memory type that is not suitable for them, which may result in undefined behavior. Using different <code>VK_BUFFER_USAGE_</code> flags may work, but you shouldn't create images in a pool intended for buffers or the other way around.</li>
<li><aclass="el"href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a>: You don't need to pass same parameters. Fill only <code>pool</code> member. Other members are ignored anyway.</li>
<p>Each Vulkan memory block managed by this library has accompanying metadata that keeps track of used and unused regions. By default, the metadata structure and algorithm tries to find best place for new allocations among free regions to optimize memory usage. This way you can allocate and free objects in any order.</p>
<p>Sometimes there is a need to use simpler, linear allocation algorithm. You can create custom pool that uses such algorithm by adding flag <aclass="el"href="vk__mem__alloc_8h.html#a9a7c45f9c863695d98c83fa5ac940fe7a13c8a444197c67866be9cb05599fc726"title="Enables alternative, linear allocation algorithm in this pool.">VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT</a> to <aclass="el"href="struct_vma_pool_create_info.html#a8405139f63d078340ae74513a59f5446"title="Use combination of VmaPoolCreateFlagBits.">VmaPoolCreateInfo::flags</a> while creating <aclass="el"href="struct_vma_pool.html"title="Represents custom memory pool.">VmaPool</a> object. Then an alternative metadata management is used. It always creates new allocations after last one and doesn't reuse free regions after allocations freed in the middle. It results in better allocation performance and less memory consumed by metadata.</p>
<p>With this one flag, you can create a custom pool that can be used in many ways: free-at-once, stack, double stack, and ring buffer. See below for details.</p>
<p>In a pool that uses linear algorithm, you still need to free all the allocations individually, e.g. by using <aclass="el"href="vk__mem__alloc_8h.html#a5fea5518972ae9094b1526cbcb19b05f"title="Frees memory previously allocated using vmaAllocateMemory(), vmaAllocateMemoryForBuffer(),...">vmaFreeMemory()</a> or <aclass="el"href="vk__mem__alloc_8h.html#a0d9f4e4ba5bf9aab1f1c746387753d77"title="Destroys Vulkan buffer and frees allocated memory.">vmaDestroyBuffer()</a>. You can free them in any order. New allocations are always made after last one - free space in the middle is not reused. However, when you release all the allocation and the pool becomes empty, allocation starts from the beginning again. This way you can use linear algorithm to speed up creation of allocations that you are going to release all at once.</p>
<p>This mode is also available for pools created with <aclass="el"href="struct_vma_pool_create_info.html#ae41142f2834fcdc82baa4883c187b75c"title="Maximum number of blocks that can be allocated in this pool. Optional.">VmaPoolCreateInfo::maxBlockCount</a> value that allows multiple memory blocks.</p>
<p>When you free an allocation that was created last, its space can be reused. Thanks to this, if you always release allocations in the order opposite to their creation (LIFO - Last In First Out), you can achieve behavior of a stack.</p>
<p>This mode is also available for pools created with <aclass="el"href="struct_vma_pool_create_info.html#ae41142f2834fcdc82baa4883c187b75c"title="Maximum number of blocks that can be allocated in this pool. Optional.">VmaPoolCreateInfo::maxBlockCount</a> value that allows multiple memory blocks.</p>
<p>To make allocation from upper stack, add flag <aclass="el"href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a42ba3a2d2c7117953210b7c3ef8da0df">VMA_ALLOCATION_CREATE_UPPER_ADDRESS_BIT</a> to <aclass="el"href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b"title="Use VmaAllocationCreateFlagBits enum.">VmaAllocationCreateInfo::flags</a>.</p>
<p>Double stack is available only in pools with one memory block - <aclass="el"href="struct_vma_pool_create_info.html#ae41142f2834fcdc82baa4883c187b75c"title="Maximum number of blocks that can be allocated in this pool. Optional.">VmaPoolCreateInfo::maxBlockCount</a> must be 1. Otherwise behavior is undefined.</p>
<p>When the two stacks' ends meet so there is not enough space between them for a new allocation, such allocation fails with usual <code>VK_ERROR_OUT_OF_DEVICE_MEMORY</code> error.</p>
<p>When you free some allocations from the beginning and there is not enough free space for a new one at the end of a pool, allocator's "cursor" wraps around to the beginning and starts allocation there. Thanks to this, if you always release allocations in the same order as you created them (FIFO - First In First Out), you can achieve behavior of a ring buffer / queue.</p>
<p>Pools with linear algorithm support <aclass="el"href="lost_allocations.html">lost allocations</a> when used as ring buffer. If there is not enough free space for a new allocation, but existing allocations from the front of the queue can become lost, they become lost and the allocation succeeds.</p>
<p><imgsrc="../gfx/Linear_allocator_6_ring_buffer_lost.png"alt="Ring buffer with lost allocations"class="inline"/></p>
<p>Ring buffer is available only in pools with one memory block - <aclass="el"href="struct_vma_pool_create_info.html#ae41142f2834fcdc82baa4883c187b75c"title="Maximum number of blocks that can be allocated in this pool. Optional.">VmaPoolCreateInfo::maxBlockCount</a> must be 1. Otherwise behavior is undefined.</p>
<p>There is another allocation algorithm that can be used with custom pools, called "buddy". Its internal data structure is based on a tree of blocks, each having size that is a power of two and a half of its parent's size. When you want to allocate memory of certain size, a free node in the tree is located. If it is too large, it is recursively split into two halves (called "buddies"). However, if requested allocation size is not a power of two, the size of a tree node is aligned up to the nearest power of two and the remaining space is wasted. When two buddy nodes become free, they are merged back into one larger node.</p>
<p>The advantage of buddy allocation algorithm over default algorithm is faster allocation and deallocation, as well as smaller external fragmentation. The disadvantage is more wasted space (internal fragmentation).</p>
<p>For more information, please search the Internet for "Buddy memory allocation" - sources that describe this concept in general.</p>
<p>To use buddy allocation algorithm with a custom pool, add flag <aclass="el"href="vk__mem__alloc_8h.html#a9a7c45f9c863695d98c83fa5ac940fe7a97a0dc38e5161b780594d998d313d35e"title="Enables alternative, buddy allocation algorithm in this pool.">VMA_POOL_CREATE_BUDDY_ALGORITHM_BIT</a> to <aclass="el"href="struct_vma_pool_create_info.html#a8405139f63d078340ae74513a59f5446"title="Use combination of VmaPoolCreateFlagBits.">VmaPoolCreateInfo::flags</a> while creating <aclass="el"href="struct_vma_pool.html"title="Represents custom memory pool.">VmaPool</a> object.</p>
<p>Several limitations apply to pools that use buddy algorithm:</p>
<li>It is recommended to use <aclass="el"href="struct_vma_pool_create_info.html#aa4265160536cdb9be821b7686c16c676"title="Size of a single VkDeviceMemory block to be allocated as part of this pool, in bytes....">VmaPoolCreateInfo::blockSize</a> that is a power of two. Otherwise, only largest power of two smaller than the size is used for allocations. The remaining space always stays unused.</li>
<li><aclass="el"href="debugging_memory_usage.html#debugging_memory_usage_margins">Margins</a> and <aclass="el"href="debugging_memory_usage.html#debugging_memory_usage_corruption_detection">corruption detection</a> don't work in such pools.</li>
<li><aclass="el"href="lost_allocations.html">Lost allocations</a> don't work in such pools. You can use them, but they never become lost. Support may be added in the future.</li>
<li><aclass="el"href="defragmentation.html">Defragmentation</a> doesn't work with allocations made from such pool. </li>
