AuroraMiddleware/VulkanMemoryAllocator
1
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator synced 2024-11-05 12:20:07 +00:00
Code Issues Projects Releases Wiki Activity

Added VmaAllocationCreateInfo::memoryTypeBits. Wrote more documentation, including new page "Choosing memory type".

Browse Source
This commit is contained in:
Adam Sawicki 2017-11-21 15:01:29 +01:00
parent b8ad8a09a1
commit 594a56260f
15 changed files with 445 additions and 160 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
bin/VulkanSample_Release_2015.exe
View File

Binary file not shown.

103
docs/html/choosing_memory_type.html Normal file
View File

@ -0,0 +1,103 @@
<!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">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>.</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 <code>VmaMemoryUsage</code>. It defines high level, common usage types.</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>
<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">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 --><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 UINT32_MAX, 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">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_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 &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>

3
docs/html/functions.html
View File

@ -139,6 +139,9 @@ $(function() {
: <a class="el" href="struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5">VmaAllocationInfo</a> : <a class="el" href="struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5">VmaAllocationInfo</a>
, <a class="el" href="struct_vma_stats.html#a13e3caf754be79352c42408756309331">VmaStats</a> , <a class="el" href="struct_vma_stats.html#a13e3caf754be79352c42408756309331">VmaStats</a>
</li> </li>
<li>memoryTypeBits
: <a class="el" href="struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055">VmaAllocationCreateInfo</a>
</li>
<li>memoryTypeIndex <li>memoryTypeIndex
: <a class="el" href="struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319">VmaPoolCreateInfo</a> : <a class="el" href="struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319">VmaPoolCreateInfo</a>
</li> </li>

3
docs/html/functions_vars.html
View File

@ -139,6 +139,9 @@ $(function() {
: <a class="el" href="struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5">VmaAllocationInfo</a> : <a class="el" href="struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5">VmaAllocationInfo</a>
, <a class="el" href="struct_vma_stats.html#a13e3caf754be79352c42408756309331">VmaStats</a> , <a class="el" href="struct_vma_stats.html#a13e3caf754be79352c42408756309331">VmaStats</a>
</li> </li>
<li>memoryTypeBits
: <a class="el" href="struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055">VmaAllocationCreateInfo</a>
</li>
<li>memoryTypeIndex <li>memoryTypeIndex
: <a class="el" href="struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319">VmaPoolCreateInfo</a> : <a class="el" href="struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319">VmaPoolCreateInfo</a>
</li> </li>

1
docs/html/index.html
View File

@ -70,6 +70,7 @@ License: MIT</p>
<ul> <ul>
<li>User guide<ul> <li>User guide<ul>
<li><a class="el" href="quick_start.html">Quick start</a></li> <li><a class="el" href="quick_start.html">Quick start</a></li>
<li><a class="el" href="choosing_memory_type.html">Choosing memory type</a></li>
<li><a class="el" href="memory_mapping.html">Memory mapping</a></li> <li><a class="el" href="memory_mapping.html">Memory mapping</a></li>
<li><a class="el" href="custom_memory_pools.html">Custom memory pools</a></li> <li><a class="el" href="custom_memory_pools.html">Custom memory pools</a></li>
<li><a class="el" href="defragmentation.html">Defragmentation</a></li> <li><a class="el" href="defragmentation.html">Defragmentation</a></li>

1
docs/html/search/all_2.js
View File

@ -1,5 +1,6 @@
var searchData= var searchData=
[ [
['choosing_20memory_20type',['Choosing memory type',['../choosing_memory_type.html',1,'index']]],
['configuration',['Configuration',['../configuration.html',1,'index']]], ['configuration',['Configuration',['../configuration.html',1,'index']]],
['custom_20memory_20pools',['Custom memory pools',['../custom_memory_pools.html',1,'index']]] ['custom_20memory_20pools',['Custom memory pools',['../custom_memory_pools.html',1,'index']]]
]; ];

1
docs/html/search/all_6.js
View File

@ -6,6 +6,7 @@ var searchData=
['memory_20mapping',['Memory mapping',['../memory_mapping.html',1,'index']]], ['memory_20mapping',['Memory mapping',['../memory_mapping.html',1,'index']]],
['memoryheap',['memoryHeap',['../struct_vma_stats.html#a0e6611508c29a187f0fd14ff1a0329c0',1,'VmaStats']]], ['memoryheap',['memoryHeap',['../struct_vma_stats.html#a0e6611508c29a187f0fd14ff1a0329c0',1,'VmaStats']]],
['memorytype',['memoryType',['../struct_vma_stats.html#a13e3caf754be79352c42408756309331',1,'VmaStats::memoryType()'],['../struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5',1,'VmaAllocationInfo::memoryType()']]], ['memorytype',['memoryType',['../struct_vma_stats.html#a13e3caf754be79352c42408756309331',1,'VmaStats::memoryType()'],['../struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5',1,'VmaAllocationInfo::memoryType()']]],
['memorytypebits',['memoryTypeBits',['../struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055',1,'VmaAllocationCreateInfo']]],
['memorytypeindex',['memoryTypeIndex',['../struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319',1,'VmaPoolCreateInfo']]], ['memorytypeindex',['memoryTypeIndex',['../struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319',1,'VmaPoolCreateInfo']]],
['minblockcount',['minBlockCount',['../struct_vma_pool_create_info.html#ad8006fb803185c0a699d30f3e9a865ae',1,'VmaPoolCreateInfo']]] ['minblockcount',['minBlockCount',['../struct_vma_pool_create_info.html#ad8006fb803185c0a699d30f3e9a865ae',1,'VmaPoolCreateInfo']]]
]; ];

1
docs/html/search/pages_1.js
View File

@ -1,5 +1,6 @@
var searchData= var searchData=
[ [
['choosing_20memory_20type',['Choosing memory type',['../choosing_memory_type.html',1,'index']]],
['configuration',['Configuration',['../configuration.html',1,'index']]], ['configuration',['Configuration',['../configuration.html',1,'index']]],
['custom_20memory_20pools',['Custom memory pools',['../custom_memory_pools.html',1,'index']]] ['custom_20memory_20pools',['Custom memory pools',['../custom_memory_pools.html',1,'index']]]
]; ];

1
docs/html/search/variables_4.js
View File

@ -5,6 +5,7 @@ var searchData=
['maxbytestomove',['maxBytesToMove',['../struct_vma_defragmentation_info.html#acb311c940a777270e67e1b81c5ab6a1d',1,'VmaDefragmentationInfo']]], ['maxbytestomove',['maxBytesToMove',['../struct_vma_defragmentation_info.html#acb311c940a777270e67e1b81c5ab6a1d',1,'VmaDefragmentationInfo']]],
['memoryheap',['memoryHeap',['../struct_vma_stats.html#a0e6611508c29a187f0fd14ff1a0329c0',1,'VmaStats']]], ['memoryheap',['memoryHeap',['../struct_vma_stats.html#a0e6611508c29a187f0fd14ff1a0329c0',1,'VmaStats']]],
['memorytype',['memoryType',['../struct_vma_stats.html#a13e3caf754be79352c42408756309331',1,'VmaStats::memoryType()'],['../struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5',1,'VmaAllocationInfo::memoryType()']]], ['memorytype',['memoryType',['../struct_vma_stats.html#a13e3caf754be79352c42408756309331',1,'VmaStats::memoryType()'],['../struct_vma_allocation_info.html#a7f6b0aa58c135e488e6b40a388dad9d5',1,'VmaAllocationInfo::memoryType()']]],
['memorytypebits',['memoryTypeBits',['../struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055',1,'VmaAllocationCreateInfo']]],
['memorytypeindex',['memoryTypeIndex',['../struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319',1,'VmaPoolCreateInfo']]], ['memorytypeindex',['memoryTypeIndex',['../struct_vma_pool_create_info.html#a596fa76b685d3f1f688f84a709a5b319',1,'VmaPoolCreateInfo']]],
['minblockcount',['minBlockCount',['../struct_vma_pool_create_info.html#ad8006fb803185c0a699d30f3e9a865ae',1,'VmaPoolCreateInfo']]] ['minblockcount',['minBlockCount',['../struct_vma_pool_create_info.html#ad8006fb803185c0a699d30f3e9a865ae',1,'VmaPoolCreateInfo']]]
]; ];

11
docs/html/struct_vma_allocation_create_info-members.html
View File

@ -66,11 +66,12 @@ $(function() {
<p>This is the complete list of members for <a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a>, including all inherited members.</p> <p>This is the complete list of members for <a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a>, including all inherited members.</p>
<table class="directory"> <table class="directory">
<tr class="even"><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr> <tr class="even"><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr>
<tr><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150">pool</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr> <tr><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055">memoryTypeBits</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr>
<tr class="even"><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d">preferredFlags</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr> <tr class="even"><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150">pool</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr>
<tr><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19">pUserData</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr> <tr><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d">preferredFlags</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr>
<tr class="even"><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#a9166390303ff42d783305bc31c2b6b90">requiredFlags</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr> <tr class="even"><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19">pUserData</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr>
<tr><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr> <tr><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#a9166390303ff42d783305bc31c2b6b90">requiredFlags</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr>
<tr class="even"><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a></td><td class="entry"><a class="el" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></td><td class="entry"></td></tr>
</table></div><!-- contents --> </table></div><!-- contents -->
<!-- start footer part --> <!-- start footer part -->
<hr class="footer"/><address class="footer"><small> <hr class="footer"/><address class="footer"><small>

41
docs/html/struct_vma_allocation_create_info.html
View File

@ -80,14 +80,17 @@ Public Attributes</h2></td></tr>
<tr class="memdesc:a9166390303ff42d783305bc31c2b6b90"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flags that must be set in a Memory Type chosen for an allocation. <a href="#a9166390303ff42d783305bc31c2b6b90">More...</a><br /></td></tr> <tr class="memdesc:a9166390303ff42d783305bc31c2b6b90"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flags that must be set in a Memory Type chosen for an allocation. <a href="#a9166390303ff42d783305bc31c2b6b90">More...</a><br /></td></tr>
<tr class="separator:a9166390303ff42d783305bc31c2b6b90"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a9166390303ff42d783305bc31c2b6b90"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a7fe8d81a1ad10b2a2faacacee5b15d6d"><td class="memItemLeft" align="right" valign="top">VkMemoryPropertyFlags&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d">preferredFlags</a></td></tr> <tr class="memitem:a7fe8d81a1ad10b2a2faacacee5b15d6d"><td class="memItemLeft" align="right" valign="top">VkMemoryPropertyFlags&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_vma_allocation_create_info.html#a7fe8d81a1ad10b2a2faacacee5b15d6d">preferredFlags</a></td></tr>
<tr class="memdesc:a7fe8d81a1ad10b2a2faacacee5b15d6d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flags that preferably should be set in a Memory Type chosen for an allocation. <a href="#a7fe8d81a1ad10b2a2faacacee5b15d6d">More...</a><br /></td></tr> <tr class="memdesc:a7fe8d81a1ad10b2a2faacacee5b15d6d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flags that preferably should be set in a memory type chosen for an allocation. <a href="#a7fe8d81a1ad10b2a2faacacee5b15d6d">More...</a><br /></td></tr>
<tr class="separator:a7fe8d81a1ad10b2a2faacacee5b15d6d"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a7fe8d81a1ad10b2a2faacacee5b15d6d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a8259e85c272683434f4abb4ddddffe19"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19">pUserData</a></td></tr> <tr class="memitem:a3bf940c0271d85d6ba32a4d820075055"><td class="memItemLeft" align="right" valign="top">uint32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_vma_allocation_create_info.html#a3bf940c0271d85d6ba32a4d820075055">memoryTypeBits</a></td></tr>
<tr class="memdesc:a8259e85c272683434f4abb4ddddffe19"><td class="mdescLeft">&#160;</td><td class="mdescRight">Custom general-purpose pointer that will be stored in VmaAllocation, can be read as <a class="el" href="struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13" title="Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...">VmaAllocationInfo::pUserData</a> and changed using <a class="el" href="vk__mem__alloc_8h.html#af9147d31ffc11d62fc187bde283ed14f" title="Sets pUserData in given allocation to new value. ">vmaSetAllocationUserData()</a>. <a href="#a8259e85c272683434f4abb4ddddffe19">More...</a><br /></td></tr> <tr class="memdesc:a3bf940c0271d85d6ba32a4d820075055"><td class="mdescLeft">&#160;</td><td class="mdescRight">Bitmask containing one bit set for every memory type acceptable for this allocation. <a href="#a3bf940c0271d85d6ba32a4d820075055">More...</a><br /></td></tr>
<tr class="separator:a8259e85c272683434f4abb4ddddffe19"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a3bf940c0271d85d6ba32a4d820075055"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a6272c0555cfd1fe28bff1afeb6190150"><td class="memItemLeft" align="right" valign="top">VmaPool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150">pool</a></td></tr> <tr class="memitem:a6272c0555cfd1fe28bff1afeb6190150"><td class="memItemLeft" align="right" valign="top">VmaPool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150">pool</a></td></tr>
<tr class="memdesc:a6272c0555cfd1fe28bff1afeb6190150"><td class="mdescLeft">&#160;</td><td class="mdescRight">Pool that this allocation should be created in. <a href="#a6272c0555cfd1fe28bff1afeb6190150">More...</a><br /></td></tr> <tr class="memdesc:a6272c0555cfd1fe28bff1afeb6190150"><td class="mdescLeft">&#160;</td><td class="mdescRight">Pool that this allocation should be created in. <a href="#a6272c0555cfd1fe28bff1afeb6190150">More...</a><br /></td></tr>
<tr class="separator:a6272c0555cfd1fe28bff1afeb6190150"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a6272c0555cfd1fe28bff1afeb6190150"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a8259e85c272683434f4abb4ddddffe19"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_vma_allocation_create_info.html#a8259e85c272683434f4abb4ddddffe19">pUserData</a></td></tr>
<tr class="memdesc:a8259e85c272683434f4abb4ddddffe19"><td class="mdescLeft">&#160;</td><td class="mdescRight">Custom general-purpose pointer that will be stored in VmaAllocation, can be read as <a class="el" href="struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13" title="Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...">VmaAllocationInfo::pUserData</a> and changed using <a class="el" href="vk__mem__alloc_8h.html#af9147d31ffc11d62fc187bde283ed14f" title="Sets pUserData in given allocation to new value. ">vmaSetAllocationUserData()</a>. <a href="#a8259e85c272683434f4abb4ddddffe19">More...</a><br /></td></tr>
<tr class="separator:a8259e85c272683434f4abb4ddddffe19"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table> </table>
<h2 class="groupheader">Member Data Documentation</h2> <h2 class="groupheader">Member Data Documentation</h2>
<a id="add09658ac14fe290ace25470ddd6d41b"></a> <a id="add09658ac14fe290ace25470ddd6d41b"></a>
@ -104,6 +107,24 @@ Public Attributes</h2></td></tr>
<p>Use VmaAllocationCreateFlagBits enum. </p> <p>Use VmaAllocationCreateFlagBits enum. </p>
</div>
</div>
<a id="a3bf940c0271d85d6ba32a4d820075055"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a3bf940c0271d85d6ba32a4d820075055">&#9670;&nbsp;</a></span>memoryTypeBits</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">uint32_t VmaAllocationCreateInfo::memoryTypeBits</td>
</tr>
</table>
</div><div class="memdoc">
<p>Bitmask containing one bit set for every memory type acceptable for this allocation. </p>
<p>Value 0 is equivalent to <code>UINT32_MAX</code> - it means any memory type is accepted if it meets other requirements specified by this structure, with no further restrictions on memory type index. <br />
If <code>pool</code> is not null, this member is ignored. </p>
</div> </div>
</div> </div>
<a id="a6272c0555cfd1fe28bff1afeb6190150"></a> <a id="a6272c0555cfd1fe28bff1afeb6190150"></a>
@ -119,7 +140,7 @@ Public Attributes</h2></td></tr>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Pool that this allocation should be created in. </p> <p>Pool that this allocation should be created in. </p>
<p>Leave <code>VK_NULL_HANDLE</code> to allocate from general memory. </p> <p>Leave <code>VK_NULL_HANDLE</code> to allocate from default pool. If not null, members: <code>usage</code>, <code>requiredFlags</code>, <code>preferredFlags</code>, <code>memoryTypeBits</code> are ignored. </p>
</div> </div>
</div> </div>
@ -135,9 +156,8 @@ Public Attributes</h2></td></tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Flags that preferably should be set in a Memory Type chosen for an allocation. </p> <p>Flags that preferably should be set in a memory type chosen for an allocation. </p>
<p>Set to 0 if no additional flags are prefered and only <code>requiredFlags</code> should be used. <br /> <p>Set to 0 if no additional flags are prefered. <br />
If not 0, it must be a superset or equal to <code>requiredFlags</code>. <br />
If <code>pool</code> is not null, this member is ignored. </p> If <code>pool</code> is not null, this member is ignored. </p>
</div> </div>
@ -155,6 +175,7 @@ If <code>pool</code> is not null, this member is ignored. </p>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Custom general-purpose pointer that will be stored in VmaAllocation, can be read as <a class="el" href="struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13" title="Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...">VmaAllocationInfo::pUserData</a> and changed using <a class="el" href="vk__mem__alloc_8h.html#af9147d31ffc11d62fc187bde283ed14f" title="Sets pUserData in given allocation to new value. ">vmaSetAllocationUserData()</a>. </p> <p>Custom general-purpose pointer that will be stored in VmaAllocation, can be read as <a class="el" href="struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13" title="Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...">VmaAllocationInfo::pUserData</a> and changed using <a class="el" href="vk__mem__alloc_8h.html#af9147d31ffc11d62fc187bde283ed14f" title="Sets pUserData in given allocation to new value. ">vmaSetAllocationUserData()</a>. </p>
<p>If <code>VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT</code> is used, it must be either null or pointer to a null-terminated string. The string will be then copied to internal buffer, so it doesn't need to be valid after allocation call. </p>
</div> </div>
</div> </div>
@ -171,7 +192,7 @@ If <code>pool</code> is not null, this member is ignored. </p>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Flags that must be set in a Memory Type chosen for an allocation. </p> <p>Flags that must be set in a Memory Type chosen for an allocation. </p>
<p>Leave 0 if you specify requirement via usage. <br /> <p>Leave 0 if you specify memory requirements in other way. <br />
If <code>pool</code> is not null, this member is ignored. </p> If <code>pool</code> is not null, this member is ignored. </p>
</div> </div>
@ -189,7 +210,7 @@ If <code>pool</code> is not null, this member is ignored. </p>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Intended usage of memory. </p> <p>Intended usage of memory. </p>
<p>Leave <code>VMA_MEMORY_USAGE_UNKNOWN</code> if you specify <code>requiredFlags</code>. You can also use both. <br /> <p>You can leave <code>VMA_MEMORY_USAGE_UNKNOWN</code> if you specify memory requirements in other way. <br />
If <code>pool</code> is not null, this member is ignored. </p> If <code>pool</code> is not null, this member is ignored. </p>
</div> </div>

9
docs/html/vk__mem__alloc_8h.html
View File

@ -712,15 +712,16 @@ Functions</h2></td></tr>
<table class="fieldtable"> <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> <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> </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 faster access from the device is preferred. No need to be mappable on host. </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 faster access from the device is preferred. It usually means device-local GPU memory. No need to be mappable on host. Good e.g. for images to be used as attachments, images containing textures to be sampled, buffers used as vertex buffer, index buffer, uniform buffer and majority of other types of resources used by device. You can still do transfers from/to such resource to/from host memory.</p>
<p>The 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 also use <code>VMA_ALLOCATION_CREATE_MAPPED_BIT</code> with this usage type. </p>
</td></tr> </td></tr>
<tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5"></a>VMA_MEMORY_USAGE_CPU_ONLY&#160;</td><td class="fielddoc"><p>Memory will be mapped on host. Could be used for transfer to/from device. </p> <tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5"></a>VMA_MEMORY_USAGE_CPU_ONLY&#160;</td><td class="fielddoc"><p>Memory will be mapped and used on host. It usually means CPU system memory. Could be used for transfer to/from device. Good e.g. for "staging" copy of buffers and images, used as transfer source or destination. Resources created in this pool may still be accessible to the device, but access to them can be slower.</p>
<p>Guarantees to be <code>HOST_VISIBLE</code> and <code>HOST_COHERENT</code>. </p> <p>Guarantees to be <code>HOST_VISIBLE</code> and <code>HOST_COHERENT</code>. </p>
</td></tr> </td></tr>
<tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca9066b52c5a7079bb74a69aaf8b92ff67"></a>VMA_MEMORY_USAGE_CPU_TO_GPU&#160;</td><td class="fielddoc"><p>Memory will be used for frequent (dynamic) updates from host and reads on device (upload). </p> <tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca9066b52c5a7079bb74a69aaf8b92ff67"></a>VMA_MEMORY_USAGE_CPU_TO_GPU&#160;</td><td class="fielddoc"><p>Memory will be used for frequent (dynamic) updates from host and reads on device (upload). Good e.g. for vertex buffers or uniform buffers updated every frame.</p>
<p>Guarantees to be <code>HOST_VISIBLE</code>. </p> <p>Guarantees to be <code>HOST_VISIBLE</code>. </p>
</td></tr> </td></tr>
<tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca7b586d2fdaf82a463b58f581ed72be27"></a>VMA_MEMORY_USAGE_GPU_TO_CPU&#160;</td><td class="fielddoc"><p>Memory will be used for frequent writing on device and readback on host (download). </p> <tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca7b586d2fdaf82a463b58f581ed72be27"></a>VMA_MEMORY_USAGE_GPU_TO_CPU&#160;</td><td class="fielddoc"><p>Memory will be used for frequent writing on device and readback on host (download).</p>
<p>Guarantees to be <code>HOST_VISIBLE</code>. </p> <p>Guarantees to be <code>HOST_VISIBLE</code>. </p>
</td></tr> </td></tr>
<tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca091e69437ef693e8d0d287f1c719ba6e"></a>VMA_MEMORY_USAGE_MAX_ENUM&#160;</td><td class="fielddoc"></td></tr> <tr><td class="fieldname"><a id="aa5846affa1e9da3800e3e78fae2305cca091e69437ef693e8d0d287f1c719ba6e"></a>VMA_MEMORY_USAGE_MAX_ENUM&#160;</td><td class="fielddoc"></td></tr>

219
docs/html/vk__mem__alloc_8h_source.html
View File

File diff suppressed because one or more lines are too long

8
docs/html/vk_khr_dedicated_allocation.html
View File

@ -74,13 +74,7 @@ $(function() {
<li>VK_KHR_dedicated_allocation</li> <li>VK_KHR_dedicated_allocation</li>
</ul> </ul>
<p>If you enabled these extensions:</p> <p>If you enabled these extensions:</p>
<p>2 . Query device for pointers to following 2 extension functions, using <code>vkGetDeviceProcAddr()</code>. Pass them in structure <a class="el" href="struct_vma_vulkan_functions.html" title="Pointers to some Vulkan functions - a subset used by the library. ">VmaVulkanFunctions</a> while creating your <code>VmaAllocator</code>.</p> <p>2 . Use <code>VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT</code> flag when creating your <code>VmaAllocator</code> to inform the library that you enabled required extensions and you want the library to use them.</p>
<ul>
<li><code>vkGetBufferMemoryRequirements2KHR</code></li>
<li><code>vkGetImageMemoryRequirements2KHR</code></li>
</ul>
<p>Other members of this structure can be null as long as you leave <code>VMA_STATIC_VULKAN_FUNCTIONS</code> defined to 1, which is the default.</p>
<div class="fragment"><div class="line"><a class="code" href="struct_vma_vulkan_functions.html">VmaVulkanFunctions</a> vulkanFunctions = {};</div><div class="line">vulkanFunctions.<a class="code" href="struct_vma_vulkan_functions.html#a9d8d1b05d2b1e7e1d9b27f6f585acf9c">vkGetBufferMemoryRequirements2KHR</a> =</div><div class="line"> (PFN_vkGetBufferMemoryRequirements2KHR)vkGetDeviceProcAddr(device, <span class="stringliteral">&quot;vkGetBufferMemoryRequirements2KHR&quot;</span>);</div><div class="line">vulkanFunctions.<a class="code" href="struct_vma_vulkan_functions.html#a9cdcdc1e2b2ea7c571f7d27e30ba6875">vkGetImageMemoryRequirements2KHR</a> =</div><div class="line"> (PFN_vkGetImageMemoryRequirements2KHR)vkGetDeviceProcAddr(device, <span class="stringliteral">&quot;vkGetImageMemoryRequirements2KHR&quot;</span>);</div><div class="line"> </div><div class="line"><a class="code" href="struct_vma_allocator_create_info.html">VmaAllocatorCreateInfo</a> allocatorInfo = {};</div><div class="line">allocatorInfo.<a class="code" href="struct_vma_allocator_create_info.html#a3dc197be3227da7338b1643f70db36bd">pVulkanFunctions</a> = &amp;vulkanFunctions;</div><div class="line"><span class="comment">// Fill other members of allocatorInfo...</span></div></div><!-- fragment --><p>3 . Use <code>VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT</code> flag when creating your <code>VmaAllocator</code> to inform the library that you enabled required extensions and you want the library to use them.</p>
<div class="fragment"><div class="line">allocatorInfo.<a class="code" href="struct_vma_allocator_create_info.html#a392ea2ecbaff93f91a7c49f735ad4346">flags</a> |= <a class="code" href="vk__mem__alloc_8h.html#a4f87c9100d154a65a4ad495f7763cf7cace7da7cc6e71a625dfa763c55a597878">VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT</a>;</div><div class="line"></div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#a200692051ddb34240248234f5f4c17bb">vmaCreateAllocator</a>(&amp;allocatorInfo, &amp;allocator);</div></div><!-- fragment --><p>That's all. The extension will be automatically used whenever you create a buffer using <a class="el" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer()</a> or image using <a class="el" href="vk__mem__alloc_8h.html#a02a94f25679275851a53e82eacbcfc73" title="Function similar to vmaCreateBuffer(). ">vmaCreateImage()</a>.</p> <div class="fragment"><div class="line">allocatorInfo.<a class="code" href="struct_vma_allocator_create_info.html#a392ea2ecbaff93f91a7c49f735ad4346">flags</a> |= <a class="code" href="vk__mem__alloc_8h.html#a4f87c9100d154a65a4ad495f7763cf7cace7da7cc6e71a625dfa763c55a597878">VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT</a>;</div><div class="line"></div><div class="line"><a class="code" href="vk__mem__alloc_8h.html#a200692051ddb34240248234f5f4c17bb">vmaCreateAllocator</a>(&amp;allocatorInfo, &amp;allocator);</div></div><!-- fragment --><p>That's all. The extension will be automatically used whenever you create a buffer using <a class="el" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer()</a> or image using <a class="el" href="vk__mem__alloc_8h.html#a02a94f25679275851a53e82eacbcfc73" title="Function similar to vmaCreateBuffer(). ">vmaCreateImage()</a>.</p>
<p>When using the extension together with Vulkan Validation Layer, you will receive warnings like this: </p><pre class="fragment">vkBindBufferMemory(): Binding memory to buffer 0x33 but vkGetBufferMemoryRequirements() has not been called on that buffer. <p>When using the extension together with Vulkan Validation Layer, you will receive warnings like this: </p><pre class="fragment">vkBindBufferMemory(): Binding memory to buffer 0x33 but vkGetBufferMemoryRequirements() has not been called on that buffer.
</pre><p>It is OK, you should just ignore it. It happens because you use function <code>vkGetBufferMemoryRequirements2KHR()</code> instead of standard <code>vkGetBufferMemoryRequirements()</code>, while the validation layer seems to be unaware of it.</p> </pre><p>It is OK, you should just ignore it. It happens because you use function <code>vkGetBufferMemoryRequirements2KHR()</code> instead of standard <code>vkGetBufferMemoryRequirements()</code>, while the validation layer seems to be unaware of it.</p>

203
src/vk_mem_alloc.h
View File

@ -40,6 +40,7 @@ Table of contents:
- User guide - User guide
- \subpage quick_start - \subpage quick_start
- \subpage choosing_memory_type
- \subpage memory_mapping - \subpage memory_mapping
- \subpage custom_memory_pools - \subpage custom_memory_pools
- \subpage defragmentation - \subpage defragmentation
@ -118,6 +119,121 @@ vmaDestroyBuffer(allocator, buffer, allocation);
vmaDestroyAllocator(allocator); vmaDestroyAllocator(allocator);
\endcode \endcode
\page choosing_memory_type Choosing memory type
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 VmaAllocationCreateInfo structure, as described below.
You can also combine multiple methods.
-# If you just want to find memory type index that meets your requirements, you
can use function vmaFindMemoryTypeIndex().
-# If you want to allocate a region of device memory without association with any
specific image or buffer, you can use function vmaAllocateMemory(). Usage of
this function is not recommended and usually not needed.
-# 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
vmaAllocateMemoryForBuffer(), vmaAllocateMemoryForImage().
-# 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 vmaCreateBuffer(),
vmaCreateImage(). This is the recommended way to use this library.
When using 3. or 4., the library internally queries Vulkan for memory types
supported for that buffer or image (function `vkGetBufferMemoryRequirements()`)
and uses only one of these types.
If no memory type can be found that meets all the requirements, these functions
return `VK_ERROR_FEATURE_NOT_PRESENT`.
You can leave VmaAllocationCreateInfo structure completely filled with zeros.
It means no requirements are specified for memory type.
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`.
It defines high level, common usage types.
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:
\code
VkBufferCreateInfo bufferInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
bufferInfo.size = 65536;
bufferInfo.usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;
VmaAllocationCreateInfo allocInfo = {};
allocInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;
VkBuffer buffer;
VmaAllocation allocation;
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
\endcode
\section choosing_memory_type_required_preferred_flags Required and preferred flags
You can specify more detailed requirements by filling members
VmaAllocationCreateInfo::requiredFlags and VmaAllocationCreateInfo::preferredFlags
with a combination of bits from enum `VkMemoryPropertyFlags`. For example,
if you want to create a buffer that will be persistently mapped on host (so it
must be `HOST_VISIBLE`) and preferably will also be `HOST_COHERENT` and `HOST_CACHED`,
use following code:
\code
VmaAllocationCreateInfo allocInfo = {};
allocInfo.requiredFlags = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT;
allocInfo.preferredFlags = VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | VK_MEMORY_PROPERTY_HOST_CACHED_BIT;
allocInfo.flags = VMA_ALLOCATION_CREATE_MAPPED_BIT;
VkBuffer buffer;
VmaAllocation allocation;
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
\endcode
A memory type is chosen that has all the required flags and as many preferred
flags set as possible.
If you use VmaAllocationCreateInfo::usage, it is just internally converted to
a set of required and preferred flags.
\section choosing_memory_type_explicit_memory_types Explicit memory types
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
VmaAllocationCreateInfo::memoryTypeBits. 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 UINT32_MAX, means there are no
restrictions to memory type index.
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:
\code
uint32_t memoryTypeIndex = 2;
VmaAllocationCreateInfo allocInfo = {};
allocInfo.memoryTypeBits = 1u << memoryTypeIndex;
VkBuffer buffer;
VmaAllocation allocation;
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
\endcode
\section choosing_memory_type_custom_memory_pools Custom memory pools
If you allocate from custom memory pool, all the ways of specifying memory
requirements described above are not applicable and the aforementioned members
of VmaAllocationCreateInfo 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 \ref custom_memory_pools.
\page memory_mapping Memory mapping \page memory_mapping Memory mapping
\section persistently_mapped_memory Persistently mapped memory \section persistently_mapped_memory Persistently mapped memory
@ -839,18 +955,42 @@ VK_DEFINE_HANDLE(VmaPool)
typedef enum VmaMemoryUsage typedef enum VmaMemoryUsage
{ {
/// No intended memory usage specified. Use other members of VmaAllocationCreateInfo to specify your requirements. /** No intended memory usage specified.
Use other members of VmaAllocationCreateInfo to specify your requirements.
*/
VMA_MEMORY_USAGE_UNKNOWN = 0, VMA_MEMORY_USAGE_UNKNOWN = 0,
/// Memory will be used on device only, so faster access from the device is preferred. No need to be mappable on host. /** Memory will be used on device only, so faster access from the device is preferred.
It usually means device-local GPU memory.
No need to be mappable on host.
Good e.g. for images to be used as attachments, images containing textures to be sampled,
buffers used as vertex buffer, index buffer, uniform buffer and majority of
other types of resources used by device.
You can still do transfers from/to such resource to/from host memory.
The allocation may still end up in `HOST_VISIBLE` memory on some implementations.
In such case, you are free to map it.
You can also use `VMA_ALLOCATION_CREATE_MAPPED_BIT` with this usage type.
*/
VMA_MEMORY_USAGE_GPU_ONLY = 1, VMA_MEMORY_USAGE_GPU_ONLY = 1,
/// Memory will be mapped on host. Could be used for transfer to/from device. /** Memory will be mapped and used on host.
/** Guarantees to be `HOST_VISIBLE` and `HOST_COHERENT`. */ It usually means CPU system memory.
Could be used for transfer to/from device.
Good e.g. for "staging" copy of buffers and images, used as transfer source or destination.
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`.
*/
VMA_MEMORY_USAGE_CPU_ONLY = 2, VMA_MEMORY_USAGE_CPU_ONLY = 2,
/// Memory will be used for frequent (dynamic) updates from host and reads on device (upload). /** Memory will be used for frequent (dynamic) updates from host and reads on device (upload).
/** Guarantees to be `HOST_VISIBLE`. */ Good e.g. for vertex buffers or uniform buffers updated every frame.
Guarantees to be `HOST_VISIBLE`.
*/
VMA_MEMORY_USAGE_CPU_TO_GPU = 3, VMA_MEMORY_USAGE_CPU_TO_GPU = 3,
/// Memory will be used for frequent writing on device and readback on host (download). /** Memory will be used for frequent writing on device and readback on host (download).
/** Guarantees to be `HOST_VISIBLE`. */
Guarantees to be `HOST_VISIBLE`.
*/
VMA_MEMORY_USAGE_GPU_TO_CPU = 4, VMA_MEMORY_USAGE_GPU_TO_CPU = 4,
VMA_MEMORY_USAGE_MAX_ENUM = 0x7FFFFFFF VMA_MEMORY_USAGE_MAX_ENUM = 0x7FFFFFFF
} VmaMemoryUsage; } VmaMemoryUsage;
@ -930,28 +1070,41 @@ typedef struct VmaAllocationCreateInfo
VmaAllocationCreateFlags flags; VmaAllocationCreateFlags flags;
/** \brief Intended usage of memory. /** \brief Intended usage of memory.
Leave `VMA_MEMORY_USAGE_UNKNOWN` if you specify `requiredFlags`. You can also use both. \n You can leave `VMA_MEMORY_USAGE_UNKNOWN` if you specify memory requirements in other way. \n
If `pool` is not null, this member is ignored. If `pool` is not null, this member is ignored.
*/ */
VmaMemoryUsage usage; VmaMemoryUsage usage;
/** \brief Flags that must be set in a Memory Type chosen for an allocation. /** \brief Flags that must be set in a Memory Type chosen for an allocation.
Leave 0 if you specify requirement via usage. \n Leave 0 if you specify memory requirements in other way. \n
If `pool` is not null, this member is ignored.*/ If `pool` is not null, this member is ignored.*/
VkMemoryPropertyFlags requiredFlags; VkMemoryPropertyFlags requiredFlags;
/** \brief Flags that preferably should be set in a Memory Type chosen for an allocation. /** \brief Flags that preferably should be set in a memory type chosen for an allocation.
Set to 0 if no additional flags are prefered and only `requiredFlags` should be used. \n Set to 0 if no additional flags are prefered. \n
If not 0, it must be a superset or equal to `requiredFlags`. \n
If `pool` is not null, this member is ignored. */ If `pool` is not null, this member is ignored. */
VkMemoryPropertyFlags preferredFlags; VkMemoryPropertyFlags preferredFlags;
/** \brief Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo::pUserData and changed using vmaSetAllocationUserData(). */ /** \brief Bitmask containing one bit set for every memory type acceptable for this allocation.
void* pUserData;
Value 0 is equivalent to `UINT32_MAX` - it means any memory type is accepted if
it meets other requirements specified by this structure, with no further
restrictions on memory type index. \n
If `pool` is not null, this member is ignored.
*/
uint32_t memoryTypeBits;
/** \brief Pool that this allocation should be created in. /** \brief Pool that this allocation should be created in.
Leave `VK_NULL_HANDLE` to allocate from general memory. Leave `VK_NULL_HANDLE` to allocate from default pool. If not null, members:
`usage`, `requiredFlags`, `preferredFlags`, `memoryTypeBits` are ignored.
*/ */
VmaPool pool; VmaPool pool;
/** \brief Custom general-purpose pointer that will be stored in VmaAllocation, can be read as VmaAllocationInfo::pUserData and changed using vmaSetAllocationUserData().
If `VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT` is used, it must be either
null or pointer to a null-terminated string. The string will be then copied to
internal buffer, so it doesn't need to be valid after allocation call.
*/
void* pUserData;
} VmaAllocationCreateInfo; } VmaAllocationCreateInfo;
/** /**
@ -1734,7 +1887,7 @@ static VkAllocationCallbacks VmaEmptyAllocationCallbacks = {
VMA_NULL, VMA_NULL, VMA_NULL, VMA_NULL, VMA_NULL, VMA_NULL }; VMA_NULL, VMA_NULL, VMA_NULL, VMA_NULL, VMA_NULL, VMA_NULL };
// Returns number of bits set to 1 in (v). // Returns number of bits set to 1 in (v).
static inline uint32_t CountBitsSet(uint32_t v) static inline uint32_t VmaCountBitsSet(uint32_t v)
{ {
uint32_t c = v - ((v >> 1) & 0x55555555); uint32_t c = v - ((v >> 1) & 0x55555555);
c = ((c >> 2) & 0x33333333) + (c & 0x33333333); c = ((c >> 2) & 0x33333333) + (c & 0x33333333);
@ -7857,7 +8010,8 @@ void vmaFreeStatsString(
#endif // #if VMA_STATS_STRING_ENABLED #endif // #if VMA_STATS_STRING_ENABLED
/** This function is not protected by any mutex because it just reads immutable data. /*
This function is not protected by any mutex because it just reads immutable data.
*/ */
VkResult vmaFindMemoryTypeIndex( VkResult vmaFindMemoryTypeIndex(
VmaAllocator allocator, VmaAllocator allocator,
@ -7869,14 +8023,13 @@ VkResult vmaFindMemoryTypeIndex(
VMA_ASSERT(pAllocationCreateInfo != VMA_NULL); VMA_ASSERT(pAllocationCreateInfo != VMA_NULL);
VMA_ASSERT(pMemoryTypeIndex != VMA_NULL); VMA_ASSERT(pMemoryTypeIndex != VMA_NULL);
if(pAllocationCreateInfo->memoryTypeBits != 0)
{
memoryTypeBits &= pAllocationCreateInfo->memoryTypeBits;
}
uint32_t requiredFlags = pAllocationCreateInfo->requiredFlags; uint32_t requiredFlags = pAllocationCreateInfo->requiredFlags;
uint32_t preferredFlags = pAllocationCreateInfo->preferredFlags; uint32_t preferredFlags = pAllocationCreateInfo->preferredFlags;
if(preferredFlags == 0)
{
preferredFlags = requiredFlags;
}
// preferredFlags, if not 0, must be a superset of requiredFlags.
VMA_ASSERT((requiredFlags & ~preferredFlags) == 0);
// Convert usage to requiredFlags and preferredFlags. // Convert usage to requiredFlags and preferredFlags.
switch(pAllocationCreateInfo->usage) switch(pAllocationCreateInfo->usage)
@ -7916,7 +8069,7 @@ VkResult vmaFindMemoryTypeIndex(
if((requiredFlags & ~currFlags) == 0) if((requiredFlags & ~currFlags) == 0)
{ {
// Calculate cost as number of bits from preferredFlags not present in this memory type. // Calculate cost as number of bits from preferredFlags not present in this memory type.
uint32_t currCost = CountBitsSet(preferredFlags & ~currFlags); uint32_t currCost = VmaCountBitsSet(preferredFlags & ~currFlags);
// Remember memory type with lowest cost. // Remember memory type with lowest cost.
if(currCost < minCost) if(currCost < minCost)
{ {