Instance Method

initWithTexture:featureChannels:

Initializes an image from a texture. The user-allocated texture has been created for a specific number of feature channels and number of images.

Declaration

- (instancetype)initWithTexture:(id<MTLTexture>)texture featureChannels:(NSUInteger)featureChannels;

Parameters

texture

The texture allocated by the user to be used as a backing storage for the image.

featureChannels

The number of feature channels the texture contains.

Return Value

A valid MPSImage object or nil, if failure.

Discussion

In a memory-intensive app, you can save memory (and allocation/deallocation time) by using an MPSTemporaryImage object, where the framework aggressively reuses underlying texture memory within the same command buffer. However, in certain cases, you may want more control on the allocation, placement, reuse, and recycling of memory-backing textures used in your app by using the Metal Resource Heaps API. In this case, an app can create an MPSImage object from a pre-allocated texture by calling this method.

The textureType property of the given texture can be of type MTLTextureType2D only if featureChannels<=4 (meaning that numberOfImages=1). Otherwise, the texture type should be MTLTextureType2DArray with the arrayLength property of the given texture being equal to numberOfImages*((featureChannels+3)/4).

For textures containing typical image data, the featureChannels parameter should be set to the number of valid color channels (e.g. for RGB data, even though the pixel format is a form of MTLPixelFormatRGBA, featureChannels should be set to 3.).