Class

MTKTextureLoader

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

Declaration

class 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

init(device: MTLDevice)

Initializes a new texture loader object.

var device: MTLDevice

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

Loading Textures from URLs

func newTexture(URL: URL, options: [MTKTextureLoader.Option : Any]?) -> MTLTexture

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

func newTexture(URL: URL, options: [MTKTextureLoader.Option : Any]?, completionHandler: MTKTextureLoader.Callback)

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

func newTextures(URLs: [URL], options: [MTKTextureLoader.Option : Any]?, error: NSErrorPointer) -> [MTLTexture]

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

func newTextures(URLs: [URL], options: [MTKTextureLoader.Option : Any]?, completionHandler: MTKTextureLoader.ArrayCallback)

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

Loading Textures from Asset Catalogs

func newTexture(name: String, scaleFactor: CGFloat, bundle: Bundle?, options: [MTKTextureLoader.Option : Any]?) -> MTLTexture

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

func newTexture(name: String, scaleFactor: CGFloat, bundle: Bundle?, options: [MTKTextureLoader.Option : Any]?, completionHandler: MTKTextureLoader.Callback)

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

func newTextures(names: [String], scaleFactor: CGFloat, bundle: Bundle?, options: [MTKTextureLoader.Option : Any]?, completionHandler: MTKTextureLoader.ArrayCallback)

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

func newTexture(name: String, scaleFactor: CGFloat, displayGamut: NSDisplayGamut, bundle: Bundle?, options: [MTKTextureLoader.Option : Any]?) -> MTLTexture

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

Loading Textures from Core Graphics Images

func newTexture(cgImage: CGImage, options: [MTKTextureLoader.Option : Any]?) -> MTLTexture

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

func newTexture(cgImage: CGImage, options: [MTKTextureLoader.Option : Any]?, completionHandler: MTKTextureLoader.Callback)

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

Loading Textures from In-Memory Data Representations

func newTexture(data: Data, options: [MTKTextureLoader.Option : Any]?) -> MTLTexture

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

func newTexture(data: Data, options: [MTKTextureLoader.Option : Any]?, completionHandler: MTKTextureLoader.Callback)

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

Loading Textures from Model I/O Representations

func newTexture(texture: MDLTexture, options: [MTKTextureLoader.Option : Any]?) -> MTLTexture

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

func newTexture(texture: MDLTexture, options: [MTKTextureLoader.Option : Any]?, completionHandler: MTKTextureLoader.Callback)

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

Specifying Loading Options

struct MTKTextureLoader.Option

Keys and values used to specify loading options.

Completing a Texture Loading Operation

typealias MTKTextureLoader.ArrayCallback

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

typealias MTKTextureLoader.Callback

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

Handling Errors

struct MTKTextureLoader.Error

Errors returned by the texture loader.

Relationships

Inherits From

Conforms To