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

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
 <meta name="generator" content="Doxygen 1.8.18"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <title>Vulkan Memory Allocator: Configuration</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.18 -->
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 var searchBox = new SearchBox("searchBox", "search",false,'Search');
 /* @license-end */
 </script>
 <script type="text/javascript" src="menudata.js"></script>
 <script type="text/javascript" src="menu.js"></script>
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 $(function() {
   initMenu('',true,false,'search.php','Search');
   $(document).ready(function() { init_search(); });
 });
 /* @license-end */</script>
 <div id="main-nav"></div>
 <!-- window showing the filter options -->
 <div id="MSearchSelectWindow"
      onmouseover="return searchBox.OnSearchSelectShow()"
      onmouseout="return searchBox.OnSearchSelectHide()"
      onkeydown="return searchBox.OnSearchSelectKey(event)">
 </div>

 <!-- iframe showing the search results (closed by default) -->
 <div id="MSearchResultsWindow">
 <iframe src="javascript:void(0)" frameborder="0"
         name="MSearchResults" id="MSearchResults">
 </iframe>
 </div>

 <div id="nav-path" class="navpath">
   <ul>
 <li class="navelem"><a class="el" href="index.html">Vulkan Memory Allocator</a></li>  </ul>
 </div>
 </div><!-- top -->
 <div class="PageDoc"><div class="header">
   <div class="headertitle">
 <div class="title">Configuration </div>  </div>
 </div><!--header-->
 <div class="contents">
 <div class="textblock"><p>Please check "CONFIGURATION SECTION" in the code to find macros that you can define before each include of this file or change directly in this file to provide your own implementation of basic facilities like assert, <code>min()</code> and <code>max()</code> functions, mutex, atomic etc. The library uses its own implementation of containers by default, but you can switch to using STL containers instead.</p>
 <p>For example, define <code>VMA_ASSERT(expr)</code> before including the library to provide custom implementation of the assertion, compatible with your project. By default it is defined to standard C <code>assert(expr)</code> in <code>_DEBUG</code> configuration and empty otherwise.</p>
 <h1><a class="anchor" id="config_Vulkan_functions"></a>
 Pointers to Vulkan functions</h1>
 <p>There are multiple ways to import pointers to Vulkan functions in the library. In the simplest case you don't need to do anything. If the compilation or linking of your program or the initialization of the <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a> doesn't work for you, you can try to reconfigure it.</p>
 <p>First, the allocator tries to fetch pointers to Vulkan functions linked statically, like this:</p>
 <div class="fragment"><div class="line">m_VulkanFunctions.vkAllocateMemory = (PFN_vkAllocateMemory)vkAllocateMemory;</div>
 </div><!-- fragment --><p>If you want to disable this feature, set configuration macro: <code>#define VMA_STATIC_VULKAN_FUNCTIONS 0</code>.</p>
 <p>Second, you can provide the pointers yourself by setting member <a class="el" href="struct_vma_allocator_create_info.html#a3dc197be3227da7338b1643f70db36bd" title="Pointers to Vulkan functions. Can be null.">VmaAllocatorCreateInfo::pVulkanFunctions</a>. You can fetch them e.g. using functions <code>vkGetInstanceProcAddr</code> and <code>vkGetDeviceProcAddr</code> or by using a helper library like <a href="https://github.com/zeux/volk">volk</a>.</p>
 <p>Third, VMA tries to fetch remaining pointers that are still null by calling <code>vkGetInstanceProcAddr</code> and <code>vkGetDeviceProcAddr</code> on its own. If you want to disable this feature, set configuration macro: <code>#define VMA_DYNAMIC_VULKAN_FUNCTIONS 0</code>.</p>
 <p>Finally, all the function pointers required by the library (considering selected Vulkan version and enabled extensions) are checked with <code>VMA_ASSERT</code> if they are not null.</p>
 <h1><a class="anchor" id="custom_memory_allocator"></a>
 Custom host memory allocator</h1>
 <p>If you use custom allocator for CPU memory rather than default operator <code>new</code> and <code>delete</code> from C++, you can make this library using your allocator as well by filling optional member <a class="el" href="struct_vma_allocator_create_info.html#a6e409087e3be55400d0e4ccbe43c608d" title="Custom CPU memory allocation callbacks. Optional.">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="allocation_callbacks"></a>
 Device memory allocation callbacks</h1>
 <p>The library makes calls to <code>vkAllocateMemory()</code> and <code>vkFreeMemory()</code> internally. You can setup callbacks to be informed about these calls, e.g. for the purpose of gathering some statistics. To do it, fill optional member <a class="el" href="struct_vma_allocator_create_info.html#af1380969b5e1ea4c3184a877892d260e" title="Informative callbacks for vkAllocateMemory, vkFreeMemory. Optional.">VmaAllocatorCreateInfo::pDeviceMemoryCallbacks</a>.</p>
 <h1><a class="anchor" id="heap_memory_limit"></a>
 Device heap memory limit</h1>
 <p>When device memory of certain heap runs out of free space, new allocations may fail (returning error code) or they may succeed, silently pushing some existing memory blocks from GPU VRAM to system RAM (which degrades performance). This behavior is implementation-dependant - it depends on GPU vendor and graphics driver.</p>
 <p>On AMD cards it can be controlled while creating Vulkan device object by using VK_AMD_memory_overallocation_behavior extension, if available.</p>
 <p>Alternatively, if you want to test how your program behaves with limited amount of Vulkan device memory available without switching your graphics card to one that really has smaller VRAM, you can use a feature of this library intended for this purpose. To do it, fill optional member <a class="el" href="struct_vma_allocator_create_info.html#a31c192aa6cbffa33279f6d9f0c47c44b" title="Either null or a pointer to an array of limits on maximum number of bytes that can be allocated out o...">VmaAllocatorCreateInfo::pHeapSizeLimit</a>. </p>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->
 <!-- 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.18
 </small></address>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
	<meta http-equiv="X-UA-Compatible" content="IE=9"/>
	<meta name="generator" content="Doxygen 1.8.18"/>
	<meta name="viewport" content="width=device-width, initial-scale=1"/>
	<title>Vulkan Memory Allocator: Configuration</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.18 -->
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	var searchBox = new SearchBox("searchBox", "search",false,'Search');
	/* @license-end */
	</script>
	<script type="text/javascript" src="menudata.js"></script>
	<script type="text/javascript" src="menu.js"></script>
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	$(function() {
	initMenu('',true,false,'search.php','Search');
	$(document).ready(function() { init_search(); });
	});
	/* @license-end */</script>
	<div id="main-nav"></div>
	<!-- window showing the filter options -->
	<div id="MSearchSelectWindow"
	onmouseover="return searchBox.OnSearchSelectShow()"
	onmouseout="return searchBox.OnSearchSelectHide()"
	onkeydown="return searchBox.OnSearchSelectKey(event)">
	</div>

	<!-- iframe showing the search results (closed by default) -->
	<div id="MSearchResultsWindow">
	<iframe src="javascript:void(0)" frameborder="0"
	name="MSearchResults" id="MSearchResults">
	</iframe>
	</div>

	<div id="nav-path" class="navpath">
	<ul>
	<li class="navelem"><a class="el" href="index.html">Vulkan Memory Allocator</a></li> </ul>
	</div>
	</div><!-- top -->
	<div class="PageDoc"><div class="header">
	<div class="headertitle">
	<div class="title">Configuration </div> </div>
	</div><!--header-->
	<div class="contents">
	<div class="textblock"><p>Please check "CONFIGURATION SECTION" in the code to find macros that you can define before each include of this file or change directly in this file to provide your own implementation of basic facilities like assert, <code>min()</code> and <code>max()</code> functions, mutex, atomic etc. The library uses its own implementation of containers by default, but you can switch to using STL containers instead.</p>
	<p>For example, define <code>VMA_ASSERT(expr)</code> before including the library to provide custom implementation of the assertion, compatible with your project. By default it is defined to standard C <code>assert(expr)</code> in <code>_DEBUG</code> configuration and empty otherwise.</p>
	<h1><a class="anchor" id="config_Vulkan_functions"></a>
	Pointers to Vulkan functions</h1>
	<p>There are multiple ways to import pointers to Vulkan functions in the library. In the simplest case you don't need to do anything. If the compilation or linking of your program or the initialization of the <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a> doesn't work for you, you can try to reconfigure it.</p>
	<p>First, the allocator tries to fetch pointers to Vulkan functions linked statically, like this:</p>
	<div class="fragment"><div class="line">m_VulkanFunctions.vkAllocateMemory = (PFN_vkAllocateMemory)vkAllocateMemory;</div>
	</div><!-- fragment --><p>If you want to disable this feature, set configuration macro: <code>#define VMA_STATIC_VULKAN_FUNCTIONS 0</code>.</p>
	<p>Second, you can provide the pointers yourself by setting member <a class="el" href="struct_vma_allocator_create_info.html#a3dc197be3227da7338b1643f70db36bd" title="Pointers to Vulkan functions. Can be null.">VmaAllocatorCreateInfo::pVulkanFunctions</a>. You can fetch them e.g. using functions <code>vkGetInstanceProcAddr</code> and <code>vkGetDeviceProcAddr</code> or by using a helper library like <a href="https://github.com/zeux/volk">volk</a>.</p>
	<p>Third, VMA tries to fetch remaining pointers that are still null by calling <code>vkGetInstanceProcAddr</code> and <code>vkGetDeviceProcAddr</code> on its own. If you want to disable this feature, set configuration macro: <code>#define VMA_DYNAMIC_VULKAN_FUNCTIONS 0</code>.</p>
	<p>Finally, all the function pointers required by the library (considering selected Vulkan version and enabled extensions) are checked with <code>VMA_ASSERT</code> if they are not null.</p>
	<h1><a class="anchor" id="custom_memory_allocator"></a>
	Custom host memory allocator</h1>
	<p>If you use custom allocator for CPU memory rather than default operator <code>new</code> and <code>delete</code> from C++, you can make this library using your allocator as well by filling optional member <a class="el" href="struct_vma_allocator_create_info.html#a6e409087e3be55400d0e4ccbe43c608d" title="Custom CPU memory allocation callbacks. Optional.">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="allocation_callbacks"></a>
	Device memory allocation callbacks</h1>
	<p>The library makes calls to <code>vkAllocateMemory()</code> and <code>vkFreeMemory()</code> internally. You can setup callbacks to be informed about these calls, e.g. for the purpose of gathering some statistics. To do it, fill optional member <a class="el" href="struct_vma_allocator_create_info.html#af1380969b5e1ea4c3184a877892d260e" title="Informative callbacks for vkAllocateMemory, vkFreeMemory. Optional.">VmaAllocatorCreateInfo::pDeviceMemoryCallbacks</a>.</p>
	<h1><a class="anchor" id="heap_memory_limit"></a>
	Device heap memory limit</h1>
	<p>When device memory of certain heap runs out of free space, new allocations may fail (returning error code) or they may succeed, silently pushing some existing memory blocks from GPU VRAM to system RAM (which degrades performance). This behavior is implementation-dependant - it depends on GPU vendor and graphics driver.</p>
	<p>On AMD cards it can be controlled while creating Vulkan device object by using VK_AMD_memory_overallocation_behavior extension, if available.</p>
	<p>Alternatively, if you want to test how your program behaves with limited amount of Vulkan device memory available without switching your graphics card to one that really has smaller VRAM, you can use a feature of this library intended for this purpose. To do it, fill optional member <a class="el" href="struct_vma_allocator_create_info.html#a31c192aa6cbffa33279f6d9f0c47c44b" title="Either null or a pointer to an array of limits on maximum number of bytes that can be allocated out o...">VmaAllocatorCreateInfo::pHeapSizeLimit</a>. </p>
	</div></div><!-- contents -->
	</div><!-- PageDoc -->
	<!-- 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.18
	</small></address>
	</body>
	</html>