MPSImageConvolution(3)

NAME
MPSImageConvolution -

SYNOPSIS

#import <MPSImageConvolution.h>

Inherits MPSUnaryImageKernel.

  Instance Methods
(nonnull instancetype) - initWithDevice:kernelWidth:kernelHeight:weights:

  Properties
NSUInteger kernelHeight
NSUInteger kernelWidth
float bias

  Additional Inherited Members

Detailed Description

MPSImageConvolution.h MetalPerformanceShaders

Copyright:
    Copyright (c) 2015 Apple Inc. All rights reserved.

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

  - (nonnull instancetype) initWithDevice: (nonnull id< MTLDevice >) device(NSUInteger) kernelWidth(NSUInteger) kernelHeight(const float *__nonnull) NS_DESIGNATED_INITIALIZER
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.