MPSNNGraph(3)						 MetalPerformanceShaders.framework					     MPSNNGraph(3)

NAME

       MPSNNGraph

SYNOPSIS

       #import <MPSNNGraph.h>

       Inherits MPSKernel, <NSCopying>, and <NSSecureCoding>.

   Instance Methods
       (nullable instancetype) - initWithDevice:resultImage:resultImageIsNeeded:
       (nullable instancetype) - initWithDevice:resultImage:
       (nullable instancetype) - initWithCoder:device:
       (nonnull instancetype) - initWithDevice:
       (MPSImage *__nullable) - encodeToCommandBuffer:sourceImages:sourceStates:intermediateImages:destinationStates:
       (MPSImageBatch *__nullable) - encodeBatchToCommandBuffer:sourceImages:sourceStates:intermediateImages:destinationStates:
       (MPSImage *__nullable) - encodeToCommandBuffer:sourceImages:
       (MPSImageBatch *__nullable) - encodeBatchToCommandBuffer:sourceImages:sourceStates:
       (MPSImage *__nonnull) - executeAsyncWithSourceImages:completionHandler:

   Class Methods
       (nullable instancetype) + graphWithDevice:resultImage:resultImageIsNeeded:
       (nullable instancetype) + graphWithDevice:resultImage:

   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
       MPSImageFeatureChannelFormat format
       BOOL resultImageIsNeeded

   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
   - (MPSImageBatch * __nullable) encodeBatchToCommandBuffer: (nonnull id< MTLCommandBuffer >) commandBuffer(NSArray< MPSImageBatch * >
       *__nonnull) sourceImages(NSArray< MPSStateBatch * > *__nullable) sourceStates
       Convenience method to encode a batch of images

   - (MPSImageBatch * __nullable) encodeBatchToCommandBuffer: (__nonnull id< MTLCommandBuffer >) commandBuffer(NSArray< MPSImageBatch * >
       *__nonnull) sourceImages(NSArray< MPSStateBatch * > *__nullable) sourceStates(NSMutableArray< MPSImageBatch * > *__nullable)
       intermediateImages(NSMutableArray< MPSStateBatch * > *__nullable) destinationStates
       Encode the graph to a MTLCommandBuffer  This interface is like the other except that it operates on a batch of images all at once. In
       addition, you may specify whether the result is needed.

       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 MPSImageBatch or MPSTemporaryImageBatch allocated per the destinationImageAllocator containing the output of the graph. It will be
	   automatically released when commandBuffer completes. If resultIsNeeded == NO, then this will return nil.

   - (MPSImage * __nullable) 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. It can be nil if resultImageIsNeeded == NO

   - (MPSImage * __nullable) 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) graphWithDevice: (nonnull id< MTLDevice >) device(MPSNNImageNode *__nonnull) resultImage
   + (nullable instancetype) graphWithDevice: (nonnull id< MTLDevice >) device(MPSNNImageNode *__nonnull) resultImage(BOOL) resultIsNeeded
   - (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
   - (nullable instancetype) initWithDevice: (nonnull id< MTLDevice >) device(MPSNNImageNode *__nonnull) resultImage(BOOL) resultIsNeeded
       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.
	   resultIsNeeded Commonly, when training a graph, the last MPSImage out of the graph is not used. The final gradient filter is run solely
	   to update some weights. If resultIsNeeded is set to NO, nil will be returned from the left hand side of the -encode call instead, and
	   computation to produce the last image may be pruned away.

       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)

   - (MPSImageFeatureChannelFormat) format [read],  [write],  [nonatomic],  [assign]
       The default storage format used for graph intermediate images  This doesn't affect how data is stored in buffers in states. Nor does it
       affect the storage format for weights such as convolution weights stored by individual filters. Default:
       MPSImageFeatureChannelFormatFloat16

   - (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: NO

   - (id<MPSHandle>) resultHandle [read],  [nonatomic],  [assign]
       Get a handle for the graph result image

   - (BOOL) resultImageIsNeeded [read],  [nonatomic],  [assign]
       Set at -init time.  If NO, nil will be returned from -encode calls and some computation may be omitted.

   - (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-100				  Thu Feb 8 2018						     MPSNNGraph(3)