Fixed wording in the new documentation chapter
diff --git a/docs/html/optimal_allocation.html b/docs/html/optimal_allocation.html index 847ab91..cfeb1c0 100644 --- a/docs/html/optimal_allocation.html +++ b/docs/html/optimal_allocation.html
@@ -98,7 +98,7 @@ <ul> <li>The allocation (resource creation) function call can fail with <code>HRESULT</code> value other than <code>S_OK</code>.</li> <li>The allocation may succeed, but take long time (even a significant fraction of a second).</li> -<li>Some resources are automatically evicted from video memory to system memory, degrading the app performance.</li> +<li>Some resources are automatically demoted from video memory to system memory, degrading the app performance.</li> <li>Even a crash of the entire graphics driver can happen, resulting in the D3D12 "device removal", which is usually catastrophic for the application.</li> </ul> <p>Unfortunately, there is no way to be 100% protected against memory overcommitment. The best approach is to avoid allocating too much memory.</p> @@ -139,9 +139,9 @@ <p>When sub-allocating a buffer, you need to remember to explicitly request proper alignment required for each region. For example, data used as a constant buffer must be aligned to <code>D3D12_CONSTANT_BUFFER_DATA_PLACEMENT_ALIGNMENT</code> = 256 B.</p> <h1><a class="anchor" id="optimal_allocation_residency_priority"></a> Residency priority</h1> -<p>When too much video memory is allocated, one of the things that can happen is the system evicting some heaps to the system memory. Moving data between memory pools or reaching out directly to the system memory through PCI Express bus can have large performance overhead, which can slow down the application, or even make the game unplayable any more. Unfortunately, it is not possible to fully control or prevent this eviction. Best thing to do is avoiding memory over-commitment. For more information, see section "Avoiding running out of memory" above.</p> +<p>When too much video memory is allocated, one of the things that can happen is the system demoting some heaps to the system memory. Moving data between memory pools or reaching out directly to the system memory through PCI Express bus can have large performance overhead, which can slow down the application, or even make the game unplayable any more. Unfortunately, it is not possible to fully control or prevent this demotion. Best thing to do is avoiding memory over-commitment. For more information, see section "Avoiding running out of memory" above.</p> <p>Recent versions of DirectX 12 SDK offer function <code>ID3D12Device1::SetResidencyPriority</code> that sets a hint about the priority of a resource - how important it is to stay resident in the video memory. Setting the priority happens at the level of an entire memory heap. D3D12MA offers an interface to set this priority in form of <a class="el" href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#a2e6074af8c8ff7b957fe8d4b5036a5e6" title="Residency priority to be set for all allocations made in this pool. Optional.">D3D12MA::POOL_DESC::ResidencyPriority</a> parameter. It affects all allocations made out of the custom pool created with it, both placed inside large heaps and created as committed.</p> -<p>It is recommended to create a custom pool for the purpose of using high residency priority of all resources that are critical for the performance, especially those that are written by the GPU, like render-target, depth-stencil textures, UAV textures and buffers. It is also worth creating them as committed, so that each one will have its own implicit heap. This can minimize the chance that an entire large heap is evicted to system memory, degrading performance of all the resources placed in it.</p> +<p>It is recommended to create a custom pool for the purpose of using high residency priority of all resources that are critical for the performance, especially those that are written by the GPU, like render-target, depth-stencil textures, UAV textures and buffers. It is also worth creating them as committed, so that each one will have its own implicit heap. This can minimize the chance that an entire large heap is demoted to system memory, degrading performance of all the resources placed in it.</p> <p>Example:</p> <div class="fragment"><div class="line"><a class="code hl_struct" href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html">D3D12MA::POOL_DESC</a> poolDesc = {};</div> <div class="line">poolDesc.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#a06e06813bcb5206e9f7a8b0564bf1d6a">HeapProperties</a>.Type = D3D12_HEAP_TYPE_DEFAULT;</div> @@ -182,7 +182,7 @@ <div class="ttc" id="astruct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c_html_a06e06813bcb5206e9f7a8b0564bf1d6a"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#a06e06813bcb5206e9f7a8b0564bf1d6a">D3D12MA::POOL_DESC::HeapProperties</a></div><div class="ttdeci">D3D12_HEAP_PROPERTIES HeapProperties</div><div class="ttdoc">The parameters of memory heap where allocations of this pool should be placed.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:866</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:931</div></div> <div class="ttc" id="astruct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c_html_a3795956e4fbfe7c3a23546e02e5d28dc"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html#a3795956e4fbfe7c3a23546e02e5d28dc">D3D12MA::POOL_DESC::HeapFlags</a></div><div class="ttdeci">D3D12_HEAP_FLAGS HeapFlags</div><div class="ttdoc">Heap flags to be used when allocating heaps of this pool.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:877</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 eviction described here happens automatically and only slows down the execution.</p> +</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> <p>Direct3D 12 offers a fixed set of memory heap types:</p>
diff --git a/include/D3D12MemAlloc.h b/include/D3D12MemAlloc.h index 1d00539..cd14773 100644 --- a/include/D3D12MemAlloc.h +++ b/include/D3D12MemAlloc.h
@@ -1956,7 +1956,7 @@ - The allocation (resource creation) function call can fail with `HRESULT` value other than `S_OK`. - The allocation may succeed, but take long time (even a significant fraction of a second). -- Some resources are automatically evicted from video memory to system memory, degrading the app performance. +- Some resources are automatically demoted from video memory to system memory, degrading the app performance. - Even a crash of the entire graphics driver can happen, resulting in the D3D12 "device removal", which is usually catastrophic for the application. @@ -2087,10 +2087,10 @@ \section optimal_allocation_residency_priority Residency priority When too much video memory is allocated, one of the things that can happen is the system -evicting some heaps to the system memory. +demoting some heaps to the system memory. Moving data between memory pools or reaching out directly to the system memory through PCI Express bus can have large performance overhead, which can slow down the application, or even make the game unplayable any more. -Unfortunately, it is not possible to fully control or prevent this eviction. +Unfortunately, it is not possible to fully control or prevent this demotion. Best thing to do is avoiding memory over-commitment. For more information, see section "Avoiding running out of memory" above. @@ -2105,7 +2105,7 @@ of all resources that are critical for the performance, especially those that are written by the GPU, like render-target, depth-stencil textures, UAV textures and buffers. It is also worth creating them as committed, so that each one will have its own implicit heap. -This can minimize the chance that an entire large heap is evicted to system memory, degrading performance +This can minimize the chance that an entire large heap is demoted to system memory, degrading performance of all the resources placed in it. Example: @@ -2145,7 +2145,7 @@ Note this is not the same as explicit eviction controlled using `ID3D12Device::Evict` and `MakeResident` functions. Resources evicted explicitly are illegal to access until they are made resident again, -while the eviction described here happens automatically and only slows down the execution. +while the demotion described here happens automatically and only slows down the execution. \section optimal_allocation_gpu_upload_heap GPU upload heap