MPSTemporaryImage(3) MetalPerformanceShaders.framework MPSTemporaryImage(3)
NAME
MPSTemporaryImage
SYNOPSIS
#import <MPSImage.h>
Inherits MPSImage.
Instance Methods
(nonnull instancetype) - initWithTexture:featureChannels:
(nonnull instancetype) - initWithDevice:imageDescriptor:
Class Methods
(nonnull id< MPSImageAllocator >) + defaultAllocator
(nonnull instancetype) +
temporaryImageWithCommandBuffer:imageDescriptor:
(nonnull instancetype) +
temporaryImageWithCommandBuffer:textureDescriptor:
(void) + prefetchStorageWithCommandBuffer:imageDescriptorList:
Properties
NSUInteger readCount
Detailed Description
MPSImage MPSTemporaryImages are for MPSImages with short lifetimes.
What is temporary memory? It is memory, plain and simple. Analogy: If
we use an app as an analogy for a command buffer, then 'Regular memory'
(such as what backs a MPSImage or the typical MTLTexture) would be
memory that you allocate at launch and never free. Temporary memory
would be memory that you free when you are done with it so it can be
used for something else as needed later in your app. You /could/ write
your app to allocate everything you will ever need up front, but this
is very inefficient and quite frankly a pain to plan out in advance.
You don't do it for your app, so why would you do it for your command
buffers?
Welcome to the 1970's! We have added a heap.
Unsurprisingly, MPSTemporaryImages can provide for profound reduction
in the the amount of memory used by your application. Like malloc, MPS
maintains a heap of memory usable in a command buffer. Over the
lifetime of a command buffer, the same piece of memory may be reused
many times. This means that each time the same meory is reused, it
aliases with previous uses. If we aren't careful, we might find that
needed data is overwritten by successive allocations. However, this is
no different than accessing freed memory only to discover it doesn't
contain what you thought it did anymore, so you should be able to keep
out of trouble by following a few simple rules, like with malloc.
To this end, we added some restrictions to help you out and get a bit
more performance. Some comments are appended in parentheses below to
extend the analogy of command buffer = program:
o The textures are MTLStorageModePrivate. You can not, for example, use
[MTLTexture getBytes...] or [MTLTexture replaceRegion...] with them.
MPSTemporaryImages are strictly read and written by the GPU. (There
is protected memory to prevent other processes from overwriting your
heap.)
o The temporary image may be used only on a single MTLCommandBuffer.
This limits the chronology to a single linear time stream. (The heap
is specific to just one command buffer. There are no mutexes to
coordinate timing of simultaneous access by multiple GPUs. Nor are we
likely to like them if there were. So, we disallow it.)
o The readCount property must be managed correctly. Please see the
description of the readCount property for full details. (The
readCount is a reference count for the block of memory that holds
your data. The usual undefined behaviors apply to reading data that
has been released. We assert when we can to prevent that from
happening accidentally, just as a program might segfault. The
readCount counts procedural users of the object --
MPSKernel.encode... calls that read the MPSTemporaryImage. As each
reads from it, the readCount is automatically decremented. The
texture data will be freed in typical usage at the right time as the
readCount reaches zero, typically with little user involvement other
than to set the readCount up front. We did examine using the main
MPSTemporaryImage reference count for this instead so that ARC would
do work for you automatically. Alas, ARC destroys things at end of
scope rather than promptly, sometimes resulting in greatly increased
memory usage. These allocations are large! So, we use this method
instead.)
Since MPSTemporaryImages can only be used with a single
MTLCommandBuffer, and can not be used off the GPU, they generally
should not be kept around past the completion of the MTLCommandBuffer.
The lifetime of MPSTemporaryImages is expected to be typically
extremely short, perhaps only a few lines of code. Like malloc, it is
intended to be fairly cheap to make MPSTemporaryImages and throw them
away. Please do so.
To keep the lifetime of the underlying texture allocation as short as
possible, the underlying texture is not allocated until the first time
the MPSTemporaryImage is used by a MPSCNNKernel or the .texture
property is read. The readCount property serves to limit the lifetime
on the other end.
You may use the MPSTemporaryImage.texture with MPSUnaryImageKernel
-encode... methods, iff featureChannels <= 4 and the MTLTexture
conforms to requirements of that MPSKernel. There is no locking
mechanism provided to prevent a MTLTexture returned from the .texture
property from becoming invalid when the readCount reaches 0.
MPSTemporaryImages can otherwise be used wherever MPSImages are used.
Method Documentation
+ (nonnull id <MPSImageAllocator>) defaultAllocator
Get a well known MPSImageAllocator that makes MPSTemporaryImages
Reimplemented from MPSImage.
- (nonnull instancetype) initWithDevice: (nonnull id< MTLDevice >)
device(const MPSImageDescriptor *__nonnull) imageDescriptor
Unavailable. Use itemporaryImageForCommandBuffer:textureDescriptor:
instead.
Reimplemented from MPSImage.
- (nonnull instancetype) initWithTexture: (nonnull id< MTLTexture >)
texture(NSUInteger) featureChannels
Unavailable. Use temporaryImageForCommandBuffer:textureDescriptor: or
-temporaryImageForCommandBuffer:imageDescriptor: instead.
Reimplemented from MPSImage.
+ (void) prefetchStorageWithCommandBuffer: (nonnull id< MTLCommandBuffer >)
commandBuffer(NSArray< MPSImageDescriptor * > *__nonnull)
descriptorList
Help MPS decide which allocations to make ahead of time The texture
cache that underlies the MPSTemporaryImage can automatically allocate
new storage as needed as you create new temporary images. However,
sometimes a more global view of what you plan to make is useful for
maximizing memory reuse to get the most efficient operation. This class
method hints to the cache what the list of images will be.
It is never necessary to call this method. It is purely a performance
and memory optimization.
Parameters:
commandBuffer The command buffer on which the MPSTemporaryImages
will be used
descriptorList A NSArray of MPSImageDescriptors, indicating images
that will be created
+ (nonnull instancetype) temporaryImageWithCommandBuffer: (nonnull id<
MTLCommandBuffer >) commandBuffer(const MPSImageDescriptor *__nonnull)
imageDescriptor
Initialize a MPSTemporaryImage for use on a MTLCommandBuffer
Parameters:
commandBuffer The MTLCommandBuffer on which the MPSTemporaryImage
will be exclusively used
imageDescriptor A valid imageDescriptor describing the MPSImage
format to create.
Returns:
A valid MPSTemporaryImage. The object will be released when the
command buffer is committed. The underlying texture will become
invalid before this time due to the action of the readCount
property.
+ (nonnull instancetype) temporaryImageWithCommandBuffer: (nonnull id<
MTLCommandBuffer >) commandBuffer(const MTLTextureDescriptor
*__nonnull) textureDescriptor
Low level interface for creating a MPSTemporaryImage using a
MTLTextureDescriptor This function provides access to MTLPixelFormats
not typically covered by -initForCommandBuffer:imageDescriptor: The
feature channels will be inferred from the MTLPixelFormat without
changing the width. The following restrictions apply:
MTLTextureType must be MTLTextureType2D or MTLTextureType2DArray
MTLTextureUsage must contain at least one of MTLTextureUsageShaderRead, MTLTextureUsageShaderWrite
MTLStorageMode must be MTLStorageModePrivate
depth must be 1
Parameters:
commandBuffer The command buffer on which the MPSTemporaryImage may
be used
textureDescriptor A texture descriptor describing the
MPSTemporaryImage texture
Returns:
A valid MPSTemporaryImage. The object will be released when the
command buffer is committed. The underlying texture will become
invalid before this time due to the action of the readCount
property.
Property Documentation
- (NSUInteger) readCount [read], [write], [nonatomic], [assign]
Author
Generated automatically by Doxygen for
MetalPerformanceShaders.framework from the source code.
Version MetalPerformanceShaders-Thu2Jul 13 2017 MPSTemporaryImage(3)
Mac OS X 10.13.1 - Generated Tue Nov 7 19:11:47 CST 2017
