daniel-lynch--ovrplugin-openxr-shim/TESTING.md

# Testing the shim — strategy & plan

We do NOT need Steam Frame to validate the hard part. The shim's whole job is
OVRPlugin -> OpenXR, and **the Quest 2 already runs an OpenXR runtime** (Meta's
Horizon OS runtime — the one that replaced VrApi). So the shim can be tested on
hardware we own, today.

## The three paths

| Path | Tests what | Available | Effort |
|------|-----------|-----------|--------|
| **A. Quest 2 + shim swap** | the real shim, real HW, real game, on Meta's OpenXR runtime | now | NDK arm64 build + Android instance handshake + manifest (real entitlement — you own it) |
| **B. Monado-sim harness** | the shim's OpenXR call logic, fast iteration | now | small C harness + Linux arm64 (VM on the Apple-Silicon MacBook) |
| **C. Steam Frame + Lepton** | the actual target (Monado under Lepton) | ~summer 2026 | everything |

Recommended order: **B for fast logic iteration, then A for the real proof.**
A is the thesis-validator; if RE4 renders on the Quest through our OpenXR shim
instead of libvrapi.so, the project is essentially proven.

---

## Path A — Quest 2 (the real test)

Idea: build the shim as an Android arm64 `.so`, drop it into the RE4 APK in place
of the real `libOVRPlugin.so`, sideload, run. Our shim calls the Quest's own
`libopenxr_loader` -> Meta's OpenXR runtime.

Prereqs to do first (these are the currently-open work items):
1. **NDK arm64 build** of the shim — DONE. `shim/build_android.sh` -> NDK r27c ->
   build/arm64/libOVRPlugin.so (aarch64, 438/438 drop-in, NEEDED libopenxr_loader).
2. **Instance handshake** — DONE. src/android_init.c: JNI_OnLoad captures the JavaVM;
   xrr_pre_init calls xrInitializeLoaderKHR + enables XR_KHR_android_create_instance
   + chains XrInstanceCreateInfoAndroidKHR. Activity from Initialize5 arg4 with an
   Application-context reflection fallback. [VERIFY-ON-HW] whether Meta's runtime
   accepts the Application context vs requiring the real Activity, and the
   PreInitialize3-creates-instance-before-activity ordering.
3. **Manifest** — add the OpenXR usage declarations Meta's runtime expects
   (`<uses-feature android:name="android.hardware.vr.headtracking">` already there;
   add OpenXR `<meta-data>`/intent bits per Meta's OpenXR mobile docs).
4. **Entitlement** — on Quest you OWN RE4 and the Quest has the real Meta Horizon
   platform service, so leave the ORIGINAL libovrplatformloader.so untouched and only
   swap libOVRPlugin.so. Logged into the owning account, the real ovr_Entitlement check
   passes legitimately ("you own it"). **CONFIRMED on device 2026-06-29:** a
   debug-re-signed, legit-mode build (original libovrplatformloader.so, no stub) launches
   into the game on a Quest 2 — re-signing does **not** break the entitlement check.
   Entitlement handling on hardware with no Meta backend (e.g. Steam Frame) is out of
   scope for this repo and is the user's responsibility.

Then:
```
# repack (you own the copy; patch-only distribution)
unzip base.apk -d apk/
cp shim/build/arm64/libOVRPlugin.so apk/lib/arm64-v8a/libOVRPlugin.so
# rebuild + zipalign + sign with your own debug key, then:
adb install -r re4vr-shim.apk     # or push OBB + sideload
adb logcat | grep -iE 'xrr|OVRPlugin|openxr'   # watch the [xrr] logs
```
Expected first-run signal: instance/session create succeed in logcat; if the frame
loop spins and the projection layer submits, you get an image (even if poses/input
are rough). Known rough edges on first run: depth (Unsupported), input (controllers
return NotYetImplemented), the [VERIFY-ON-HW] swapchain index lockstep.

## Path B — Monado simulated (fast iteration, works on the Mac)

Monado has a simulated/headless HMD driver — no real headset. Run it in a Linux
arm64 VM (UTM/QEMU on Apple Silicon), point an OpenXR loader at it, and run the
harness (tests/harness.c) which drives the ovrp_* sequence:
  PreInitialize3 -> Initialize5 -> SetupLayer -> [WaitToBeginFrame -> BeginFrame4 ->
  GetNodePoseState3 -> EndFrame4] xN -> Shutdown2
and asserts each returns ovrpSuccess. This exercises the real OpenXR calls without
RE4 or hardware. Build:
```
# inside the Linux arm64 env, with Monado + openxr loader installed:
cc -std=c11 -Iinclude -Ithird_party/openxr tests/harness.c \
   src/*.c -lopenxr_loader -lvulkan -o harness   # needs a Vulkan device/headless
XR_RUNTIME_JSON=/path/to/monado/openxr_monado-dev.json ./harness
```
Note: Initialize5 needs real Vulkan handles; for a pure-logic smoke test the harness
can pass a headless VkInstance/Device (or we add a "no-gfx" build flag that skips
xrCreateSession to test the non-rendering calls first).

## Path C — Steam Frame (the target)

Same arm64 shim `.so`, but the APK runs under **Lepton** (Valve's Waydroid/AOSP) and
the OpenXR runtime is **Monado**. Once Frame ships: NDK build -> repack -> sideload
into Lepton -> the open question is whether Lepton exposes the OpenXR loader +
Vulkan swapchain sharing across the container (see HOST.md unknowns). Path A having
worked makes this mostly a packaging/runtime-plumbing exercise.

---

## Current state (what's ready to test vs not)

WIRED & building (host x86-64, validation only):
- Session lifecycle: instance/system/session create, event-driven state machine.
- Frame loop: xrWaitFrame/Begin/EndFrame, predicted display time.
- Poses: xrLocateViews (eyes) + xrLocateSpace (head).
- Swapchains: xrCreateSwapchain from ovrpLayerDesc, enumerate VkImages, per-frame
  acquire/wait/release, real XrCompositionLayerProjection submit.
- 20 OpenXR functions; 239/239 ovrp_ symbols.

NOT yet (the to-do list before a meaningful Quest run):
- arm64/Android NDK build (host build only so far).
- [ANDROID-TODO] JavaVM/activity -> XrInstanceCreateInfoAndroidKHR + xrInitializeLoaderKHR.
- Input: controller/hand action sets (GetControllerState4 returns NotYetImplemented).
- Depth layer (SetupLayerDepth -> Unsupported).
- Map ovrp_GetInstance/DeviceExtensionsVk -> xrGetVulkan*ExtensionsKHR (so the app
  creates its VkInstance/Device with the runtime's required extensions).
- [VERIFY-ON-HW] swapchain index lockstep assumption.

## Pick-up-tomorrow shortlist
1. Install Android NDK; cross-build the shim to arm64 (proves it builds for target).
2. Stand up the Monado-sim Linux arm64 VM on the Mac + run tests/harness.c (Path B
   smoke test of the non-gfx calls).
3. Then start the [ANDROID-TODO] instance handshake (gates the real Quest run).