<!--
{
  "availability" : [
    "iOS: 10.0.0 -",
    "iPadOS: 10.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.13.0 -",
    "tvOS: 10.0.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "MetalPerformanceShaders",
  "identifier" : "/documentation/MetalPerformanceShaders/MPSImageGaussianPyramid",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Metal Performance Shaders"
    ],
    "preciseIdentifier" : "c:objc(cs)MPSImageGaussianPyramid"
  },
  "title" : "MPSImageGaussianPyramid"
}
-->

# MPSImageGaussianPyramid

A filter that convolves an image with a Gaussian pyramid.

```
class MPSImageGaussianPyramid
```

## Overview

The Gaussian image pyramid kernel is enqueued as an in-place operation using the [`encode(commandBuffer:inPlaceTexture:fallbackCopyAllocator:)`](/documentation/MetalPerformanceShaders/MPSUnaryImageKernel/encode(commandBuffer:inPlaceTexture:fallbackCopyAllocator:)) method. All mip-map levels (after level 1) present in the provided image are filled using the provided filter kernel. The `fallbackCopyAllocator` parameter is not used. The Gaussian image pyramid kernel ignores the [`clipRect`](/documentation/MetalPerformanceShaders/MPSUnaryImageKernel/clipRect) and [`offset`](/documentation/MetalPerformanceShaders/MPSUnaryImageKernel/offset) properties, and fills the entirety of the mip-map levels. Recall the size of the nth mip-map level as:

- `w_n = max(1, floor(w_0 / 2^n))`
- `h_n = max(1, floor(h_0 / 2^n))`

Where `w_0` and `h_0` are the width and height of the 0th level, respectively (i.e. the image dimensions themselves).

The Gaussian image pyramid is constructed as follows:

- First, the 0th level mip-map of the input image is filtered with the specified convolution kernel. The default convolution filter kernel is `k = ww^T`, where `w = [1/16, 1/4, 3/8, 1/4,  1/16 ]^T`. You may also modify this kernel with a `centerWeight` parameter of `a` resulting in `k = ww^T`, where `w = [(1/4 - a/2), 1/4, a, 1/4, (1/4 - a/2) ]^T`, or you may provide a completely custom kernel.
- Afterwards, the image is down-sampled by removing all odd rows and columns, which defines the next level in the Gaussian image pyramid.
- This procedure is continued until every mip-map level present in the image is filled with all the pyramid levels.

> Note:
> Make sure your chosen texture type is compatible with mip-mapping and also supports texture views (i.e. the texture’s usage includes the <doc://com.apple.documentation/documentation/Metal/MTLTextureUsage/pixelFormatView> option).

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)