| This repository contains D3D12 Memory Allocator (D3D12MA) - a software library implemented in C++, intended for developers who use Direct3D 12 on Windows. It supports any D3D12-compatible GPU. It is distributed under the MIT license. | |
| # Requirements | |
| Using D3D12MA requires: | |
| - C++ compiler with at least C++14 support | |
| - DirectX 12 headers available - either headers supplied by the Windows SDK or the DirectX 12 Agility SDK (both Retail and Preview versions are supported) | |
| - When using Agility SDK, set `D3D12MA_AGILITY_SDK_DIRECTORY` Cmake variable to appropriate directory. | |
| - When using preview Agility SDK, also set `D3D12MA_AGILITY_SDK_PREVIEW` Cmake option to `ON`. | |
| # Scope | |
| Using this library is not required to use D3D12, but it is helpful and recommended, as it simplifies some aspects of the D3D12 API: allocating heaps, creating buffers and textures. The library: | |
| - Allocates larger heaps, tracks occupied and free ranges, and selects suitable ranges for placed resources. | |
| - Automatically respects size and alignment requirements for created resources. | |
| - Automatically handles the resource heap tier - whether it's `D3D12_RESOURCE_HEAP_TIER_1` that requires certain resource classes to be kept separate or `D3D12_RESOURCE_HEAP_TIER_2` that allows keeping them all together. | |
| # How to use | |
| D3D12MA is distributed in source form. The library is implemented entirely in two files: the header `include/D3D12MemAlloc.h` and the implementation `src/D3D12MemAlloc.cpp`. Other C++ source/header files you can see in this repository are sample, support, and test code, so you don't need to use them when developing software using this library. | |
| # Library API | |
| Full documentation of the library API is provided in Doxygen-style comments in `include/D3D12MemAlloc.h`. | |
| The API is similar in style to D3D12. Errors are reported using `HRESULT` error codes returned from most functions `SUCCEEDED(hr)` / `FAILED(hr)` macros are recommended for checking them. C++ exceptions are not used. Library symbols are defined in the `D3D12MA` namespace. | |
| The API is object-oriented. Classes derive from `IUnknown` and implement its interface, including thread-safe reference counting, so they follow a style similar to COM interfaces. They can be used with smart pointers designed for COM interfaces, like `Microsoft::WRL::ComPtr`. However, they are not true COM interfaces, they don't have GUIDs. | |
| The most important classes are: | |
| - `D3D12MA::Allocator` - represents the main allocator object. Creating only one per `ID3D12Device` and keeping it alive throughout the application's use of D3D12 is recommended. | |
| - The allocator must outlive allocations, pools, and other objects that depend on it. | |
| - `D3D12MA::Allocation` - represents a specific region of allocated D3D12 heap memory and (optionally) a D3D12 resource. It may hold a reference to: | |
| - `ID3D12Heap` memory block or a subregion of such block (it is managed by D3D12MA internally) | |
| - `ID3D12Resource` created as a placed resource in a heap memory block or created as a committed resource (which then has its own implicit heap) | |
| - An allocation is, thus, either using a shared heap, owning a dedicated heap, or representing a committed resource with an implicit heap. | |
| A typical workflow for using objects of this library is: | |
| 1. Initialize a description structure such as `D3D12MA::ALLOCATION_DESC`. | |
| 2. Call an object creation method like `D3D12MA::Allocator::CreateResource`. Receive a pointer to the created object. Check the result for success or error. | |
| 3. Use the object by calling its methods. Keep it alive as long as needed, carefully considering its lifetime and usage on both CPU and GPU. | |
| 4. When no longer needed, call its `Release` method, which decrements reference counter, destroying the object when the counter reaches 0. | |
| Example showing the creation and usage of a buffer intended for data uploading: | |
| ```cpp | |
| D3D12MA::Allocator* allocator = ... | |
| // 1. Initialize description structures. | |
| const UINT64 bufSize = 65536; | |
| D3D12_RESOURCE_DESC resourceDesc = {}; | |
| resourceDesc.Dimension = D3D12_RESOURCE_DIMENSION_BUFFER; | |
| resourceDesc.Alignment = 0; | |
| resourceDesc.Width = bufSize; | |
| resourceDesc.Height = 1; | |
| resourceDesc.DepthOrArraySize = 1; | |
| resourceDesc.MipLevels = 1; | |
| resourceDesc.Format = DXGI_FORMAT_UNKNOWN; | |
| resourceDesc.SampleDesc.Count = 1; | |
| resourceDesc.SampleDesc.Quality = 0; | |
| resourceDesc.Layout = D3D12_TEXTURE_LAYOUT_ROW_MAJOR; | |
| resourceDesc.Flags = D3D12_RESOURCE_FLAG_NONE; | |
| D3D12MA::ALLOCATION_DESC allocationDesc = {}; | |
| allocationDesc.HeapType = D3D12_HEAP_TYPE_UPLOAD; | |
| // 2. Create the allocation object, along with its resource. | |
| D3D12MA::Allocation* allocation = NULL; | |
| ID3D12Resource* resource = NULL; | |
| HRESULT hr = allocator->CreateResource(&allocationDesc, &resourceDesc, | |
| D3D12_RESOURCE_STATE_COMMON, NULL, &allocation, IID_PPV_ARGS(&resource)); | |
| // Check hr... | |
| // 3. Use the resource, for example: | |
| const float* bufData = ...; | |
| D3D12_RANGE emptyRange = {0, 0}; | |
| void* mappedPtr = NULL; | |
| hr = resource->Map(0, &emptyRange, &mappedPtr); | |
| // Check hr... | |
| memcpy(mappedPtr, bufData, bufSize); | |
| resource->Unmap(0, NULL); | |
| // ... | |
| // 4. When no longer needed or used, destroy the objects. | |
| resource->Release(); | |
| allocation->Release(); | |
| ``` | |
| DirectX 12 Agility SDK offers a library of helpers in files `build\native\include\d3dx12\*.h`. They include structures that help with complete and concise initialization of the core D3D12 `*_DESC` structures. For example, the structure `CD3DX12_RESOURCE_DESC` can be used to conveniently fill in structure `D3D12_RESOURCE_DESC`. Similarly, this library provides a set of helper structures that aid in initialization of some of the `*_DESC` structures defined in the library. Their usage is recommended, along with the usage of some smart pointers for both D3D12 and D3D12MA objects. For example: | |
| ```cpp | |
| D3D12MA::CALLOCATION_DESC allocationDesc{D3D12_HEAP_TYPE_UPLOAD}; | |
| CD3DX12_RESOURCE_DESC resourceDesc = CD3DX12_RESOURCE_DESC::Buffer(bufSize); | |
| ComPtr<D3D12MA::Allocation> allocation; | |
| ComPtr<ID3D12Resource> resource; | |
| HRESULT hr = allocator->CreateResource(&allocationDesc, &resourceDesc, | |
| D3D12_RESOURCE_STATE_COMMON, NULL, &allocation, IID_PPV_ARGS(&resource)); | |
| ``` | |
| # Object references, ownership, and lifetime | |
| Care must be taken to correctly manage object lifetime and references, to avoid memory leaks or use-after-free bugs. | |
| - If an `Allocation` has been created together with a resource (using methods like `Allocator::CreateResource`), the allocation object holds a reference to the resource and releases it when the allocation is destroyed. | |
| - An allocation object without a resource may be created with `Allocator::AllocateMemory`, but it is not recommended for typical usage. | |
| - If an `Allocation` has been created with its own dedicated `ID3D12Heap` object, the allocation object holds a reference to the heap and releases it when the allocation is destroyed. | |
| - Such an allocation may be created, for example, by using `Allocator::AllocateMemory` with `ALLOCATION_FLAG_COMMITTED`, but it is not recommended for typical usage. | |
| - If an `Allocation` object points to a subregion of a larger `ID3D12Heap`, that heap is managed internally by D3D12MA and may be used for other non-overlapping allocations. | |
| - If you receive a pointer to a resource created together with the allocation using methods such as `Allocator::CreateResource` (by passing a non-null `ppvResource` argument), the reference count of the resource is incremented. | |
| - To release the objects properly, you then need to call `Release` on both the allocation and the resource objects. | |
| - The `ID3D12Resource` and `ID3D12Heap` associated with an allocation can be queried later by calling methods `Allocation::GetResource`, `Allocation::GetHeap`, respectively. | |
| - `GetHeap` returns null for committed resources with implicit heaps. | |
| - `GetResource` can return null for raw allocations with no resource attached. | |
| - Calling these methods does not increment the returned object's reference count. Callers must not release that borrowed reference unless they separately acquired ownership, for example through `AddRef` or a smart-pointer copy. | |
| Resources and allocations shouldn't be released when they may still be in use on the GPU device, so CPU-side C++ code may need to wait for the GPU to finish (e.g. using a D3D12 fence) before releasing such objects. |