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

 <!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: Vulkan Memory Allocator</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>
 </div><!-- top -->
 <!-- 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 class="header">
   <div class="headertitle">
 <div class="title">Vulkan Memory Allocator </div>  </div>
 </div><!--header-->
 <div class="contents">
 <div class="textblock"><p>Version 1.0.0 (2017-06-16)</p>
 <p>Members grouped: see <a href="modules.html"><b>Modules</b></a>.</p>
 <p>All members: see <a class="el" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a>.</p>
 <h1><a class="anchor" id="problem"></a>
 Problem Statement</h1>
 <p>Memory allocation and resource (buffer and image) creation in Vulkan is difficult (comparing to older graphics API-s, like D3D11 or OpenGL) for several reasons:</p>
 <ul>
 <li>It requires a lot of boilerplate code, just like everything else in Vulkan, because it is a low-level and high-performance API.</li>
 <li>There is additional level of indirection: VkDeviceMemory is allocated separately from creating VkBuffer/VkImage and they must be bound together. The binding cannot be changed later - resource must be recreated.</li>
 <li>Driver must be queried for supported memory heaps and memory types. Different IHV-s provide different types of it.</li>
 <li>Resources that don't fit in VRAM are not automatically evicted to RAM. Developer must handle out-of-memory errors on his own.</li>
 <li>It is recommended practice to allocate bigger chunks of memory and assign parts of them to particular resources.</li>
 </ul>
 <h1><a class="anchor" id="features"></a>
 Features</h1>
 <p>This library is helps game developers to manage memory allocations and resource creation by offering some higher-level functions. Features of the library could be divided into several layers, low level to high level:</p>
 <ol type="1">
 <li>Functions that help to choose correct and optimal memory type based on intended usage of the memory.<ul>
 <li>Required or preferred traits of the memory are expressed using higher-level description comparing to Vulkan flags.</li>
 </ul>
 </li>
 <li>Functions that allocate memory blocks, reserve and return parts of them (VkDeviceMemory + offset + size) to the user.<ul>
 <li>Library keeps track of allocated memory blocks, used and unused ranges inside them, finds best matching unused ranges for new allocations, takes all the rules of alignment into consideration.</li>
 </ul>
 </li>
 <li>Functions that can create an image/buffer, allocate memory for it and bind them together - all in one call.</li>
 </ol>
 <h1><a class="anchor" id="prequisites"></a>
 Prequisites</h1>
 <ul>
 <li>Self-contained C++ library in single header file. No external dependencies other than standard C and C++ library and of course Vulkan.</li>
 <li>Public interface in C, in same convention as Vulkan API. Implementation in C++.</li>
 <li>Interface documented using Doxygen-style comments.</li>
 <li>Platform-independent, but developed and tested on Windows using Visual Studio.</li>
 <li>Error handling implemented by returning VkResult error codes - same way as in Vulkan.</li>
 </ul>
 <h1><a class="anchor" id="quick_start"></a>
 Quick Start</h1>
 <p>In your project code:</p>
 <ol type="1">
 <li>Include "vk_mem_alloc.h" file wherever you want to use the library.</li>
 <li>In exacly one C++ file define following macro before include to build library implementation.</li>
 </ol>
 <pre class="fragment">#define VMA_IMPLEMENTATION
 #include "vk_mem_alloc.h"
 </pre><p>At program startup:</p>
 <ol type="1">
 <li>Initialize Vulkan to have VkPhysicalDevice and VkDevice 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 create VmaAllocator object by calling <a class="el" href="group__general.html#ga200692051ddb34240248234f5f4c17bb" title="Creates Allocator object. ">vmaCreateAllocator()</a>.</li>
 </ol>
 <pre class="fragment">VmaAllocatorCreateInfo allocatorInfo = {};
 allocatorInfo.physicalDevice = physicalDevice;
 allocatorInfo.device = device;

 VmaAllocator allocator;
 vmaCreateAllocator(&amp;allocatorInfo, &amp;allocator);
 </pre><p>When you want to create a buffer or image:</p>
 <ol type="1">
 <li>Fill VkBufferCreateInfo / VkImageCreateInfo structure.</li>
 <li>Fill <a class="el" href="struct_vma_memory_requirements.html">VmaMemoryRequirements</a> structure.</li>
 <li>Call <a class="el" href="group__layer3.html#ga6cafa3a644324a1e0c9165494db11648">vmaCreateBuffer()</a> / <a class="el" href="group__layer3.html#ga9646281a3d9abc9f4d0bc5632db117de" title="Function similar to vmaCreateBuffer(). ">vmaCreateImage()</a> to get VkBuffer/VkImage with memory already allocated and bound to it.</li>
 </ol>
 <pre class="fragment">VkBufferCreateInfo bufferInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
 bufferInfo.size = myBufferSize;
 bufferInfo.usage = VK_BUFFER_USAGE_VERTEX_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;

 VmaMemoryRequirements memReq = {};
 memReq.usage = VMA_MEMORY_USAGE_GPU_ONLY;

 VkBuffer buffer;
 vmaCreateBuffer(allocator, &amp;bufferInfo, &amp;memReq, &amp;buffer, nullptr, nullptr);
 </pre><p>When no longer needed, destroy your buffer or image using <a class="el" href="group__layer3.html#ga967857c06b8232b2a54936daf36d1535">vmaDestroyBuffer()</a> / <a class="el" href="group__layer3.html#ga9377799736c4a1262b41ee441e5fc877">vmaDestroyImage()</a>. This function would also free memory bound to it.</p>
 <pre class="fragment">vmaDestroyBuffer(allocator, buffer);
 </pre><h1><a class="anchor" id="configuration"></a>
 Configuration</h1>
 <p>Set VMA_STATS_STRING_ENABLED macro in <a class="el" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a> to 0 or 1 to disable/enable compilation of code for dumping internal allocator state to string in JSON format.</p>
 <p>Please check "CONFIGURATION" section in vk_mem_alloc.cpp file to find macros and other definitions that you can change to connect the library to your own implementation of basic facilities like assert, min and max functions, mutex etc. C++ STL is used by default, but changing these allows you to get rid of any STL usage if you want, as many game developers tend to do.</p>
 <h1><a class="anchor" id="custom_memory_allocator"></a>
 Custom memory allocator</h1>
 <p>You can use custom memory allocator by filling optional member <a class="el" href="struct_vma_allocator_create_info.html#a6e409087e3be55400d0e4ccbe43c608d" title="Custom allocation callbacks. ">VmaAllocatorCreateInfo::pAllocationCallbacks</a>. These functions will be passed to Vulkan, as well as used by the library itself to make any CPU-side allocations.</p>
 <h1><a class="anchor" id="thread_safety"></a>
 Thread safety</h1>
 <p>All calls to functions that take VmaAllocator as first parameter are safe to call from multiple threads simultaneously, synchronized internally when needed. </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>
	<!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: Vulkan Memory Allocator</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>
	</div><!-- top -->
	<!-- 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 class="header">
	<div class="headertitle">
	<div class="title">Vulkan Memory Allocator </div> </div>
	</div><!--header-->
	<div class="contents">
	<div class="textblock"><p>Version 1.0.0 (2017-06-16)</p>
	<p>Members grouped: see <a href="modules.html"><b>Modules</b></a>.</p>
	<p>All members: see <a class="el" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a>.</p>
	<h1><a class="anchor" id="problem"></a>
	Problem Statement</h1>
	<p>Memory allocation and resource (buffer and image) creation in Vulkan is difficult (comparing to older graphics API-s, like D3D11 or OpenGL) for several reasons:</p>
	<ul>
	<li>It requires a lot of boilerplate code, just like everything else in Vulkan, because it is a low-level and high-performance API.</li>
	<li>There is additional level of indirection: VkDeviceMemory is allocated separately from creating VkBuffer/VkImage and they must be bound together. The binding cannot be changed later - resource must be recreated.</li>
	<li>Driver must be queried for supported memory heaps and memory types. Different IHV-s provide different types of it.</li>
	<li>Resources that don't fit in VRAM are not automatically evicted to RAM. Developer must handle out-of-memory errors on his own.</li>
	<li>It is recommended practice to allocate bigger chunks of memory and assign parts of them to particular resources.</li>
	</ul>
	<h1><a class="anchor" id="features"></a>
	Features</h1>
	<p>This library is helps game developers to manage memory allocations and resource creation by offering some higher-level functions. Features of the library could be divided into several layers, low level to high level:</p>
	<ol type="1">
	<li>Functions that help to choose correct and optimal memory type based on intended usage of the memory.<ul>
	<li>Required or preferred traits of the memory are expressed using higher-level description comparing to Vulkan flags.</li>
	</ul>
	</li>
	<li>Functions that allocate memory blocks, reserve and return parts of them (VkDeviceMemory + offset + size) to the user.<ul>
	<li>Library keeps track of allocated memory blocks, used and unused ranges inside them, finds best matching unused ranges for new allocations, takes all the rules of alignment into consideration.</li>
	</ul>
	</li>
	<li>Functions that can create an image/buffer, allocate memory for it and bind them together - all in one call.</li>
	</ol>
	<h1><a class="anchor" id="prequisites"></a>
	Prequisites</h1>
	<ul>
	<li>Self-contained C++ library in single header file. No external dependencies other than standard C and C++ library and of course Vulkan.</li>
	<li>Public interface in C, in same convention as Vulkan API. Implementation in C++.</li>
	<li>Interface documented using Doxygen-style comments.</li>
	<li>Platform-independent, but developed and tested on Windows using Visual Studio.</li>
	<li>Error handling implemented by returning VkResult error codes - same way as in Vulkan.</li>
	</ul>
	<h1><a class="anchor" id="quick_start"></a>
	Quick Start</h1>
	<p>In your project code:</p>
	<ol type="1">
	<li>Include "vk_mem_alloc.h" file wherever you want to use the library.</li>
	<li>In exacly one C++ file define following macro before include to build library implementation.</li>
	</ol>
	<pre class="fragment">#define VMA_IMPLEMENTATION
	#include "vk_mem_alloc.h"
	</pre><p>At program startup:</p>
	<ol type="1">
	<li>Initialize Vulkan to have VkPhysicalDevice and VkDevice 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 create VmaAllocator object by calling <a class="el" href="group__general.html#ga200692051ddb34240248234f5f4c17bb" title="Creates Allocator object. ">vmaCreateAllocator()</a>.</li>
	</ol>
	<pre class="fragment">VmaAllocatorCreateInfo allocatorInfo = {};
	allocatorInfo.physicalDevice = physicalDevice;
	allocatorInfo.device = device;

	VmaAllocator allocator;
	vmaCreateAllocator(&allocatorInfo, &allocator);
	</pre><p>When you want to create a buffer or image:</p>
	<ol type="1">
	<li>Fill VkBufferCreateInfo / VkImageCreateInfo structure.</li>
	<li>Fill <a class="el" href="struct_vma_memory_requirements.html">VmaMemoryRequirements</a> structure.</li>
	<li>Call <a class="el" href="group__layer3.html#ga6cafa3a644324a1e0c9165494db11648">vmaCreateBuffer()</a> / <a class="el" href="group__layer3.html#ga9646281a3d9abc9f4d0bc5632db117de" title="Function similar to vmaCreateBuffer(). ">vmaCreateImage()</a> to get VkBuffer/VkImage with memory already allocated and bound to it.</li>
	</ol>
	<pre class="fragment">VkBufferCreateInfo bufferInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
	bufferInfo.size = myBufferSize;
	bufferInfo.usage = VK_BUFFER_USAGE_VERTEX_BUFFER_BIT \| VK_BUFFER_USAGE_TRANSFER_DST_BIT;

	VmaMemoryRequirements memReq = {};
	memReq.usage = VMA_MEMORY_USAGE_GPU_ONLY;

	VkBuffer buffer;
	vmaCreateBuffer(allocator, &bufferInfo, &memReq, &buffer, nullptr, nullptr);
	</pre><p>When no longer needed, destroy your buffer or image using <a class="el" href="group__layer3.html#ga967857c06b8232b2a54936daf36d1535">vmaDestroyBuffer()</a> / <a class="el" href="group__layer3.html#ga9377799736c4a1262b41ee441e5fc877">vmaDestroyImage()</a>. This function would also free memory bound to it.</p>
	<pre class="fragment">vmaDestroyBuffer(allocator, buffer);
	</pre><h1><a class="anchor" id="configuration"></a>
	Configuration</h1>
	<p>Set VMA_STATS_STRING_ENABLED macro in <a class="el" href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a> to 0 or 1 to disable/enable compilation of code for dumping internal allocator state to string in JSON format.</p>
	<p>Please check "CONFIGURATION" section in vk_mem_alloc.cpp file to find macros and other definitions that you can change to connect the library to your own implementation of basic facilities like assert, min and max functions, mutex etc. C++ STL is used by default, but changing these allows you to get rid of any STL usage if you want, as many game developers tend to do.</p>
	<h1><a class="anchor" id="custom_memory_allocator"></a>
	Custom memory allocator</h1>
	<p>You can use custom memory allocator by filling optional member <a class="el" href="struct_vma_allocator_create_info.html#a6e409087e3be55400d0e4ccbe43c608d" title="Custom allocation callbacks. ">VmaAllocatorCreateInfo::pAllocationCallbacks</a>. These functions will be passed to Vulkan, as well as used by the library itself to make any CPU-side allocations.</p>
	<h1><a class="anchor" id="thread_safety"></a>
	Thread safety</h1>
	<p>All calls to functions that take VmaAllocator as first parameter are safe to call from multiple threads simultaneously, synchronized internally when needed. </p>
	</div></div><!-- contents -->
	<!-- start footer part -->
	<hr class="footer"/><address class="footer"><small>
	Generated by  <a href="http://www.doxygen.org/index.html">
	<img class="footer" src="doxygen.png" alt="doxygen"/>
	</a> 1.8.13
	</small></address>
	</body>
	</html>