docs/html/general_considerations.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=11"/>
 <meta name="generator" content="Doxygen 1.9.4"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <title>Vulkan Memory Allocator: General considerations</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 id="projectrow">
   <td id="projectalign">
    <div id="projectname">Vulkan Memory Allocator
    </div>
   </td>
  </tr>
  </tbody>
 </table>
 </div>
 <!-- end header part -->
 <!-- Generated by Doxygen 1.9.4 -->
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
 var searchBox = new SearchBox("searchBox", "search",'Search','.html');
 /* @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');
   $(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><div class="header">
   <div class="headertitle"><div class="title">General considerations </div></div>
 </div><!--header-->
 <div class="contents">
 <div class="textblock"><h1><a class="anchor" id="general_considerations_thread_safety"></a>
 Thread safety</h1>
 <ul>
 <li>The library has no global state, so separate <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a> objects can be used independently. There should be no need to create multiple such objects though - one per <code>VkDevice</code> is enough.</li>
 <li>By default, all calls to functions that take <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a> as first parameter are safe to call from multiple threads simultaneously because they are synchronized internally when needed. This includes allocation and deallocation from default memory pool, as well as custom <a class="el" href="struct_vma_pool.html" title="Represents custom memory pool.">VmaPool</a>.</li>
 <li>When the allocator is created with <a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7ca4816ddaed324ba110172ca608a20f29d" title="Allocator and all objects created from it will not be synchronized internally, so you must guarantee ...">VMA_ALLOCATOR_CREATE_EXTERNALLY_SYNCHRONIZED_BIT</a> flag, calls to functions that take such <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a> object must be synchronized externally.</li>
 <li>Access to a <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> object must be externally synchronized. For example, you must not call <a class="el" href="group__group__alloc.html#ga86dd08aba8633bfa4ad0df2e76481d8b" title="Returns current information about specified allocation.">vmaGetAllocationInfo()</a> and <a class="el" href="group__group__alloc.html#gad5bd1243512d099706de88168992f069" title="Maps memory represented by given allocation and returns pointer to it.">vmaMapMemory()</a> from different threads at the same time if you pass the same <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> object to these functions.</li>
 <li><a class="el" href="struct_vma_virtual_block.html" title="Handle to a virtual block object that allows to use core allocation algorithm without allocating any ...">VmaVirtualBlock</a> is not safe to be used from multiple threads simultaneously.</li>
 </ul>
 <h1><a class="anchor" id="general_considerations_versioning_and_compatibility"></a>
 Versioning and compatibility</h1>
 <p >The library uses <a href="https://semver.org/"><b>Semantic Versioning</b></a>, which means version numbers follow convention: Major.Minor.Patch (e.g. 2.3.0), where:</p>
 <ul>
 <li>Incremented Patch version means a release is backward- and forward-compatible, introducing only some internal improvements, bug fixes, optimizations etc. or changes that are out of scope of the official API described in this documentation.</li>
 <li>Incremented Minor version means a release is backward-compatible, so existing code that uses the library should continue to work, while some new symbols could have been added: new structures, functions, new values in existing enums and bit flags, new structure members, but not new function parameters.</li>
 <li>Incrementing Major version means a release could break some backward compatibility.</li>
 </ul>
 <p >All changes between official releases are documented in file "CHANGELOG.md".</p>
 <dl class="section warning"><dt>Warning</dt><dd>Backward compatiblity is considered on the level of C++ source code, not binary linkage. Adding new members to existing structures is treated as backward compatible if initializing the new members to binary zero results in the old behavior. You should always fully initialize all library structures to zeros and not rely on their exact binary size.</dd></dl>
 <h1><a class="anchor" id="general_considerations_validation_layer_warnings"></a>
 Validation layer warnings</h1>
 <p >When using this library, you can meet following types of warnings issued by Vulkan validation layer. They don't necessarily indicate a bug, so you may need to just ignore them.</p>
 <ul>
 <li><em>vkBindBufferMemory(): Binding memory to buffer 0xeb8e4 but vkGetBufferMemoryRequirements() has not been called on that buffer.</em><ul>
 <li>It happens when VK_KHR_dedicated_allocation extension is enabled. <code>vkGetBufferMemoryRequirements2KHR</code> function is used instead, while validation layer seems to be unaware of it.</li>
 </ul>
 </li>
 <li><em>Mapping an image with layout VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL can result in undefined behavior if this memory is used by the device. Only GENERAL or PREINITIALIZED should be used.</em><ul>
 <li>It happens when you map a buffer or image, because the library maps entire <code>VkDeviceMemory</code> block, where different types of images and buffers may end up together, especially on GPUs with unified memory like Intel.</li>
 </ul>
 </li>
 <li><em>Non-linear image 0xebc91 is aliased with linear buffer 0xeb8e4 which may indicate a bug.</em><ul>
 <li>It may happen when you use <a class="el" href="defragmentation.html">defragmentation</a>.</li>
 </ul>
 </li>
 </ul>
 <h1><a class="anchor" id="general_considerations_allocation_algorithm"></a>
 Allocation algorithm</h1>
 <p >The library uses following algorithm for allocation, in order:</p>
 <ol type="1">
 <li>Try to find free range of memory in existing blocks.</li>
 <li>If failed, try to create a new block of <code>VkDeviceMemory</code>, with preferred block size.</li>
 <li>If failed, try to create such block with size / 2, size / 4, size / 8.</li>
 <li>If failed, try to allocate separate <code>VkDeviceMemory</code> for this allocation, just like when you use <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block.">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>.</li>
 <li>If failed, choose other memory type that meets the requirements specified in <a class="el" href="struct_vma_allocation_create_info.html" title="Parameters of new VmaAllocation.">VmaAllocationCreateInfo</a> and go to point 1.</li>
 <li>If failed, return <code>VK_ERROR_OUT_OF_DEVICE_MEMORY</code>.</li>
 </ol>
 <h1><a class="anchor" id="general_considerations_features_not_supported"></a>
 Features not supported</h1>
 <p >Features deliberately excluded from the scope of this library:</p>
 <ol type="1">
 <li><b>Data transfer.</b> Uploading (streaming) and downloading data of buffers and images between CPU and GPU memory and related synchronization is responsibility of the user. Defining some "texture" object that would automatically stream its data from a staging copy in CPU memory to GPU memory would rather be a feature of another, higher-level library implemented on top of VMA. VMA doesn't record any commands to a <code>VkCommandBuffer</code>. It just allocates memory.</li>
 <li><b>Recreation of buffers and images.</b> Although the library has functions for buffer and image creation: <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>, you need to recreate these objects yourself after defragmentation. That is because the big structures <code>VkBufferCreateInfo</code>, <code>VkImageCreateInfo</code> are not stored in <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> object.</li>
 <li><b>Handling CPU memory allocation failures.</b> When dynamically creating small C++ objects in CPU memory (not Vulkan memory), allocation failures are not checked and handled gracefully, because that would complicate code significantly and is usually not needed in desktop PC applications anyway. Success of an allocation is just checked with an assert.</li>
 <li><b>Code free of any compiler warnings.</b> Maintaining the library to compile and work correctly on so many different platforms is hard enough. Being free of any warnings, on any version of any compiler, is simply not feasible. There are many preprocessor macros that make some variables unused, function parameters unreferenced, or conditional expressions constant in some configurations. The code of this library should not be bigger or more complicated just to silence these warnings. It is recommended to disable such warnings instead.</li>
 <li>This is a C++ library with C interface. <b>Bindings or ports to any other programming languages</b> are welcome as external projects but are not going to be included into this repository. </li>
 </ol>
 </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.9.4
 </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=11"/>
	<meta name="generator" content="Doxygen 1.9.4"/>
	<meta name="viewport" content="width=device-width, initial-scale=1"/>
	<title>Vulkan Memory Allocator: General considerations</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 id="projectrow">
	<td id="projectalign">
	<div id="projectname">Vulkan Memory Allocator
	</div>
	</td>
	</tr>
	</tbody>
	</table>
	</div>
	<!-- end header part -->
	<!-- Generated by Doxygen 1.9.4 -->
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
	var searchBox = new SearchBox("searchBox", "search",'Search','.html');
	/* @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&dn=expat.txt MIT */
	$(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><div class="header">
	<div class="headertitle"><div class="title">General considerations </div></div>
	</div><!--header-->
	<div class="contents">
	<div class="textblock"><h1><a class="anchor" id="general_considerations_thread_safety"></a>
	Thread safety</h1>
	<ul>
	<li>The library has no global state, so separate <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a> objects can be used independently. There should be no need to create multiple such objects though - one per <code>VkDevice</code> is enough.</li>
	<li>By default, all calls to functions that take <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a> as first parameter are safe to call from multiple threads simultaneously because they are synchronized internally when needed. This includes allocation and deallocation from default memory pool, as well as custom <a class="el" href="struct_vma_pool.html" title="Represents custom memory pool.">VmaPool</a>.</li>
	<li>When the allocator is created with <a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7ca4816ddaed324ba110172ca608a20f29d" title="Allocator and all objects created from it will not be synchronized internally, so you must guarantee ...">VMA_ALLOCATOR_CREATE_EXTERNALLY_SYNCHRONIZED_BIT</a> flag, calls to functions that take such <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a> object must be synchronized externally.</li>
	<li>Access to a <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> object must be externally synchronized. For example, you must not call <a class="el" href="group__group__alloc.html#ga86dd08aba8633bfa4ad0df2e76481d8b" title="Returns current information about specified allocation.">vmaGetAllocationInfo()</a> and <a class="el" href="group__group__alloc.html#gad5bd1243512d099706de88168992f069" title="Maps memory represented by given allocation and returns pointer to it.">vmaMapMemory()</a> from different threads at the same time if you pass the same <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> object to these functions.</li>
	<li><a class="el" href="struct_vma_virtual_block.html" title="Handle to a virtual block object that allows to use core allocation algorithm without allocating any ...">VmaVirtualBlock</a> is not safe to be used from multiple threads simultaneously.</li>
	</ul>
	<h1><a class="anchor" id="general_considerations_versioning_and_compatibility"></a>
	Versioning and compatibility</h1>
	<p >The library uses <a href="https://semver.org/"><b>Semantic Versioning</b></a>, which means version numbers follow convention: Major.Minor.Patch (e.g. 2.3.0), where:</p>
	<ul>
	<li>Incremented Patch version means a release is backward- and forward-compatible, introducing only some internal improvements, bug fixes, optimizations etc. or changes that are out of scope of the official API described in this documentation.</li>
	<li>Incremented Minor version means a release is backward-compatible, so existing code that uses the library should continue to work, while some new symbols could have been added: new structures, functions, new values in existing enums and bit flags, new structure members, but not new function parameters.</li>
	<li>Incrementing Major version means a release could break some backward compatibility.</li>
	</ul>
	<p >All changes between official releases are documented in file "CHANGELOG.md".</p>
	<dl class="section warning"><dt>Warning</dt><dd>Backward compatiblity is considered on the level of C++ source code, not binary linkage. Adding new members to existing structures is treated as backward compatible if initializing the new members to binary zero results in the old behavior. You should always fully initialize all library structures to zeros and not rely on their exact binary size.</dd></dl>
	<h1><a class="anchor" id="general_considerations_validation_layer_warnings"></a>
	Validation layer warnings</h1>
	<p >When using this library, you can meet following types of warnings issued by Vulkan validation layer. They don't necessarily indicate a bug, so you may need to just ignore them.</p>
	<ul>
	<li><em>vkBindBufferMemory(): Binding memory to buffer 0xeb8e4 but vkGetBufferMemoryRequirements() has not been called on that buffer.</em><ul>
	<li>It happens when VK_KHR_dedicated_allocation extension is enabled. <code>vkGetBufferMemoryRequirements2KHR</code> function is used instead, while validation layer seems to be unaware of it.</li>
	</ul>
	</li>
	<li><em>Mapping an image with layout VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL can result in undefined behavior if this memory is used by the device. Only GENERAL or PREINITIALIZED should be used.</em><ul>
	<li>It happens when you map a buffer or image, because the library maps entire <code>VkDeviceMemory</code> block, where different types of images and buffers may end up together, especially on GPUs with unified memory like Intel.</li>
	</ul>
	</li>
	<li><em>Non-linear image 0xebc91 is aliased with linear buffer 0xeb8e4 which may indicate a bug.</em><ul>
	<li>It may happen when you use <a class="el" href="defragmentation.html">defragmentation</a>.</li>
	</ul>
	</li>
	</ul>
	<h1><a class="anchor" id="general_considerations_allocation_algorithm"></a>
	Allocation algorithm</h1>
	<p >The library uses following algorithm for allocation, in order:</p>
	<ol type="1">
	<li>Try to find free range of memory in existing blocks.</li>
	<li>If failed, try to create a new block of <code>VkDeviceMemory</code>, with preferred block size.</li>
	<li>If failed, try to create such block with size / 2, size / 4, size / 8.</li>
	<li>If failed, try to allocate separate <code>VkDeviceMemory</code> for this allocation, just like when you use <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block.">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>.</li>
	<li>If failed, choose other memory type that meets the requirements specified in <a class="el" href="struct_vma_allocation_create_info.html" title="Parameters of new VmaAllocation.">VmaAllocationCreateInfo</a> and go to point 1.</li>
	<li>If failed, return <code>VK_ERROR_OUT_OF_DEVICE_MEMORY</code>.</li>
	</ol>
	<h1><a class="anchor" id="general_considerations_features_not_supported"></a>
	Features not supported</h1>
	<p >Features deliberately excluded from the scope of this library:</p>
	<ol type="1">
	<li><b>Data transfer.</b> Uploading (streaming) and downloading data of buffers and images between CPU and GPU memory and related synchronization is responsibility of the user. Defining some "texture" object that would automatically stream its data from a staging copy in CPU memory to GPU memory would rather be a feature of another, higher-level library implemented on top of VMA. VMA doesn't record any commands to a <code>VkCommandBuffer</code>. It just allocates memory.</li>
	<li><b>Recreation of buffers and images.</b> Although the library has functions for buffer and image creation: <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>, you need to recreate these objects yourself after defragmentation. That is because the big structures <code>VkBufferCreateInfo</code>, <code>VkImageCreateInfo</code> are not stored in <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> object.</li>
	<li><b>Handling CPU memory allocation failures.</b> When dynamically creating small C++ objects in CPU memory (not Vulkan memory), allocation failures are not checked and handled gracefully, because that would complicate code significantly and is usually not needed in desktop PC applications anyway. Success of an allocation is just checked with an assert.</li>
	<li><b>Code free of any compiler warnings.</b> Maintaining the library to compile and work correctly on so many different platforms is hard enough. Being free of any warnings, on any version of any compiler, is simply not feasible. There are many preprocessor macros that make some variables unused, function parameters unreferenced, or conditional expressions constant in some configurations. The code of this library should not be bigger or more complicated just to silence these warnings. It is recommended to disable such warnings instead.</li>
	<li>This is a C++ library with C interface. <b>Bindings or ports to any other programming languages</b> are welcome as external projects but are not going to be included into this repository. </li>
	</ol>
	</div></div><!-- contents -->
	</div><!-- PageDoc -->
	<!-- start footer part -->
	<hr class="footer"/><address class="footer"><small>
	Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
	</small></address>
	</body>
	</html>