From 2d7d710944bb91d724fc503a691980c90a05618c Mon Sep 17 00:00:00 2001 From: Adam Sawicki Date: Wed, 30 Mar 2022 13:23:01 +0200 Subject: [PATCH] Added missing changes --- docs/html/quick_start.html | 8 ++++---- include/D3D12MemAlloc.h | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/html/quick_start.html b/docs/html/quick_start.html index 33b1897..acbc0d9 100644 --- a/docs/html/quick_start.html +++ b/docs/html/quick_start.html @@ -141,8 +141,8 @@ Creating resources

Resource reference counting

ID3D12Resource 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 D3D12MA::Allocation remembers the resource (buffer or texture) that was created together with this memory allocation and holds a reference to the ID3D12Resource object. (Note this is a difference to Vulkan Memory Allocator, where a VmaAllocation 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.

-

The simplest use case is shown in the code snippet above. 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. The resource can be obtained by calling allocation->GetResource(), which doesn't increment the resource reference counter. Calling allocation->Release() will decrease the resource reference counter, which is = 1 in this case, so the resource will be released.

-

Second option 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.

+

The simplest use case is shown in the code snippet above. 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. The resource can be obtained by calling allocation->GetResource(), which doesn't increment the resource reference counter. Calling allocation->Release() will decrease the resource reference counter, which is = 1 in this case, so the resource will be released.

+

Second option 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.

D3D12MA::Allocation* allocation;
ID3D12Resource* resource;
HRESULT hr = allocator->CreateResource(
@@ -157,8 +157,8 @@ Resource reference counting

In this case, returned pointer resource is equal to allocation->GetResource(), but the creation function additionally increases resource reference counter for the purpose of returning it from this call (it actually calls QueryInterface 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.

resource->Release();
allocation->Release();
-

More advanced use cases are possible when we consider that an D3D12MA::Allocation object can just hold a reference to any resource. It can be changed by calling D3D12MA::Allocation::SetResource. This function releases the old resource and calls AddRef on the new one.

-

Special care must be taken when performing defragmentation. 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, while the old resource accessible through pass.pMoves[i].pSrcAllocation->GetResource() is then released. For more information, see documentation chapter Defragmentation.

+

More advanced use cases are possible when we consider that an D3D12MA::Allocation object can just hold a reference to any resource. It can be changed by calling D3D12MA::Allocation::SetResource. This function releases the old resource and calls AddRef on the new one.

+

Special care must be taken when performing defragmentation. 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, while the old resource accessible through pass.pMoves[i].pSrcAllocation->GetResource() is then released. For more information, see documentation chapter Defragmentation.

Mapping memory

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 ID3D12Resource::Map method.

diff --git a/include/D3D12MemAlloc.h b/include/D3D12MemAlloc.h index 8800c5d..582e79c 100644 --- a/include/D3D12MemAlloc.h +++ b/include/D3D12MemAlloc.h @@ -1644,7 +1644,7 @@ and holds a reference to the `ID3D12Resource` object. with the buffer or image that was created with it.) Thus, it is important to manage the resource reference counter properly. -The simplest use case is shown in the code snippet above. +The simplest use case is shown in the code snippet above. 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. 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, so the resource will be released. -Second option is to retrieve a pointer to the resource along with D3D12MA::Allocation. +Second option 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. \code @@ -1680,12 +1680,12 @@ resource->Release(); allocation->Release(); \endcode -More advanced use cases are possible when we consider that an D3D12MA::Allocation object can just hold +More advanced use cases are possible when we consider that an D3D12MA::Allocation object can just hold a reference to any resource. It can be changed by calling D3D12MA::Allocation::SetResource. This function 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 defragmentation. 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, while the old resource accessible through `pass.pMoves[i].pSrcAllocation->GetResource()` is then released.