MPSNNGraph(3) MetalPerformanceShaders.framework MPSNNGraph(3)
NAME
MPSNNGraph
SYNOPSIS
#import <MPSNNGraph.h>
Inherits MPSKernel, <NSCopying>, and <NSSecureCoding>.
Instance Methods
(nullable instancetype) - initWithDevice:resultImage:
(nullable instancetype) - initWithCoder:device:
(nonnull instancetype) - initWithDevice:
(MPSImage *__nonnull) -
encodeToCommandBuffer:sourceImages:sourceStates:intermediateImages:destinationStates:
(MPSImage *__nonnull) - encodeToCommandBuffer:sourceImages:
(MPSImage *__nonnull) - executeAsyncWithSourceImages:completionHandler:
Properties
NSArray< id< MPSHandle > > * sourceImageHandles
NSArray< id< MPSHandle > > * sourceStateHandles
NSArray< id< MPSHandle > > * intermediateImageHandles
NSArray< id< MPSHandle > > * resultStateHandles
id< MPSHandle > resultHandle
BOOL outputStateIsTemporary
id< MPSImageAllocator > destinationImageAllocator
Additional Inherited Members
Detailed Description
Optimized representation of a graph of MPSNNImageNodes and
MPSNNFilterNodes Once you have prepared a graph of MPSNNImageNodes and
MPSNNFilterNodes (and if needed MPSNNStateNodes), you may initialize a
MPSNNGraph using the MPSNNImageNode that you wish to appear as the
result. The MPSNNGraph object will introspect the graph representation
and determine which nodes are needed for inputs, and which nodes are
produced as output state (if any). Nodes which are not needed to
calculate the result image node are ignored. Some nodes may be
internally concatenated with other nodes for better performance.
Note: the MPSNNImageNode that you choose as the result node may be
interior to a graph. This feature is provided as a means to examine
intermediate computations in the full graph for debugging purposes.
During MPSNNGraph construction, the graph attached to the result node
will be parsed and reduced to an optimized representation. This
representation may be saved using the NSSecureCoding protocol for later
recall.
When decoding a MPSNNGraph using a NSCoder, it will be created against
the system default MTLDevice. If you would like to set the MTLDevice,
your NSCoder should conform to the <MPSDeviceProvider> protocol.
You may find it helpful to set MPSKernelOptionsVerbose on the graph
when debugging.
Method Documentation
- (MPSImage * __nonnull) encodeToCommandBuffer: (nonnull id<
MTLCommandBuffer >) commandBuffer(NSArray< MPSImage * > *__nonnull)
sourceImages
Encode the graph to a MTLCommandBuffer
IMPORTANT: Please use [MTLCommandBuffer addCompletedHandler:] to
determine when this work is done. Use CPU time that would have been
spent waiting for the GPU to encode the next command buffer and commit
it too. That way, the work for the next command buffer is ready to go
the moment the GPU is done. This will keep the GPU busy and running at
top speed.
Those who ignore this advice and use [MTLCommandBuffer
waitUntilCompleted] instead will likely cause their code to slow down
by a factor of two or more. The CPU clock spins down while it waits for
the GPU. When the GPU completes, the CPU runs slowly for a while until
it spins up. The GPU has to wait for the CPU to encode more work (at
low clock), giving it plenty of time to spin its own clock down. In
typical CNN graph usage, neither may ever reach maximum clock
frequency, causing slow down far beyond what otherwise would be
expected from simple failure to schedule CPU and GPU work concurrently.
Regrattably, it is probable that every performance benchmark you see on
the net will be based on [MTLCommandBuffer waitUntilCompleted].
Parameters:
commandBuffer The command buffer
sourceImages A list of MPSImages to use as the source images for
the graph. These should be in the same order as the list returned
from MPSNNGraph.sourceImageHandles.
Returns:
A MPSImage or MPSTemporaryImage allocated per the
destinationImageAllocator containing the output of the graph. It
will be automatically released when commandBuffer completes.
- (MPSImage * __nonnull) encodeToCommandBuffer: (nonnull id<
MTLCommandBuffer >) commandBuffer(NSArray< MPSImage * > *__nonnull)
sourceImages(NSArray< MPSState * > *__nullable)
sourceStates(NSMutableArray< MPSImage * > *__nullable)
intermediateImages(NSMutableArray< MPSState * > *__nullable)
destinationStates
Encode the graph to a MTLCommandBuffer
Parameters:
commandBuffer The command buffer
sourceImages A list of MPSImages to use as the source images for
the graph. These should be in the same order as the list returned
from MPSNNGraph.sourceImageHandles. The images may be image arrays.
Typically, this is only one or two images such as a .JPG decoded
into a MPSImage*. If the sourceImages are MPSTemporaryImages, the
graph will decrement the readCount by 1, even if the graph actually
reads an image multiple times.
sourceStates A list of MPSState objects to use as state for a
graph. These should be in the same order as the list returned from
MPSNNGraph.sourceStateHandles. May be nil, if there is no source
state. If the sourceStates are temporary, the graph will decrement
the readCount by 1, even if the graph actually reads the state
multiple times.
intermediateImages An optional NSMutableArray to receive any
MPSImage objects exported as part of its operation. These are only
the images that were tagged with MPSNNImageNode.exportFromGraph =
YES. The identity of the states is given by -resultStateHandles. If
temporary, each intermediateImage will have a readCount of 1. If
the result was tagged exportFromGraph = YES, it will be here too,
with a readCount of 2.
destinationStates An optional NSMutableArray to receive any
MPSState objects created as part of its operation. The identity of
the states is given by -resultStateHandles.
Returns:
A MPSImage or MPSTemporaryImage allocated per the
destinationImageAllocator containing the output of the graph. It
will be automatically released when commandBuffer completes.
- (MPSImage * __nonnull) executeAsyncWithSourceImages: (NSArray< MPSImage *
> *__nonnull) sourceImages(MPSNNGraphCompletionHandler __nonnull)
handler
Convenience method to execute a graph without having to manage many
Metal details This function will synchronously encode the graph on a
private command buffer, commit it to a MPS internal command queue and
return. The GPU will start working. When the GPU is done, the
completion handler will be called. You should use the intervening time
to encode other work for execution on the GPU, so that the GPU stays
busy and doesn't clock down.
The work will be performed on the MTLDevice that hosts the source
images.
This is a convenience API. There are a few situations it does not
handle optimally. These may be better handled using
[encodeToCommandBuffer:sourceImages:]. Specifically:
o If the graph needs to be run multiple times for different images,
it would be better to encode the graph multiple times on the same
command buffer using [encodeToCommandBuffer:sourceImages:] This
will allow the multiple graphs to share memory for intermediate
storage, dramatically reducing memory usage.
o If preprocessing or post-processing of the MPSImage is required,
such as resizing or normalization outside of a convolution, it would
be better to encode those things on the same command buffer.
Memory may be saved here too for intermediate storage. (MPSTemporaryImage
lifetime does not span multiple command buffers.)
Parameters:
sourceImages A list of MPSImages to use as the source images for
the graph. These should be in the same order as the list returned
from MPSNNGraph.sourceImageHandles. They should be allocated
against the same MTLDevice. There must be at least one source
image. Note: this array is intended to handle the case where
multiple input images are required to generate a single graph
result. That is, the graph itself has multiple inputs. If you need
to execute the graph multiple times, then call this API multiple
times, or better yet use [encodeToCommandBuffer:sourceImages:]
multiple times. (See discussion)
handler A block to receive any errors generated. This block may run
on any thread and may be called before this method returns. The
image, if any, passed to this callback is the same image as that
returned from the left hand side.
Returns:
A MPSImage to receive the result. The data in the image will not be
valid until the completionHandler is called.
- (nullable instancetype) initWithCoder: (NSCoder *__nonnull)
aDecoder(nonnull id< MTLDevice >) device
NSSecureCoding compatability While the standard
NSSecureCoding/NSCoding method -initWithCoder: should work, since the
file can't know which device your data is allocated on, we have to
guess and may guess incorrectly. To avoid that problem, use
initWithCoder:device instead.
Parameters:
aDecoder The NSCoder subclass with your serialized MPSKernel
device The MTLDevice on which to make the MPSKernel
Returns:
A new MPSKernel object, or nil if failure.
Reimplemented from MPSKernel.
- (nonnull instancetype) initWithDevice: (__nonnull id< MTLDevice >) device
Use initWithDevice:resultImage: instead
- (nullable instancetype) initWithDevice: (nonnull id< MTLDevice >)
device(MPSNNImageNode *__nonnull) resultImage
Initialize a MPSNNGraph object on a device starting with resultImage
working backward The MPSNNGraph constructor will start with the
indicated result image, and look to see what MPSNNFilterNode produced
it, then look to its dependencies and so forth to reveal the subsection
of the graph necessary to compute the image.
Parameters:
device The MTLDevice on which to run the graph
resultImage The MPSNNImageNode corresponding to the last image in
the graph. This is the image that will be returned. Note: the
imageAllocator for this node is ignored and the
MPSNNGraph.destinationImageAllocator is used for this node instead.
Returns:
A new MPSNNGraph.
Property Documentation
- (id<MPSImageAllocator>) destinationImageAllocator [read], [write],
[nonatomic], [retain]
Method to allocate the result image from -encodeToCommandBuffer...
This property overrides the allocator for the final result image in the
graph. Default: defaultAllocator (MPSImage)
- (NSArray<id <MPSHandle> >*) intermediateImageHandles [read],
[nonatomic], [copy]
Get a list of identifiers for intermediate images objects produced by
the graph
- (BOOL) outputStateIsTemporary [read], [write], [nonatomic], [assign]
Should MPSState objects produced by -encodeToCommandBuffer... be
temporary objects. See MPSState description. Default: YES
- (id<MPSHandle>) resultHandle [read], [nonatomic], [assign]
Get a handle for the graph result image
- (NSArray<id <MPSHandle> >*) resultStateHandles [read], [nonatomic],
[copy]
Get a list of identifiers for result state objects produced by the
graph Not guaranteed to be in the same order as sourceStateHandles
- (NSArray<id <MPSHandle> >*) sourceImageHandles [read], [nonatomic],
[copy]
Get a list of identifiers for source images needed to calculate the
result image
- (NSArray<id <MPSHandle> >*) sourceStateHandles [read], [nonatomic],
[copy]
Get a list of identifiers for source state objects needed to calculate
the result image Not guaranteed to be in the same order as
resultStateHandles
Author
Generated automatically by Doxygen for
MetalPerformanceShaders.framework from the source code.
Version MetalPerformanceShaders-Thu2Jul 13 2017 MPSNNGraph(3)
Mac OS X 10.12.6 - Generated Tue Oct 31 16:17:49 CDT 2017
