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 (all done — kept as the record of what Path A needed):
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** — no change needed in the end. RE4 VR is already a shipping Quest VR app
   and declares `<uses-feature android:name="android.hardware.vr.headtracking">`;
   `packaging/inspect_manifest.sh` reports any gaps.
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
```
`packaging/repack.sh` now does the repack, align and re-sign in one step; the manual
sequence above is kept only to show what it does.

First-run signal to look for: instance and session create succeeding in logcat, then the
frame loop spinning and the projection layer submitting. (Historically the rough edges on a
first run were depth, input and the swapchain index lockstep; input and rendering are now
working — see "Current state" below.)

## Path B — desktop OpenXR harness (fast iteration) — BUILT

`tools/desktop-harness/` drives the `ovrp_*` sequence against a real OpenXR runtime with no
headset and no RE4:
  PreInitialize3 -> Initialize5 -> SetupLayer -> [WaitToBeginFrame -> BeginFrame4 ->
  GetNodePoseState3 -> EndFrame4] xN -> Shutdown2
asserting each returns `ovrpSuccess`. Build and run:
```
shim/build_host.sh                 # -> build/host/{libOVRPlugin.so,harness}
tools/desktop-harness/run.sh       # headless against monado-service
```
Needs libvulkan and an OpenXR loader (Debian: `libvulkan-dev libopenxr-loader1
libopenxr-dev`); without the loader `build_host.sh` compiles the objects and stops.

Worth adding when chasing a portability bug: run it with `VK_LAYER_KHRONOS_validation` and
the OpenXR core-validation API layer enabled. The harness currently passes without them, so
it does not yet catch usage-flag or queue-family mistakes that a strict runtime would reject.

Note: `shim/tests/harness.c` is the original superseded smoke test; its build line is stale
and no script references it.

## Path C — Steam Frame (the target)

Same arm64 shim `.so`, but the APK runs under **Lepton** (Valve's Waydroid fork, now open
source) and the OpenXR runtime inside the container is **SteamVR** — Lepton's
`vendor/etc/openxr/1/active_runtime.json` names `steamvr` and points at a host-mounted
`vrclient.so`. (Earlier notes here and in `HOST.md` assumed Monado; that was wrong.)

What that buys us: SteamVR presents Frame controllers as emulating Oculus Touch by default,
so the shim's Touch bindings should bind; and it advertises the `XR_FB_foveation` family plus
`XR_META_foveation_eye_tracked`, so the existing foveation path survives. Lepton also mounts
the host's mesa/turnip/zink and gralloc into the container, which answers the old
`HOST.md` unknown about sharing swapchain images across the container boundary.

Steam Frame shipped 2026-09-14. Flow: NDK build -> `repack.sh` -> `steamframe_patches.sh`
(the Build spoof is required — Lepton reports `ro.product.manufacturer=Valve`) -> sideload
via adb into a Lepton container. Path A having worked makes this mostly packaging and
runtime-plumbing, but see `HOST.md` for the specific items to check first.

---

## Current state

**Path A is done and field-verified.** RE4 VR boots and is playable on a Quest 2 through the
shim on Meta's OpenXR runtime: stereo rendering, head and controller tracking, buttons,
grips, haptics, save loading. The frame-pacing "ghost" that dominated development is fixed
(game-thread pacing; see `docs/research/ghost-fix-2026-06-27.md`). Shipped and verified:

- Session lifecycle, event-driven state machine, Android instance handshake
  (`src/android_init.c`).
- Frame loop with `xrWaitFrame` on the game thread and a FIFO frameState handoff to the
  render thread.
- Poses via `xrLocateViews` and `xrLocateSpace`; `LOCAL_FLOOR` when the game asks for floor
  level.
- Swapchains from `ovrpLayerDesc`, per-frame acquire/wait/release, real projection-layer
  submit, layer z-order fix so splash quads composite above the eye layer.
- Input action sets for Touch controllers plus haptics (`src/xr_input.c`).
- Vulkan extension queries mapped to `xrGetVulkan*ExtensionsKHR` (`src/vk_session.c`).
- CPU/GPU perf levels forwarded via `XR_EXT_performance_settings`; game-driven foveation.
- 438/438 `ovrp_` symbols; around 48 OpenXR entry points.

**Open / known gaps:**
- Depth layer submission is built but gated off (`debug.re4vr.depth`); Meta's runtime accepts
  but does not use plain KHR depth for reprojection.
- Swapchain index lockstep with UE's own `TextureStage` is assumed, not enforced — a
  mismatch is logged but not corrected.
- Residual `XR_FRAME_DISCARDED` hiccups from the frameState ring dropping its oldest entry
  under overflow instead of applying back-pressure.
- In-game black near load zones is a level-streaming / memory stall, mitigated rather than
  fixed. See `docs/handoffs/HANDOFF-2026-06-27.md`.
- Several `debug.re4vr.*` paths are documented dead ends kept for reference.

## Next: Path C (Steam Frame)

Frame shipped 2026-09-14, so this is the live front. Highest-value items before a first boot
attempt, in order:
1. **Page alignment.** The shim's ELF segments and the repacked APK are 4 KB-aligned
   (`zipalign -p 4`); Valve's Unreal docs reference a 16 KB page-alignment requirement. If
   the Frame kernel uses 16 KB pages the library will not load. Check first: it is a
   `-Wl,-z,max-page-size=16384` plus `zipalign -P 16` fix, but it would present as a
   mystery launch failure.
2. **Swapchain usage flags.** `setup_layer` requests only COLOR_ATTACHMENT and SAMPLED.
   Meta over-provisions mutable, broadly-usable images; a spec-following runtime gives you
   exactly what you asked for, and UE 4.25 needs a mutable format for its linear UNORM view.
3. **Refresh rate.** 72 Hz is hardcoded in `ovrp_GetSystemDisplayFrequency2` and in the
   frame-budget constant. Frame runs 72/90/120/144. Derive it from
   `predictedDisplayPeriod`.
4. **Session events.** Only READY and STOPPING are handled, so focus loss and quit from the
   Steam overlay never reach the game.
5. **The per-frame GPU flush-wait.** It exists because Meta's compositor does not sync
   against our submit. A/B it on Frame with `debug.re4vr.noflushwait`.