| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US"> |
| <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.14.0"/> |
| <meta name="viewport" content="width=device-width, initial-scale=1"/> |
| <title>Vulkan Memory Allocator: Recommended usage patterns</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> |
| <link href="doxygen.css" rel="stylesheet" type="text/css" /> |
| </head> |
| <body> |
| <div id="top"><!-- do not remove this div, it is closed by doxygen! --> |
| <div id="titlearea"> |
| <table cellspacing="0" cellpadding="0"> |
| <tbody> |
| <tr id="projectrow"> |
| <td id="projectalign"> |
| <div id="projectname">Vulkan Memory Allocator |
| </div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <!-- end header part --> |
| <!-- Generated by Doxygen 1.14.0 --> |
| <script type="text/javascript"> |
| var searchBox = new SearchBox("searchBox", "search/",'.html'); |
| </script> |
| <script type="text/javascript"> |
| $(function() { codefold.init(); }); |
| </script> |
| <script type="text/javascript" src="menudata.js"></script> |
| <script type="text/javascript" src="menu.js"></script> |
| <script type="text/javascript"> |
| $(function() { |
| initMenu('',true,false,'search.php','Search',false); |
| $(function() { init_search(); }); |
| }); |
| </script> |
| <div id="main-nav"></div> |
| <!-- window showing the filter options --> |
| <div id="MSearchSelectWindow" |
| onmouseover="return searchBox.OnSearchSelectShow()" |
| onmouseout="return searchBox.OnSearchSelectHide()" |
| onkeydown="return searchBox.OnSearchSelectKey(event)"> |
| </div> |
| |
| <!-- iframe showing the search results (closed by default) --> |
| <div id="MSearchResultsWindow"> |
| <div id="MSearchResults"> |
| <div class="SRPage"> |
| <div id="SRIndex"> |
| <div id="SRResults"></div> |
| <div class="SRStatus" id="Loading">Loading...</div> |
| <div class="SRStatus" id="Searching">Searching...</div> |
| <div class="SRStatus" id="NoMatches">No Matches</div> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <div id="nav-path" class="navpath"> |
| <ul> |
| <li class="navelem"><a href="index.html">Vulkan Memory Allocator</a></li> </ul> |
| </div> |
| </div><!-- top --> |
| <div id="doc-content"> |
| <div><div class="header"> |
| <div class="headertitle"><div class="title">Recommended usage patterns </div></div> |
| </div><!--header--> |
| <div class="contents"> |
| <div class="textblock"><p>Vulkan gives great flexibility in memory allocation. This chapter shows the most common patterns.</p> |
| <p>See also slides from talk: <a href="https://www.gdcvault.com/play/1025458/Advanced-Graphics-Techniques-Tutorial-New">Sawicki, Adam. Advanced Graphics Techniques Tutorial: Memory management in Vulkan and DX12. Game Developers Conference, 2018</a></p> |
| <h1 class="doxsection"><a class="anchor" id="usage_patterns_gpu_only"></a> |
| GPU-only resource</h1> |
| <p><b>When:</b> Any resources that you frequently write and read on GPU, e.g. images used as color attachments (aka "render targets"), depth-stencil attachments, images/buffers used as storage image/buffer (aka "Unordered Access View (UAV)").</p> |
| <p><b>What to do:</b> Let the library select the optimal memory type, which will likely have <span class="tt">VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT</span>.</p> |
| <div class="fragment"><div class="line">VkImageCreateInfo imgCreateInfo = { VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO };</div> |
| <div class="line">imgCreateInfo.imageType = VK_IMAGE_TYPE_2D;</div> |
| <div class="line">imgCreateInfo.extent.width = 3840;</div> |
| <div class="line">imgCreateInfo.extent.height = 2160;</div> |
| <div class="line">imgCreateInfo.extent.depth = 1;</div> |
| <div class="line">imgCreateInfo.mipLevels = 1;</div> |
| <div class="line">imgCreateInfo.arrayLayers = 1;</div> |
| <div class="line">imgCreateInfo.format = VK_FORMAT_R8G8B8A8_UNORM;</div> |
| <div class="line">imgCreateInfo.tiling = VK_IMAGE_TILING_OPTIMAL;</div> |
| <div class="line">imgCreateInfo.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;</div> |
| <div class="line">imgCreateInfo.usage = VK_IMAGE_USAGE_SAMPLED_BIT | VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;</div> |
| <div class="line">imgCreateInfo.samples = VK_SAMPLE_COUNT_1_BIT;</div> |
| <div class="line"> </div> |
| <div class="line"><a class="code hl_struct" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocCreateInfo = {};</div> |
| <div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a>;</div> |
| <div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>;</div> |
| <div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#a983d39e1a2e63649d78a960aa2fdd0f7">priority</a> = 1.0f;</div> |
| <div class="line"> </div> |
| <div class="line">VkImage img;</div> |
| <div class="line"><a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> alloc;</div> |
| <div class="line"><a class="code hl_function" href="group__group__alloc.html#ga02a94f25679275851a53e82eacbcfc73">vmaCreateImage</a>(allocator, &imgCreateInfo, &allocCreateInfo, &img, &alloc, <span class="keyword">nullptr</span>);</div> |
| <div class="ttc" id="agroup__group__alloc_html_ga02a94f25679275851a53e82eacbcfc73"><div class="ttname"><a href="group__group__alloc.html#ga02a94f25679275851a53e82eacbcfc73">vmaCreateImage</a></div><div class="ttdeci">VkResult vmaCreateImage(VmaAllocator allocator, const VkImageCreateInfo *pImageCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkImage *pImage, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)</div><div class="ttdoc">Function similar to vmaCreateBuffer() but for images.</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:551</div></div> |
| <div class="ttc" id="agroup__group__alloc_html_ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f"><div class="ttname"><a href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</div><div class="ttdoc">Set this flag if the allocation should have its own memory block.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:590</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:1292</div></div> |
| <div class="ttc" id="astruct_vma_allocation_create_info_html_a983d39e1a2e63649d78a960aa2fdd0f7"><div class="ttname"><a href="struct_vma_allocation_create_info.html#a983d39e1a2e63649d78a960aa2fdd0f7">VmaAllocationCreateInfo::priority</a></div><div class="ttdeci">float priority</div><div class="ttdoc">A floating-point value between 0 and 1, indicating the priority of the allocation relative to other m...</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1338</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:1300</div></div> |
| <div class="ttc" id="astruct_vma_allocation_create_info_html_add09658ac14fe290ace25470ddd6d41b"><div class="ttname"><a href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">VmaAllocationCreateInfo::flags</a></div><div class="ttdeci">VmaAllocationCreateFlags flags</div><div class="ttdoc">Use VmaAllocationCreateFlagBits enum.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1294</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><!-- fragment --><p><b>Also consider:</b> Consider creating them as dedicated allocations using <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>, especially if they are large or if you plan to destroy and recreate them with different sizes e.g. when display resolution changes. Prefer to create such resources first and all other GPU resources (like textures and vertex buffers) later. When VK_EXT_memory_priority extension is enabled, it is also worth setting high priority to such allocation to decrease chances to be evicted to system memory by the operating system.</p> |
| <h1 class="doxsection"><a class="anchor" id="usage_patterns_staging_copy_upload"></a> |
| Staging copy for upload</h1> |
| <p><b>When:</b> A "staging" buffer than you want to map and fill from CPU code, then use as a source of transfer to some GPU resource.</p> |
| <p><b>What to do:</b> Use flag <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a>. Let the library select the optimal memory type, which will always have <span class="tt">VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT</span>.</p> |
| <div class="fragment"><div class="line">VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };</div> |
| <div class="line">bufCreateInfo.size = 65536;</div> |
| <div class="line">bufCreateInfo.usage = VK_BUFFER_USAGE_TRANSFER_SRC_BIT;</div> |
| <div class="line"> </div> |
| <div class="line"><a class="code hl_struct" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocCreateInfo = {};</div> |
| <div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a>;</div> |
| <div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> |</div> |
| <div class="line"> <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a>;</div> |
| <div class="line"> </div> |
| <div class="line">VkBuffer buf;</div> |
| <div class="line"><a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> alloc;</div> |
| <div class="line"><a class="code hl_struct" href="struct_vma_allocation_info.html">VmaAllocationInfo</a> allocInfo;</div> |
| <div class="line"><a class="code hl_function" href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);</div> |
| <div class="line"> </div> |
| <div class="line">...</div> |
| <div class="line"> </div> |
| <div class="line">memcpy(allocInfo.<a class="code hl_variable" href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2">pMappedData</a>, myData, myDataSize);</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_ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f"><div class="ttname"><a href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATION_CREATE_MAPPED_BIT</div><div class="ttdoc">Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:611</div></div> |
| <div class="ttc" id="agroup__group__alloc_html_ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5"><div class="ttname"><a href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:660</div></div> |
| <div class="ttc" id="astruct_vma_allocation_info_html"><div class="ttname"><a href="struct_vma_allocation_info.html">VmaAllocationInfo</a></div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1411</div></div> |
| <div class="ttc" id="astruct_vma_allocation_info_html_a5eeffbe2d2f30f53370ff14aefbadbe2"><div class="ttname"><a href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2">VmaAllocationInfo::pMappedData</a></div><div class="ttdeci">void * pMappedData</div><div class="ttdoc">Pointer to the beginning of this allocation as mapped data.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1453</div></div> |
| </div><!-- fragment --><p><b>Also consider:</b> You can map the allocation using <a class="el" href="group__group__alloc.html#gad5bd1243512d099706de88168992f069" title="Maps memory represented by given allocation and returns pointer to it.">vmaMapMemory()</a> or you can create it as persistenly mapped using <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f" title="Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.">VMA_ALLOCATION_CREATE_MAPPED_BIT</a>, as in the example above.</p> |
| <h1 class="doxsection"><a class="anchor" id="usage_patterns_readback"></a> |
| Readback</h1> |
| <p><b>When:</b> Buffers for data written by or transferred from the GPU that you want to read back on the CPU, e.g. results of some computations.</p> |
| <p><b>What to do:</b> Use flag <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597add61238d98e20917b9a06c617763f492">VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT</a>. Let the library select the optimal memory type, which will always have <span class="tt">VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT</span> and <span class="tt">VK_MEMORY_PROPERTY_HOST_CACHED_BIT</span>.</p> |
| <div class="fragment"><div class="line">VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };</div> |
| <div class="line">bufCreateInfo.size = 65536;</div> |
| <div class="line">bufCreateInfo.usage = VK_BUFFER_USAGE_TRANSFER_DST_BIT;</div> |
| <div class="line"> </div> |
| <div class="line"><a class="code hl_struct" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocCreateInfo = {};</div> |
| <div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a>;</div> |
| <div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597add61238d98e20917b9a06c617763f492">VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT</a> |</div> |
| <div class="line"> <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a>;</div> |
| <div class="line"> </div> |
| <div class="line">VkBuffer buf;</div> |
| <div class="line"><a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> alloc;</div> |
| <div class="line"><a class="code hl_struct" href="struct_vma_allocation_info.html">VmaAllocationInfo</a> allocInfo;</div> |
| <div class="line"><a class="code hl_function" href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);</div> |
| <div class="line"> </div> |
| <div class="line">...</div> |
| <div class="line"> </div> |
| <div class="line">const <span class="keywordtype">float</span>* downloadedData = (<span class="keyword">const</span> <span class="keywordtype">float</span>*)allocInfo.<a class="code hl_variable" href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2">pMappedData</a>;</div> |
| <div class="ttc" id="agroup__group__alloc_html_ggad9889c10c798b040d59c92f257cae597add61238d98e20917b9a06c617763f492"><div class="ttname"><a href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597add61238d98e20917b9a06c617763f492">VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:672</div></div> |
| </div><!-- fragment --><h1 class="doxsection"><a class="anchor" id="usage_patterns_advanced_data_uploading"></a> |
| Advanced data uploading</h1> |
| <p>For resources that you frequently write on CPU via mapped pointer and frequently read on GPU e.g. as a uniform buffer (also called "dynamic"), multiple options are possible:</p> |
| <ol type="1"> |
| <li>Easiest solution is to have one copy of the resource in <span class="tt">HOST_VISIBLE</span> memory, even if it means system RAM (not <span class="tt">DEVICE_LOCAL</span>) on systems with a discrete graphics card, and make the device reach out to that resource directly.<ul> |
| <li>Reads performed by the device will then go through PCI Express bus. The performance of this access may be limited, but it may be fine depending on the size of this resource (whether it is small enough to quickly end up in GPU cache) and the sparsity of access.</li> |
| </ul> |
| </li> |
| <li>On systems with unified memory (e.g. AMD APU or Intel integrated graphics, mobile chips), a memory type may be available that is both <span class="tt">HOST_VISIBLE</span> (available for mapping) and <span class="tt">DEVICE_LOCAL</span> (fast to access from the GPU). Then, it is likely the best choice for such type of resource.</li> |
| <li>Systems with a discrete graphics card and separate video memory may or may not expose a memory type that is both <span class="tt">HOST_VISIBLE</span> and <span class="tt">DEVICE_LOCAL</span>, also known as Base Address Register (BAR). If they do, it represents a piece of VRAM (or entire VRAM, if ReBAR is enabled in the motherboard BIOS) that is available to CPU for mapping.<ul> |
| <li>Writes performed by the host to that memory go through PCI Express bus. The performance of these writes may be limited, but it may be fine, especially on PCIe 4.0, as long as rules of using uncached and write-combined memory are followed - only sequential writes and no reads.</li> |
| </ul> |
| </li> |
| <li>Finally, you may need or prefer to create a separate copy of the resource in <span class="tt">DEVICE_LOCAL</span> memory, a separate "staging" copy in <span class="tt">HOST_VISIBLE</span> memory and perform an explicit transfer command between them.</li> |
| </ol> |
| <p>Thankfully, VMA offers an aid to create and use such resources in the the way optimal for the current Vulkan device. To help the library make the best choice, use flag <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> together with <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11337f96eacf34c1016c339eac165cad">VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT</a>. It will then prefer a memory type that is both <span class="tt">DEVICE_LOCAL</span> and <span class="tt">HOST_VISIBLE</span> (integrated memory or BAR), but if no such memory type is available or allocation from it fails (PC graphics cards have only 256 MB of BAR by default, unless ReBAR is supported and enabled in BIOS), it will fall back to <span class="tt">DEVICE_LOCAL</span> memory for fast GPU access. It is then up to you to detect that the allocation ended up in a memory type that is not <span class="tt">HOST_VISIBLE</span>, so you need to create another "staging" allocation and perform explicit transfers.</p> |
| <div class="fragment"><div class="line">VkBufferCreateInfo bufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };</div> |
| <div class="line">bufCreateInfo.size = 65536;</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 hl_struct" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocCreateInfo = {};</div> |
| <div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a>;</div> |
| <div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> |</div> |
| <div class="line"> <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11337f96eacf34c1016c339eac165cad">VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT</a> |</div> |
| <div class="line"> <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a>;</div> |
| <div class="line"> </div> |
| <div class="line">VkBuffer buf;</div> |
| <div class="line"><a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> alloc;</div> |
| <div class="line"><a class="code hl_struct" href="struct_vma_allocation_info.html">VmaAllocationInfo</a> allocInfo;</div> |
| <div class="line">VkResult result = <a class="code hl_function" href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &bufCreateInfo, &allocCreateInfo, &buf, &alloc, &allocInfo);</div> |
| <div class="line"><span class="comment">// Check result...</span></div> |
| <div class="line"> </div> |
| <div class="line">VkMemoryPropertyFlags memPropFlags;</div> |
| <div class="line"><a class="code hl_function" href="group__group__alloc.html#ga571e87dd38e552249b56b1b0b982fad1">vmaGetAllocationMemoryProperties</a>(allocator, alloc, &memPropFlags);</div> |
| <div class="line"> </div> |
| <div class="line"><span class="keywordflow">if</span>(memPropFlags & VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT)</div> |
| <div class="line">{</div> |
| <div class="line"> <span class="comment">// The Allocation ended up in a mappable memory.</span></div> |
| <div class="line"> <span class="comment">// Calling vmaCopyMemoryToAllocation() does vmaMapMemory(), memcpy(), vmaUnmapMemory(), and vmaFlushAllocation().</span></div> |
| <div class="line"> result = <a class="code hl_function" href="group__group__alloc.html#ga11731ec58a3a43a22bb925e0780ef405">vmaCopyMemoryToAllocation</a>(allocator, myData, alloc, 0, myDataSize);</div> |
| <div class="line"> <span class="comment">// Check result...</span></div> |
| <div class="line"> </div> |
| <div class="line"> VkBufferMemoryBarrier bufMemBarrier = { VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER };</div> |
| <div class="line"> bufMemBarrier.srcAccessMask = VK_ACCESS_HOST_WRITE_BIT;</div> |
| <div class="line"> bufMemBarrier.dstAccessMask = VK_ACCESS_UNIFORM_READ_BIT;</div> |
| <div class="line"> bufMemBarrier.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;</div> |
| <div class="line"> bufMemBarrier.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;</div> |
| <div class="line"> bufMemBarrier.buffer = buf;</div> |
| <div class="line"> bufMemBarrier.offset = 0;</div> |
| <div class="line"> bufMemBarrier.size = VK_WHOLE_SIZE;</div> |
| <div class="line"> </div> |
| <div class="line"> <span class="comment">// It's important to insert a buffer memory barrier here to ensure writing to the buffer has finished.</span></div> |
| <div class="line"> vkCmdPipelineBarrier(cmdBuf, VK_PIPELINE_STAGE_HOST_BIT, VK_PIPELINE_STAGE_VERTEX_SHADER_BIT,</div> |
| <div class="line"> 0, 0, <span class="keyword">nullptr</span>, 1, &bufMemBarrier, 0, <span class="keyword">nullptr</span>);</div> |
| <div class="line">}</div> |
| <div class="line"><span class="keywordflow">else</span></div> |
| <div class="line">{</div> |
| <div class="line"> <span class="comment">// Allocation ended up in a non-mappable memory - a transfer using a staging buffer is required.</span></div> |
| <div class="line"> VkBufferCreateInfo stagingBufCreateInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };</div> |
| <div class="line"> stagingBufCreateInfo.size = 65536;</div> |
| <div class="line"> stagingBufCreateInfo.usage = VK_BUFFER_USAGE_TRANSFER_SRC_BIT;</div> |
| <div class="line"> </div> |
| <div class="line"> <a class="code hl_struct" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> stagingAllocCreateInfo = {};</div> |
| <div class="line"> stagingAllocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a>;</div> |
| <div class="line"> stagingAllocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> |</div> |
| <div class="line"> <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">VMA_ALLOCATION_CREATE_MAPPED_BIT</a>;</div> |
| <div class="line"> </div> |
| <div class="line"> VkBuffer stagingBuf;</div> |
| <div class="line"> <a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> stagingAlloc;</div> |
| <div class="line"> <a class="code hl_struct" href="struct_vma_allocation_info.html">VmaAllocationInfo</a> stagingAllocInfo;</div> |
| <div class="line"> result = <a class="code hl_function" href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &stagingBufCreateInfo, &stagingAllocCreateInfo,</div> |
| <div class="line"> &stagingBuf, &stagingAlloc, &stagingAllocInfo);</div> |
| <div class="line"> <span class="comment">// Check result...</span></div> |
| <div class="line"> </div> |
| <div class="line"> <span class="comment">// Calling vmaCopyMemoryToAllocation() does vmaMapMemory(), memcpy(), vmaUnmapMemory(), and vmaFlushAllocation().</span></div> |
| <div class="line"> result = <a class="code hl_function" href="group__group__alloc.html#ga11731ec58a3a43a22bb925e0780ef405">vmaCopyMemoryToAllocation</a>(allocator, myData, stagingAlloc, 0, myDataSize);</div> |
| <div class="line"> <span class="comment">// Check result...</span></div> |
| <div class="line"> </div> |
| <div class="line"> VkBufferMemoryBarrier bufMemBarrier = { VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER };</div> |
| <div class="line"> bufMemBarrier.srcAccessMask = VK_ACCESS_HOST_WRITE_BIT;</div> |
| <div class="line"> bufMemBarrier.dstAccessMask = VK_ACCESS_TRANSFER_READ_BIT;</div> |
| <div class="line"> bufMemBarrier.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;</div> |
| <div class="line"> bufMemBarrier.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;</div> |
| <div class="line"> bufMemBarrier.buffer = stagingBuf;</div> |
| <div class="line"> bufMemBarrier.offset = 0;</div> |
| <div class="line"> bufMemBarrier.size = VK_WHOLE_SIZE;</div> |
| <div class="line"> </div> |
| <div class="line"> <span class="comment">// Insert a buffer memory barrier to make sure writing to the staging buffer has finished.</span></div> |
| <div class="line"> vkCmdPipelineBarrier(cmdBuf, VK_PIPELINE_STAGE_HOST_BIT, VK_PIPELINE_STAGE_TRANSFER_BIT,</div> |
| <div class="line"> 0, 0, <span class="keyword">nullptr</span>, 1, &bufMemBarrier, 0, <span class="keyword">nullptr</span>);</div> |
| <div class="line"> </div> |
| <div class="line"> VkBufferCopy bufCopy = {</div> |
| <div class="line"> 0, <span class="comment">// srcOffset</span></div> |
| <div class="line"> 0, <span class="comment">// dstOffset,</span></div> |
| <div class="line"> myDataSize, <span class="comment">// size</span></div> |
| <div class="line"> };</div> |
| <div class="line"> </div> |
| <div class="line"> vkCmdCopyBuffer(cmdBuf, stagingBuf, buf, 1, &bufCopy);</div> |
| <div class="line"> </div> |
| <div class="line"> VkBufferMemoryBarrier bufMemBarrier2 = { VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER };</div> |
| <div class="line"> bufMemBarrier2.srcAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;</div> |
| <div class="line"> bufMemBarrier2.dstAccessMask = VK_ACCESS_UNIFORM_READ_BIT; <span class="comment">// We created a uniform buffer</span></div> |
| <div class="line"> bufMemBarrier2.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;</div> |
| <div class="line"> bufMemBarrier2.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;</div> |
| <div class="line"> bufMemBarrier2.buffer = buf;</div> |
| <div class="line"> bufMemBarrier2.offset = 0;</div> |
| <div class="line"> bufMemBarrier2.size = VK_WHOLE_SIZE;</div> |
| <div class="line"> </div> |
| <div class="line"> <span class="comment">// Make sure copying from staging buffer to the actual buffer has finished by inserting a buffer memory barrier.</span></div> |
| <div class="line"> vkCmdPipelineBarrier(cmdBuf, VK_PIPELINE_STAGE_TRANSFER_BIT, VK_PIPELINE_STAGE_VERTEX_SHADER_BIT,</div> |
| <div class="line"> 0, 0, <span class="keyword">nullptr</span>, 1, &bufMemBarrier2, 0, <span class="keyword">nullptr</span>);</div> |
| <div class="line">}</div> |
| <div class="ttc" id="agroup__group__alloc_html_ga11731ec58a3a43a22bb925e0780ef405"><div class="ttname"><a href="group__group__alloc.html#ga11731ec58a3a43a22bb925e0780ef405">vmaCopyMemoryToAllocation</a></div><div class="ttdeci">VkResult vmaCopyMemoryToAllocation(VmaAllocator allocator, const void *pSrcHostPointer, VmaAllocation dstAllocation, VkDeviceSize dstAllocationLocalOffset, VkDeviceSize size)</div><div class="ttdoc">Maps the allocation temporarily if needed, copies data from specified host pointer to it,...</div></div> |
| <div class="ttc" id="agroup__group__alloc_html_ga571e87dd38e552249b56b1b0b982fad1"><div class="ttname"><a href="group__group__alloc.html#ga571e87dd38e552249b56b1b0b982fad1">vmaGetAllocationMemoryProperties</a></div><div class="ttdeci">void vmaGetAllocationMemoryProperties(VmaAllocator allocator, VmaAllocation allocation, VkMemoryPropertyFlags *pFlags)</div><div class="ttdoc">Given an allocation, returns Property Flags of its memory type.</div></div> |
| <div class="ttc" id="agroup__group__alloc_html_ggad9889c10c798b040d59c92f257cae597a11337f96eacf34c1016c339eac165cad"><div class="ttname"><a href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11337f96eacf34c1016c339eac165cad">VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:684</div></div> |
| </div><!-- fragment --><h1 class="doxsection"><a class="anchor" id="usage_patterns_other_use_cases"></a> |
| Other use cases</h1> |
| <p>Here are some other, less obvious use cases and their recommended settings:</p> |
| <ul> |
| <li>An image that is used only as transfer source and destination, but it should stay on the device, as it is used to temporarily store a copy of some texture, e.g. from the current to the next frame, for temporal antialiasing or other temporal effects.<ul> |
| <li>Use <span class="tt">VkImageCreateInfo::usage = VK_IMAGE_USAGE_TRANSFER_SRC_BIT | VK_IMAGE_USAGE_TRANSFER_DST_BIT</span></li> |
| <li>Use <a class="el" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910" title="Intended usage of memory.">VmaAllocationCreateInfo::usage</a> = <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a></li> |
| </ul> |
| </li> |
| <li>An image that is used only as transfer source and destination, but it should be placed in the system RAM despite it doesn't need to be mapped, because it serves as a "swap" copy to evict least recently used textures from VRAM.<ul> |
| <li>Use <span class="tt">VkImageCreateInfo::usage = VK_IMAGE_USAGE_TRANSFER_SRC_BIT | VK_IMAGE_USAGE_TRANSFER_DST_BIT</span></li> |
| <li>Use <a class="el" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910" title="Intended usage of memory.">VmaAllocationCreateInfo::usage</a> = <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca9b422585242160b8ed3418310ee6664d">VMA_MEMORY_USAGE_AUTO_PREFER_HOST</a>, as VMA needs a hint here to differentiate from the previous case.</li> |
| </ul> |
| </li> |
| <li>A buffer that you want to map and write from the CPU, directly read from the GPU (e.g. as a uniform or vertex buffer), but you have a clear preference to place it in device or host memory due to its large size.<ul> |
| <li>Use <span class="tt">VkBufferCreateInfo::usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT</span></li> |
| <li>Use <a class="el" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910" title="Intended usage of memory.">VmaAllocationCreateInfo::usage</a> = <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305ccae2adb696d6a73c18bb20c23666661327">VMA_MEMORY_USAGE_AUTO_PREFER_DEVICE</a> or <a class="el" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca9b422585242160b8ed3418310ee6664d">VMA_MEMORY_USAGE_AUTO_PREFER_HOST</a></li> |
| <li>Use <a class="el" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b" title="Use VmaAllocationCreateFlagBits enum.">VmaAllocationCreateInfo::flags</a> = <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> </li> |
| </ul> |
| </li> |
| </ul> |
| </div></div><!-- contents --> |
| </div><!-- PageDoc --> |
| <!-- start footer part --> |
| <hr class="footer"/><address class="footer"><small> |
| Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.14.0 |
| </small></address> |
| </div><!-- doc-content --> |
| </body> |
| </html> |
