--- title: Image Filters framework: metalperformanceshaders role: collectionGroup role_heading: API Collection path: metalperformanceshaders/image-filters --- # Image Filters Apply high-performance filters to, and extract statistical and histogram data from images. ## Overview Overview The MPSUnaryImageKernel and MPSBinaryImageKernel base classes define several properties common to all image kernels: | | | In-Place Operation Some kernels can operate in place. This means that the same texture is used to hold both the input image and the result image. Operating in place is a great way to save memory, time, and energy. You can perform an in-place operation by using the encode(commandBuffer:inPlaceTexture:fallbackCopyAllocator:) method. Unfortunately, it is not always possible for kernels to run in place. Whether a particular kernel can operate in place can vary according to the hardware it is running on, the OS version, and the parameters and properties passed to it. You may not assume that because a kernel works in place today on a particular device that it will do so in the future. To simplify error handling with failed in-place operation, the encode(commandBuffer:inPlaceTexture:fallbackCopyAllocator:) method takes an optional MPSCopyAllocator object. It is used to create a new texture when in-place operation is not possible so as to allow the operation to proceed out of place in a reliable fashion instead. When this happens, the input texture is released and replaced with a new texture. To make use of the feature, you will need to write a copy allocator block. The following code listing shows a minimal copy allocator implementation. For more information, see the MPSCopyAllocator reference. Listing 1. Minimal MPSCopyAllocator Implementation Supported Pixel Formats for Image Kernels All Metal Performance Shaders image kernels support source and destination textures with the following ordinary and packed pixel formats: Some compressed pixel formats can be used as source textures. They cannot be used as destination textures because they cannot be written to. Metal Performance Shaders image kernels support the following compression families: PVRTC EAC/ETC ASTC The following Metal Performance Shaders image kernels also support source and destination textures with ordinary signed and unsigned integer pixel formats: MPSImageTranspose MPSImageIntegral MPSImageIntegralOfSquares The ordinary signed and unsigned integer pixel formats supported by these image kernels: For more information on pixel formats, see MTLPixelFormat and Pixel Format Capabilities. Sample Code Listing 2. Metal Performance Shaders Sample Code #import // Blur the input texture (in place if possible) on MTLCommandQueue q, and return the new texture. // This is a trivial example. It is not necessary or necessarily advised to enqueue a MPSKernel on // its own MTLCommandBuffer or using its own MTLComputeCommandEncoder. Group work together. // Here we assume that you have already gotten a MTLDevice using MTLCreateSystemDefaultDevice() or // MTLCopyAllDevices(), used it to create a MTLCommandQueue with MTLDevice.newCommandQueue, and // similarly made textures with the device as needed. void MyBlurTextureInPlace(id __strong *inTexture, float blurRadius, id q) { // Create the usual Metal objects. // MPS does not need a dedicated MTLCommandBuffer or MTLComputeCommandEncoder. // This is a trivial example. You should reuse the MTL objects you already have, if you have them. id device = q.device; id buffer = [q commandBuffer]; // Create a MPS filter. MPSImageGaussianBlur *blur = [[MPSImageGaussianBlur alloc] initWithDevice: device]; if( nil == blur ) MyHandleError(kOutOfMemory); blur.sigma = blurRadius; // Defaults are okay here for other MPSKernel properties (clipRect, origin, edgeMode). // Attempt to do the work in place. Since we provided a copyAllocator as an out-of-place // fallback, we don’t need to check to see if it succeeded or not. // See the "Minimal MPSCopyAllocator Implementation" code listing for a sample myAllocator. [blur encodeToCommandBuffer: commandBuffer inPlaceTexture: inTexture copyAllocator: myAllocator]; [blur release]; // The usual Metal enqueue process. [buffer waitUntilCompleted]; return result; } ## Topics ### Morphological Image Filters - [MPSImageAreaMax](metalperformanceshaders/mpsimageareamax.md) - [MPSImageDilate](metalperformanceshaders/mpsimagedilate.md) - [MPSImageAreaMin](metalperformanceshaders/mpsimageareamin.md) - [MPSImageErode](metalperformanceshaders/mpsimageerode.md) ### Convolution Image Filters - [MPSImageConvolution](metalperformanceshaders/mpsimageconvolution.md) - [MPSImageMedian](metalperformanceshaders/mpsimagemedian.md) - [MPSImageBox](metalperformanceshaders/mpsimagebox.md) - [MPSImageTent](metalperformanceshaders/mpsimagetent.md) - [MPSImageGaussianBlur](metalperformanceshaders/mpsimagegaussianblur.md) - [MPSImageGaussianPyramid](metalperformanceshaders/mpsimagegaussianpyramid.md) - [MPSImageSobel](metalperformanceshaders/mpsimagesobel.md) - [MPSImageLaplacian](metalperformanceshaders/mpsimagelaplacian.md) - [MPSImageLaplacianPyramid](metalperformanceshaders/mpsimagelaplacianpyramid.md) - [MPSImageLaplacianPyramidAdd](metalperformanceshaders/mpsimagelaplacianpyramidadd.md) - [MPSImageLaplacianPyramidSubtract](metalperformanceshaders/mpsimagelaplacianpyramidsubtract.md) - [MPSImagePyramid](metalperformanceshaders/mpsimagepyramid.md) ### Histogram Image Filters - [MPSImageHistogram](metalperformanceshaders/mpsimagehistogram.md) - [MPSImageHistogramEqualization](metalperformanceshaders/mpsimagehistogramequalization.md) - [MPSImageHistogramSpecification](metalperformanceshaders/mpsimagehistogramspecification.md) ### Image Threshold Filters - [MPSImageThresholdBinary](metalperformanceshaders/mpsimagethresholdbinary.md) - [MPSImageThresholdBinaryInverse](metalperformanceshaders/mpsimagethresholdbinaryinverse.md) - [MPSImageThresholdToZero](metalperformanceshaders/mpsimagethresholdtozero.md) - [MPSImageThresholdToZeroInverse](metalperformanceshaders/mpsimagethresholdtozeroinverse.md) - [MPSImageThresholdTruncate](metalperformanceshaders/mpsimagethresholdtruncate.md) ### Image Integral Filters - [MPSImageIntegral](metalperformanceshaders/mpsimageintegral.md) - [MPSImageIntegralOfSquares](metalperformanceshaders/mpsimageintegralofsquares.md) ### Image Manipulation Filters - [MPSImageConversion](metalperformanceshaders/mpsimageconversion.md) - [MPSImageScale](metalperformanceshaders/mpsimagescale.md) - [MPSImageLanczosScale](metalperformanceshaders/mpsimagelanczosscale.md) - [MPSImageBilinearScale](metalperformanceshaders/mpsimagebilinearscale.md) - [MPSImageTranspose](metalperformanceshaders/mpsimagetranspose.md) ### Image Statistics Filters - [MPSImageStatisticsMean](metalperformanceshaders/mpsimagestatisticsmean.md) - [MPSImageStatisticsMeanAndVariance](metalperformanceshaders/mpsimagestatisticsmeanandvariance.md) - [MPSImageStatisticsMinAndMax](metalperformanceshaders/mpsimagestatisticsminandmax.md) ### Image Reduction Filters - [MPSImageReduceRowMax](metalperformanceshaders/mpsimagereducerowmax.md) - [MPSImageReduceRowMin](metalperformanceshaders/mpsimagereducerowmin.md) - [MPSImageReduceRowSum](metalperformanceshaders/mpsimagereducerowsum.md) - [MPSImageReduceRowMean](metalperformanceshaders/mpsimagereducerowmean.md) - [MPSImageReduceColumnMax](metalperformanceshaders/mpsimagereducecolumnmax.md) - [MPSImageReduceColumnMin](metalperformanceshaders/mpsimagereducecolumnmin.md) - [MPSImageReduceColumnSum](metalperformanceshaders/mpsimagereducecolumnsum.md) - [MPSImageReduceColumnMean](metalperformanceshaders/mpsimagereducecolumnmean.md) - [MPSImageReduceUnary](metalperformanceshaders/mpsimagereduceunary.md) ### Image Arithmetic Filters - [MPSImageAdd](metalperformanceshaders/mpsimageadd.md) - [MPSImageSubtract](metalperformanceshaders/mpsimagesubtract.md) - [MPSImageMultiply](metalperformanceshaders/mpsimagemultiply.md) - [MPSImageDivide](metalperformanceshaders/mpsimagedivide.md) - [MPSImageArithmetic](metalperformanceshaders/mpsimagearithmetic.md) ### Euclidean Distance Transform Filter - [MPSImageEuclideanDistanceTransform](metalperformanceshaders/mpsimageeuclideandistancetransform.md) ### Fast Guided Filter - [MPSImageGuidedFilter](metalperformanceshaders/mpsimageguidedfilter.md) ### Keypoints - [MPSImageFindKeypoints](metalperformanceshaders/mpsimagefindkeypoints.md) - [MPSImageKeypointData](metalperformanceshaders/mpsimagekeypointdata.md) - [MPSImageKeypointRangeInfo](metalperformanceshaders/mpsimagekeypointrangeinfo.md) ### Image Filter Base Classes - [MPSUnaryImageKernel](metalperformanceshaders/mpsunaryimagekernel.md) - [MPSBinaryImageKernel](metalperformanceshaders/mpsbinaryimagekernel.md)