Created documentation chapter "General considerations".

Author: adam-sawicki-a

docs/html/index.html

@@ -83,7 +83,7 @@
 </ul>
 </li>
 <li><a class="el" href="thread_safety.html">Thread safety</a></li>
-<li><a class="el" href="about_the_library.html">About the library</a></li>
+<li><a class="el" href="general_considerations.html">General considerations</a></li>
 </ul>
 <p>See also:</p>
 <ul>

docs/html/lost_allocations.html

@@ -77,17 +77,7 @@
 <p><b>Q: How do you inform the library when new frame starts?</b></p>
 <p>You need to call function <a class="el" href="vk__mem__alloc_8h.html#ade56bf8dc9f5a5eaddf5f119ed525236" title="Sets index of the current frame. ">vmaSetCurrentFrameIndex()</a>.</p>
 <p>Example code:</p>
-<div class="fragment"><div class="line"><span class="keyword">struct </span>MyBuffer</div><div class="line">{</div><div class="line">    VkBuffer m_Buf = <span class="keyword">nullptr</span>;</div><div class="line">    VmaAllocation m_Alloc = <span class="keyword">nullptr</span>;</div><div class="line"></div><div class="line">    <span class="comment">// Called when the buffer is really needed in the current frame.</span></div><div class="line">    <span class="keywordtype">void</span> EnsureBuffer();</div><div class="line">};</div><div class="line"></div><div class="line"><span class="keywordtype">void</span> MyBuffer::EnsureBuffer()</div><div class="line">{</div><div class="line">    <span class="comment">// Buffer has been created.</span></div><div class="line">    <span class="keywordflow">if</span>(m_Buf != VK_NULL_HANDLE)</div><div class="line">    {</div><div class="line">        <span class="comment">// Check if its allocation is not lost + mark it as used in current frame.</span></div><div class="line">        <span class="keywordflow">if</span>(<a class="code" href="vk__mem__alloc_8h.html#a43d8ba9673c846f049089a5029d5c73a">vmaTouchAllocation</a>(allocator, m_Alloc))</div><div class="line">        {</div><div class="line">            <span class="comment">// It&#39;s all OK - safe to use m_Buf.</span></div><div class="line">            <span class="keywordflow">return</span>;</div><div class="line">        }</div><div class="line">    }</div><div class="line"></div><div class="line">    <span class="comment">// Buffer not yet exists or lost - destroy and recreate it.</span></div><div class="line"></div><div class="line">    <a class="code" href="vk__mem__alloc_8h.html#a0d9f4e4ba5bf9aab1f1c746387753d77">vmaDestroyBuffer</a>(allocator, m_Buf, m_Alloc);</div><div class="line"></div><div class="line">    VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };</div><div class="line">    bufCreateInfo.size = 1024;</div><div class="line">    bufCreateInfo.usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;</div><div class="line"></div><div class="line">    <a class="code" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocCreateInfo = {};</div><div class="line">    allocCreateInfo.<a class="code" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code" href="vk__mem__alloc_8h.html#aa5846affa1e9da3800e3e78fae2305ccac6b5dc1432d88647aa4cd456246eadf7">VMA_MEMORY_USAGE_GPU_ONLY</a>;</div><div class="line">    allocCreateInfo.<a class="code" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code" href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a5f436af6c8fe8540573a6d22627a6fd2">VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT</a> |</div><div class="line">        <a class="code" href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a68686d0ce9beb0d4d1b9f2b8b1389a7e">VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT</a>;</div><div class="line"></div><div class="line">    <a class="code" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &amp;bufCreateInfo, &amp;allocCreateInfo, &amp;m_Buf, &amp;m_Alloc, <span class="keyword">nullptr</span>);</div><div class="line">}</div></div><!-- fragment --><p>When using lost allocations, you may see some Vulkan validation layer warnings about overlapping regions of memory bound to different kinds of buffers and images. This is still valid as long as you implement proper handling of lost allocations (like in the example above) and don't use them.</p>
-<p>The library uses following algorithm for allocation, in order:</p>
-<ol type="1">
-<li>Try to find free range of memory in existing blocks.</li>
-<li>If failed, try to create a new block of <code>VkDeviceMemory</code>, with preferred block size.</li>
-<li>If failed, try to create such block with size/2 and size/4.</li>
-<li>If failed and <a class="el" href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a68686d0ce9beb0d4d1b9f2b8b1389a7e">VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT</a> flag was specified, try to find space in existing blocks, possilby making some other allocations lost.</li>
-<li>If failed, try to allocate separate <code>VkDeviceMemory</code> for this allocation, just like when you use <a class="el" href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block. ">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>.</li>
-<li>If failed, choose other memory type that meets the requirements specified in <a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> and go to point 1.</li>
-<li>If failed, return <code>VK_ERROR_OUT_OF_DEVICE_MEMORY</code>. </li>
-</ol>
+<div class="fragment"><div class="line"><span class="keyword">struct </span>MyBuffer</div><div class="line">{</div><div class="line">    VkBuffer m_Buf = <span class="keyword">nullptr</span>;</div><div class="line">    VmaAllocation m_Alloc = <span class="keyword">nullptr</span>;</div><div class="line"></div><div class="line">    <span class="comment">// Called when the buffer is really needed in the current frame.</span></div><div class="line">    <span class="keywordtype">void</span> EnsureBuffer();</div><div class="line">};</div><div class="line"></div><div class="line"><span class="keywordtype">void</span> MyBuffer::EnsureBuffer()</div><div class="line">{</div><div class="line">    <span class="comment">// Buffer has been created.</span></div><div class="line">    <span class="keywordflow">if</span>(m_Buf != VK_NULL_HANDLE)</div><div class="line">    {</div><div class="line">        <span class="comment">// Check if its allocation is not lost + mark it as used in current frame.</span></div><div class="line">        <span class="keywordflow">if</span>(<a class="code" href="vk__mem__alloc_8h.html#a43d8ba9673c846f049089a5029d5c73a">vmaTouchAllocation</a>(allocator, m_Alloc))</div><div class="line">        {</div><div class="line">            <span class="comment">// It&#39;s all OK - safe to use m_Buf.</span></div><div class="line">            <span class="keywordflow">return</span>;</div><div class="line">        }</div><div class="line">    }</div><div class="line"></div><div class="line">    <span class="comment">// Buffer not yet exists or lost - destroy and recreate it.</span></div><div class="line"></div><div class="line">    <a class="code" href="vk__mem__alloc_8h.html#a0d9f4e4ba5bf9aab1f1c746387753d77">vmaDestroyBuffer</a>(allocator, m_Buf, m_Alloc);</div><div class="line"></div><div class="line">    VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };</div><div class="line">    bufCreateInfo.size = 1024;</div><div class="line">    bufCreateInfo.usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;</div><div class="line"></div><div class="line">    <a class="code" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocCreateInfo = {};</div><div class="line">    allocCreateInfo.<a class="code" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code" href="vk__mem__alloc_8h.html#aa5846affa1e9da3800e3e78fae2305ccac6b5dc1432d88647aa4cd456246eadf7">VMA_MEMORY_USAGE_GPU_ONLY</a>;</div><div class="line">    allocCreateInfo.<a class="code" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code" href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a5f436af6c8fe8540573a6d22627a6fd2">VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT</a> |</div><div class="line">        <a class="code" href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a68686d0ce9beb0d4d1b9f2b8b1389a7e">VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT</a>;</div><div class="line"></div><div class="line">    <a class="code" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &amp;bufCreateInfo, &amp;allocCreateInfo, &amp;m_Buf, &amp;m_Alloc, <span class="keyword">nullptr</span>);</div><div class="line">}</div></div><!-- fragment --><p>When using lost allocations, you may see some Vulkan validation layer warnings about overlapping regions of memory bound to different kinds of buffers and images. This is still valid as long as you implement proper handling of lost allocations (like in the example above) and don't use them. </p>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>

docs/html/search/all_0.js

@@ -1,6 +1,5 @@
 var searchData=
 [
-  ['about_20the_20library',['About the library',['../about_the_library.html',1,'index']]],
   ['allocation_20names_20and_20user_20data',['Allocation names and user data',['../allocation_annotation.html',1,'index']]],
   ['allocationcount',['allocationCount',['../struct_vma_stat_info.html#a537741e4d5cdddc1c0ab95ec650afaff',1,'VmaStatInfo::allocationCount()'],['../struct_vma_pool_stats.html#ad1924eb54fffa45e9e0e65670c8fe5eb',1,'VmaPoolStats::allocationCount()']]],
   ['allocationsizeavg',['allocationSizeAvg',['../struct_vma_stat_info.html#a1081a039964e566c672e7a2347f9e599',1,'VmaStatInfo']]],

docs/html/search/all_5.js

@@ -1,4 +1,4 @@
 var searchData=
 [
-  ['lost_20allocations',['Lost allocations',['../lost_allocations.html',1,'index']]]
+  ['general_20considerations',['General considerations',['../general_considerations.html',1,'index']]]
 ];

docs/html/search/all_6.js

@@ -1,12 +1,4 @@
 var searchData=
 [
-  ['maxallocationstomove',['maxAllocationsToMove',['../struct_vma_defragmentation_info.html#aa7c7304e13c71f604c907196c4e28fbc',1,'VmaDefragmentationInfo']]],
-  ['maxblockcount',['maxBlockCount',['../struct_vma_pool_create_info.html#ae41142f2834fcdc82baa4883c187b75c',1,'VmaPoolCreateInfo']]],
-  ['maxbytestomove',['maxBytesToMove',['../struct_vma_defragmentation_info.html#acb311c940a777270e67e1b81c5ab6a1d',1,'VmaDefragmentationInfo']]],
-  ['memory_20mapping',['Memory mapping',['../memory_mapping.html',1,'index']]],
-  ['memoryheap',['memoryHeap',['../struct_vma_stats.html#a0e6611508c29a187f0fd14ff1a0329c0',1,'VmaStats']]],
-  ['memorytype',['memoryType',['../struct_vma_stats.html#a13e3caf754be79352c42408756309331',1,'VmaStats::memoryType()'],['../struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5',1,'VmaAllocationInfo::memoryType()']]],
-  ['memorytypebits',['memoryTypeBits',['../struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055',1,'VmaAllocationCreateInfo']]],
-  ['memorytypeindex',['memoryTypeIndex',['../struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319',1,'VmaPoolCreateInfo']]],
-  ['minblockcount',['minBlockCount',['../struct_vma_pool_create_info.html#ad8006fb803185c0a699d30f3e9a865ae',1,'VmaPoolCreateInfo']]]
+  ['lost_20allocations',['Lost allocations',['../lost_allocations.html',1,'index']]]
 ];

docs/html/search/all_7.js

@@ -1,4 +1,12 @@
 var searchData=
 [
-  ['offset',['offset',['../struct_vma_allocation_info.html#a4a3c732388dbdc7a23f9365b00825268',1,'VmaAllocationInfo']]]
+  ['maxallocationstomove',['maxAllocationsToMove',['../struct_vma_defragmentation_info.html#aa7c7304e13c71f604c907196c4e28fbc',1,'VmaDefragmentationInfo']]],
+  ['maxblockcount',['maxBlockCount',['../struct_vma_pool_create_info.html#ae41142f2834fcdc82baa4883c187b75c',1,'VmaPoolCreateInfo']]],
+  ['maxbytestomove',['maxBytesToMove',['../struct_vma_defragmentation_info.html#acb311c940a777270e67e1b81c5ab6a1d',1,'VmaDefragmentationInfo']]],
+  ['memory_20mapping',['Memory mapping',['../memory_mapping.html',1,'index']]],
+  ['memoryheap',['memoryHeap',['../struct_vma_stats.html#a0e6611508c29a187f0fd14ff1a0329c0',1,'VmaStats']]],
+  ['memorytype',['memoryType',['../struct_vma_stats.html#a13e3caf754be79352c42408756309331',1,'VmaStats::memoryType()'],['../struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5',1,'VmaAllocationInfo::memoryType()']]],
+  ['memorytypebits',['memoryTypeBits',['../struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055',1,'VmaAllocationCreateInfo']]],
+  ['memorytypeindex',['memoryTypeIndex',['../struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319',1,'VmaPoolCreateInfo']]],
+  ['minblockcount',['minBlockCount',['../struct_vma_pool_create_info.html#ad8006fb803185c0a699d30f3e9a865ae',1,'VmaPoolCreateInfo']]]
 ];

docs/html/search/all_8.js

@@ -1,17 +1,4 @@
 var searchData=
 [
-  ['pallocationcallbacks',['pAllocationCallbacks',['../struct_vma_allocator_create_info.html#a6e409087e3be55400d0e4ccbe43c608d',1,'VmaAllocatorCreateInfo']]],
-  ['pdevicememorycallbacks',['pDeviceMemoryCallbacks',['../struct_vma_allocator_create_info.html#af1380969b5e1ea4c3184a877892d260e',1,'VmaAllocatorCreateInfo']]],
-  ['pfn_5fvmaallocatedevicememoryfunction',['PFN_vmaAllocateDeviceMemoryFunction',['../vk__mem__alloc_8h.html#ab6a6477cda1ce775b30bde96d766203b',1,'vk_mem_alloc.h']]],
-  ['pfn_5fvmafreedevicememoryfunction',['PFN_vmaFreeDeviceMemoryFunction',['../vk__mem__alloc_8h.html#aef2545dc2e9dd4f29ab9ba6ac6fe2f49',1,'vk_mem_alloc.h']]],
-  ['pfnallocate',['pfnAllocate',['../struct_vma_device_memory_callbacks.html#a4f17f7b255101e733b44d5633aceabfb',1,'VmaDeviceMemoryCallbacks']]],
-  ['pfnfree',['pfnFree',['../struct_vma_device_memory_callbacks.html#abe8a3328bbc916f6f712fdb6b299444c',1,'VmaDeviceMemoryCallbacks']]],
-  ['pheapsizelimit',['pHeapSizeLimit',['../struct_vma_allocator_create_info.html#a31c192aa6cbffa33279f6d9f0c47c44b',1,'VmaAllocatorCreateInfo']]],
-  ['physicaldevice',['physicalDevice',['../struct_vma_allocator_create_info.html#a08230f04ae6ccf8a78150a9e829a7156',1,'VmaAllocatorCreateInfo']]],
-  ['pmappeddata',['pMappedData',['../struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2',1,'VmaAllocationInfo']]],
-  ['pool',['pool',['../struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150',1,'VmaAllocationCreateInfo']]],
-  ['preferredflags',['preferredFlags',['../struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d',1,'VmaAllocationCreateInfo']]],
-  ['preferredlargeheapblocksize',['preferredLargeHeapBlockSize',['../struct_vma_allocator_create_info.html#a8e4714298e3121cdd8b214a1ae7a637a',1,'VmaAllocatorCreateInfo']]],
-  ['puserdata',['pUserData',['../struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19',1,'VmaAllocationCreateInfo::pUserData()'],['../struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13',1,'VmaAllocationInfo::pUserData()']]],
-  ['pvulkanfunctions',['pVulkanFunctions',['../struct_vma_allocator_create_info.html#a3dc197be3227da7338b1643f70db36bd',1,'VmaAllocatorCreateInfo']]]
+  ['offset',['offset',['../struct_vma_allocation_info.html#a4a3c732388dbdc7a23f9365b00825268',1,'VmaAllocationInfo']]]
 ];

docs/html/search/all_9.js

@@ -1,4 +1,4 @@
 var searchData=
 [
-  ['requiredflags',['requiredFlags',['../struct_vma_allocation_create_info.html#a9166390303ff42d783305bc31c2b6b90',1,'VmaAllocationCreateInfo']]]
+  ['quick_20start',['Quick start',['../quick_start.html',1,'index']]]
 ];

docs/html/search/all_a.js

@@ -1,4 +1,4 @@
 var searchData=
 [
-  ['size',['size',['../struct_vma_pool_stats.html#a326807b2de2b0931cee4ed9a5f2e420c',1,'VmaPoolStats::size()'],['../struct_vma_allocation_info.html#aac76d113a6a5ccbb09fea00fb25fd18f',1,'VmaAllocationInfo::size()']]]
+  ['requiredflags',['requiredFlags',['../struct_vma_allocation_create_info.html#a9166390303ff42d783305bc31c2b6b90',1,'VmaAllocationCreateInfo']]]
 ];