Contents

Creating sparse heaps and sparse textures

Allocate memory for sparse textures by creating a sparse heap.

Overview

Sparse heaps are MTLHeap instances that create sparse textures and provide memory for them. Unlike with a standard heap, you use a sparse heap only to create sparse textures and allocate storage for texture data. You allocate memory when you create the heap, and later, as needed, map or unmap portions of the heap’s memory to textures. Memory is mapped in larger chunks called sparse tiles. The size of sparse tiles (in bytes) is determined by the device instance.

Create a sparse heap

Create an MTLHeapDescriptor instance and set its type to MTLHeapType.sparse. You need to allocate sparse heaps with the MTLStorageMode.private storage mode. Specify the heap’s size as a multiple of the sparse tile size. To get the tile size, read the sparseTileSizeInBytes property on the MTLDevice instance that you’re using to create the heap.

The code below creates a new sparse heap, rounding the heap size up to the tile size.

Specify a heap size that’s appropriate for your app, based on how many textures you’ve, how large those textures are, and your image-quality goals. You may need to experiment to determine the best size. The heap should be large enough that your app doesn’t need to unmap sparse tiles frequently and doesn’t suffer from image-quality problems. Unless you need finer-grained control of how different collections of textures are allocated in memory, allocate a single sparse heap and use it to manage all of your app’s texture memory.

Create a sparse texture

All textures that you create on a sparse heap are sparse textures. When you create textures on heaps, use the same storage mode as the sparse heap, similar to the example code below:

When you create a sparse texture, no memory is allocated for it. It can’t store any pixel data until you map sparse tiles on the heap to regions inside the texture. For more information about mapping and unmapping sparse tiles, see Assigning memory to sparse textures. For more information about how sparse textures behave when you access them, see Reading and writing to sparse textures.

See Also

Sparse textures