Drawing in the air and on surfaces with a spatial stylus

At a glance

Project structure

Source bundle/
├── ARKit-SurfaceInking/ARKit-SurfaceInking/SurfaceInkingApp.swift  # SurfaceInkingApp
├── ARKit-SurfaceInking/ARKit-SurfaceInking/Drawing/DrawingInputProvider.swift  # StylusAnchorInput, DrawingInputProvider, TrackingMode
├── ARKit-SurfaceInking/ARKit-SurfaceInking/Models/AppModel.swift  # AppModel, ImmersiveSpaceState, DrawingSettings
├── ARKit-SurfaceInking/ARKit-SurfaceInking/Models/StylusModel.swift  # StylusButtonInput, Source, StylusModel
├── ARKit-SurfaceInking/ARKit-SurfaceInking/Views/StylusDrawingSettingsView.swift  # StylusDrawingSettingsView, StylusSettingsHeaderView, StylusSettingsBodyView
├── ARKit-SurfaceInking/ARKit-SurfaceInking/Utilities/CurveProcessing.swift  # HermiteInterpolant, HermiteControlPoint, SubdivisionSearchItem
├── ARKit-SurfaceInking/ARKit-SurfaceInking/Drawing/Mesh/BrushComponent.swift  # BrushComponent, BrushSystem
├── ARKit-SurfaceInking/ARKit-SurfaceInking/Drawing/Style/BrushStyleProvider.swift  # BrushStyleProvider, ThicknessType, Settings
└── ARKit-SurfaceInking/Packages/RealityKitContent/Package.realitycomposerpro/ProjectData/main.json  # authored RealityKit content

Structure observations

• The runtime boundary is WindowGroup + ImmersiveSpace; the pruned tree lists only files that explain lifecycle, state, or framework integration.
• App code is split into role-named views, models, managers, providers, components, or systems.
• Authored .reality or Reality Composer Pro content is a real implementation boundary; Swift loads or drives it rather than reproducing its entity graph.

Overall architecture

flowchart LR
    SurfaceInkingApp_1["SurfaceInkingApp"]
    WindowGroup___ImmersiveSpace_2["WindowGroup + ImmersiveSpace"]
    StylusDrawingSettingsView_3["StylusDrawingSettingsView"]
    AppModel_4["AppModel"]
    RealityView_entity_graph_5["RealityView entity graph"]
    ARKit_providers___RealityKit_6["ARKit providers + RealityKit"]
    SurfaceInkingApp_1 --> WindowGroup___ImmersiveSpace_2
    WindowGroup___ImmersiveSpace_2 --> StylusDrawingSettingsView_3
    StylusDrawingSettingsView_3 --> AppModel_4
    AppModel_4 --> RealityView_entity_graph_5
    RealityView_entity_graph_5 --> ARKit_providers___RealityKit_6

Reference code

ARKit-SurfaceInking/ARKit-SurfaceInking/SurfaceInkingApp.swift:12 — the app or executable entry declares the outer scene lifecycle.

struct SurfaceInkingApp: App {
    // ...
}

The diagram is a responsibility flow, not a claim that every adjacent node directly calls the next. It keeps scene ownership, shared state, RealityKit content, and framework-provider work at separate levels.

Ownership and state

classDiagram
    SurfaceInkingApp *-- AppModel : appModel
    SurfaceInkingApp *-- StylusModel : stylusModel
    StylusDrawingSettingsView o-- AppModel : appModel
    StylusInputState --> AppModel : appModel

Ownership evidence

ARKit-SurfaceInking/ARKit-SurfaceInking/SurfaceInkingApp.swift:14 — representative stored state or the nearest verified lifecycle anchor.

@main
struct SurfaceInkingApp: App {
    // ...
    private let appModel = AppModel()
    // ...
}

Ownership here is deliberately narrow: @Environment and weak references are shared links, initialized @State or stored services are lifecycle ownership, and a RealityView content closure owns additions to its entity graph without making the SwiftUI view a reference-type owner.

Class and protocol design

Verified protocol-oriented seams: Float → HermiteInterpolant, SIMD2 → HermiteInterpolant, SIMD3 → HermiteInterpolant, SIMD4 → HermiteInterpolant. Framework conformances remain adapters, not proof of an app-wide protocol architecture.

Access control

No reviewed declaration uses fileprivate, open; unmodified Swift declarations are internal.

Reference code

ARKit-SurfaceInking/ARKit-SurfaceInking/Drawing/CurveProcessing/SmoothCurveSampler.swift:31 — representative visibility boundary.

    private(set) var curve: DrawingMeshGenerator
    
    /// A parameter that determines how closely the samples the smooth curve sampler generates should conform to the ideal smoothed curve.
    ///
    /// Lower values of flatness results in more samples but a smoother curve.
    public let flatness: Float

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: SurfaceInkingApp; Model: AppModel, StylusModel; Provider: BrushStyleProvider, DrawingInputProvider; View: BrushStyleView, BrushTypeView, DeveloperDrawingMediumSettingsView, DeveloperSettingsView, ImmersiveDrawingView.
• ECS names pair data and behavior: components none; systems BrushSystem.
• Protocols: HermiteInterpolant.
• Commands use verb-led methods: isButtonPressed, getButtonPressure, getDrawingMedium, getChangedButtonInputIndex, updateButtonInputs, pruneButtonInputs, getCurrentDrawingMedium, getAnchorInput.
• Files generally match their primary type; Views, Models, Managers, Providers, Components, Systems, and Packages folders describe architectural roles where present.

Architecture takeaways

• Treat SurfaceInkingApp as the owner of scene declarations, not as the owner of every RealityKit entity created later.
• Keep view-local interaction in SwiftUI, but move provider sessions, playback resources, shared game state, or transport state into a stable owner when their lifetime exceeds one render pass.
• Run ARKit providers for the scene lifetime and consume their asynchronous updates in cancellable tasks; map anchors to entities at the boundary.
• Model immersive-space open, transition, and close states explicitly so windows and immersive content cannot drift apart.

Source map

• Official Apple documentation