A material that makes the mesh part a portal to a different world.
You use a `PortalMaterial` with ``PortalComponent`` and ``WorldComponent`` to enable portal features.
You can set this material on individual mesh parts. For example, create a box with
``MeshResource/generateBox(width:height:depth:cornerRadius:splitFaces:)-7m6ha``.
It can have some faces using ``PhysicallyBasedMaterial`` and some faces using `PortalMaterial`.
```swift
let portal = Entity()
// When you set `splitFaces` to `true`, each face takes up a different material slot.
let cyanMaterial = SimpleMaterial(color: .cyan, isMetallic: false)
portal.components.set(ModelComponent(
mesh: .generateBox(width: 0.5, height: 0.5, depth: 0.5, splitFaces: true),
materials: [PortalMaterial(),
cyanMaterial,
cyanMaterial,
cyanMaterial,
cyanMaterial,
cyanMaterial]
))
// Because the box has `0.5 x 0.5 x 0.5` dimensions,
// offset the portal plane on the z-axis by 0.25 so that
// it's at the front of the cube.
// Make sure it faces toward the positive z-direction.
portal.components.set(PortalComponent(
target: world,
clippingMode: .disabled,
crossingMode: .plane(PortalComponent.Plane(position: [0, 0, 0.25], normal: [0, 0, 1]))
))
```
RealityKit treats each mesh part with a `PortalMaterial` as a different portal, even if they
are pointing to the same world. Beware of the performance impact of this usage.
See ``PortalComponent`` for example usage.
Members (13)
get · iOS 18.0+
faceCulling
TypeScript
get faceCulling(): MaterialParameterTypes_FaceCulling
Swift declaration
var faceCulling: PortalMaterial.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 18.0+
faceCulling
TypeScript
set faceCulling(value: MaterialParameterTypes_FaceCulling)
Swift declaration
var faceCulling: PortalMaterial.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.
Returns the value of a parameter by name.
- Parameter name: The name of the parameter as declared in the shader
graph.
- Returns: The current value of the parameter, or `nil` if the parameter
has no value set on this material.
Returns the value of a parameter identified by a handle.
- Parameter handle: A handle previously returned by
``parameterHandle(name:)``.
- Returns: The current value of the parameter, or `nil` if the parameter
has no value set on this material.
mutating func setParameter(name: String, value newValue: MaterialParameters.Value) throws
Sets the value of a parameter by name.
Call this method to drive a shader-graph input from Swift — for example,
to animate a portal's opacity each frame, or to swap in a different
texture in response to user input.
- Parameters:
- name: The name of the parameter as declared in the shader graph.
- value: The new value to assign to the parameter.
- Throws: An error if the parameter doesn't exist on this material's
program, or if the value's type doesn't match the parameter's
declared type.
mutating func setParameter(handle: MaterialParameters.Handle, value newValue: MaterialParameters.Value) throws
Sets the value of a parameter identified by a handle.
Use this overload alongside ``parameterHandle(name:)`` when you update
the same parameter often enough that avoiding repeated name lookups
matters. For one-off updates, ``setParameter(name:value:)`` is more
readable.
- Parameters:
- handle: A handle previously returned by ``parameterHandle(name:)``.
- value: The new value to assign to the parameter.
- Throws: An error if the parameter doesn't exist on this material's
program, or if the value's type doesn't match the parameter's
declared type.
Returns a handle for the parameter with the given name.
Handles bypass the per-call string lookup that
``setParameter(name:value:)`` and ``getParameter(name:)`` perform. In
performance-sensitive code that updates the same parameter every frame,
obtain a handle once during setup and reuse it.
- Parameter name: The name of the parameter as declared in the shader
graph.
- Returns: A handle that identifies the parameter on any
``PortalMaterial`` whose program declares an input with the given
name.
get · iOS 18.0+
triangleFillMode
TypeScript
get triangleFillMode(): MaterialParameterTypes_TriangleFillMode
Swift declaration
var triangleFillMode: PortalMaterial.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: PortalMaterial.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.
Creates a portal material from a previously compiled program.
Because ``PortalMaterial/Program/init(descriptor:)`` is asynchronous,
preload the programs your scene needs once during setup, then use this
initializer to instantiate portal materials from them synchronously at
runtime — for example, when populating a model component each frame.
After creating the material, bind its shader inputs by calling
``setParameter(name:value:)`` or ``setParameter(handle:value:)``.
- Parameter program: A compiled portal program. The resulting material
shares the program's compiled shader artifact.
get · iOS 27.0+
program
TypeScript
get program(): PortalMaterial_Program
Swift declaration
var program: PortalMaterial.Program { get set }
The compiled program that drives this material's surface and geometry shading.
Read this property to recover the program a portal material was created
with — for example, to share it with another ``PortalMaterial``. Assign
a new program to swap a portal's shading without rebuilding the
material; the material's existing parameter bindings are preserved, and
bindings whose names and types match inputs on the new program's
shader graph keep working. Bindings that don't match are ignored at
render time — re-bind any new inputs the program introduces before
drawing the portal.
set · iOS 27.0+
program
TypeScript
set program(value: PortalMaterial_Program)
Swift declaration
var program: PortalMaterial.Program { get set }
The compiled program that drives this material's surface and geometry shading.
Read this property to recover the program a portal material was created
with — for example, to share it with another ``PortalMaterial``. Assign
a new program to swap a portal's shading without rebuilding the
material; the material's existing parameter bindings are preserved, and
bindings whose names and types match inputs on the new program's
shader graph keep working. Bindings that don't match are ignored at
render time — re-bind any new inputs the program introduces before
drawing the portal.
