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

RE4 VR Shim — Handoff (2026-06-27, native-parity / P4 passthru)

Branch latency-perffix-copyring. Goal this arc: get the shim to native (stock VrApi) parity. Stock RE4 VR is flawless on this Quest 2; our OpenXR shim had black logos + eye-layer ghosting. Detailed findings in auto-memory (MEMORY.md): native-parity-diagnosis, logo-black-is-layer-zorder, eye-ghost-submission-path-clean-need-p4, three-perf-levers-built.

SHIPPED + VERIFIED this session

Logo black FIXED — it was a layer z-order bug. RE'd it: the 3 intro logos are Oculus splash layers (OculusHMD::FSplash); the game submits [logo-quad, eye-fov] in that order, and OpenXR composites strictly in array order (last = on top), so our opaque eye-fov drew ON TOP of the logo → black. VrApi treats eye-fov as the base regardless of order. Fix: build_composition (shim/src/xr_runtime.c) stable-partitions so projection layers go bottom, quads on top. Gated debug.re4vr.eyebottom (default ON). Device-verified: logos now render. A/B: eyebottom 0.

STILL OPEN: eye-layer ghosting (hand deforms / "three hands", close objects, SEATED mode)

Standing mode = black+reproject instead (load-gated, see standing-vs-sitting-blackflash); seated = clean ghost repro (no reproject confound). Every shim submission metric is CLEAN (all device-verified, see eye-ghost-submission-path-clean-need-p4): depth on didn't fix it; submit is 18ms EARLY not late; VrApi Stale=0; pose render==submit (g_xr.views); FOV render==submit; ffr ruled out; mono cast shows a normal hand in sharp frames → it's a per-eye/stereo artifact we can't see from our side. Hence P4.

NEXT TASK — build the full P4 passthru forwarding (DE-RISKED, viable)

Run the REAL OVRPlugin inside our app and LOG native's actual per-eye poses/FOV/layer submission, to diff against our clean-but-ghosting values. Feasibility PROVEN: PASSTHRU-PROBE: dlopen OK — real lib + libvrapi load in our unofficial app, entry points resolve (probe in core.c passthru_probe() at PreInitialize3, gated debug.re4vr.passthru_probe).

Already in place: SONAME-patched real lib at packaging/libs/arm64/libOVRPlugin_real.so (patchelf --set-soname libOVRPlugin_real.so); repack.sh auto-bundles it when present (verified in the APK). libvrapi.so already rides along from the original APK.

The build (all-or-nothing — real lib must own the whole session to run EndFrame4):

1. New shim/src/passthru.c: dlopen("libOVRPlugin_real.so", RTLD_NOW|RTLD_LOCAL) once; build a table of real fn pointers (dlsym each ovrp_* the game uses); expose pt_active() + pt_<fn>() accessors (or a single dispatch). Gate: debug.re4vr.passthru (default 0).
2. In EVERY game-called export (the ~30 in core.c/layers.c + the ~12 stubs the game hits — see below), add at the top: if (pt_active()) { ...optional log...; return real_ovrp_X(args); }. Partial forwarding CRASHES mid-frame, so forward the COMPLETE called set. The game-called set = everything currently implemented in core.c/layers.c PLUS these stubs it invokes (from device log): DestroyDistortionWindow2, SetupDisplayObjects2, SetReorientHMDOnControllerRecenter, SetClientColorDesc, SetAppEngineInfo2, SetAppCPUPriority2, InitializeMixedReality, GetViewportStencil, GetSystemRecommendedMSAALevel2, GetLocalTrackingSpaceRecenterCount, GetLayerTextureFoveation, GetControllerHapticsDesc2. (Confirm the live set by grepping a passthru boot for any of OUR stub ovrp/impl logs that still fire — those are unforwarded calls.)
3. LOG the ghost-relevant ones: EndFrame4 (per-layer pose+fov+swapchain+flags), GetNodePoseState3(Eye L/R return), GetNodeFrustum2(return), CalculateEyeLayerDesc2, WaitToBeginFrame/EndFrame4 timing. Forward these to real, log args/returns.
4. Boot test: with passthru 1, does the game run NATIVE through our shim (looks like stock, no ghost)? If yes → capture native EndFrame4 per-eye poses/fov, diff against our values (ours are in the STEREO/HEADvsEYE logs). The delta is the ghost cause. If the game won't init native (Init5 entitlement/session), fall back to static RE of the projection path. CAVEAT: in passthru our shim must NOT also init OpenXR — make xrr_init/frame-loop no-op when pt_active (real lib owns the session). Watch for double-init of VrApi/OpenXR.

The 3 perf levers (built earlier this session — all DEAD ENDS, gated off)

• Adaptive-res (ovrp_GetAdaptiveGpuPerformanceScale2, core.c): INERT — game's Settings.byte [0x19] bit4 clear, never downscales. debug.re4vr.adaptivescale.
• Render-ahead (debug.re4vr.renderahead): stable now (old pipeline=1 instability fixed) but does NOT reduce black (still 66-76% under load — black is draw/streaming-bound, not latency). BLACKCOUNT counter (debug.re4vr.blackcount) is the measurement tool.
• Depth-hold (debug.re4vr.depthhold, needs depth 1): built, untested, ADDS memory pressure.
• Reproject remains the actual in-game black fix. Corridor black = engine streaming/memory stall (lmkd thrash, Graphics 1.69GB), not GPU — confirmed; GPU knobs don't help. Streaming-throttle CVar is a documented-but-not-built future lever (config-injection DEAD — Shipping ignores external UE4CommandLine.txt; would need CVar memory-patch via IConsoleManager).

Code state (UNCOMMITTED on branch) — RECOMMEND COMMIT before further work

git status: M core.c stubs.c vk_session.c xr_runtime.c xr_runtime.h packaging/repack.sh; new HANDOFF-2026-06-27*.md, save_backup/, packaging/libs/arm64/libOVRPlugin_real.so (986KB binary — needed for passthru; confirm it's committed or staged). +383/-88 in shim. Contains: eyebottom fix (keep — verified), 3 perf levers (gated off), QUADLUMA + per-layer luma diag, passthru probe, depth-aware vk helpers (xrr_vk_alloc_images_ex/xrr_vk_copy_submit_ex).

Build / deploy / device workflow

./shim/build_android.sh && ./packaging/repack.sh           # repack auto-bundles libOVRPlugin_real.so
adb -s <redacted-serial> install -r packaging/out/re4vr-shim.apk   # -r over SAME-signed shim PRESERVES data (no OBB/save dance)
adb -s <redacted-serial> logcat -G 16M                         # big buffer so brief windows don't rotate
adb -s <redacted-serial> logcat | grep -iE "xrr|PASSTHRU"

• Every cold relaunch needs a manual dismiss of the UnOfficialApp dialog (debug-signed) and the ControllerRequired dialog if controllers asleep → autonomous cold-launch capture is blocked; ask the user to dismiss + boot. Logos play on cold start only.
• SAVE DISCIPLINE: adb pull /sdcard/Android/data/com.Armature.VR4/files/savegame00.sav BEFORE any uninstall (uninstall wipes app data; cloud doesn't restore unofficial-app saves — lost one this session). Only stock<->shim swaps need uninstall; shim->shim is install -r (preserves data). OBB preserve trick: adb shell mv /sdcard/Android/obb/com.Armature.VR4 /sdcard/obb_bak before uninstall.
• Stock original APK (pristine, real 907KB OVRPlugin) for A/B: dump/obb/VR4-Android-Shipping-arm64.apk.
• Current device props: eyebottom 1 reproject 1 depth 1 depthhold 0 renderahead 0 blackcount 1 adaptivescale 1 passthru_probe 1 (set passthru 1 for the new path once built).

RE tooling (works)

capstone 5.0.7 in python (NOT pyelftools — absent; parse ELF phdrs manually, see scratchpad disasm.py pattern). nm -DC for libUE4 dynsym. PluginWrapper offset→name mapping was UNRELIABLE; trust call-site offsets + the dynamic stub ovrp log signal instead.