eden-emu/VulkanMemoryAllocator
14
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator.git synced 2025-05-15 17:28:38 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Added functions vmaCopyMemoryToAllocation, vmaCopyAllocationToMemory

Browse source 
Few other minor fixes and improvements.
Regenerated documentation.
This commit is contained in:
Adam Sawicki 2024-01-21 13:30:23 +01:00
parent 484f40312f
commit b5456bb4e5
190 changed files with 3464 additions and 5181 deletions
Download patch file Download diff file Expand all files Collapse all files

48
docs/html/custom_memory_pools.html
View file

@ -3,12 +3,14 @@
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="generator" content="Doxygen 1.10.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Vulkan Memory Allocator: Custom memory pools</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
@ -29,7 +31,7 @@
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<!-- Generated by Doxygen 1.10.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
@ -41,7 +43,7 @@ var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
$(function() { init_search(); });
});
/* @license-end */
</script>
@ -76,7 +78,7 @@ $(function() {
<div class="headertitle"><div class="title">Custom memory pools</div></div>
</div><!--header-->
<div class="contents">
<div class="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>
<div class="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. You are using default pools whenever you leave <a class="el" href="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150" title="Pool that this allocation should be created in.">VmaAllocationCreateInfo::pool</a> = null.</p>
<p>You can create custom pool and allocate memory out of it. It can be useful if you want to:</p>
<ul>
<li>Keep certain kind of allocations separate from others.</li>
@ -131,15 +133,15 @@ $(function() {
<div class="ttc" id="agroup__group__alloc_html_ga5c8770ded7c59c8caac6de0c2cb00b50"><div class="ttname"><a href="group__group__alloc.html#ga5c8770ded7c59c8caac6de0c2cb00b50">vmaCreatePool</a></div><div class="ttdeci">VkResult vmaCreatePool(VmaAllocator allocator, const VmaPoolCreateInfo *pCreateInfo, VmaPool *pPool)</div><div class="ttdoc">Allocates Vulkan device memory and creates VmaPool object.</div></div>
<div class="ttc" id="agroup__group__alloc_html_gac72ee55598617e8eecca384e746bab51"><div class="ttname"><a href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a></div><div class="ttdeci">VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)</div><div class="ttdoc">Creates a new VkBuffer, allocates and binds memory for it.</div></div>
<div class="ttc" id="agroup__group__alloc_html_gae790ab9ffaf7667fb8f62523e6897888"><div class="ttname"><a href="group__group__alloc.html#gae790ab9ffaf7667fb8f62523e6897888">vmaFindMemoryTypeIndexForBufferInfo</a></div><div class="ttdeci">VkResult vmaFindMemoryTypeIndexForBufferInfo(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, uint32_t *pMemoryTypeIndex)</div><div class="ttdoc">Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.</div></div>
<div class="ttc" id="agroup__group__alloc_html_ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e"><div class="ttname"><a href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a></div><div class="ttdeci">@ VMA_MEMORY_USAGE_AUTO</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:493</div></div>
<div class="ttc" id="astruct_vma_allocation_create_info_html"><div class="ttname"><a href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></div><div class="ttdoc">Parameters of new VmaAllocation.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1223</div></div>
<div class="ttc" id="astruct_vma_allocation_create_info_html_a6272c0555cfd1fe28bff1afeb6190150"><div class="ttname"><a href="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150">VmaAllocationCreateInfo::pool</a></div><div class="ttdeci">VmaPool pool</div><div class="ttdoc">Pool that this allocation should be created in.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1255</div></div>
<div class="ttc" id="astruct_vma_allocation_create_info_html_accb8b06b1f677d858cb9af20705fa910"><div class="ttname"><a href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">VmaAllocationCreateInfo::usage</a></div><div class="ttdeci">VmaMemoryUsage usage</div><div class="ttdoc">Intended usage of memory.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1231</div></div>
<div class="ttc" id="agroup__group__alloc_html_ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e"><div class="ttname"><a href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a></div><div class="ttdeci">@ VMA_MEMORY_USAGE_AUTO</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:510</div></div>
<div class="ttc" id="astruct_vma_allocation_create_info_html"><div class="ttname"><a href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></div><div class="ttdoc">Parameters of new VmaAllocation.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1245</div></div>
<div class="ttc" id="astruct_vma_allocation_create_info_html_a6272c0555cfd1fe28bff1afeb6190150"><div class="ttname"><a href="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150">VmaAllocationCreateInfo::pool</a></div><div class="ttdeci">VmaPool pool</div><div class="ttdoc">Pool that this allocation should be created in.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1277</div></div>
<div class="ttc" id="astruct_vma_allocation_create_info_html_accb8b06b1f677d858cb9af20705fa910"><div class="ttname"><a href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">VmaAllocationCreateInfo::usage</a></div><div class="ttdeci">VmaMemoryUsage usage</div><div class="ttdoc">Intended usage of memory.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1253</div></div>
<div class="ttc" id="astruct_vma_allocation_html"><div class="ttname"><a href="struct_vma_allocation.html">VmaAllocation</a></div><div class="ttdoc">Represents single memory allocation.</div></div>
<div class="ttc" id="astruct_vma_pool_create_info_html"><div class="ttname"><a href="struct_vma_pool_create_info.html">VmaPoolCreateInfo</a></div><div class="ttdoc">Describes parameter of created VmaPool.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1274</div></div>
<div class="ttc" id="astruct_vma_pool_create_info_html_a596fa76b685d3f1f688f84a709a5b319"><div class="ttname"><a href="struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319">VmaPoolCreateInfo::memoryTypeIndex</a></div><div class="ttdeci">uint32_t memoryTypeIndex</div><div class="ttdoc">Vulkan memory type index to allocate this pool from.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1277</div></div>
<div class="ttc" id="astruct_vma_pool_create_info_html_aa4265160536cdb9be821b7686c16c676"><div class="ttname"><a href="struct_vma_pool_create_info.html#aa4265160536cdb9be821b7686c16c676">VmaPoolCreateInfo::blockSize</a></div><div class="ttdeci">VkDeviceSize blockSize</div><div class="ttdoc">Size of a single VkDeviceMemory block to be allocated as part of this pool, in bytes....</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1290</div></div>
<div class="ttc" id="astruct_vma_pool_create_info_html_ae41142f2834fcdc82baa4883c187b75c"><div class="ttname"><a href="struct_vma_pool_create_info.html#ae41142f2834fcdc82baa4883c187b75c">VmaPoolCreateInfo::maxBlockCount</a></div><div class="ttdeci">size_t maxBlockCount</div><div class="ttdoc">Maximum number of blocks that can be allocated in this pool. Optional.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1303</div></div>
<div class="ttc" id="astruct_vma_pool_create_info_html"><div class="ttname"><a href="struct_vma_pool_create_info.html">VmaPoolCreateInfo</a></div><div class="ttdoc">Describes parameter of created VmaPool.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1296</div></div>
<div class="ttc" id="astruct_vma_pool_create_info_html_a596fa76b685d3f1f688f84a709a5b319"><div class="ttname"><a href="struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319">VmaPoolCreateInfo::memoryTypeIndex</a></div><div class="ttdeci">uint32_t memoryTypeIndex</div><div class="ttdoc">Vulkan memory type index to allocate this pool from.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1299</div></div>
<div class="ttc" id="astruct_vma_pool_create_info_html_aa4265160536cdb9be821b7686c16c676"><div class="ttname"><a href="struct_vma_pool_create_info.html#aa4265160536cdb9be821b7686c16c676">VmaPoolCreateInfo::blockSize</a></div><div class="ttdeci">VkDeviceSize blockSize</div><div class="ttdoc">Size of a single VkDeviceMemory block to be allocated as part of this pool, in bytes....</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1312</div></div>
<div class="ttc" id="astruct_vma_pool_create_info_html_ae41142f2834fcdc82baa4883c187b75c"><div class="ttname"><a href="struct_vma_pool_create_info.html#ae41142f2834fcdc82baa4883c187b75c">VmaPoolCreateInfo::maxBlockCount</a></div><div class="ttdeci">size_t maxBlockCount</div><div class="ttdoc">Maximum number of blocks that can be allocated in this pool. Optional.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1325</div></div>
<div class="ttc" id="astruct_vma_pool_html"><div class="ttname"><a href="struct_vma_pool.html">VmaPool</a></div><div class="ttdoc">Represents custom memory pool.</div></div>
</div><!-- fragment --><p>You have to free all allocations made from this pool before destroying it.</p>
<div class="fragment"><div class="line"><a class="code hl_function" href="group__group__alloc.html#ga0d9f4e4ba5bf9aab1f1c746387753d77">vmaDestroyBuffer</a>(allocator, buf, alloc);</div>
@ -147,7 +149,6 @@ $(function() {
<div class="ttc" id="agroup__group__alloc_html_ga0d9f4e4ba5bf9aab1f1c746387753d77"><div class="ttname"><a href="group__group__alloc.html#ga0d9f4e4ba5bf9aab1f1c746387753d77">vmaDestroyBuffer</a></div><div class="ttdeci">void vmaDestroyBuffer(VmaAllocator allocator, VkBuffer buffer, VmaAllocation allocation)</div><div class="ttdoc">Destroys Vulkan buffer and frees allocated memory.</div></div>
<div class="ttc" id="agroup__group__alloc_html_ga5485779c8f1948238fc4e92232fa65e1"><div class="ttname"><a href="group__group__alloc.html#ga5485779c8f1948238fc4e92232fa65e1">vmaDestroyPool</a></div><div class="ttdeci">void vmaDestroyPool(VmaAllocator allocator, VmaPool pool)</div><div class="ttdoc">Destroys VmaPool object and frees Vulkan device memory.</div></div>
</div><!-- fragment --><p>New versions of this library support creating dedicated allocations in custom pools. It is supported only when <a class="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> = 0. To use this feature, set <a class="el" href="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150" title="Pool that this allocation should be created in.">VmaAllocationCreateInfo::pool</a> to the pointer to your custom pool and <a class="el" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b" title="Use VmaAllocationCreateFlagBits enum.">VmaAllocationCreateInfo::flags</a> to <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block.">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>.</p>
<dl class="section note"><dt>Note</dt><dd>Excessive use of custom pools is a common mistake when using this library. Custom pools may be useful for special purposes - when you want to keep certain type of resources separate e.g. to reserve minimum amount of memory for them or limit maximum amount of memory they can occupy. For most resources this is not needed and so it is not recommended to create <a class="el" href="struct_vma_pool.html" title="Represents custom memory pool.">VmaPool</a> objects and allocations out of them. Allocating from the default pool is sufficient.</dd></dl>
<h1><a class="anchor" id="custom_memory_pools_MemTypeIndex"></a>
Choosing memory type index</h1>
<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 <a class="el" href="group__group__alloc.html#gae790ab9ffaf7667fb8f62523e6897888" title="Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.">vmaFindMemoryTypeIndexForBufferInfo()</a>, <a class="el" href="group__group__alloc.html#ga088da83d8eaf3ce9056d9ea0b981d472" 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>
@ -169,6 +170,25 @@ Choosing memory type index</h1>
<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><a class="el" href="struct_vma_allocation_create_info.html" title="Parameters of new VmaAllocation.">VmaAllocationCreateInfo</a>: You don't need to pass same parameters. Fill only <code>pool</code> member. Other members are ignored anyway.</li>
</ul>
<h1><a class="anchor" id="custom_memory_pools_when_not_use"></a>
When not to use custom pools</h1>
<p>Custom pools are commonly overused by VMA users. While it may feel natural to keep some logical groups of resources separate in memory, in most cases it does more harm than good. Using custom pool shouldn't be your first choice. Instead, please make all allocations from default pools first and only use custom pools if you can prove and measure that it is beneficial in some way, e.g. it results in lower memory usage, better performance, etc.</p>
<p>Using custom pools has disadvantages:</p>
<ul>
<li>Each pool has its own collection of <code>VkDeviceMemory</code> blocks. Some of them may be partially or even completely empty. Spreading allocations across multiple pools increases the amount of wasted (allocated but unbound) memory.</li>
<li>You must manually choose specific memory type to be used by a custom pool (set as <a class="el" href="struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319" title="Vulkan memory type index to allocate this pool from.">VmaPoolCreateInfo::memoryTypeIndex</a>). When using default pools, best memory type for each of your allocations can be selected automatically using a carefully design algorithm that works across all kinds of GPUs.</li>
<li>If an allocation from a custom pool at specific memory type fails, entire allocation operation returns failure. When using default pools, VMA tries another compatible memory type.</li>
<li>If you set <a class="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> != 0, each memory block has the same size, while default pools start from small blocks and only allocate next blocks larger and larger up to the preferred block size.</li>
</ul>
<p>Many of the common concerns can be addressed in a different way than using custom pools:</p>
<ul>
<li>If you want to keep your allocations of certain size (small versus large) or certain lifetime (transient versus long lived) separate, you likely don't need to. VMA uses a high quality allocation algorithm that manages memory well in various cases. Please mesure and check if using custom pools provides a benefit.</li>
<li>If you want to keep your images and buffers separate, you don't need to. VMA respects <code>bufferImageGranularity</code> limit automatically.</li>
<li>If you want to keep your mapped and not mapped allocations separate, you don't need to. VMA respects <code>nonCoherentAtomSize</code> limit automatically. It also maps only those <code>VkDeviceMemory</code> blocks that need to map any allocation. It even tries to keep mappable and non-mappable allocations in separate blocks to minimize the amount of mapped memory.</li>
<li>If you want to choose a custom size for the default memory block, you can set it globally instead using <a class="el" href="struct_vma_allocator_create_info.html#a8e4714298e3121cdd8b214a1ae7a637a" title="Preferred size of a single VkDeviceMemory block to be allocated from large heaps &gt; 1 GiB....">VmaAllocatorCreateInfo::preferredLargeHeapBlockSize</a>.</li>
<li>If you want to select specific memory type for your allocation, you can set <a class="el" href="struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055" title="Bitmask containing one bit set for every memory type acceptable for this allocation.">VmaAllocationCreateInfo::memoryTypeBits</a> to <code>(1u &lt;&lt; myMemoryTypeIndex)</code> instead.</li>
<li>If you need to create a buffer with certain minimum alignment, you can still do it using default pools with dedicated function <a class="el" href="group__group__alloc.html#gaa06a690013a0d01e60894ac378083834" title="Creates a buffer with additional minimum alignment.">vmaCreateBufferWithAlignment()</a>.</li>
</ul>
<h1><a class="anchor" id="linear_algorithm"></a>
Linear allocation algorithm</h1>
<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>
@ -207,7 +227,7 @@ Ring buffer</h2>
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.10.0
</small></address>
</body>
</html>