| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> |
| <meta http-equiv="X-UA-Compatible" content="IE=9"/> |
| <meta name="generator" content="Doxygen 1.8.13"/> |
| <meta name="viewport" content="width=device-width, initial-scale=1"/> |
| <title>Vulkan Memory Allocator: Choosing memory type</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> |
| <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 style="height: 56px;"> |
| <td id="projectalign" style="padding-left: 0.5em;"> |
| <div id="projectname">Vulkan Memory Allocator |
| </div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <!-- end header part --> |
| <!-- Generated by Doxygen 1.8.13 --> |
| <script type="text/javascript"> |
| var searchBox = new SearchBox("searchBox", "search",false,'Search'); |
| </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'); |
| $(document).ready(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"> |
| <iframe src="javascript:void(0)" frameborder="0" |
| name="MSearchResults" id="MSearchResults"> |
| </iframe> |
| </div> |
| |
| <div id="nav-path" class="navpath"> |
| <ul> |
| <li class="navelem"><a class="el" href="index.html">Vulkan Memory Allocator</a></li> </ul> |
| </div> |
| </div><!-- top --> |
| <div class="header"> |
| <div class="headertitle"> |
| <div class="title">Choosing memory type </div> </div> |
| </div><!--header--> |
| <div class="contents"> |
| <div class="textblock"><p>Physical devices in Vulkan support various combinations of memory heaps and types. Help with choosing correct and optimal memory type for your specific resource is one of the key features of this library. You can use it by filling appropriate members of <a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> structure, as described below. You can also combine multiple methods.</p> |
| <ol type="1"> |
| <li>If you just want to find memory type index that meets your requirements, you can use function <a class="el" href="vk__mem__alloc_8h.html#aef15a94b58fbcb0fe706d5720e84a74a" title="Helps to find memoryTypeIndex, given memoryTypeBits and VmaAllocationCreateInfo. ">vmaFindMemoryTypeIndex()</a>.</li> |
| <li>If you want to allocate a region of device memory without association with any specific image or buffer, you can use function <a class="el" href="vk__mem__alloc_8h.html#abf28077dbf82d0908b8acbe8ee8dd9b8" title="General purpose memory allocation. ">vmaAllocateMemory()</a>. Usage of this function is not recommended and usually not needed.</li> |
| <li>If you already have a buffer or an image created, you want to allocate memory for it and then you will bind it yourself, you can use function <a class="el" href="vk__mem__alloc_8h.html#a7fdf64415b6c3d83c454f28d2c53df7b">vmaAllocateMemoryForBuffer()</a>, <a class="el" href="vk__mem__alloc_8h.html#a0faa3f9e5fb233d29d1e00390650febb" title="Function similar to vmaAllocateMemoryForBuffer(). ">vmaAllocateMemoryForImage()</a>. For binding you should use functions: <a class="el" href="vk__mem__alloc_8h.html#a6b0929b914b60cf2d45cac4bf3547470" title="Binds buffer to allocation. ">vmaBindBufferMemory()</a>, <a class="el" href="vk__mem__alloc_8h.html#a3d3ca45799923aa5d138e9e5f9eb2da5" title="Binds image to allocation. ">vmaBindImageMemory()</a>.</li> |
| <li>If you want to create a buffer or an image, allocate memory for it and bind them together, all in one call, you can use function <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>. This is the recommended way to use this library.</li> |
| </ol> |
| <p>When using 3. or 4., the library internally queries Vulkan for memory types supported for that buffer or image (function <code>vkGetBufferMemoryRequirements()</code>) and uses only one of these types.</p> |
| <p>If no memory type can be found that meets all the requirements, these functions return <code>VK_ERROR_FEATURE_NOT_PRESENT</code>.</p> |
| <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 <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"><a class="code" href="struct_vma_allocation.html">VmaAllocation</a> allocation;</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &bufferInfo, &allocInfo, &buffer, &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> |
| <p>You can specify more detailed requirements by filling members <a class="el" href="struct_vma_allocation_create_info.html#a9166390303ff42d783305bc31c2b6b90" title="Flags that must be set in a Memory Type chosen for an allocation. ">VmaAllocationCreateInfo::requiredFlags</a> and <a class="el" href="struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d" title="Flags that preferably should be set in a memory type chosen for an allocation. ">VmaAllocationCreateInfo::preferredFlags</a> with a combination of bits from enum <code>VkMemoryPropertyFlags</code>. For example, if you want to create a buffer that will be persistently mapped on host (so it must be <code>HOST_VISIBLE</code>) and preferably will also be <code>HOST_COHERENT</code> and <code>HOST_CACHED</code>, use following code:</p> |
| <div class="fragment"><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#a9166390303ff42d783305bc31c2b6b90">requiredFlags</a> = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT;</div><div class="line">allocInfo.<a class="code" href="struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d">preferredFlags</a> = VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | VK_MEMORY_PROPERTY_HOST_CACHED_BIT;</div><div class="line">allocInfo.<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 buffer;</div><div class="line"><a class="code" href="struct_vma_allocation.html">VmaAllocation</a> allocation;</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, <span class="keyword">nullptr</span>);</div></div><!-- fragment --><p>A memory type is chosen that has all the required flags and as many preferred flags set as possible.</p> |
| <p>If you use <a class="el" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910" title="Intended usage of memory. ">VmaAllocationCreateInfo::usage</a>, it is just internally converted to a set of required and preferred flags.</p> |
| <h1><a class="anchor" id="choosing_memory_type_explicit_memory_types"></a> |
| Explicit memory types</h1> |
| <p>If you inspected memory types available on the physical device and you have a preference for memory types that you want to use, you can fill member <a class="el" href="struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055" title="Bitmask containing one bit set for every memory type acceptable for this allocation. ">VmaAllocationCreateInfo::memoryTypeBits</a>. It is a bit mask, where each bit set means that a memory type with that index is allowed to be used for the allocation. Special value 0, just like <code>UINT32_MAX</code>, means there are no restrictions to memory type index.</p> |
| <p>Please note that this member is NOT just a memory type index. Still you can use it to choose just one, specific memory type. For example, if you already determined that your buffer should be created in memory type 2, use following code:</p> |
| <div class="fragment"><div class="line">uint32_t memoryTypeIndex = 2;</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#a3bf940c0271d85d6ba32a4d820075055">memoryTypeBits</a> = 1u << memoryTypeIndex;</div><div class="line"></div><div class="line">VkBuffer buffer;</div><div class="line"><a class="code" href="struct_vma_allocation.html">VmaAllocation</a> allocation;</div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, <span class="keyword">nullptr</span>);</div></div><!-- fragment --><h1><a class="anchor" id="choosing_memory_type_custom_memory_pools"></a> |
| Custom memory pools</h1> |
| <p>If you allocate from custom memory pool, all the ways of specifying memory requirements described above are not applicable and the aforementioned members of <a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> structure are ignored. Memory type is selected explicitly when creating the pool and then used to make all the allocations from that pool. For further details, see <a class="el" href="custom_memory_pools.html">Custom memory pools</a>. </p> |
| </div></div><!-- contents --> |
| <!-- start footer part --> |
| <hr class="footer"/><address class="footer"><small> |
| Generated by  <a href="http://www.doxygen.org/index.html"> |
| <img class="footer" src="doxygen.png" alt="doxygen"/> |
| </a> 1.8.13 |
| </small></address> |
| </body> |
| </html> |
