A material that simulates the appearance of real-world objects.
In RealityKit, a _material_ is an object that defines the surface properties
of a rendered 3D object. A Physically Based Rendering (PBR) material is a
material that closely approximates the way light reflects off of real-world
objects. Use ``PhysicallyBasedMaterial`` to create highly realistic-looking
objects for your AR scenes.
Many of the properties for ``PhysicallyBasedMaterial`` provide the option to
use more than one type of data to specify that property. You can set an
object’s ``PhysicallyBasedMaterial/baseColor-swift.property`` using a
specific color for the entire material, or you can use an image that UV-maps
on to the entity.
``PhysicallyBasedMaterial`` includes all material properties supported by
USDZ. On iOS 15 and later, RealityKit automatically uses
``PhysicallyBasedMaterial`` when importing an entity from a USDZ file.
For more information on using ``PhysicallyBasedMaterial``, see
<doc:applying-realistic-material-and-lighting-effects-to-entities>.
Members (62)
get · iOS 27.0+
bentNormal
TypeScript
get bentNormal(): PhysicallyBasedMaterial_BentNormal
Swift declaration
var bentNormal: PhysicallyBasedMaterial.BentNormal { get set }
The bent normal map for the entity.
_Bent normal mapping_ describes the average direction of least occlusion at each surface point.
This is used to modulate lighting intensity and direction of the material. Use with ambient occlusion
to improve the accuracy of indirect diffuse lighting. You can generate bent normals maps from
a 3D software package.
The following code loads a bent normal map texture and uses it to set this property:
```swift
if let bentNormalResource = try? TextureResource.load(named:"entity_bentNormalMap") {
let bentNormalMap = PhysicallyBasedMaterial.Texture(bentNormalResource)
material.bentNormal = .init(texture: bentNormalMap)
}
```
set · iOS 27.0+
bentNormal
TypeScript
set bentNormal(value: PhysicallyBasedMaterial_BentNormal)
Swift declaration
var bentNormal: PhysicallyBasedMaterial.BentNormal { get set }
The bent normal map for the entity.
_Bent normal mapping_ describes the average direction of least occlusion at each surface point.
This is used to modulate lighting intensity and direction of the material. Use with ambient occlusion
to improve the accuracy of indirect diffuse lighting. You can generate bent normals maps from
a 3D software package.
The following code loads a bent normal map texture and uses it to set this property:
```swift
if let bentNormalResource = try? TextureResource.load(named:"entity_bentNormalMap") {
let bentNormalMap = PhysicallyBasedMaterial.Texture(bentNormalResource)
material.bentNormal = .init(texture: bentNormalMap)
}
```
get · iOS 18.0+
readsDepth
TypeScript
get readsDepth(): boolean
Swift declaration
var readsDepth: Bool { get set }
A boolean value that determines whether this material performs the depth test by reading RealityKit's depth buffer.
If true, meshes with this material will depth test each of their fragments when being rendered.
If an object that writes depth is in front of this material, this material will be hidden.
If false, meshes with this material will ignore the depth test, and always render all of their
fragments during their draw call, regardless of the positioning of other objects in the scene.
Note that other objects may still render on top of this material, depending on draw order.
The default value is true.
set · iOS 18.0+
readsDepth
TypeScript
set readsDepth(value: boolean)
Swift declaration
var readsDepth: Bool { get set }
A boolean value that determines whether this material performs the depth test by reading RealityKit's depth buffer.
If true, meshes with this material will depth test each of their fragments when being rendered.
If an object that writes depth is in front of this material, this material will be hidden.
If false, meshes with this material will ignore the depth test, and always render all of their
fragments during their draw call, regardless of the positioning of other objects in the scene.
Note that other objects may still render on top of this material, depending on draw order.
The default value is true.
get · iOS 15.0+
faceCulling
TypeScript
get faceCulling(): MaterialParameterTypes_FaceCulling
Swift declaration
var faceCulling: PhysicallyBasedMaterial.FaceCulling { get set }
A process in which the system specifies polygons to remove before
rendering a mesh using this material.
To improve performance, RealityKit culls polygons, or faces, that it
determines won’t be visible. Discarding faces that aren’t part of the
final render eliminates the need to do any calculations for those
faces.
RealityKit recognizes when a face aims toward the camera (a front face)
or away from the camera (a back face). This value controls the type of
faces RealityKit culls.
This value defaults to ``MaterialParameterTypes/FaceCulling/back``,
which means RealityKit removes faces that point away from the camera.
Most of the time, this is the correct behavior, because back faces are
usually obscured by other front-facing polygons.
You can change the culling behavior to cull front faces instead or to
turn off face culling altogether, but be aware that turning off face
culling results in less efficient rendering and may negatively impact
your app’s frame rate.
set · iOS 15.0+
faceCulling
TypeScript
set faceCulling(value: MaterialParameterTypes_FaceCulling)
Swift declaration
var faceCulling: PhysicallyBasedMaterial.FaceCulling { get set }
A process in which the system specifies polygons to remove before
rendering a mesh using this material.
To improve performance, RealityKit culls polygons, or faces, that it
determines won’t be visible. Discarding faces that aren’t part of the
final render eliminates the need to do any calculations for those
faces.
RealityKit recognizes when a face aims toward the camera (a front face)
or away from the camera (a back face). This value controls the type of
faces RealityKit culls.
This value defaults to ``MaterialParameterTypes/FaceCulling/back``,
which means RealityKit removes faces that point away from the camera.
Most of the time, this is the correct behavior, because back faces are
usually obscured by other front-facing polygons.
You can change the culling behavior to cull front faces instead or to
turn off face culling altogether, but be aware that turning off face
culling results in less efficient rendering and may negatively impact
your app’s frame rate.
get · iOS 18.0+
writesDepth
TypeScript
get writesDepth(): boolean
Swift declaration
var writesDepth: Bool { get set }
A boolean value that determines whether this material writes its depth into RealityKit's depth buffer.
If true, meshes with this material will occlude objects behind them by writing their depth
into RealityKit's depth buffer.
If false, meshes with this material will not write their depth into
RealityKit's depth buffer, and may be overwritten by objects drawn behind them, depending on
draw order.
The default value is true.
set · iOS 18.0+
writesDepth
TypeScript
set writesDepth(value: boolean)
Swift declaration
var writesDepth: Bool { get set }
A boolean value that determines whether this material writes its depth into RealityKit's depth buffer.
If true, meshes with this material will occlude objects behind them by writing their depth
into RealityKit's depth buffer.
If false, meshes with this material will not write their depth into
RealityKit's depth buffer, and may be overwritten by objects drawn behind them, depending on
draw order.
The default value is true.
get · iOS 15.0+
emissiveColor
TypeScript
get emissiveColor(): PhysicallyBasedMaterial_EmissiveColor
Swift declaration
var emissiveColor: PhysicallyBasedMaterial.EmissiveColor { get set }
The color of the light the entity emits.
With Physically Based Rendering (PBR), you can give entities in
RealityKit the appearance of emitting light. Use this property to
simulate real-world objects that glow, such as objects with LEDs or
computer screens. To enable light emission from a material, set
``PhysicallyBasedMaterial/emissiveIntensity`` to a value greater than
zero, then specify a color for the emitted light other than black using
this property. You can specify a single emissive color for the entire
material, or use a UV-mapped image texture to use different colors for
different parts of the entity.
The following example uses a single color for the entire material:
```swift
material.emissiveIntensity = 2.0
self.emissiveColor = PhysicallyBasedMaterial.EmissiveColor(color: .red)
```
This example uses an image map to control the light emission color:
```swift
if let emissiveResource = try? TextureResource.load(named:"entity_emissive") {
let emissiveMap = MaterialParameters.Texture(emissiveResource)
material.emissiveColor = .init(texture: emissiveMap)
}
```
set · iOS 15.0+
emissiveColor
TypeScript
set emissiveColor(value: PhysicallyBasedMaterial_EmissiveColor)
Swift declaration
var emissiveColor: PhysicallyBasedMaterial.EmissiveColor { get set }
The color of the light the entity emits.
With Physically Based Rendering (PBR), you can give entities in
RealityKit the appearance of emitting light. Use this property to
simulate real-world objects that glow, such as objects with LEDs or
computer screens. To enable light emission from a material, set
``PhysicallyBasedMaterial/emissiveIntensity`` to a value greater than
zero, then specify a color for the emitted light other than black using
this property. You can specify a single emissive color for the entire
material, or use a UV-mapped image texture to use different colors for
different parts of the entity.
The following example uses a single color for the entire material:
```swift
material.emissiveIntensity = 2.0
self.emissiveColor = PhysicallyBasedMaterial.EmissiveColor(color: .red)
```
This example uses an image map to control the light emission color:
```swift
if let emissiveResource = try? TextureResource.load(named:"entity_emissive") {
let emissiveMap = MaterialParameters.Texture(emissiveResource)
material.emissiveColor = .init(texture: emissiveMap)
}
```
get · iOS 15.0+
anisotropyAngle
TypeScript
get anisotropyAngle(): PhysicallyBasedMaterial_AnisotropyAngle
Swift declaration
var anisotropyAngle: PhysicallyBasedMaterial.AnisotropyAngle { get set }
The angle at which the anisotropic direction of the material is oriented,
influencing the reflection and appearance of surface highlights.
This property controls the scattering angle for anisotropic objects. If
``PhysicallyBasedMaterial/anisotropyLevel-swift.property`` is `0.0`,
this property has no effect. This property takes a value between `0.0
`and `1.0` or a UV-mapped grayscale image specifying angles for
different parts of the entity.` A` value of black (`0.0)` means a
rotation of 0° and a value of white (`1.0)` indicates a rotation of
360°. To determine the
``PhysicallyBasedMaterial/anisotropyAngle-swift.property`` value from an
angle, divide the desired angle in degrees by `360.0` or the desired
angle in radians by pi times 2.
```swift
let angleDegrees = Float(125.0)
let anisotropyAngleFromDegrees = angleDegrees / 360.0
let angleRadians = Float(2.181662) let anisotropyAngleFromRadians =
angleRadians / (Float.pi * Float(2.0))
```
The following example shows how to specify `anisotropyAngle` using
single values for the entire material:
```swift
material.anisotropyAngle = .AnisotropyAngle(floatLiteral: 0.25)
```
This example shows how to specify anisotropy using a UV-mapped image
texture for ``PhysicallyBasedMaterial/anisotropyLevel-swift.property``
and a separate image for
``PhysicallyBasedMaterial/anisotropyAngle-swift.property``:
```swift
if let anisoLevelResource = try? TextureResource.load(named:
"entity_aniso_level") {
let anisoLevelMap = MaterialParameters.Texture(sheenResource)
material.anisotropyLevel = .init(texture: anisoLevelMap)
}
if let anisoAngleResource = try? TextureResource.load(named:
"entity_aniso_angle") {
let anisoAngleMap = MaterialParameters.Texture(anisoAngleResource)
material.anisotropyAngle = .init(texture: anisoAngleMap)
}
```
set · iOS 15.0+
anisotropyAngle
TypeScript
set anisotropyAngle(value: PhysicallyBasedMaterial_AnisotropyAngle)
Swift declaration
var anisotropyAngle: PhysicallyBasedMaterial.AnisotropyAngle { get set }
The angle at which the anisotropic direction of the material is oriented,
influencing the reflection and appearance of surface highlights.
This property controls the scattering angle for anisotropic objects. If
``PhysicallyBasedMaterial/anisotropyLevel-swift.property`` is `0.0`,
this property has no effect. This property takes a value between `0.0
`and `1.0` or a UV-mapped grayscale image specifying angles for
different parts of the entity.` A` value of black (`0.0)` means a
rotation of 0° and a value of white (`1.0)` indicates a rotation of
360°. To determine the
``PhysicallyBasedMaterial/anisotropyAngle-swift.property`` value from an
angle, divide the desired angle in degrees by `360.0` or the desired
angle in radians by pi times 2.
```swift
let angleDegrees = Float(125.0)
let anisotropyAngleFromDegrees = angleDegrees / 360.0
let angleRadians = Float(2.181662) let anisotropyAngleFromRadians =
angleRadians / (Float.pi * Float(2.0))
```
The following example shows how to specify `anisotropyAngle` using
single values for the entire material:
```swift
material.anisotropyAngle = .AnisotropyAngle(floatLiteral: 0.25)
```
This example shows how to specify anisotropy using a UV-mapped image
texture for ``PhysicallyBasedMaterial/anisotropyLevel-swift.property``
and a separate image for
``PhysicallyBasedMaterial/anisotropyAngle-swift.property``:
```swift
if let anisoLevelResource = try? TextureResource.load(named:
"entity_aniso_level") {
let anisoLevelMap = MaterialParameters.Texture(sheenResource)
material.anisotropyLevel = .init(texture: anisoLevelMap)
}
if let anisoAngleResource = try? TextureResource.load(named:
"entity_aniso_angle") {
let anisoAngleMap = MaterialParameters.Texture(anisoAngleResource)
material.anisotropyAngle = .init(texture: anisoAngleMap)
}
```
get · iOS 15.0+
anisotropyLevel
TypeScript
get anisotropyLevel(): PhysicallyBasedMaterial_AnisotropyLevel
Swift declaration
var anisotropyLevel: PhysicallyBasedMaterial.AnisotropyLevel { get set }
The degree to which an entity reflects light to create stretched or
oblong highlights.
By default, PBR materials are isotropic; in other words, an entity that
uses ``PhysicallyBasedMaterial`` reflects light uniformly in all
directions, mimicking the behavior of most real-world objects. Some
objects, including those with many small parallel striations such as
vinyl records, CDs, or straight hair, reflect light more in some
directions than others, resulting in stretched or oblong specular
highlights, as shown in the following figure.
This property controls the amount of anisotropy. It works together with
``PhysicallyBasedMaterial/anisotropyAngle-swift.property``, which
defines the angle of elongation for the specular highlights.
The following example specifies `anisotropyLevel` using single values
for the entire material:
```swift
material.anisotropyLevel = .AnisotropyLevel(floatLiteral: 0.5)
```
This example specifies `anisotropyLevel` using a UV-mapped image
texture.
```swift
if let anisoLevelResource = try? TextureResource.load(named:
"entity_aniso_level") {
let anisoLevelMap = MaterialParameters.Texture(sheenResource)
material.anisotropyLevel = .init(texture: anisoLevelMap)
}
```
set · iOS 15.0+
anisotropyLevel
TypeScript
set anisotropyLevel(value: PhysicallyBasedMaterial_AnisotropyLevel)
Swift declaration
var anisotropyLevel: PhysicallyBasedMaterial.AnisotropyLevel { get set }
The degree to which an entity reflects light to create stretched or
oblong highlights.
By default, PBR materials are isotropic; in other words, an entity that
uses ``PhysicallyBasedMaterial`` reflects light uniformly in all
directions, mimicking the behavior of most real-world objects. Some
objects, including those with many small parallel striations such as
vinyl records, CDs, or straight hair, reflect light more in some
directions than others, resulting in stretched or oblong specular
highlights, as shown in the following figure.
This property controls the amount of anisotropy. It works together with
``PhysicallyBasedMaterial/anisotropyAngle-swift.property``, which
defines the angle of elongation for the specular highlights.
The following example specifies `anisotropyLevel` using single values
for the entire material:
```swift
material.anisotropyLevel = .AnisotropyLevel(floatLiteral: 0.5)
```
This example specifies `anisotropyLevel` using a UV-mapped image
texture.
```swift
if let anisoLevelResource = try? TextureResource.load(named:
"entity_aniso_level") {
let anisoLevelMap = MaterialParameters.Texture(sheenResource)
material.anisotropyLevel = .init(texture: anisoLevelMap)
}
```
get · iOS 18.0+
clearcoatNormal
TypeScript
get clearcoatNormal(): PhysicallyBasedMaterial_ClearcoatNormal
Swift declaration
var clearcoatNormal: PhysicallyBasedMaterial.ClearcoatNormal { get set }
Waviness and imperfections for the top clearcoat.
An entity in RealityKit can display a clearcoat, which is a separate
layer of transparent specular highlights used to simulate a clear
coating, like on a car or the surface of lacquered objects. This
property allows you to specify a clearcoat normal and add
waviness and imperfections to the top clearcoat.
To use clearcoat rendering, set `clearcoat` to a value greater than `0.0`.
This example shows how to set the `clearcoatNormal` using a UV-mapped
image:
```swift
if let clearcoatNormalTextureResource = try?
TextureResource.load(named: "entity_cc_normalMap") {
let ccNormalMap = MaterialParameters.Texture(clearcoatNormalTextureResource)
material.clearcoatNormal = .init(texture: ccNormalMap)
}
```
set · iOS 18.0+
clearcoatNormal
TypeScript
set clearcoatNormal(value: PhysicallyBasedMaterial_ClearcoatNormal)
Swift declaration
var clearcoatNormal: PhysicallyBasedMaterial.ClearcoatNormal { get set }
Waviness and imperfections for the top clearcoat.
An entity in RealityKit can display a clearcoat, which is a separate
layer of transparent specular highlights used to simulate a clear
coating, like on a car or the surface of lacquered objects. This
property allows you to specify a clearcoat normal and add
waviness and imperfections to the top clearcoat.
To use clearcoat rendering, set `clearcoat` to a value greater than `0.0`.
This example shows how to set the `clearcoatNormal` using a UV-mapped
image:
```swift
if let clearcoatNormalTextureResource = try?
TextureResource.load(named: "entity_cc_normalMap") {
let ccNormalMap = MaterialParameters.Texture(clearcoatNormalTextureResource)
material.clearcoatNormal = .init(texture: ccNormalMap)
}
```
get · iOS 27.0+
subsurfaceColor
TypeScript
get subsurfaceColor(): PhysicallyBasedMaterial_SubsurfaceColor
Swift declaration
var subsurfaceColor: PhysicallyBasedMaterial.SubsurfaceColor { get set }
set · iOS 27.0+
subsurfaceColor
TypeScript
set subsurfaceColor(value: PhysicallyBasedMaterial_SubsurfaceColor)
Swift declaration
var subsurfaceColor: PhysicallyBasedMaterial.SubsurfaceColor { get set }
get · iOS 15.0+
ambientOcclusion
TypeScript
get ambientOcclusion(): PhysicallyBasedMaterial_AmbientOcclusion
Swift declaration
var ambientOcclusion: PhysicallyBasedMaterial.AmbientOcclusion { get set }
The ambient occlusion values for a material.
Ambient occlusion represents the entity’s exposure to ambient light.
Specify ambient occlusion using a UV-mapped image called an _ambient
occlusion map_. A value of black (`0.0`) represents parts of the model
that receive less ambient light because that part of the model is a
crevice, dent, or recessed area, or because another part of the same
entity is preventing ambient light from reaching it. Ambient occlusion
values of white (`1.0`) represent flat portions of the model that
receive full ambient light. You generate ambient occlusion maps using a
3D software package.
The following code loads an ambient occlusion map:
```swift if let aoResource = try? TextureResource.load(named:
"entity_ao") {
let aoMap = MaterialParameters.Texture(aoResource)
material.emissiveColor = .init(texture: aoMap)
} ```
set · iOS 15.0+
ambientOcclusion
TypeScript
set ambientOcclusion(value: PhysicallyBasedMaterial_AmbientOcclusion)
Swift declaration
var ambientOcclusion: PhysicallyBasedMaterial.AmbientOcclusion { get set }
The ambient occlusion values for a material.
Ambient occlusion represents the entity’s exposure to ambient light.
Specify ambient occlusion using a UV-mapped image called an _ambient
occlusion map_. A value of black (`0.0`) represents parts of the model
that receive less ambient light because that part of the model is a
crevice, dent, or recessed area, or because another part of the same
entity is preventing ambient light from reaching it. Ambient occlusion
values of white (`1.0`) represent flat portions of the model that
receive full ambient light. You generate ambient occlusion maps using a
3D software package.
The following code loads an ambient occlusion map:
```swift if let aoResource = try? TextureResource.load(named:
"entity_ao") {
let aoMap = MaterialParameters.Texture(aoResource)
material.emissiveColor = .init(texture: aoMap)
} ```
get · iOS 15.0+
opacityThreshold
TypeScript
get opacityThreshold(): (number) | null
Swift declaration
var opacityThreshold: Float? { get set }
A threshold below which RealityKit ignores opacity.
When `opacityThreshold` is set, RealityKit discards pixels with opacity values less
than the `opacityThreshold`, and renders opacity values greater than or equal to
`opacityThreshold` fully opaque.
- Note: When the `opacityThreshold` property is set, the blend mode of the
``PhysicallyBasedMaterial/blending-swift.property`` property is ignored and the renderer
applies the masking behavior.
set · iOS 15.0+
opacityThreshold
TypeScript
set opacityThreshold(value: (number) | null)
Swift declaration
var opacityThreshold: Float? { get set }
A threshold below which RealityKit ignores opacity.
When `opacityThreshold` is set, RealityKit discards pixels with opacity values less
than the `opacityThreshold`, and renders opacity values greater than or equal to
`opacityThreshold` fully opaque.
- Note: When the `opacityThreshold` property is set, the blend mode of the
``PhysicallyBasedMaterial/blending-swift.property`` property is ignored and the renderer
applies the masking behavior.
get · iOS 27.0+
subsurfaceRadius
TypeScript
get subsurfaceRadius(): PhysicallyBasedMaterial_SubsurfaceRadius
Swift declaration
var subsurfaceRadius: PhysicallyBasedMaterial.SubsurfaceRadius { get set }
set · iOS 27.0+
subsurfaceRadius
TypeScript
set subsurfaceRadius(value: PhysicallyBasedMaterial_SubsurfaceRadius)
Swift declaration
var subsurfaceRadius: PhysicallyBasedMaterial.SubsurfaceRadius { get set }
get · iOS 27.0+
subsurfaceWeight
TypeScript
get subsurfaceWeight(): PhysicallyBasedMaterial_SubsurfaceWeight
Swift declaration
var subsurfaceWeight: PhysicallyBasedMaterial.SubsurfaceWeight { get set }
set · iOS 27.0+
subsurfaceWeight
TypeScript
set subsurfaceWeight(value: PhysicallyBasedMaterial_SubsurfaceWeight)
Swift declaration
var subsurfaceWeight: PhysicallyBasedMaterial.SubsurfaceWeight { get set }
get · iOS 18.0+
triangleFillMode
TypeScript
get triangleFillMode(): MaterialParameterTypes_TriangleFillMode
Swift declaration
var triangleFillMode: PhysicallyBasedMaterial.TriangleFillMode { get set }
The object that controls how RealityKit draws triangles.
A value of ``MaterialParameterTypes/TriangleFillMode/fill`` causes RealityKit
to draw triangles normally, while a value of ``MaterialParameterTypes/TriangleFillMode/lines``
turns on wireframe rendering.
set · iOS 18.0+
triangleFillMode
TypeScript
set triangleFillMode(value: MaterialParameterTypes_TriangleFillMode)
Swift declaration
var triangleFillMode: PhysicallyBasedMaterial.TriangleFillMode { get set }
The object that controls how RealityKit draws triangles.
A value of ``MaterialParameterTypes/TriangleFillMode/fill`` causes RealityKit
to draw triangles normally, while a value of ``MaterialParameterTypes/TriangleFillMode/lines``
turns on wireframe rendering.
get · iOS 15.0+
emissiveIntensity
TypeScript
get emissiveIntensity(): number
Swift declaration
var emissiveIntensity: Float { get set }
The intensity of light emitted by the entity.
To make a material _emissive_ and appear to emit light, set this
property to a value greater than zero and set
``PhysicallyBasedMaterial/emissiveColor-swift.property`` to a value
other than black. RealityKit multiplies
``PhysicallyBasedMaterial/emissiveColor-swift.property`` by this value,
so the higher the value, the more intense the entity’s emission of
light.
You can set this property to values greater than `1.0`.
set · iOS 15.0+
emissiveIntensity
TypeScript
set emissiveIntensity(value: number)
Swift declaration
var emissiveIntensity: Float { get set }
The intensity of light emitted by the entity.
To make a material _emissive_ and appear to emit light, set this
property to a value greater than zero and set
``PhysicallyBasedMaterial/emissiveColor-swift.property`` to a value
other than black. RealityKit multiplies
``PhysicallyBasedMaterial/emissiveColor-swift.property`` by this value,
so the higher the value, the more intense the entity’s emission of
light.
You can set this property to values greater than `1.0`.
get · iOS 15.0+
clearcoatRoughness
TypeScript
get clearcoatRoughness(): PhysicallyBasedMaterial_ClearcoatRoughness
Swift declaration
var clearcoatRoughness: PhysicallyBasedMaterial.ClearcoatRoughness { get set }
The degree to which an entity’s clear, shiny coating scatters light to
create soft highlights.
When you enable clearcoat rendering for a material, RealityKit renders
the clearcoat as a separate layer just above the surface of the entity.
You can specify a clearcoat roughness value for the clearcoat to
indicate how much the clearcoat scatters light that bounces off of it,
which softens and spreads out the highlights.
You can specify a single value that applies to the entire material, or
you can supply a UV-mapped image texture containing different roughness
values for different parts of the entity.
The following example sets the `clearcoatRoughness` using a single
value:
```swift
material.clearcoatRoughness = .init(floatLiteral: 0.5)
```
This example shows how to set the `clearcoatRoughness` using a UV-mapped
image:
```swift
if let clearcoatRoughnessResource = try?
TextureResource.load(named: "entity_cc_roughness") {
let ccRoughnessMap = MaterialParameters.Texture(clearcoatRoughnessResource)
material.clearcoat = .init(texture: ccRoughnessMap)
}
```
set · iOS 15.0+
clearcoatRoughness
TypeScript
set clearcoatRoughness(value: PhysicallyBasedMaterial_ClearcoatRoughness)
Swift declaration
var clearcoatRoughness: PhysicallyBasedMaterial.ClearcoatRoughness { get set }
The degree to which an entity’s clear, shiny coating scatters light to
create soft highlights.
When you enable clearcoat rendering for a material, RealityKit renders
the clearcoat as a separate layer just above the surface of the entity.
You can specify a clearcoat roughness value for the clearcoat to
indicate how much the clearcoat scatters light that bounces off of it,
which softens and spreads out the highlights.
You can specify a single value that applies to the entire material, or
you can supply a UV-mapped image texture containing different roughness
values for different parts of the entity.
The following example sets the `clearcoatRoughness` using a single
value:
```swift
material.clearcoatRoughness = .init(floatLiteral: 0.5)
```
This example shows how to set the `clearcoatRoughness` using a UV-mapped
image:
```swift
if let clearcoatRoughnessResource = try?
TextureResource.load(named: "entity_cc_roughness") {
let ccRoughnessMap = MaterialParameters.Texture(clearcoatRoughnessResource)
material.clearcoat = .init(texture: ccRoughnessMap)
}
```
get · iOS 27.0+
subsurfaceRadiusScale
TypeScript
get subsurfaceRadiusScale(): PhysicallyBasedMaterial_SubsurfaceRadiusScale
Swift declaration
var subsurfaceRadiusScale: PhysicallyBasedMaterial.SubsurfaceRadiusScale { get set }
set · iOS 27.0+
subsurfaceRadiusScale
TypeScript
set subsurfaceRadiusScale(value: PhysicallyBasedMaterial_SubsurfaceRadiusScale)
Swift declaration
var subsurfaceRadiusScale: PhysicallyBasedMaterial.SubsurfaceRadiusScale { get set }
get · iOS 27.0+
enableSpecularOcclusion
TypeScript
get enableSpecularOcclusion(): boolean
Swift declaration
var enableSpecularOcclusion: Bool { get set }
Enables specular occlusion computations.
When enabled, this property reduces specular highlights in areas that are occluded from ambient light,
allowing for more realistic indirect lighting. This uses bent normal maps to modulate specular reflections
based on ambient occlusion and roughness.
Specular occlusion is particularly useful for character rendering and complex surfaces where
traditional ambient occlusion alone may not provide sufficient detail for realistic specular lighting.
- Note: This feature requires bent normal maps. Enable bent normals using
``PhysicallyBasedMaterial/bentNormal-swift.property``.
```swift
material.enableSpecularOcclusion = boolean_value
```
set · iOS 27.0+
enableSpecularOcclusion
TypeScript
set enableSpecularOcclusion(value: boolean)
Swift declaration
var enableSpecularOcclusion: Bool { get set }
Enables specular occlusion computations.
When enabled, this property reduces specular highlights in areas that are occluded from ambient light,
allowing for more realistic indirect lighting. This uses bent normal maps to modulate specular reflections
based on ambient occlusion and roughness.
Specular occlusion is particularly useful for character rendering and complex surfaces where
traditional ambient occlusion alone may not provide sufficient detail for realistic specular lighting.
- Note: This feature requires bent normal maps. Enable bent normals using
``PhysicallyBasedMaterial/bentNormal-swift.property``.
```swift
material.enableSpecularOcclusion = boolean_value
```
get · iOS 15.0+
textureCoordinateTransform
TypeScript
get textureCoordinateTransform(): MaterialParameterTypes_TextureCoordinateTransform
Swift declaration
var textureCoordinateTransform: PhysicallyBasedMaterial.TextureCoordinateTransform { get set }
A two-dimensional transformation to apply to the entity’s primary
texture coordinates.
An entity’s UV texture coordinates control how RealityKit materials map
image textures onto an entity. This property allows you to transform the
texture coordinates to change the way this material maps its textures.
You might, for example, change the scale of a property to apply a tiled,
repeating pattern, or continuously rotate or translate the texture
coordinates to animate materials to create special effects, such as fire
or flowing liquids.
The following example shows how to set a material’s UV transformation:
```swift
let rotationRadians = Float(45.0) * .pi / 180 // 45 degrees converted to radians.
material.textureCoordinateTransform = .init(offset: SIMD2<Float>(x:0.5, y: 0.5),
scale: SIMD2<Float>(x:0.5, y: 0.5),
rotation: rotationRadians)
```
Some entities imported from USDZ files have more than one set of UV
coordinates. This property affects the primary UV set (sometimes called
“UV1”). To transform the secondary UV coordinates (”UV2”), use
``PhysicallyBasedMaterial/secondaryTextureCoordinateTransform``.
set · iOS 15.0+
textureCoordinateTransform
TypeScript
set textureCoordinateTransform(value: MaterialParameterTypes_TextureCoordinateTransform)
Swift declaration
var textureCoordinateTransform: PhysicallyBasedMaterial.TextureCoordinateTransform { get set }
A two-dimensional transformation to apply to the entity’s primary
texture coordinates.
An entity’s UV texture coordinates control how RealityKit materials map
image textures onto an entity. This property allows you to transform the
texture coordinates to change the way this material maps its textures.
You might, for example, change the scale of a property to apply a tiled,
repeating pattern, or continuously rotate or translate the texture
coordinates to animate materials to create special effects, such as fire
or flowing liquids.
The following example shows how to set a material’s UV transformation:
```swift
let rotationRadians = Float(45.0) * .pi / 180 // 45 degrees converted to radians.
material.textureCoordinateTransform = .init(offset: SIMD2<Float>(x:0.5, y: 0.5),
scale: SIMD2<Float>(x:0.5, y: 0.5),
rotation: rotationRadians)
```
Some entities imported from USDZ files have more than one set of UV
coordinates. This property affects the primary UV set (sometimes called
“UV1”). To transform the secondary UV coordinates (”UV2”), use
``PhysicallyBasedMaterial/secondaryTextureCoordinateTransform``.
get · iOS 27.0+
subsurfaceScatterAnisotropy
TypeScript
get subsurfaceScatterAnisotropy(): PhysicallyBasedMaterial_SubsurfaceScatterAnisotropy
Swift declaration
var subsurfaceScatterAnisotropy: PhysicallyBasedMaterial.SubsurfaceScatterAnisotropy { get set }
set · iOS 27.0+
subsurfaceScatterAnisotropy
TypeScript
set subsurfaceScatterAnisotropy(value: PhysicallyBasedMaterial_SubsurfaceScatterAnisotropy)
Swift declaration
var subsurfaceScatterAnisotropy: PhysicallyBasedMaterial.SubsurfaceScatterAnisotropy { get set }
get · iOS 15.0+
secondaryTextureCoordinateTransform
TypeScript
get secondaryTextureCoordinateTransform(): MaterialParameterTypes_TextureCoordinateTransform
Swift declaration
var secondaryTextureCoordinateTransform: PhysicallyBasedMaterial.TextureCoordinateTransform { get set }
A two-dimensional transformation to apply to the entity’s secondary
texture coordinates.
An entity’s UV texture coordinates define how RealityKit maps image
textures onto an entity. This property allows you to transform the
secondary texture coordinates to change the way this material maps
textures onto an entity. If an entity has multiple materials assigned to
it, the transformation doesn’t affect how the other materials map their
textures.
You might, for example, change the scale of the UV coordinates to apply
a tiled, repeating pattern to the surface of your entity, or
continuously rotate or translate the texture coordinates to animate
materials to create special effects, such as fire or flowing liquids.
The following example demonstrates how to set a material’s UV
transformation:
```swift
let rotationRadians = Float(45.0) * .pi / 180 // 45 degrees converted to radians.
secondaryTextureCoordinateTransform =.init(offset: SIMD2<Float>(x:0.5, y: 0.5),
scale: SIMD2<Float>(x:0.5, y: 0.5),
rotation: rotationRadians)
```
Some entities imported from USDZ files have more than one set of UV
coordinates. This property transforms the secondary set. To transform
the primary UV coordinates in a material, see
``PhysicallyBasedMaterial/textureCoordinateTransform-swift.property``.
set · iOS 15.0+
secondaryTextureCoordinateTransform
TypeScript
set secondaryTextureCoordinateTransform(value: MaterialParameterTypes_TextureCoordinateTransform)
Swift declaration
var secondaryTextureCoordinateTransform: PhysicallyBasedMaterial.TextureCoordinateTransform { get set }
A two-dimensional transformation to apply to the entity’s secondary
texture coordinates.
An entity’s UV texture coordinates define how RealityKit maps image
textures onto an entity. This property allows you to transform the
secondary texture coordinates to change the way this material maps
textures onto an entity. If an entity has multiple materials assigned to
it, the transformation doesn’t affect how the other materials map their
textures.
You might, for example, change the scale of the UV coordinates to apply
a tiled, repeating pattern to the surface of your entity, or
continuously rotate or translate the texture coordinates to animate
materials to create special effects, such as fire or flowing liquids.
The following example demonstrates how to set a material’s UV
transformation:
```swift
let rotationRadians = Float(45.0) * .pi / 180 // 45 degrees converted to radians.
secondaryTextureCoordinateTransform =.init(offset: SIMD2<Float>(x:0.5, y: 0.5),
scale: SIMD2<Float>(x:0.5, y: 0.5),
rotation: rotationRadians)
```
Some entities imported from USDZ files have more than one set of UV
coordinates. This property transforms the secondary set. To transform
the primary UV coordinates in a material, see
``PhysicallyBasedMaterial/textureCoordinateTransform-swift.property``.
get · iOS 15.0+
sheen
TypeScript
get sheen(): (PhysicallyBasedMaterial_SheenColor) | null
Swift declaration
var sheen: PhysicallyBasedMaterial.SheenColor? { get set }
The intensity of an entity’s sheen.
For a ``PhysicallyBasedMaterial``, object, you can use `sheen` to add
soft specular highlights that simulate subtle reflections like the ones
that occur with some materials, primarily fabrics. You can specify
`sheen` using a single color, or you can provide a UV-mapped image.
The following example specifies `sheen` using a single value for the
entire material:
```swift
let sheenColor = PhysicallyBasedMaterial.Color(deviceRed: 0.8,
green: 0.8, blue: 0.8, alpha: 1.0)
material.sheen = .init(tint:sheenColor)
```
This example shows how to specify sheen using a UV-mapped image texture:
```swift
if let sheenResource = try? TextureResource.load(named:
"entity_sheen") {
let sheenMap = MaterialParameters.Texture(sheenResource)
material.sheen = .init(texture: sheenMap)
}
```
set · iOS 15.0+
sheen
TypeScript
set sheen(value: (PhysicallyBasedMaterial_SheenColor) | null)
Swift declaration
var sheen: PhysicallyBasedMaterial.SheenColor? { get set }
The intensity of an entity’s sheen.
For a ``PhysicallyBasedMaterial``, object, you can use `sheen` to add
soft specular highlights that simulate subtle reflections like the ones
that occur with some materials, primarily fabrics. You can specify
`sheen` using a single color, or you can provide a UV-mapped image.
The following example specifies `sheen` using a single value for the
entire material:
```swift
let sheenColor = PhysicallyBasedMaterial.Color(deviceRed: 0.8,
green: 0.8, blue: 0.8, alpha: 1.0)
material.sheen = .init(tint:sheenColor)
```
This example shows how to specify sheen using a UV-mapped image texture:
```swift
if let sheenResource = try? TextureResource.load(named:
"entity_sheen") {
let sheenMap = MaterialParameters.Texture(sheenResource)
material.sheen = .init(texture: sheenMap)
}
```
get · iOS 15.0+
normal
TypeScript
get normal(): PhysicallyBasedMaterial_Normal
Swift declaration
var normal: PhysicallyBasedMaterial.Normal { get set }
The normal map for the entity.
_Normal mapping_ is a real-time rendering technique that captures fine
surface details for a model using a texture instead of increasing the
number of polygons in the model. It works by storing _surface normals_,
which are vectors perpendicular to the surface of the model, from a much
higher resolution version of the same 3D object. A normal map stores
each vector in the image by storing the vectors’ `X`, `Y`, and `Z`
values as the `R`, `G`, and `B` components of the corresponding pixel in
the UV-mapped image.
If you provide a normal map, RealityKit uses the normals stored in the
image to do lighting calculations. This results in much more realistic
highlights, shadows, and reflections without incurring the computational
cost of using a much higher resolution 3D model. RealityKit uses
tangent-space normal maps.
The following code loads a normal map texture and uses it to set this
property:
```swift
if let normalResource = try? TextureResource.load(named:
"entity_normals") {
let normalMap = MaterialParameters.Texture(normalResource)
material.normal = PhysicallyBasedMaterial.Normal(texture:normalMap)
}
```
set · iOS 15.0+
normal
TypeScript
set normal(value: PhysicallyBasedMaterial_Normal)
Swift declaration
var normal: PhysicallyBasedMaterial.Normal { get set }
The normal map for the entity.
_Normal mapping_ is a real-time rendering technique that captures fine
surface details for a model using a texture instead of increasing the
number of polygons in the model. It works by storing _surface normals_,
which are vectors perpendicular to the surface of the model, from a much
higher resolution version of the same 3D object. A normal map stores
each vector in the image by storing the vectors’ `X`, `Y`, and `Z`
values as the `R`, `G`, and `B` components of the corresponding pixel in
the UV-mapped image.
If you provide a normal map, RealityKit uses the normals stored in the
image to do lighting calculations. This results in much more realistic
highlights, shadows, and reflections without incurring the computational
cost of using a much higher resolution 3D model. RealityKit uses
tangent-space normal maps.
The following code loads a normal map texture and uses it to set this
property:
```swift
if let normalResource = try? TextureResource.load(named:
"entity_normals") {
let normalMap = MaterialParameters.Texture(normalResource)
material.normal = PhysicallyBasedMaterial.Normal(texture:normalMap)
}
```
var program: PhysicallyBasedMaterial.Program { get set }
set · iOS 18.0+
program
TypeScript
set program(value: PhysicallyBasedMaterial_Program)
Swift declaration
var program: PhysicallyBasedMaterial.Program { get set }
get · iOS 15.0+
blending
TypeScript
get blending(): PhysicallyBasedMaterial_Blending
Swift declaration
var blending: PhysicallyBasedMaterial.Blending { get set }
The transparency of an entity.
Use this property to specify whether an entity is opaque or transparent.
To create an entity that’s opaque, assign
``PhysicallyBasedMaterial/Blending-swift.enum/opaque`` to this property.
```swift
material.blending = .opaque
```
To create a translucent or transparent object using a single opacity
value for the entire material, initialize
``PhysicallyBasedMaterial/Blending-swift.enum/transparent(opacity:)``
using a `Float` value.
```swift
material.blending = .transparent(opacity: .init(floatLiteral:0.5))
```
To use a UV-mapped grayscale image texture to specify different opacity
values for different parts of an entity, initialize
``PhysicallyBasedMaterial/Blending-swift.enum/transparent(opacity:)``
using a texture. If you provide a color image, RealityKit only uses the
intensity of the red channel.
```swift
if let opacityResource = try? TextureResource.load(named:
"entity_opacity") {
let opacityMap = MaterialParameters.Texture(opacityResource)
material.blending = .transparent(opacity: .init(texture: opacityMap))
}
```
set · iOS 15.0+
blending
TypeScript
set blending(value: PhysicallyBasedMaterial_Blending)
Swift declaration
var blending: PhysicallyBasedMaterial.Blending { get set }
The transparency of an entity.
Use this property to specify whether an entity is opaque or transparent.
To create an entity that’s opaque, assign
``PhysicallyBasedMaterial/Blending-swift.enum/opaque`` to this property.
```swift
material.blending = .opaque
```
To create a translucent or transparent object using a single opacity
value for the entire material, initialize
``PhysicallyBasedMaterial/Blending-swift.enum/transparent(opacity:)``
using a `Float` value.
```swift
material.blending = .transparent(opacity: .init(floatLiteral:0.5))
```
To use a UV-mapped grayscale image texture to specify different opacity
values for different parts of an entity, initialize
``PhysicallyBasedMaterial/Blending-swift.enum/transparent(opacity:)``
using a texture. If you provide a color image, RealityKit only uses the
intensity of the red channel.
```swift
if let opacityResource = try? TextureResource.load(named:
"entity_opacity") {
let opacityMap = MaterialParameters.Texture(opacityResource)
material.blending = .transparent(opacity: .init(texture: opacityMap))
}
```
get · iOS 15.0+
metallic
TypeScript
get metallic(): PhysicallyBasedMaterial_Metallic
Swift declaration
var metallic: PhysicallyBasedMaterial.Metallic { get set }
The reflectiveness of an entity.
The `metallic` property represents the reflectiveness of an entity. Use
this property to specify whether the entity displays metallic qualities
and reflects the surrounding environment, or displays dielectric
qualities and doesn’t reflect the environment.
Specify this property using a
<doc://com.apple.documentation/documentation/swift/float> to represent a
uniform reflectiveness for the entire entity. You an also use a
UV-mapped grayscale image to represent the reflectiveness of different
parts of the entity. When using an image, black pixels represent areas
that are dielectric, while white pixels represents areas that are
completely metallic and reflective.
If you initialize this property with a color image, rather than a
grayscale image, RealityKit only uses the intensity of the image’s red
channel.
The following example specifies the metallic qualities of an entity
using a single float value:
```swift
material.metallic = 1.0
```
The following example specifies the metallic qualities of an entity
using a UV-mapped image:
```swift
// Load a texture resource from a file.
let metalResource = try TextureResource.load(named: "entity_metallic")
// Set the texture to the metallic property.
let metallic = MaterialParameters.Texture(metalResource)
material.metallic = PhysicallyBasedMaterial.Metallic(texture: metallic)
```
set · iOS 15.0+
metallic
TypeScript
set metallic(value: PhysicallyBasedMaterial_Metallic)
Swift declaration
var metallic: PhysicallyBasedMaterial.Metallic { get set }
The reflectiveness of an entity.
The `metallic` property represents the reflectiveness of an entity. Use
this property to specify whether the entity displays metallic qualities
and reflects the surrounding environment, or displays dielectric
qualities and doesn’t reflect the environment.
Specify this property using a
<doc://com.apple.documentation/documentation/swift/float> to represent a
uniform reflectiveness for the entire entity. You an also use a
UV-mapped grayscale image to represent the reflectiveness of different
parts of the entity. When using an image, black pixels represent areas
that are dielectric, while white pixels represents areas that are
completely metallic and reflective.
If you initialize this property with a color image, rather than a
grayscale image, RealityKit only uses the intensity of the image’s red
channel.
The following example specifies the metallic qualities of an entity
using a single float value:
```swift
material.metallic = 1.0
```
The following example specifies the metallic qualities of an entity
using a UV-mapped image:
```swift
// Load a texture resource from a file.
let metalResource = try TextureResource.load(named: "entity_metallic")
// Set the texture to the metallic property.
let metallic = MaterialParameters.Texture(metalResource)
material.metallic = PhysicallyBasedMaterial.Metallic(texture: metallic)
```
get · iOS 15.0+
specular
TypeScript
get specular(): PhysicallyBasedMaterial_Specular
Swift declaration
var specular: PhysicallyBasedMaterial.Specular { get set }
The specular highlight applied to the entity.
In Physically Based Rendering (PBR), specular highlights primarily come
from the object’s ``PhysicallyBasedMaterial/roughness-swift.property``
value. RealityKit automatically renders materials that have a low
roughness value with specular highlights based on the environment
lighting and the shape of the entity. As a result, for most materials,
you won’t need to specify a `specular` value when using
``PhysicallyBasedMaterial``.
For some types of dielectric (nonmetallic) materials, like facet-cut
glass or gems, PBR algorithms don’t create bright enough specular
highlights using just roughness. To accurately simulate those types of
materials, use the ``PhysicallyBasedMaterial/specular-swift.property``
property to specify additional specular for the entity.
The following example demonstrates how to specify specular using a
single value for the entire material:
```swift
material.specular = .init(floatLiteral: 0.8)
```
This example shows how to specify specular using a UV-mapped image
texture:
```swift
if let specularResource = try? TextureResource.load(named:"entity_specular") {
let specularMap = MaterialParameters.Texture(specularResource)
material.specular = .init(texture: specularMap)
}
```
set · iOS 15.0+
specular
TypeScript
set specular(value: PhysicallyBasedMaterial_Specular)
Swift declaration
var specular: PhysicallyBasedMaterial.Specular { get set }
The specular highlight applied to the entity.
In Physically Based Rendering (PBR), specular highlights primarily come
from the object’s ``PhysicallyBasedMaterial/roughness-swift.property``
value. RealityKit automatically renders materials that have a low
roughness value with specular highlights based on the environment
lighting and the shape of the entity. As a result, for most materials,
you won’t need to specify a `specular` value when using
``PhysicallyBasedMaterial``.
For some types of dielectric (nonmetallic) materials, like facet-cut
glass or gems, PBR algorithms don’t create bright enough specular
highlights using just roughness. To accurately simulate those types of
materials, use the ``PhysicallyBasedMaterial/specular-swift.property``
property to specify additional specular for the entity.
The following example demonstrates how to specify specular using a
single value for the entire material:
```swift
material.specular = .init(floatLiteral: 0.8)
```
This example shows how to specify specular using a UV-mapped image
texture:
```swift
if let specularResource = try? TextureResource.load(named:"entity_specular") {
let specularMap = MaterialParameters.Texture(specularResource)
material.specular = .init(texture: specularMap)
}
```
get · iOS 15.0+
baseColor
TypeScript
get baseColor(): PhysicallyBasedMaterial_BaseColor
Swift declaration
var baseColor: PhysicallyBasedMaterial.BaseColor { get set }
The color of an entity unmodified by lighting.
The base color of an entity is either a solid color or a UV-mapped image
texture. This property represents the color of the entity before
RealityKit applies any lighting or rendering calculations.
To determine the appearance of the entity, RealityKit modifies the
entity’s base color using its material properties and the light sources
in the scene.
You can define an entity’s base color using a `CGColor`, a UV-mapped
image texture, or both. If you only provide a color, RealityKit uses
that as the base color for the entire entity. If you specify only an
image texture, it applies that texture as the base color of the entity.
If you provide both a color and a texture, RealityKit tints the image
texture using the color.
Here’s an example of using a single color to specify base color:
```swift
var material = PhysicallyBasedMaterial()
material.baseColor = PhysicallyBasedMaterial.BaseColor(tint:.red)
```
The following example demonstrates how to use an image to specify base
color:
```swift
var material = PhysicallyBasedMaterial()
// Load entity_basecolor.png from the app's bundle.
if let baseResource = try? TextureResource.load(named: "entity_basecolor") {
// Create a material parameter and assign it.
let baseColor = MaterialParameters.Texture(baseResource)
material.baseColor = PhysicallyBasedMaterial.BaseColor(texture:baseColor)
}
```
set · iOS 15.0+
baseColor
TypeScript
set baseColor(value: PhysicallyBasedMaterial_BaseColor)
Swift declaration
var baseColor: PhysicallyBasedMaterial.BaseColor { get set }
The color of an entity unmodified by lighting.
The base color of an entity is either a solid color or a UV-mapped image
texture. This property represents the color of the entity before
RealityKit applies any lighting or rendering calculations.
To determine the appearance of the entity, RealityKit modifies the
entity’s base color using its material properties and the light sources
in the scene.
You can define an entity’s base color using a `CGColor`, a UV-mapped
image texture, or both. If you only provide a color, RealityKit uses
that as the base color for the entire entity. If you specify only an
image texture, it applies that texture as the base color of the entity.
If you provide both a color and a texture, RealityKit tints the image
texture using the color.
Here’s an example of using a single color to specify base color:
```swift
var material = PhysicallyBasedMaterial()
material.baseColor = PhysicallyBasedMaterial.BaseColor(tint:.red)
```
The following example demonstrates how to use an image to specify base
color:
```swift
var material = PhysicallyBasedMaterial()
// Load entity_basecolor.png from the app's bundle.
if let baseResource = try? TextureResource.load(named: "entity_basecolor") {
// Create a material parameter and assign it.
let baseColor = MaterialParameters.Texture(baseResource)
material.baseColor = PhysicallyBasedMaterial.BaseColor(texture:baseColor)
}
```
get · iOS 15.0+
clearcoat
TypeScript
get clearcoat(): PhysicallyBasedMaterial_Clearcoat
Swift declaration
var clearcoat: PhysicallyBasedMaterial.Clearcoat { get set }
The transparent highlights that simulate a clear, shiny coating on an
entity.
An entity in RealityKit can display a clearcoat, which is a separate
layer of transparent specular highlights used to simulate a clear
transparent coating, like the paint on a car, or the surface of
lacquered objects. By default, materials don’t have clearcoat enabled.
Use this property to enable clearcoat rendering. Specifying any value
greater than `0.0` turns clearcoat rendering on. A value of `1.0`
indicates a full clearcoat. RealityKit treats values above `1.0` as if
they’re `1.0`.
You can specify ``PhysicallyBasedMaterial/clearcoat-swift.property``
using a single `Float` that applies to the entire material, or a
UV-mapped grayscale image to provide different values for different
parts of an entity.
The following example specifies `clearcoat` using a single value:
```swift
material.clearcoat = .init(floatLiteral: 0.8)
```
And this example shows how to specify `clearcoat` using a UV-mapped
image texture:
```swift
if let clearcoatResource = try? TextureResource.load(named:"entity_clearcoat") {
let clearcoatMap = MaterialParameters.Texture(clearcoatResource)
material.clearcoat = .init(texture: clearcoatMap)
}
```
set · iOS 15.0+
clearcoat
TypeScript
set clearcoat(value: PhysicallyBasedMaterial_Clearcoat)
Swift declaration
var clearcoat: PhysicallyBasedMaterial.Clearcoat { get set }
The transparent highlights that simulate a clear, shiny coating on an
entity.
An entity in RealityKit can display a clearcoat, which is a separate
layer of transparent specular highlights used to simulate a clear
transparent coating, like the paint on a car, or the surface of
lacquered objects. By default, materials don’t have clearcoat enabled.
Use this property to enable clearcoat rendering. Specifying any value
greater than `0.0` turns clearcoat rendering on. A value of `1.0`
indicates a full clearcoat. RealityKit treats values above `1.0` as if
they’re `1.0`.
You can specify ``PhysicallyBasedMaterial/clearcoat-swift.property``
using a single `Float` that applies to the entire material, or a
UV-mapped grayscale image to provide different values for different
parts of an entity.
The following example specifies `clearcoat` using a single value:
```swift
material.clearcoat = .init(floatLiteral: 0.8)
```
And this example shows how to specify `clearcoat` using a UV-mapped
image texture:
```swift
if let clearcoatResource = try? TextureResource.load(named:"entity_clearcoat") {
let clearcoatMap = MaterialParameters.Texture(clearcoatResource)
material.clearcoat = .init(texture: clearcoatMap)
}
```
get · iOS 15.0+
roughness
TypeScript
get roughness(): PhysicallyBasedMaterial_Roughness
Swift declaration
var roughness: PhysicallyBasedMaterial.Roughness { get set }
The amount the surface of the 3D object scatters reflected light.
The `roughness` property represents how much the surface of the entity
scatters light it reflects. A material with a high roughness has a matte
appearance, while one with a low roughness has a shiny appearance.
Specify this property using a
<doc://com.apple.documentation/documentation/swift/float> to represent a
uniform `roughness` for the entire entity, or a UV-mapped grayscale
image that uses shades of gray to represent the roughness of different
parts of the entity. When using an image, black pixels represent areas
that have a low roughness and appear shiny, while white represents areas
that have a high roughness and display a matte finish.
If you initialize this property with a color image rather than a
grayscale image, RealityKit only uses the intensity of the image’s red
channel.
The following example uses a single value to specify roughness:
```swift
material.roughness = PhysicallyBasedMaterial.Roughness(floatLiteral: 0.0)
```
The following example uses an image to specify roughness:
```swift
if let roughnessResource = try? TextureResource.load(named:
"entity_roughness") {
let roughness = MaterialParameters.Texture(roughnessResource)
material.roughness = PhysicallyBasedMaterial.Roughness(texture:roughness)
}
```
set · iOS 15.0+
roughness
TypeScript
set roughness(value: PhysicallyBasedMaterial_Roughness)
Swift declaration
var roughness: PhysicallyBasedMaterial.Roughness { get set }
The amount the surface of the 3D object scatters reflected light.
The `roughness` property represents how much the surface of the entity
scatters light it reflects. A material with a high roughness has a matte
appearance, while one with a low roughness has a shiny appearance.
Specify this property using a
<doc://com.apple.documentation/documentation/swift/float> to represent a
uniform `roughness` for the entire entity, or a UV-mapped grayscale
image that uses shades of gray to represent the roughness of different
parts of the entity. When using an image, black pixels represent areas
that have a low roughness and appear shiny, while white represents areas
that have a high roughness and display a matte finish.
If you initialize this property with a color image rather than a
grayscale image, RealityKit only uses the intensity of the image’s red
channel.
The following example uses a single value to specify roughness:
```swift
material.roughness = PhysicallyBasedMaterial.Roughness(floatLiteral: 0.0)
```
The following example uses an image to specify roughness:
```swift
if let roughnessResource = try? TextureResource.load(named:
"entity_roughness") {
let roughness = MaterialParameters.Texture(roughnessResource)
material.roughness = PhysicallyBasedMaterial.Roughness(texture:roughness)
}
```
