.TH "MPSCNNBinaryKernel" 3 "Mon Jul 9 2018" "Version MetalPerformanceShaders-119.3" "MetalPerformanceShaders.framework" \" -*- nroff -*- .ad l .nh .SH NAME MPSCNNBinaryKernel .SH SYNOPSIS .br .PP .PP \fC#import \fP .PP Inherits \fBMPSKernel\fP\&. .PP Inherited by \fBMPSCNNArithmetic\fP, \fBMPSCNNGradientKernel\fP, and \fBMPSNNReduceBinary\fP\&. .SS "Instance Methods" .in +1c .ti -1c .RI "(nonnull instancetype) \- \fBinitWithDevice:\fP" .br .ti -1c .RI "(nullable instancetype) \- \fBinitWithCoder:device:\fP" .br .ti -1c .RI "(void) \- \fBencodeToCommandBuffer:primaryImage:secondaryImage:destinationImage:\fP" .br .ti -1c .RI "(void) \- \fBencodeBatchToCommandBuffer:primaryImages:secondaryImages:destinationImages:\fP" .br .ti -1c .RI "(\fBMPSImage\fP *__nonnull) \- \fBencodeToCommandBuffer:primaryImage:secondaryImage:\fP" .br .ti -1c .RI "(\fBMPSImageBatch\fP *__nonnull) \- \fBencodeBatchToCommandBuffer:primaryImages:secondaryImages:\fP" .br .ti -1c .RI "(\fBMPSImage\fP *__nonnull) \- \fBencodeToCommandBuffer:primaryImage:secondaryImage:destinationState:destinationStateIsTemporary:\fP" .br .ti -1c .RI "(\fBMPSImageBatch\fP *__nonnull) \- \fBencodeBatchToCommandBuffer:primaryImages:secondaryImages:destinationStates:destinationStateIsTemporary:\fP" .br .ti -1c .RI "(\fBMPSState\fP *__nullable) \- \fBresultStateForPrimaryImage:secondaryImage:sourceStates:destinationImage:\fP" .br .ti -1c .RI "(\fBMPSStateBatch\fP *__nullable) \- \fBresultStateBatchForPrimaryImage:secondaryImage:sourceStates:destinationImage:\fP" .br .ti -1c .RI "(\fBMPSState\fP *__nullable) \- \fBtemporaryResultStateForCommandBuffer:primaryImage:secondaryImage:sourceStates:destinationImage:\fP" .br .ti -1c .RI "(\fBMPSStateBatch\fP *__nullable) \- \fBtemporaryResultStateBatchForCommandBuffer:primaryImage:secondaryImage:sourceStates:destinationImage:\fP" .br .ti -1c .RI "(BOOL) \- \fBisResultStateReusedAcrossBatch\fP" .br .ti -1c .RI "(BOOL) \- \fBappendBatchBarrier\fP" .br .ti -1c .RI "(\fBMPSImageDescriptor\fP *__nonnull) \- \fBdestinationImageDescriptorForSourceImages:sourceStates:\fP" .br .in -1c .SS "Properties" .in +1c .ti -1c .RI "\fBMPSOffset\fP \fBprimaryOffset\fP" .br .ti -1c .RI "\fBMPSOffset\fP \fBsecondaryOffset\fP" .br .ti -1c .RI "MTLRegion \fBclipRect\fP" .br .ti -1c .RI "NSUInteger \fBdestinationFeatureChannelOffset\fP" .br .ti -1c .RI "NSUInteger \fBprimarySourceFeatureChannelOffset\fP" .br .ti -1c .RI "NSUInteger \fBsecondarySourceFeatureChannelOffset\fP" .br .ti -1c .RI "NSUInteger \fBprimarySourceFeatureChannelMaxCount\fP" .br .ti -1c .RI "NSUInteger \fBsecondarySourceFeatureChannelMaxCount\fP" .br .ti -1c .RI "\fBMPSImageEdgeMode\fP \fBprimaryEdgeMode\fP" .br .ti -1c .RI "\fBMPSImageEdgeMode\fP \fBsecondaryEdgeMode\fP" .br .ti -1c .RI "NSUInteger \fBprimaryKernelWidth\fP" .br .ti -1c .RI "NSUInteger \fBprimaryKernelHeight\fP" .br .ti -1c .RI "NSUInteger \fBsecondaryKernelWidth\fP" .br .ti -1c .RI "NSUInteger \fBsecondaryKernelHeight\fP" .br .ti -1c .RI "NSUInteger \fBprimaryStrideInPixelsX\fP" .br .ti -1c .RI "NSUInteger \fBprimaryStrideInPixelsY\fP" .br .ti -1c .RI "NSUInteger \fBsecondaryStrideInPixelsX\fP" .br .ti -1c .RI "NSUInteger \fBsecondaryStrideInPixelsY\fP" .br .ti -1c .RI "NSUInteger \fBprimaryDilationRateX\fP" .br .ti -1c .RI "NSUInteger \fBprimaryDilationRateY\fP" .br .ti -1c .RI "NSUInteger \fBsecondaryDilationRateX\fP" .br .ti -1c .RI "NSUInteger \fBsecondaryDilationRateY\fP" .br .ti -1c .RI "BOOL \fBisBackwards\fP" .br .ti -1c .RI "BOOL \fBisStateModified\fP" .br .ti -1c .RI "id< \fBMPSNNPadding\fP > \fBpadding\fP" .br .ti -1c .RI "id< MPSImageAllocator > \fBdestinationImageAllocator\fP" .br .in -1c .SS "Additional Inherited Members" .SH "Detailed Description" .PP This depends on Metal\&.framework Describes a convolution neural network kernel\&. \fBA\fP \fBMPSCNNKernel\fP consumes two MPSImages, primary and secondary, and produces one \fBMPSImage\fP\&. .SH "Method Documentation" .PP .SS "\- (BOOL) appendBatchBarrier " Returns YES if the filter must be run over the entire batch before its results may be considered complete The \fBMPSNNGraph\fP may split batches into sub-batches to save memory\&. However, some filters, like batch statistics calculations, need to operate over the entire batch to calculate a valid result, in this case, the mean and variance per channel over the set of images\&. .PP In such cases, the accumulated result is commonly stored in a \fBMPSState\fP containing a MTLBuffer\&. (MTLTextures may not be able to be read from and written to in the same filter on some devices\&.) -isResultStateReusedAcrossBatch is set to YES, so that the state is allocated once and passed in for each sub-batch and the filter accumulates its results into it, one sub-batch at a time\&. Note that sub-batches may frequently be as small as 1\&. .PP Default: NO .SS "\- (\fBMPSImageDescriptor\fP*__nonnull) destinationImageDescriptorForSourceImages: (NSArray< \fBMPSImage\fP * > *__nonnull) sourceImages(NSArray< \fBMPSState\fP * > *__nullable) sourceStates" Get a suggested destination image descriptor for a source image Your application is certainly free to pass in any destinationImage it likes to encodeToCommandBuffer:sourceImage:destinationImage, within reason\&. This is the basic design for iOS 10\&. This method is therefore not required\&. .PP However, calculating the \fBMPSImage\fP size and \fBMPSCNNBinaryKernel\fP properties for each filter can be tedious and complicated work, so this method is made available to automate the process\&. The application may modify the properties of the descriptor before a \fBMPSImage\fP is made from it, so long as the choice is sensible for the kernel in question\&. Please see individual kernel descriptions for restrictions\&. .PP The expected timeline for use is as follows: .PP 1) This method is called: a) The default MPS padding calculation is applied\&. It uses the MPSNNPaddingMethod of the \&.padding property to provide a consistent addressing scheme over the graph\&. It creates the \fBMPSImageDescriptor\fP and adjusts the \&.offset property of the MPSNNKernel\&. When using a \fBMPSNNGraph\fP, the padding is set using the \fBMPSNNFilterNode\fP as a proxy\&. .PP b) This method may be overridden by \fBMPSCNNBinaryKernel\fP subclass to achieve any customization appropriate to the object type\&. .PP c) Source states are then applied in order\&. These may modify the descriptor and may update other object properties\&. See: -destinationImageDescriptorForSourceImages:sourceStates: forKernel:suggestedDescriptor: This is the typical way in which MPS may attempt to influence the operation of its kernels\&. .PP d) If the \&.padding property has a custom padding policy method of the same name, it is called\&. Similarly, it may also adjust the descriptor and any \fBMPSCNNBinaryKernel\fP properties\&. This is the typical way in which your application may attempt to influence the operation of the MPS kernels\&. .PP 2) \fBA\fP result is returned from this method and the caller may further adjust the descriptor and kernel properties directly\&. .PP 3) The caller uses the descriptor to make a new \fBMPSImage\fP to use as the destination image for the -encode call in step 5\&. .PP 4) The caller calls -resultStateForSourceImage:sourceStates:destinationImage: to make any result states needed for the kernel\&. If there isn't one, it will return nil\&. \fBA\fP variant is available to return a temporary state instead\&. .PP 5) a -encode method is called to encode the kernel\&. .PP The entire process 1-5 is more simply achieved by just calling an -encode\&.\&.\&. method that returns a \fBMPSImage\fP out the left hand sid of the method\&. Simpler still, use the \fBMPSNNGraph\fP to coordinate the entire process from end to end\&. Opportunities to influence the process are of course reduced, as (2) is no longer possible with either method\&. Your application may opt to use the five step method if it requires greater customization as described, or if it would like to estimate storage in advance based on the sum of MPSImageDescriptors before processing a graph\&. Storage estimation is done by using the \fBMPSImageDescriptor\fP to create a \fBMPSImage\fP (without passing it a texture), and then call -resourceSize\&. As long as the \fBMPSImage\fP is not used in an encode call and the \&.texture property is not invoked, the underlying MTLTexture is not created\&. .PP No destination state or destination image is provided as an argument to this function because it is expected they will be made / configured after this is called\&. This method is expected to auto-configure important object properties that may be needed in the ensuing destination image and state creation steps\&. .PP \fBParameters:\fP .RS 4 \fIsourceImages\fP \fBA\fP array of source images that will be passed into the -encode call Since \fBMPSCNNBinaryKernel\fP is a binary kernel, it is an array of length 2\&. .br \fIsourceStates\fP An optional array of source states that will be passed into the -encode call .RE .PP \fBReturns:\fP .RS 4 an image descriptor allocated on the autorelease pool .RE .PP .SS "\- (\fBMPSImageBatch\fP * __nonnull) encodeBatchToCommandBuffer: (nonnull id< MTLCommandBuffer >) commandBuffer(\fBMPSImageBatch\fP *__nonnull) primaryImage(\fBMPSImageBatch\fP *__nonnull) secondaryImage" Encode a \fBMPSCNNKernel\fP into a command Buffer\&. Create textures to hold the results and return them\&. In the first iteration on this method, encodeBatchToCommandBuffer:sourceImage:destinationImage: some work was left for the developer to do in the form of correctly setting the offset property and sizing the result buffer\&. With the introduction of the padding policy (see padding property) the filter can do this work itself\&. If you would like to have some input into what sort of \fBMPSImage\fP (e\&.g\&. temporary vs\&. regular) or what size it is or where it is allocated, you may set the destinationImageAllocator to allocate the image yourself\&. .PP This method uses the \fBMPSNNPadding\fP padding property to figure out how to size the result image and to set the offset property\&. See discussion in \fBMPSNeuralNetworkTypes\&.h\fP\&. All images in a batch must have \fBMPSImage\&.numberOfImages\fP = 1\&. .PP \fBParameters:\fP .RS 4 \fIcommandBuffer\fP The command buffer .br \fIprimaryImage\fP \fBA\fP MPSImages to use as the primary source images for the filter\&. .br \fIsecondaryImage\fP \fBA\fP MPSImages to use as the secondary source images for the filter\&. .RE .PP \fBReturns:\fP .RS 4 \fBA\fP \fBMPSImage\fP or \fBMPSTemporaryImage\fP allocated per the destinationImageAllocator containing the output of the graph\&. The returned image will be automatically released when the command buffer completes\&. If you want to keep it around for longer, retain the image\&. (ARC will do this for you if you use it later\&.) .RE .PP .PP Reimplemented in \fBMPSCNNBatchNormalizationGradient\fP\&. .SS "\- (void) encodeBatchToCommandBuffer: (nonnull id< MTLCommandBuffer >) commandBuffer(\fBMPSImageBatch\fP *__nonnull) primaryImages(\fBMPSImageBatch\fP *__nonnull) secondaryImages(\fBMPSImageBatch\fP *__nonnull) destinationImages" Encode a \fBMPSCNNKernel\fP into a command Buffer\&. The operation shall proceed out-of-place\&. This is the older style of encode which reads the offset, doesn't change it, and ignores the padding method\&. Multiple images are processed concurrently\&. All images must have \fBMPSImage\&.numberOfImages\fP = 1\&. .PP \fBParameters:\fP .RS 4 \fIcommandBuffer\fP \fBA\fP valid MTLCommandBuffer to receive the encoded filter .br \fIprimaryImages\fP An array of \fBMPSImage\fP objects containing the primary source images\&. .br \fIsecondaryImages\fP An array \fBMPSImage\fP objects containing the secondary source images\&. .br \fIdestinationImages\fP An array of \fBMPSImage\fP objects to contain the result images\&. destinationImages may not alias primarySourceImages or secondarySourceImages in any manner\&. .RE .PP .PP Reimplemented in \fBMPSCNNBatchNormalizationGradient\fP\&. .SS "\- (\fBMPSImageBatch\fP * __nonnull) encodeBatchToCommandBuffer: (nonnull id< MTLCommandBuffer >) commandBuffer(\fBMPSImageBatch\fP *__nonnull) primaryImages(\fBMPSImageBatch\fP *__nonnull) secondaryImages(__autoreleasing \fBMPSStateBatch\fP *__nullable *__nonnull) outState(BOOL) isTemporary" Encode a \fBMPSCNNKernel\fP into a command Buffer\&. Create a texture and state to hold the results and return them\&. In the first iteration on this method, encodeToCommandBuffer:sourceImage:destinationState:destinationImage: some work was left for the developer to do in the form of correctly setting the offset property and sizing the result buffer\&. With the introduction of the padding policy (see padding property) the filter can do this work itself\&. If you would like to have some input into what sort of \fBMPSImage\fP (e\&.g\&. temporary vs\&. regular) or what size it is or where it is allocated, you may set the destinationImageAllocator to allocate the image yourself\&. .PP This method uses the \fBMPSNNPadding\fP padding property to figure out how to size the result image and to set the offset property\&. See discussion in \fBMPSNeuralNetworkTypes\&.h\fP\&. All images in a batch must have \fBMPSImage\&.numberOfImages\fP = 1\&. .PP \fBParameters:\fP .RS 4 \fIcommandBuffer\fP The command buffer .br \fIprimaryImages\fP \fBA\fP \fBMPSImage\fP to use as the source images for the filter\&. .br \fIsecondaryImages\fP \fBA\fP \fBMPSImage\fP to use as the source images for the filter\&. .br \fIoutState\fP \fBA\fP new state object is returned here\&. .br \fIisTemporary\fP YES if the outState should be a temporary object .RE .PP \fBReturns:\fP .RS 4 \fBA\fP \fBMPSImage\fP or \fBMPSTemporaryImage\fP allocated per the destinationImageAllocator containing the output of the graph\&. The offset property will be adjusted to reflect the offset used during the encode\&. The returned image will be automatically released when the command buffer completes\&. If you want to keep it around for longer, retain the image\&. (ARC will do this for you if you use it later\&.) .RE .PP .SS "\- (\fBMPSImage\fP * __nonnull) encodeToCommandBuffer: (nonnull id< MTLCommandBuffer >) commandBuffer(\fBMPSImage\fP *__nonnull) primaryImage(\fBMPSImage\fP *__nonnull) secondaryImage" Encode a \fBMPSCNNKernel\fP into a command Buffer\&. Create a texture to hold the result and return it\&. In the first iteration on this method, encodeToCommandBuffer:sourceImage:destinationImage: some work was left for the developer to do in the form of correctly setting the offset property and sizing the result buffer\&. With the introduction of the padding policy (see padding property) the filter can do this work itself\&. If you would like to have some input into what sort of \fBMPSImage\fP (e\&.g\&. temporary vs\&. regular) or what size it is or where it is allocated, you may set the destinationImageAllocator to allocate the image yourself\&. .PP This method uses the \fBMPSNNPadding\fP padding property to figure out how to size the result image and to set the offset property\&. See discussion in \fBMPSNeuralNetworkTypes\&.h\fP\&. .PP \fBParameters:\fP .RS 4 \fIcommandBuffer\fP The command buffer .br \fIprimaryImage\fP \fBA\fP MPSImages to use as the primary source images for the filter\&. .br \fIsecondaryImage\fP \fBA\fP MPSImages to use as the secondary source images for the filter\&. .RE .PP \fBReturns:\fP .RS 4 \fBA\fP \fBMPSImage\fP or \fBMPSTemporaryImage\fP allocated per the destinationImageAllocator containing the output of the graph\&. The returned image will be automatically released when the command buffer completes\&. If you want to keep it around for longer, retain the image\&. (ARC will do this for you if you use it later\&.) .RE .PP .PP Reimplemented in \fBMPSCNNBatchNormalizationGradient\fP\&. .SS "\- (void) encodeToCommandBuffer: (nonnull id< MTLCommandBuffer >) commandBuffer(\fBMPSImage\fP *__nonnull) primaryImage(\fBMPSImage\fP *__nonnull) secondaryImage(\fBMPSImage\fP *__nonnull) destinationImage" Encode a \fBMPSCNNKernel\fP into a command Buffer\&. The operation shall proceed out-of-place\&. This is the older style of encode which reads the offset, doesn't change it, and ignores the padding method\&. .PP \fBParameters:\fP .RS 4 \fIcommandBuffer\fP \fBA\fP valid MTLCommandBuffer to receive the encoded filter .br \fIprimaryImage\fP \fBA\fP valid \fBMPSImage\fP object containing the primary source image\&. .br \fIsecondaryImage\fP \fBA\fP valid \fBMPSImage\fP object containing the secondary source image\&. .br \fIdestinationImage\fP \fBA\fP valid \fBMPSImage\fP to be overwritten by result image\&. destinationImage may not alias primarySourceImage or secondarySourceImage\&. .RE .PP .PP Reimplemented in \fBMPSCNNBatchNormalizationGradient\fP\&. .SS "\- (\fBMPSImage\fP * __nonnull) encodeToCommandBuffer: (nonnull id< MTLCommandBuffer >) commandBuffer(\fBMPSImage\fP *__nonnull) primaryImage(\fBMPSImage\fP *__nonnull) secondaryImage(__autoreleasing \fBMPSState\fP *__nullable *__nonnull) outState(BOOL) isTemporary" Encode a \fBMPSCNNKernel\fP into a command Buffer\&. Create a texture and state to hold the results and return them\&. In the first iteration on this method, encodeToCommandBuffer:sourceImage:destinationState:destinationImage: some work was left for the developer to do in the form of correctly setting the offset property and sizing the result buffer\&. With the introduction of the padding policy (see padding property) the filter can do this work itself\&. If you would like to have some input into what sort of \fBMPSImage\fP (e\&.g\&. temporary vs\&. regular) or what size it is or where it is allocated, you may set the destinationImageAllocator to allocate the image yourself\&. .PP This method uses the \fBMPSNNPadding\fP padding property to figure out how to size the result image and to set the offset property\&. See discussion in \fBMPSNeuralNetworkTypes\&.h\fP\&. All images in a batch must have \fBMPSImage\&.numberOfImages\fP = 1\&. .PP \fBParameters:\fP .RS 4 \fIcommandBuffer\fP The command buffer .br \fIprimaryImage\fP \fBA\fP \fBMPSImage\fP to use as the source images for the filter\&. .br \fIsecondaryImage\fP \fBA\fP \fBMPSImage\fP to use as the source images for the filter\&. .br \fIoutState\fP The address of location to write the pointer to the result state of the operation .br \fIisTemporary\fP YES if the outState should be a temporary object .RE .PP \fBReturns:\fP .RS 4 \fBA\fP \fBMPSImage\fP or \fBMPSTemporaryImage\fP allocated per the destinationImageAllocator containing the output of the graph\&. The offset property will be adjusted to reflect the offset used during the encode\&. The returned image will be automatically released when the command buffer completes\&. If you want to keep it around for longer, retain the image\&. (ARC will do this for you if you use it later\&.) .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 \fBMPSKernel\fP\&. .PP Reimplemented in \fBMPSCNNConvolutionGradient\fP, \fBMPSCNNFullyConnectedGradient\fP, \fBMPSCNNGradientKernel\fP, \fBMPSCNNPoolingAverageGradient\fP, \fBMPSCNNPoolingMaxGradient\fP, \fBMPSCNNPoolingL2NormGradient\fP, \fBMPSCNNDilatedPoolingMaxGradient\fP, \fBMPSCNNSoftMaxGradient\fP, \fBMPSCNNLogSoftMaxGradient\fP, \fBMPSCNNCrossChannelNormalizationGradient\fP, \fBMPSCNNPoolingGradient\fP, \fBMPSCNNLocalContrastNormalizationGradient\fP, \fBMPSCNNBatchNormalizationGradient\fP, \fBMPSCNNBatchNormalizationStatisticsGradient\fP, \fBMPSCNNNeuronGradient\fP, \fBMPSCNNDropoutGradient\fP, and \fBMPSCNNSpatialNormalizationGradient\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 \fBMPSKernel\fP\&. .PP Reimplemented in \fBMPSCNNConvolutionGradient\fP, \fBMPSCNNFullyConnectedGradient\fP, \fBMPSCNNGradientKernel\fP, \fBMPSCNNSoftMaxGradient\fP, \fBMPSCNNLogSoftMaxGradient\fP, \fBMPSCNNPoolingGradient\fP, \fBMPSNNReduceFeatureChannelsAndWeightsSum\fP, \fBMPSCNNArithmeticGradient\fP, \fBMPSNNReduceBinary\fP, \fBMPSNNReduceFeatureChannelsAndWeightsMean\fP, \fBMPSCNNNeuronGradient\fP, \fBMPSCNNUpsamplingGradient\fP, \fBMPSCNNDropoutGradient\fP, \fBMPSCNNArithmetic\fP, \fBMPSCNNAdd\fP, \fBMPSCNNSubtract\fP, \fBMPSCNNMultiply\fP, and \fBMPSCNNDivide\fP\&. .SS "\- (BOOL) isResultStateReusedAcrossBatch " Returns YES if the same state is used for every operation in a batch If NO, then each image in a MPSImageBatch will need a corresponding (and different) state to go with it\&. Set to YES to avoid allocating redundant state in the case when the same state is used all the time\&. Default: NO .SS "\- (\fBMPSStateBatch\fP * __nullable) resultStateBatchForPrimaryImage: (\fBMPSImageBatch\fP *__nonnull) primaryImage(\fBMPSImageBatch\fP *__nonnull) secondaryImage(NSArray< \fBMPSStateBatch\fP * > *__nullable) sourceStates(\fBMPSImageBatch\fP *__nonnull) destinationImage" .SS "\- (\fBMPSState\fP * __nullable) resultStateForPrimaryImage: (\fBMPSImage\fP *__nonnull) primaryImage(\fBMPSImage\fP *__nonnull) secondaryImage(NSArray< \fBMPSState\fP * > *__nullable) sourceStates(\fBMPSImage\fP *__nonnull) destinationImage" Allocate a \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 a \fBMPSState\fP object (if any) 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 source image\&. 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 result state should be made after the kernel properties are configured for the -encode call that will write to the state, and after -destinationImageDescriptorForSourceImages:sourceStates: is called (if it is called)\&. Otherwise, behavior is undefined\&. Please see the description of -[\fBMPSCNNKernel\fP resultStateForSourceImage:sourceStates:destinationImage:] for more\&. .PP Default: returns nil .PP \fBParameters:\fP .RS 4 \fIprimaryImage\fP The \fBMPSImage\fP consumed by the associated -encode call\&. .br \fIsecondaryImage\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\&. 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 .SS "\- (\fBMPSStateBatch\fP * __nullable) temporaryResultStateBatchForCommandBuffer: (nonnull id< MTLCommandBuffer >) commandBuffer(\fBMPSImageBatch\fP *__nonnull) primaryImage(\fBMPSImageBatch\fP *__nonnull) secondaryImage(NSArray< \fBMPSStateBatch\fP * > *__nullable) sourceStates(\fBMPSImageBatch\fP *__nonnull) destinationImage" .SS "\- (\fBMPSState\fP * __nullable) temporaryResultStateForCommandBuffer: (nonnull id< MTLCommandBuffer >) commandBuffer(\fBMPSImage\fP *__nonnull) primaryImage(\fBMPSImage\fP *__nonnull) secondaryImage(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 result state should be made after the kernel properties are configured for the -encode call that will write to the state, and after -destinationImageDescriptorForSourceImages:sourceStates: is called (if it is called)\&. Otherwise, behavior is undefined\&. Please see the description of -[\fBMPSCNNKernel\fP resultStateForSourceImage:sourceStates:destinationImage] for more\&. .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 \fIprimaryImage\fP The \fBMPSImage\fP consumed by the associated -encode call\&. .br \fIsecondaryImage\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\&. 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 .SH "Property Documentation" .PP .SS "\- clipRect\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" An optional clip rectangle to use when writing data\&. Only the pixels in the rectangle will be overwritten\&. \fBA\fP MTLRegion that indicates which part of the destination to overwrite\&. If the clipRect does not lie completely within the destination image, the intersection between clip rectangle and destination bounds is used\&. Default: MPSRectNoClip (\fBMPSKernel::MPSRectNoClip\fP) indicating the entire image\&. clipRect\&.origin\&.z is the index of starting destination image in batch processing mode\&. clipRect\&.size\&.depth is the number of images to process in batch processing mode\&. .PP See Also: \fBMPSKernel clipRect\fP .SS "\- destinationFeatureChannelOffset\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The number of channels in the destination \fBMPSImage\fP to skip before writing output\&. This is the starting offset into the destination image in the feature channel dimension at which destination data is written\&. This allows an application to pass a subset of all the channels in \fBMPSImage\fP as output of \fBMPSKernel\fP\&. E\&.g\&. Suppose \fBMPSImage\fP has 24 channels and a \fBMPSKernel\fP outputs 8 channels\&. If we want channels 8 to 15 of this \fBMPSImage\fP to be used as output, we can set destinationFeatureChannelOffset = 8\&. Note that this offset applies independently to each image when the \fBMPSImage\fP is a container for multiple images and the \fBMPSCNNKernel\fP is processing multiple images (clipRect\&.size\&.depth > 1)\&. The default value is 0 and any value specifed shall be a multiple of 4\&. If \fBMPSKernel\fP outputs N channels, destination image MUST have at least destinationFeatureChannelOffset + N channels\&. Using a destination image with insufficient number of feature channels result in an error\&. E\&.g\&. if the \fBMPSCNNConvolution\fP outputs 32 channels, and destination has 64 channels, then it is an error to set destinationFeatureChannelOffset > 32\&. .SS "\- (id) destinationImageAllocator\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [retain]\fP" Method to allocate the result image for -encodeToCommandBuffer:sourceImage: Default: \fBdefaultAllocator (MPSTemporaryImage)\fP .SS "\- isBackwards\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" YES if the filter operates backwards\&. This influences how strideInPixelsX/Y should be interpreted\&. .SS "\- (BOOL) isStateModified\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" Returns true if the -encode call modifies the state object it accepts\&. .SS "\- padding\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The padding method used by the filter This influences how strideInPixelsX/Y should be interpreted\&. Default: MPSNNPaddingMethodAlignCentered | MPSNNPaddingMethodAddRemainderToTopLeft | MPSNNPaddingMethodSizeSame Some object types (e\&.g\&. \fBMPSCNNFullyConnected\fP) may override this default with something appropriate to its operation\&. .SS "\- (NSUInteger) primaryDilationRateX\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" .SS "\- (NSUInteger) primaryDilationRateY\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" .SS "\- primaryEdgeMode\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The MPSImageEdgeMode to use when texture reads stray off the edge of the primary source image Most \fBMPSKernel\fP objects can read off the edge of the source image\&. This can happen because of a negative offset property, because the offset + clipRect\&.size is larger than the source image or because the filter looks at neighboring pixels, such as a Convolution filter\&. Default: MPSImageEdgeModeZero\&. .PP See Also: \fBMPSKernelEdgeMode\fP .SS "\- primaryKernelHeight\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The height of the \fBMPSCNNBinaryKernel\fP filter window This is the vertical diameter of the region read by the filter for each result pixel\&. If the \fBMPSCNNKernel\fP does not have a filter window, then 1 will be returned\&. .SS "\- primaryKernelWidth\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The width of the \fBMPSCNNBinaryKernel\fP filter window This is the horizontal diameter of the region read by the filter for each result pixel\&. If the \fBMPSCNNKernel\fP does not have a filter window, then 1 will be returned\&. .SS "\- primaryOffset\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The position of the destination clip rectangle origin relative to the primary source buffer\&. The offset is defined to be the position of clipRect\&.origin in source coordinates\&. Default: {0,0,0}, indicating that the top left corners of the clipRect and primary source image align\&. offset\&.z is the index of starting source image in batch processing mode\&. .PP See Also: \fBsubsubsection_mpsoffset\fP .SS "\- primarySourceFeatureChannelMaxCount\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The maximum number of channels in the primary source \fBMPSImage\fP to use Most filters can insert a slice operation into the filter for free\&. Use this to limit the size of the feature channel slice taken from the input image\&. If the value is too large, it is truncated to be the remaining size in the image after the sourceFeatureChannelOffset is taken into account\&. Default: ULONG_MAX .SS "\- primarySourceFeatureChannelOffset\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The number of channels in the primary source \fBMPSImage\fP to skip before reading the input\&. This is the starting offset into the primary source image in the feature channel dimension at which source data is read\&. Unit: feature channels This allows an application to read a subset of all the channels in \fBMPSImage\fP as input of \fBMPSKernel\fP\&. E\&.g\&. Suppose \fBMPSImage\fP has 24 channels and a \fBMPSKernel\fP needs to read 8 channels\&. If we want channels 8 to 15 of this \fBMPSImage\fP to be used as input, we can set primarySourceFeatureChannelOffset = 8\&. Note that this offset applies independently to each image when the \fBMPSImage\fP is a container for multiple images and the \fBMPSCNNKernel\fP is processing multiple images (clipRect\&.size\&.depth > 1)\&. The default value is 0 and any value specifed shall be a multiple of 4\&. If \fBMPSKernel\fP inputs N channels, the source image MUST have at least primarySourceFeatureChannelOffset + N channels\&. Using a source image with insufficient number of feature channels will result in an error\&. E\&.g\&. if the \fBMPSCNNConvolution\fP inputs 32 channels, and the source has 64 channels, then it is an error to set primarySourceFeatureChannelOffset > 32\&. .SS "\- primaryStrideInPixelsX\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The downsampling (or upsampling if a backwards filter) factor in the horizontal dimension for the primary source image If the filter does not do up or downsampling, 1 is returned\&. .SS "\- primaryStrideInPixelsY\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The downsampling (or upsampling if a backwards filter) factor in the vertical dimension for the primary source image If the filter does not do up or downsampling, 1 is returned\&. .SS "\- (NSUInteger) secondaryDilationRateX\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" .SS "\- (NSUInteger) secondaryDilationRateY\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" .SS "\- secondaryEdgeMode\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The MPSImageEdgeMode to use when texture reads stray off the edge of the primary source image Most \fBMPSKernel\fP objects can read off the edge of the source image\&. This can happen because of a negative offset property, because the offset + clipRect\&.size is larger than the source image or because the filter looks at neighboring pixels, such as a Convolution filter\&. Default: MPSImageEdgeModeZero\&. .PP See Also: \fBMPSKernelEdgeMode\fP .SS "\- (NSUInteger) secondaryKernelHeight\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" .SS "\- (NSUInteger) secondaryKernelWidth\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" .SS "\- secondaryOffset\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The position of the destination clip rectangle origin relative to the secondary source buffer\&. The offset is defined to be the position of clipRect\&.origin in source coordinates\&. Default: {0,0,0}, indicating that the top left corners of the clipRect and secondary source image align\&. offset\&.z is the index of starting source image in batch processing mode\&. .PP See Also: \fBsubsubsection_mpsoffset\fP .SS "\- secondarySourceFeatureChannelMaxCount\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The maximum number of channels in the secondary source \fBMPSImage\fP to use Most filters can insert a slice operation into the filter for free\&. Use this to limit the size of the feature channel slice taken from the input image\&. If the value is too large, it is truncated to be the remaining size in the image after the sourceFeatureChannelOffset is taken into account\&. Default: ULONG_MAX .SS "\- secondarySourceFeatureChannelOffset\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The number of channels in the secondary source \fBMPSImage\fP to skip before reading the input\&. This is the starting offset into the secondary source image in the feature channel dimension at which source data is read\&. Unit: feature channels This allows an application to read a subset of all the channels in \fBMPSImage\fP as input of \fBMPSKernel\fP\&. E\&.g\&. Suppose \fBMPSImage\fP has 24 channels and a \fBMPSKernel\fP needs to read 8 channels\&. If we want channels 8 to 15 of this \fBMPSImage\fP to be used as input, we can set secondarySourceFeatureChannelOffset = 8\&. Note that this offset applies independently to each image when the \fBMPSImage\fP is a container for multiple images and the \fBMPSCNNKernel\fP is processing multiple images (clipRect\&.size\&.depth > 1)\&. The default value is 0 and any value specifed shall be a multiple of 4\&. If \fBMPSKernel\fP inputs N channels, the source image MUST have at least primarySourceFeatureChannelOffset + N channels\&. Using a source image with insufficient number of feature channels will result in an error\&. E\&.g\&. if the \fBMPSCNNConvolution\fP inputs 32 channels, and the source has 64 channels, then it is an error to set primarySourceFeatureChannelOffset > 32\&. .SS "\- secondaryStrideInPixelsX\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The downsampling (or upsampling if a backwards filter) factor in the horizontal dimension for the secondary source image If the filter does not do up or downsampling, 1 is returned\&. .SS "\- secondaryStrideInPixelsY\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP" The downsampling (or upsampling if a backwards filter) factor in the vertical dimension for the secondary source image If the filter does not do up or downsampling, 1 is returned\&. .SH "Author" .PP Generated automatically by Doxygen for MetalPerformanceShaders\&.framework from the source code\&.