Class

MTKTextureLoader

An object that decodes common image formats into Metal textures for use in your app.

Declaration

@interface MTKTextureLoader : NSObject

Overview

Use MTKTextureLoader to create a Metal texture with preexisting data as its contents. This class can read common file formats like PNG, JPEG, and TIFF. It can also load image data from KTX and PVR files, asset catalogs, Core Graphics images, and other sources. It infers the output texture format and pixel format from the image data. You can specify options to alter the image loading and texture creation process.

You can create textures synchronously or asynchronously. MTKTextureLoader methods return MTLTexture objects. You are responsible for maintaining strong references to the textures after you create them.

Initialize a MTKTextureLoader object using the device object that it should use to create textures, then call one of the texture loader's methods to create a texture. The code listing below synchronously creates a texture from data stored at a URL, using the default options:

- (id<MTLTexture>)loadTextureUsingMetalKit: (NSURL *) url device: (id<MTLDevice>) device {
    MTKTextureLoader *loader = [[MTKTextureLoader alloc] initWithDevice: device];
    
    id<MTLTexture> texture = [loader newTextureWithContentsOfURL:url options:nil error:nil];
    
    if(!texture)
    {
        NSLog(@"Failed to create the texture from %@", url.absoluteString);
        return nil;
    }
    return texture;
}

You'd typically use MTKTextureLoader to create a texture when you need basic texture loading behavior. If you have custom data formats, or need to change the texture's contents at runtime, use methods on MTLTexture instead. For more information, see Creating and Sampling Textures.

Topics

Creating a Texture Loader

- initWithDevice:

Initializes a new texture loader object.

device

The device object that the texture loader uses to create textures.

Loading Textures from URLs

- newTextureWithContentsOfURL:options:error:

Synchronously loads image data and creates a new Metal texture from a given URL.

- newTextureWithContentsOfURL:options:completionHandler:

Asynchronously loads image data and creates a new Metal texture from a given URL.

- newTexturesWithContentsOfURLs:options:error:

Synchronously loads image data and creates new Metal textures from the specified list of URLs.

- newTexturesWithContentsOfURLs:options:completionHandler:

Asynchronously loads image data and creates new Metal textures from the specified list of URLs.

Loading Textures from Asset Catalogs

- newTextureWithName:scaleFactor:bundle:options:error:

Synchronously loads image data and creates a Metal texture from the named texture asset in an asset catalog.

- newTextureWithName:scaleFactor:bundle:options:completionHandler:

Asynchronously loads image data and creates a Metal texture from the named texture asset in an asset catalog.

- newTexturesWithNames:scaleFactor:bundle:options:completionHandler:

Asynchronously loads image data and creates Metal textures from the specified list of named texture assets in an asset catalog.

- newTextureWithName:scaleFactor:displayGamut:bundle:options:error:

Synchronously loads image data and creates a Metal texture from the named texture asset in an asset catalog, using a specified display gamut.

- newTextureWithName:scaleFactor:displayGamut:bundle:options:completionHandler:

Asynchronously loads image data and creates a Metal texture from the named texture asset in an asset catalog.

- newTexturesWithNames:scaleFactor:displayGamut:bundle:options:completionHandler:

Asynchronously loads image data and creates Metal textures from the specified list of named texture assets in an asset catalog.

Loading Textures from Core Graphics Images

- newTextureWithCGImage:options:error:

Synchronously loads image data and creates a new Metal texture from a given bitmap image.

- newTextureWithCGImage:options:completionHandler:

Asynchronously loads image data and creates a new Metal texture from a given bitmap image.

Loading Textures from In-Memory Data Representations

- newTextureWithData:options:error:

Synchronously creates a new Metal texture from an in-memory representation of the texture's data.

- newTextureWithData:options:completionHandler:

Asynchronously creates a new Metal texture from an in-memory representation of the texture's data.

Loading Textures from Model I/O Representations

- newTextureWithMDLTexture:options:error:

Synchronously loads image data and creates a Metal texture from the specified Model I/O texture.

- newTextureWithMDLTexture:options:completionHandler:

Asynchronously loads image data and creates a Metal texture from the specified Model I/O texture.

Specifying Loading Options

MTKTextureLoaderOption

Keys and values used to specify loading options.

Completing a Texture Loading Operation

MTKTextureLoaderArrayCallback

The signature for the block executed after an asynchronous loading operation for multiple textures has completed.

MTKTextureLoaderCallback

The signature for the block executed after an asynchronous loading operation for a single texture has completed.

Handling Errors

MTKTextureLoaderError

Errors returned by the texture loader.

Relationships

Inherits From