Added documentation about committed allocations in custom pools
Also a small improvement in TestStandardCustomCommittedPlaced.
diff --git a/src/D3D12MemAlloc.h b/src/D3D12MemAlloc.h
index 301964b..ded69c3 100644
--- a/src/D3D12MemAlloc.h
+++ b/src/D3D12MemAlloc.h
@@ -259,7 +259,7 @@
\endcode
To allocate resources out of a custom pool, only set member D3D12MA::ALLOCATION_DESC::CustomPool.
-Other members of this structure are then ignored. Example:
+Example:
\code
ALLOCATION_DESC allocDesc = {};
@@ -271,8 +271,6 @@
D3D12_RESOURCE_STATE_GENERIC_READ, NULL, &alloc, IID_NULL, NULL);
\endcode
-Currently all allocations from custom pools are created as Placed, never as Committed.
-
All allocations must be released before releasing the pool.
The pool must be released before relasing the allocator.
@@ -287,8 +285,10 @@
more opportunities for internal optimizations, custom pools may be useful in following cases:
- To keep some resources separate from others in memory.
+- To keep track of memory usage of just a specific group of resources. Statistics can be queried using
+ D3D12MA::Pool::CalculateStats.
- To use specific size of a memory block (`ID3D12Heap`). To set it, use member D3D12MA::POOL_DESC::BlockSize.
- When set to 0, the library uses automatically determined, increasing block sizes.
+ When set to 0, the library uses automatically determined, variable block sizes.
- To reserve some minimum amount of memory allocated. To use it, set member D3D12MA::POOL_DESC::MinBlockCount.
- To limit maximum amount of memory allocated. To use it, set member D3D12MA::POOL_DESC::MaxBlockCount.
- To use extended parameters of the D3D12 memory allocation. While resources created from default pools
@@ -297,6 +297,27 @@
(D3D12MA::POOL_DESC::HeapFlags), which is useful e.g. for cross-adapter sharing or UMA
(see also D3D12MA::Allocator::IsUMA).
+New versions of this library support creating **committed allocations in custom pools**.
+It is supported only when D3D12MA::POOL_DESC::BlockSize = 0.
+To use this feature, set D3D12MA::ALLOCATION_DESC::CustomPool to the pointer to your custom pool and
+D3D12MA::ALLOCATION_DESC::Flags to D3D12MA::ALLOCATION_FLAG_COMMITTED. Example:
+
+\code
+ALLOCATION_DESC allocDesc = {};
+allocDesc.CustomPool = pool;
+allocDesc.Flags = ALLOCATION_FLAG_COMMITTED;
+
+D3D12_RESOURCE_DESC resDesc = ...
+Allocation* alloc;
+ID3D12Resource* res;
+hr = allocator->CreateResource(&allocDesc, &resDesc,
+ D3D12_RESOURCE_STATE_GENERIC_READ, NULL, &alloc, IID_PPV_ARGS(&res));
+\endcode
+
+This feature may seem unnecessary, but creating committed allocations from custom pools may be useful
+in some cases, e.g. to have separate memory usage statistics for some group of resources or to use
+extended allocation parameters, like custom `D3D12_HEAP_PROPERTIES`, which are available only in custom pools.
+
\page resource_aliasing Resource aliasing (overlap)
diff --git a/src/Tests.cpp b/src/Tests.cpp
index 8374feb..2d91a1b 100644
--- a/src/Tests.cpp
+++ b/src/Tests.cpp
@@ -856,6 +856,10 @@
bool expectSuccess = !neverAllocate; // NEVER_ALLOCATE should always fail with COMMITTED.
CHECK_BOOL(expectSuccess == SUCCEEDED(hr));
+ if(SUCCEEDED(hr) && useCommitted)
+ {
+ CHECK_BOOL(allocPtr->GetHeap() == NULL); // Committed allocation has implicit heap.
+ }
}
}
