.TH "MPSCNNConvolution" 3 "Mon Jul 9 2018" "Version MetalPerformanceShaders-119.3" "MetalPerformanceShaders.framework" \" -*- nroff -*- .ad l .nh .SH NAME MPSCNNConvolution .SH SYNOPSIS .br .PP .PP \fC#import \fP .PP Inherits \fBMPSCNNKernel\fP\&. .PP Inherited by \fBMPSCNNFullyConnected\fP\&. .SS "Instance Methods" .in +1c .ti -1c .RI "(nonnull instancetype) \- \fBinitWithDevice:weights:\fP" .br .ti -1c .RI "(nonnull instancetype) \- \fBinitWithDevice:convolutionDescriptor:kernelWeights:biasTerms:flags:\fP" .br .ti -1c .RI "(nullable instancetype) \- \fBinitWithCoder:device:\fP" .br .ti -1c .RI "(nonnull instancetype) \- \fBinitWithDevice:\fP" .br .ti -1c .RI "(\fBMPSCNNConvolutionGradientState\fP *__nullable) \- \fBresultStateForSourceImage:sourceStates:destinationImage:\fP" .br .ti -1c .RI "(\fBMPSCNNConvolutionGradientStateBatch\fP *__nullable) \- \fBresultStateBatchForSourceImage:sourceStates:destinationImage:\fP" .br .ti -1c .RI "(\fBMPSCNNConvolutionGradientState\fP *__nullable) \- \fBtemporaryResultStateForCommandBuffer:sourceImage:sourceStates:destinationImage:\fP" .br .ti -1c .RI "(\fBMPSCNNConvolutionGradientStateBatch\fP *__nullable) \- \fBtemporaryResultStateBatchForCommandBuffer:sourceImage:sourceStates:destinationImage:\fP" .br .ti -1c .RI "(void) \- \fBreloadWeightsAndBiasesFromDataSource\fP" .br .ti -1c .RI "(void) \- \fBreloadWeightsAndBiasesWithDataSource:\fP" .br .ti -1c .RI "(void) \- \fBreloadWeightsAndBiasesWithCommandBuffer:state:\fP" .br .ti -1c .RI "(\fBMPSCNNConvolutionWeightsAndBiasesState\fP *__nonnull) \- \fBexportWeightsAndBiasesWithCommandBuffer:resultStateCanBeTemporary:\fP" .br .in -1c .SS "Properties" .in +1c .ti -1c .RI "NSUInteger \fBinputFeatureChannels\fP" .br .ti -1c .RI "NSUInteger \fBoutputFeatureChannels\fP" .br .ti -1c .RI "NSUInteger \fBgroups\fP" .br .ti -1c .RI "id< \fBMPSCNNConvolutionDataSource\fP > \fBdataSource\fP" .br .ti -1c .RI "NSUInteger \fBsubPixelScaleFactor\fP" .br .ti -1c .RI "const \fBMPSCNNNeuron\fP *__nullable \fBneuron\fP" .br .ti -1c .RI "const \fBMPSCNNNeuron\fP *__nullable \fBMPSCNNNeuronType\fP \fBneuronType\fP" .br .ti -1c .RI "const \fBMPSCNNNeuron\fP *__nullable \fBMPSCNNNeuronType\fP float \fBneuronParameterA\fP" .br .ti -1c .RI "const \fBMPSCNNNeuron\fP *__nullable \fBMPSCNNNeuronType\fP float float \fBneuronParameterB\fP" .br .ti -1c .RI "const \fBMPSCNNNeuron\fP *__nullable \fBMPSCNNNeuronType\fP float float float \fBneuronParameterC\fP" .br .ti -1c .RI "const \fBMPSCNNNeuron\fP *__nullable \fBMPSCNNNeuronType\fP float float float \fBMPSNNNeuronDescriptor\fP *__nullable \fBfusedNeuronDescriptor\fP" .br .ti -1c .RI "const \fBMPSCNNNeuron\fP *__nullable \fBMPSCNNNeuronType\fP float float float \fBMPSNNNeuronDescriptor\fP *__nullable NSUInteger \fBchannelMultiplier\fP" .br .ti -1c .RI "\fBMPSNNConvolutionAccumulatorPrecisionOption\fP \fBaccumulatorPrecisionOption\fP" .br .in -1c .SS "Additional Inherited Members" .SH "Detailed Description" .PP This depends on Metal\&.framework The \fBMPSCNNConvolution\fP specifies a convolution\&. The \fBMPSCNNConvolution\fP convolves the input image with a set of filters, each producing one feature map in the output image\&. .SH "Method Documentation" .PP .SS "\- (\fBMPSCNNConvolutionWeightsAndBiasesState\fP* __nonnull) exportWeightsAndBiasesWithCommandBuffer: (__nonnull id< MTLCommandBuffer >) commandBuffer(BOOL) resultStateCanBeTemporary" GPU side export\&. Enqueue a kernel to export current weights and biases stored in MPSCNNConvoltion's internal buffers into weights and biases MTLBuffer returned in \fBMPSCNNConvolutionWeightsAndBiasesState\fP\&. .PP \fBParameters:\fP .RS 4 \fIcommandBuffer\fP Metal command buffer on which export kernel is enqueued\&. .br \fIresultStateCanBeTemporary\fP If FALSE, state returned will be non-temporary\&. If TRUE, returned state may or may not be temporary\&. .RE .PP \fBReturns:\fP .RS 4 \fBMPSCNNConvolutionWeightsAndBiasesState\fP containing weights and biases buffer to which weights got exported\&. This state and be temporary or non-temporary depending on the flag resultStateCanBeTemporary .RE .PP .SS "\- (nullable instancetype) \fBinitWithCoder:\fP (NSCoder *__nonnull) aDecoder(nonnull id< MTLDevice >) device" \fBNSSecureCoding\fP 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\&. .PP \fBParameters:\fP .RS 4 \fIaDecoder\fP The NSCoder subclass with your serialized \fBMPSKernel\fP .br \fIdevice\fP The MTLDevice on which to make the \fBMPSKernel\fP .RE .PP \fBReturns:\fP .RS 4 \fBA\fP new \fBMPSKernel\fP object, or nil if failure\&. .RE .PP .PP Reimplemented from \fBMPSCNNKernel\fP\&. .PP Reimplemented in \fBMPSCNNFullyConnected\fP\&. .SS "\- (nonnull instancetype) initWithDevice: (nonnull id< MTLDevice >) device" Standard init with default properties per filter type .PP \fBParameters:\fP .RS 4 \fIdevice\fP The device that the filter will be used on\&. May not be NULL\&. .RE .PP \fBReturns:\fP .RS 4 \fBA\fP pointer to the newly initialized object\&. This will fail, returning nil if the device is not supported\&. Devices must be MTLFeatureSet_iOS_GPUFamily2_v1 or later\&. .RE .PP .PP Reimplemented from \fBMPSCNNKernel\fP\&. .PP Reimplemented in \fBMPSCNNFullyConnected\fP\&. .SS "\- (nonnull instancetype) \fBinitWithDevice:\fP (nonnull id< MTLDevice >) device(const \fBMPSCNNConvolutionDescriptor\fP *__nonnull) convolutionDescriptor(const float *__nonnull) kernelWeights(const float *__nullable) biasTerms(\fBMPSCNNConvolutionFlags\fP) flags" Initializes a convolution kernel WARNING: This API is depreated and will be removed in the future\&. It cannot be used when training\&. Also serialization/unserialization wont work for \fBMPSCNNConvolution\fP objects created with this init\&. Please move onto using initWithDevice:weights:\&. .PP \fBParameters:\fP .RS 4 \fIdevice\fP The MTLDevice on which this \fBMPSCNNConvolution\fP filter will be used .br \fIconvolutionDescriptor\fP \fBA\fP pointer to a \fBMPSCNNConvolutionDescriptor\fP\&. .br \fIkernelWeights\fP \fBA\fP pointer to a weights array\&. Each entry is a float value\&. The number of entries is = inputFeatureChannels * outputFeatureChannels * kernelHeight * kernelWidth The layout of filter weight is so that it can be reinterpreted as 4D tensor (array) weight[ outputChannels ][ kernelHeight ][ kernelWidth ][ inputChannels / groups ] Weights are converted to half float (fp16) internally for best performance\&. .br \fIbiasTerms\fP \fBA\fP pointer to bias terms to be applied to the convolution output\&. Each entry is a float value\&. The number of entries is = numberOfOutputFeatureMaps .br \fIflags\fP Currently unused\&. Pass MPSCNNConvolutionFlagsNone .RE .PP \fBReturns:\fP .RS 4 \fBA\fP valid \fBMPSCNNConvolution\fP object or nil, if failure\&. .RE .PP .PP Reimplemented in \fBMPSCNNFullyConnected\fP\&. .SS "\- (nonnull instancetype) \fBinitWithDevice:\fP (nonnull id< MTLDevice >) device(nonnull id< \fBMPSCNNConvolutionDataSource\fP >) weights" Initializes a convolution kernel .PP \fBParameters:\fP .RS 4 \fIdevice\fP The MTLDevice on which this \fBMPSCNNConvolution\fP filter will be used .br \fIweights\fP \fBA\fP pointer to a object that conforms to the \fBMPSCNNConvolutionDataSource\fP protocol\&. The \fBMPSCNNConvolutionDataSource\fP protocol declares the methods that an instance of \fBMPSCNNConvolution\fP uses to obtain the weights and bias terms for the CNN convolution filter\&. .RE .PP \fBReturns:\fP .RS 4 \fBA\fP valid \fBMPSCNNConvolution\fP object or nil, if failure\&. .RE .PP .PP Reimplemented in \fBMPSCNNFullyConnected\fP\&. .SS "\- (void) reloadWeightsAndBiasesFromDataSource " CPU side reload\&. Reload the updated weights and biases from data provider into internal weights and bias buffers\&. Weights and biases gradients needed for update are obtained from \fBMPSCNNConvolutionGradientState\fP object\&. Data provider passed in init call is used for this purpose\&. .SS "\- (void) reloadWeightsAndBiasesWithCommandBuffer: (__nonnull id< MTLCommandBuffer >) commandBuffer(\fBMPSCNNConvolutionWeightsAndBiasesState\fP *__nonnull) state" GPU side reload\&. Reload the updated weights and biases from update buffer produced by application enqueued metal kernel into internal weights and biases buffer\&. Weights and biases gradients needed for update are obtained from \fBMPSCNNConvolutionGradientState\fP object's gradientForWeights and gradientForBiases metal buffer\&. .PP \fBParameters:\fP .RS 4 \fIcommandBuffer\fP Metal command buffer on which application update kernel was enqueued consuming \fBMPSCNNConvolutionGradientState\fP's gradientForWeights and gradientForBiases buffers and producing updateBuffer metal buffer\&. .br \fIstate\fP \fBMPSCNNConvolutionWeightsAndBiasesState\fP containing weights and biases buffers which have updated weights produced by application's update kernel\&. The state readcount will be decremented\&. .RE .PP .SS "\- (void) reloadWeightsAndBiasesWithDataSource: (__nonnull id< \fBMPSCNNConvolutionDataSource\fP >) dataSource" Deprecated\&. dataSource will be ignored\&. .SS "\- (\fBMPSCNNConvolutionGradientStateBatch\fP * __nullable) resultStateBatchForSourceImage: (\fBMPSImageBatch\fP *__nonnull) sourceImage(NSArray< \fBMPSStateBatch\fP * > *__nullable) sourceStates(\fBMPSImageBatch\fP *_Nonnull) destinationImage" .SS "\- (\fBMPSCNNConvolutionGradientState\fP * __nullable) resultStateForSourceImage: (\fBMPSImage\fP *__nonnull) sourceImage(NSArray< \fBMPSState\fP * > *__nullable) sourceStates(\fBMPSImage\fP *__nonnull) destinationImage" Allocate a MPCNNConvolutionGradientSState to hold the results from a -encodeBatchToCommandBuffer\&.\&.\&. operation .PP \fBParameters:\fP .RS 4 \fIsourceImage\fP The \fBMPSImage\fP consumed by the associated -encode call\&. .br \fIsourceStates\fP The list of MPSStates consumed by the associated -encode call, for a batch size of 1\&. .RE .PP \fBReturns:\fP .RS 4 The list of states produced by the -encode call for batch size of 1\&. -isResultStateReusedAcrossBatch returns YES for \fBMPSCNNConvolution\fP so same state is used across entire batch\&. State object is not reusasable across batches\&. .RE .PP .PP Reimplemented from \fBMPSCNNKernel\fP\&. .SS "\- (\fBMPSCNNConvolutionGradientStateBatch\fP * __nullable) temporaryResultStateBatchForCommandBuffer: (nonnull id< MTLCommandBuffer >) commandBuffer(\fBMPSImageBatch\fP *__nonnull) sourceImage(NSArray< \fBMPSStateBatch\fP * > *__nullable) sourceStates(\fBMPSImageBatch\fP *__nonnull) destinationImage" .PP Reimplemented from \fBMPSCNNKernel\fP\&. .SS "\- (\fBMPSCNNConvolutionGradientState\fP * __nullable) temporaryResultStateForCommandBuffer: (nonnull id< MTLCommandBuffer >) commandBuffer(\fBMPSImage\fP *__nonnull) sourceImage(NSArray< \fBMPSState\fP * > *__nullable) sourceStates(\fBMPSImage\fP *__nonnull) destinationImage" Allocate a temporary \fBMPSState\fP (subclass) to hold the results from a -encodeBatchToCommandBuffer\&.\&.\&. operation \fBA\fP graph may need to allocate storage up front before executing\&. This may be necessary to avoid using too much memory and to manage large batches\&. The function should allocate any \fBMPSState\fP objects that will be produced by an -encode call with the indicated sourceImages and sourceStates inputs\&. Though the states can be further adjusted in the ensuing -encode call, the states should be initialized with all important data and all MTLResource storage allocated\&. The data stored in the MTLResource need not be initialized, unless the ensuing -encode call expects it to be\&. .PP The MTLDevice used by the result is derived from the command buffer\&. The padding policy will be applied to the filter before this is called to give it the chance to configure any properties like \fBMPSCNNKernel\&.offset\fP\&. .PP CAUTION: The kernel must have all properties set to values that will ultimately be passed to the -encode call that writes to the state, before -resultStateForSourceImages:sourceStates:destinationImage: is called or behavior is undefined\&. Please note that -destinationImageDescriptorForSourceImages:sourceStates:destinationImage: will alter some of these properties automatically based on the padding policy\&. If you intend to call that to make the destination image, then you should call that before -resultStateForSourceImages:sourceStates:destinationImage:\&. This will ensure the properties used in the encode call and in the destination image creation match those used to configure the state\&. .PP The following order is recommended: .PP .nf // Configure MPSCNNKernel properties first kernel.edgeMode = MPSImageEdgeModeZero; kernel.destinationFeatureChannelOffset = 128; // concatenation without the copy ... // ALERT: will change MPSCNNKernel properties MPSImageDescriptor * d = [kernel destinationImageDescriptorForSourceImage: source sourceStates: states]; MPSTemporaryImage * dest = [MPSTemporaryImage temporaryImageWithCommandBuffer: cmdBuf imageDescriptor: d]; // Now that all properties are configured properly, we can make the result state // and call encode. MPSState * __nullable destState = [kernel temporaryResultStateForCommandBuffer: cmdBuf sourceImage: source sourceStates: states]; // This form of -encode will be declared by the MPSCNNKernel subclass [kernel encodeToCommandBuffer: cmdBuf sourceImage: source destinationState: destState destinationImage: dest ]; .fi .PP .PP Default: returns nil .PP \fBParameters:\fP .RS 4 \fIcommandBuffer\fP The command buffer to allocate the temporary storage against The state will only be valid on this command buffer\&. .br \fIsourceImage\fP The \fBMPSImage\fP consumed by the associated -encode call\&. .br \fIsourceStates\fP The list of MPSStates consumed by the associated -encode call, for a batch size of 1\&. .br \fIdestinationImage\fP The destination image for the encode call .RE .PP \fBReturns:\fP .RS 4 The list of states produced by the -encode call for batch size of 1\&. When the batch size is not 1, this function will be called repeatedly unless -isResultStateReusedAcrossBatch returns YES\&. If -isResultStateReusedAcrossBatch returns YES, then it will be called once per batch and the MPSStateBatch array will contain MPSStateBatch\&.length references to the same object\&. .RE .PP .PP Reimplemented from \fBMPSCNNKernel\fP\&. .SH "Property Documentation" .PP .SS "\- (\fBMPSNNConvolutionAccumulatorPrecisionOption\fP) accumulatorPrecisionOption\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" Precision of accumulator used in convolution\&. See \fBMPSNeuralNetworkTypes\&.h\fP for discussion\&. Default is MPSNNConvolutionAccumulatorPrecisionOptionFloat\&. .SS "\- (const \fBMPSCNNNeuron\fP* __nullable \fBMPSCNNNeuronType\fP float float float \fBMPSNNNeuronDescriptor\fP* __nullable NSUInteger) channelMultiplier\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" Channel multiplier\&. For convolution created with \fBMPSCNNDepthWiseConvolutionDescriptor\fP, it is the number of output feature channels for each input channel\&. See \fBMPSCNNDepthWiseConvolutionDescriptor\fP for more details\&. Default is 0 which means regular CNN convolution\&. .SS "\- dataSource\fC [read]\fP, \fC [nonatomic]\fP, \fC [retain]\fP" dataSource with which convolution object was created .SS "\- (const \fBMPSCNNNeuron\fP* __nullable \fBMPSCNNNeuronType\fP float float float \fBMPSNNNeuronDescriptor\fP* __nullable) fusedNeuronDescriptor\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" Fused neuron descritor passed in convolution descriptor for fusion with convolution\&. Please see class description for interpretation of c\&. .SS "\- groups\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" Number of groups input and output channels are divided into\&. .SS "\- inputFeatureChannels\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The number of feature channels per pixel in the input image\&. .SS "\- neuron\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" \fBMPSCNNNeuron\fP filter to be applied as part of convolution\&. Can be nil in wich case no neuron activation fuction is applied\&. .SS "\- (const \fBMPSCNNNeuron\fP* __nullable \fBMPSCNNNeuronType\fP float) neuronParameterA\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" Parameter 'a' for the neuron\&. Default: 1\&.0f Please see class description for interpretation of a\&. .SS "\- (const \fBMPSCNNNeuron\fP* __nullable \fBMPSCNNNeuronType\fP float float) neuronParameterB\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" Parameter 'b' for the neuron\&. Default: 1\&.0f Please see class description for interpretation of b\&. .SS "\- (const \fBMPSCNNNeuron\fP* __nullable \fBMPSCNNNeuronType\fP float float float) neuronParameterC\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" Parameter 'c' for the neuron\&. Default: 1\&.0f Please see class description for interpretation of c\&. .SS "\- (const \fBMPSCNNNeuron\fP* __nullable \fBMPSCNNNeuronType\fP) neuronType\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The type of neuron to append to the convolution Please see class description for a full list\&. Default is MPSCNNNeuronTypeNone\&. .SS "\- outputFeatureChannels\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The number of feature channels per pixel in the output image\&. .SS "\- subPixelScaleFactor\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" Sub pixel scale factor which was passed in as part of \fBMPSCNNConvolutionDescriptor\fP when creating this \fBMPSCNNConvolution\fP object\&. .SH "Author" .PP Generated automatically by Doxygen for MetalPerformanceShaders\&.framework from the source code\&.