AuroraMiddleware/D3D12MemoryAllocator
1
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator.git synced 2024-11-24 21:10:11 +00:00
Code Issues Projects Releases Wiki Activity

Added missing changes

Browse Source
This commit is contained in:
Adam Sawicki 2022-03-30 13:23:01 +02:00
parent 3365a2d0e1
commit 2d7d710944
2 changed files with 8 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/html/quick_start.html
View File

@ -141,8 +141,8 @@ Creating resources</h1>
<h1><a class="anchor" id="quick_start_resource_reference_counting"></a> <h1><a class="anchor" id="quick_start_resource_reference_counting"></a>
Resource reference counting</h1> Resource reference counting</h1>
<p ><code>ID3D12Resource</code> and other interfaces of Direct3D 12 use COM, so they are reference-counted. Objects of this library are reference-counted as well. An object of type <a class="el" href="class_d3_d12_m_a_1_1_allocation.html" title="Represents single memory allocation.">D3D12MA::Allocation</a> remembers the resource (buffer or texture) that was created together with this memory allocation and holds a reference to the <code>ID3D12Resource</code> object. (Note this is a difference to Vulkan Memory Allocator, where a <code>VmaAllocation</code> object has no connection with the buffer or image that was created with it.) Thus, it is important to manage the resource reference counter properly.</p> <p ><code>ID3D12Resource</code> and other interfaces of Direct3D 12 use COM, so they are reference-counted. Objects of this library are reference-counted as well. An object of type <a class="el" href="class_d3_d12_m_a_1_1_allocation.html" title="Represents single memory allocation.">D3D12MA::Allocation</a> remembers the resource (buffer or texture) that was created together with this memory allocation and holds a reference to the <code>ID3D12Resource</code> object. (Note this is a difference to Vulkan Memory Allocator, where a <code>VmaAllocation</code> object has no connection with the buffer or image that was created with it.) Thus, it is important to manage the resource reference counter properly.</p>
<p >The simplest use case is shown in the code snippet above. When only <a class="el" href="class_d3_d12_m_a_1_1_allocation.html" title="Represents single memory allocation.">D3D12MA::Allocation</a> object is obtained from a 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>, it remembers the <code>ID3D12Resource</code> that was created with it and holds a reference to it. The resource can be obtained by calling <code>allocation-&gt;GetResource()</code>, which doesn't increment the resource reference counter. Calling <code>allocation-&gt;Release()</code> will decrease the resource reference counter, which is = 1 in this case, so the resource will be released.</p> <p ><b>The simplest use case</b> is shown in the code snippet above. When only <a class="el" href="class_d3_d12_m_a_1_1_allocation.html" title="Represents single memory allocation.">D3D12MA::Allocation</a> object is obtained from a 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>, it remembers the <code>ID3D12Resource</code> that was created with it and holds a reference to it. The resource can be obtained by calling <code>allocation-&gt;GetResource()</code>, which doesn't increment the resource reference counter. Calling <code>allocation-&gt;Release()</code> will decrease the resource reference counter, which is = 1 in this case, so the resource will be released.</p>
<p >Second option is to retrieve a pointer to the resource along with <a class="el" href="class_d3_d12_m_a_1_1_allocation.html" title="Represents single memory allocation.">D3D12MA::Allocation</a>. Last parameters of the resource creation function can be used for this purpose.</p> <p ><b>Second option</b> is to retrieve a pointer to the resource along with <a class="el" href="class_d3_d12_m_a_1_1_allocation.html" title="Represents single memory allocation.">D3D12MA::Allocation</a>. Last parameters of the resource creation function can be used for this purpose.</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>* allocation;</div> <div class="fragment"><div class="line"><a class="code hl_class" href="class_d3_d12_m_a_1_1_allocation.html">D3D12MA::Allocation</a>* allocation;</div>
<div class="line">ID3D12Resource* resource;</div> <div class="line">ID3D12Resource* resource;</div>
<div class="line">HRESULT hr = allocator-&gt;<a class="code hl_function" href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a">CreateResource</a>(</div> <div class="line">HRESULT hr = allocator-&gt;<a class="code hl_function" href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a">CreateResource</a>(</div>
@ -157,8 +157,8 @@ Resource reference counting</h1>
</div><!-- fragment --><p >In this case, returned pointer <code>resource</code> is equal to <code>allocation-&gt;GetResource()</code>, but the creation function additionally increases resource reference counter for the purpose of returning it from this call (it actually calls <code>QueryInterface</code> internally), so the resource will have the counter = 2. The resource then need to be released along with the allocation, in this particular order, to make sure the resource is destroyed before its memory heap can potentially be freed.</p> </div><!-- fragment --><p >In this case, returned pointer <code>resource</code> is equal to <code>allocation-&gt;GetResource()</code>, but the creation function additionally increases resource reference counter for the purpose of returning it from this call (it actually calls <code>QueryInterface</code> internally), so the resource will have the counter = 2. The resource then need to be released along with the allocation, in this particular order, to make sure the resource is destroyed before its memory heap can potentially be freed.</p>
<div class="fragment"><div class="line">resource-&gt;Release();</div> <div class="fragment"><div class="line">resource-&gt;Release();</div>
<div class="line">allocation-&gt;Release();</div> <div class="line">allocation-&gt;Release();</div>
</div><!-- fragment --><p >More advanced use cases are possible when we consider that an <a class="el" href="class_d3_d12_m_a_1_1_allocation.html" title="Represents single memory allocation.">D3D12MA::Allocation</a> object can just hold a reference to any resource. It can be changed by calling <a class="el" href="class_d3_d12_m_a_1_1_allocation.html#a414a088c22bae0f29b1038f5f9346d14" title="Releases the resource currently pointed by the allocation (if any), sets it to new one,...">D3D12MA::Allocation::SetResource</a>. This function releases the old resource and calls <code>AddRef</code> on the new one.</p> </div><!-- fragment --><p ><b>More advanced use cases</b> are possible when we consider that an <a class="el" href="class_d3_d12_m_a_1_1_allocation.html" title="Represents single memory allocation.">D3D12MA::Allocation</a> object can just hold a reference to any resource. It can be changed by calling <a class="el" href="class_d3_d12_m_a_1_1_allocation.html#a414a088c22bae0f29b1038f5f9346d14" title="Releases the resource currently pointed by the allocation (if any), sets it to new one,...">D3D12MA::Allocation::SetResource</a>. This function releases the old resource and calls <code>AddRef</code> on the new one.</p>
<p >Special care must be taken when performing defragmentation. The new resource created at the destination place should be set as <code>pass.pMoves[i].pDstTmpAllocation-&gt;SetResource(newRes)</code>, but it is moved to the source allocation at end of the defragmentation pass, while the old resource accessible through <code>pass.pMoves[i].pSrcAllocation-&gt;GetResource()</code> is then released. For more information, see documentation chapter <a class="el" href="defragmentation.html">Defragmentation</a>.</p> <p >Special care must be taken when performing <b>defragmentation</b>. The new resource created at the destination place should be set as <code>pass.pMoves[i].pDstTmpAllocation-&gt;SetResource(newRes)</code>, but it is moved to the source allocation at end of the defragmentation pass, while the old resource accessible through <code>pass.pMoves[i].pSrcAllocation-&gt;GetResource()</code> is then released. For more information, see documentation chapter <a class="el" href="defragmentation.html">Defragmentation</a>.</p>
<h1><a class="anchor" id="quick_start_mapping_memory"></a> <h1><a class="anchor" id="quick_start_mapping_memory"></a>
Mapping memory</h1> Mapping memory</h1>
<p >The process of getting regular CPU-side pointer to the memory of a resource in Direct3D is called "mapping". There are rules and restrictions to this process, as described in D3D12 documentation of <code>ID3D12Resource::Map</code> method.</p> <p >The process of getting regular CPU-side pointer to the memory of a resource in Direct3D is called "mapping". There are rules and restrictions to this process, as described in D3D12 documentation of <code>ID3D12Resource::Map</code> method.</p>

8
include/D3D12MemAlloc.h
View File

@ -1644,7 +1644,7 @@ and holds a reference to the `ID3D12Resource` object.
with the buffer or image that was created with it.) with the buffer or image that was created with it.)
Thus, it is important to manage the resource reference counter properly. Thus, it is important to manage the resource reference counter properly.
The simplest use case is shown in the code snippet above. <b>The simplest use case</b> is shown in the code snippet above.
When only D3D12MA::Allocation object is obtained from a function call like D3D12MA::Allocator::CreateResource, When only D3D12MA::Allocation object is obtained from a function call like D3D12MA::Allocator::CreateResource,
it remembers the `ID3D12Resource` that was created with it and holds a reference to it. it remembers the `ID3D12Resource` that was created with it and holds a reference to it.
The resource can be obtained by calling `allocation->GetResource()`, which doesn't increment the resource The resource can be obtained by calling `allocation->GetResource()`, which doesn't increment the resource
@ -1652,7 +1652,7 @@ reference counter.
Calling `allocation->Release()` will decrease the resource reference counter, which is = 1 in this case, Calling `allocation->Release()` will decrease the resource reference counter, which is = 1 in this case,
so the resource will be released. so the resource will be released.
Second option is to retrieve a pointer to the resource along with D3D12MA::Allocation. <b>Second option</b> is to retrieve a pointer to the resource along with D3D12MA::Allocation.
Last parameters of the resource creation function can be used for this purpose. Last parameters of the resource creation function can be used for this purpose.
\code \code
@ -1680,12 +1680,12 @@ resource->Release();
allocation->Release(); allocation->Release();
\endcode \endcode
More advanced use cases are possible when we consider that an D3D12MA::Allocation object can just hold <b>More advanced use cases</b> are possible when we consider that an D3D12MA::Allocation object can just hold
a reference to any resource. a reference to any resource.
It can be changed by calling D3D12MA::Allocation::SetResource. This function It can be changed by calling D3D12MA::Allocation::SetResource. This function
releases the old resource and calls `AddRef` on the new one. releases the old resource and calls `AddRef` on the new one.
Special care must be taken when performing defragmentation. Special care must be taken when performing <b>defragmentation</b>.
The new resource created at the destination place should be set as `pass.pMoves[i].pDstTmpAllocation->SetResource(newRes)`, The new resource created at the destination place should be set as `pass.pMoves[i].pDstTmpAllocation->SetResource(newRes)`,
but it is moved to the source allocation at end of the defragmentation pass, but it is moved to the source allocation at end of the defragmentation pass,
while the old resource accessible through `pass.pMoves[i].pSrcAllocation->GetResource()` is then released. while the old resource accessible through `pass.pMoves[i].pSrcAllocation->GetResource()` is then released.