| <!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.14.0"/> |
| <meta name="viewport" content="width=device-width, initial-scale=1"/> |
| <title>D3D12 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> |
| <script type="text/javascript" src="clipboard.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">D3D12 Memory Allocator |
| </div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <!-- end header part --> |
| <!-- Generated by Doxygen 1.14.0 --> |
| <script type="text/javascript"> |
| var searchBox = new SearchBox("searchBox", "search/",'.html'); |
| </script> |
| <script type="text/javascript"> |
| $(function() { codefold.init(); }); |
| </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',false); |
| $(function() { init_search(); }); |
| }); |
| </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"> |
| <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 href="index.html">D3D12 Memory Allocator</a></li> </ul> |
| </div> |
| </div><!-- top --> |
| <div id="doc-content"> |
| <div><div class="header"> |
| <div class="headertitle"><div class="title">Configuration </div></div> |
| </div><!--header--> |
| <div class="contents"> |
| <div class="textblock"><p>Please check file <span class="tt">D3D12MemAlloc.cpp</span> lines between "Configuration Begin" and "Configuration End" to find macros that you can define to change the behavior of the library, primarily for debugging purposes.</p> |
| <h1 class="doxsection"><a class="anchor" id="custom_memory_allocator"></a> |
| Custom CPU memory allocator</h1> |
| <p>If you use custom allocator for CPU memory rather than default C++ operator <span class="tt">new</span> and <span class="tt">delete</span> or <span class="tt">malloc</span> and <span class="tt">free</span> functions, you can make this library using your allocator as well by filling structure <a class="el" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___c_a_l_l_b_a_c_k_s.html" title="Custom callbacks to CPU memory allocation functions.">D3D12MA::ALLOCATION_CALLBACKS</a> and passing it as optional member <a class="el" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c.html#a773ecc1945eb47c20e06455c3759e4ef" title="Custom CPU memory allocation callbacks. Optional.">D3D12MA::ALLOCATOR_DESC::pAllocationCallbacks</a>. Functions pointed there will be used by the library to make any CPU-side allocations. Example:</p> |
| <div class="fragment"><div class="line"><span class="preprocessor">#include <malloc.h></span></div> |
| <div class="line"> </div> |
| <div class="line"><span class="keywordtype">void</span>* CustomAllocate(<span class="keywordtype">size_t</span> Size, <span class="keywordtype">size_t</span> Alignment, <span class="keywordtype">void</span>* pPrivateData)</div> |
| <div class="line">{</div> |
| <div class="line"> <span class="keywordtype">void</span>* memory = _aligned_malloc(Size, Alignment);</div> |
| <div class="line"> <span class="comment">// Your extra bookkeeping here...</span></div> |
| <div class="line"> <span class="keywordflow">return</span> memory;</div> |
| <div class="line">}</div> |
| <div class="line"> </div> |
| <div class="line"><span class="keywordtype">void</span> CustomFree(<span class="keywordtype">void</span>* pMemory, <span class="keywordtype">void</span>* pPrivateData)</div> |
| <div class="line">{</div> |
| <div class="line"> <span class="comment">// Your extra bookkeeping here...</span></div> |
| <div class="line"> _aligned_free(pMemory);</div> |
| <div class="line">}</div> |
| <div class="line"> </div> |
| <div class="line">...</div> |
| <div class="line"> </div> |
| <div class="line">D3D12MA::ALLOCATION_CALLBACKS allocationCallbacks = {};</div> |
| <div class="line">allocationCallbacks.pAllocate = &CustomAllocate;</div> |
| <div class="line">allocationCallbacks.pFree = &CustomFree;</div> |
| <div class="line"> </div> |
| <div class="line"><a class="code hl_struct" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c.html">D3D12MA::ALLOCATOR_DESC</a> allocatorDesc = {};</div> |
| <div class="line">allocatorDesc.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c.html#ada1bf21205065b3aa0284b5a9ee1cb3c">pDevice</a> = device;</div> |
| <div class="line">allocatorDesc.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c.html#abf9a9f87f0ffea52816efd363c5fcd7b">pAdapter</a> = adapter;</div> |
| <div class="line">allocatorDesc.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c.html#ad8abad7c80ea0d8df27c85243ce720f3">Flags</a> = <a class="code hl_define" href="_d3_d12_mem_alloc_8h.html#accfbeae642feeacf353ce695e91a5e73">D3D12MA_RECOMMENDED_ALLOCATOR_FLAGS</a>;</div> |
| <div class="line">allocatorDesc.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c.html#a773ecc1945eb47c20e06455c3759e4ef">pAllocationCallbacks</a> = &allocationCallbacks;</div> |
| <div class="line"> </div> |
| <div class="line"><a class="code hl_class" href="class_d3_d12_m_a_1_1_allocator.html">D3D12MA::Allocator</a>* allocator;</div> |
| <div class="line">HRESULT hr = <a class="code hl_function" href="namespace_d3_d12_m_a.html#ab7a1cd1683986d75ce1488b0920f4cb0">D3D12MA::CreateAllocator</a>(&allocatorDesc, &allocator);</div> |
| <div class="line"><span class="comment">// Check hr...</span></div> |
| <div class="ttc" id="a_d3_d12_mem_alloc_8h_html_accfbeae642feeacf353ce695e91a5e73"><div class="ttname"><a href="_d3_d12_mem_alloc_8h.html#accfbeae642feeacf353ce695e91a5e73">D3D12MA_RECOMMENDED_ALLOCATOR_FLAGS</a></div><div class="ttdeci">#define D3D12MA_RECOMMENDED_ALLOCATOR_FLAGS</div><div class="ttdoc">Set of flags recommended for use in D3D12MA::ALLOCATOR_DESC::Flags for optimal performance.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:128</div></div> |
| <div class="ttc" id="aclass_d3_d12_m_a_1_1_allocator_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocator.html">D3D12MA::Allocator</a></div><div class="ttdoc">Represents main object of this library initialized for particular ID3D12Device.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1174</div></div> |
| <div class="ttc" id="anamespace_d3_d12_m_a_html_ab7a1cd1683986d75ce1488b0920f4cb0"><div class="ttname"><a href="namespace_d3_d12_m_a.html#ab7a1cd1683986d75ce1488b0920f4cb0">D3D12MA::CreateAllocator</a></div><div class="ttdeci">D3D12MA_API HRESULT CreateAllocator(const ALLOCATOR_DESC *pDesc, Allocator **ppAllocator)</div><div class="ttdoc">Creates new main D3D12MA::Allocator object and returns it through ppAllocator.</div></div> |
| <div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c.html">D3D12MA::ALLOCATOR_DESC</a></div><div class="ttdoc">Parameters of created Allocator object. To be used with CreateAllocator().</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1132</div></div> |
| <div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c_html_a773ecc1945eb47c20e06455c3759e4ef"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c.html#a773ecc1945eb47c20e06455c3759e4ef">D3D12MA::ALLOCATOR_DESC::pAllocationCallbacks</a></div><div class="ttdeci">const ALLOCATION_CALLBACKS * pAllocationCallbacks</div><div class="ttdoc">Custom CPU memory allocation callbacks. Optional.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1155</div></div> |
| <div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c_html_abf9a9f87f0ffea52816efd363c5fcd7b"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c.html#abf9a9f87f0ffea52816efd363c5fcd7b">D3D12MA::ALLOCATOR_DESC::pAdapter</a></div><div class="ttdeci">IDXGIAdapter * pAdapter</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1161</div></div> |
| <div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c_html_ad8abad7c80ea0d8df27c85243ce720f3"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c.html#ad8abad7c80ea0d8df27c85243ce720f3">D3D12MA::ALLOCATOR_DESC::Flags</a></div><div class="ttdeci">ALLOCATOR_FLAGS Flags</div><div class="ttdoc">Flags for the entire allocator.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1137</div></div> |
| <div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c_html_ada1bf21205065b3aa0284b5a9ee1cb3c"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c.html#ada1bf21205065b3aa0284b5a9ee1cb3c">D3D12MA::ALLOCATOR_DESC::pDevice</a></div><div class="ttdeci">ID3D12Device * pDevice</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1143</div></div> |
| </div><!-- fragment --><h1 class="doxsection"><a class="anchor" id="debug_margins"></a> |
| Debug margins</h1> |
| <p>By default, allocations are laid out in memory blocks next to each other if possible (considering required alignment returned by <span class="tt">ID3D12Device::GetResourceAllocationInfo</span>).</p> |
| <p><img src="../gfx/Margins_1.png" alt="Allocations without margin" class="inline"/></p> |
| <p>Define macro <span class="tt">D3D12MA_DEBUG_MARGIN</span> to some non-zero value (e.g. 16) inside "D3D12MemAlloc.cpp" to enforce specified number of bytes as a margin after every allocation.</p> |
| <p><img src="../gfx/Margins_2.png" alt="Allocations with margin" class="inline"/></p> |
| <p>If your bug goes away after enabling margins, it means it may be caused by memory being overwritten outside of allocation boundaries. It is not 100% certain though. Change in application behavior may also be caused by different order and distribution of allocations across memory blocks after margins are applied.</p> |
| <p>Margins work with all memory heap types.</p> |
| <p>Margin is applied only to placed allocations made out of memory heaps and not to committed allocations, which have their own, implicit memory heap of specific size. It is thus not applied to allocations made using <a class="el" href="namespace_d3_d12_m_a.html#abbad31a7e0b3d09d77f3fb704b77645ea661a5472dba3dcecc5a2cc92afd25675">D3D12MA::ALLOCATION_FLAG_COMMITTED</a> flag or those automatically decided to put into committed allocations, e.g. due to its large size.</p> |
| <p>Margins appear in <a class="el" href="statistics.html#statistics_json_dump">JSON dump</a> as part of free space.</p> |
| <p>Note that enabling margins increases memory usage and fragmentation.</p> |
| <p>Margins do not apply to <a class="el" href="virtual_allocator.html">Virtual allocator</a>. </p> |
| </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.14.0 |
| </small></address> |
| </div><!-- doc-content --> |
| </body> |
| </html> |
