2nd/10_Wiki/Topics/Coding/iOS_visionOS_Basics.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
ios-visionos-basics	visionOS — 공간 컴퓨팅 / RealityKit / Window	Coding	draft	B	conceptual	2026-05-09	2026-05-09	ios visionos vision-pro realitykit vibe-coding	language applicable_to Swift / SwiftUI / RealityKit visionOS		visionOS Vision Pro immersive space window group RealityKit

visionOS

Apple Vision Pro. 3가지 mode: Window (2D 패널) / Volume (3D 박스) / Immersive (전체). SwiftUI 같은 코드로 시작 가능. RealityKit 으로 3D.

📖 핵심 개념

• Window: 일반 SwiftUI window — visionOS 가 자동 floating panel.
• Volume: 작은 3D 공간 (박스).
• Immersive: 전체 환경 (mixed / full).
• Eye + pinch: 보고 + 손가락 핀치 = 탭.

💻 코드 패턴

Window

@main
struct VisionApp: App {
    var body: some Scene {
        WindowGroup(id: "main") {
            ContentView()
        }
        // 일반 SwiftUI 작동 — 3D 공간 floating window
    }
}

Volume (3D 컨테이너)

WindowGroup(id: "globe") {
    GlobeView()
}
.windowStyle(.volumetric)
.defaultSize(width: 0.5, height: 0.5, depth: 0.5, in: .meters)

struct GlobeView: View {
    var body: some View {
        Model3D(named: "Earth") { model in
            model.resizable().scaledToFit()
        } placeholder: {
            ProgressView()
        }
    }
}

Immersive Space

@main
struct VisionApp: App {
    var body: some Scene {
        WindowGroup { ContentView() }
        ImmersiveSpace(id: "world") {
            ImmersiveView()
        }
        .immersionStyle(selection: .constant(.mixed), in: .mixed, .full)
    }
}

struct ContentView: View {
    @Environment(\.openImmersiveSpace) var open
    var body: some View {
        Button("Enter") { Task { await open(id: "world") } }
    }
}

RealityKit (3D scene)

struct ImmersiveView: View {
    var body: some View {
        RealityView { content in
            let earth = ModelEntity(mesh: .generateSphere(radius: 0.2))
            earth.model?.materials = [SimpleMaterial(color: .blue, isMetallic: false)]
            earth.position = [0, 1.5, -1]
            content.add(earth)
        } update: { content in
            // 매 frame
        }
    }
}

Gesture (RealityKit)

RealityView { content in ... }
    .gesture(
        DragGesture()
            .targetedToAnyEntity()
            .onChanged { value in
                value.entity.position = value.convert(value.location3D, from: .local, to: value.entity.parent!)
            }
    )

Hover 효과

Image(systemName: "heart")
    .hoverEffect(.lift) // 사용자가 보면 lift

.hoverEffect(.highlight) // 윤곽

안경 / 환경 감지

import ARKit

let session = ARKitSession()
let handTracking = HandTrackingProvider()
try await session.run([handTracking])

for await update in handTracking.anchorUpdates {
    // hand pose
}

Anchor

let anchor = AnchorEntity(.hand(.left, location: .palm))
content.add(anchor)
// 손에 따라다님

Spatial audio

let audioRes = try await AudioFileResource.load(named: "ambient.wav")
let player = entity.prepareAudio(audioRes)
player.gain = -10
player.play()

Eye tracking 권한

• Privacy 강함. Direct gaze 위치는 OS 처리, 앱은 hover 만.

Sharing window between iOS / visionOS

#if os(visionOS)
.windowStyle(.volumetric)
#endif

🤔 의사결정 기준

콘텐츠	mode
기존 iPad app	Window (Compatible)
일반 productivity	Window
3D 모델 viewer	Volume
게임 / 몰입	ImmersiveSpace
AR 위 가상 객체	Mixed immersion
완전 가상	Full immersion

❌ 안티패턴

• iOS UI 그대로: visionOS hover / spatial 활용 X.
• Eye tracking 데이터 수집 가정: 가능 X. privacy.
• Modal 거대 화면 가운데: Window depth 고려 + glass material 사용.
• Audio 평면 stereo: spatial 권장.
• Hand tracking 없는 immersive: 사용자 손 보임 — 방해.
• RealityKit ECS 무시 + Entity 만: 큰 scene 성능.
• Glass material 안 사용: visionOS UI 와 어색.

🤖 LLM 활용 힌트

• 시작 = Window (iOS app 그대로).
• 3D = Volume + Model3D / RealityView.
• 몰입 = ImmersiveSpace + RealityKit.

🔗 관련 문서

• iOS_SwiftUI_State_Property_Wrappers
• iOS_Live_Activities
• iOS_TipKit_Patterns