<!--
{
  "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

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

[`-  initWithDevice:`](/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

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

[`-  encodeToCommandBuffer: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())

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Relationships

### Inherited By

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### Inherits From

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

### Conforms To

[`CVarArg`](/documentation/Swift/CVarArg)

[`Equatable`](/documentation/Swift/Equatable)

[`NSSecureCoding`](/documentation/Foundation/NSSecureCoding)

[`NSCopying`](/documentation/Foundation/NSCopying)

[`Hashable`](/documentation/Swift/Hashable)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`NSCoding`](/documentation/Foundation/NSCoding)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

---

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)