daniel-lynch--ovrplugin-openxr-shim/docs/handoffs/HANDOFF-2026-06-27.md

# RE4 VR Shim — Handoff (2026-06-27, 3-levers + streaming-bound reframe)

Branch `latency-perffix-copyring`. Prior: `HANDOFF-2026-06-26-reproject.md`. Auto-memory:
`three-perf-levers-built`, plus the prior reproject/black chain. This session built the 3
forward perf levers, soak-tested them, and **reframed the in-game black as a level-streaming /
memory-bandwidth stall (NOT GPU-bound)** — which retires the GPU levers and points at a UE
async-streaming CVar as the only remaining cause-fix.

## What was built (uncommitted on the branch; compiles clean, gated, device-tested)
1. **Lever A — dynamic resolution** `ovrp_GetAdaptiveGpuPerformanceScale2` (real impl in
   `core.c`, helper `xrr_adaptive_gpu_scale()` in `xr_runtime.c`, stub removed from `stubs.c`).
   Props `debug.re4vr.adaptivescale` (1), `adaptivefloor` (60). **DEVICE RESULT: inert** — zero
   `VIEWPORT SUB` under extreme load ⇒ game's `Settings.byte[0x19] bit4` is clear, game ignores
   our scale (the handoff caveat held).
2. **Lever B — render-ahead + truncation counter.** Shared `reproject_resolved_eye()` now feeds
   both present paths; render-ahead via `debug.re4vr.renderahead 1` (pose-patches `g_pending` to
   last-good on a black held frame; clean engage/disengage drain + presentIndex guard).
   `BLACKCOUNT` counter (`debug.re4vr.blackcount`, default 1). **DEVICE RESULT: render-ahead is
   STABLE (old pipeline=1 instability fixed) but NOT a black cure** — still spiked to 66–76%
   black with `pipelined=1`. Confirms black is draw/CPU-bound, not latency-bound. Counter works
   perfectly and was the instrument for everything below.
3. **Lever C — depth-hold** (`debug.re4vr.depthhold 1`, default 0; needs `depth 1`; sync path
   only). Depth-aware `xrr_vk_alloc_images_ex` / `xrr_vk_copy_submit_ex` (isDepth). **No crash
   from the depth barriers, but it ADDS graphics memory in the exact pressured zone — net
   negative for the streaming-stall black; left OFF.**

## THE REFRAME (this session's real finding) — black is a STREAMING/MEMORY stall
User observation: the long black/reproject episode was **in a corridor next to a load-zone
door** — which has *fewer* draws than the open areas that render fine. That contradicts
"draw-bound." The trace agrees:
- `dumpsys meminfo`: **Graphics 1.69 GB**, TOTAL RSS 2.87 GB (Quest 2). During the black window
  (02:06:41–45) the system logged `RescueParty: lmkd_native` + **`ActivityManager: Lost
  connection to lmkd`** — the low-memory killer daemon fell over. Severe memory thrash.
- Black frames were at **near-normal 72Hz cadence** (dt ~21–24ms), only ~8 true hitches in 25s
  but 240–275/360 frames black ⇒ GPU keeping cadence while UE hands us **empty** frames ⇒ the
  **game thread is stalled (streaming the next zone in), not the GPU**.
Conclusion: near a load door UE pre-streams the adjacent zone's textures → memory spike → page
reclaim/lmkd thrash → game-thread stall → empty (black) eye frames. **GPU knobs (resolution,
FFR, render-ahead) cannot help; they target a bottleneck that isn't the limiter.**

### Mitigation that DID help (memory, not pixels)
Config `renderahead=0 reproject=1 depth=0 depthhold=0 sscap=1`: peak black **76% → ~16%**, most
windows 0%. Note **`sscap` did nothing** (eye buffer stayed 1728×1900 — already the recommended
size, no supersample to cap); the win came from **`depth=0` freeing graphics memory**. Cleanest
possible proof it's memory-bound. Reproject hides the residual ⇒ playable.

**Recommended shipping config:** `renderahead=0 reproject=1 holdevery=4 savethr=40 abruptdrop=0
depth=0 depthhold=0 blackcount=1 adaptivescale=1 adaptivefloor=60` (adaptivescale harmless even
if inert).

## NEXT TASK — throttle UE async streaming via a CVar (the only remaining cause-fix)
User's instinct: deprioritize the background stream-ahead, accept a longer load screen. Maps to
UE4 CVars: **`s.AsyncLoadingTimeLimit`**, `s.LevelStreamingActorsUpdateTimeLimit`,
`s.PriorityAsyncLoadingExtraTime`, `s.AsyncLoadingUseFullTimeLimit`, and memory-side
`r.Streaming.PoolSize` / `r.Streaming.LimitPoolSizeToVRAM` / prefetch distance. Lowering the
async time limits spreads streaming over more frames (less per-frame game-thread theft → smoother
active scene, slower stream). Lowering the streaming pool caps the pre-spike.

### CHEAP path PROBED & DEAD (don't retry the same way)
External `UE4CommandLine.txt` override is NOT read by this Shipping build. Tested
`-execcmds="t.MaxFPS 20"` at both `/sdcard/UE4Game/VR4/UE4CommandLine.txt` and the app-scoped
`/sdcard/Android/data/com.Armature.VR4/files/UE4Game/VR4/UE4CommandLine.txt`; **end_frame
heartbeat stayed at 71 fps** (decisive — heartbeat = game render rate; VrApi FPS=72 is just the
reprojecting compositor, ignore it). The engine only uses the baked `assets/UE4CommandLine.txt`
(`../../../VR4/VR4.uproject`). Minor caveat: `t.MaxFPS` *could* be VR-overridden, but two paths
+ heartbeat make "file not read" the strong read.
- **Secondary cheap probe worth ONE try before memory-patching:** `GameUserSettings.ini`
  scalability — `GGameUserSettingsIni` is read from a *writable* app-scoped Saved/Config path.
  Write `[ScalabilityGroups] sg.TextureQuality=0 / sg.ViewDistanceQuality=1` and see if the
  texture-streaming pool shrinks (watch `dumpsys meminfo` Graphics + BLACKCOUNT in the corridor).
  Uncertain (game may overwrite settings via its own UI), but declarative if it sticks.

### ROBUST path — set the CVar from the shim (the actual handoff task)
The console-variable machinery is present and several helpers are **exported (`T`)** in
`dump/apk_libs/lib/arm64-v8a/libUE4.so`:
- `_Z22CreateConsoleVariablesv`, `_Z27ForEachCVarInSectionFromIni...`, and (seen via strings)
  `LoadConsoleVariablesFromINI`, plus `IConsoleVariable` / `IConsoleManager` infra and
  `OnCVarChange`. Kismet `GetConsoleVariable{Int,Float,Bool}Value` exist too.
- **Plan:** after UE init (we already dlsym-patch UE's exported globals for the submit hook — same
  technique), resolve `IConsoleManager::Get()` then `FindConsoleVariable("s.AsyncLoadingTimeLimit")`
  and call `->Set("2", ECVF_SetByCode)`. RE steps: (a) find `IConsoleManager::Get` (likely a local
  symbol — use the full symbol table / capstone like the game-perf RE; `CreateConsoleVariablesv` and
  the `RegisterConsoleVariable` callsites reference the manager singleton). (b) confirm the
  `IConsoleVariable::Set(const TCHAR*, EConsoleVariableFlags)` vtable slot ABI. (c) call it for the
  3–4 streaming CVars at a safe point (first frame). Gate behind `debug.re4vr.streamthrottle`.
- **Verify:** corridor soak, `BLACKCOUNT` delta + `dumpsys meminfo` Graphics, and confirm load
  transitions still complete (just slower). The counter is already the measurement tool.

## IS THIS NECESSARY OR OVER-ENGINEERING? (honest call)
**Leaning over-engineering for the value.** The streaming-stall black is already well-mitigated
(reproject + depth-off: 76%→16% peak, mostly 0%, residual hidden as a brief hold). The CVar
memory-patch is invasive RE (console-manager ABI, fragile across game updates) for a marginal win
on a transient that's already hidden. **Recommend: stop at the memory-light + reproject config,
document the CVar route as a known lever, and only build it if the corridor reproject-holds are
perceptually annoying enough to the user to justify it.** Try the GameUserSettings probe first
(cheap) if pursuing further.

## Build / deploy / config
```
./shim/build_android.sh && ./packaging/repack.sh    # check libOVRPlugin.so timestamp before repack
adb -s <redacted-serial> install -r packaging/out/re4vr-shim.apk
adb -s <redacted-serial> logcat | grep -iE "xrr|REPROJECT|BLACKCOUNT|VIEWPORT SUB"
```
Files changed this session: `core.c`, `stubs.c`, `vk_session.c`, `xr_runtime.c/.h` (+316/−89).
Not yet committed.