commit	2764c221dcfc4db90f51702644cc8988eb8f78de	[log] [tgz]
author	Adam Sawicki <Adam.Sawicki@amd.com>	Mon Sep 02 13:23:41 2019 +0200
committer	Adam Sawicki <Adam.Sawicki@amd.com>	Mon Sep 02 13:23:41 2019 +0200
tree	dc81559192e604783a4a8312114c5a2b6e9d1444
parent	164d7f2afd835ab5f0211c3504c3362a47fbbb3f [diff]

tree: dc81559192e604783a4a8312114c5a2b6e9d1444

README.md

D3D12 Memory Allocator

Easy to integrate memory allocation library for Direct3D 12.

License: MIT. See LICENSE.txt

Changelog: See CHANGELOG.md

Product page: D3D12 Memory Allocator on GPUOpen

Build status:

Windows:

Problem

Memory allocation and resource (buffer and texture) creation in new, explicit graphics APIs (Vulkan® and Direct3D 12) is difficult comparing to older graphics APIs like Direct3D 11 or OpenGL® because it is recommended to allocate bigger blocks of memory and assign parts of them to resources. Vulkan Memory Allocator is a library that implements this functionality for Vulkan. It is available online since 2017 and it is successfully used in many software projects, including some AAA game studios. This is an equivalent library for D3D12.

Features

This library can help developers to manage memory allocations and resource creation by offering function Allocator::CreateResource similar to the standard ID3D12Device::CreateCommittedResource. It internally:

Allocates and keeps track of bigger memory heaps, used and unused ranges inside them, finds best matching unused ranges to create new resources there as placed resources.
Automatically respects alignment requirements for created resources.
Automatically handles resource heap tier - whether it's D3D12_RESOURCE_HEAP_TIER_1 that requires to keep certain classes of resources separate or D3D12_RESOURCE_HEAP_TIER_2 that allows to keep them all together.

Additional features:

Well-documented - description of all classes and functions provided, along with chapters that contain general description and example code.
Thread-safety: Library is designed to be used in multithreaded code.
Configuration: Fill optional members of ALLOCATOR_DESC structure to provide custom CPU memory allocator and other parameters.
Customization: Predefine appropriate macros to provide your own implementation of external facilities used by the library, like assert, mutex, and atomic.

Prerequisites

Self-contained C++ library in single pair of H + CPP files. No external dependencies other than standard C, C++ library and Windows SDK. STL containers, C++ exceptions, and RTTI are not used.
Object-oriented interface in a convention similar to D3D12.
Error handling implemented by returning HRESULT error codes - same way as in D3D12.
Interface documented using Doxygen-style comments.

Example

Basic usage of this library is very simple. Advanced features are optional. After you created global Allocator object, a complete code needed to create a texture may look like this:

D3D12_RESOURCE_DESC resourceDesc = {};
resourceDesc.Dimension = D3D12_RESOURCE_DIMENSION_TEXTURE2D;
resourceDesc.Alignment = 0;
resourceDesc.Width = 1024;
resourceDesc.Height = 1024;
resourceDesc.DepthOrArraySize = 1;
resourceDesc.MipLevels = 1;
resourceDesc.Format = DXGI_FORMAT_R8G8B8A8_UNORM;
resourceDesc.SampleDesc.Count = 1;
resourceDesc.SampleDesc.Quality = 0;
resourceDesc.Layout = D3D12_TEXTURE_LAYOUT_UNKNOWN;
resourceDesc.Flags = D3D12_RESOURCE_FLAG_NONE;

D3D12MA::ALLOCATION_DESC allocationDesc = {};
allocDesc.HeapType = D3D12_HEAP_TYPE_DEFAULT;

D3D12Resource* resource;
D3D12MA::Allocation* allocation;
HRESULT hr = allocator->CreateResource(
    &allocationDesc,
    &resourceDesc,
    D3D12_RESOURCE_STATE_COPY_DEST,
    NULL,
    &allocation,
    IID_PPV_ARGS(&resource));

With this one function call:

ID3D12Heap memory block is allocated if needed.
An unused region of the memory block assigned.
ID3D12Resource is created as placed resource, bound to this region.

Allocation is an object that represents memory assigned to this texture. It can be queried for parameters like offset and size.

Documentation

Documentation is provided together with the library in form of Doxygen-style comments inside the code, in file “src/D3D12MemAlloc.h”. They can be read directly or turned into HTML and other convenient to read formats. Unfortunately we can't provide pregenerated version browseable online. You can generate it on your own by following these steps:

Install Doxygen.
Open command line and enter “src” directory.
Type command: doxygen
Open following file in a web browser: “docs/html/index.html”.

Copyright notice

This software package uses third party software:

Parts of the code of Vulkan Memory Allocator by AMD, license: MIT
Parts of the code of DirectX-Graphics-Samples by Microsoft, license: MIT
Premake 5 binary, license: BSD

For more information see NOTICES.txt.

Software using this library

Place for the link to your project :)