More documentation. Especially added new section "Finding out if memory is mappable".

docs/html/vk__mem__alloc_8h.html

@@ -1295,8 +1295,9 @@ Functions</h2></td></tr>
 <p>The function also frees empty <code>VkDeviceMemory</code> blocks.</p>
 <p>After allocation has been moved, its <a class="el" href="struct_vma_allocation_info.html#ae0bfb7dfdf79a76ffefc9a94677a2f67" title="Handle to Vulkan memory object. ">VmaAllocationInfo::deviceMemory</a> and/or <a class="el" href="struct_vma_allocation_info.html#a4a3c732388dbdc7a23f9365b00825268" title="Offset into deviceMemory object to the beginning of this allocation, in bytes. (deviceMemory, offset) pair is unique to this allocation. ">VmaAllocationInfo::offset</a> changes. You must query them again using <a class="el" href="vk__mem__alloc_8h.html#a86dd08aba8633bfa4ad0df2e76481d8b" title="Returns current information about specified allocation. ">vmaGetAllocationInfo()</a> if you need them.</p>
 <p>If an allocation has been moved, data in memory is copied to new place automatically, but if it was bound to a buffer or an image, you must destroy that object yourself, create new one and bind it to the new memory pointed by the allocation. You must use <code>vkDestroyBuffer()</code>, <code>vkDestroyImage()</code>, <code>vkCreateBuffer()</code>, <code>vkCreateImage()</code> for that purpose and NOT <a class="el" href="vk__mem__alloc_8h.html#a0d9f4e4ba5bf9aab1f1c746387753d77" title="Destroys Vulkan buffer and frees allocated memory. ">vmaDestroyBuffer()</a>, <a class="el" href="vk__mem__alloc_8h.html#ae50d2cb3b4a3bfd4dd40987234e50e7e" title="Destroys Vulkan image and frees allocated memory. ">vmaDestroyImage()</a>, <a class="el" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer()</a>, <a class="el" href="vk__mem__alloc_8h.html#a02a94f25679275851a53e82eacbcfc73" title="Function similar to vmaCreateBuffer(). ">vmaCreateImage()</a>! Example:</p>
-<div class="fragment"><div class="line">VkDevice device = ...;</div><div class="line">VmaAllocator allocator = ...;</div><div class="line">std::vector&lt;VkBuffer&gt; buffers = ...;</div><div class="line">std::vector&lt;VmaAllocation&gt; allocations = ...;</div><div class="line"></div><div class="line">std::vector&lt;VkBool32&gt; allocationsChanged(allocations.size());</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#a6aced90fcc7b39882b6654a740a0b9bb">vmaDefragment</a>(allocator, allocations.data(), allocations.size(), allocationsChanged.data(), <span class="keyword">nullptr</span>, <span class="keyword">nullptr</span>);</div><div class="line"></div><div class="line"><span class="keywordflow">for</span>(<span class="keywordtype">size_t</span> i = 0; i &lt; allocations.size(); ++i)</div><div class="line">{</div><div class="line">    <span class="keywordflow">if</span>(allocationsChanged[i])</div><div class="line">    {</div><div class="line">        <a class="code" href="struct_vma_allocation_info.html">VmaAllocationInfo</a> allocInfo;</div><div class="line">        <a class="code" href="vk__mem__alloc_8h.html#a86dd08aba8633bfa4ad0df2e76481d8b">vmaGetAllocationInfo</a>(allocator, allocations[i], &amp;allocInfo);</div><div class="line"></div><div class="line">        vkDestroyBuffer(device, buffers[i], <span class="keyword">nullptr</span>);</div><div class="line"></div><div class="line">        VkBufferCreateInfo bufferInfo = ...;</div><div class="line">        vkCreateBuffer(device, &amp;bufferInfo, <span class="keyword">nullptr</span>, &amp;buffers[i]);</div><div class="line">            </div><div class="line">        <span class="comment">// You can make dummy call to vkGetBufferMemoryRequirements here to silence validation layer warning.</span></div><div class="line">            </div><div class="line">        vkBindBufferMemory(device, buffers[i], allocInfo.<a class="code" href="struct_vma_allocation_info.html#ae0bfb7dfdf79a76ffefc9a94677a2f67">deviceMemory</a>, allocInfo.<a class="code" href="struct_vma_allocation_info.html#a4a3c732388dbdc7a23f9365b00825268">offset</a>);</div><div class="line">    }</div><div class="line">}</div></div><!-- fragment --><p>Warning! This function is not correct according to Vulkan specification. Use it at your own risk. That's becuase Vulkan doesn't guarantee that memory requirements (size and alignment) for a new buffer or image are consistent. They may be different even for subsequent calls with the same parameters. It really does happen on some platforms, especially with images.</p>
-<p>This function may be time-consuming, so you shouldn't call it too often (like every frame or after every resource creation/destruction), but rater you can call it on special occasions (like when reloading a game level, when you just destroyed a lot of objects). </p>
+<div class="fragment"><div class="line">VkDevice device = ...;</div><div class="line">VmaAllocator allocator = ...;</div><div class="line">std::vector&lt;VkBuffer&gt; buffers = ...;</div><div class="line">std::vector&lt;VmaAllocation&gt; allocations = ...;</div><div class="line"></div><div class="line">std::vector&lt;VkBool32&gt; allocationsChanged(allocations.size());</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#a6aced90fcc7b39882b6654a740a0b9bb">vmaDefragment</a>(allocator, allocations.data(), allocations.size(), allocationsChanged.data(), <span class="keyword">nullptr</span>, <span class="keyword">nullptr</span>);</div><div class="line"></div><div class="line"><span class="keywordflow">for</span>(<span class="keywordtype">size_t</span> i = 0; i &lt; allocations.size(); ++i)</div><div class="line">{</div><div class="line">    <span class="keywordflow">if</span>(allocationsChanged[i])</div><div class="line">    {</div><div class="line">        <a class="code" href="struct_vma_allocation_info.html">VmaAllocationInfo</a> allocInfo;</div><div class="line">        <a class="code" href="vk__mem__alloc_8h.html#a86dd08aba8633bfa4ad0df2e76481d8b">vmaGetAllocationInfo</a>(allocator, allocations[i], &amp;allocInfo);</div><div class="line"></div><div class="line">        vkDestroyBuffer(device, buffers[i], <span class="keyword">nullptr</span>);</div><div class="line"></div><div class="line">        VkBufferCreateInfo bufferInfo = ...;</div><div class="line">        vkCreateBuffer(device, &amp;bufferInfo, <span class="keyword">nullptr</span>, &amp;buffers[i]);</div><div class="line">            </div><div class="line">        <span class="comment">// You can make dummy call to vkGetBufferMemoryRequirements here to silence validation layer warning.</span></div><div class="line">            </div><div class="line">        vkBindBufferMemory(device, buffers[i], allocInfo.<a class="code" href="struct_vma_allocation_info.html#ae0bfb7dfdf79a76ffefc9a94677a2f67">deviceMemory</a>, allocInfo.<a class="code" href="struct_vma_allocation_info.html#a4a3c732388dbdc7a23f9365b00825268">offset</a>);</div><div class="line">    }</div><div class="line">}</div></div><!-- fragment --><p>Note: Please don't expect memory to be fully compacted after this call. Algorithms inside are based on some heuristics that try to maximize number of Vulkan memory blocks to make totally empty to release them, as well as to maximimze continuous empty space inside remaining blocks, while minimizing the number and size of data that needs to be moved. Some fragmentation still remains after this call. This is normal.</p>
+<p>Warning: This function is not 100% correct according to Vulkan specification. Use it at your own risk. That's because Vulkan doesn't guarantee that memory requirements (size and alignment) for a new buffer or image are consistent. They may be different even for subsequent calls with the same parameters. It really does happen on some platforms, especially with images.</p>
+<p>Warning: This function may be time-consuming, so you shouldn't call it too often (like every frame or after every resource creation/destruction). You can call it on special occasions (like when reloading a game level or when you just destroyed a lot of objects). </p>
 
 </div>
 </div>