# MPSTemporaryImage A texture for use in convolutional neural networks that stores transient data to be used and discarded promptly. ``` class MPSTemporaryImage ``` ## Overview [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) objects can provide a profound reduction in the aggregate texture memory and associated CPU-side allocation cost in your app. Metal Performance Shaders achieves this by automatically identifying [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) objects that do not overlap in time over the course of a object’s lifetime and can therefore reuse the same memory. [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) objects leverage an internal cache of preallocated reusable memory to hold pixel data to avoid typical memory allocation performance penalties common to ordinary [`MPSImage`](/documentation/MetalPerformanceShaders/MPSImage) and objects. To avoid data corruption due to aliasing, [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) objects impose some important restrictions: - The underlying texture storage mode is . You cannot, for example, use the or methods with them. Temporary images are strictly read and written by the GPU. - The temporary image may be used only on a single object. This limits the chronology to a single linear time stream. - The [`readCount`](/documentation/MetalPerformanceShaders/MPSTemporaryImage/readCount) property must be managed correctly. - Temporary images must also adhere to the general pixel format restrictions for [`MPSImage`](/documentation/MetalPerformanceShaders/MPSImage) objects. Since temporary images can only be used with a single command buffer, and can not be used off the GPU, they generally should not be kept around past the completion of their associated command buffer. The lifetime of a temporary image is typically expected to be extremely short, perhaps spanning only a few lines of code. To keep the lifetime of the underlying texture allocation as short as possible, the texture is not allocated until the first time the [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) object is used by an [`MPSCNNKernel`](/documentation/MetalPerformanceShaders/MPSCNNKernel) object or until the first time the [`texture`](/documentation/MetalPerformanceShaders/MPSImage/texture) property is read. The [`readCount`](/documentation/MetalPerformanceShaders/MPSTemporaryImage/readCount) property serves to limit the lifetime of the texture on deallocation. You may use the [`texture`](/documentation/MetalPerformanceShaders/MPSImage/texture) property with the `encode` methods of an [`MPSUnaryImageKernel`](/documentation/MetalPerformanceShaders/MPSUnaryImageKernel) subclass, if `featureChannels<=4` and the texture conforms to the requirements of the given kernel. In such cases, the [`readCount`](/documentation/MetalPerformanceShaders/MPSTemporaryImage/readCount) property is not modified, since the enclosing object is not available. There is no locking mechanism provided to prevent a object returned from the [`texture`](/documentation/MetalPerformanceShaders/MPSImage/texture) property from becoming invalid when the value of the [`readCount`](/documentation/MetalPerformanceShaders/MPSTemporaryImage/readCount) property reaches 0. [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) objects can otherwise be used wherever [`MPSImage`](/documentation/MetalPerformanceShaders/MPSImage) objects are used. ### The MPSTemporaryImage Class The [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) class extends the [`MPSImage`](/documentation/MetalPerformanceShaders/MPSImage) class to provide advanced caching of unused memory, in order to increase performance and reduce memory footprint. [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) objects are intended as fast GPU-only storage for intermediate image data needed only transiently within a single object. They accelerate the common case of image data which is created only to be consumed and destroyed immediately by the next operation(s) encoded in a command buffer. [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) objects provide a convenient and simple way to save memory by automatically aliasing other [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) objects in the same command buffer. Because they alias (i.e., share texel storage with) other textures in the same command buffer, the valid lifetime of the data in an [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) object is extremely short, limited to a portion of a the command buffer itself. You can not read or write data to an [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) using the CPU, or use the data in other objects. Use regular [`MPSImage`](/documentation/MetalPerformanceShaders/MPSImage) objects for more persistent storage. ## Topics ### Initializers [`init(commandBuffer:imageDescriptor:)`](/documentation/MetalPerformanceShaders/MPSTemporaryImage/init(commandBuffer:imageDescriptor:)) Initializes a temporary image for use on a command buffer. [`MPSImageDescriptor`](/documentation/MetalPerformanceShaders/MPSImageDescriptor) A description of the attributes used to create an [`MPSImage`](/documentation/MetalPerformanceShaders/MPSImage). [`init(commandBuffer:textureDescriptor:)`](/documentation/MetalPerformanceShaders/MPSTemporaryImage/init(commandBuffer:textureDescriptor:)) Low-level interface for creating a temporary image using a texture descriptor. [`init(commandBuffer:textureDescriptor:featureChannels:)`](/documentation/MetalPerformanceShaders/MPSTemporaryImage/init(commandBuffer:textureDescriptor:featureChannels:)) ### Methods [`prefetchStorage(with:imageDescriptorList:)`](/documentation/MetalPerformanceShaders/MPSTemporaryImage/prefetchStorage(with:imageDescriptorList:)) A method that helps the framework decide which allocations to make ahead of time. ### Methods to Get an Image Allocator [`defaultAllocator()`](/documentation/MetalPerformanceShaders/MPSTemporaryImage/defaultAllocator()) [`MPSImageAllocator`](/documentation/MetalPerformanceShaders/MPSImageAllocator) ### Properties [`readCount`](/documentation/MetalPerformanceShaders/MPSTemporaryImage/readCount) The number of times a temporary image may be read by a CNN kernel before its contents become undefined. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)