NAME

MPSImageConvolution

SYNOPSIS

#import <MPSImageConvolution.h>

Inherits MPSUnaryImageKernel.

Instance Methods

(nonnull instancetype) - initWithDevice:kernelWidth:kernelHeight:weights:
(nullable instancetype) - initWithCoder:device:

Properties

NSUInteger kernelHeight
NSUInteger kernelWidth
float bias

Detailed Description

MPSImageConvolution.h MetalPerformanceShaders

Copyright:

MetalPerformanceShaders Convolution Filters

The MPSImageConvolution convolves an image with given filter of odd width and height. The center of the kernel aligns with the MPSImageConvolution.offset. That is, the position of the top left corner of the area covered by the kernel is given by MPSImageConvolution.offset - {kernel_width>>1, kernel_height>>1, 0}

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.

If there are multiple channels in the source image, each channel is processed independently.

Separable convolution filters may perform better when done in two passes. A 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:

-1      0       1
-2      0       2
-1      0       1

can be separated into the product of two vectors:

1
2      x    [-1  0   1]
1

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.

Method Documentation

- (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 MPSUnaryImageKernel.

- (nonnull instancetype) initWithDevice: (nonnull id< MTLDevice >) device(NSUInteger) kernelWidth(NSUInteger) kernelHeight(const float *__nonnull) kernelWeights

Initialize a convolution filter

Parameters:

device The device the filter will run on
kernelWidth the width of the kernel
kernelHeight the height of the kernel
kernelWeights A pointer to an array of kernelWidth * kernelHeight values to be used as the kernel. These are in row major order.

Returns:

A valid MPSImageConvolution object or nil, if failure.

Property Documentation

- bias [read], [write], [nonatomic], [assign]

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.

Default value is 0.0f.

- kernelHeight [read], [nonatomic], [assign]

The height of the filter window. Must be an odd number.

- kernelWidth [read], [nonatomic], [assign]

The width of the filter window. Must be an odd number.

Author

Generated automatically by Doxygen for MetalPerformanceShaders.framework from the source code.