Added documentation chapter: Frequenty asked questions Rebuilt the docs.
diff --git a/docs/html/configuration.html b/docs/html/configuration.html index 5ff7d2d..cc02050 100644 --- a/docs/html/configuration.html +++ b/docs/html/configuration.html
@@ -125,14 +125,14 @@ <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:127</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:1162</div></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:1163</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:1120</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:1143</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:1149</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:1125</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:1131</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:1121</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:1144</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:1150</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:1126</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:1132</div></div> </div><!-- fragment --><h1><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 <code>ID3D12Device::GetResourceAllocationInfo</code>).</p>
diff --git a/docs/html/custom_pools.html b/docs/html/custom_pools.html index 70c1d27..cfde4d4 100644 --- a/docs/html/custom_pools.html +++ b/docs/html/custom_pools.html
@@ -102,8 +102,8 @@ <div class="line"> </div> <div class="line">Pool* pool;</div> <div class="line">HRESULT hr = allocator->CreatePool(&poolDesc, &pool);</div> -<div class="ttc" id="a_d3_d12_mem_alloc_8h_html_a2679d8c9f6d900168bb45450bc88998b"><div class="ttname"><a href="_d3_d12_mem_alloc_8h.html#a2679d8c9f6d900168bb45450bc88998b">D3D12MA_RECOMMENDED_POOL_FLAGS</a></div><div class="ttdeci">#define D3D12MA_RECOMMENDED_POOL_FLAGS</div><div class="ttdoc">Set of flags recommended for use in D3D12MA::POOL_DESC::Flags for optimal performance.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:141</div></div> -<div class="ttc" id="a_d3_d12_mem_alloc_8h_html_ac3d50f134ad24c58df4a934b87847653"><div class="ttname"><a href="_d3_d12_mem_alloc_8h.html#ac3d50f134ad24c58df4a934b87847653">D3D12MA_RECOMMENDED_HEAP_FLAGS</a></div><div class="ttdeci">#define D3D12MA_RECOMMENDED_HEAP_FLAGS</div><div class="ttdoc">Set of flags recommended for use in D3D12MA::POOL_DESC::HeapFlags for optimal performance.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:135</div></div> +<div class="ttc" id="a_d3_d12_mem_alloc_8h_html_a2679d8c9f6d900168bb45450bc88998b"><div class="ttname"><a href="_d3_d12_mem_alloc_8h.html#a2679d8c9f6d900168bb45450bc88998b">D3D12MA_RECOMMENDED_POOL_FLAGS</a></div><div class="ttdeci">#define D3D12MA_RECOMMENDED_POOL_FLAGS</div><div class="ttdoc">Set of flags recommended for use in D3D12MA::POOL_DESC::Flags for optimal performance.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:142</div></div> +<div class="ttc" id="a_d3_d12_mem_alloc_8h_html_ac3d50f134ad24c58df4a934b87847653"><div class="ttname"><a href="_d3_d12_mem_alloc_8h.html#ac3d50f134ad24c58df4a934b87847653">D3D12MA_RECOMMENDED_HEAP_FLAGS</a></div><div class="ttdeci">#define D3D12MA_RECOMMENDED_HEAP_FLAGS</div><div class="ttdoc">Set of flags recommended for use in D3D12MA::POOL_DESC::HeapFlags for optimal performance.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:136</div></div> </div><!-- fragment --><p>To allocate resources out of a custom pool, only set member <a class="el" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#ab06b85f3cf3254f855b29264477e3934" title="Custom pool to place the new resource in. Optional.">D3D12MA::ALLOCATION_DESC::CustomPool</a>. Example:</p> <div class="fragment"><div class="line">ALLOCATION_DESC allocDesc = {};</div> <div class="line">allocDesc.CustomPool = pool;</div>
diff --git a/docs/html/defragmentation.html b/docs/html/defragmentation.html index c0331fc..24b88e1 100644 --- a/docs/html/defragmentation.html +++ b/docs/html/defragmentation.html
@@ -149,19 +149,19 @@ <div class="line">defragCtx->Release();</div> <div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html_a414a088c22bae0f29b1038f5f9346d14"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html#a414a088c22bae0f29b1038f5f9346d14">D3D12MA::Allocation::SetResource</a></div><div class="ttdeci">void SetResource(ID3D12Resource *pResource)</div><div class="ttdoc">Releases the resource currently pointed by the allocation (if not null), sets it to new one,...</div></div> <div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html_a47be9557d441797b65de177a3d5cdf60"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html#a47be9557d441797b65de177a3d5cdf60">D3D12MA::Allocation::GetOffset</a></div><div class="ttdeci">UINT64 GetOffset() const</div><div class="ttdoc">Returns offset in bytes from the start of memory heap.</div></div> -<div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html_ad00308118252f82d8f803c623c67bf18"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html#ad00308118252f82d8f803c623c67bf18">D3D12MA::Allocation::GetResource</a></div><div class="ttdeci">ID3D12Resource * GetResource() const</div><div class="ttdoc">Returns D3D12 resource associated with this object.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:551</div></div> +<div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html_ad00308118252f82d8f803c623c67bf18"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html#ad00308118252f82d8f803c623c67bf18">D3D12MA::Allocation::GetResource</a></div><div class="ttdeci">ID3D12Resource * GetResource() const</div><div class="ttdoc">Returns D3D12 resource associated with this object.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:552</div></div> <div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html_adca8d5a82bed492fe7265fcda6e53da2"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html#adca8d5a82bed492fe7265fcda6e53da2">D3D12MA::Allocation::GetHeap</a></div><div class="ttdeci">ID3D12Heap * GetHeap() const</div><div class="ttdoc">Returns memory heap that the resource is created in.</div></div> -<div class="ttc" id="aclass_d3_d12_m_a_1_1_defragmentation_context_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_defragmentation_context.html">D3D12MA::DefragmentationContext</a></div><div class="ttdoc">Represents defragmentation process in progress.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:813</div></div> +<div class="ttc" id="aclass_d3_d12_m_a_1_1_defragmentation_context_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_defragmentation_context.html">D3D12MA::DefragmentationContext</a></div><div class="ttdoc">Represents defragmentation process in progress.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:814</div></div> <div class="ttc" id="aclass_d3_d12_m_a_1_1_defragmentation_context_html_a1606c015d02edc094bb246986159d592"><div class="ttname"><a href="class_d3_d12_m_a_1_1_defragmentation_context.html#a1606c015d02edc094bb246986159d592">D3D12MA::DefragmentationContext::BeginPass</a></div><div class="ttdeci">HRESULT BeginPass(DEFRAGMENTATION_PASS_MOVE_INFO *pPassInfo)</div><div class="ttdoc">Starts single defragmentation pass.</div></div> <div class="ttc" id="aclass_d3_d12_m_a_1_1_defragmentation_context_html_aad502ba70d6dadaeee37703fd8bf90ae"><div class="ttname"><a href="class_d3_d12_m_a_1_1_defragmentation_context.html#aad502ba70d6dadaeee37703fd8bf90ae">D3D12MA::DefragmentationContext::EndPass</a></div><div class="ttdeci">HRESULT EndPass(DEFRAGMENTATION_PASS_MOVE_INFO *pPassInfo)</div><div class="ttdoc">Ends single defragmentation pass.</div></div> -<div class="ttc" id="anamespace_d3_d12_m_a_html_ab433989212ee6736bf9d63c5bc565df4a9d0301a81136ca79e3ba52542c6d2e13"><div class="ttname"><a href="namespace_d3_d12_m_a.html#ab433989212ee6736bf9d63c5bc565df4a9d0301a81136ca79e3ba52542c6d2e13">D3D12MA::DEFRAGMENTATION_FLAG_ALGORITHM_FAST</a></div><div class="ttdeci">@ DEFRAGMENTATION_FLAG_ALGORITHM_FAST</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:693</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___d_e_s_c.html">D3D12MA::DEFRAGMENTATION_DESC</a></div><div class="ttdoc">Parameters for defragmentation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:715</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___d_e_s_c_html_aac9a357e679a0afa9ab84cd06057630b"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___d_e_s_c.html#aac9a357e679a0afa9ab84cd06057630b">D3D12MA::DEFRAGMENTATION_DESC::Flags</a></div><div class="ttdeci">DEFRAGMENTATION_FLAGS Flags</div><div class="ttdoc">Flags.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:717</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___m_o_v_e_html_a4946b874c958a71c21fac25b515cf5f7"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___m_o_v_e.html#a4946b874c958a71c21fac25b515cf5f7">D3D12MA::DEFRAGMENTATION_MOVE::pSrcAllocation</a></div><div class="ttdeci">Allocation * pSrcAllocation</div><div class="ttdoc">Allocation that should be moved.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:751</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___m_o_v_e_html_aec0c7f51ccc870c6a88af7c7390d8eda"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___m_o_v_e.html#aec0c7f51ccc870c6a88af7c7390d8eda">D3D12MA::DEFRAGMENTATION_MOVE::pDstTmpAllocation</a></div><div class="ttdeci">Allocation * pDstTmpAllocation</div><div class="ttdoc">Temporary allocation pointing to destination memory that will replace pSrcAllocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:759</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___p_a_s_s___m_o_v_e___i_n_f_o_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___p_a_s_s___m_o_v_e___i_n_f_o.html">D3D12MA::DEFRAGMENTATION_PASS_MOVE_INFO</a></div><div class="ttdoc">Parameters for incremental defragmentation steps.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:767</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___p_a_s_s___m_o_v_e___i_n_f_o_html_a719fbdaae54251759605c41baeb24dc4"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___p_a_s_s___m_o_v_e___i_n_f_o.html#a719fbdaae54251759605c41baeb24dc4">D3D12MA::DEFRAGMENTATION_PASS_MOVE_INFO::pMoves</a></div><div class="ttdeci">DEFRAGMENTATION_MOVE * pMoves</div><div class="ttdoc">Array of moves to be performed by the user in the current defragmentation pass.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:791</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___p_a_s_s___m_o_v_e___i_n_f_o_html_a8df22d990c318d82fe9fcc5f04132c04"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___p_a_s_s___m_o_v_e___i_n_f_o.html#a8df22d990c318d82fe9fcc5f04132c04">D3D12MA::DEFRAGMENTATION_PASS_MOVE_INFO::MoveCount</a></div><div class="ttdeci">UINT32 MoveCount</div><div class="ttdoc">Number of elements in the pMoves array.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:769</div></div> +<div class="ttc" id="anamespace_d3_d12_m_a_html_ab433989212ee6736bf9d63c5bc565df4a9d0301a81136ca79e3ba52542c6d2e13"><div class="ttname"><a href="namespace_d3_d12_m_a.html#ab433989212ee6736bf9d63c5bc565df4a9d0301a81136ca79e3ba52542c6d2e13">D3D12MA::DEFRAGMENTATION_FLAG_ALGORITHM_FAST</a></div><div class="ttdeci">@ DEFRAGMENTATION_FLAG_ALGORITHM_FAST</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:694</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___d_e_s_c.html">D3D12MA::DEFRAGMENTATION_DESC</a></div><div class="ttdoc">Parameters for defragmentation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:716</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___d_e_s_c_html_aac9a357e679a0afa9ab84cd06057630b"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___d_e_s_c.html#aac9a357e679a0afa9ab84cd06057630b">D3D12MA::DEFRAGMENTATION_DESC::Flags</a></div><div class="ttdeci">DEFRAGMENTATION_FLAGS Flags</div><div class="ttdoc">Flags.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:718</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___m_o_v_e_html_a4946b874c958a71c21fac25b515cf5f7"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___m_o_v_e.html#a4946b874c958a71c21fac25b515cf5f7">D3D12MA::DEFRAGMENTATION_MOVE::pSrcAllocation</a></div><div class="ttdeci">Allocation * pSrcAllocation</div><div class="ttdoc">Allocation that should be moved.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:752</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___m_o_v_e_html_aec0c7f51ccc870c6a88af7c7390d8eda"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___m_o_v_e.html#aec0c7f51ccc870c6a88af7c7390d8eda">D3D12MA::DEFRAGMENTATION_MOVE::pDstTmpAllocation</a></div><div class="ttdeci">Allocation * pDstTmpAllocation</div><div class="ttdoc">Temporary allocation pointing to destination memory that will replace pSrcAllocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:760</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___p_a_s_s___m_o_v_e___i_n_f_o_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___p_a_s_s___m_o_v_e___i_n_f_o.html">D3D12MA::DEFRAGMENTATION_PASS_MOVE_INFO</a></div><div class="ttdoc">Parameters for incremental defragmentation steps.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:768</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___p_a_s_s___m_o_v_e___i_n_f_o_html_a719fbdaae54251759605c41baeb24dc4"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___p_a_s_s___m_o_v_e___i_n_f_o.html#a719fbdaae54251759605c41baeb24dc4">D3D12MA::DEFRAGMENTATION_PASS_MOVE_INFO::pMoves</a></div><div class="ttdeci">DEFRAGMENTATION_MOVE * pMoves</div><div class="ttdoc">Array of moves to be performed by the user in the current defragmentation pass.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:792</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___p_a_s_s___m_o_v_e___i_n_f_o_html_a8df22d990c318d82fe9fcc5f04132c04"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_d_e_f_r_a_g_m_e_n_t_a_t_i_o_n___p_a_s_s___m_o_v_e___i_n_f_o.html#a8df22d990c318d82fe9fcc5f04132c04">D3D12MA::DEFRAGMENTATION_PASS_MOVE_INFO::MoveCount</a></div><div class="ttdeci">UINT32 MoveCount</div><div class="ttdoc">Number of elements in the pMoves array.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:770</div></div> </div><!-- fragment --><p>Although functions like <a class="el" href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a" title="Allocates memory and creates a D3D12 resource (buffer or texture). This is the main allocation functi...">D3D12MA::Allocator::CreateResource()</a> create an allocation and a buffer/texture at once, these are just a shortcut for allocating memory and creating a placed resource. Defragmentation works on memory allocations only. You must handle the rest manually. Defragmentation is an iterative process that should repreat "passes" as long as related functions return <code>S_FALSE</code> not <code>S_OK</code>. In each pass:</p> <ol type="1"> <li><a class="el" href="class_d3_d12_m_a_1_1_defragmentation_context.html#a1606c015d02edc094bb246986159d592" title="Starts single defragmentation pass.">D3D12MA::DefragmentationContext::BeginPass()</a> function call:<ul>
diff --git a/docs/html/doxygen_crawl.html b/docs/html/doxygen_crawl.html index f1b5a12..4abdf1d 100644 --- a/docs/html/doxygen_crawl.html +++ b/docs/html/doxygen_crawl.html
@@ -114,6 +114,7 @@ <a href="defragmentation.html"/> <a href="dir_d44c64559bbebec7f509842c48db8b23.html"/> <a href="doxygen_crawl.html"/> +<a href="faq.html"/> <a href="files.html"/> <a href="functions.html"/> <a href="functions_func.html"/>
diff --git a/docs/html/faq.html b/docs/html/faq.html new file mode 100644 index 0000000..eb29fe2 --- /dev/null +++ b/docs/html/faq.html
@@ -0,0 +1,171 @@ +<!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.13.0"/> +<meta name="viewport" content="width=device-width, initial-scale=1"/> +<title>D3D12 Memory Allocator: Frequenty asked questions</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> +<link href="navtree.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="resize.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.13.0 --> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */ +var searchBox = new SearchBox("searchBox", "search/",'.html'); +/* @license-end */ +</script> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */ +$(function() { codefold.init(0); }); +/* @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',false); + $(function() { init_search(); }); +}); +/* @license-end */ +</script> +<div id="main-nav"></div> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */ +$(function(){ initResizable(false); }); +/* @license-end */ +</script> +<!-- 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 class="el" 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">Frequenty asked questions</div></div> +</div><!--header--> +<div class="contents"> +<div class="textblock"><p><b>What is D3D12MA?</b></p> +<p>D3D12 Memory Allocator (D3D12MA) is a software library for developers who use the DirectX(R) 12 graphics API in their code. It is written in C++.</p> +<p><b>What is the license of D3D12MA?</b></p> +<p>D3D12MA is licensed under MIT, which means it is open source and free software.</p> +<p><b>What is the purpose of D3D12MA?</b></p> +<p>D3D12MA helps with handling one aspect of DX12 usage, which is GPU memory management - allocation of <code>ID3D12Heap</code> objects and creation of <code>ID3D12Resource</code> objects - buffers and textures.</p> +<p><b>Do I need to use D3D12MA?</b></p> +<p>You don't need to, but it may be beneficial in many cases. DX12 is a complex and low-level API, so libraries like this that abstract certain aspects of the API and bring them to a higher level are useful. When developing any non-trivial graphics application, you may benefit from using a memory allocator. Using D3D12MA can save time compared to implementing your own.</p> +<p>In DX12 you can create each resource separately with its own implicit memory heap by calling <code>CreateCommittedResource</code>, but this may not be the optimal solution. For more information, see <a class="el" href="optimal_allocation.html#optimal_allocation_committed_vs_placed">Committed versus placed resources</a>.</p> +<p><b>When should I not use D3D12MA?</b></p> +<p>While D3D12MA is useful for many applications that use the DX12 API, there are cases when it may be a better choice not to use it. For example, if the application is very simple, e.g. serving as a sample or a learning exercise to help you understand or teach others the basics of DX12, and it creates only a small number of buffers and textures, then including D3D12MA may be an overkill. Developing your own memory allocator may also be a good learning exercise.</p> +<p><b>What are the benefits of using D3D12MA?</b></p> +<ol type="1"> +<li>D3D12MA allocates large blocks of <code>ID3D12Heap</code> memory and sub-allocates parts of them to create your placed resources. Allocating a new block of GPU memory may be a time-consuming operation. Sub-allocating parts of a memory block requires implementing an allocation algorithm, which is a non-trivial task. D3D12MA does that, using an advanced and efficient algorithm that works well in various use cases.</li> +<li>D3D12MA offers a simple API that allows creating placed buffers and textures within one function call like <a class="el" href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a" title="Allocates memory and creates a D3D12 resource (buffer or texture). This is the main allocation functi...">D3D12MA::Allocator::CreateResource</a>.</li> +</ol> +<p>The library is doing much more under the hood. For example, it keeps buffers separate from textures when needed, respecting <code>D3D12_RESOURCE_HEAP_TIER</code>. It also makes use of the "small texture alignment" automatically, so you don't need to think about it.</p> +<p><b>Which version should I pick?</b></p> +<p>You can just pick <a href="https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator">the latest version from the "master" branch</a>. It is kept in a good shape most of the time, compiling and working correctly, with no compatibility-breaking changes and no unfinished code.</p> +<p>If you want an even more stable version, you can pick <a href="https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator/releases">the latest official release</a>. Current code from the master branch is occasionally tagged as a release, with <a href="https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator/blob/master/CHANGELOG.md">CHANGELOG</a> carefully curated to enumerate all important changes since the previous version.</p> +<p>The library uses <a href="https://semver.org/">Semantic Versioning</a>, which means versions that only differ in the patch number are forward and backward compatible (e.g., only fixing some bugs), while versions that differ in the minor number are backward compatible (e.g., only adding new functions to the API, but not removing or changing existing ones).</p> +<p><b>How to integrate it with my code?</b></p> +<p>D3D12MA is an small library fully implemented in a single pair of CPP + H files.</p> +<p>You can pull the entire GitHub repository, e.g. using Git submodules. The repository contains ancillary files like the Cmake script, Doxygen config file, sample application, test suite, and others. You can compile it as a library and link with your project.</p> +<p>However, a simpler way is taking only files "include\D3D12MemAlloc.h", "src\D3D12MemAlloc.cpp" and including them in your project. These files contain all you need: a copyright notice, declarations of the public library interface (API), its internal implementation, and even the documentation in form of Doxygen-style comments.</p> +<p><b>I am not a fan of modern C++. Can I still use it?</b></p> +<p>Very likely yes. We acknowledge that many C++ developers, especially in the games industry, do not appreciate all the latest features that the language has to offer.</p> +<ul> +<li>D3D12MA doesn't throw or catch any C++ exceptions. It reports errors by returning a <code>HRESULT</code> value instead, just like DX12. If you don't use exceptions in your project, your code is not exception-safe, or even if you disable exception handling in the compiler options, you can still use D3D12MA.</li> +<li>D3D12MA doesn't use C++ run-time type information like <code>typeid</code> or <code>dynamic_cast</code>, so if you disable RTTI in the compiler options, you can still use the library.</li> +<li>D3D12MA uses only a limited subset of standard C and C++ library. It doesn't use STL containers like <code>std::vector</code>, <code>map</code>, or <code>string</code>, either in the public interface nor in the internal implementation. It implements its own containers instead.</li> +<li>If you don't use the default heap memory allocator through <code>malloc/free</code> or <code>new/delete</code> but implement your own allocator instead, you can pass it to D3D12MA as <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> and the library will use your functions for every dynamic heap allocation made internally.</li> +</ul> +<p><b>Is it available for other programming languages?</b></p> +<p>D3D12MA is a C++ library in similar style as DX12. Bindings to other programming languages are out of scope of this project, but they are welcome as external projects. Some of them are listed in <a href="https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator/?tab=readme-ov-file#see-also">README.md, "See also" section</a>, including binding to C. Before using any of them, please check if they are still maintained and updated to use a recent version of D3D12MA.</p> +<p><b>What platforms does it support?</b></p> +<p>D3D12MA relies only on DX12 and some parts of the standard C and C++ library, so it could support any platform where a C++ compiler and DX12 are available. However, it is developed and tested only on Microsoft(R) Windows(R).</p> +<p><b>Does it only work on AMD GPUs?</b></p> +<p>No! While D3D12MA is published by AMD, it works on any GPU that supports DX12, whether a discrete PC graphics card or a processor integrated graphics. It doesn't give AMD GPUs any advantage over any other GPUs.</p> +<p><b>What DirectX 12 versions are supported?</b></p> +<p>D3D12MA is updated to support latest versions of DirectX 12, as available through recent retail versions of the <a href="https://devblogs.microsoft.com/directx/directx12agility/">DirectX 12 Agility SDK</a>. Support for new features added in the preview version of the Agility SDK is developed on separate branches until they are included in the retail version.</p> +<p>The library also supports older versions down to the base DX12 shipping with Windows SDK. Features added by later versions of the Agility SDK are automatically enabled conditionally using <code>#ifdef</code> preprocessor macros depending on the version of the SDK that you compile your project with.</p> +<p><b>Does it support other graphics APIs, like Vulkan(R)?</b></p> +<p>No, but we offer an equivalent library for Vulkan: <a href="https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator">Vulkan Memory Allocator</a>. It uses the same core allocation algorithm. It also shares many features with D3D12MA, like the support for custom pools and virtual allocator. However, it is not identical in terms of the features supported. Its API also looks different, because while the interface of D3D12MA is similar in style to DX12, the interface of VMA is similar to Vulkan.</p> +<p><b>Is the library lightweight?</b></p> +<p>Yes. D3D12MA is implemented with high-performance and real-time applications like video games in mind. The CPU performance overhead of using this library is low. It uses a high-quality allocation algorithm called Two-Level Segregated Fit (TLSF), which in most cases can find a free place for a new allocation in few steps. The library also doesn't perform too many CPU heap allocations. In many cases, the allocation happens with 0 new CPU heap allocations performed by the library. Even the creation of a <a class="el" href="class_d3_d12_m_a_1_1_allocation.html" title="Represents single memory allocation.">D3D12MA::Allocation</a> object doesn't typically feature an CPU allocation, because these objects are returned out of a dedicated memory pool.</p> +<p>That said, D3D12MA needs some extra memory and extra time to maintain the metadata about the occupied and free regions of the memory blocks, and the algorithms and data structures used must be generic enough to work well in most cases.</p> +<p><b>Does it have a documentation?</b></p> +<p>Yes! D3D12MA comes with full documentation of all elements of the API (classes, structures, enums), as well as many generic chapters that provide an introduction, describe core concepts of the library, good practices, etc. The entire documentation is written in form of code comments inside "D3D12MemAlloc.h", in Doxygen format. You can access it in multiple ways:</p> +<ul> +<li>Browsable online: <a href="https://gpuopen-librariesandsdks.github.io/D3D12MemoryAllocator/html/">https://gpuopen-librariesandsdks.github.io/D3D12MemoryAllocator/html/</a></li> +<li>Local HTML pages available after you clone the repository and open file "docs\html\index.html".</li> +<li>You can rebuild the documentation in HTML or some other format from the source code using Doxygen. Configuration file "Doxyfile" is part of the repository.</li> +<li>Finally, you can just read the comments preceding declarations of any public classes and functions of the library.</li> +</ul> +<p><b>Is it a mature project?</b></p> +<p>Yes! The library is in development since May 2019, has over 300 commits, and multiple contributors. It is used by many software projects, including some large and popular ones like Qt or Godot Engine, as well as some AAA games.</p> +<p><b>How can I contribute to the project?</b></p> +<p>If you have an idea for improvement or a feature request, you can go to <a href="https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator">the library repository</a> and create an Issue ticket, describing your idea. You can also implement it yourself by forking the repository, making changes to the code, and creating a Pull request.</p> +<p>If you want to ask a question, you can also create a ticket the same way. Before doing this, please make sure you read the relevant part of the DX12 documentation and D3D12MA documentation, where you may find the answers to your question.</p> +<p>If you want to report a suspected bug, you can also create a ticket the same way. Before doing this, please put some effort into the investigation of whether the bug is really in the library and not in your code or in the DX12 implementation (the GPU driver) on your platform:</p> +<ul> +<li>Enable D3D Debug Layer and make sure it is free from any errors.</li> +<li>Make sure <code>D3D12MA_ASSERT</code> is defined to an implementation that can report a failure and not ignore it.</li> +<li>Try making your allocation using pure DX12 functions like <code>CreateCommittedResource()</code> rather than D3D12MA and see if the bug persists.</li> +</ul> +<p><b>I found some compilation warnings. How can we fix them?</b></p> +<p>Seeing compiler warnings may be annoying to some developers, but it is a design decision to not fix all of them. Due to the nature of the C++ language, certain preprocessor macros can 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. For more information, see <a class="el" href="general_considerations.html#general_considerations_features_not_supported">Features not supported</a>.</p> +<p>However, if you observe a warning that is really dangerous, e.g., about an implicit conversion from a larger to a smaller integer type, please report it and it will be fixed ASAP. </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.13.0 +</small></address> +</div><!-- doc-content --> +</body> +</html>
diff --git a/docs/html/index.html b/docs/html/index.html index 14cd6ca..ad11257 100644 --- a/docs/html/index.html +++ b/docs/html/index.html
@@ -94,6 +94,7 @@ <h1><a class="anchor" id="main_table_of_contents"></a> Table of contents</h1> <ul> +<li><a class="el" href="faq.html">Frequenty asked questions</a></li> <li><a class="el" href="quick_start.html">Quick start</a><ul> <li><a class="el" href="quick_start.html#quick_start_project_setup">Project setup</a></li> <li><a class="el" href="quick_start.html#quick_start_creating_resources">Creating resources</a></li>
diff --git a/docs/html/optimal_allocation.html b/docs/html/optimal_allocation.html index b2d540e..79ef3ce 100644 --- a/docs/html/optimal_allocation.html +++ b/docs/html/optimal_allocation.html
@@ -110,9 +110,9 @@ <div class="line"> </div> <div class="line">UINT64 freeBytes = videoMemBudget.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_budget.html#a326515f08d89ee2e31dcfdd5c1e8ac71">BudgetBytes</a> - videoMemBudget.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_budget.html#a77a8c9e32d6602f95b7d1c285cddd253">UsageBytes</a>;</div> <div class="line">gameStreamingSystem->SetAvailableFreeMemory(freeBytes);</div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_budget_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_budget.html">D3D12MA::Budget</a></div><div class="ttdoc">Statistics of current memory usage and available budget for a specific memory segment group.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:473</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_budget_html_a326515f08d89ee2e31dcfdd5c1e8ac71"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_budget.html#a326515f08d89ee2e31dcfdd5c1e8ac71">D3D12MA::Budget::BudgetBytes</a></div><div class="ttdeci">UINT64 BudgetBytes</div><div class="ttdoc">Estimated amount of memory available to the program.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:496</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_budget_html_a77a8c9e32d6602f95b7d1c285cddd253"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_budget.html#a77a8c9e32d6602f95b7d1c285cddd253">D3D12MA::Budget::UsageBytes</a></div><div class="ttdeci">UINT64 UsageBytes</div><div class="ttdoc">Estimated current memory usage of the program.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:485</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_budget_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_budget.html">D3D12MA::Budget</a></div><div class="ttdoc">Statistics of current memory usage and available budget for a specific memory segment group.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:474</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_budget_html_a326515f08d89ee2e31dcfdd5c1e8ac71"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_budget.html#a326515f08d89ee2e31dcfdd5c1e8ac71">D3D12MA::Budget::BudgetBytes</a></div><div class="ttdeci">UINT64 BudgetBytes</div><div class="ttdoc">Estimated amount of memory available to the program.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:497</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_budget_html_a77a8c9e32d6602f95b7d1c285cddd253"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_budget.html#a77a8c9e32d6602f95b7d1c285cddd253">D3D12MA::Budget::UsageBytes</a></div><div class="ttdeci">UINT64 UsageBytes</div><div class="ttdoc">Estimated current memory usage of the program.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:486</div></div> </div><!-- fragment --><dl class="section user"><dt>Implementation detail</dt><dd>DXGI interface offers function <code>IDXGIAdapter3::QueryVideoMemoryInfo</code> that queries the current memory usage and budget. This library automatically makes use of it when available (when you use recent enough version of the DirectX SDK). If not, it falls back to estimating the usage and budget based on the total amount of the allocated memory and 80% of the full memory capacity, respectively.</dd></dl> <dl class="section user"><dt>Implementation detail</dt><dd>Allocating large heaps and creating placed resources in them is one of the main features of this library. However, if allocating new such block would exceed the budget, it will automatically prefer creating the resource as committed to have exactly the right size, which can lower the chance of getting into trouble in case of over-commitment.</dd></dl> <p>When creating non-essential resources, you can use <a class="el" href="namespace_d3_d12_m_a.html#abbad31a7e0b3d09d77f3fb704b77645eab374417c1f22a833ead268a6c21424e6">D3D12MA::ALLOCATION_FLAG_WITHIN_BUDGET</a>. Then, in case the allocation would exceed the budget, the library will return failure from the function without attempting to allocate the actual D3D12 memory.</p> @@ -163,18 +163,18 @@ <div class="line">hr = allocator->CreateResource(&allocDesc, &resDesc, D3D12_RESOURCE_STATE_COMMON,</div> <div class="line"> NULL, &alloc, IID_NULL, NULL);</div> <div class="line"><span class="comment">// Check hr...</span></div> -<div class="ttc" id="a_d3_d12_mem_alloc_8h_html_ac3d50f134ad24c58df4a934b87847653"><div class="ttname"><a href="_d3_d12_mem_alloc_8h.html#ac3d50f134ad24c58df4a934b87847653">D3D12MA_RECOMMENDED_HEAP_FLAGS</a></div><div class="ttdeci">#define D3D12MA_RECOMMENDED_HEAP_FLAGS</div><div class="ttdoc">Set of flags recommended for use in D3D12MA::POOL_DESC::HeapFlags for optimal performance.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:135</div></div> -<div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html">D3D12MA::Allocation</a></div><div class="ttdoc">Represents single memory allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:522</div></div> -<div class="ttc" id="aclass_d3_d12_m_a_1_1_pool_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_pool.html">D3D12MA::Pool</a></div><div class="ttdoc">Custom memory pool.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:991</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::CALLOCATION_DESC</a></div><div class="ttdoc">Helper structure that helps with complete and conscise initialization of the D3D12MA::ALLOCATION_DESC...</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1656</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_c_p_o_o_l___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_c_p_o_o_l___d_e_s_c.html">D3D12MA::CPOOL_DESC</a></div><div class="ttdoc">Helper structure that helps with complete and conscise initialization of the D3D12MA::POOL_DESC struc...</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1692</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c_html_a2e6074af8c8ff7b957fe8d4b5036a5e6"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#a2e6074af8c8ff7b957fe8d4b5036a5e6">D3D12MA::POOL_DESC::ResidencyPriority</a></div><div class="ttdeci">D3D12_RESIDENCY_PRIORITY ResidencyPriority</div><div class="ttdoc">Residency priority to be set for all allocations made in this pool. Optional.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:979</div></div> +<div class="ttc" id="a_d3_d12_mem_alloc_8h_html_ac3d50f134ad24c58df4a934b87847653"><div class="ttname"><a href="_d3_d12_mem_alloc_8h.html#ac3d50f134ad24c58df4a934b87847653">D3D12MA_RECOMMENDED_HEAP_FLAGS</a></div><div class="ttdeci">#define D3D12MA_RECOMMENDED_HEAP_FLAGS</div><div class="ttdoc">Set of flags recommended for use in D3D12MA::POOL_DESC::HeapFlags for optimal performance.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:136</div></div> +<div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html">D3D12MA::Allocation</a></div><div class="ttdoc">Represents single memory allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:523</div></div> +<div class="ttc" id="aclass_d3_d12_m_a_1_1_pool_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_pool.html">D3D12MA::Pool</a></div><div class="ttdoc">Custom memory pool.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:992</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::CALLOCATION_DESC</a></div><div class="ttdoc">Helper structure that helps with complete and conscise initialization of the D3D12MA::ALLOCATION_DESC...</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1657</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_c_p_o_o_l___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_c_p_o_o_l___d_e_s_c.html">D3D12MA::CPOOL_DESC</a></div><div class="ttdoc">Helper structure that helps with complete and conscise initialization of the D3D12MA::POOL_DESC struc...</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1693</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c_html_a2e6074af8c8ff7b957fe8d4b5036a5e6"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#a2e6074af8c8ff7b957fe8d4b5036a5e6">D3D12MA::POOL_DESC::ResidencyPriority</a></div><div class="ttdeci">D3D12_RESIDENCY_PRIORITY ResidencyPriority</div><div class="ttdoc">Residency priority to be set for all allocations made in this pool. Optional.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:980</div></div> </div><!-- fragment --><p>When you have a committed allocation created, you can also set the residency priority of its resource using the D3D12 function:</p> <div class="fragment"><div class="line"><a class="code hl_class" href="class_d3_d12_m_a_1_1_allocation.html">D3D12MA::Allocation</a>* committedAlloc = ...</div> <div class="line">ID3D12Pageable* res = committedAlloc-><a class="code hl_function" href="class_d3_d12_m_a_1_1_allocation.html#ad00308118252f82d8f803c623c67bf18">GetResource</a>();</div> <div class="line">D3D12_RESIDENCY_PRIORITY priority = D3D12_RESIDENCY_PRIORITY_HIGH;</div> <div class="line">device1->SetResidencyPriority(1, &res, &priority);</div> -<div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html_ad00308118252f82d8f803c623c67bf18"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html#ad00308118252f82d8f803c623c67bf18">D3D12MA::Allocation::GetResource</a></div><div class="ttdeci">ID3D12Resource * GetResource() const</div><div class="ttdoc">Returns D3D12 resource associated with this object.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:551</div></div> +<div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html_ad00308118252f82d8f803c623c67bf18"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html#ad00308118252f82d8f803c623c67bf18">D3D12MA::Allocation::GetResource</a></div><div class="ttdeci">ID3D12Resource * GetResource() const</div><div class="ttdoc">Returns D3D12 resource associated with this object.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:552</div></div> </div><!-- fragment --><p>Note this is not the same as explicit eviction controlled using <code>ID3D12Device::Evict</code> and <code>MakeResident</code> functions. Resources evicted explicitly are illegal to access until they are made resident again, while the demotion described here happens automatically and only slows down the execution.</p> <h1><a class="anchor" id="optimal_allocation_gpu_upload_heap"></a> GPU upload heap</h1> @@ -239,7 +239,7 @@ <div class="line">}</div> <div class="line"><span class="keywordflow">else</span></div> <div class="line"> <span class="comment">// Some other error code e.g., out of memory...</span></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_aa46b3c0456e5a23edef3328607ebf4d7"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#aa46b3c0456e5a23edef3328607ebf4d7">D3D12MA::ALLOCATION_DESC::HeapType</a></div><div class="ttdeci">D3D12_HEAP_TYPE HeapType</div><div class="ttdoc">The type of memory heap where the new allocation should be placed.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:346</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_aa46b3c0456e5a23edef3328607ebf4d7"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#aa46b3c0456e5a23edef3328607ebf4d7">D3D12MA::ALLOCATION_DESC::HeapType</a></div><div class="ttdeci">D3D12_HEAP_TYPE HeapType</div><div class="ttdoc">The type of memory heap where the new allocation should be placed.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:347</div></div> </div><!-- fragment --><h1><a class="anchor" id="optimal_allocation_committed_vs_placed"></a> Committed versus placed resources</h1> <p>When using D3D12 API directly, there are 3 ways of creating resources:</p> @@ -300,7 +300,7 @@ <div class="line"><span class="comment">// Even a large buffer like this, filling 90% of the block, was created as placed!</span></div> <div class="line">assert(alloc-><a class="code hl_function" href="class_d3_d12_m_a_1_1_allocation.html#adca8d5a82bed492fe7265fcda6e53da2">GetHeap</a>() != NULL);</div> <div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html_adca8d5a82bed492fe7265fcda6e53da2"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html#adca8d5a82bed492fe7265fcda6e53da2">D3D12MA::Allocation::GetHeap</a></div><div class="ttdeci">ID3D12Heap * GetHeap() const</div><div class="ttdoc">Returns memory heap that the resource is created in.</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c_html_af7284cc51a8ed5b551075584256de23c"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#af7284cc51a8ed5b551075584256de23c">D3D12MA::POOL_DESC::BlockSize</a></div><div class="ttdeci">UINT64 BlockSize</div><div class="ttdoc">Size of a single heap (memory block) to be allocated as part of this pool, in bytes....</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:932</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c_html_af7284cc51a8ed5b551075584256de23c"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#af7284cc51a8ed5b551075584256de23c">D3D12MA::POOL_DESC::BlockSize</a></div><div class="ttdeci">UINT64 BlockSize</div><div class="ttdoc">Size of a single heap (memory block) to be allocated as part of this pool, in bytes....</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:933</div></div> </div><!-- fragment --><p><b>You can request a new resource to be created as placed</b> by using <a class="el" href="namespace_d3_d12_m_a.html#abbad31a7e0b3d09d77f3fb704b77645ea4d6808f27de6d0ae57014ec1f4d54326">D3D12MA::ALLOCATION_FLAG_CAN_ALIAS</a>. This is required especially if you plan to create another resource in the same region of memory, aliasing with your resource - hence the name of this flag.</p> <p>Note <a class="el" href="namespace_d3_d12_m_a.html#abbad31a7e0b3d09d77f3fb704b77645ea4d6808f27de6d0ae57014ec1f4d54326">D3D12MA::ALLOCATION_FLAG_CAN_ALIAS</a> can be even combined with <a class="el" href="namespace_d3_d12_m_a.html#abbad31a7e0b3d09d77f3fb704b77645ea661a5472dba3dcecc5a2cc92afd25675">D3D12MA::ALLOCATION_FLAG_COMMITTED</a>. In this case, the resource is not created as committed, but it is also not placed as part of a larger heap. What happens instead is that a new heap is created with the exact size required for the resource, and the resource is created in it, placed at offset 0.</p> <h1><a class="anchor" id="optimal_allocation_resource_alignment"></a>
diff --git a/docs/html/quick_start.html b/docs/html/quick_start.html index b6f51c9..83bd0e2 100644 --- a/docs/html/quick_start.html +++ b/docs/html/quick_start.html
@@ -114,8 +114,8 @@ <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:127</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:1162</div></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:1163</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><!-- fragment --><p>(5.) Right before destroying the D3D12 device, destroy the allocator object.</p> <div class="fragment"><div class="line">allocator->Release();</div> @@ -153,11 +153,11 @@ <div class="line"> </div> <div class="line">ID3D12Resource* res = allocation-><a class="code hl_function" href="class_d3_d12_m_a_1_1_allocation.html#ad00308118252f82d8f803c623c67bf18">GetResource</a>();</div> <div class="line"><span class="comment">// Use res...</span></div> -<div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html">D3D12MA::Allocation</a></div><div class="ttdoc">Represents single memory allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:522</div></div> -<div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html_ad00308118252f82d8f803c623c67bf18"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html#ad00308118252f82d8f803c623c67bf18">D3D12MA::Allocation::GetResource</a></div><div class="ttdeci">ID3D12Resource * GetResource() const</div><div class="ttdoc">Returns D3D12 resource associated with this object.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:551</div></div> +<div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html">D3D12MA::Allocation</a></div><div class="ttdoc">Represents single memory allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:523</div></div> +<div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html_ad00308118252f82d8f803c623c67bf18"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html#ad00308118252f82d8f803c623c67bf18">D3D12MA::Allocation::GetResource</a></div><div class="ttdeci">ID3D12Resource * GetResource() const</div><div class="ttdoc">Returns D3D12 resource associated with this object.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:552</div></div> <div class="ttc" id="aclass_d3_d12_m_a_1_1_allocator_html_aa37d6b9fe8ea0864f7a35b9d68e8345a"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a">D3D12MA::Allocator::CreateResource</a></div><div class="ttdeci">HRESULT CreateResource(const ALLOCATION_DESC *pAllocDesc, const D3D12_RESOURCE_DESC *pResourceDesc, D3D12_RESOURCE_STATES InitialResourceState, const D3D12_CLEAR_VALUE *pOptimizedClearValue, Allocation **ppAllocation, REFIID riidResource, void **ppvResource)</div><div class="ttdoc">Allocates memory and creates a D3D12 resource (buffer or texture). This is the main allocation functi...</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::ALLOCATION_DESC</a></div><div class="ttdoc">Parameters of created D3D12MA::Allocation object. To be used with Allocator::CreateResource.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:337</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_aa46b3c0456e5a23edef3328607ebf4d7"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#aa46b3c0456e5a23edef3328607ebf4d7">D3D12MA::ALLOCATION_DESC::HeapType</a></div><div class="ttdeci">D3D12_HEAP_TYPE HeapType</div><div class="ttdoc">The type of memory heap where the new allocation should be placed.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:346</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::ALLOCATION_DESC</a></div><div class="ttdoc">Parameters of created D3D12MA::Allocation object. To be used with Allocator::CreateResource.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:338</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_aa46b3c0456e5a23edef3328607ebf4d7"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#aa46b3c0456e5a23edef3328607ebf4d7">D3D12MA::ALLOCATION_DESC::HeapType</a></div><div class="ttdeci">D3D12_HEAP_TYPE HeapType</div><div class="ttdoc">The type of memory heap where the new allocation should be placed.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:347</div></div> </div><!-- fragment --><p>You need to release the allocation object when no longer needed. This will also release the D3D12 resource.</p> <div class="fragment"><div class="line">allocation->Release();</div> </div><!-- fragment --><p>The advantage of using the allocator instead of creating committed resource, and the main purpose of this library, is that it can decide to allocate bigger memory heap internally using <code>ID3D12Device::CreateHeap</code> and place multiple resources in it, at different offsets, using <code>ID3D12Device::CreatePlacedResource</code>. The library manages its own collection of allocated memory blocks (heaps) and remembers which parts of them are occupied and which parts are free to be used for new resources.</p> @@ -269,11 +269,11 @@ <div class="line">HRESULT hr = allocator-><a class="code hl_function" href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a">CreateResource</a>(&allocDesc, &resDesc,</div> <div class="line"> D3D12_RESOURCE_STATE_COMMON, NULL, &alloc, IID_PPV_ARGS(&res));</div> <div class="line"><span class="comment">// Check hr...</span></div> -<div class="ttc" id="anamespace_d3_d12_m_a_html_abbad31a7e0b3d09d77f3fb704b77645eaa3ded8847563c24b4522af0586dbd2cb"><div class="ttname"><a href="namespace_d3_d12_m_a.html#abbad31a7e0b3d09d77f3fb704b77645eaa3ded8847563c24b4522af0586dbd2cb">D3D12MA::ALLOCATION_FLAG_STRATEGY_MIN_TIME</a></div><div class="ttdeci">@ ALLOCATION_FLAG_STRATEGY_MIN_TIME</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:315</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_a92dec49b788a334fc91c55340dfbace6"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a92dec49b788a334fc91c55340dfbace6">D3D12MA::ALLOCATION_DESC::Flags</a></div><div class="ttdeci">ALLOCATION_FLAGS Flags</div><div class="ttdoc">Flags for the allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:339</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_a97878838f976b2d1e6b1a76881035690"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a97878838f976b2d1e6b1a76881035690">D3D12MA::ALLOCATION_DESC::ExtraHeapFlags</a></div><div class="ttdeci">D3D12_HEAP_FLAGS ExtraHeapFlags</div><div class="ttdoc">Additional heap flags to be used when allocating memory.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:362</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_ab06b85f3cf3254f855b29264477e3934"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#ab06b85f3cf3254f855b29264477e3934">D3D12MA::ALLOCATION_DESC::CustomPool</a></div><div class="ttdeci">Pool * CustomPool</div><div class="ttdoc">Custom pool to place the new resource in. Optional.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:368</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_ac638dd987f1326e2fdab91892d994d35"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#ac638dd987f1326e2fdab91892d994d35">D3D12MA::ALLOCATION_DESC::pPrivateData</a></div><div class="ttdeci">void * pPrivateData</div><div class="ttdoc">Custom general-purpose pointer that will be stored in D3D12MA::Allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:370</div></div> +<div class="ttc" id="anamespace_d3_d12_m_a_html_abbad31a7e0b3d09d77f3fb704b77645eaa3ded8847563c24b4522af0586dbd2cb"><div class="ttname"><a href="namespace_d3_d12_m_a.html#abbad31a7e0b3d09d77f3fb704b77645eaa3ded8847563c24b4522af0586dbd2cb">D3D12MA::ALLOCATION_FLAG_STRATEGY_MIN_TIME</a></div><div class="ttdeci">@ ALLOCATION_FLAG_STRATEGY_MIN_TIME</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:316</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_a92dec49b788a334fc91c55340dfbace6"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a92dec49b788a334fc91c55340dfbace6">D3D12MA::ALLOCATION_DESC::Flags</a></div><div class="ttdeci">ALLOCATION_FLAGS Flags</div><div class="ttdoc">Flags for the allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:340</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_a97878838f976b2d1e6b1a76881035690"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a97878838f976b2d1e6b1a76881035690">D3D12MA::ALLOCATION_DESC::ExtraHeapFlags</a></div><div class="ttdeci">D3D12_HEAP_FLAGS ExtraHeapFlags</div><div class="ttdoc">Additional heap flags to be used when allocating memory.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:363</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_ab06b85f3cf3254f855b29264477e3934"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#ab06b85f3cf3254f855b29264477e3934">D3D12MA::ALLOCATION_DESC::CustomPool</a></div><div class="ttdeci">Pool * CustomPool</div><div class="ttdoc">Custom pool to place the new resource in. Optional.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:369</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_ac638dd987f1326e2fdab91892d994d35"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#ac638dd987f1326e2fdab91892d994d35">D3D12MA::ALLOCATION_DESC::pPrivateData</a></div><div class="ttdeci">void * pPrivateData</div><div class="ttdoc">Custom general-purpose pointer that will be stored in D3D12MA::Allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:371</div></div> </div><!-- fragment --><p>Or you can use helper structs from both D3X12 library and this library to make the code shorter:</p> <div class="fragment"><div class="line"><a class="code hl_struct" href="struct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::CALLOCATION_DESC</a> allocDesc = <a class="code hl_struct" href="struct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::CALLOCATION_DESC</a>{</div> <div class="line"> D3D12_HEAP_TYPE_UPLOAD,</div> @@ -286,7 +286,7 @@ <div class="line">HRESULT hr = allocator-><a class="code hl_function" href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a">CreateResource</a>(&allocDesc, &resDesc,</div> <div class="line"> D3D12_RESOURCE_STATE_COMMON, NULL, &alloc, IID_PPV_ARGS(&res));</div> <div class="line"><span class="comment">// Check hr...</span></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::CALLOCATION_DESC</a></div><div class="ttdoc">Helper structure that helps with complete and conscise initialization of the D3D12MA::ALLOCATION_DESC...</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1656</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::CALLOCATION_DESC</a></div><div class="ttdoc">Helper structure that helps with complete and conscise initialization of the D3D12MA::ALLOCATION_DESC...</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1657</div></div> </div><!-- fragment --> </div></div><!-- contents --> </div><!-- PageDoc --> <!-- start footer part -->
diff --git a/docs/html/resource_aliasing.html b/docs/html/resource_aliasing.html index f24db13..df40fa8 100644 --- a/docs/html/resource_aliasing.html +++ b/docs/html/resource_aliasing.html
@@ -166,11 +166,11 @@ <div class="line">res2->Release();</div> <div class="line">res1->Release();</div> <div class="line">alloc->Release();</div> -<div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html">D3D12MA::Allocation</a></div><div class="ttdoc">Represents single memory allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:522</div></div> +<div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html">D3D12MA::Allocation</a></div><div class="ttdoc">Represents single memory allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:523</div></div> <div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html_adca8d5a82bed492fe7265fcda6e53da2"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html#adca8d5a82bed492fe7265fcda6e53da2">D3D12MA::Allocation::GetHeap</a></div><div class="ttdeci">ID3D12Heap * GetHeap() const</div><div class="ttdoc">Returns memory heap that the resource is created in.</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::ALLOCATION_DESC</a></div><div class="ttdoc">Parameters of created D3D12MA::Allocation object. To be used with Allocator::CreateResource.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:337</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_a97878838f976b2d1e6b1a76881035690"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a97878838f976b2d1e6b1a76881035690">D3D12MA::ALLOCATION_DESC::ExtraHeapFlags</a></div><div class="ttdeci">D3D12_HEAP_FLAGS ExtraHeapFlags</div><div class="ttdoc">Additional heap flags to be used when allocating memory.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:362</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_aa46b3c0456e5a23edef3328607ebf4d7"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#aa46b3c0456e5a23edef3328607ebf4d7">D3D12MA::ALLOCATION_DESC::HeapType</a></div><div class="ttdeci">D3D12_HEAP_TYPE HeapType</div><div class="ttdoc">The type of memory heap where the new allocation should be placed.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:346</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::ALLOCATION_DESC</a></div><div class="ttdoc">Parameters of created D3D12MA::Allocation object. To be used with Allocator::CreateResource.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:338</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_a97878838f976b2d1e6b1a76881035690"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a97878838f976b2d1e6b1a76881035690">D3D12MA::ALLOCATION_DESC::ExtraHeapFlags</a></div><div class="ttdeci">D3D12_HEAP_FLAGS ExtraHeapFlags</div><div class="ttdoc">Additional heap flags to be used when allocating memory.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:363</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_aa46b3c0456e5a23edef3328607ebf4d7"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#aa46b3c0456e5a23edef3328607ebf4d7">D3D12MA::ALLOCATION_DESC::HeapType</a></div><div class="ttdeci">D3D12_HEAP_TYPE HeapType</div><div class="ttdoc">The type of memory heap where the new allocation should be placed.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:347</div></div> </div><!-- fragment --><p>Remember that using resouces that alias in memory requires proper synchronization. You need to issue a special barrier of type <code>D3D12_RESOURCE_BARRIER_TYPE_ALIASING</code>. You also need to treat a resource after aliasing as uninitialized - containing garbage data. For example, if you use <code>res1</code> and then want to use <code>res2</code>, you need to first initialize <code>res2</code> using either Clear, Discard, or Copy to the entire resource.</p> <p>Additional considerations:</p> <ul>
diff --git a/docs/html/search/all_0.js b/docs/html/search/all_0.js index 5afdd52..fa900d4 100644 --- a/docs/html/search/all_0.js +++ b/docs/html/search/all_0.js
@@ -52,6 +52,7 @@ ['and_20compatibility_49',['Versioning and compatibility',['../general_considerations.html#general_considerations_versioning_and_compatibility',1,'']]], ['and_20initialization_50',['Project setup and initialization',['../quick_start.html#quick_start_project_setup',1,'']]], ['and_20units_51',['Alignment and units',['../virtual_allocator.html#virtual_allocator_alignment_and_units',1,'']]], - ['at_20once_52',['Free-at-once',['../linear_algorithm.html#linear_algorithm_free_at_once',1,'']]], - ['avoiding_20running_20out_20of_20memory_53',['Avoiding running out of memory',['../optimal_allocation.html#optimal_allocation_avoiding_running_out_of_memory',1,'']]] + ['asked_20questions_52',['Frequenty asked questions',['../faq.html',1,'index']]], + ['at_20once_53',['Free-at-once',['../linear_algorithm.html#linear_algorithm_free_at_once',1,'']]], + ['avoiding_20running_20out_20of_20memory_54',['Avoiding running out of memory',['../optimal_allocation.html#optimal_allocation_avoiding_running_out_of_memory',1,'']]] ];
diff --git a/docs/html/search/all_5.js b/docs/html/search/all_5.js index 139f958..7034992 100644 --- a/docs/html/search/all_5.js +++ b/docs/html/search/all_5.js
@@ -6,5 +6,6 @@ ['free_20at_20once_3',['Free-at-once',['../linear_algorithm.html#linear_algorithm_free_at_once',1,'']]], ['free_5ffunc_5fptr_4',['FREE_FUNC_PTR',['../namespace_d3_d12_m_a.html#a7c61f55eeb64451cb0c08c0461bbe1a3',1,'D3D12MA']]], ['freeallocation_5',['FreeAllocation',['../class_d3_d12_m_a_1_1_virtual_block.html#aab44e46bd122054c894fc84740f1e8fb',1,'D3D12MA::VirtualBlock']]], - ['freestatsstring_6',['FreeStatsString',['../class_d3_d12_m_a_1_1_allocator.html#a8392663494384c16d8bfa12b827b4f9c',1,'D3D12MA::Allocator::FreeStatsString()'],['../class_d3_d12_m_a_1_1_virtual_block.html#a6f78ddaa7da194e239089e52093e68a9',1,'D3D12MA::VirtualBlock::FreeStatsString()']]] + ['freestatsstring_6',['FreeStatsString',['../class_d3_d12_m_a_1_1_allocator.html#a8392663494384c16d8bfa12b827b4f9c',1,'D3D12MA::Allocator::FreeStatsString()'],['../class_d3_d12_m_a_1_1_virtual_block.html#a6f78ddaa7da194e239089e52093e68a9',1,'D3D12MA::VirtualBlock::FreeStatsString()']]], + ['frequenty_20asked_20questions_7',['Frequenty asked questions',['../faq.html',1,'index']]] ];
diff --git a/docs/html/search/all_f.js b/docs/html/search/all_f.js index 813ffa8..06873a2 100644 --- a/docs/html/search/all_f.js +++ b/docs/html/search/all_f.js
@@ -1,4 +1,5 @@ var searchData= [ - ['quick_20start_0',['Quick start',['../quick_start.html',1,'index']]] + ['questions_0',['Frequenty asked questions',['../faq.html',1,'index']]], + ['quick_20start_1',['Quick start',['../quick_start.html',1,'index']]] ];
diff --git a/docs/html/search/pages_0.js b/docs/html/search/pages_0.js index 45dc28f..cfda587 100644 --- a/docs/html/search/pages_0.js +++ b/docs/html/search/pages_0.js
@@ -5,5 +5,6 @@ ['allocation_2',['Optimal resource allocation',['../optimal_allocation.html',1,'index']]], ['allocation_20algorithm_3',['Linear allocation algorithm',['../linear_algorithm.html',1,'index']]], ['allocator_4',['D3D12 Memory Allocator',['../index.html',1,'']]], - ['allocator_5',['Virtual allocator',['../virtual_allocator.html',1,'optimal_allocation']]] + ['allocator_5',['Virtual allocator',['../virtual_allocator.html',1,'optimal_allocation']]], + ['asked_20questions_6',['Frequenty asked questions',['../faq.html',1,'index']]] ];
diff --git a/docs/html/search/pages_3.js b/docs/html/search/pages_3.js index 1aed57d..1e569e4 100644 --- a/docs/html/search/pages_3.js +++ b/docs/html/search/pages_3.js
@@ -1,4 +1,4 @@ var searchData= [ - ['general_20considerations_0',['General considerations',['../general_considerations.html',1,'index']]] + ['frequenty_20asked_20questions_0',['Frequenty asked questions',['../faq.html',1,'index']]] ];
diff --git a/docs/html/search/pages_4.js b/docs/html/search/pages_4.js index b965ff9..1aed57d 100644 --- a/docs/html/search/pages_4.js +++ b/docs/html/search/pages_4.js
@@ -1,4 +1,4 @@ var searchData= [ - ['linear_20allocation_20algorithm_0',['Linear allocation algorithm',['../linear_algorithm.html',1,'index']]] + ['general_20considerations_0',['General considerations',['../general_considerations.html',1,'index']]] ];
diff --git a/docs/html/search/pages_5.js b/docs/html/search/pages_5.js index 2fa4310..b965ff9 100644 --- a/docs/html/search/pages_5.js +++ b/docs/html/search/pages_5.js
@@ -1,5 +1,4 @@ var searchData= [ - ['memory_20allocator_0',['D3D12 Memory Allocator',['../index.html',1,'']]], - ['memory_20pools_1',['Custom memory pools',['../custom_pools.html',1,'optimal_allocation']]] + ['linear_20allocation_20algorithm_0',['Linear allocation algorithm',['../linear_algorithm.html',1,'index']]] ];
diff --git a/docs/html/search/pages_6.js b/docs/html/search/pages_6.js index 0c3cb7f..2fa4310 100644 --- a/docs/html/search/pages_6.js +++ b/docs/html/search/pages_6.js
@@ -1,5 +1,5 @@ var searchData= [ - ['optimal_20resource_20allocation_0',['Optimal resource allocation',['../optimal_allocation.html',1,'index']]], - ['overlap_1',['Resource aliasing (overlap)',['../resource_aliasing.html',1,'optimal_allocation']]] + ['memory_20allocator_0',['D3D12 Memory Allocator',['../index.html',1,'']]], + ['memory_20pools_1',['Custom memory pools',['../custom_pools.html',1,'optimal_allocation']]] ];
diff --git a/docs/html/search/pages_7.js b/docs/html/search/pages_7.js index f4128dd..0c3cb7f 100644 --- a/docs/html/search/pages_7.js +++ b/docs/html/search/pages_7.js
@@ -1,4 +1,5 @@ var searchData= [ - ['pools_0',['Custom memory pools',['../custom_pools.html',1,'optimal_allocation']]] + ['optimal_20resource_20allocation_0',['Optimal resource allocation',['../optimal_allocation.html',1,'index']]], + ['overlap_1',['Resource aliasing (overlap)',['../resource_aliasing.html',1,'optimal_allocation']]] ];
diff --git a/docs/html/search/pages_8.js b/docs/html/search/pages_8.js index 813ffa8..f4128dd 100644 --- a/docs/html/search/pages_8.js +++ b/docs/html/search/pages_8.js
@@ -1,4 +1,4 @@ var searchData= [ - ['quick_20start_0',['Quick start',['../quick_start.html',1,'index']]] + ['pools_0',['Custom memory pools',['../custom_pools.html',1,'optimal_allocation']]] ];
diff --git a/docs/html/search/pages_9.js b/docs/html/search/pages_9.js index 53f0a34..06873a2 100644 --- a/docs/html/search/pages_9.js +++ b/docs/html/search/pages_9.js
@@ -1,5 +1,5 @@ var searchData= [ - ['resource_20aliasing_20overlap_0',['Resource aliasing (overlap)',['../resource_aliasing.html',1,'optimal_allocation']]], - ['resource_20allocation_1',['Optimal resource allocation',['../optimal_allocation.html',1,'index']]] + ['questions_0',['Frequenty asked questions',['../faq.html',1,'index']]], + ['quick_20start_1',['Quick start',['../quick_start.html',1,'index']]] ];
diff --git a/docs/html/search/pages_a.js b/docs/html/search/pages_a.js index d4b7ec0..53f0a34 100644 --- a/docs/html/search/pages_a.js +++ b/docs/html/search/pages_a.js
@@ -1,5 +1,5 @@ var searchData= [ - ['start_0',['Quick start',['../quick_start.html',1,'index']]], - ['statistics_1',['Statistics',['../statistics.html',1,'optimal_allocation']]] + ['resource_20aliasing_20overlap_0',['Resource aliasing (overlap)',['../resource_aliasing.html',1,'optimal_allocation']]], + ['resource_20allocation_1',['Optimal resource allocation',['../optimal_allocation.html',1,'index']]] ];
diff --git a/docs/html/search/pages_b.js b/docs/html/search/pages_b.js index 6f1ceb8..d4b7ec0 100644 --- a/docs/html/search/pages_b.js +++ b/docs/html/search/pages_b.js
@@ -1,4 +1,5 @@ var searchData= [ - ['virtual_20allocator_0',['Virtual allocator',['../virtual_allocator.html',1,'optimal_allocation']]] + ['start_0',['Quick start',['../quick_start.html',1,'index']]], + ['statistics_1',['Statistics',['../statistics.html',1,'optimal_allocation']]] ];
diff --git a/docs/html/search/pages_c.js b/docs/html/search/pages_c.js new file mode 100644 index 0000000..6f1ceb8 --- /dev/null +++ b/docs/html/search/pages_c.js
@@ -0,0 +1,4 @@ +var searchData= +[ + ['virtual_20allocator_0',['Virtual allocator',['../virtual_allocator.html',1,'optimal_allocation']]] +];
diff --git a/docs/html/search/searchdata.js b/docs/html/search/searchdata.js index b0a256b..1b7813a 100644 --- a/docs/html/search/searchdata.js +++ b/docs/html/search/searchdata.js
@@ -11,7 +11,7 @@ 8: "adpv", 9: "cd", 10: "d", - 11: "acdglmopqrsv" + 11: "acdfglmopqrsv" }; var indexSectionNames =
diff --git a/docs/html/statistics.html b/docs/html/statistics.html index c49c20a..ceca76e 100644 --- a/docs/html/statistics.html +++ b/docs/html/statistics.html
@@ -107,9 +107,9 @@ <div class="line">printf(<span class="stringliteral">"D3D12 reports total usage %llu B with budget %llu B.\n"</span>,</div> <div class="line"> localBudget.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_budget.html#a77a8c9e32d6602f95b7d1c285cddd253">UsageBytes</a>,</div> <div class="line"> localBudget.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_budget.html#a326515f08d89ee2e31dcfdd5c1e8ac71">BudgetBytes</a>);</div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_budget_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_budget.html">D3D12MA::Budget</a></div><div class="ttdoc">Statistics of current memory usage and available budget for a specific memory segment group.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:473</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_budget_html_a326515f08d89ee2e31dcfdd5c1e8ac71"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_budget.html#a326515f08d89ee2e31dcfdd5c1e8ac71">D3D12MA::Budget::BudgetBytes</a></div><div class="ttdeci">UINT64 BudgetBytes</div><div class="ttdoc">Estimated amount of memory available to the program.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:496</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_budget_html_a77a8c9e32d6602f95b7d1c285cddd253"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_budget.html#a77a8c9e32d6602f95b7d1c285cddd253">D3D12MA::Budget::UsageBytes</a></div><div class="ttdeci">UINT64 UsageBytes</div><div class="ttdoc">Estimated current memory usage of the program.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:485</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_budget_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_budget.html">D3D12MA::Budget</a></div><div class="ttdoc">Statistics of current memory usage and available budget for a specific memory segment group.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:474</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_budget_html_a326515f08d89ee2e31dcfdd5c1e8ac71"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_budget.html#a326515f08d89ee2e31dcfdd5c1e8ac71">D3D12MA::Budget::BudgetBytes</a></div><div class="ttdeci">UINT64 BudgetBytes</div><div class="ttdoc">Estimated amount of memory available to the program.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:497</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_budget_html_a77a8c9e32d6602f95b7d1c285cddd253"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_budget.html#a77a8c9e32d6602f95b7d1c285cddd253">D3D12MA::Budget::UsageBytes</a></div><div class="ttdeci">UINT64 UsageBytes</div><div class="ttdoc">Estimated current memory usage of the program.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:486</div></div> </div><!-- fragment --><p>You can query for more detailed statistics per heap type, memory segment group, and totals, including minimum and maximum allocation size and unused range size, by calling function <a class="el" href="class_d3_d12_m_a_1_1_allocator.html#a99db00df909963573a976c203b107d22" title="Retrieves statistics from current state of the allocator.">D3D12MA::Allocator::CalculateStatistics()</a> and inspecting structure <a class="el" href="struct_d3_d12_m_a_1_1_total_statistics.html" title="General statistics from current state of the allocator - total memory usage across all memory heaps a...">D3D12MA::TotalStatistics</a>. This function is slower though, as it has to traverse all the internal data structures, so it should be used only for debugging purposes.</p> <p>You can query for statistics of a custom pool using function <a class="el" href="class_d3_d12_m_a_1_1_pool.html#aa9d849dc4667314b2a53eddf02f5af91" title="Retrieves basic statistics of the custom pool that are fast to calculate.">D3D12MA::Pool::GetStatistics()</a> or <a class="el" href="class_d3_d12_m_a_1_1_pool.html#ad07999ac5dc8f0c63187afd45d551910" title="Retrieves detailed statistics of the custom pool that are slower to calculate.">D3D12MA::Pool::CalculateStatistics()</a>.</p> <p>You can query for information about a specific allocation using functions of the <a class="el" href="class_d3_d12_m_a_1_1_allocation.html" title="Represents single memory allocation.">D3D12MA::Allocation</a> class, e.g. <code>GetSize()</code>, <code>GetOffset()</code>, <code>GetHeap()</code>.</p>
diff --git a/docs/html/virtual_allocator.html b/docs/html/virtual_allocator.html index f445d16..b3a8ad1 100644 --- a/docs/html/virtual_allocator.html +++ b/docs/html/virtual_allocator.html
@@ -105,9 +105,9 @@ <div class="line"> </div> <div class="line"><a class="code hl_class" href="class_d3_d12_m_a_1_1_virtual_block.html">D3D12MA::VirtualBlock</a> *block;</div> <div class="line">HRESULT hr = CreateVirtualBlock(&blockDesc, &block);</div> -<div class="ttc" id="aclass_d3_d12_m_a_1_1_virtual_block_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_virtual_block.html">D3D12MA::VirtualBlock</a></div><div class="ttdoc">Represents pure allocation algorithm and a data structure with allocations in some memory block,...</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1574</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___b_l_o_c_k___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___b_l_o_c_k___d_e_s_c.html">D3D12MA::VIRTUAL_BLOCK_DESC</a></div><div class="ttdoc">Parameters of created D3D12MA::VirtualBlock object to be passed to CreateVirtualBlock().</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1480</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___b_l_o_c_k___d_e_s_c_html_ac56491679f276a5a9956ed99bc4654e4"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___b_l_o_c_k___d_e_s_c.html#ac56491679f276a5a9956ed99bc4654e4">D3D12MA::VIRTUAL_BLOCK_DESC::Size</a></div><div class="ttdeci">UINT64 Size</div><div class="ttdoc">Total size of the block.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1488</div></div> +<div class="ttc" id="aclass_d3_d12_m_a_1_1_virtual_block_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_virtual_block.html">D3D12MA::VirtualBlock</a></div><div class="ttdoc">Represents pure allocation algorithm and a data structure with allocations in some memory block,...</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1575</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___b_l_o_c_k___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___b_l_o_c_k___d_e_s_c.html">D3D12MA::VIRTUAL_BLOCK_DESC</a></div><div class="ttdoc">Parameters of created D3D12MA::VirtualBlock object to be passed to CreateVirtualBlock().</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1481</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___b_l_o_c_k___d_e_s_c_html_ac56491679f276a5a9956ed99bc4654e4"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___b_l_o_c_k___d_e_s_c.html#ac56491679f276a5a9956ed99bc4654e4">D3D12MA::VIRTUAL_BLOCK_DESC::Size</a></div><div class="ttdeci">UINT64 Size</div><div class="ttdoc">Total size of the block.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1489</div></div> </div><!-- fragment --><h1><a class="anchor" id="virtual_allocator_making_virtual_allocations"></a> Making virtual allocations</h1> <p><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> object contains internal data structure that keeps track of free and occupied regions using the same code as the main D3D12 memory allocator. A single allocation is identified by a lightweight structure <a class="el" href="struct_d3_d12_m_a_1_1_virtual_allocation.html" title="Represents single memory allocation done inside VirtualBlock.">D3D12MA::VirtualAllocation</a>. You will also likely want to know the offset at which the allocation was made in the block.</p> @@ -132,9 +132,9 @@ <div class="line"> <span class="comment">// Allocation failed - no space for it could be found. Handle this error!</span></div> <div class="line">}</div> <div class="ttc" id="aclass_d3_d12_m_a_1_1_virtual_block_html_a9281daf76e888ea1bd5247d5732e8179"><div class="ttname"><a href="class_d3_d12_m_a_1_1_virtual_block.html#a9281daf76e888ea1bd5247d5732e8179">D3D12MA::VirtualBlock::Allocate</a></div><div class="ttdeci">HRESULT Allocate(const VIRTUAL_ALLOCATION_DESC *pDesc, VirtualAllocation *pAllocation, UINT64 *pOffset)</div><div class="ttdoc">Creates new allocation.</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::VIRTUAL_ALLOCATION_DESC</a></div><div class="ttdoc">Parameters of created virtual allocation to be passed to VirtualBlock::Allocate().</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1525</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_a976b649e45abdd0769da0d79acde4bac"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a976b649e45abdd0769da0d79acde4bac">D3D12MA::VIRTUAL_ALLOCATION_DESC::Size</a></div><div class="ttdeci">UINT64 Size</div><div class="ttdoc">Size of the allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1532</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_virtual_allocation_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_virtual_allocation.html">D3D12MA::VirtualAllocation</a></div><div class="ttdoc">Represents single memory allocation done inside VirtualBlock.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:502</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::VIRTUAL_ALLOCATION_DESC</a></div><div class="ttdoc">Parameters of created virtual allocation to be passed to VirtualBlock::Allocate().</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1526</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_a976b649e45abdd0769da0d79acde4bac"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a976b649e45abdd0769da0d79acde4bac">D3D12MA::VIRTUAL_ALLOCATION_DESC::Size</a></div><div class="ttdeci">UINT64 Size</div><div class="ttdoc">Size of the allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1533</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_virtual_allocation_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_virtual_allocation.html">D3D12MA::VirtualAllocation</a></div><div class="ttdoc">Represents single memory allocation done inside VirtualBlock.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:503</div></div> </div><!-- fragment --><h1><a class="anchor" id="virtual_allocator_deallocation"></a> Deallocation</h1> <p>When no longer needed, an allocation can be freed by calling <a class="el" href="class_d3_d12_m_a_1_1_virtual_block.html#aab44e46bd122054c894fc84740f1e8fb" title="Frees the allocation.">D3D12MA::VirtualBlock::FreeAllocation</a>.</p> @@ -171,7 +171,7 @@ <div class="line"><a class="code hl_struct" href="struct_d3_d12_m_a_1_1_virtual_allocation.html">D3D12MA::VirtualAllocation</a> alloc;</div> <div class="line">UINT64 allocOffset;</div> <div class="line">hr = block-><a class="code hl_function" href="class_d3_d12_m_a_1_1_virtual_block.html#a9281daf76e888ea1bd5247d5732e8179">Allocate</a>(&allocDesc, &alloc, &allocOffset);</div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_aaa95e62f2f399339a09dcbb312a42de0"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#aaa95e62f2f399339a09dcbb312a42de0">D3D12MA::VIRTUAL_ALLOCATION_DESC::Alignment</a></div><div class="ttdeci">UINT64 Alignment</div><div class="ttdoc">Required alignment of the allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1537</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_aaa95e62f2f399339a09dcbb312a42de0"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#aaa95e62f2f399339a09dcbb312a42de0">D3D12MA::VIRTUAL_ALLOCATION_DESC::Alignment</a></div><div class="ttdeci">UINT64 Alignment</div><div class="ttdoc">Required alignment of the allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1538</div></div> </div><!-- fragment --><p>Alignments of different allocations made from one block may vary. However, if all alignments and sizes are always multiply of some size e.g. 4 B or <code>sizeof(MyDataStruct)</code>, you can express all sizes, alignments, and offsets in multiples of that size instead of individual bytes. It might be more convenient, but you need to make sure to use this new unit consistently in all the places:</p> <ul> <li><a class="el" href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___b_l_o_c_k___d_e_s_c.html#ac56491679f276a5a9956ed99bc4654e4" title="Total size of the block.">D3D12MA::VIRTUAL_BLOCK_DESC::Size</a></li> @@ -186,9 +186,9 @@ <div class="line">printf(<span class="stringliteral">"My virtual block has %llu bytes used by %u virtual allocations\n"</span>,</div> <div class="line"> stats.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_statistics.html#a53cfe3d241124b5a8e8058871a4b50e8">AllocationBytes</a>, stats.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_statistics.html#aef88ac53531db43a8888ad2be4a06c68">AllocationCount</a>);</div> <div class="ttc" id="aclass_d3_d12_m_a_1_1_virtual_block_html_a0f1dda0e019e218b021f64987a74b110"><div class="ttname"><a href="class_d3_d12_m_a_1_1_virtual_block.html#a0f1dda0e019e218b021f64987a74b110">D3D12MA::VirtualBlock::GetStatistics</a></div><div class="ttdeci">void GetStatistics(Statistics *pStats) const</div><div class="ttdoc">Retrieves basic statistics of the virtual block that are fast to calculate.</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_statistics_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_statistics.html">D3D12MA::Statistics</a></div><div class="ttdoc">Calculated statistics of memory usage e.g. in a specific memory heap type, memory segment group,...</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:380</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_statistics_html_a53cfe3d241124b5a8e8058871a4b50e8"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_statistics.html#a53cfe3d241124b5a8e8058871a4b50e8">D3D12MA::Statistics::AllocationBytes</a></div><div class="ttdeci">UINT64 AllocationBytes</div><div class="ttdoc">Total number of bytes occupied by all D3D12MA::Allocation objects.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:398</div></div> -<div class="ttc" id="astruct_d3_d12_m_a_1_1_statistics_html_aef88ac53531db43a8888ad2be4a06c68"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_statistics.html#aef88ac53531db43a8888ad2be4a06c68">D3D12MA::Statistics::AllocationCount</a></div><div class="ttdeci">UINT AllocationCount</div><div class="ttdoc">Number of D3D12MA::Allocation objects allocated.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:388</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_statistics_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_statistics.html">D3D12MA::Statistics</a></div><div class="ttdoc">Calculated statistics of memory usage e.g. in a specific memory heap type, memory segment group,...</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:381</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_statistics_html_a53cfe3d241124b5a8e8058871a4b50e8"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_statistics.html#a53cfe3d241124b5a8e8058871a4b50e8">D3D12MA::Statistics::AllocationBytes</a></div><div class="ttdeci">UINT64 AllocationBytes</div><div class="ttdoc">Total number of bytes occupied by all D3D12MA::Allocation objects.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:399</div></div> +<div class="ttc" id="astruct_d3_d12_m_a_1_1_statistics_html_aef88ac53531db43a8888ad2be4a06c68"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_statistics.html#aef88ac53531db43a8888ad2be4a06c68">D3D12MA::Statistics::AllocationCount</a></div><div class="ttdeci">UINT AllocationCount</div><div class="ttdoc">Number of D3D12MA::Allocation objects allocated.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:389</div></div> </div><!-- fragment --><p>More detailed statistics can be obtained using function <a class="el" href="class_d3_d12_m_a_1_1_virtual_block.html#a614a82247ce6cf29c38895e16eb971d9" title="Retrieves detailed statistics of the virtual block that are slower to calculate.">D3D12MA::VirtualBlock::CalculateStatistics()</a>, but they are slower to calculate.</p> <p>You can also request a full list of allocations and free regions as a string in JSON format by calling <a class="el" href="class_d3_d12_m_a_1_1_virtual_block.html#a828a27070bfa762cae796d4c8f2ef703" title="Builds and returns statistics as a string in JSON format, including the list of allocations with thei...">D3D12MA::VirtualBlock::BuildStatsString</a>. Returned string must be later freed using <a class="el" href="class_d3_d12_m_a_1_1_virtual_block.html#a6f78ddaa7da194e239089e52093e68a9" title="Frees memory of a string returned from VirtualBlock::BuildStatsString.">D3D12MA::VirtualBlock::FreeStatsString</a>. The format of this string may differ from the one returned by the main D3D12 allocator, but it is similar.</p> <h1><a class="anchor" id="virtual_allocator_additional_considerations"></a>
diff --git a/include/D3D12MemAlloc.h b/include/D3D12MemAlloc.h index a829201..e24864d 100644 --- a/include/D3D12MemAlloc.h +++ b/include/D3D12MemAlloc.h
@@ -33,6 +33,7 @@ \section main_table_of_contents Table of contents +- \subpage faq - \subpage quick_start - [Project setup](@ref quick_start_project_setup) - [Creating resources](@ref quick_start_creating_resources) @@ -1797,6 +1798,221 @@ /// \endcond /** +\page faq Frequenty asked questions + +<b>What is %D3D12MA?</b> + +D3D12 Memory Allocator (%D3D12MA) is a software library for developers who use the DirectX(R) 12 graphics API in their code. +It is written in C++. + +<b>What is the license of %D3D12MA?</b> + +%D3D12MA is licensed under MIT, which means it is open source and free software. + +<b>What is the purpose of %D3D12MA?</b> + +%D3D12MA helps with handling one aspect of DX12 usage, which is GPU memory management - +allocation of `ID3D12Heap` objects and creation of `ID3D12Resource` objects - buffers and textures. + +<b>Do I need to use %D3D12MA?</b> + +You don't need to, but it may be beneficial in many cases. +DX12 is a complex and low-level API, so libraries like this that abstract certain aspects of the API +and bring them to a higher level are useful. +When developing any non-trivial graphics application, you may benefit from using a memory allocator. +Using %D3D12MA can save time compared to implementing your own. + +In DX12 you can create each resource separately with its own implicit memory heap by calling `CreateCommittedResource`, +but this may not be the optimal solution. +For more information, see [Committed versus placed resources](@ref optimal_allocation_committed_vs_placed). + +<b>When should I not use %D3D12MA?</b> + +While %D3D12MA is useful for many applications that use the DX12 API, there are cases +when it may be a better choice not to use it. +For example, if the application is very simple, e.g. serving as a sample or a learning exercise +to help you understand or teach others the basics of DX12, +and it creates only a small number of buffers and textures, then including %D3D12MA may be an overkill. +Developing your own memory allocator may also be a good learning exercise. + +<b>What are the benefits of using %D3D12MA?</b> + +-# %D3D12MA allocates large blocks of `ID3D12Heap` memory and sub-allocates parts of them to create your placed resources. + Allocating a new block of GPU memory may be a time-consuming operation. + Sub-allocating parts of a memory block requires implementing an allocation algorithm, + which is a non-trivial task. + %D3D12MA does that, using an advanced and efficient algorithm that works well in various use cases. +-# %D3D12MA offers a simple API that allows creating placed buffers and textures within one function call + like D3D12MA::Allocator::CreateResource. + +The library is doing much more under the hood. +For example, it keeps buffers separate from textures when needed, respecting `D3D12_RESOURCE_HEAP_TIER`. +It also makes use of the "small texture alignment" automatically, so you don't need to think about it. + +<b>Which version should I pick?</b> + +You can just pick [the latest version from the "master" branch](https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator). +It is kept in a good shape most of the time, compiling and working correctly, +with no compatibility-breaking changes and no unfinished code. + +If you want an even more stable version, you can pick +[the latest official release](https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator/releases). +Current code from the master branch is occasionally tagged as a release, +with [CHANGELOG](https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator/blob/master/CHANGELOG.md) +carefully curated to enumerate all important changes since the previous version. + +The library uses [Semantic Versioning](https://semver.org/), +which means versions that only differ in the patch number are forward and backward compatible +(e.g., only fixing some bugs), while versions that differ in the minor number are backward compatible +(e.g., only adding new functions to the API, but not removing or changing existing ones). + +<b>How to integrate it with my code?</b> + +%D3D12MA is an small library fully implemented in a single pair of CPP + H files. + +You can pull the entire GitHub repository, e.g. using Git submodules. +The repository contains ancillary files like the Cmake script, Doxygen config file, +sample application, test suite, and others. +You can compile it as a library and link with your project. + +However, a simpler way is taking only files "include\D3D12MemAlloc.h", "src\D3D12MemAlloc.cpp" +and including them in your project. +These files contain all you need: a copyright notice, +declarations of the public library interface (API), its internal implementation, +and even the documentation in form of Doxygen-style comments. + +<b>I am not a fan of modern C++. Can I still use it?</b> + +Very likely yes. +We acknowledge that many C++ developers, especially in the games industry, +do not appreciate all the latest features that the language has to offer. + +- %D3D12MA doesn't throw or catch any C++ exceptions. + It reports errors by returning a `HRESULT` value instead, just like DX12. + If you don't use exceptions in your project, your code is not exception-safe, + or even if you disable exception handling in the compiler options, you can still use %D3D12MA. +- %D3D12MA doesn't use C++ run-time type information like `typeid` or `dynamic_cast`, + so if you disable RTTI in the compiler options, you can still use the library. +- %D3D12MA uses only a limited subset of standard C and C++ library. + It doesn't use STL containers like `std::vector`, `map`, or `string`, + either in the public interface nor in the internal implementation. + It implements its own containers instead. +- If you don't use the default heap memory allocator through `malloc/free` or `new/delete` + but implement your own allocator instead, you can pass it to %D3D12MA as + D3D12MA::ALLOCATOR_DESC::pAllocationCallbacks + and the library will use your functions for every dynamic heap allocation made internally. + +<b>Is it available for other programming languages?</b> + +%D3D12MA is a C++ library in similar style as DX12. +Bindings to other programming languages are out of scope of this project, +but they are welcome as external projects. +Some of them are listed in [README.md, "See also" section](https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator/?tab=readme-ov-file#see-also), +including binding to C. +Before using any of them, please check if they are still maintained and updated to use a recent version of %D3D12MA. + +<b>What platforms does it support?</b> + +%D3D12MA relies only on DX12 and some parts of the standard C and C++ library, +so it could support any platform where a C++ compiler and DX12 are available. +However, it is developed and tested only on Microsoft(R) Windows(R). + +<b>Does it only work on AMD GPUs?</b> + +No! While %D3D12MA is published by AMD, it works on any GPU that supports DX12, +whether a discrete PC graphics card or a processor integrated graphics. +It doesn't give AMD GPUs any advantage over any other GPUs. + +<b>What DirectX 12 versions are supported?</b> + +%D3D12MA is updated to support latest versions of DirectX 12, as available through recent retail versions of the +[DirectX 12 Agility SDK](https://devblogs.microsoft.com/directx/directx12agility/). +Support for new features added in the preview version of the Agility SDK is developed on separate branches until they are included in the retail version. + +The library also supports older versions down to the base DX12 shipping with Windows SDK. +Features added by later versions of the Agility SDK are automatically enabled conditionally using +`#ifdef` preprocessor macros depending on the version of the SDK that you compile your project with. + +<b>Does it support other graphics APIs, like Vulkan(R)?</b> + +No, but we offer an equivalent library for Vulkan: +[Vulkan Memory Allocator](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator). +It uses the same core allocation algorithm. +It also shares many features with %D3D12MA, like the support for custom pools and virtual allocator. +However, it is not identical in terms of the features supported. +Its API also looks different, because while the interface of %D3D12MA is similar in style to DX12, +the interface of VMA is similar to Vulkan. + +<b>Is the library lightweight?</b> + +Yes. +%D3D12MA is implemented with high-performance and real-time applications like video games in mind. +The CPU performance overhead of using this library is low. +It uses a high-quality allocation algorithm called Two-Level Segregated Fit (TLSF), +which in most cases can find a free place for a new allocation in few steps. +The library also doesn't perform too many CPU heap allocations. +In many cases, the allocation happens with 0 new CPU heap allocations performed by the library. +Even the creation of a D3D12MA::Allocation object doesn't typically feature an CPU allocation, +because these objects are returned out of a dedicated memory pool. + +That said, %D3D12MA needs some extra memory and extra time +to maintain the metadata about the occupied and free regions of the memory blocks, +and the algorithms and data structures used must be generic enough to work well in most cases. + +<b>Does it have a documentation?</b> + +Yes! %D3D12MA comes with full documentation of all elements of the API (classes, structures, enums), +as well as many generic chapters that provide an introduction, +describe core concepts of the library, good practices, etc. +The entire documentation is written in form of code comments inside "D3D12MemAlloc.h", in Doxygen format. +You can access it in multiple ways: + +- Browsable online: https://gpuopen-librariesandsdks.github.io/D3D12MemoryAllocator/html/ +- Local HTML pages available after you clone the repository and open file "docs\html\index.html". +- You can rebuild the documentation in HTML or some other format from the source code using Doxygen. + Configuration file "Doxyfile" is part of the repository. +- Finally, you can just read the comments preceding declarations of any public classes and functions of the library. + +<b>Is it a mature project?</b> + +Yes! The library is in development since May 2019, has over 300 commits, and multiple contributors. +It is used by many software projects, including some large and popular ones like Qt or Godot Engine, +as well as some AAA games. + +<b>How can I contribute to the project?</b> + +If you have an idea for improvement or a feature request, +you can go to [the library repository](https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator) +and create an Issue ticket, describing your idea. +You can also implement it yourself by forking the repository, making changes to the code, +and creating a Pull request. + +If you want to ask a question, you can also create a ticket the same way. +Before doing this, please make sure you read the relevant part of the DX12 documentation and %D3D12MA documentation, +where you may find the answers to your question. + +If you want to report a suspected bug, you can also create a ticket the same way. +Before doing this, please put some effort into the investigation of whether the bug is really +in the library and not in your code or in the DX12 implementation (the GPU driver) on your platform: + +- Enable D3D Debug Layer and make sure it is free from any errors. +- Make sure `D3D12MA_ASSERT` is defined to an implementation that can report a failure and not ignore it. +- Try making your allocation using pure DX12 functions like `CreateCommittedResource()` rather than %D3D12MA and see if the bug persists. + +<b>I found some compilation warnings. How can we fix them?</b> + +Seeing compiler warnings may be annoying to some developers, +but it is a design decision to not fix all of them. +Due to the nature of the C++ language, certain preprocessor macros can 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. +For more information, see [Features not supported](@ref general_considerations_features_not_supported). + +However, if you observe a warning that is really dangerous, e.g., +about an implicit conversion from a larger to a smaller integer type, please report it and it will be fixed ASAP. + + \page quick_start Quick start \section quick_start_project_setup Project setup and initialization