Heaps

Heaps API provides heap object allocation and resource placement in this heap objects. Resources may be aliased if memory ranges of multiple resources are overlapping, in this case alive/to-be-used resources must be marked active via activate_*() methods and dead/non-used resources must be marked inactive via deactivate_*() methods

Use ResourceDescription to query required heap group, size and aligment with get_resource_allocation_properties() Having this data, allocate fitting heap with create_resource_heap() and place resource there at will with place_*_in_resource_heap()

For ResourceHeapGroup description see ResourceHeapGroupProperties

Callable d3d:: methods

ResourceAllocationProperties get_resource_allocation_properties(const ResourceDescription &desc)

Retrieves the resource allocation properties for a given resource description.

Parameters:

desc – The resource description. Resource descriptions that would describe a resource with one or more of its dimensions being 0 will result in an error.

Returns:

The resource allocation properties. On error sizeInBytes field of the returned value will be 0.

ResourceHeap *create_resource_heap(ResourceHeapGroup *heap_group, size_t size, ResourceHeapCreateFlags flags)

Creates a resource heap with the specified size and flags.

Parameters:

  • heap_group – The resource heap group.

  • size – The size of the resource heap in bytes. A value of 0 is invalid and results in undefined behavior.

  • flags – The flags for creating the resource heap.

Returns:

A pointer to the created resource heap. May be nullptr on error, like out of memory or invalid inputs.

void destroy_resource_heap(ResourceHeap *heap)

Destroys a resource heap.

Parameters:

heap – The resource heap to destroy.

Sbuffer *place_buffer_in_resource_heap(ResourceHeap *heap, const ResourceDescription &desc, size_t offset, const ResourceAllocationProperties &alloc_info, const char *name)

Places a buffer in a resource heap at the specified offset.

The heap group of heap has to match the heap group of alloc_info that was returned by get_resource_allocation_properties.

Parameters:

  • heap – The resource heap.

  • desc – The resource description.

  • offset – The offset in the resource heap in bytes.

  • alloc_info – The resource allocation properties.

  • name – The name of the buffer.

Returns:

A pointer to the placed buffer. May be nullptr on error, like invalid inputs.

BaseTexture *place_texture_in_resource_heap(ResourceHeap *heap, const ResourceDescription &desc, size_t offset, const ResourceAllocationProperties &alloc_info, const char *name)

Places a texture in a resource heap at the specified offset.

The heap group of heap has to match the heap group of alloc_info that was returned by get_resource_allocation_properties.

Parameters:

  • heap – The resource heap.

  • desc – The resource description.

  • offset – The offset in the resource heap in bytes.

  • alloc_info – The resource allocation properties.

  • name – The name of the texture.

Returns:

A pointer to the placed texture. May be nullptr on error, like invalid inputs.

ResourceHeapGroupProperties get_resource_heap_group_properties(ResourceHeapGroup *heap_group)

Retrieves the resource heap group properties for a given resource heap group.

Note

Different groups may return identical values, this does not mean that the heap group is identical or can be substituted for each another. Heap groups represent purpose bound memory that may have device specific properties, that limit the use of a heap group for certain resource types.

Parameters:

heap_group – The resource heap group.

Returns:

The resource heap group properties.

void activate_buffer(Sbuffer *buf, ResourceActivationAction action, const ResourceClearValue &value = {}, GpuPipeline gpu_pipeline = GpuPipeline::GRAPHICS)

Activates a buffer with the specified action and optional clear value.

Only activated placed buffer could be safely used. Using the buffer before being activated results in undefined behavior.

Warning

gpu_pipeline parameter doesn’t work currently.

Parameters:

  • buf – The buffer to activate.

  • action – The activation action.

  • value – The clear value (optional).

  • gpu_pipeline – The GPU pipeline to use (optional).

void activate_texture(BaseTexture *tex, ResourceActivationAction action, const ResourceClearValue &value = {}, GpuPipeline gpu_pipeline = GpuPipeline::GRAPHICS)

Activates a texture with the specified action and optional clear value.

Only activated placed textures could be safely used. Using the texture before being activated results in undefined behavior.

Warning

gpu_pipeline parameter doesn’t work currently.

Parameters:

  • tex – The texture to activate.

  • action – The activation action.

  • value – The clear value (optional).

  • gpu_pipeline – The GPU pipeline to use (optional).

void deactivate_buffer(Sbuffer *buf, GpuPipeline gpu_pipeline = GpuPipeline::GRAPHICS)

Deactivates a buffer with the specified GPU pipeline.

The method call is necessary to have a correct state of the resources on a heap. Using the buffer after being deactivated results in undefined behavior.

Warning

gpu_pipeline parameter doesn’t work currently.

Parameters:

  • buf – The placed buffer to deactivate.

  • gpu_pipeline – The GPU pipeline to use (optional).

void deactivate_texture(BaseTexture *tex, GpuPipeline gpu_pipeline = GpuPipeline::GRAPHICS)

Deactivates a texture with the specified GPU pipeline.

The method call is necessary to have a correct state of the resources on a heap. Using the texture after being deactivated results in undefined behavior.

Warning

gpu_pipeline parameter doesn’t work currently.

Parameters:

  • tex – The placed texture to deactivate.

  • gpu_pipeline – The GPU pipeline to use (optional).

Defines

FIELD_MATCHES(field)

Typedefs

using ResourceHeapCreateFlags = uint32_t

Definition of ResourceHeapCreateFlags type. See ResourceHeapCreateFlag for valid values.

Enums

enum class ResourceActivationAction : unsigned

Enumeration representing different resource activation actions.

Values:

enumerator REWRITE_AS_COPY_DESTINATION

Rewrite the resource as a copy destination.

enumerator REWRITE_AS_UAV

Rewrite the resource as an unordered access view.

enumerator REWRITE_AS_RTV_DSV

Rewrite the resource as a render target or depth-stencil view.

enumerator CLEAR_F_AS_UAV

Clear the resource as a floating-point unordered access view.

enumerator CLEAR_I_AS_UAV

Clear the resource as an integer unordered access view.

enumerator CLEAR_AS_RTV_DSV

Clear the resource as a render target or depth-stencil view.

enumerator DISCARD_AS_UAV

Discard the resource as an unordered access view.

enumerator DISCARD_AS_RTV_DSV

Discard the resource as a render target or depth-stencil view.

enum ResourceHeapCreateFlag

A set of flags that steer the behavior of the driver during creation of resource heaps.

Values:

enumerator RHCF_NONE

By default the drivers are allowed to use already reserved memory of internal heaps, to source the needed memory. Drivers are also allowed to allocate larger memory heaps and use the excess memory for their internal resource and memory management.

enumerator RHCF_REQUIRES_DEDICATED_HEAP

Resource heaps created with this flag, will use their own dedicate memory heap to supply the memory for resources. When this flag is not used to create a resource heap, the driver is allowed to source the need memory from existing driver managed heaps, or create a larger underlying memory heap and use the excess memory for its internal resource and memory management. This flag should be used only when really necessary, as it restricts the drivers option to use already reserved memory for this heap and increase the memory pressure on the system.

Note

That on certain system configurations, for example GDK with predefined memory heap allocations, this flag may be ignored by the driver, as it would otherwise not be able to satisfy heap creation request.

struct BasicResourceDescription

Basic resource description that contains common fields for all GPU resource types.

Subclassed by BasicTextureResourceDescription, BufferResourceDescription

Public Members

uint32_t cFlags

The resource creation flags.

ResourceActivationAction activation

The resource activation action.

ResourceClearValue clearValue

The clear value.

struct BufferResourceDescription : public BasicResourceDescription

Buffer resource description that contains fields specific to buffer resources.

Public Members

uint32_t elementSizeInBytes

The size of a single element in bytes.

uint32_t elementCount

The number of elements in the buffer.

uint32_t viewFormat

The view format of the buffer.

struct BasicTextureResourceDescription : public BasicResourceDescription

Basic texture resource description that contains fields common to all texture resources.

Subclassed by CubeTextureResourceDescription, TextureResourceDescription

Public Members

uint32_t mipLevels

The number of mip levels.

struct TextureResourceDescription : public BasicTextureResourceDescription

Texture resource description that contains fields specific to 2D textures.

Subclassed by ArrayTextureResourceDescription, VolTextureResourceDescription

Public Members

uint32_t width

The width of the texture.

uint32_t height

The height of the texture.

struct VolTextureResourceDescription : public TextureResourceDescription

Volume texture resource description that contains fields specific to volume textures.

Public Members

uint32_t depth

The depth of the volume texture.

struct ArrayTextureResourceDescription : public TextureResourceDescription

Array texture resource description that contains fields specific to array textures.

Public Members

uint32_t arrayLayers

The number of array layers.

struct CubeTextureResourceDescription : public BasicTextureResourceDescription

Cube texture resource description that contains fields specific to cube textures.

Subclassed by ArrayCubeTextureResourceDescription

Public Members

uint32_t extent

The extent of the cube texture.

struct ArrayCubeTextureResourceDescription : public CubeTextureResourceDescription

Array cube texture resource description that contains fields specific to array cube textures.

Public Members

uint32_t cubes

The number of cubes in the array cube texture.

struct ResourceDescription

A common type for a resource description that can be used to describe any type of GPU resource.

Public Types

using HashT = size_t

The type of the hash value.

Public Functions

ResourceDescription() = default

Default constructor.

ResourceDescription(const ResourceDescription&) = default

Copy constructor.

ResourceDescription &operator=(const ResourceDescription&) = default

Copy assignment operator.

inline ResourceDescription(const BufferResourceDescription &buf)

Constructor for buffer resources.

inline ResourceDescription(const TextureResourceDescription &tex)

Constructor for 2D textures.

inline ResourceDescription(const VolTextureResourceDescription &tex)

Constructor for volume textures.

inline ResourceDescription(const ArrayTextureResourceDescription &tex)

Constructor for array textures.

inline ResourceDescription(const CubeTextureResourceDescription &tex)

Constructor for cube textures.

inline ResourceDescription(const ArrayCubeTextureResourceDescription &tex)

Constructor for array cube textures.

inline bool operator==(const ResourceDescription &r) const

Equality operator for resource descriptions.

The operator compares all necessary fields of the resource descriptions for equality.

Parameters:

r – The resource description to compare with.

Returns:

True if the resource descriptions are equal, false otherwise.

inline HashT hash() const

Computes the hash value of the resource description.

Returns:

The hash value of the resource description.

Public Members

uint32_t resType

The type of the resource. One of the RES3D_* constants.

BasicResourceDescription asBasicRes

The basic resource description.

BufferResourceDescription asBufferRes

The buffer resource description.

BasicTextureResourceDescription asBasicTexRes

The basic texture resource description.

TextureResourceDescription asTexRes

The 2D texture resource description.

VolTextureResourceDescription asVolTexRes

The volume texture resource description.

ArrayTextureResourceDescription asArrayTexRes

The array texture resource description.

CubeTextureResourceDescription asCubeTexRes

The cube texture resource description.

ArrayCubeTextureResourceDescription asArrayCubeTexRes

The array cube texture resource description.

union ResourceDescription::[anonymous] [anonymous]

Private Functions

inline HashT hashPack() const

Hashes an empty tuple of values.

Returns:

HashT the hash value of the tuple.

template<typename T, typename ...Ts>
inline HashT hashPack(const T &first, const Ts&... other) const

Hashes a tuple of values.

Template Parameters:

  • T – type of the first value.

  • Ts – types of the other values.

Parameters:

  • first – the first value.

  • other – the other values.

Returns:

HashT the hash value of the tuple.

struct ResourceHeapGroupProperties

Properties of a resource heap group. A heap group is a type of memory with specific properties.

Note

Heap groups can not be substitutes for different groups with equal properties, as some devices have different memory types with the same public properties, but with purpose bound properties that are identified by a heap group. For example, older NVIDIA hardware can not put render target and non render target textures into the same memory region, they have to be specific for render targets and non render targets, this is exposed as different heap groups, but they have the same public properties, as they are all reside on GPU local memory.

Public Members

uint32_t flags

Flags of the resource heap group represented as a single dword.

bool isCPUVisible

If true, the CPU can access this memory directly. On consoles this is usually true for all heap groups, on PC only for system memory heap groups.

bool isGPULocal

If true, the GPU can access this memory directly without going over a bus like PCIE. On consoles this is usually true for all heap groups, on PC only for memory dedicated to the GPU.

bool isOnChip

Special on chip memory, like ESRAM of the XB1.

union ResourceHeapGroupProperties::[anonymous] [anonymous]
uint64_t maxResourceSize

The maximum size of a resource that can be placed into a heap of this group.

uint64_t maxHeapSize

the maximum size of a individual heap, this is usually limited by the amount that is installed in the system. Drivers may impose other limitations.

uint64_t optimalMaxHeapSize

This is a hint for the user to try to aim for this heap size for best performance. Larger heaps until maxHeapSize are still possible, but larger heaps than optimalMaxHeapSize may yield worse performance, as the runtime may has to use sub-optimal memory sources to satisfy the allocation request. A value of 0 indicates that there is no optimal size and any size is expected to perform similarly.

For example on DX12 on Windows the optimal size is 64 MiBytes, suggested by MS representatives, as windows may not be able to provide heaps in the requested memory source.

struct ResourceAllocationProperties

Properties of a resource allocation.

Public Members

size_t sizeInBytes

The size of the resource allocation in bytes.

size_t offsetAlignment

The alignment of the offset in bytes.

ResourceHeapGroup *heapGroup

The resource heap group.

namespace eastl
template<>
class hash<ResourceDescription>

Hash function specialization for ResourceDescription.

Public Functions

inline size_t operator()(const ResourceDescription &desc) const

Computes the hash value of a resource description.

Parameters:

desc – The resource description.

Returns:

The hash value of the resource description.

namespace d3d

Functions

ResourceAllocationProperties get_resource_allocation_properties(const ResourceDescription &desc)

Retrieves the resource allocation properties for a given resource description.

Parameters:

desc – The resource description. Resource descriptions that would describe a resource with one or more of its dimensions being 0 will result in an error.

Returns:

The resource allocation properties. On error sizeInBytes field of the returned value will be 0.

ResourceHeap *create_resource_heap(ResourceHeapGroup *heap_group, size_t size, ResourceHeapCreateFlags flags)

Creates a resource heap with the specified size and flags.

Parameters:

  • heap_group – The resource heap group.

  • size – The size of the resource heap in bytes. A value of 0 is invalid and results in undefined behavior.

  • flags – The flags for creating the resource heap.

Returns:

A pointer to the created resource heap. May be nullptr on error, like out of memory or invalid inputs.

void destroy_resource_heap(ResourceHeap *heap)

Destroys a resource heap.

Parameters:

heap – The resource heap to destroy.

Sbuffer *place_buffer_in_resource_heap(ResourceHeap *heap, const ResourceDescription &desc, size_t offset, const ResourceAllocationProperties &alloc_info, const char *name)

Places a buffer in a resource heap at the specified offset.

The heap group of heap has to match the heap group of alloc_info that was returned by get_resource_allocation_properties.

Parameters:

  • heap – The resource heap.

  • desc – The resource description.

  • offset – The offset in the resource heap in bytes.

  • alloc_info – The resource allocation properties.

  • name – The name of the buffer.

Returns:

A pointer to the placed buffer. May be nullptr on error, like invalid inputs.

BaseTexture *place_texture_in_resource_heap(ResourceHeap *heap, const ResourceDescription &desc, size_t offset, const ResourceAllocationProperties &alloc_info, const char *name)

Places a texture in a resource heap at the specified offset.

The heap group of heap has to match the heap group of alloc_info that was returned by get_resource_allocation_properties.

Parameters:

  • heap – The resource heap.

  • desc – The resource description.

  • offset – The offset in the resource heap in bytes.

  • alloc_info – The resource allocation properties.

  • name – The name of the texture.

Returns:

A pointer to the placed texture. May be nullptr on error, like invalid inputs.

ResourceHeapGroupProperties get_resource_heap_group_properties(ResourceHeapGroup *heap_group)

Retrieves the resource heap group properties for a given resource heap group.

Note

Different groups may return identical values, this does not mean that the heap group is identical or can be substituted for each another. Heap groups represent purpose bound memory that may have device specific properties, that limit the use of a heap group for certain resource types.

Parameters:

heap_group – The resource heap group.

Returns:

The resource heap group properties.

void activate_buffer(Sbuffer *buf, ResourceActivationAction action, const ResourceClearValue &value = {}, GpuPipeline gpu_pipeline = GpuPipeline::GRAPHICS)

Activates a buffer with the specified action and optional clear value.

Only activated placed buffer could be safely used. Using the buffer before being activated results in undefined behavior.

Warning

gpu_pipeline parameter doesn’t work currently.

Parameters:

  • buf – The buffer to activate.

  • action – The activation action.

  • value – The clear value (optional).

  • gpu_pipeline – The GPU pipeline to use (optional).

void activate_texture(BaseTexture *tex, ResourceActivationAction action, const ResourceClearValue &value = {}, GpuPipeline gpu_pipeline = GpuPipeline::GRAPHICS)

Activates a texture with the specified action and optional clear value.

Only activated placed textures could be safely used. Using the texture before being activated results in undefined behavior.

Warning

gpu_pipeline parameter doesn’t work currently.

Parameters:

  • tex – The texture to activate.

  • action – The activation action.

  • value – The clear value (optional).

  • gpu_pipeline – The GPU pipeline to use (optional).

void deactivate_buffer(Sbuffer *buf, GpuPipeline gpu_pipeline = GpuPipeline::GRAPHICS)

Deactivates a buffer with the specified GPU pipeline.

The method call is necessary to have a correct state of the resources on a heap. Using the buffer after being deactivated results in undefined behavior.

Warning

gpu_pipeline parameter doesn’t work currently.

Parameters:

  • buf – The placed buffer to deactivate.

  • gpu_pipeline – The GPU pipeline to use (optional).

void deactivate_texture(BaseTexture *tex, GpuPipeline gpu_pipeline = GpuPipeline::GRAPHICS)

Deactivates a texture with the specified GPU pipeline.

The method call is necessary to have a correct state of the resources on a heap. Using the texture after being deactivated results in undefined behavior.

Warning

gpu_pipeline parameter doesn’t work currently.

Parameters:

  • tex – The placed texture to deactivate.

  • gpu_pipeline – The GPU pipeline to use (optional).