What's New / Spatial, 3D & RealityKit

What's new in _RealityKit_ComputeGraph

+42 NewiOS · macOS · tvOS

_RealityKit_ComputeGraph is a Swift cross-import overlay, not a standalone framework. Its API appears only when a target imports both RealityKit and ComputeGraph. It defines components that connect compute-graph pipelines to RealityKit entities, binding buffers, textures, uniforms, and simulation state.

The 27 SDK adds 42 APIs and removes or deprecates none. New types include the ComputeGraphComponent, ComputeGraphRuntimeComponent, ComputeGraphOutputComponent, and ComputeGraphViewpointComponent components, the SimulationState enum, and the UniformHandle, ParameterHandle, BufferInfo, and Dependencies structs. ComputeGraphComponent holds most of the surface, with members resource, pipelines, state, models, materials, and randomSeed, and methods setTexture, setBuffer, and setOutputEnabled.

New

42
struct

BufferInfo

NewiOSmacOStvOS
public struct BufferInfo
Declaration
public struct BufferInfo {

    public init(buffer: any MTLBuffer, bufferOffset: Int = 0, elementCount: Int)
}
struct

ComputeGraphComponent

NewiOSmacOStvOS
public struct ComputeGraphComponent : Component

A component that drives a compute graph–based particle simulation on an entity.

Attach this component to any Entity to with a loaded ComputeGraphResource and execute it each frame using Metal compute pipelines. The system automatically creates and manages child entities for each graph output, each carrying its own ModelComponent and material.

var component = ComputeGraphComponent(resource: resource)
entity.components.set(component)
Declaration
public struct ComputeGraphComponent : Component {

    /// Creates a `ComputeGraphComponent` with no resource attached.
    public init()
}
extension

ComputeGraphComponent.SimulationState

NewiOSmacOStvOS
extension ComputeGraphComponent.SimulationState : Equatable
Declaration
extension ComputeGraphComponent.SimulationState : Equatable {
}
extension

ComputeGraphComponent.SimulationState

NewiOSmacOStvOS
extension ComputeGraphComponent.SimulationState : Hashable
Declaration
extension ComputeGraphComponent.SimulationState : Hashable {
}
struct

ComputeGraphOutputComponent

NewiOSmacOStvOS
public struct ComputeGraphOutputComponent : TransientComponent

A transient component that identifies the compute graph output associated with an entity.

The system attaches this component to child entities that represent individual graph outputs. Use outputID to correlate the entity with a specific output inside the owning entity's running simulation.

Declaration
public struct ComputeGraphOutputComponent : TransientComponent {

    /// The identifier of the output node in the compute graph that this entity
    /// represents.
    public var outputID: ComputeNodeGraph.NodeID { get }
}
struct

ComputeGraphRuntimeComponent

NewiOSmacOStvOS
public struct ComputeGraphRuntimeComponent : TransientComponent

Manages the live GPU simulation for an entity's ComputeGraphComponent_v1.

RealityKit creates the ComputeGraphRuntimeComponent automatically on the first frame that a ComputeGraphComponent becomes active. You do not need to add it manually.

Declaration
public struct ComputeGraphRuntimeComponent : TransientComponent {
}
extension

ComputeGraphSharedUniforms

NewiOSmacOStvOS
extension ComputeGraphSharedUniforms
Declaration
extension ComputeGraphSharedUniforms {

    /// Stores a uniform value, replacing any previously stored value of the same type.
    ///
    /// - Parameter value: The value to store. Must conform to `BitwiseCopyable`.
    public func setUniform<V>(_ value: borrowing V) where V : BitwiseCopyable

    /// Returns the stored uniform value for the given type, or `nil` if none has been set.
    ///
    /// - Parameter type: The `BitwiseCopyable` type to retrieve.
    /// - Returns: The stored value, or `nil`.
    public func uniform<V>(_ type: V.Type) -> V? where V : BitwiseCopyable

    /// Registers a closure that transforms a uniform value of type `V` on a per-entity basis.
    ///
    /// The closure receives the current value and the entity being evaluated,
    /// and returns the transformed value. This lets you derive per-entity
    /// variants of a global uniform at simulation time, for example, converting
    /// a position from the scene's coordinate system to the system's coordinate system.
    ///
    /// - Parameter transform: A closure `(V, Entity) -> V`.
    public func setUniformTransform<V>(_ transform: @escaping (V, Entity) -> V) where V : BitwiseCopyable

    /// Registers a raw-data transformer closure for a uniform of type `V`.
    ///
    /// Use this overload when the transformation is most naturally expressed
    /// over the raw byte representation of the value.
    ///
    /// - Parameters:
    ///   - type: The `BitwiseCopyable` type the transformer operates on.
    ///   - transform: A closure `(inout MutableRawSpan, Entity) -> Void`.
    public func setUniformTransform<V>(type: V.Type, transform: @escaping @_lifetime(0: copy 0) (inout MutableRawSpan, Entity) -> Void) where V : BitwiseCopyable
}
struct

ComputeGraphViewpointComponent

NewiOSmacOStvOS
public struct ComputeGraphViewpointComponent : TransientComponent

A transient component that provides camera viewpoint information to the particle simulation.

Attach this component to an entity to supply the simulation with an observer's position and direction. The simulation uses these values for view-dependent effects such as billboard orientation or camera-facing particles.

Both properties are optional. When nil, the simulation falls back to its default viewpoint behavior.

Declaration
public struct ComputeGraphViewpointComponent : TransientComponent {

    /// The direction the observer is facing, in world space.
    public var viewDirection: SIMD3<Float>?

    /// The position of the observer, in world space.
    public var viewPosition: SIMD3<Float>?

    public init()
}
struct

ParameterHandle

NewiOSmacOStvOS
public struct ParameterHandle
Declaration
public struct ParameterHandle {
}
func

ComputeGraphComponent.fastForward

NewiOSmacOStvOS
public mutating func fastForward()

Fast-forwards the simulation using the default prewarm behavior.

func

ComputeGraphComponent.fastForward

NewiOSmacOStvOS
public mutating func fastForward(stepCount: Int, stepDeltaTime: Float)

Advances the particle simulation by multiple steps in a single operation.

Note: The simulation will be advanced by a total time of stepCount * stepDeltaTime seconds.

Parameters

stepCount
The number of simulation steps to execute. Each step represents one iteration of the simulation update cycle. Must be positive.
stepDeltaTime
The time interval (in seconds) to use for each simulation step.
func

ComputeGraphComponent.findBufferIndex

NewiOSmacOStvOS
public func findBufferIndex(port: ComputeNodeGraph.Port.Address) -> Int?
func

ComputeGraphComponent.firstBufferIndex

NewiOSmacOStvOS
public func firstBufferIndex(type: String) -> Int?
init

ComputeGraphComponent.init

NewiOSmacOStvOS
public init(resource: ComputeGraphResource)

Creates a ComputeGraphComponent and immediately attaches the given resource.

Parameters

resource
The ComputeGraphResource that defines the simulation.
func

ComputeGraphComponent.isOutputEnabled

NewiOSmacOStvOS
public func isOutputEnabled(_ outputID: ComputeNodeGraph.NodeID) -> Bool

Reads the enabled state of an output identified by ID

Returnsthe enabled state, or false if the output is unknown

var

ComputeGraphComponent.materials

NewiOSmacOStvOS
public var materials: [ComputeNodeGraph.NodeID : any Material]

Per-output material overrides, keyed by output node identifier.

When non-nil, these materials replace the corresponding materials defined in resource. Set to [:] to restore resource-defined materials.

var

ComputeGraphComponent.models

NewiOSmacOStvOS
public var models: [ComputeNodeGraph.NodeID : ModelComponent]

Per-output model component overrides, keyed by output node identifier.

When non-nil, these model components replace those defined in resource. Set to [:] to restore resource-defined models.

func

ComputeGraphComponent.pause

NewiOSmacOStvOS
public mutating func pause()

Pauses the simulation, freezing it at its current state.

var

ComputeGraphComponent.pipelines

NewiOSmacOStvOS
public var pipelines: ComputeNodeGraph.Pipelines?

The compiled pipelines used to execute the simulation.

When nil, the pipelines from resource are used. Assigning a value overrides the resource's pipelines without replacing the loaded assets.

func

ComputeGraphComponent.play

NewiOSmacOStvOS
public mutating func play()

Resumes the simulation from a paused or stepped state.

var

ComputeGraphComponent.randomSeed

NewiOSmacOStvOS
public var randomSeed: UInt32?

An optional fixed random seed for the simulation.

When nil, a random seed is chosen each time the simulation is (re)initialized.

func

ComputeGraphComponent.replaceUniforms

NewiOSmacOStvOS
public mutating func replaceUniforms(_ data: Data)

Replaces the entire uniform buffer with the given data.

You can query pipelines.assembly.uniformBufferSize for the required size. If too few bytes are provided, the remaining bytes retain their previous values.

Parameters

data
Raw bytes to write into the uniform buffer.
var

ComputeGraphComponent.resource

NewiOSmacOStvOS
public var resource: ComputeGraphResource?

The compute graph resource that defines the simulation.

Assigning a new resource replaces the current graph and resets the simulation. Set to nil to detach the resource without destroying the entity.

func

ComputeGraphComponent.setBuffer

NewiOSmacOStvOS
public mutating func setBuffer(_ buffer: (any MTLBuffer)?, bufferOffset: Int = 0, elementCount: Int? = nil, at index: Int)

Binds a Metal buffer to a parameter.

Parameters

buffer
The MTLBuffer to bind.
bufferOffset
Byte offset into buffer. Defaults to 0.
elementCount
Number of elements in the buffer, for buffers with variable capacity.
at
Index into the device buffers table.
func

ComputeGraphComponent.setOutputEnabled

NewiOSmacOStvOS
public mutating func setOutputEnabled(_ outputID: ComputeNodeGraph.NodeID, enabled: Bool)

Sets the enable state of an output identified by ID

This will cause the output mesh to disappear, and output stages to stop executing. The simulation, however, will continue to execute. See pause(), play(), and RealityKit.Entity.isEnabled to control the simulation as a whole

func

ComputeGraphComponent.setTexture

NewiOSmacOStvOS
public mutating func setTexture(_ texture: (any MTLTexture)?, at index: Int)

Binds a Metal texture to a parameter at the given index.

Parameters

texture
The MTLTexture to bind, or nil to unbind the current texture.
index
The index of the texture parameter in the texture table.
func

ComputeGraphComponent.setUniformData

NewiOSmacOStvOS
public mutating func setUniformData(_ data: RawSpan, for handle: ComputeGraphComponent.UniformHandle)

Sets the value of a uniform to raw bytes.

Parameters

data
Raw bytes to write into the uniform.
handle
The handle identifying the target uniform.
func

ComputeGraphComponent.setUniformValue

NewiOSmacOStvOS
public mutating func setUniformValue<V>(_ value: V, for handle: ComputeGraphComponent.UniformHandle) where V : BitwiseCopyable

Sets the value of a uniform to a BitwiseCopyable typed value.

Parameters

value
The value to write.
handle
The handle identifying the target uniform.
func

ComputeGraphComponent.setUniformValue

NewiOSmacOStvOS
public mutating func setUniformValue<V>(_ value: V, named name: String) -> Bool where V : BitwiseCopyable

Sets the value of a named uniform to a BitwiseCopyable typed value.

Parameters

value
The value to write.
name
The name of the uniform to update.

Returnstrue if the uniform was found and updated; false otherwise.

var

ComputeGraphComponent.simulationRate

NewiOSmacOStvOS
public var simulationRate: ComputeGraphSimulation.SimulationRate

The rate at which the simulation updates.

Defaults to default if no custom rate has been set.

enum

ComputeGraphComponent.SimulationState

NewiOSmacOStvOS
public enum SimulationState

The playback state of a compute graph simulation.

Declaration
public enum SimulationState {

    /// The simulation advances each frame at its configured rate.
    case playing

    /// The simulation is frozen; no steps are evaluated.
    case paused

    /// The simulation evaluates exactly one step on the next frame, then returns to ``paused``.
    case stepping

    /// Returns a Boolean value indicating whether two values are equal.
    ///
    /// Equality is the inverse of inequality. For any values `a` and `b`,
    /// `a == b` implies that `a != b` is `false`.
    ///
    /// - Parameters:
    ///   - lhs: A value to compare.
    ///   - rhs: Another value to compare.
    public static func == (a: ComputeGraphComponent.SimulationState, b: ComputeGraphComponent.SimulationState) -> Bool

    /// Hashes the essential components of this value by feeding them into the
    /// given hasher.
    ///
    /// Implement this method to conform to the `Hashable` protocol. The
    /// components used for hashing must be the same as the components compared
    /// in your type's `==` operator implementation. Call `hasher.combine(_:)`
    /// with each of these components.
    ///
    /// - Important: In your implementation of `hash(into:)`,
    ///   don't call `finalize()` on the `hasher` instance provided,
    ///   or replace it with a different instance.
    ///   Doing so may become a compile-time error in the future.
    ///
    /// - Parameter hasher: The hasher to use when combining the components
    ///   of this instance.
    public func hash(into hasher: inout Hasher)

    /// The hash value.
    ///
    /// Hash values are not guaranteed to be equal across different executions of
    /// your program. Do not save hash values to use during a future execution.
    ///
    /// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
    ///   conform to `Hashable`, implement the `hash(into:)` requirement instead.
    ///   The compiler provides an implementation for `hashValue` for you.
    public var hashValue: Int { get }
}
func

ComputeGraphComponent.spawn

NewiOSmacOStvOS
public mutating func spawn(element: ElementSpawnParameters, in system: ComputeNodeGraph.NodeID? = nil)

Spawns a new element in the particle simulation.

This method queues an element to be spawned during the next simulation update. The spawning is deferred and batched for performance reasons.

Note: The actual spawning occurs during the simulation update cycle.

Parameters

element
The spawn parameters defining the properties of the element to create
system
The ID of the specific system to spawn the element in. When nil, all systems will be asked to spawn the same element.
func

ComputeGraphComponent.spawn

NewiOSmacOStvOS
public mutating func spawn(elements: [ElementSpawnParameters], in system: ComputeNodeGraph.NodeID? = nil)

Spawns elements into the particle simulation.

This method queues an element to be spawned during the next simulation update. The spawning is deferred and batched for performance reasons.

Note: The actual spawning occurs during the simulation update cycle.

Parameters

element
The spawn parameters defining the properties of the element to create
system
The ID of the specific system to spawn the element in. When nil, all systems will be asked to spawn the same element.
var

ComputeGraphComponent.state

NewiOSmacOStvOS
public var state: ComputeGraphComponent.SimulationState

The current playback state of the simulation.

func

ComputeGraphComponent.step

NewiOSmacOStvOS
public mutating func step()

Advances the simulation by a single frame, then pauses.

func

ComputeGraphComponent.uniformHandle

NewiOSmacOStvOS
public func uniformHandle(named name: String) -> ComputeGraphComponent.UniformHandle?

Returns a handle for the named uniform.

Parameters

name
The name of the named uniform.

ReturnsA UniformHandle, or nil if no match is found.

struct

ComputeGraphComponent.UniformHandle

NewiOSmacOStvOS
public struct UniformHandle
Declaration
public struct UniformHandle {
}
struct

ComputeGraphResource.Dependencies

NewiOSmacOStvOS
public struct Dependencies
Declaration
public struct Dependencies {

    public init()

    public var outputMaterials: [ComputeNodeGraph.NodeID : any Material]

    public var outputModels: [ComputeNodeGraph.NodeID : ModelComponent]

    public var textures: [ComputeNodeGraph.Port.Address : TextureResource]

    public var buffers: [ComputeNodeGraph.Port.Address : ComputeGraphResource.BufferInfo]
}
init

ComputeGraphResource.init

NewiOSmacOStvOS
public convenience init(graph: ComputeNodeGraph, pipelines: ComputeNodeGraph.Pipelines, dependencies: ComputeGraphResource.Dependencies) throws
func

ComputeGraphRuntimeComponent.readOutput

NewiOSmacOStvOS
public func readOutput(_ port: ComputeNodeGraph.Port.Address) -> (any MTLBuffer)?

Returns the output buffer for the port at the given address.

Parameters

port
The port address of the output to read.

ReturnsThe MTLBuffer for that port, or nil if not found.

func

ComputeGraphRuntimeComponent.readOutputs

NewiOSmacOStvOS
public func readOutputs(_ node: ComputeNodeGraph.NodeID) -> [any MTLBuffer]?

Returns all output buffers for the given output node.

Parameters

node
The node identifier whose output buffers should be read.

ReturnsAn array of MTLBuffer objects, or nil if the node identifier is invalid or no output buffers are found.

var

ComputeGraphRuntimeComponent.simulation

NewiOSmacOStvOS
public var simulation: ComputeGraphSimulation { get }

The underlying compute graph simulation driving this entity.

No APIs match your filter.

← More in Spatial, 3D & RealityKit