Article

Copying Data into or out of Mipmaps

Specify which mipmaps are affected by the data transfer.

Overview

When you copy data between resources, and the source or destination is a texture, you need to specify which mipmaps are affected.

Copy Data from System Memory to a Mipmap

When you copy data from system memory into a texture, state which mipmap is the destination of that copy, as shown in the code below:

MTLRegion region = {
    { 0, 0, 0 },                   // MTLOrigin
    {image.width, image.height, 1} // MTLSize
};

[texture replaceRegion:region
           mipmapLevel:0
             withBytes:image.data.bytes
           bytesPerRow:bytesPerRow];

Call this routine once for each mipmap you want to fill, changing the region to match the size of the mipmap level you are writing to.

Copy Mipmap Data Between Metal Resources

If you already have data in Metal resources, use a MTLBlitCommandEncoder to copy data to and from different mipmaps in a texture.

To copy all matching data between two textures, encode a command using the copy(from:to:): method. The two textures must have the same pixel format and type. All matching mipmap sizes are copied to the destination texture.

To copy a selection of mipmaps from one texture to another, use the copy(from:sourceSlice:sourceLevel:to:destinationSlice:destinationLevel:sliceCount:levelCount:) method. Specify the first source mipmap level and first destination mipmap level, both of which must have the same dimensions. Also specify the number of mipmap levels you want to copy.

For example, the following code is written with the assumption that the destination texture is twice as large in both dimensions as the source texture. Mipmap 1 in the destination matches the size of the source mipmap 0, so the code specifies a source level of 0 and a destination level of 1. The level count specifies that 5 mipmaps should be copied.

[encoder copyFromTexture: source
    sourceSlice: 0
    sourceLevel: 0
    toTexture: destination
    destinationSlice: 0
    destinationLevel: 1
    sliceCount: 1
    levelCount: 5];

If you need to copy data between buffers and textures, encode a separate blit command for each mipmap level to copy. See MTLBlitCommandEncoder for other methods that copy data to and from textures.

See Also

Essentials

Creating a Mipmapped Texture

Decide whether a texture that you are creating needs mipmaps.

Generating Mipmap Data

Create your mipmaps either when you author content or at runtime.

Adding Mipmap Filtering to Samplers

Specify how the GPU samples mipmaps in your textures.