<!--
{
  "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",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "RealityKit"
    ],
    "preciseIdentifier" : "s:17RealityFoundation14CustomMaterialV"
  },
  "title" : "CustomMaterial"
}
-->

# CustomMaterial

A material that works with custom Metal shader functions.

```
struct CustomMaterial
```

## Overview

Custom, or programmable, materials allow you to leverage RealityKit’s
existing shader pipeline to render physically based or unlit materials that
support custom Metal shader functions. These functions modify how RealityKit
renders an entity. Custom materials support two different types of custom
Metal shader functions: geometry modifiers and surface shaders.

Use a _surface shader _to calculate or specify all the material attributes
that RealityKit uses to render your entity, such as
[`baseColor`](/documentation/RealityKit/CustomMaterial/baseColor-swift.property),
[`normal`](/documentation/RealityKit/CustomMaterial/normal-swift.property), and
[`roughness`](/documentation/RealityKit/CustomMaterial/roughness-swift.property). A *geometry modifier* can
offset the position of an entity’s vertices to change the size and shape of
an entity. It can also change other per-vertex data, such as vertex color
and UV texture coordinates, which define how RealityKit maps textures on to
the model.

> Important: For the Metal API documentation for custom material shader
> functions, see [the Metal RealityKit APIs PDF](https://developer.apple.com/metal/Metal-RealityKit-APIs.pdf).

For more information on creating custom materials and writing shader
functions, see [Modifying RealityKit rendering using custom materials](/documentation/RealityKit/modifying-realitykit-rendering-using-custom-materials).

## Topics

### Creating custom materials

[`init(from:geometryModifier:)`](/documentation/RealityKit/CustomMaterial/init(from:geometryModifier:))

Creates a custom material from an existing material and a geometry
modifier.

[`init(from:surfaceShader:geometryModifier:)`](/documentation/RealityKit/CustomMaterial/init(from:surfaceShader:geometryModifier:))

Creates a custom material from an existing material, surface shader, and
geometry modifier.

[`init(surfaceShader:geometryModifier:lightingModel:)`](/documentation/RealityKit/CustomMaterial/init(surfaceShader:geometryModifier:lightingModel:))

Creates a custom material from a lighting model, surface shader, and
geometry modifier.

[`init(program:)`](/documentation/RealityKit/CustomMaterial/init(program:))

### Setting the core properties

[`baseColor`](/documentation/RealityKit/CustomMaterial/baseColor-swift.property)

The color of an entity unmodified by lighting.

[`roughness`](/documentation/RealityKit/CustomMaterial/roughness-swift.property)

The amount the surface of the 3D object scatters reflected light.

[`metallic`](/documentation/RealityKit/CustomMaterial/metallic-swift.property)

The reflectiveness of an entity.

[`normal`](/documentation/RealityKit/CustomMaterial/normal-swift.property)

A texture map that stores fine surface details for the entity.

[`emissiveColor`](/documentation/RealityKit/CustomMaterial/emissiveColor-swift.property)

The color of light this material emits.

[`ambientOcclusion`](/documentation/RealityKit/CustomMaterial/ambientOcclusion-swift.property)

The ambient light exposure for a material.

[`specular`](/documentation/RealityKit/CustomMaterial/specular-swift.property)

The bright highlights to apply to the entity.

[`clearcoat`](/documentation/RealityKit/CustomMaterial/clearcoat-swift.property)

The transparent highlights that simulate a clear, shiny coating on an
entity.

[`clearcoatRoughness`](/documentation/RealityKit/CustomMaterial/clearcoatRoughness-swift.property)

The degree to which an entity’s clear, shiny coating scatters light to
create soft highlights.

[`clearcoatNormal`](/documentation/RealityKit/CustomMaterial/clearcoatNormal-swift.property)

Waviness and imperfections for the top clearcoat.

### Controlling opacity

[`opacityThreshold`](/documentation/RealityKit/CustomMaterial/opacityThreshold)

The minimum opacity value to treat as fully opaque.

[`blending`](/documentation/RealityKit/CustomMaterial/blending-swift.property)

The transparency of an entity.

### Setting shader properties

[`program`](/documentation/RealityKit/CustomMaterial/program-swift.property)

[`custom`](/documentation/RealityKit/CustomMaterial/custom-swift.property)

User-defined properties for the material’s shader functions.

[`lightingModel`](/documentation/RealityKit/CustomMaterial/lightingModel-swift.property)

The lighting model that the material uses.

[`withMutableUniforms(ofType:_:)`](/documentation/RealityKit/CustomMaterial/withMutableUniforms(ofType:_:))

Calls the given closure with an inout reference to the underlying storage bound to the
custom uniforms argument of a surface shader and geometry modifier.

[`withMutableUniforms(ofType:stage:_:)`](/documentation/RealityKit/CustomMaterial/withMutableUniforms(ofType:stage:_:))

Calls the given closure with an inout reference to the underlying storage bound to the
custom uniforms argument of a surface shader or geometry modifier.

### Modifying texture coordinates

[`textureCoordinateTransform`](/documentation/RealityKit/CustomMaterial/textureCoordinateTransform-swift.property)

A two-dimensional transformation RealityKit applies to the entity’s
primary texture coordinates.

[`secondaryTextureCoordinateTransform`](/documentation/RealityKit/CustomMaterial/secondaryTextureCoordinateTransform)

A two-dimensional transformation RealityKit applies to the entity’s
secondary texture coordinates.

### Culling unnecessary polygons

[`faceCulling`](/documentation/RealityKit/CustomMaterial/faceCulling-swift.property)

A process in which the system specifies polygons to remove before
rendering a mesh using this material.

### Setting depth testing properties

[`readsDepth`](/documentation/RealityKit/CustomMaterial/readsDepth)

A boolean value that determines whether this material performs the depth test by reading RealityKit’s depth buffer.

[`writesDepth`](/documentation/RealityKit/CustomMaterial/writesDepth)

A boolean value that determines whether this material writes its depth into RealityKit’s depth buffer.

### Applying post-lighting shading


---

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)