docs/html/choosing_memory_type.html - external/github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator - Git at Google

 <!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">
 <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.17"/>
 <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.17 -->
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 var searchBox = new SearchBox("searchBox", "search",false,'Search');
 /* @license-end */
 </script>
 <script type="text/javascript" src="menudata.js"></script>
 <script type="text/javascript" src="menu.js"></script>
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 $(function() {
   initMenu('',true,false,'search.php','Search');
   $(document).ready(function() { init_search(); });
 });
 /* @license-end */</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="PageDoc"><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>, <a class="el" href="vk__mem__alloc_8h.html#ae790ab9ffaf7667fb8f62523e6897888" title="Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.">vmaFindMemoryTypeIndexForBufferInfo()</a>, <a class="el" href="vk__mem__alloc_8h.html#a088da83d8eaf3ce9056d9ea0b981d472" title="Helps to find memoryTypeIndex, given VkImageCreateInfo and VmaAllocationCreateInfo.">vmaFindMemoryTypeIndexForImageInfo()</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. <a class="el" href="vk__mem__alloc_8h.html#ad37e82e492b3de38fc3f4cffd9ad0ae1" title="General purpose memory allocation for multiple allocation objects at once.">vmaAllocateMemoryPages()</a> function is also provided for creating multiple allocations at once, which may be useful for sparse binding.</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> or their extended versions: <a class="el" href="vk__mem__alloc_8h.html#a927c944f45e0f2941182abb6f608e64a" title="Binds buffer to allocation with additional parameters.">vmaBindBufferMemory2()</a>, <a class="el" href="vk__mem__alloc_8h.html#aa8251ee81b0045a443e35b8e8aa021bc" title="Binds image to allocation with additional parameters.">vmaBindImageMemory2()</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 easiest and 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, &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>
 <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, &amp;bufferInfo, &amp;allocInfo, &amp;buffer, &amp;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 &lt;&lt; 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, &amp;bufferInfo, &amp;allocInfo, &amp;buffer, &amp;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>
 <h1><a class="anchor" id="choosing_memory_type_dedicated_allocations"></a>
 Dedicated allocations</h1>
 <p>Memory for allocations is reserved out of larger block of <code>VkDeviceMemory</code> allocated from Vulkan internally. That's the main feature of this whole library. You can still request a separate memory block to be created for an allocation, just like you would do in a trivial solution without using any allocator. In that case, a buffer or image is always bound to that memory at offset 0. This is called a "dedicated allocation". You can explicitly request it by using flag <a class="el" href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block.">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>. The library can also internally decide to use dedicated allocation in some cases, e.g.:</p>
 <ul>
 <li>When the size of the allocation is large.</li>
 <li>When <a class="el" href="vk_khr_dedicated_allocation.html">VK_KHR_dedicated_allocation</a> extension is enabled and it reports that dedicated allocation is required or recommended for the resource.</li>
 <li>When allocation of next big memory block fails due to not enough device memory, but allocation with the exact requested size succeeds. </li>
 </ul>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->
 <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 class="ttc" id="avk__mem__alloc_8h_html_aa5846affa1e9da3800e3e78fae2305ccac6b5dc1432d88647aa4cd456246eadf7"><div class="ttname"><a href="vk__mem__alloc_8h.html#aa5846affa1e9da3800e3e78fae2305ccac6b5dc1432d88647aa4cd456246eadf7">VMA_MEMORY_USAGE_GPU_ONLY</a></div><div class="ttdeci">@ VMA_MEMORY_USAGE_GPU_ONLY</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:2456</div></div>
 <div class="ttc" id="astruct_vma_allocation_create_info_html_a9166390303ff42d783305bc31c2b6b90"><div class="ttname"><a href="struct_vma_allocation_create_info.html#a9166390303ff42d783305bc31c2b6b90">VmaAllocationCreateInfo::requiredFlags</a></div><div class="ttdeci">VkMemoryPropertyFlags requiredFlags</div><div class="ttdoc">Flags that must be set in a Memory Type chosen for an allocation.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:2627</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:2622</div></div>
 <div class="ttc" id="avk__mem__alloc_8h_html_ac72ee55598617e8eecca384e746bab51"><div class="ttname"><a href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a></div><div class="ttdeci">VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)</div></div>
 <div class="ttc" id="avk__mem__alloc_8h_html_ad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f"><div class="ttname"><a href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">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:2533</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:2616</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="ttdef"><b>Definition:</b> vk_mem_alloc.h:2613</div></div>
 <div class="ttc" id="astruct_vma_allocation_create_info_html_a7fe8d81a1ad10b2a2faacacee5b15d6d"><div class="ttname"><a href="struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d">VmaAllocationCreateInfo::preferredFlags</a></div><div class="ttdeci">VkMemoryPropertyFlags preferredFlags</div><div class="ttdoc">Flags that preferably should be set in a memory type chosen for an allocation.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:2632</div></div>
 <div class="ttc" id="astruct_vma_allocation_create_info_html_a3bf940c0271d85d6ba32a4d820075055"><div class="ttname"><a href="struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055">VmaAllocationCreateInfo::memoryTypeBits</a></div><div class="ttdeci">uint32_t memoryTypeBits</div><div class="ttdoc">Bitmask containing one bit set for every memory type acceptable for this allocation.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:2640</div></div>
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
 Generated by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.17
 </small></address>
 </body>
 </html>
	<!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">
	<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.17"/>
	<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.17 -->
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	var searchBox = new SearchBox("searchBox", "search",false,'Search');
	/* @license-end */
	</script>
	<script type="text/javascript" src="menudata.js"></script>
	<script type="text/javascript" src="menu.js"></script>
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	$(function() {
	initMenu('',true,false,'search.php','Search');
	$(document).ready(function() { init_search(); });
	});
	/* @license-end */</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="PageDoc"><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>, <a class="el" href="vk__mem__alloc_8h.html#ae790ab9ffaf7667fb8f62523e6897888" title="Helps to find memoryTypeIndex, given VkBufferCreateInfo and VmaAllocationCreateInfo.">vmaFindMemoryTypeIndexForBufferInfo()</a>, <a class="el" href="vk__mem__alloc_8h.html#a088da83d8eaf3ce9056d9ea0b981d472" title="Helps to find memoryTypeIndex, given VkImageCreateInfo and VmaAllocationCreateInfo.">vmaFindMemoryTypeIndexForImageInfo()</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. <a class="el" href="vk__mem__alloc_8h.html#ad37e82e492b3de38fc3f4cffd9ad0ae1" title="General purpose memory allocation for multiple allocation objects at once.">vmaAllocateMemoryPages()</a> function is also provided for creating multiple allocations at once, which may be useful for sparse binding.</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> or their extended versions: <a class="el" href="vk__mem__alloc_8h.html#a927c944f45e0f2941182abb6f608e64a" title="Binds buffer to allocation with additional parameters.">vmaBindBufferMemory2()</a>, <a class="el" href="vk__mem__alloc_8h.html#aa8251ee81b0045a443e35b8e8aa021bc" title="Binds image to allocation with additional parameters.">vmaBindImageMemory2()</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 easiest and 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>
	<h1><a class="anchor" id="choosing_memory_type_dedicated_allocations"></a>
	Dedicated allocations</h1>
	<p>Memory for allocations is reserved out of larger block of <code>VkDeviceMemory</code> allocated from Vulkan internally. That's the main feature of this whole library. You can still request a separate memory block to be created for an allocation, just like you would do in a trivial solution without using any allocator. In that case, a buffer or image is always bound to that memory at offset 0. This is called a "dedicated allocation". You can explicitly request it by using flag <a class="el" href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block.">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>. The library can also internally decide to use dedicated allocation in some cases, e.g.:</p>
	<ul>
	<li>When the size of the allocation is large.</li>
	<li>When <a class="el" href="vk_khr_dedicated_allocation.html">VK_KHR_dedicated_allocation</a> extension is enabled and it reports that dedicated allocation is required or recommended for the resource.</li>
	<li>When allocation of next big memory block fails due to not enough device memory, but allocation with the exact requested size succeeds. </li>
	</ul>
	</div></div><!-- contents -->
	</div><!-- PageDoc -->
	<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 class="ttc" id="avk__mem__alloc_8h_html_aa5846affa1e9da3800e3e78fae2305ccac6b5dc1432d88647aa4cd456246eadf7"><div class="ttname"><a href="vk__mem__alloc_8h.html#aa5846affa1e9da3800e3e78fae2305ccac6b5dc1432d88647aa4cd456246eadf7">VMA_MEMORY_USAGE_GPU_ONLY</a></div><div class="ttdeci">@ VMA_MEMORY_USAGE_GPU_ONLY</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:2456</div></div>
	<div class="ttc" id="astruct_vma_allocation_create_info_html_a9166390303ff42d783305bc31c2b6b90"><div class="ttname"><a href="struct_vma_allocation_create_info.html#a9166390303ff42d783305bc31c2b6b90">VmaAllocationCreateInfo::requiredFlags</a></div><div class="ttdeci">VkMemoryPropertyFlags requiredFlags</div><div class="ttdoc">Flags that must be set in a Memory Type chosen for an allocation.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:2627</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:2622</div></div>
	<div class="ttc" id="avk__mem__alloc_8h_html_ac72ee55598617e8eecca384e746bab51"><div class="ttname"><a href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a></div><div class="ttdeci">VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo pBufferCreateInfo, const VmaAllocationCreateInfo pAllocationCreateInfo, VkBuffer pBuffer, VmaAllocation pAllocation, VmaAllocationInfo *pAllocationInfo)</div></div>
	<div class="ttc" id="avk__mem__alloc_8h_html_ad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f"><div class="ttname"><a href="vk__mem__alloc_8h.html#ad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f">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:2533</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:2616</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="ttdef"><b>Definition:</b> vk_mem_alloc.h:2613</div></div>
	<div class="ttc" id="astruct_vma_allocation_create_info_html_a7fe8d81a1ad10b2a2faacacee5b15d6d"><div class="ttname"><a href="struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d">VmaAllocationCreateInfo::preferredFlags</a></div><div class="ttdeci">VkMemoryPropertyFlags preferredFlags</div><div class="ttdoc">Flags that preferably should be set in a memory type chosen for an allocation.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:2632</div></div>
	<div class="ttc" id="astruct_vma_allocation_create_info_html_a3bf940c0271d85d6ba32a4d820075055"><div class="ttname"><a href="struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055">VmaAllocationCreateInfo::memoryTypeBits</a></div><div class="ttdeci">uint32_t memoryTypeBits</div><div class="ttdoc">Bitmask containing one bit set for every memory type acceptable for this allocation.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:2640</div></div>
	<!-- 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.17
	</small></address>
	</body>
	</html>