<!--
{
  "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/MPSCNNKernel",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Metal Performance Shaders"
    ],
    "preciseIdentifier" : "c:objc(cs)MPSCNNKernel"
  },
  "title" : "MPSCNNKernel"
}
-->

# MPSCNNKernel

Base class for neural network layers.

```
class MPSCNNKernel
```

## Overview

An [`MPSCNNKernel`](/documentation/MetalPerformanceShaders/MPSCNNKernel) object consumes one [`MPSImage`](/documentation/MetalPerformanceShaders/MPSImage) object and produces one [`MPSImage`](/documentation/MetalPerformanceShaders/MPSImage) object.

The region overwritten in the destination image is described by the [`clipRect`](/documentation/MetalPerformanceShaders/MPSCNNKernel/clipRect) property.  The top left corner of the region consumed (ignoring adjustments for filter size—for example, convolution filter size) is given by the [`offset`](/documentation/MetalPerformanceShaders/MPSCNNKernel/offset) property. The size of the region consumed is a function of the size of the [`clipRect`](/documentation/MetalPerformanceShaders/MPSCNNKernel/clipRect) property and any subsampling caused by pixel strides at work (for example, [`strideInPixelsX`](/documentation/MetalPerformanceShaders/MPSCNNKernel/strideInPixelsX)/[`strideInPixelsY`](/documentation/MetalPerformanceShaders/MPSCNNKernel/strideInPixelsY) in the [`MPSCNNPooling`](/documentation/MetalPerformanceShaders/MPSCNNPooling) class).  Wherever the [`offset`](/documentation/MetalPerformanceShaders/MPSCNNKernel/offset) and [`clipRect`](/documentation/MetalPerformanceShaders/MPSCNNKernel/clipRect) properties would cause an `{x,y}` pixel address not in the image to be read, the [`edgeMode`](/documentation/MetalPerformanceShaders/MPSCNNKernel/edgeMode) property is used to determine what value to read there.

The `z` or `depth` component of the [`offset`](/documentation/MetalPerformanceShaders/MPSCNNKernel/offset), <doc://com.apple.documentation/documentation/Metal/MTLRegion/origin> and [`size`](/documentation/MetalPerformanceShaders/MPSRegion/size) properties indexes which images to use.

- If the [`MPSImage`](/documentation/MetalPerformanceShaders/MPSImage) object contains only a single image, then these values should be `offset.z = 0`, `clipRect.origin.z = 0`, and `clipRect.size.depth = 1`.
- If the [`MPSImage`](/documentation/MetalPerformanceShaders/MPSImage) object contains multiple images, then the value of `clipRect.size.depth` determines the number of images to process. Both the source and destination [`MPSImage`](/documentation/MetalPerformanceShaders/MPSImage) objects must have at least this many images. The value of `offset.z` refers to the starting image index of the source. Thus, the value of `offset.z + clipRect.size.depth` must be `<=source.numberOfImages`. Similarly, the value of `clipRect.origin.z` determines the starting image index of the destination. Thus, the value of `clipRect.origin.z + clipRect.size.depth` must be `<=destination.numberOfImages`.

The [`destinationFeatureChannelOffset`](/documentation/MetalPerformanceShaders/MPSCNNKernel/destinationFeatureChannelOffset) property can be used to control where the kernel will start writing in terms of feature channel dimension. For example, if the destination has 64 channels and th[`destinationFeatureChannelOffset`](/documentation/MetalPerformanceShaders/MPSCNNKernel/destinationFeatureChannelOffset)e kernel outputs 32 channels, channels 0-31 of the destination will be populated by the kernel (by default). But if you want the kernel to populate channels 32-63 of the destination, you can set the value of [`destinationFeatureChannelOffset`](/documentation/MetalPerformanceShaders/MPSCNNKernel/destinationFeatureChannelOffset) to 32. Suppose you have a source of dimensions `w x h x Ni`, where `N` is the number of channels, which goes through a convolution filter `C0` which produces the output `O0 = w x h x N0` and `C`1 which produces the output `O1 = w x h x N1` followed by concatenation which produces `O = w x h x (N0 + N1)`. You can achieve this by creating an [`MPSImage`](/documentation/MetalPerformanceShaders/MPSImage) object with dimensions `w x h x (N0 + N1)` and using this as the destination of both convolutions as follows:

- `C0: destinationFeatureChannelOffset = 0`, this will output `N0` channels starting at channel `0` of destination thus populating `[0,N0-1]` channels.
- `C1: destinationFeatureChannelOffset = N0`, this will output `N1` channels starting at channel `N0` of destination thus populating `[N0,N0+N1-1]` channels.

## Topics

### Initializers

[`init(coder:device:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/init(coder:device:))

[`init(device:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/init(device:))

### Instance Properties

[`offset`](/documentation/MetalPerformanceShaders/MPSCNNKernel/offset)

The position of the destination image’s clip rectangle origin, relative to the source image.

[`MPSOffset`](/documentation/MetalPerformanceShaders/MPSOffset)

A signed coordinate with x, y, and z components.

[`clipRect`](/documentation/MetalPerformanceShaders/MPSCNNKernel/clipRect)

An optional clip rectangle to use when writing data. Only the pixels in the clip rectangle will be overwritten.

  <doc://com.apple.documentation/documentation/Metal/MTLRegion>

[`destinationFeatureChannelOffset`](/documentation/MetalPerformanceShaders/MPSCNNKernel/destinationFeatureChannelOffset)

The number of channels in the destination image to skip before writing output data.

[`edgeMode`](/documentation/MetalPerformanceShaders/MPSCNNKernel/edgeMode)

The edge mode to use when texture reads stray off the edge of an image.

[`MPSImageEdgeMode`](/documentation/MetalPerformanceShaders/MPSImageEdgeMode)

The options used to control the edge behavior of an image filter when it reads outside the bounds of a source texture.

[`kernelHeight`](/documentation/MetalPerformanceShaders/MPSCNNKernel/kernelHeight)

[`kernelWidth`](/documentation/MetalPerformanceShaders/MPSCNNKernel/kernelWidth)

[`strideInPixelsX`](/documentation/MetalPerformanceShaders/MPSCNNKernel/strideInPixelsX)

[`strideInPixelsY`](/documentation/MetalPerformanceShaders/MPSCNNKernel/strideInPixelsY)

[`isBackwards`](/documentation/MetalPerformanceShaders/MPSCNNKernel/isBackwards)

[`padding`](/documentation/MetalPerformanceShaders/MPSCNNKernel/padding)

[`MPSNNPadding`](/documentation/MetalPerformanceShaders/MPSNNPadding)

The protocol that provides a description of how kernels should pad images.

[`destinationImageAllocator`](/documentation/MetalPerformanceShaders/MPSCNNKernel/destinationImageAllocator)

[`MPSImageAllocator`](/documentation/MetalPerformanceShaders/MPSImageAllocator)

[`dilationRateX`](/documentation/MetalPerformanceShaders/MPSCNNKernel/dilationRateX)

[`dilationRateY`](/documentation/MetalPerformanceShaders/MPSCNNKernel/dilationRateY)

[`isStateModified`](/documentation/MetalPerformanceShaders/MPSCNNKernel/isStateModified)

[`sourceFeatureChannelMaxCount`](/documentation/MetalPerformanceShaders/MPSCNNKernel/sourceFeatureChannelMaxCount)

[`sourceFeatureChannelOffset`](/documentation/MetalPerformanceShaders/MPSCNNKernel/sourceFeatureChannelOffset)

### Instance Methods

[`encode(commandBuffer:sourceImage:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/encode(commandBuffer:sourceImage:))

[`encode(commandBuffer:sourceImage:destinationImage:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/encode(commandBuffer:sourceImage:destinationImage:))

Encodes a kernel into a command buffer.  The ensuing operation proceeds out-of-place.

[`appendBatchBarrier()`](/documentation/MetalPerformanceShaders/MPSCNNKernel/appendBatchBarrier())

[`batchEncodingStorageSize(sourceImage:sourceStates:destinationImage:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/batchEncodingStorageSize(sourceImage:sourceStates:destinationImage:))

[`destinationImageDescriptor(sourceImages:sourceStates:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/destinationImageDescriptor(sourceImages:sourceStates:))

[`encode(commandBuffer:sourceImage:destinationState:destinationImage:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/encode(commandBuffer:sourceImage:destinationState:destinationImage:))

[`encode(commandBuffer:sourceImage:destinationState:destinationStateIsTemporary:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/encode(commandBuffer:sourceImage:destinationState:destinationStateIsTemporary:))

[`encodeBatch(commandBuffer:sourceImages:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/encodeBatch(commandBuffer:sourceImages:))

[`encodeBatch(commandBuffer:sourceImages:destinationImages:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/encodeBatch(commandBuffer:sourceImages:destinationImages:))

[`encodeBatch(commandBuffer:sourceImages:destinationStates:destinationImages:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/encodeBatch(commandBuffer:sourceImages:destinationStates:destinationImages:))

[`encodeBatch(commandBuffer:sourceImages:destinationStates:destinationStateIsTemporary:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/encodeBatch(commandBuffer:sourceImages:destinationStates:destinationStateIsTemporary:))

[`encodingStorageSize(sourceImage:sourceStates:destinationImage:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/encodingStorageSize(sourceImage:sourceStates:destinationImage:))

[`isResultStateReusedAcrossBatch()`](/documentation/MetalPerformanceShaders/MPSCNNKernel/isResultStateReusedAcrossBatch())

[`resultState(sourceImage:sourceStates:destinationImage:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/resultState(sourceImage:sourceStates:destinationImage:))

[`resultStateBatch(sourceImage:sourceStates:destinationImage:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/resultStateBatch(sourceImage:sourceStates:destinationImage:))

[`temporaryResultState(commandBuffer:sourceImage:sourceStates:destinationImage:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/temporaryResultState(commandBuffer:sourceImage:sourceStates:destinationImage:))

[`temporaryResultStateBatch(commandBuffer:sourceImage:sourceStates:destinationImage:)`](/documentation/MetalPerformanceShaders/MPSCNNKernel/temporaryResultStateBatch(commandBuffer:sourceImage:sourceStates:destinationImage:))


---

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)