Protocol

MTLHeap

A memory pool from which you can suballocate resources.

Declaration

protocol MTLHeap

Overview

Don’t implement this protocol yourself; instead, configure a MTLHeapDescriptor object and call the makeHeap(descriptor:) method of a MTLDevice object.

Resources can be sub-allocated from a heap and made aliasable or non-aliasable. A sub-allocated resource is non-aliased by default, preventing future sub-allocated resources from using its memory. Sub-allocated resources are aliased when they share the same memory allocation backed by a heap.

All resources sub-allocated from the same heap share the same storage mode and CPU cache mode. Heaps can be made purgeable but their sub-allocated resources are not; they can only reflect the heap’s purgeability state.

Topics

Identifying the Heap

var device: MTLDevice

The device object that created the heap.

Required.

var label: String?

A string that identifies the heap.

Required.

Querying Heap Properties

var storageMode: MTLStorageMode

The storage mode of the heap.

Required.

var cpuCacheMode: MTLCPUCacheMode

The CPU cache mode of the heap.

Required.

var size: Int

The total size of the heap, in bytes.

Required.

var usedSize: Int

The size of all resources sub-allocated from the heap, in bytes.

Required.

var currentAllocatedSize: Int

The size, in bytes, of the current heap allocation.

Required.

func maxAvailableSize(alignment: Int) -> Int

The maximum size, in bytes, that can be successfully sub-allocated from the heap for a resource with the given alignment.

Required.

Setting the Purgeable State of the Resource

func setPurgeableState(MTLPurgeableState) -> MTLPurgeableState

Sets the purgeable state of the heap.

Required.

Creating Suballocated Resources

func makeBuffer(length: Int, options: MTLResourceOptions) -> MTLBuffer?

Creates a new buffer backed by heap memory.

Required.

func makeTexture(descriptor: MTLTextureDescriptor) -> MTLTexture?

Creates a new texture backed by heap memory.

Required.

Relationships

Inherits From

See Also

Essentials

Image Filter Graph with Heaps and Fences

Demonstrates how to use heaps and fences to optimize a multistage image filter.

class MTLHeapDescriptor

An object you use to configure new heap objects.

struct MTLSizeAndAlign

The size and alignment of a resource, in bytes.