Rendering a windowed game in stereo

At a glance

Project structure

Source bundle/
├── RealityKit-Stereo-Rendering/RealityKitStereoRenderingApp.swift  # MetalVRRPortalSampleApp, WindowView, OnDismiss
├── RealityKit-Stereo-Rendering/DeferredLighting/Renderer/Renderer.swift  # Renderer, DrawableProviding
├── RealityKit-Stereo-Rendering/DeferredLighting/Renderer/SinglePassDeferredRenderer.swift  # SinglePassDeferredRenderer
├── RealityKit-Stereo-Rendering/DeferredLighting/Renderer/TraditionalDeferredRenderer.swift  # TraditionalDeferredRenderer
├── RealityKit-Stereo-Rendering/DeferredLighting/DeferredLightingView.swift  # DeferredLightingComponent, DeferredLightingEntity, DeferredLightingSystem
├── RealityKit-Stereo-Rendering/DeferredLighting/Renderer/Utilities/RenderDestination.swift  # RenderDestination
├── RealityKit-Stereo-Rendering/MetalVRREntity.swift  # RateFactors, RateFactorProviding, RateIndicator
└── Packages/RealityKit-Assets/Package.realitycomposerpro/ProjectData/main.json  # authored RealityKit content

Structure observations

• The runtime boundary is WindowGroup + volumetric window + ImmersiveSpace + SwiftUI/UIKit host; the tree is pruned to lifecycle, state, framework, rendering, and ECS files.
• The source is C/Objective-C header, Metal, Swift; role-named types and feature folders separate the major responsibilities.
• Authored .reality, .rkassets, or Reality Composer Pro content is an implementation boundary; Swift loads or drives it rather than reproducing its entity graph.

Overall architecture

flowchart LR
    MetalVRRPortalSampleApp_1["MetalVRRPortalSampleApp"]
    WindowGroup___volumetric_window___ImmersiveSpace___SwiftUI_UIKit_host_2["WindowGroup + volumetric window + ImmersiveSpace + SwiftUI/UIKit host"]
    DeferredLightingView_3["DeferredLightingView"]
    Renderer_4["Renderer"]
    RealityKit_entity_graph_5["RealityKit entity graph"]
    head_pose___stereo_Metal_renderer_6["head pose + stereo Metal renderer"]
    MetalVRRPortalSampleApp_1 --> WindowGroup___volumetric_window___ImmersiveSpace___SwiftUI_UIKit_host_2
    WindowGroup___volumetric_window___ImmersiveSpace___SwiftUI_UIKit_host_2 --> DeferredLightingView_3
    DeferredLightingView_3 --> Renderer_4
    Renderer_4 --> RealityKit_entity_graph_5
    RealityKit_entity_graph_5 --> head_pose___stereo_Metal_renderer_6

Reference code

RealityKit-Stereo-Rendering/RealityKitStereoRenderingApp.swift:13 — executable or app-lifecycle anchor.

struct MetalVRRPortalSampleApp: App {
    // ...
}

The diagram is a responsibility flow, not a claim that every adjacent node directly calls the next. It separates lifecycle, presentation, stable state, framework/session work, and the RealityKit entity graph.

Ownership and state

classDiagram
    DeferredLightingView *-- MetalVRREntity : renderEntity
    DeferredLightingView *-- Entity : root3DFrame
    DeferredLightingView *-- Entity : root
    DeferredLightingView *-- HeadPositionProvider : headTracker

Ownership evidence

RealityKit-Stereo-Rendering/DeferredLighting/DeferredLightingView.swift:282 — representative stored state or nearest verified lifecycle anchor.

struct DeferredLightingView: View {
    // ...
    @State var renderEntity: MetalVRREntity?
    // ...
}

Ownership is intentionally narrow: environment, bindings, observed objects, weak links, and delegate callbacks do not prove lifetime ownership. Initialized stored services and wrapper-managed state do; entities added inside a RealityKit content closure belong to that entity graph.

Class and protocol design

Verified protocol-oriented seams: ResolutionProbeGrid → RateFactorProviding, DeferredLightingEntity → DrawableProviding, DeferredLightingEntity → RenderDestination, MTKView → DrawableProviding, MTKView → RenderDestination. Framework conformances remain adapters, not proof of an app-wide protocol architecture.

Access control

No reviewed Swift access example uses private(set), open; declarations without a modifier are internal.

Objective-C/C header and implementation visibility is documented separately from Swift lexical access control.

Reference code

RealityKit-Stereo-Rendering/DeferredLighting/DeferredLightingView.swift:285 — representative visibility boundary.

struct DeferredLightingView: View {
    // ...
    @Environment(\.openWindow) private var openWindow
    // ...
}

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: MetalVRRPortalSampleApp; Controller: ViewController; Provider: HeadPositionProvider; Renderer: Renderer, SinglePassDeferredRenderer, TraditionalDeferredRenderer; System: DeferredLightingSystem, ResolutionProbeSystem.
• ECS names pair data and behavior: components DeferredLightingComponent; systems DeferredLightingSystem, ResolutionProbeSystem.
• Protocols: DrawableProviding, RenderDestination, RateFactorProviding.
• Commands use verb-led methods: beginFrame, beginDrawableCommands, endFrame, encodePass, encodeStage, encodeGBufferStage, encodeDirectionalLightingStage, encodeLightMaskStage.
• Files and folders use primary-type or responsibility names such as Views, Models, Rendering, Components, Systems, Packages, or feature names where those boundaries exist.

Architecture takeaways

• Treat MetalVRRPortalSampleApp as the owner of executable or scene lifecycle, not automatically as the owner of every entity created later.
• Keep view/controller input near presentation, but move sessions, reconstruction, capture, rendering, shared game state, or documents into stable owners when their lifetime exceeds one callback or render pass.
• Use components for per-entity data and systems for repeated simulation instead of centralizing every update in a view model or controller.
• Count authored Reality Composer Pro assets as implementation; the Swift shell is not the complete architecture.

Source map

• Official Apple documentation