D3D12MA::Allocation Class Reference

Represents single memory allocation. More...

#include <D3D12MemAlloc.h>

Inherits IUnknownImpl.

Public Member Functions
UINT64	GetOffset () const
	Returns offset in bytes from the start of memory heap. More...
UINT64	GetAlignment () const
	Returns alignment that resource was created with.
UINT64	GetSize () const
	Returns size in bytes of the allocation. More...
ID3D12Resource *	GetResource () const
	Returns D3D12 resource associated with this object. More...
void	SetResource (ID3D12Resource *pResource)
	Releases the resource currently pointed by the allocation (if any), sets it to new one, incrementing its reference counter (if not null).
ID3D12Heap *	GetHeap () const
	Returns memory heap that the resource is created in. More...
void	SetPrivateData (void *pPrivateData)
	Changes custom pointer for an allocation to a new value.
void *	GetPrivateData () const
	Get custom pointer associated with the allocation.
void	SetName (LPCWSTR Name)
	Associates a name with the allocation object. This name is for use in debug diagnostics and tools. More...
LPCWSTR	GetName () const
	Returns the name associated with the allocation object. More...
BOOL	WasZeroInitialized () const
	Returns TRUE if the memory of the allocation was filled with zeros when the allocation was created. More...

Protected Member Functions
void	ReleaseThis () override

Friends
class	AllocatorPimpl
class	BlockVector
class	CommittedAllocationList
class	JsonWriter
class	BlockMetadata_Linear
class	DefragmentationContextPimpl
struct	CommittedAllocationListItemTraits
template<typename T >
class	PoolAllocator
template<typename T >
void	D3D12MA_DELETE (const ALLOCATION_CALLBACKS &, T *)

Detailed Description

Represents single memory allocation.

It may be either implicit memory heap dedicated to a single resource or a specific region of a bigger heap plus unique offset.

To create such object, fill structure D3D12MA::ALLOCATION_DESC and call function Allocator::CreateResource.

The object remembers size and some other information. To retrieve this information, use methods of this class.

The object also remembers ID3D12Resource and "owns" a reference to it, so it calls Release() on the resource when destroyed.

Member Function Documentation

GetHeap()

ID3D12Heap* D3D12MA::Allocation::GetHeap

(

)

const

Returns memory heap that the resource is created in.

If the Allocation represents committed resource with implicit heap, returns NULL.

GetName()

LPCWSTR D3D12MA::Allocation::GetName ( ) const

inline

Returns the name associated with the allocation object.

Returned string points to an internal copy.

If no name was associated with the allocation, returns null.

GetOffset()

UINT64 D3D12MA::Allocation::GetOffset

(

)

const

Returns offset in bytes from the start of memory heap.

You usually don't need to use this offset. If you create a buffer or a texture together with the allocation using function D3D12MA::Allocator::CreateResource, functions that operate on that resource refer to the beginning of the resource, not entire memory heap.

If the Allocation represents committed resource with implicit heap, returns 0.

GetResource()

ID3D12Resource* D3D12MA::Allocation::GetResource ( ) const

inline

Returns D3D12 resource associated with this object.

Calling this method doesn't increment resource's reference counter.

GetSize()

UINT64 D3D12MA::Allocation::GetSize ( ) const

inline

Returns size in bytes of the allocation.

• If you created a buffer or a texture together with the allocation using function D3D12MA::Allocator::CreateResource, this is the size of the resource returned by ID3D12Device::GetResourceAllocationInfo.
• For allocations made out of bigger memory blocks, this also is the size of the memory region assigned exclusively to this allocation.
• For resources created as committed, this value may not be accurate. DirectX implementation may optimize memory usage internally so that you may even observe regions of ID3D12Resource::GetGPUVirtualAddress() + Allocation::GetSize() to overlap in memory and still work correctly.

SetName()

void D3D12MA::Allocation::SetName

(

LPCWSTR

Name

)

Associates a name with the allocation object. This name is for use in debug diagnostics and tools.

Internal copy of the string is made, so the memory pointed by the argument can be changed of freed immediately after this call.

Name can be null.

WasZeroInitialized()

BOOL D3D12MA::Allocation::WasZeroInitialized ( ) const

inline

Returns TRUE if the memory of the allocation was filled with zeros when the allocation was created.

Returns TRUE only if the allocator is sure that the entire memory where the allocation was created was filled with zeros at the moment the allocation was made.

Returns FALSE if the memory could potentially contain garbage data. If it's a render-target or depth-stencil texture, it then needs proper initialization with ClearRenderTargetView, ClearDepthStencilView, DiscardResource, or a copy operation, as described on page "ID3D12Device::CreatePlacedResource method - Notes on the required resource initialization" in Microsoft documentation. Please note that rendering a fullscreen triangle or quad to the texture as a render target is not a proper way of initialization!

See also articles:

• "Coming to DirectX 12: More control over memory allocation" on DirectX Developer Blog
• "Initializing DX12 Textures After Allocation and Aliasing".

---

The documentation for this class was generated from the following file:

• Gems/Atom/RHI/DX12/External/AMD_D3D12MemoryAllocator/v2.0.1/dx12ma/D3D12MemAlloc.h