mirror/VulkanMemoryAllocator
1
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator.git synced 2024-11-10 02:31:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Written new contents of "Mapping memory" documentation chapter.

Browse Source
This commit is contained in:
Adam Sawicki 2018-03-01 12:19:37 +01:00
parent f44305429c
commit a3e019d476
7 changed files with 223 additions and 181 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/html/choosing_memory_type.html
View File

@ -78,7 +78,7 @@ $(function() {
<p>You can leave <a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> structure completely filled with zeros. It means no requirements are specified for memory type. It is valid, although not very useful.</p>
<h1><a class="anchor" id="choosing_memory_type_usage"></a>
Usage</h1>
<p>The easiest way to specify memory requirements is to fill member <a class="el" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910" title="Intended usage of memory. ">VmaAllocationCreateInfo::usage</a> using one of the values of enum <code>VmaMemoryUsage</code>. It defines high level, common usage types.</p>
<p>The easiest way to specify memory requirements is to fill member <a class="el" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910" title="Intended usage of memory. ">VmaAllocationCreateInfo::usage</a> using one of the values of enum <a class="el" href="vk__mem__alloc_8h.html#aa5846affa1e9da3800e3e78fae2305cc">VmaMemoryUsage</a>. It defines high level, common usage types. For more details, see description of this enum.</p>
<p>For example, if you want to create a uniform buffer that will be filled using transfer only once or infrequently and used for rendering every frame, you can do it using following code:</p>
<div class="fragment"><div class="line">VkBufferCreateInfo bufferInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };</div><div class="line">bufferInfo.size = 65536;</div><div class="line">bufferInfo.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> allocInfo = {};</div><div class="line">allocInfo.<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"></div><div class="line">VkBuffer buffer;</div><div class="line">VmaAllocation allocation;</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &amp;bufferInfo, &amp;allocInfo, &amp;buffer, &amp;allocation, <span class="keyword">nullptr</span>);</div></div><!-- fragment --><h1><a class="anchor" id="choosing_memory_type_required_preferred_flags"></a>
Required and preferred flags</h1>

31
docs/html/memory_mapping.html
View File

@ -66,22 +66,23 @@ $(function() {
<div class="title">Memory mapping </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="persistently_mapped_memory"></a>
<div class="textblock"><p>To "map memory" in Vulkan means to obtain a CPU pointer to <code>VkDeviceMemory</code>, to be able to read from it or write to it in CPU code. Mapping is possible only of memory allocated from a memory type that has <code>VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT</code> flag. Functions <code>vkMapMemory()</code>, <code>vkUnmapMemory()</code> are designed for this purpose. You can use them directly with memory allocated by this library, but it is not recommended because of following issue: Mapping the same <code>VkDeviceMemory</code> block multiple times is illegal - only one mapping at a time is allowed. This includes mapping disjoint regions. Mapping is not reference-counted internally by Vulkan. Because of this, Vulkan Memory Allocator provides following facilities:</p>
<h1><a class="anchor" id="memory_mapping_mapping_functions"></a>
Mapping functions</h1>
<p>The library provides following functions for mapping of a specific <code>VmaAllocation</code>: <a class="el" href="vk__mem__alloc_8h.html#ad5bd1243512d099706de88168992f069" title="Maps memory represented by given allocation and returns pointer to it. ">vmaMapMemory()</a>, <a class="el" href="vk__mem__alloc_8h.html#a9bc268595cb33f6ec4d519cfce81ff45" title="Unmaps memory represented by given allocation, mapped previously using vmaMapMemory(). ">vmaUnmapMemory()</a>. They are safer and more convenient to use than standard Vulkan functions. You can map an allocation multiple times simultaneously - mapping is reference-counted internally. You can also map different allocations simultaneously regardless of whether they use the same <code>VkDeviceMemory</code> block. They way it's implemented is that the library always maps entire memory block, not just region of the allocation. For further details, see description of <a class="el" href="vk__mem__alloc_8h.html#ad5bd1243512d099706de88168992f069" title="Maps memory represented by given allocation and returns pointer to it. ">vmaMapMemory()</a> function. Example:</p>
<div class="fragment"><div class="line"><span class="comment">// Having these objects initialized:</span></div><div class="line"></div><div class="line"><span class="keyword">struct </span>ConstantBuffer</div><div class="line">{</div><div class="line"> ...</div><div class="line">};</div><div class="line">ConstantBuffer constantBufferData;</div><div class="line"></div><div class="line">VmaAllocator allocator;</div><div class="line">VmaBuffer constantBuffer;</div><div class="line">VmaAllocation constantBufferAllocation;</div><div class="line"></div><div class="line"><span class="comment">// You can map and fill your buffer using following code:</span></div><div class="line"></div><div class="line"><span class="keywordtype">void</span>* mappedData;</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#ad5bd1243512d099706de88168992f069">vmaMapMemory</a>(allocator, constantBufferAllocation, &amp;mappedData);</div><div class="line">memcpy(mappedData, &amp;constantBufferData, <span class="keyword">sizeof</span>(constantBufferData));</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#a9bc268595cb33f6ec4d519cfce81ff45">vmaUnmapMemory</a>(allocator, constantBufferAllocation);</div></div><!-- fragment --><h1><a class="anchor" id="memory_mapping_persistently_mapped_memory"></a>
Persistently mapped memory</h1>
<p>If you need to map memory on host, it may happen that two allocations are assigned to the same <code>VkDeviceMemory</code> block, so if you map them both at the same time, it will cause error because mapping single memory block multiple times is illegal in Vulkan.</p>
<p>TODO update this...</p>
<p>It is safer, more convenient and more efficient to use special feature designed for that: persistently mapped memory. Allocations made with <code>VMA_ALLOCATION_CREATE_MAPPED_BIT</code> flag set in <a class="el" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b" title="Use VmaAllocationCreateFlagBits enum. ">VmaAllocationCreateInfo::flags</a> are returned from device memory blocks that stay mapped all the time, so you can just access CPU pointer to it. <a class="el" href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2" title="Pointer to the beginning of this allocation as mapped data. ">VmaAllocationInfo::pMappedData</a> pointer is already offseted to the beginning of particular allocation. Example:</p>
<div class="fragment"><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_TRANSFER_SRC_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#aa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5">VMA_MEMORY_USAGE_CPU_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#ad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a>;</div><div class="line"></div><div class="line">VkBuffer buf;</div><div class="line">VmaAllocation alloc;</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#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &amp;bufCreateInfo, &amp;allocCreateInfo, &amp;buf, &amp;alloc, &amp;allocInfo);</div><div class="line"></div><div class="line"><span class="comment">// Buffer is immediately mapped. You can access its memory.</span></div><div class="line">memcpy(allocInfo.<a class="code" href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2">pMappedData</a>, myData, 1024);</div></div><!-- fragment --><p>Memory in Vulkan doesn't need to be unmapped before using it e.g. for transfers, but if you are not sure whether it's <code>HOST_COHERENT</code> (here is surely is because it's created with <code>VMA_MEMORY_USAGE_CPU_ONLY</code>), you should check it. If it's not, you should call <code>vkInvalidateMappedMemoryRanges()</code> before reading and <code>vkFlushMappedMemoryRanges()</code> after writing to mapped memory on CPU. Example:</p>
<div class="fragment"><div class="line">VkMemoryPropertyFlags memFlags;</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#a8701444752eb5de4464adb5a2b514bca">vmaGetMemoryTypeProperties</a>(allocator, allocInfo.<a class="code" href="struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5">memoryType</a>, &amp;memFlags);</div><div class="line"><span class="keywordflow">if</span>((memFlags &amp; VK_MEMORY_PROPERTY_HOST_COHERENT_BIT) == 0)</div><div class="line">{</div><div class="line"> VkMappedMemoryRange memRange = { VK_STRUCTURE_TYPE_MAPPED_MEMORY_RANGE };</div><div class="line"> memRange.memory = allocInfo.<a class="code" href="struct_vma_allocation_info.html#ae0bfb7dfdf79a76ffefc9a94677a2f67">deviceMemory</a>;</div><div class="line"> memRange.offset = allocInfo.<a class="code" href="struct_vma_allocation_info.html#a4a3c732388dbdc7a23f9365b00825268">offset</a>;</div><div class="line"> memRange.size = allocInfo.<a class="code" href="struct_vma_allocation_info.html#aac76d113a6a5ccbb09fea00fb25fd18f">size</a>;</div><div class="line"> vkFlushMappedMemoryRanges(device, 1, &amp;memRange);</div><div class="line">}</div></div><!-- fragment --><h1><a class="anchor" id="amd_perf_note"></a>
Note on performance</h1>
<p>There is a situation that you should be careful about. It happens only if all of following conditions are met:</p>
<ol type="1">
<li>You use AMD GPU.</li>
<li>You use the memory type that is both <code>DEVICE_LOCAL</code> and <code>HOST_VISIBLE</code> (used when you specify <code>VMA_MEMORY_USAGE_CPU_TO_GPU</code>).</li>
<li>Operating system is Windows 7 or 8.x (Windows 10 is not affected because it uses WDDM2).</li>
</ol>
<p>Then whenever a <code>VkDeviceMemory</code> block allocated from this memory type is mapped for the time of any call to <code>vkQueueSubmit()</code> or <code>vkQueuePresentKHR()</code>, this block is migrated by WDDM to system RAM, which degrades performance. It doesn't matter if that particular memory block is actually used by the command buffer being submitted.</p>
<p>To avoid this problem, either make sure to unmap all allocations made from this memory type before your Submit and Present, or use <code>VMA_MEMORY_USAGE_GPU_ONLY</code> and transfer from a staging buffer in <code>VMA_MEMORY_USAGE_CPU_ONLY</code>, which can safely stay mapped all the time. </p>
<p>Kepping your memory persistently mapped is generally OK in Vulkan. You don't need to unmap it before using its data on the GPU. The library provides a special feature designed for that: Allocations made with <code>VMA_ALLOCATION_CREATE_MAPPED_BIT</code> flag set in <a class="el" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b" title="Use VmaAllocationCreateFlagBits enum. ">VmaAllocationCreateInfo::flags</a> stay mapped all the time, so you can just access CPU pointer to it any time without a need to call any "map" or "unmap" function. Example:</p>
<div class="fragment"><div class="line">VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };</div><div class="line">bufCreateInfo.size = <span class="keyword">sizeof</span>(ConstantBuffer);</div><div class="line">bufCreateInfo.usage = VK_BUFFER_USAGE_TRANSFER_SRC_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#aa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5">VMA_MEMORY_USAGE_CPU_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#ad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a>;</div><div class="line"></div><div class="line">VkBuffer buf;</div><div class="line">VmaAllocation alloc;</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#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &amp;bufCreateInfo, &amp;allocCreateInfo, &amp;buf, &amp;alloc, &amp;allocInfo);</div><div class="line"></div><div class="line"><span class="comment">// Buffer is already mapped. You can access its memory.</span></div><div class="line">memcpy(allocInfo.<a class="code" href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2">pMappedData</a>, &amp;constantBufferData, <span class="keyword">sizeof</span>(constantBufferData));</div></div><!-- fragment --><p>There are some exceptions though, when you should consider mapping memory only for a short period of time:</p>
<ul>
<li>When operating system is Windows 7 or 8.x (Windows 10 is not affected because it uses WDDM2), device is discrete AMD GPU, and memory type is the special 256 MiB pool of <code>DEVICE_LOCAL + HOST_VISIBLE</code> memory (selected when you use <code>VMA_MEMORY_USAGE_CPU_TO_GPU</code>), then whenever a memory block allocated from this memory type stays mapped for the time of any call to <code>vkQueueSubmit()</code> or <code>vkQueuePresentKHR()</code>, this block is migrated by WDDM to system RAM, which degrades performance. It doesn't matter if that particular memory block is actually used by the command buffer being submitted.</li>
<li>Keeping many large memory blocks mapped may impact performance or stability of some debugging tools.</li>
</ul>
<h1><a class="anchor" id="memory_mapping_cache_control"></a>
Cache control</h1>
<p>Memory in Vulkan doesn't need to be unmapped before using it on GPU, but unless a memory types has <code>VK_MEMORY_PROPERTY_HOST_COHERENT_BIT</code> flag set, you need to manually invalidate cache before reading of mapped pointer using function <code>vkvkInvalidateMappedMemoryRanges()</code> and flush cache after writing to mapped pointer using function <code>vkFlushMappedMemoryRanges()</code>. Example:</p>
<div class="fragment"><div class="line">memcpy(allocInfo.<a class="code" href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2">pMappedData</a>, &amp;constantBufferData, <span class="keyword">sizeof</span>(constantBufferData));</div><div class="line"></div><div class="line">VkMemoryPropertyFlags memFlags;</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#a8701444752eb5de4464adb5a2b514bca">vmaGetMemoryTypeProperties</a>(allocator, allocInfo.<a class="code" href="struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5">memoryType</a>, &amp;memFlags);</div><div class="line"><span class="keywordflow">if</span>((memFlags &amp; VK_MEMORY_PROPERTY_HOST_COHERENT_BIT) == 0)</div><div class="line">{</div><div class="line"> VkMappedMemoryRange memRange = { VK_STRUCTURE_TYPE_MAPPED_MEMORY_RANGE };</div><div class="line"> memRange.memory = allocInfo.<a class="code" href="struct_vma_allocation_info.html#ae0bfb7dfdf79a76ffefc9a94677a2f67">deviceMemory</a>;</div><div class="line"> memRange.offset = allocInfo.<a class="code" href="struct_vma_allocation_info.html#a4a3c732388dbdc7a23f9365b00825268">offset</a>;</div><div class="line"> memRange.size = allocInfo.<a class="code" href="struct_vma_allocation_info.html#aac76d113a6a5ccbb09fea00fb25fd18f">size</a>;</div><div class="line"> vkFlushMappedMemoryRanges(device, 1, &amp;memRange);</div><div class="line">}</div></div><!-- fragment --><p>Please note that memory allocated with <code>VMA_MEMORY_USAGE_CPU_ONLY</code> is guaranteed to be host coherent.</p>
<p>Also, Windows drivers from all 3 PC GPU vendors (AMD, Intel, NVIDIA) currently provide <code>VK_MEMORY_PROPERTY_HOST_COHERENT_BIT</code> flag on all memory types that are <code>VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT</code>, so on this platform you may not need to bother. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>

4
docs/html/struct_vma_allocator_create_info.html
View File

@ -74,7 +74,7 @@ $(function() {
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-attribs"></a>
Public Attributes</h2></td></tr>
<tr class="memitem:a392ea2ecbaff93f91a7c49f735ad4346"><td class="memItemLeft" align="right" valign="top"><a class="el" href="vk__mem__alloc_8h.html#acfe6863e160722c2c1bbcf7573fddc4d">VmaAllocatorCreateFlags</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_vma_allocator_create_info.html#a392ea2ecbaff93f91a7c49f735ad4346">flags</a></td></tr>
<tr class="memdesc:a392ea2ecbaff93f91a7c49f735ad4346"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flags for created allocator. Use VmaAllocatorCreateFlagBits enum. <a href="#a392ea2ecbaff93f91a7c49f735ad4346">More...</a><br /></td></tr>
<tr class="memdesc:a392ea2ecbaff93f91a7c49f735ad4346"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flags for created allocator. Use <a class="el" href="vk__mem__alloc_8h.html#a4ddf381b6ce795bdfbc6c614640b9915" title="Flags for created VmaAllocator. ">VmaAllocatorCreateFlagBits</a> enum. <a href="#a392ea2ecbaff93f91a7c49f735ad4346">More...</a><br /></td></tr>
<tr class="separator:a392ea2ecbaff93f91a7c49f735ad4346"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a08230f04ae6ccf8a78150a9e829a7156"><td class="memItemLeft" align="right" valign="top">VkPhysicalDevice&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_vma_allocator_create_info.html#a08230f04ae6ccf8a78150a9e829a7156">physicalDevice</a></td></tr>
<tr class="memdesc:a08230f04ae6ccf8a78150a9e829a7156"><td class="mdescLeft">&#160;</td><td class="mdescRight">Vulkan physical device. <a href="#a08230f04ae6ccf8a78150a9e829a7156">More...</a><br /></td></tr>
@ -133,7 +133,7 @@ Public Attributes</h2></td></tr>
</table>
</div><div class="memdoc">
<p>Flags for created allocator. Use VmaAllocatorCreateFlagBits enum. </p>
<p>Flags for created allocator. Use <a class="el" href="vk__mem__alloc_8h.html#a4ddf381b6ce795bdfbc6c614640b9915" title="Flags for created VmaAllocator. ">VmaAllocatorCreateFlagBits</a> enum. </p>
</div>
</div>

4
docs/html/struct_vma_pool_create_info.html
View File

@ -77,7 +77,7 @@ Public Attributes</h2></td></tr>
<tr class="memdesc:a596fa76b685d3f1f688f84a709a5b319"><td class="mdescLeft">&#160;</td><td class="mdescRight">Vulkan memory type index to allocate this pool from. <a href="#a596fa76b685d3f1f688f84a709a5b319">More...</a><br /></td></tr>
<tr class="separator:a596fa76b685d3f1f688f84a709a5b319"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a8405139f63d078340ae74513a59f5446"><td class="memItemLeft" align="right" valign="top"><a class="el" href="vk__mem__alloc_8h.html#a2770e325ea42e087c1b91fdf46d0292a">VmaPoolCreateFlags</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_vma_pool_create_info.html#a8405139f63d078340ae74513a59f5446">flags</a></td></tr>
<tr class="memdesc:a8405139f63d078340ae74513a59f5446"><td class="mdescLeft">&#160;</td><td class="mdescRight">Use combination of <code>VmaPoolCreateFlagBits</code>. <a href="#a8405139f63d078340ae74513a59f5446">More...</a><br /></td></tr>
<tr class="memdesc:a8405139f63d078340ae74513a59f5446"><td class="mdescLeft">&#160;</td><td class="mdescRight">Use combination of <a class="el" href="vk__mem__alloc_8h.html#a8f93195158e0e2ac80ca352064e71c1f" title="Flags to be passed as VmaPoolCreateInfo::flags. ">VmaPoolCreateFlagBits</a>. <a href="#a8405139f63d078340ae74513a59f5446">More...</a><br /></td></tr>
<tr class="separator:a8405139f63d078340ae74513a59f5446"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aa4265160536cdb9be821b7686c16c676"><td class="memItemLeft" align="right" valign="top">VkDeviceSize&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_vma_pool_create_info.html#aa4265160536cdb9be821b7686c16c676">blockSize</a></td></tr>
<tr class="memdesc:aa4265160536cdb9be821b7686c16c676"><td class="mdescLeft">&#160;</td><td class="mdescRight">Size of a single <code>VkDeviceMemory</code> block to be allocated as part of this pool, in bytes. <a href="#aa4265160536cdb9be821b7686c16c676">More...</a><br /></td></tr>
@ -124,7 +124,7 @@ Public Attributes</h2></td></tr>
</table>
</div><div class="memdoc">
<p>Use combination of <code>VmaPoolCreateFlagBits</code>. </p>
<p>Use combination of <a class="el" href="vk__mem__alloc_8h.html#a8f93195158e0e2ac80ca352064e71c1f" title="Flags to be passed as VmaPoolCreateInfo::flags. ">VmaPoolCreateFlagBits</a>. </p>
</div>
</div>

8
docs/html/vk__mem__alloc_8h.html
View File

@ -711,7 +711,7 @@ Functions</h2></td></tr>
<table class="fieldtable">
<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305ccaf50d27e34e0925cf3a63db8c839121dd"></a>VMA_MEMORY_USAGE_UNKNOWN&#160;</td><td class="fielddoc"><p>No intended memory usage specified. Use other members of <a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> to specify your requirements. </p>
</td></tr>
<tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305ccac6b5dc1432d88647aa4cd456246eadf7"></a>VMA_MEMORY_USAGE_GPU_ONLY&#160;</td><td class="fielddoc"><p>Memory will be used on device only, so fast access from the device is preferred. It usually means device-local GPU (video) memory. No need to be mappable on host. It is roughly equivalent of D3D12_HEAP_TYPE_DEFAULT.</p>
<tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305ccac6b5dc1432d88647aa4cd456246eadf7"></a>VMA_MEMORY_USAGE_GPU_ONLY&#160;</td><td class="fielddoc"><p>Memory will be used on device only, so fast access from the device is preferred. It usually means device-local GPU (video) memory. No need to be mappable on host. It is roughly equivalent of <code>D3D12_HEAP_TYPE_DEFAULT</code>.</p>
<p>Usage:</p>
<ul>
<li>Resources written and read by device, e.g. images used as attachments.</li>
@ -719,17 +719,17 @@ Functions</h2></td></tr>
</ul>
<p>Allocation may still end up in <code>HOST_VISIBLE</code> memory on some implementations. In such case, you are free to map it. You can use <code>VMA_ALLOCATION_CREATE_MAPPED_BIT</code> with this usage type. </p>
</td></tr>
<tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5"></a>VMA_MEMORY_USAGE_CPU_ONLY&#160;</td><td class="fielddoc"><p>Memory will be mappable on host. It usually means CPU (system) memory. Resources created in this pool are still accessible to the device, but access to them can be slower. Guarantees to be <code>HOST_VISIBLE</code> and <code>HOST_COHERENT</code>. CPU read may be uncached. It is roughly equivalent of D3D12_HEAP_TYPE_UPLOAD.</p>
<tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5"></a>VMA_MEMORY_USAGE_CPU_ONLY&#160;</td><td class="fielddoc"><p>Memory will be mappable on host. It usually means CPU (system) memory. Resources created in this pool may still be accessible to the device, but access to them can be slower. Guarantees to be <code>HOST_VISIBLE</code> and <code>HOST_COHERENT</code>. CPU read may be uncached. It is roughly equivalent of <code>D3D12_HEAP_TYPE_UPLOAD</code>.</p>
<p>Usage: Staging copy of resources used as transfer source. </p>
</td></tr>
<tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca9066b52c5a7079bb74a69aaf8b92ff67"></a>VMA_MEMORY_USAGE_CPU_TO_GPU&#160;</td><td class="fielddoc"><p>Memory that is both mappable on host (guarantees to be <code>HOST_VISIBLE</code>) and preferably fast to access by GPU. CPU reads may be uncached and very slow.</p>
<p>Usage: Resources written frequently by host (dynamic), read by device. E.g. textures, vertex buffers, uniform buffers updated every frame or every draw call. </p>
</td></tr>
<tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca7b586d2fdaf82a463b58f581ed72be27"></a>VMA_MEMORY_USAGE_GPU_TO_CPU&#160;</td><td class="fielddoc"><p>Memory mappable on host (guarantees to be <code>HOST_VISIBLE</code>) and cached. It is roughly equivalent of D3D12_HEAP_TYPE_READBACK.</p>
<tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca7b586d2fdaf82a463b58f581ed72be27"></a>VMA_MEMORY_USAGE_GPU_TO_CPU&#160;</td><td class="fielddoc"><p>Memory mappable on host (guarantees to be <code>HOST_VISIBLE</code>) and cached. It is roughly equivalent of <code>D3D12_HEAP_TYPE_READBACK</code>.</p>
<p>Usage:</p>
<ul>
<li>Resources written by device, read by host - results of some computations, e.g. screen capture, average scene luminance for HDR tone mapping.</li>
<li>Any resources read on host, e.g. CPU-side copy of vertex buffer used as source of transfer, but also used for collision detection. </li>
<li>Any resources read or accessed randomly on host, e.g. CPU-side copy of vertex buffer used as source of transfer, but also used for collision detection. </li>
</ul>
</td></tr>
<tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca091e69437ef693e8d0d287f1c719ba6e"></a>VMA_MEMORY_USAGE_MAX_ENUM&#160;</td><td class="fielddoc"></td></tr>

218
docs/html/vk__mem__alloc_8h_source.html
View File

File diff suppressed because one or more lines are too long

137
src/vk_mem_alloc.h
View File

@ -155,8 +155,9 @@ It is valid, although not very useful.
\section choosing_memory_type_usage Usage
The easiest way to specify memory requirements is to fill member
VmaAllocationCreateInfo::usage using one of the values of enum `VmaMemoryUsage`.
VmaAllocationCreateInfo::usage using one of the values of enum #VmaMemoryUsage.
It defines high level, common usage types.
For more details, see description of this enum.
For example, if you want to create a uniform buffer that will be filled using
transfer only once or infrequently and used for rendering every frame, you can
@ -237,26 +238,62 @@ that pool. For further details, see \ref custom_memory_pools.
\page memory_mapping Memory mapping
\section persistently_mapped_memory Persistently mapped memory
To "map memory" in Vulkan means to obtain a CPU pointer to `VkDeviceMemory`,
to be able to read from it or write to it in CPU code.
Mapping is possible only of memory allocated from a memory type that has
`VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT` flag.
Functions `vkMapMemory()`, `vkUnmapMemory()` are designed for this purpose.
You can use them directly with memory allocated by this library,
but it is not recommended because of following issue:
Mapping the same `VkDeviceMemory` block multiple times is illegal - only one mapping at a time is allowed.
This includes mapping disjoint regions. Mapping is not reference-counted internally by Vulkan.
Because of this, Vulkan Memory Allocator provides following facilities:
If you need to map memory on host, it may happen that two allocations are
assigned to the same `VkDeviceMemory` block, so if you map them both at the same
time, it will cause error because mapping single memory block multiple times is
illegal in Vulkan.
\section memory_mapping_mapping_functions Mapping functions
TODO update this...
The library provides following functions for mapping of a specific `VmaAllocation`: vmaMapMemory(), vmaUnmapMemory().
They are safer and more convenient to use than standard Vulkan functions.
You can map an allocation multiple times simultaneously - mapping is reference-counted internally.
You can also map different allocations simultaneously regardless of whether they use the same `VkDeviceMemory` block.
They way it's implemented is that the library always maps entire memory block, not just region of the allocation.
For further details, see description of vmaMapMemory() function.
Example:
It is safer, more convenient and more efficient to use special feature designed
for that: persistently mapped memory. Allocations made with
`VMA_ALLOCATION_CREATE_MAPPED_BIT` flag set in
VmaAllocationCreateInfo::flags are returned from device memory
blocks that stay mapped all the time, so you can just access CPU pointer to it.
VmaAllocationInfo::pMappedData pointer is already offseted to the beginning of
particular allocation. Example:
\code
// Having these objects initialized:
struct ConstantBuffer
{
...
};
ConstantBuffer constantBufferData;
VmaAllocator allocator;
VmaBuffer constantBuffer;
VmaAllocation constantBufferAllocation;
// You can map and fill your buffer using following code:
void* mappedData;
vmaMapMemory(allocator, constantBufferAllocation, &mappedData);
memcpy(mappedData, &constantBufferData, sizeof(constantBufferData));
vmaUnmapMemory(allocator, constantBufferAllocation);
\endcode
\section memory_mapping_persistently_mapped_memory Persistently mapped memory
Kepping your memory persistently mapped is generally OK in Vulkan.
You don't need to unmap it before using its data on the GPU.
The library provides a special feature designed for that:
Allocations made with `VMA_ALLOCATION_CREATE_MAPPED_BIT` flag set in
VmaAllocationCreateInfo::flags stay mapped all the time,
so you can just access CPU pointer to it any time
without a need to call any "map" or "unmap" function.
Example:
\code
VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
bufCreateInfo.size = 1024;
bufCreateInfo.size = sizeof(ConstantBuffer);
bufCreateInfo.usage = VK_BUFFER_USAGE_TRANSFER_SRC_BIT;
VmaAllocationCreateInfo allocCreateInfo = {};
@ -268,17 +305,36 @@ VmaAllocation alloc;
VmaAllocationInfo allocInfo;
vmaCreateBuffer(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);
// Buffer is immediately mapped. You can access its memory.
memcpy(allocInfo.pMappedData, myData, 1024);
// Buffer is already mapped. You can access its memory.
memcpy(allocInfo.pMappedData, &constantBufferData, sizeof(constantBufferData));
\endcode
Memory in Vulkan doesn't need to be unmapped before using it e.g. for transfers,
but if you are not sure whether it's `HOST_COHERENT` (here is surely is because
it's created with `VMA_MEMORY_USAGE_CPU_ONLY`), you should check it. If it's
not, you should call `vkInvalidateMappedMemoryRanges()` before reading and
`vkFlushMappedMemoryRanges()` after writing to mapped memory on CPU. Example:
There are some exceptions though, when you should consider mapping memory only for a short period of time:
- When operating system is Windows 7 or 8.x (Windows 10 is not affected because it uses WDDM2),
device is discrete AMD GPU,
and memory type is the special 256 MiB pool of `DEVICE_LOCAL + HOST_VISIBLE` memory
(selected when you use `VMA_MEMORY_USAGE_CPU_TO_GPU`),
then whenever a memory block allocated from this memory type stays mapped
for the time of any call to `vkQueueSubmit()` or `vkQueuePresentKHR()`, this
block is migrated by WDDM to system RAM, which degrades performance. It doesn't
matter if that particular memory block is actually used by the command buffer
being submitted.
- Keeping many large memory blocks mapped may impact performance or stability of some debugging tools.
\section memory_mapping_cache_control Cache control
Memory in Vulkan doesn't need to be unmapped before using it on GPU,
but unless a memory types has `VK_MEMORY_PROPERTY_HOST_COHERENT_BIT` flag set,
you need to manually invalidate cache before reading of mapped pointer
using function `vkvkInvalidateMappedMemoryRanges()`
and flush cache after writing to mapped pointer
using function `vkFlushMappedMemoryRanges()`.
Example:
\code
memcpy(allocInfo.pMappedData, &constantBufferData, sizeof(constantBufferData));
VkMemoryPropertyFlags memFlags;
vmaGetMemoryTypeProperties(allocator, allocInfo.memoryType, &memFlags);
if((memFlags & VK_MEMORY_PROPERTY_HOST_COHERENT_BIT) == 0)
@ -291,27 +347,12 @@ if((memFlags & VK_MEMORY_PROPERTY_HOST_COHERENT_BIT) == 0)
}
\endcode
\section amd_perf_note Note on performance
Please note that memory allocated with `VMA_MEMORY_USAGE_CPU_ONLY` is guaranteed to be host coherent.
There is a situation that you should be careful about. It happens only if all of
following conditions are met:
Also, Windows drivers from all 3 PC GPU vendors (AMD, Intel, NVIDIA)
currently provide `VK_MEMORY_PROPERTY_HOST_COHERENT_BIT` flag on all memory types that are
`VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT`, so on this platform you may not need to bother.
-# You use AMD GPU.
-# You use the memory type that is both `DEVICE_LOCAL` and `HOST_VISIBLE`
(used when you specify `VMA_MEMORY_USAGE_CPU_TO_GPU`).
-# Operating system is Windows 7 or 8.x (Windows 10 is not affected because it
uses WDDM2).
Then whenever a `VkDeviceMemory` block allocated from this memory type is mapped
for the time of any call to `vkQueueSubmit()` or `vkQueuePresentKHR()`, this
block is migrated by WDDM to system RAM, which degrades performance. It doesn't
matter if that particular memory block is actually used by the command buffer
being submitted.
To avoid this problem, either make sure to unmap all allocations made from this
memory type before your Submit and Present, or use `VMA_MEMORY_USAGE_GPU_ONLY`
and transfer from a staging buffer in `VMA_MEMORY_USAGE_CPU_ONLY`, which can
safely stay mapped all the time.
\page custom_memory_pools Custom memory pools
@ -824,7 +865,7 @@ typedef struct VmaVulkanFunctions {
/// Description of a Allocator to be created.
typedef struct VmaAllocatorCreateInfo
{
/// Flags for created allocator. Use VmaAllocatorCreateFlagBits enum.
/// Flags for created allocator. Use #VmaAllocatorCreateFlagBits enum.
VmaAllocatorCreateFlags flags;
/// Vulkan physical device.
/** It must be valid throughout whole lifetime of created allocator. */
@ -1001,7 +1042,7 @@ typedef enum VmaMemoryUsage
/** Memory will be used on device only, so fast access from the device is preferred.
It usually means device-local GPU (video) memory.
No need to be mappable on host.
It is roughly equivalent of D3D12_HEAP_TYPE_DEFAULT.
It is roughly equivalent of `D3D12_HEAP_TYPE_DEFAULT`.
Usage:
@ -1017,10 +1058,10 @@ typedef enum VmaMemoryUsage
VMA_MEMORY_USAGE_GPU_ONLY = 1,
/** Memory will be mappable on host.
It usually means CPU (system) memory.
Resources created in this pool are still accessible to the device, but access to them can be slower.
Resources created in this pool may still be accessible to the device, but access to them can be slower.
Guarantees to be `HOST_VISIBLE` and `HOST_COHERENT`.
CPU read may be uncached.
It is roughly equivalent of D3D12_HEAP_TYPE_UPLOAD.
It is roughly equivalent of `D3D12_HEAP_TYPE_UPLOAD`.
Usage: Staging copy of resources used as transfer source.
*/
@ -1033,12 +1074,12 @@ typedef enum VmaMemoryUsage
*/
VMA_MEMORY_USAGE_CPU_TO_GPU = 3,
/** Memory mappable on host (guarantees to be `HOST_VISIBLE`) and cached.
It is roughly equivalent of D3D12_HEAP_TYPE_READBACK.
It is roughly equivalent of `D3D12_HEAP_TYPE_READBACK`.
Usage:
- Resources written by device, read by host - results of some computations, e.g. screen capture, average scene luminance for HDR tone mapping.
- Any resources read on host, e.g. CPU-side copy of vertex buffer used as source of transfer, but also used for collision detection.
- Any resources read or accessed randomly on host, e.g. CPU-side copy of vertex buffer used as source of transfer, but also used for collision detection.
*/
VMA_MEMORY_USAGE_GPU_TO_CPU = 4,
VMA_MEMORY_USAGE_MAX_ENUM = 0x7FFFFFFF
@ -1207,7 +1248,7 @@ typedef struct VmaPoolCreateInfo {
/** \brief Vulkan memory type index to allocate this pool from.
*/
uint32_t memoryTypeIndex;
/** \brief Use combination of `VmaPoolCreateFlagBits`.
/** \brief Use combination of #VmaPoolCreateFlagBits.
*/
VmaPoolCreateFlags flags;
/** \brief Size of a single `VkDeviceMemory` block to be allocated as part of this pool, in bytes.