Minor addition to documentation.

Author: adam-sawicki-a

docs/html/lost_allocations.html

@@ -77,7 +77,9 @@
 <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>
+<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>You can create an allocation that is already in lost state from the beginning using function <a class="el" href="vk__mem__alloc_8h.html#ae5c9657d9e94756269145b01c05d16f1" title="Creates new allocation that is in lost state from the beginning. ">vmaCreateLostAllocation()</a>. It may be useful if you need a "dummy" allocation that is not null.</p>
+<p>You can call function <a class="el" href="vk__mem__alloc_8h.html#a736bd6cbda886f36c891727e73bd4024" title="Marks all allocations in given pool as lost if they are not used in current frame or VmaPoolCreateInf...">vmaMakePoolAllocationsLost()</a> to set all eligible allocations in a specified custom pool to lost state. Allocations that have been "touched" in current frame or <a class="el" href="struct_vma_pool_create_info.html#a9437e43ffbb644dbbf7fc4e50cfad6aa" title="Maximum number of additional frames that are in use at the same time as current frame. ">VmaPoolCreateInfo::frameInUseCount</a> frames back cannot become lost. </p>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>

docs/html/vk__mem__alloc_8h_source.html

@@ -673,6 +673,14 @@ 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.
 
+You can create an allocation that is already in lost state from the beginning using function
+vmaCreateLostAllocation(). It may be useful if you need a "dummy" allocation that is not null.
+
+You can call function vmaMakePoolAllocationsLost() to set all eligible allocations
+in a specified custom pool to lost state.
+Allocations that have been "touched" in current frame or VmaPoolCreateInfo::frameInUseCount frames back
+cannot become lost.
+
 
 \page statistics Statistics