docs/html/general_considerations.html - external/github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator - 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.3"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <title>Direct3D 12 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">Direct3D 12 Memory Allocator
    </div>
   </td>
  </tr>
  </tbody>
 </table>
 </div>
 <!-- end header part -->
 <!-- Generated by Doxygen 1.9.3 -->
 <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">D3D12 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="class_d3_d12_m_a_1_1_allocator.html" title="Represents main object of this library initialized for particular ID3D12Device.">D3D12MA::Allocator</a> objects can be used independently. In typical applications there should be no need to create multiple such objects though - one per <code>ID3D12Device</code> is enough.</li>
 <li>All calls to methods of <a class="el" href="class_d3_d12_m_a_1_1_allocator.html" title="Represents main object of this library initialized for particular ID3D12Device.">D3D12MA::Allocator</a> class are safe to be made from multiple threads simultaneously because they are synchronized internally when needed.</li>
 <li>When the allocator is created with <a class="el" href="namespace_d3_d12_m_a.html#ad5ae5a5e42b878f2e18ab5d1fbfb9916a1b06bb21df006f76a9ed1bc41838bc52">D3D12MA::ALLOCATOR_FLAG_SINGLETHREADED</a>, calls to methods of <a class="el" href="class_d3_d12_m_a_1_1_allocator.html" title="Represents main object of this library initialized for particular ID3D12Device.">D3D12MA::Allocator</a> class must be made from a single thread or synchronized by the user. Using this flag may improve performance.</li>
 <li><a class="el" href="class_d3_d12_m_a_1_1_virtual_block.html" title="Represents pure allocation algorithm and a data structure with allocations in some memory block,...">D3D12MA::VirtualBlock</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_features_not_supported"></a>
 Features not supported</h1>
 <p >Features deliberately excluded from the scope of this library:</p>
 <ul>
 <li><b>Descriptor allocation.</b> Although also called "heaps", objects that represent descriptors are separate part of the D3D12 API from buffers and textures. You can still use <a class="el" href="virtual_allocator.html">Virtual allocator</a> to manage descriptors and their ranges inside a descriptor heap.</li>
 <li><b>Support for reserved (tiled) resources.</b> We don't recommend using them.</li>
 <li>Support for <code>ID3D12Device::Evict</code> and <code>MakeResident</code>. We don't recommend using them. You can call them on the D3D12 objects manually. Plese keep in mind, however, that eviction happens on the level of entire <code>ID3D12Heap</code> memory blocks and not individual buffers or textures which may be placed inside them.</li>
 <li><b>Handling CPU memory allocation failures.</b> When dynamically creating small C++ objects in CPU memory (not the GPU memory), allocation failures are not 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> 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. <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>
 </ul>
 </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.3
 </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.3"/>
	<meta name="viewport" content="width=device-width, initial-scale=1"/>
	<title>Direct3D 12 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">Direct3D 12 Memory Allocator
	</div>
	</td>
	</tr>
	</tbody>
	</table>
	</div>
	<!-- end header part -->
	<!-- Generated by Doxygen 1.9.3 -->
	<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">D3D12 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="class_d3_d12_m_a_1_1_allocator.html" title="Represents main object of this library initialized for particular ID3D12Device.">D3D12MA::Allocator</a> objects can be used independently. In typical applications there should be no need to create multiple such objects though - one per <code>ID3D12Device</code> is enough.</li>
	<li>All calls to methods of <a class="el" href="class_d3_d12_m_a_1_1_allocator.html" title="Represents main object of this library initialized for particular ID3D12Device.">D3D12MA::Allocator</a> class are safe to be made from multiple threads simultaneously because they are synchronized internally when needed.</li>
	<li>When the allocator is created with <a class="el" href="namespace_d3_d12_m_a.html#ad5ae5a5e42b878f2e18ab5d1fbfb9916a1b06bb21df006f76a9ed1bc41838bc52">D3D12MA::ALLOCATOR_FLAG_SINGLETHREADED</a>, calls to methods of <a class="el" href="class_d3_d12_m_a_1_1_allocator.html" title="Represents main object of this library initialized for particular ID3D12Device.">D3D12MA::Allocator</a> class must be made from a single thread or synchronized by the user. Using this flag may improve performance.</li>
	<li><a class="el" href="class_d3_d12_m_a_1_1_virtual_block.html" title="Represents pure allocation algorithm and a data structure with allocations in some memory block,...">D3D12MA::VirtualBlock</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_features_not_supported"></a>
	Features not supported</h1>
	<p >Features deliberately excluded from the scope of this library:</p>
	<ul>
	<li><b>Descriptor allocation.</b> Although also called "heaps", objects that represent descriptors are separate part of the D3D12 API from buffers and textures. You can still use <a class="el" href="virtual_allocator.html">Virtual allocator</a> to manage descriptors and their ranges inside a descriptor heap.</li>
	<li><b>Support for reserved (tiled) resources.</b> We don't recommend using them.</li>
	<li>Support for <code>ID3D12Device::Evict</code> and <code>MakeResident</code>. We don't recommend using them. You can call them on the D3D12 objects manually. Plese keep in mind, however, that eviction happens on the level of entire <code>ID3D12Heap</code> memory blocks and not individual buffers or textures which may be placed inside them.</li>
	<li><b>Handling CPU memory allocation failures.</b> When dynamically creating small C++ objects in CPU memory (not the GPU memory), allocation failures are not 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> 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. <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>
	</ul>
	</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.3
	</small></address>
	</body>
	</html>