| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> |
| <meta http-equiv="X-UA-Compatible" content="IE=11"/> |
| <meta name="generator" content="Doxygen 1.14.0"/> |
| <meta name="viewport" content="width=device-width, initial-scale=1"/> |
| <title>D3D12 Memory Allocator: Quick start</title> |
| <link href="tabs.css" rel="stylesheet" type="text/css"/> |
| <script type="text/javascript" src="jquery.js"></script> |
| <script type="text/javascript" src="dynsections.js"></script> |
| <script type="text/javascript" src="clipboard.js"></script> |
| <script type="text/javascript" src="cookie.js"></script> |
| <link href="search/search.css" rel="stylesheet" type="text/css"/> |
| <script type="text/javascript" src="search/searchdata.js"></script> |
| <script type="text/javascript" src="search/search.js"></script> |
| <link href="doxygen.css" rel="stylesheet" type="text/css" /> |
| </head> |
| <body> |
| <div id="top"><!-- do not remove this div, it is closed by doxygen! --> |
| <div id="titlearea"> |
| <table cellspacing="0" cellpadding="0"> |
| <tbody> |
| <tr id="projectrow"> |
| <td id="projectalign"> |
| <div id="projectname">D3D12 Memory Allocator |
| </div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <!-- end header part --> |
| <!-- Generated by Doxygen 1.14.0 --> |
| <script type="text/javascript"> |
| var searchBox = new SearchBox("searchBox", "search/",'.html'); |
| </script> |
| <script type="text/javascript"> |
| $(function() { codefold.init(); }); |
| </script> |
| <script type="text/javascript" src="menudata.js"></script> |
| <script type="text/javascript" src="menu.js"></script> |
| <script type="text/javascript"> |
| $(function() { |
| initMenu('',true,false,'search.php','Search',false); |
| $(function() { init_search(); }); |
| }); |
| </script> |
| <div id="main-nav"></div> |
| <!-- window showing the filter options --> |
| <div id="MSearchSelectWindow" |
| onmouseover="return searchBox.OnSearchSelectShow()" |
| onmouseout="return searchBox.OnSearchSelectHide()" |
| onkeydown="return searchBox.OnSearchSelectKey(event)"> |
| </div> |
| |
| <!-- iframe showing the search results (closed by default) --> |
| <div id="MSearchResultsWindow"> |
| <div id="MSearchResults"> |
| <div class="SRPage"> |
| <div id="SRIndex"> |
| <div id="SRResults"></div> |
| <div class="SRStatus" id="Loading">Loading...</div> |
| <div class="SRStatus" id="Searching">Searching...</div> |
| <div class="SRStatus" id="NoMatches">No Matches</div> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <div id="nav-path" class="navpath"> |
| <ul> |
| <li class="navelem"><a href="index.html">D3D12 Memory Allocator</a></li> </ul> |
| </div> |
| </div><!-- top --> |
| <div id="doc-content"> |
| <div><div class="header"> |
| <div class="headertitle"><div class="title">Quick start </div></div> |
| </div><!--header--> |
| <div class="contents"> |
| <div class="textblock"><h1 class="doxsection"><a class="anchor" id="quick_start_project_setup"></a> |
| Project setup and initialization</h1> |
| <p>This is a small, standalone C++ library. It consists of 2 files: "D3D12MemAlloc.h" header file with public interface and "D3D12MemAlloc.cpp" with internal implementation. The only external dependencies are WinAPI, Direct3D 12, and parts of C/C++ standard library (but STL containers, exceptions, or RTTI are not used).</p> |
| <p>The library is developed and tested using Microsoft Visual Studio 2022, but it should work with other compilers as well. It is designed for 64-bit code.</p> |
| <p>To use the library in your project:</p> |
| <p>(1.) Copy files <span class="tt">D3D12MemAlloc.cpp</span>, <span class="tt">D3D12MemAlloc.h</span> to your project.</p> |
| <p>(2.) Make <span class="tt">D3D12MemAlloc.cpp</span> compiling as part of the project, as C++ code.</p> |
| <p>(3.) Include library header in each CPP file that needs to use the library.</p> |
| <div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="_d3_d12_mem_alloc_8h.html">D3D12MemAlloc.h</a>"</span></div> |
| <div class="ttc" id="a_d3_d12_mem_alloc_8h_html"><div class="ttname"><a href="_d3_d12_mem_alloc_8h.html">D3D12MemAlloc.h</a></div></div> |
| </div><!-- fragment --><p>(4.) Right after you created <span class="tt">ID3D12Device</span>, fill <a class="el" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_o_r___d_e_s_c.html" title="Parameters of created Allocator object. To be used with CreateAllocator().">D3D12MA::ALLOCATOR_DESC</a> structure and call function <a class="el" href="namespace_d3_d12_m_a.html#ab7a1cd1683986d75ce1488b0920f4cb0" title="Creates new main D3D12MA::Allocator object and returns it through ppAllocator.">D3D12MA::CreateAllocator</a> to create the main <a class="el" href="class_d3_d12_m_a_1_1_allocator.html" title="Represents main object of this library initialized for particular ID3D12Device.">D3D12MA::Allocator</a> object.</p> |
| <p>Please note that all symbols of the library are declared inside <a class="el" href="namespace_d3_d12_m_a.html">D3D12MA</a> namespace.</p> |
| <div class="fragment"><div class="line">IDXGIAdapter* adapter = ...</div> |
| <div class="line">ID3D12Device* device = ...</div> |
| <div class="line"> </div> |
| <div class="line">D3D12MA::ALLOCATOR_DESC allocatorDesc = {};</div> |
| <div class="line">allocatorDesc.pDevice = device;</div> |
| <div class="line">allocatorDesc.pAdapter = adapter;</div> |
| <div class="line">allocatorDesc.Flags = <a class="code hl_define" href="_d3_d12_mem_alloc_8h.html#accfbeae642feeacf353ce695e91a5e73">D3D12MA_RECOMMENDED_ALLOCATOR_FLAGS</a>;</div> |
| <div class="line"> </div> |
| <div class="line"><a class="code hl_class" href="class_d3_d12_m_a_1_1_allocator.html">D3D12MA::Allocator</a>* allocator;</div> |
| <div class="line">HRESULT hr = <a class="code hl_function" href="namespace_d3_d12_m_a.html#ab7a1cd1683986d75ce1488b0920f4cb0">D3D12MA::CreateAllocator</a>(&allocatorDesc, &allocator);</div> |
| <div class="line"><span class="comment">// Check hr...</span></div> |
| <div class="ttc" id="a_d3_d12_mem_alloc_8h_html_accfbeae642feeacf353ce695e91a5e73"><div class="ttname"><a href="_d3_d12_mem_alloc_8h.html#accfbeae642feeacf353ce695e91a5e73">D3D12MA_RECOMMENDED_ALLOCATOR_FLAGS</a></div><div class="ttdeci">#define D3D12MA_RECOMMENDED_ALLOCATOR_FLAGS</div><div class="ttdoc">Set of flags recommended for use in D3D12MA::ALLOCATOR_DESC::Flags for optimal performance.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:128</div></div> |
| <div class="ttc" id="aclass_d3_d12_m_a_1_1_allocator_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocator.html">D3D12MA::Allocator</a></div><div class="ttdoc">Represents main object of this library initialized for particular ID3D12Device.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1174</div></div> |
| <div class="ttc" id="anamespace_d3_d12_m_a_html_ab7a1cd1683986d75ce1488b0920f4cb0"><div class="ttname"><a href="namespace_d3_d12_m_a.html#ab7a1cd1683986d75ce1488b0920f4cb0">D3D12MA::CreateAllocator</a></div><div class="ttdeci">D3D12MA_API HRESULT CreateAllocator(const ALLOCATOR_DESC *pDesc, Allocator **ppAllocator)</div><div class="ttdoc">Creates new main D3D12MA::Allocator object and returns it through ppAllocator.</div></div> |
| </div><!-- fragment --><p>(5.) Right before destroying the D3D12 device, destroy the allocator object.</p> |
| <div class="fragment"><div class="line">allocator->Release();</div> |
| </div><!-- fragment --><p>Objects of this library must be destroyed by calling <span class="tt">Release</span> method. They are somewhat compatible with COM: they implement <span class="tt">IUnknown</span> interface with its virtual methods: <span class="tt">AddRef</span>, <span class="tt">Release</span>, <span class="tt">QueryInterface</span>, and they are reference-counted internally. You can use smart pointers designed for COM with objects of this library - e.g. <span class="tt">CComPtr</span> or <span class="tt">Microsoft::WRL::ComPtr</span>. The reference counter is thread-safe. <span class="tt">QueryInterface</span> method supports only <span class="tt">IUnknown</span>, as classes of this library don't define their own GUIDs.</p> |
| <h1 class="doxsection"><a class="anchor" id="quick_start_creating_resources"></a> |
| Creating resources</h1> |
| <p>To use the library for creating resources (textures and buffers), call method <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> in the place where you would previously call <span class="tt">ID3D12Device::CreateCommittedResource</span>.</p> |
| <p>The function has similar syntax, but it expects structure <a class="el" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html" title="Parameters of created D3D12MA::Allocation object. To be used with Allocator::CreateResource.">D3D12MA::ALLOCATION_DESC</a> to be passed along with <span class="tt">D3D12_RESOURCE_DESC</span> and other parameters for created resource. This structure describes parameters of the desired memory allocation, including choice of <span class="tt">D3D12_HEAP_TYPE</span>.</p> |
| <p>The function returns a new object of type <a class="el" href="class_d3_d12_m_a_1_1_allocation.html" title="Represents single memory allocation.">D3D12MA::Allocation</a>. It represents allocated memory and can be queried for size, offset, <span class="tt">ID3D12Heap</span>. It also holds a reference to the <span class="tt">ID3D12Resource</span>, which can be accessed by calling <a class="el" href="class_d3_d12_m_a_1_1_allocation.html#ad00308118252f82d8f803c623c67bf18" title="Returns D3D12 resource associated with this object.">D3D12MA::Allocation::GetResource()</a>.</p> |
| <div class="fragment"><div class="line">D3D12_RESOURCE_DESC resourceDesc = {};</div> |
| <div class="line">resourceDesc.Dimension = D3D12_RESOURCE_DIMENSION_TEXTURE2D;</div> |
| <div class="line">resourceDesc.Alignment = 0;</div> |
| <div class="line">resourceDesc.Width = 1024;</div> |
| <div class="line">resourceDesc.Height = 1024;</div> |
| <div class="line">resourceDesc.DepthOrArraySize = 1;</div> |
| <div class="line">resourceDesc.MipLevels = 1;</div> |
| <div class="line">resourceDesc.Format = DXGI_FORMAT_R8G8B8A8_UNORM;</div> |
| <div class="line">resourceDesc.SampleDesc.Count = 1;</div> |
| <div class="line">resourceDesc.SampleDesc.Quality = 0;</div> |
| <div class="line">resourceDesc.Layout = D3D12_TEXTURE_LAYOUT_UNKNOWN;</div> |
| <div class="line">resourceDesc.Flags = D3D12_RESOURCE_FLAG_NONE;</div> |
| <div class="line"> </div> |
| <div class="line"><a class="code hl_struct" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::ALLOCATION_DESC</a> allocationDesc = {};</div> |
| <div class="line">allocationDesc.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#aa46b3c0456e5a23edef3328607ebf4d7">HeapType</a> = D3D12_HEAP_TYPE_DEFAULT;</div> |
| <div class="line"> </div> |
| <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">HRESULT hr = allocator-><a class="code hl_function" href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a">CreateResource</a>(</div> |
| <div class="line"> &allocationDesc,</div> |
| <div class="line"> &resourceDesc,</div> |
| <div class="line"> D3D12_RESOURCE_STATE_COPY_DEST,</div> |
| <div class="line"> NULL,</div> |
| <div class="line"> &allocation,</div> |
| <div class="line"> IID_NULL, NULL);</div> |
| <div class="line"><span class="comment">// Check hr...</span></div> |
| <div class="line"> </div> |
| <div class="line">ID3D12Resource* res = allocation-><a class="code hl_function" href="class_d3_d12_m_a_1_1_allocation.html#ad00308118252f82d8f803c623c67bf18">GetResource</a>();</div> |
| <div class="line"><span class="comment">// Use res...</span></div> |
| <div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html">D3D12MA::Allocation</a></div><div class="ttdoc">Represents single memory allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:523</div></div> |
| <div class="ttc" id="aclass_d3_d12_m_a_1_1_allocation_html_ad00308118252f82d8f803c623c67bf18"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocation.html#ad00308118252f82d8f803c623c67bf18">D3D12MA::Allocation::GetResource</a></div><div class="ttdeci">ID3D12Resource * GetResource() const</div><div class="ttdoc">Returns D3D12 resource associated with this object.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:552</div></div> |
| <div class="ttc" id="aclass_d3_d12_m_a_1_1_allocator_html_aa37d6b9fe8ea0864f7a35b9d68e8345a"><div class="ttname"><a href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a">D3D12MA::Allocator::CreateResource</a></div><div class="ttdeci">HRESULT CreateResource(const ALLOCATION_DESC *pAllocDesc, const D3D12_RESOURCE_DESC *pResourceDesc, D3D12_RESOURCE_STATES InitialResourceState, const D3D12_CLEAR_VALUE *pOptimizedClearValue, Allocation **ppAllocation, REFIID riidResource, void **ppvResource)</div><div class="ttdoc">Allocates memory and creates a D3D12 resource (buffer or texture). This is the main allocation functi...</div></div> |
| <div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::ALLOCATION_DESC</a></div><div class="ttdoc">Parameters of created D3D12MA::Allocation object. To be used with Allocator::CreateResource.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:338</div></div> |
| <div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_aa46b3c0456e5a23edef3328607ebf4d7"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#aa46b3c0456e5a23edef3328607ebf4d7">D3D12MA::ALLOCATION_DESC::HeapType</a></div><div class="ttdeci">D3D12_HEAP_TYPE HeapType</div><div class="ttdoc">The type of memory heap where the new allocation should be placed.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:347</div></div> |
| </div><!-- fragment --><p>You need to release the allocation object when no longer needed. This will also release the D3D12 resource.</p> |
| <div class="fragment"><div class="line">allocation->Release();</div> |
| </div><!-- fragment --><p>The advantage of using the allocator instead of creating committed resource, and the main purpose of this library, is that it can decide to allocate bigger memory heap internally using <span class="tt">ID3D12Device::CreateHeap</span> and place multiple resources in it, at different offsets, using <span class="tt">ID3D12Device::CreatePlacedResource</span>. The library manages its own collection of allocated memory blocks (heaps) and remembers which parts of them are occupied and which parts are free to be used for new resources.</p> |
| <p>It is important to remember that resources created as placed don't have their memory initialized to zeros, but may contain garbage data, so they need to be fully initialized before usage, e.g. using Clear (<span class="tt">ClearRenderTargetView</span>), Discard (<span class="tt">DiscardResource</span>), or Copy (<span class="tt">CopyResource</span>).</p> |
| <p>The library also automatically handles resource heap tier. When <span class="tt">D3D12_FEATURE_DATA_D3D12_OPTIONS::ResourceHeapTier == D3D12_RESOURCE_HEAP_TIER_1</span>, resources of 3 types: buffers, textures that are render targets or depth-stencil, and other textures must be kept in separate heaps. When <span class="tt">D3D12_RESOURCE_HEAP_TIER_2</span>, they can be kept together. By using this library, you don't need to handle this manually.</p> |
| <h1 class="doxsection"><a class="anchor" id="quick_start_resource_reference_counting"></a> |
| Resource reference counting</h1> |
| <p><span class="tt">ID3D12Resource</span> 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 <span class="tt">ID3D12Resource</span> object. (Note this is a difference to Vulkan Memory Allocator, where a <span class="tt">VmaAllocation</span> 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><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 <span class="tt">ID3D12Resource</span> that was created with it and holds a reference to it. The resource can be obtained by calling <span class="tt">allocation->GetResource()</span>, which doesn't increment the resource reference counter. Calling <span class="tt">allocation->Release()</span> will decrease the resource reference counter, which is 1 in this case, so the resource will be released.</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="line">ID3D12Resource* resource;</div> |
| <div class="line">HRESULT hr = allocator-><a class="code hl_function" href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a">CreateResource</a>(</div> |
| <div class="line"> &allocationDesc,</div> |
| <div class="line"> &resourceDesc,</div> |
| <div class="line"> D3D12_RESOURCE_STATE_COPY_DEST,</div> |
| <div class="line"> NULL,</div> |
| <div class="line"> &allocation,</div> |
| <div class="line"> IID_PPV_ARGS(&resource));</div> |
| <div class="line"> </div> |
| <div class="line"><span class="comment">// Use resource...</span></div> |
| </div><!-- fragment --><p>In this case, returned pointer <span class="tt">resource</span> is equal to <span class="tt">allocation->GetResource()</span>, but the creation function additionally increases resource reference counter for the purpose of returning it from this call (it actually calls <span class="tt">QueryInterface</span> 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->Release();</div> |
| <div class="line">allocation->Release();</div> |
| </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 not null), sets it to new one,...">D3D12MA::Allocation::SetResource</a>. This function releases the old resource and calls <span class="tt">AddRef</span> on the new one.</p> |
| <p>Special care must be taken when performing <b>defragmentation</b>. The new resource created at the destination place should be set as <span class="tt">pass.pMoves[i].pDstTmpAllocation->SetResource(newRes)</span>, but it is moved to the source allocation at end of the defragmentation pass, while the old resource accessible through <span class="tt">pass.pMoves[i].pSrcAllocation->GetResource()</span> is then released. For more information, see documentation chapter <a class="el" href="defragmentation.html">Defragmentation</a>.</p> |
| <h1 class="doxsection"><a class="anchor" id="quick_start_mapping_memory"></a> |
| 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 <span class="tt">ID3D12Resource::Map</span> method.</p> |
| <p>Mapping happens on the level of particular resources, not entire memory heaps, and so it is out of scope of this library. Just as the documentation of the <span class="tt">Map</span> function says:</p> |
| <ul> |
| <li>Returned pointer refers to data of particular subresource, not entire memory heap.</li> |
| <li>You can map same resource multiple times. It is ref-counted internally.</li> |
| <li>Mapping is thread-safe.</li> |
| <li>Unmapping is not required before resource destruction.</li> |
| <li>Unmapping may not be required before using written data - some heap types on some platforms support resources persistently mapped.</li> |
| </ul> |
| <p>When using this library, you can map and use your resources normally without considering whether they are created as committed resources or placed resources in one large heap.</p> |
| <p>Example for buffer created and filled in <span class="tt">UPLOAD</span> heap type:</p> |
| <div class="fragment"><div class="line"><span class="keyword">const</span> UINT64 bufSize = 65536;</div> |
| <div class="line"><span class="keyword">const</span> <span class="keywordtype">float</span>* bufData = ...;</div> |
| <div class="line"> </div> |
| <div class="line">D3D12_RESOURCE_DESC resourceDesc = {};</div> |
| <div class="line">resourceDesc.Dimension = D3D12_RESOURCE_DIMENSION_BUFFER;</div> |
| <div class="line">resourceDesc.Alignment = 0;</div> |
| <div class="line">resourceDesc.Width = bufSize;</div> |
| <div class="line">resourceDesc.Height = 1;</div> |
| <div class="line">resourceDesc.DepthOrArraySize = 1;</div> |
| <div class="line">resourceDesc.MipLevels = 1;</div> |
| <div class="line">resourceDesc.Format = DXGI_FORMAT_UNKNOWN;</div> |
| <div class="line">resourceDesc.SampleDesc.Count = 1;</div> |
| <div class="line">resourceDesc.SampleDesc.Quality = 0;</div> |
| <div class="line">resourceDesc.Layout = D3D12_TEXTURE_LAYOUT_ROW_MAJOR;</div> |
| <div class="line">resourceDesc.Flags = D3D12_RESOURCE_FLAG_NONE;</div> |
| <div class="line"> </div> |
| <div class="line"><a class="code hl_struct" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::ALLOCATION_DESC</a> allocationDesc = {};</div> |
| <div class="line">allocationDesc.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#aa46b3c0456e5a23edef3328607ebf4d7">HeapType</a> = D3D12_HEAP_TYPE_UPLOAD;</div> |
| <div class="line"> </div> |
| <div class="line">D3D12Resource* resource;</div> |
| <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">HRESULT hr = allocator-><a class="code hl_function" href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a">CreateResource</a>(</div> |
| <div class="line"> &allocationDesc,</div> |
| <div class="line"> &resourceDesc,</div> |
| <div class="line"> D3D12_RESOURCE_STATE_GENERIC_READ,</div> |
| <div class="line"> NULL,</div> |
| <div class="line"> &allocation,</div> |
| <div class="line"> IID_PPV_ARGS(&resource));</div> |
| <div class="line"> </div> |
| <div class="line">D3D12_RANGE emptyRange = {0, 0};</div> |
| <div class="line"><span class="keywordtype">void</span>* mappedPtr;</div> |
| <div class="line">hr = resource->Map(0, &emptyRange, &mappedPtr);</div> |
| <div class="line"> </div> |
| <div class="line">memcpy(mappedPtr, bufData, bufSize);</div> |
| <div class="line"> </div> |
| <div class="line">resource->Unmap(0, NULL);</div> |
| </div><!-- fragment --><h1 class="doxsection"><a class="anchor" id="quick_start_helper_structures"></a> |
| Helper structures</h1> |
| <p>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 <span class="tt">*_DESC</span> structures by using some basic C++ features (constructors, static methods, default parameters). They inherit from these structures, so they support implicit casting to them. For example, structure <span class="tt">CD3DX12_RESOURCE_DESC</span> can be used to conveniently fill in structure <span class="tt">D3D12_RESOURCE_DESC</span>.</p> |
| <p>Similarly, this library provides a set of helper structures that aid in initialization of some of the <span class="tt">*_DESC</span> structures defined in the library. These are:</p> |
| <ul> |
| <li><a class="el" href="struct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html" title="Helper structure that helps with complete and conscise initialization of the D3D12MA::ALLOCATION_DESC...">D3D12MA::CALLOCATION_DESC</a>, which inherits from <a class="el" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html" title="Parameters of created D3D12MA::Allocation object. To be used with Allocator::CreateResource.">D3D12MA::ALLOCATION_DESC</a>.</li> |
| <li><a class="el" href="struct_d3_d12_m_a_1_1_c_p_o_o_l___d_e_s_c.html" title="Helper structure that helps with complete and conscise initialization of the D3D12MA::POOL_DESC struc...">D3D12MA::CPOOL_DESC</a>, which inherits from <a class="el" href="struct_d3_d12_m_a_1_1_p_o_o_l___d_e_s_c.html" title="Parameters of created D3D12MA::Pool object. To be used with D3D12MA::Allocator::CreatePool.">D3D12MA::POOL_DESC</a>.</li> |
| <li><a class="el" href="struct_d3_d12_m_a_1_1_c_v_i_r_t_u_a_l___b_l_o_c_k___d_e_s_c.html" title="Helper structure that helps with complete and conscise initialization of the D3D12MA::VIRTUAL_BLOCK_D...">D3D12MA::CVIRTUAL_BLOCK_DESC</a>, which inherits from <a class="el" href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___b_l_o_c_k___d_e_s_c.html" title="Parameters of created D3D12MA::VirtualBlock object to be passed to CreateVirtualBlock().">D3D12MA::VIRTUAL_BLOCK_DESC</a>.</li> |
| <li><a class="el" href="struct_d3_d12_m_a_1_1_c_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c.html" title="Helper structure that helps with complete and conscise initialization of the D3D12MA::VIRTUAL_ALLOCAT...">D3D12MA::CVIRTUAL_ALLOCATION_DESC</a>, which inherits from <a class="el" href="struct_d3_d12_m_a_1_1_v_i_r_t_u_a_l___a_l_l_o_c_a_t_i_o_n___d_e_s_c.html" title="Parameters of created virtual allocation to be passed to VirtualBlock::Allocate().">D3D12MA::VIRTUAL_ALLOCATION_DESC</a>.</li> |
| </ul> |
| <p>For example, when you want to create a buffer in the <span class="tt">UPLAOD</span> heap using minimal allocation time, you can use base structures:</p> |
| <div class="fragment"><div class="line"><a class="code hl_struct" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::ALLOCATION_DESC</a> allocDesc;</div> |
| <div class="line">allocDesc.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a92dec49b788a334fc91c55340dfbace6">Flags</a> = <a class="code hl_enumvalue" href="namespace_d3_d12_m_a.html#abbad31a7e0b3d09d77f3fb704b77645eaa3ded8847563c24b4522af0586dbd2cb">D3D12MA::ALLOCATION_FLAG_STRATEGY_MIN_TIME</a>;</div> |
| <div class="line">allocDesc.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#aa46b3c0456e5a23edef3328607ebf4d7">HeapType</a> = D3D12_HEAP_TYPE_UPLOAD;</div> |
| <div class="line">allocDesc.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a97878838f976b2d1e6b1a76881035690">ExtraHeapFlags</a> = D3D12_HEAP_FLAG_NONE;</div> |
| <div class="line">allocDesc.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#ab06b85f3cf3254f855b29264477e3934">CustomPool</a> = NULL;</div> |
| <div class="line">allocDesc.<a class="code hl_variable" href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#ac638dd987f1326e2fdab91892d994d35">pPrivateData</a> = NULL;</div> |
| <div class="line"> </div> |
| <div class="line">D3D12_RESOURCE_DESC resDesc;</div> |
| <div class="line">resDesc.Dimension = D3D12_RESOURCE_DIMENSION_BUFFER;</div> |
| <div class="line">resDesc.Alignment = 0;</div> |
| <div class="line">resDesc.Width = myBufSize;</div> |
| <div class="line">resDesc.Height = 1;</div> |
| <div class="line">resDesc.DepthOrArraySize = 1;</div> |
| <div class="line">resDesc.MipLevels = 1;</div> |
| <div class="line">resDesc.Format = DXGI_FORMAT_UNKNOWN;</div> |
| <div class="line">resDesc.SampleDesc.Count = 1;</div> |
| <div class="line">resDesc.SampleDesc.Quality = 0;</div> |
| <div class="line">resDesc.Layout = D3D12_TEXTURE_LAYOUT_ROW_MAJOR;</div> |
| <div class="line">resDesc.Flags = D3D12_RESOURCE_FLAG_NONE;</div> |
| <div class="line"> </div> |
| <div class="line"><a class="code hl_class" href="class_d3_d12_m_a_1_1_allocation.html">D3D12MA::Allocation</a>* alloc;</div> |
| <div class="line">ID3D12Resource* res;</div> |
| <div class="line">HRESULT hr = allocator-><a class="code hl_function" href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a">CreateResource</a>(&allocDesc, &resDesc,</div> |
| <div class="line"> D3D12_RESOURCE_STATE_COMMON, NULL, &alloc, IID_PPV_ARGS(&res));</div> |
| <div class="line"><span class="comment">// Check hr...</span></div> |
| <div class="ttc" id="anamespace_d3_d12_m_a_html_abbad31a7e0b3d09d77f3fb704b77645eaa3ded8847563c24b4522af0586dbd2cb"><div class="ttname"><a href="namespace_d3_d12_m_a.html#abbad31a7e0b3d09d77f3fb704b77645eaa3ded8847563c24b4522af0586dbd2cb">D3D12MA::ALLOCATION_FLAG_STRATEGY_MIN_TIME</a></div><div class="ttdeci">@ ALLOCATION_FLAG_STRATEGY_MIN_TIME</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:316</div></div> |
| <div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_a92dec49b788a334fc91c55340dfbace6"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a92dec49b788a334fc91c55340dfbace6">D3D12MA::ALLOCATION_DESC::Flags</a></div><div class="ttdeci">ALLOCATION_FLAGS Flags</div><div class="ttdoc">Flags for the allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:340</div></div> |
| <div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_a97878838f976b2d1e6b1a76881035690"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#a97878838f976b2d1e6b1a76881035690">D3D12MA::ALLOCATION_DESC::ExtraHeapFlags</a></div><div class="ttdeci">D3D12_HEAP_FLAGS ExtraHeapFlags</div><div class="ttdoc">Additional heap flags to be used when allocating memory.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:363</div></div> |
| <div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_ab06b85f3cf3254f855b29264477e3934"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#ab06b85f3cf3254f855b29264477e3934">D3D12MA::ALLOCATION_DESC::CustomPool</a></div><div class="ttdeci">Pool * CustomPool</div><div class="ttdoc">Custom pool to place the new resource in. Optional.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:369</div></div> |
| <div class="ttc" id="astruct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html_ac638dd987f1326e2fdab91892d994d35"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html#ac638dd987f1326e2fdab91892d994d35">D3D12MA::ALLOCATION_DESC::pPrivateData</a></div><div class="ttdeci">void * pPrivateData</div><div class="ttdoc">Custom general-purpose pointer that will be stored in D3D12MA::Allocation.</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:371</div></div> |
| </div><!-- fragment --><p>Or you can use helper structs from both D3X12 library and this library to make the code shorter:</p> |
| <div class="fragment"><div class="line"><a class="code hl_struct" href="struct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::CALLOCATION_DESC</a> allocDesc = <a class="code hl_struct" href="struct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::CALLOCATION_DESC</a>{</div> |
| <div class="line"> D3D12_HEAP_TYPE_UPLOAD,</div> |
| <div class="line"> <a class="code hl_enumvalue" href="namespace_d3_d12_m_a.html#abbad31a7e0b3d09d77f3fb704b77645eaa3ded8847563c24b4522af0586dbd2cb">D3D12MA::ALLOCATION_FLAG_STRATEGY_MIN_TIME</a> };</div> |
| <div class="line"> </div> |
| <div class="line">CD3DX12_RESOURCE_DESC resDesc = CD3DX12_RESOURCE_DESC::Buffer(myBufSize);</div> |
| <div class="line"> </div> |
| <div class="line"><a class="code hl_class" href="class_d3_d12_m_a_1_1_allocation.html">D3D12MA::Allocation</a>* alloc;</div> |
| <div class="line">ID3D12Resource* res;</div> |
| <div class="line">HRESULT hr = allocator-><a class="code hl_function" href="class_d3_d12_m_a_1_1_allocator.html#aa37d6b9fe8ea0864f7a35b9d68e8345a">CreateResource</a>(&allocDesc, &resDesc,</div> |
| <div class="line"> D3D12_RESOURCE_STATE_COMMON, NULL, &alloc, IID_PPV_ARGS(&res));</div> |
| <div class="line"><span class="comment">// Check hr...</span></div> |
| <div class="ttc" id="astruct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c_html"><div class="ttname"><a href="struct_d3_d12_m_a_1_1_c_a_l_l_o_c_a_t_i_o_n___d_e_s_c.html">D3D12MA::CALLOCATION_DESC</a></div><div class="ttdoc">Helper structure that helps with complete and conscise initialization of the D3D12MA::ALLOCATION_DESC...</div><div class="ttdef"><b>Definition</b> D3D12MemAlloc.h:1676</div></div> |
| </div><!-- fragment --> </div></div><!-- contents --> |
| </div><!-- PageDoc --> |
| <!-- start footer part --> |
| <hr class="footer"/><address class="footer"><small> |
| Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.14.0 |
| </small></address> |
| </div><!-- doc-content --> |
| </body> |
| </html> |
