.TH "MPSImageConvolution" 3 "Mon Jul 9 2018" "Version MetalPerformanceShaders-119.3" "MetalPerformanceShaders.framework" \" -*- nroff -*-
.ad l
.nh
.SH NAME
MPSImageConvolution
.SH SYNOPSIS
.br
.PP
.PP
\fC#import <MPSImageConvolution\&.h>\fP
.PP
Inherits \fBMPSUnaryImageKernel\fP\&.
.SS "Instance Methods"

.in +1c
.ti -1c
.RI "(nonnull instancetype) \- \fBinitWithDevice:kernelWidth:kernelHeight:weights:\fP"
.br
.ti -1c
.RI "(nullable instancetype) \- \fBinitWithCoder:device:\fP"
.br
.in -1c
.SS "Properties"

.in +1c
.ti -1c
.RI "NSUInteger \fBkernelHeight\fP"
.br
.ti -1c
.RI "NSUInteger \fBkernelWidth\fP"
.br
.ti -1c
.RI "float \fBbias\fP"
.br
.in -1c
.SS "Additional Inherited Members"
.SH "Detailed Description"
.PP 
\fBMPSImageConvolution\&.h\fP  MetalPerformanceShaders 
.PP
\fBCopyright:\fP
.RS 4
Copyright (c) 2015 Apple Inc\&. All rights reserved\&.
.RE
.PP
MetalPerformanceShaders Convolution Filters
.PP
The \fBMPSImageConvolution\fP convolves an image with given filter of odd width and height\&. The center of the kernel aligns with the \fBMPSImageConvolution\&.offset\fP\&. That is, the position of the top left corner of the area covered by the kernel is given by \fBMPSImageConvolution\&.offset\fP - {kernel_width>>1, kernel_height>>1, 0}
.PP
Optimized cases include 3x3,5x5,7x7,9x9,11x11, 1xN and Nx1\&. If a convolution kernel does not fall into one of these cases but is a rank-1 matrix (a\&.k\&.a\&. separable) then it will fall on an optimzied separable path\&. Other convolutions will execute with full MxN complexity\&.
.PP
If there are multiple channels in the source image, each channel is processed independently\&.
.PP
Separable convolution filters may perform better when done in two passes\&. \fBA\fP convolution filter is separable if the ratio of filter values between all rows is constant over the whole row\&. For example, this edge detection filter: 
.PP
.nf
-1      0       1
-2      0       2
-1      0       1

.fi
.PP
 can be separated into the product of two vectors: 
.PP
.nf
1
2      x    [-1  0   1]
1

.fi
.PP
 and consequently can be done as two, one-dimensional convolution passes back to back on the same image\&. In this way, the number of multiplies (ignoring the fact that we could skip zeros here) is reduced from 3*3=9 to 3+3 = 6\&. There are similar savings for addition\&. For large filters, the savings can be profound\&. 
.SH "Method Documentation"
.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 \fBMPSUnaryImageKernel\fP\&.
.SS "\- (nonnull instancetype) \fBinitWithDevice:\fP (nonnull id< MTLDevice >) device(NSUInteger) kernelWidth(NSUInteger) kernelHeight(const float *__nonnull) kernelWeights"
Initialize a convolution filter 
.PP
\fBParameters:\fP
.RS 4
\fIdevice\fP The device the filter will run on 
.br
\fIkernelWidth\fP the width of the kernel 
.br
\fIkernelHeight\fP the height of the kernel 
.br
\fIkernelWeights\fP \fBA\fP pointer to an array of kernelWidth * kernelHeight values to be used as the kernel\&. These are in row major order\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
\fBA\fP valid \fBMPSImageConvolution\fP object or nil, if failure\&. 
.RE
.PP

.SH "Property Documentation"
.PP 
.SS "\- bias\fC [read]\fP, \fC [write]\fP, \fC [nonatomic]\fP, \fC [assign]\fP"
The bias is a value to be added to convolved pixel before it is converted back to the storage format\&. It can be used to convert negative values into a representable range for a unsigned MTLPixelFormat\&. For example, many edge detection filters produce results in the range [-k,k]\&. By scaling the filter weights by 0\&.5/k and adding 0\&.5, the results will be in range [0,1] suitable for use with unorm formats\&. It can be used in combination with renormalization of the filter weights to do video ranging as part of the convolution effect\&. It can also just be used to increase the brightness of the image\&.
.PP
Default value is 0\&.0f\&. 
.SS "\- kernelHeight\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP"
The height of the filter window\&. Must be an odd number\&. 
.SS "\- kernelWidth\fC [read]\fP, \fC [nonatomic]\fP, \fC [assign]\fP"
The width of the filter window\&. Must be an odd number\&. 

.SH "Author"
.PP 
Generated automatically by Doxygen for MetalPerformanceShaders\&.framework from the source code\&.