AuroraMiddleware/VulkanMemoryAllocator
1
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator synced 2024-11-21 20:00:11 +00:00
Code Issues Projects Releases Wiki Activity
master
VulkanMemoryAllocator/docs/html/quick_start.html
Adam Sawicki eb46f62376 Added documentation for VK_KHR_external_memory_win32 
Rebuilt the documentation.
2024-08-28 13:20:19 +02:00

248 lines
29 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.11.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Vulkan Memory Allocator: Quick start</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">Vulkan Memory Allocator
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.11.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @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:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search',false);
$(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function(){ initResizable(false); });
/* @license-end */
</script>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Vulkan Memory Allocator</a></li> </ul>
</div>
</div><!-- top -->
<div id="doc-content">
<div><div class="header">
<div class="headertitle"><div class="title">Quick start</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="quick_start_project_setup"></a>
Project setup</h1>
<p>Vulkan Memory Allocator comes in form of a "stb-style" single header file. While you can pull the entire repository e.g. as Git module, there is also Cmake script provided, you don't need to build it as a separate library project. You can add file "vk_mem_alloc.h" directly to your project and submit it to code repository next to your other source files.</p>
<p>"Single header" doesn't mean that everything is contained in C/C++ declarations, like it tends to be in case of inline functions or C++ templates. It means that implementation is bundled with interface in a single file and needs to be extracted using preprocessor macro. If you don't do it properly, it will result in linker errors.</p>
<p>To do it properly:</p>
<ol type="1">
<li>Include "vk_mem_alloc.h" file in each CPP file where you want to use the library. This includes declarations of all members of the library.</li>
<li>In exactly one CPP file define following macro before this include. It enables also internal definitions.</li>
</ol>
<div class="fragment"><div class="line"><span class="preprocessor">#define VMA_IMPLEMENTATION</span></div>
<div class="line"><span class="preprocessor">#include &quot;<a class="code" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a>&quot;</span></div>
<div class="ttc" id="avk__mem__alloc_8h_html"><div class="ttname"><a href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a></div></div>
</div><!-- fragment --><p>It may be a good idea to create dedicated CPP file just for this purpose, e.g. "VmaUsage.cpp".</p>
<p>This library includes header <code>&lt;vulkan/vulkan.h&gt;</code>, which in turn includes <code>&lt;windows.h&gt;</code> on Windows. If you need some specific macros defined before including these headers (like <code>WIN32_LEAN_AND_MEAN</code> or <code>WINVER</code> for Windows, <code>VK_USE_PLATFORM_WIN32_KHR</code> for Vulkan), you must define them before every <code>#include</code> of this library. It may be a good idea to create a dedicate header file for this purpose, e.g. "VmaUsage.h", that will be included in other source files instead of VMA header directly.</p>
<p>This library is written in C++, but has C-compatible interface. Thus, you can include and use "vk_mem_alloc.h" in C or C++ code, but full implementation with <code>VMA_IMPLEMENTATION</code> macro must be compiled as C++, NOT as C. Some features of C++14 are used and required. Features of C++20 are used optionally when available. Some headers of standard C and C++ library are used, but STL containers, RTTI, or C++ exceptions are not used.</p>
<h1><a class="anchor" id="quick_start_initialization"></a>
Initialization</h1>
<p>VMA offers library interface in a style similar to Vulkan, with object handles like <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a>, structures describing parameters of objects to be created like <a class="el" href="struct_vma_allocation_create_info.html" title="Parameters of new VmaAllocation.">VmaAllocationCreateInfo</a>, and errors codes returned from functions using <code>VkResult</code> type.</p>
<p>The first and the main object that needs to be created is <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a>. It represents the initialization of the entire library. Only one such object should be created per <code>VkDevice</code>. You should create it at program startup, after <code>VkDevice</code> was created, and before any device memory allocator needs to be made. It must be destroyed before <code>VkDevice</code> is destroyed.</p>
<p>At program startup:</p>
<ol type="1">
<li>Initialize Vulkan to have <code>VkInstance</code>, <code>VkPhysicalDevice</code>, <code>VkDevice</code> object.</li>
<li>Fill <a class="el" href="struct_vma_allocator_create_info.html" title="Description of a Allocator to be created.">VmaAllocatorCreateInfo</a> structure and call <a class="el" href="group__group__init.html#ga200692051ddb34240248234f5f4c17bb" title="Creates VmaAllocator object.">vmaCreateAllocator()</a> to create <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a> object.</li>
</ol>
<p>Only members <code>physicalDevice</code>, <code>device</code>, <code>instance</code> are required. However, you should inform the library which Vulkan version do you use by setting <a class="el" href="struct_vma_allocator_create_info.html#ae0ffc55139b54520a6bb704b29ffc285" title="Optional. Vulkan version that the application uses.">VmaAllocatorCreateInfo::vulkanApiVersion</a> and which extensions did you enable by setting <a class="el" href="struct_vma_allocator_create_info.html#a392ea2ecbaff93f91a7c49f735ad4346" title="Flags for created allocator. Use VmaAllocatorCreateFlagBits enum.">VmaAllocatorCreateInfo::flags</a>. Otherwise, VMA would use only features of Vulkan 1.0 core with no extensions. See below for details.</p>
<h2><a class="anchor" id="quick_start_initialization_selecting_vulkan_version"></a>
Selecting Vulkan version</h2>
<p>VMA supports Vulkan version down to 1.0, for backward compatibility. If you want to use higher version, you need to inform the library about it. This is a two-step process.</p>
<p><b>Step 1: Compile time.</b> By default, VMA compiles with code supporting the highest Vulkan version found in the included <code>&lt;vulkan/vulkan.h&gt;</code> that is also supported by the library. If this is OK, you don't need to do anything. However, if you want to compile VMA as if only some lower Vulkan version was available, define macro <code>VMA_VULKAN_VERSION</code> before every <code>#include "vk_mem_alloc.h"</code>. It should have decimal numeric value in form of ABBBCCC, where A = major, BBB = minor, CCC = patch Vulkan version. For example, to compile against Vulkan 1.2:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define VMA_VULKAN_VERSION 1002000 </span><span class="comment">// Vulkan 1.2</span></div>
<div class="line"><span class="preprocessor">#include &quot;<a class="code" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a>&quot;</span></div>
</div><!-- fragment --><p><b>Step 2: Runtime.</b> Even when compiled with higher Vulkan version available, VMA can use only features of a lower version, which is configurable during creation of the <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a> object. By default, only Vulkan 1.0 is used. To initialize the allocator with support for higher Vulkan version, you need to set member <a class="el" href="struct_vma_allocator_create_info.html#ae0ffc55139b54520a6bb704b29ffc285" title="Optional. Vulkan version that the application uses.">VmaAllocatorCreateInfo::vulkanApiVersion</a> to an appropriate value, e.g. using constants like <code>VK_API_VERSION_1_2</code>. See code sample below.</p>
<h2><a class="anchor" id="quick_start_initialization_importing_vulkan_functions"></a>
Importing Vulkan functions</h2>
<p>You may need to configure importing Vulkan functions. There are 3 ways to do this:</p>
<ol type="1">
<li><b>If you link with Vulkan static library</b> (e.g. "vulkan-1.lib" on Windows):<ul>
<li>You don't need to do anything.</li>
<li>VMA will use these, as macro <code>VMA_STATIC_VULKAN_FUNCTIONS</code> is defined to 1 by default.</li>
</ul>
</li>
<li><b>If you want VMA to fetch pointers to Vulkan functions dynamically</b> using <code>vkGetInstanceProcAddr</code>, <code>vkGetDeviceProcAddr</code> (this is the option presented in the example below):<ul>
<li>Define <code>VMA_STATIC_VULKAN_FUNCTIONS</code> to 0, <code>VMA_DYNAMIC_VULKAN_FUNCTIONS</code> to 1.</li>
<li>Provide pointers to these two functions via <a class="el" href="struct_vma_vulkan_functions.html#a3eafa102f5f8915f093f40675636b849" title="Required when using VMA_DYNAMIC_VULKAN_FUNCTIONS.">VmaVulkanFunctions::vkGetInstanceProcAddr</a>, <a class="el" href="struct_vma_vulkan_functions.html#ac383ab9af127e5e136622fa4ebea9e57" title="Required when using VMA_DYNAMIC_VULKAN_FUNCTIONS.">VmaVulkanFunctions::vkGetDeviceProcAddr</a>.</li>
<li>The library will fetch pointers to all other functions it needs internally.</li>
</ul>
</li>
<li><b>If you fetch pointers to all Vulkan functions in a custom way</b>, e.g. using some loader like <a href="https://github.com/zeux/volk">Volk</a>:<ul>
<li>Define <code>VMA_STATIC_VULKAN_FUNCTIONS</code> and <code>VMA_DYNAMIC_VULKAN_FUNCTIONS</code> to 0.</li>
<li>Pass these pointers via structure <a class="el" href="struct_vma_vulkan_functions.html" title="Pointers to some Vulkan functions - a subset used by the library.">VmaVulkanFunctions</a>.</li>
</ul>
</li>
</ol>
<h2><a class="anchor" id="quick_start_initialization_enabling_extensions"></a>
Enabling extensions</h2>
<p>VMA can automatically use following Vulkan extensions. If you found them available on the selected physical device and you enabled them while creating <code>VkInstance</code> / <code>VkDevice</code> object, inform VMA about their availability by setting appropriate flags in <a class="el" href="struct_vma_allocator_create_info.html#a392ea2ecbaff93f91a7c49f735ad4346" title="Flags for created allocator. Use VmaAllocatorCreateFlagBits enum.">VmaAllocatorCreateInfo::flags</a>.</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">Vulkan extension </th><th class="markdownTableHeadNone">VMA flag </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">VK_KHR_dedicated_allocation </td><td class="markdownTableBodyNone"><a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7cace7da7cc6e71a625dfa763c55a597878" title="Enables usage of VK_KHR_dedicated_allocation extension.">VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT</a> </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">VK_KHR_bind_memory2 </td><td class="markdownTableBodyNone"><a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7ca8fb75bf07cd184ab903596295e863dee">VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT</a> </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">VK_KHR_maintenance4 </td><td class="markdownTableBodyNone"><a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7caa2566e7f75e19ae7ec9c4fa509fea5fb">VMA_ALLOCATOR_CREATE_KHR_MAINTENANCE4_BIT</a> </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">VK_KHR_maintenance5 </td><td class="markdownTableBodyNone"><a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7caca82d4ce40bdb59d3da52a539c21d6b8">VMA_ALLOCATOR_CREATE_KHR_MAINTENANCE5_BIT</a> </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">VK_EXT_memory_budget </td><td class="markdownTableBodyNone"><a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7ca4d4687863f7bd4b418c6006dc04400b0">VMA_ALLOCATOR_CREATE_EXT_MEMORY_BUDGET_BIT</a> </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">VK_KHR_buffer_device_address </td><td class="markdownTableBodyNone"><a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7ca5f1b28b0414319d1687e1f2b30ab0089">VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT</a> </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">VK_EXT_memory_priority </td><td class="markdownTableBodyNone"><a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7caffdd7a5169be3dbd7cbf6b3619e4f78a">VMA_ALLOCATOR_CREATE_EXT_MEMORY_PRIORITY_BIT</a> </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">VK_AMD_device_coherent_memory </td><td class="markdownTableBodyNone"><a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7ca2acce4886d8078552efa38878413970f">VMA_ALLOCATOR_CREATE_AMD_DEVICE_COHERENT_MEMORY_BIT</a> </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">VK_KHR_external_memory_win32 </td><td class="markdownTableBodyNone"><a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7ca4897d1181a186e327f4dadd680ad00ac">VMA_ALLOCATOR_CREATE_KHR_EXTERNAL_MEMORY_WIN32_BIT</a> </td></tr>
</table>
<p>Example with fetching pointers to Vulkan functions dynamically:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define VMA_STATIC_VULKAN_FUNCTIONS 0</span></div>
<div class="line"><span class="preprocessor">#define VMA_DYNAMIC_VULKAN_FUNCTIONS 1</span></div>
<div class="line"><span class="preprocessor">#include &quot;<a class="code" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a>&quot;</span></div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line"> </div>
<div class="line">VmaVulkanFunctions vulkanFunctions = {};</div>
<div class="line">vulkanFunctions.vkGetInstanceProcAddr = &amp;vkGetInstanceProcAddr;</div>
<div class="line">vulkanFunctions.vkGetDeviceProcAddr = &amp;vkGetDeviceProcAddr;</div>
<div class="line"> </div>
<div class="line"><a class="code hl_struct" href="struct_vma_allocator_create_info.html">VmaAllocatorCreateInfo</a> allocatorCreateInfo = {};</div>
<div class="line">allocatorCreateInfo.<a class="code hl_variable" href="struct_vma_allocator_create_info.html#a392ea2ecbaff93f91a7c49f735ad4346">flags</a> = <a class="code hl_enumvalue" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7ca4d4687863f7bd4b418c6006dc04400b0">VMA_ALLOCATOR_CREATE_EXT_MEMORY_BUDGET_BIT</a>;</div>
<div class="line">allocatorCreateInfo.<a class="code hl_variable" href="struct_vma_allocator_create_info.html#ae0ffc55139b54520a6bb704b29ffc285">vulkanApiVersion</a> = VK_API_VERSION_1_2;</div>
<div class="line">allocatorCreateInfo.<a class="code hl_variable" href="struct_vma_allocator_create_info.html#a08230f04ae6ccf8a78150a9e829a7156">physicalDevice</a> = physicalDevice;</div>
<div class="line">allocatorCreateInfo.<a class="code hl_variable" href="struct_vma_allocator_create_info.html#ad924ddd77b04039c88d0c09b0ffcd500">device</a> = device;</div>
<div class="line">allocatorCreateInfo.<a class="code hl_variable" href="struct_vma_allocator_create_info.html#a70dd42e29b1df1d1b9b61532ae0b370b">instance</a> = instance;</div>
<div class="line">allocatorCreateInfo.<a class="code hl_variable" href="struct_vma_allocator_create_info.html#a3dc197be3227da7338b1643f70db36bd">pVulkanFunctions</a> = &amp;vulkanFunctions;</div>
<div class="line"> </div>
<div class="line"><a class="code hl_struct" href="struct_vma_allocator.html">VmaAllocator</a> allocator;</div>
<div class="line"><a class="code hl_function" href="group__group__init.html#ga200692051ddb34240248234f5f4c17bb">vmaCreateAllocator</a>(&amp;allocatorCreateInfo, &amp;allocator);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Entire program...</span></div>
<div class="line"> </div>
<div class="line"><span class="comment">// At the end, don&#39;t forget to:</span></div>
<div class="line"><a class="code hl_function" href="group__group__init.html#gaa8d164061c88f22fb1fd3c8f3534bc1d">vmaDestroyAllocator</a>(allocator);</div>
<div class="ttc" id="agroup__group__init_html_ga200692051ddb34240248234f5f4c17bb"><div class="ttname"><a href="group__group__init.html#ga200692051ddb34240248234f5f4c17bb">vmaCreateAllocator</a></div><div class="ttdeci">VkResult vmaCreateAllocator(const VmaAllocatorCreateInfo *pCreateInfo, VmaAllocator *pAllocator)</div><div class="ttdoc">Creates VmaAllocator object.</div></div>
<div class="ttc" id="agroup__group__init_html_gaa8d164061c88f22fb1fd3c8f3534bc1d"><div class="ttname"><a href="group__group__init.html#gaa8d164061c88f22fb1fd3c8f3534bc1d">vmaDestroyAllocator</a></div><div class="ttdeci">void vmaDestroyAllocator(VmaAllocator allocator)</div><div class="ttdoc">Destroys allocator object.</div></div>
<div class="ttc" id="agroup__group__init_html_gga4f87c9100d154a65a4ad495f7763cf7ca4d4687863f7bd4b418c6006dc04400b0"><div class="ttname"><a href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7ca4d4687863f7bd4b418c6006dc04400b0">VMA_ALLOCATOR_CREATE_EXT_MEMORY_BUDGET_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATOR_CREATE_EXT_MEMORY_BUDGET_BIT</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:405</div></div>
<div class="ttc" id="astruct_vma_allocator_create_info_html"><div class="ttname"><a href="struct_vma_allocator_create_info.html">VmaAllocatorCreateInfo</a></div><div class="ttdoc">Description of a Allocator to be created.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1066</div></div>
<div class="ttc" id="astruct_vma_allocator_create_info_html_a08230f04ae6ccf8a78150a9e829a7156"><div class="ttname"><a href="struct_vma_allocator_create_info.html#a08230f04ae6ccf8a78150a9e829a7156">VmaAllocatorCreateInfo::physicalDevice</a></div><div class="ttdeci">VkPhysicalDevice physicalDevice</div><div class="ttdoc">Vulkan physical device.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1071</div></div>
<div class="ttc" id="astruct_vma_allocator_create_info_html_a392ea2ecbaff93f91a7c49f735ad4346"><div class="ttname"><a href="struct_vma_allocator_create_info.html#a392ea2ecbaff93f91a7c49f735ad4346">VmaAllocatorCreateInfo::flags</a></div><div class="ttdeci">VmaAllocatorCreateFlags flags</div><div class="ttdoc">Flags for created allocator. Use VmaAllocatorCreateFlagBits enum.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1068</div></div>
<div class="ttc" id="astruct_vma_allocator_create_info_html_a3dc197be3227da7338b1643f70db36bd"><div class="ttname"><a href="struct_vma_allocator_create_info.html#a3dc197be3227da7338b1643f70db36bd">VmaAllocatorCreateInfo::pVulkanFunctions</a></div><div class="ttdeci">const VmaVulkanFunctions * pVulkanFunctions</div><div class="ttdoc">Pointers to Vulkan functions. Can be null.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1114</div></div>
<div class="ttc" id="astruct_vma_allocator_create_info_html_a70dd42e29b1df1d1b9b61532ae0b370b"><div class="ttname"><a href="struct_vma_allocator_create_info.html#a70dd42e29b1df1d1b9b61532ae0b370b">VmaAllocatorCreateInfo::instance</a></div><div class="ttdeci">VkInstance instance</div><div class="ttdoc">Handle to Vulkan instance object.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1119</div></div>
<div class="ttc" id="astruct_vma_allocator_create_info_html_ad924ddd77b04039c88d0c09b0ffcd500"><div class="ttname"><a href="struct_vma_allocator_create_info.html#ad924ddd77b04039c88d0c09b0ffcd500">VmaAllocatorCreateInfo::device</a></div><div class="ttdeci">VkDevice device</div><div class="ttdoc">Vulkan device.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1074</div></div>
<div class="ttc" id="astruct_vma_allocator_create_info_html_ae0ffc55139b54520a6bb704b29ffc285"><div class="ttname"><a href="struct_vma_allocator_create_info.html#ae0ffc55139b54520a6bb704b29ffc285">VmaAllocatorCreateInfo::vulkanApiVersion</a></div><div class="ttdeci">uint32_t vulkanApiVersion</div><div class="ttdoc">Optional. Vulkan version that the application uses.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1130</div></div>
<div class="ttc" id="astruct_vma_allocator_html"><div class="ttname"><a href="struct_vma_allocator.html">VmaAllocator</a></div><div class="ttdoc">Represents main object of this library initialized.</div></div>
</div><!-- fragment --><h2><a class="anchor" id="quick_start_initialization_other_config"></a>
Other configuration options</h2>
<p>There are additional configuration options available through preprocessor macros that you can define before including VMA header and through parameters passed in <a class="el" href="struct_vma_allocator_create_info.html" title="Description of a Allocator to be created.">VmaAllocatorCreateInfo</a>. They include a possibility to use your own callbacks for host memory allocations (<code>VkAllocationCallbacks</code>), callbacks for device memory allocations (instead of <code>vkAllocateMemory</code>, <code>vkFreeMemory</code>), or your custom <code>VMA_ASSERT</code> macro, among others. For more information, see: <a class="el" href="configuration.html">Configuration</a>.</p>
<h1><a class="anchor" id="quick_start_resource_allocation"></a>
Resource allocation</h1>
<p>When you want to create a buffer or image:</p>
<ol type="1">
<li>Fill <code>VkBufferCreateInfo</code> / <code>VkImageCreateInfo</code> structure.</li>
<li>Fill <a class="el" href="struct_vma_allocation_create_info.html" title="Parameters of new VmaAllocation.">VmaAllocationCreateInfo</a> structure.</li>
<li>Call <a class="el" href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51" title="Creates a new VkBuffer, allocates and binds memory for it.">vmaCreateBuffer()</a> / <a class="el" href="group__group__alloc.html#ga02a94f25679275851a53e82eacbcfc73" title="Function similar to vmaCreateBuffer().">vmaCreateImage()</a> to get <code>VkBuffer</code>/<code>VkImage</code> with memory already allocated and bound to it, plus <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> objects that represents its underlying memory.</li>
</ol>
<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_VERTEX_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;</div>
<div class="line"> </div>
<div class="line"><a class="code hl_struct" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocInfo = {};</div>
<div class="line">allocInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a>;</div>
<div class="line"> </div>
<div class="line">VkBuffer buffer;</div>
<div class="line"><a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> allocation;</div>
<div class="line"><a class="code hl_function" href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a>(allocator, &amp;bufferInfo, &amp;allocInfo, &amp;buffer, &amp;allocation, <span class="keyword">nullptr</span>);</div>
<div class="ttc" id="agroup__group__alloc_html_gac72ee55598617e8eecca384e746bab51"><div class="ttname"><a href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51">vmaCreateBuffer</a></div><div class="ttdeci">VkResult vmaCreateBuffer(VmaAllocator allocator, const VkBufferCreateInfo *pBufferCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkBuffer *pBuffer, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)</div><div class="ttdoc">Creates a new VkBuffer, allocates and binds memory for it.</div></div>
<div class="ttc" id="agroup__group__alloc_html_ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e"><div class="ttname"><a href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a></div><div class="ttdeci">@ VMA_MEMORY_USAGE_AUTO</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:548</div></div>
<div class="ttc" id="astruct_vma_allocation_create_info_html"><div class="ttname"><a href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></div><div class="ttdoc">Parameters of new VmaAllocation.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1289</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:1297</div></div>
<div class="ttc" id="astruct_vma_allocation_html"><div class="ttname"><a href="struct_vma_allocation.html">VmaAllocation</a></div><div class="ttdoc">Represents single memory allocation.</div></div>
</div><!-- fragment --><p>Don't forget to destroy your buffer and allocation objects when no longer needed:</p>
<div class="fragment"><div class="line"><a class="code hl_function" href="group__group__alloc.html#ga0d9f4e4ba5bf9aab1f1c746387753d77">vmaDestroyBuffer</a>(allocator, buffer, allocation);</div>
<div class="ttc" id="agroup__group__alloc_html_ga0d9f4e4ba5bf9aab1f1c746387753d77"><div class="ttname"><a href="group__group__alloc.html#ga0d9f4e4ba5bf9aab1f1c746387753d77">vmaDestroyBuffer</a></div><div class="ttdeci">void vmaDestroyBuffer(VmaAllocator allocator, VkBuffer buffer, VmaAllocation allocation)</div><div class="ttdoc">Destroys Vulkan buffer and frees allocated memory.</div></div>
</div><!-- fragment --><p>If you need to map the buffer, you must set flag <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a9be224df3bfc1cfa06203aed689a30c5">VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT</a> or <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597add61238d98e20917b9a06c617763f492">VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT</a> in <a class="el" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b" title="Use VmaAllocationCreateFlagBits enum.">VmaAllocationCreateInfo::flags</a>. There are many additional parameters that can control the choice of memory type to be used for the allocation and other features. For more information, see documentation chapters: <a class="el" href="choosing_memory_type.html">Choosing memory type</a>, <a class="el" href="memory_mapping.html">Memory mapping</a>. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.11.0
</small></address>
</div><!-- doc-content -->
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink