<!--
{
  "availability" : [
    "iOS: 8.0.0 -",
    "iPadOS: 8.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.11.0 -",
    "tvOS: -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Metal",
  "identifier" : "/documentation/Metal/MTLStencilDescriptor",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Metal"
    ],
    "preciseIdentifier" : "c:objc(cs)MTLStencilDescriptor"
  },
  "title" : "MTLStencilDescriptor"
}
-->

# MTLStencilDescriptor

An object that defines the front-facing or back-facing stencil operations of a depth and stencil state object.

```
class MTLStencilDescriptor
```

## Overview

A stencil test is a comparison between a masked reference value and a masked value stored in a stencil attachment. (A value is *masked* by performing a logical AND operation on it with the [`readMask`](/documentation/Metal/MTLStencilDescriptor/readMask) value.) The [`MTLStencilDescriptor`](/documentation/Metal/MTLStencilDescriptor) object defines how to update the contents of the stencil attachment, based on the results of the stencil test and the depth test.

The [`stencilCompareFunction`](/documentation/Metal/MTLStencilDescriptor/stencilCompareFunction) property defines the stencil test. The [`stencilFailureOperation`](/documentation/Metal/MTLStencilDescriptor/stencilFailureOperation), [`depthFailureOperation`](/documentation/Metal/MTLStencilDescriptor/depthFailureOperation), and [`depthStencilPassOperation`](/documentation/Metal/MTLStencilDescriptor/depthStencilPassOperation) properties specify what to do to a stencil value stored in the stencil attachment for three different test outcomes: if the stencil test fails, if the stencil test passes and the depth test fails, or if both stencil and depth tests succeed, respectively. [`writeMask`](/documentation/Metal/MTLStencilDescriptor/writeMask) determines which stencil bits can be modified as the result of a stencil operation.

## Topics

### Configuring stencil functions and operations

[`stencilFailureOperation`](/documentation/Metal/MTLStencilDescriptor/stencilFailureOperation)

The operation that is performed to update the values in the stencil attachment when the stencil test fails.

[`depthFailureOperation`](/documentation/Metal/MTLStencilDescriptor/depthFailureOperation)

The operation that is performed to update the values in the stencil attachment when the stencil test passes, but the depth test fails.

[`depthStencilPassOperation`](/documentation/Metal/MTLStencilDescriptor/depthStencilPassOperation)

The operation that is performed to update the values in the stencil attachment when both the stencil test and the depth test pass.

[`stencilCompareFunction`](/documentation/Metal/MTLStencilDescriptor/stencilCompareFunction)

The comparison that is performed between the masked reference value and a masked value in the stencil attachment.

[`MTLStencilOperation`](/documentation/Metal/MTLStencilOperation)

The operation performed on a currently stored stencil value when a comparison test passes or fails.

### Configuring stencil bit mask properties

[`readMask`](/documentation/Metal/MTLStencilDescriptor/readMask)

A bitmask that determines from which bits that stencil comparison tests can read.

[`writeMask`](/documentation/Metal/MTLStencilDescriptor/writeMask)

A bitmask that determines to which bits that stencil operations can write.


---

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)