ipin-vr/docs/POC_VR_SPEC.md

SPEC — VR Coexistence PoC (native OpenXR, Quest 3)

Apka pomiarowa, nie produkt. Cel: udowodnić, że na Quest 3 da się jednocześnie renderować scenę VR/MR i uruchamiać lokalny LLM i mówić (TTS) — wszystko w jednym procesie, offline — oraz zmierzyć, ile to kosztuje klatki, CPU/GPU, pamięć i temperaturę.

To jest pionowy plasterek Etapu 2 z ROADMAP, zbudowany jako narzędzie do pomiaru.

1. Co mierzymy (sens istnienia apki)

Podczas pracy ciągłej (render) + cyklicznej inferencji + TTS zbieramy:

• FPS / stale frames renderera w oknie generacji vs. w spoczynku,
• CPU/GPU utilization i temperaturę w czasie (soak ~15 min),
• latencję i throughput inferencji pod obciążeniem renderera (tok/s),
• PSS całego procesu.

Pomiar: OVR Metrics Tool (nakładka FPS/CPU/GPU/temp) + log apki do logcat.

2. Kryteria „zielono" (do walidacji, nie gwarancje)

• Renderer utrzymuje docelowe ≥72 FPS w trakcie generacji, bez kaskady stale frames.
• Generacja pod obciążeniem renderera ≥ ~10 tok/s (standalone było 23,6 @4 wątki).
• Całość < 5,75 GiB PSS (limit aplikacji immersyjnej Quest 3).
• Brak throttlingu do poziomu nieużywalnego w ciągu 15 min ciągłej pracy.

3. Architektura

Natywny C++ / Android NDK, jeden proces, arm64-v8a.

Wątki:

• Render thread — pętla klatek OpenXR (passthrough + panel tekstowy). Nigdy nie blokuje się na inferencji ani TTS.
• Inference worker — llama.cpp in-process, ładuje Qwen2.5-1.5B Q4 raz, generuje na żądanie. Cap 4 wątki (wynik z benchmarku: 6 wątków regresuje przez rdzenie efficiency). CPU affinity konfigurowalna (patrz §6).
• TTS/audio thread — sherpa-onnx (offline) syntezuje PCM, oddtwarzanie przez Oboe.

Przepływ na trigger: worker generuje polecenie → tekst trafia do render threada (panel) i do TTS threada (mowa). Render leci nieprzerwanie przez cały czas.

4. Punkt startu i zależności

NIE pisać OpenXR od zera. Start z sample'a passthrough z Meta OpenXR Mobile SDK (np. XrPassthrough); dokładamy worker LLM, TTS, panel i triggery.

Wendorowane zależności (jako podprojekty CMake / prebuilt arm64):

• llama.cpp — add_subdirectory, build arm64-v8a, OpenMP on, bez GPU. API biblioteczne (llama + common), nie serwer.
• sherpa-onnx — prebuilt Android arm64 (OfflineTts), używa głosu pl_PL-gosia (.onnx, ten sam co na PC). Ogarnia espeak-ng.
• Oboe — audio out (AAudio/OpenSL wrapper).
• stb_truetype.h — rasteryzacja tekstu polecenia do tekstury GL.

Model i głos NIE w APK: wgrywane na /sdcard/Android/data/<pkg>/files/ (lub /data/local/tmp) i ładowane po ścieżce. Model ~935 MiB.

5. Generator treści (zgodny z zasadą gramatyki)

Port leksykonu i reguł renderowania z docs/LEXICON.md + docs/SPEC.md §5 do C++ (OBJECTS/COLORS/LOCATIONS/VERBS + render()). Zasada bez zmian: powierzchniowy tekst tylko z leksykonu.

Rola LLM tutaj jest podwójna:

1. realistyczne obciążenie obliczeniowe (prawdziwa generacja N tokenów),
2. wybór elementów polecenia.

Worker odpala prawdziwą generację llama.cpp z naszym promptem; jeśli uda się sparsować JSON z ID — renderuje z nich, jeśli nie — fallback na losowy wybór z leksykonu. Tak czy siak gramatyka jest poprawna, a obciążenie CPU realne (o to chodzi w pomiarze).

6. Kontrakt wątków i CPU affinity (najważniejsze)

To tu rozstrzyga się koegzystencja. Na XR2 Gen 2 (2P + 4E):

• Render thread + kompozycja: zostawiamy je runtime'owi, ale apka nie odpala inferencji na tym samym rdzeniu.
• Inference worker: maska CPU konfigurowalna w runtime (sched_setaffinity / pthread_setaffinity_np), domyślnie tak, by NIE zajmować rdzenia renderera. Liczba wątków konfigurowalna (domyślnie 4), priorytet niższy niż render.
• TTS thread: osobny, niski priorytet.

Apka ma pozwalać zmieniać maskę i liczbę wątków bez rekompilacji (np. plik konfig albo argumenty intentu), żeby zmierzyć FPS przy różnych podziałach rdzeni.

7. UI / interakcja (minimalne)

• Passthrough on, jeden pływający panel przed użytkownikiem.
• Panel pokazuje: aktualne polecenie + live odczyt (ostatnia inferencja ms, tok/s, przybliżony FPS, PSS).
• Trigger generacji: przycisk kontrolera (np. A) oraz opcjonalny auto-loop co N sekund (do soak-testu). Bez obiektów 3D, bez scen — tylko panel. Render ma głównie istnieć i trzymać FPS.

8. Logowanie i soak

Apka loguje do logcat na każdą generację: liczba tokenów, ms, tok/s, peak VmRSS (/proc/self/status). Tryb soak: auto-trigger co ~10 s przez 15 min; równolegle OVR Metrics Tool zapisuje FPS/CPU/GPU/temp. Wynik = wykres FPS i temperatury w czasie.

9. Budżet pamięci (orientacyjnie, < 5,75 GiB)

• model Q4: ~1,1 GiB
• KV cache (krótki kontekst): ~50–150 MiB
• onnxruntime + głos Piper: ~0,1 GiB
• OpenXR runtime + GL + tekstury: ~0,3–0,5 GiB
• razem: ~1,6–1,9 GiB → duży zapas pod limitem.

10. Build / deploy

Android NDK + CMake + Gradle. arm64-v8a only. Loader OpenXR z Meta SDK. Podpis debug, adb install. Min SDK zgodny z Horizon OS (API 29+). Plan budowy fazami (patrz niżej), nie jednym strzałem.

11. Poza zakresem

STT, ocena wykonania, UX terapeutyczny, obiekty 3D, hand tracking, pakowanie do Store.

12. Fazy budowy (dla Claude Code)

1. Scaffold — sample passthrough Meta uruchomiony na Queście (czysty render, FPS w OVR).
2. LLM — wlinkować llama.cpp, worker ładuje model, generacja na trigger (log tok/s), na razie tekst tylko do logcat.
3. Affinity — maska/wątki konfigurowalne; zmierzyć wpływ na FPS.
4. TTS — sherpa-onnx + Oboe, wypowiada polecenie.
5. Panel — stb_truetype, tekst + live odczyt na panelu.
6. Soak + pomiar — auto-loop, logowanie, 15-min test.

Każdą fazę walidujemy na urządzeniu zanim ruszymy dalej.