<!--
{
  "availability" : [
    "iOS: 15.0.0 -",
    "iPadOS: 15.0.0 -",
    "macCatalyst: 15.0.0 -",
    "macOS: 12.0.0 -",
    "tvOS: 26.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "RealityKit",
  "identifier" : "/documentation/RealityKit/CustomMaterial/opacityThreshold",
  "metadataVersion" : "0.1.0",
  "role" : "Instance Property",
  "symbol" : {
    "kind" : "Instance Property",
    "modules" : [
      "RealityKit"
    ],
    "preciseIdentifier" : "s:17RealityFoundation14CustomMaterialV16opacityThresholdSfSgvp"
  },
  "title" : "opacityThreshold"
}
-->

# opacityThreshold

The minimum opacity value to treat as fully opaque.

```
var opacityThreshold: Float? { get set }
```

## Discussion

In a custom material, `opacityThreshold` helps define how RealityKit
renders transparency when using a texture (known as an *alpha map*) to
control opacity. This property is available as an input to the
material’s surface shader, but RealityKit doesn’t automatically use this
value to render your entity.
To render an entity transparent,
call `params.surface().set_opacity()` from the surface shader.

When `opacityThreshold` is set, [`PhysicallyBasedMaterial`](/documentation/RealityKit/PhysicallyBasedMaterial)
uses the opacity texture as a mask. RealityKit discards pixels with opacity values less
than the `opacityThreshold`, and renders opacity values greater than or equal to
`opacityThreshold` fully opaque.

The following Metal code replicates the behavior of the
[`PhysicallyBasedMaterial`](/documentation/RealityKit/PhysicallyBasedMaterial) shaders:

```cpp
// Retrieve the threshold from the CustomMaterial.
float opacityThreshold = params.material_constants().opacity_threshold();

// Retrieve the entity's texture coordinates.
float2 uv = params.geometry().uv0();

// Entities loaded from USDZ or .reality files use texture coordinates with
// a flipped y-axis. This adjusts for that.
uv.y = 1.0 - uv.y;

// Retrieve the opacity texture from the material.
auto tex = params.textures();

// Sample the value from the opacity texture.
half opacity = tex.opacity().sample(textureSampler, uv).r;

// When the opacity threshold is used, set the opacity to either
// 1.0 or 0.0 depending on the value of the opacity threshold for
// the masking behavior.
opacity = (opacity <= opacityThreshold) ? 0.0 : 1.0;

// Use the calculated value to set the opacity for rendering.
params.surface().set_opacity(opacity);
```

---

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)