From da7dd08640668eb5ce466b7562e2fe7c4264d68e Mon Sep 17 00:00:00 2001 From: Daniel Lynch Date: Tue, 22 Sep 2026 22:44:34 -0400 Subject: [PATCH] docs: fix runtime claim, stale header notes and dangling doc references - ovrplugin_shim.h: runtime on Steam Frame is SteamVR (HOST.md), not Monado; drop the "Status: scaffold" line and the note that SetupLayer / GetLayerTexture2 await a 128-byte desc (implemented against the 108-byte ovrpLayerDesc); point RE-NOTES/SHIM-SCOPE at docs/research/. - lever2-detect-skip-black-handoff.md lives in docs/research/, not analysis/. - References to unpublished RE notes now say so instead of naming files that are not in the repo. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/handoffs/HANDOFF-2026-06-26-reproject.md | 2 +- docs/handoffs/HANDOFF-2026-06-26-skipblack.md | 2 +- docs/handoffs/HANDOFF-2026-06-26.md | 2 +- docs/research/render-submit-sync-design.md | 4 ++-- shim/include/ovrplugin_shim.h | 20 +++++++++---------- shim/src/core.c | 3 ++- shim/src/xr_runtime.c | 2 +- 7 files changed, 18 insertions(+), 17 deletions(-) diff --git a/docs/handoffs/HANDOFF-2026-06-26-reproject.md b/docs/handoffs/HANDOFF-2026-06-26-reproject.md index 0e5176c..d329601 100644 --- a/docs/handoffs/HANDOFF-2026-06-26-reproject.md +++ b/docs/handoffs/HANDOFF-2026-06-26-reproject.md @@ -58,7 +58,7 @@ now a SAFETY NET for render-ahead's old instability (detect+hide any black inste ## Game perf RE (done this session) — one new lever, several myths busted Static RE of the GAME binary `dump/apk_libs/lib/arm64-v8a/libUE4.so` via capstone. Full report: -`analysis/game-perf-RE.md`; memory `game-perf-RE-findings`. This REPLACES the behavioral +private RE notes (not published); memory `game-perf-RE-findings`. This REPLACES the behavioral inferences in `game-doesnt-drive-dynamic-perf-from-feed` with code proof: - **No game-side dynamic-FFR loop exists** — `SetTiledMultiRes{Level,Dynamic}` args are config bytes (`SetTiledMultiResDynamic(Settings.byte[0x11d])`), never compared to GPU time/metrics. So diff --git a/docs/handoffs/HANDOFF-2026-06-26-skipblack.md b/docs/handoffs/HANDOFF-2026-06-26-skipblack.md index 45b582f..a51e736 100644 --- a/docs/handoffs/HANDOFF-2026-06-26-skipblack.md +++ b/docs/handoffs/HANDOFF-2026-06-26-skipblack.md @@ -3,7 +3,7 @@ Continuation of `HANDOFF-2026-06-26.md` (morning). Branch `latency-perffix-copyring`. This session built + ran **Lever 2 step 1 (instrument-only black-frame detector)** and validated the signal is real but coarse. Detailed finding in auto-memory -`skipblack-posthitch-signal-validated`. Design: `analysis/lever2-detect-skip-black-handoff.md`. +`skipblack-posthitch-signal-validated`. Design: `docs/research/lever2-detect-skip-black-handoff.md`. ## TL;DR — the post-hitch black signal is REAL but needs a tighter gate + frame-accurate proof Added `debug.re4vr.skipblack 1` (instrument-only): after a HITCH (dt>20ms), flag the next diff --git a/docs/handoffs/HANDOFF-2026-06-26.md b/docs/handoffs/HANDOFF-2026-06-26.md index c41030b..71fd2f4 100644 --- a/docs/handoffs/HANDOFF-2026-06-26.md +++ b/docs/handoffs/HANDOFF-2026-06-26.md @@ -19,7 +19,7 @@ frame-drop under load**, NOT a shim bug: - Load-gated: bridge (sparse) never blacks; house/dense geometry blacks; worse while casting. ## NEXT TASK — Lever 2: detect the bad frame + reproject -Full design in `analysis/lever2-detect-skip-black-handoff.md`. Idea: when UE hands us a +Full design in `docs/research/lever2-detect-skip-black-handoff.md`. Idea: when UE hands us a truncated/black frame, DON'T present it — re-present the last-good eye image with the current pose so the OpenXR compositor reprojects (timewarp) instead of showing black. - **Bad-frame signal:** start with the **post-hitch heuristic** (the truncated frame is the diff --git a/docs/research/render-submit-sync-design.md b/docs/research/render-submit-sync-design.md index e9742ee..bdff138 100644 --- a/docs/research/render-submit-sync-design.md +++ b/docs/research/render-submit-sync-design.md @@ -1,6 +1,6 @@ # Render-submit race — fix design (#2) -Pairs with `render-submit-sync-RE.md` (subagent RE of UE/OVRPlugin submit timing). +Pairs with private RE notes on UE/OVRPlugin submit timing (not published). Status: design draft; final approach (A vs B) gated on the RE findings. ## Confirmed mechanism @@ -52,7 +52,7 @@ the submit without a hook), adds latency/stalls. Not recommended. **D. Use an ovrp call UE makes around submit as the sync point** — only viable if the RE finds UE invokes an OVRPlugin entry point right after the render submit. Unlikely; → RE. -## RE outcome (`render-submit-sync-RE.md`) → Option A is feasible +## RE outcome (private RE notes, not published) → Option A is feasible - **Original = zero Vulkan sync, definitively:** libOVRPlugin imports *no* `vk*` (only `vrapi_*`); libvrapi imports no `vk*` either. The compositor is a separate system process; swapchains are cross-process system-owned (`vrapi_CreateTextureSwapChainCrossProcess`). diff --git a/shim/include/ovrplugin_shim.h b/shim/include/ovrplugin_shim.h index 36d1978..72bd473 100644 --- a/shim/include/ovrplugin_shim.h +++ b/shim/include/ovrplugin_shim.h @@ -2,18 +2,19 @@ * * Goal: a drop-in replacement libOVRPlugin.so that re-exports the ovrp_* symbols * RE4 VR (com.Armature.VR4, OVRPlugin 1.51 / pkg 19.0.0.449.531) calls, backed by - * OpenXR (Monado) on Steam Frame instead of Meta's libvrapi.so. + * OpenXR (SteamVR on Steam Frame — see HOST.md) instead of Meta's libvrapi.so. * * Provenance of each declaration: * [VERIFIED] struct size / arg shape confirmed from Ghidra decompilation of the - * actual binary (see analysis/ovrp_decomp.txt, RE-NOTES.md). + * actual binary (decomp output is private, not published; + * findings summarized in docs/research/RE-NOTES.md). * [HEADER] taken from public OVRPlugin.cs @ v1.51; layout trusted because the * VERIFIED structs matched it byte-for-byte, but not independently * re-confirmed against this binary yet. * [TODO] signature not yet finalized — placeholder, do not trust arg list. * - * Status: scaffold. Base types + the fully-confirmed functions are real; the rest - * of the ~239-function surface (analysis/shim_surface.txt) is still to be filled. + * This header declares the base types and the functions the shim implements by hand; + * the rest of the export surface (analysis/shim_surface.txt) is generated stubs. */ #ifndef OVRPLUGIN_SHIM_H #define OVRPLUGIN_SHIM_H @@ -277,12 +278,11 @@ OVRP_EXPORT ovrpResult ovrp_IsPerfMetricsSupported(ovrpPerfMetrics metric, ovrpB OVRP_EXPORT ovrpResult ovrp_GetPerfMetricsFloat(ovrpPerfMetrics metric, float *outValue); OVRP_EXPORT ovrpResult ovrp_GetPerfMetricsInt(ovrpPerfMetrics metric, int *outValue); -/* TODO: remaining ~225 of the 239-function surface; see analysis/shim_surface.txt. - * Buckets (per SHIM-SCOPE.md): ~150 stub-to-constant (Media_, camera, perf, - * boundary, handtracking, system-getters), ~45 mechanical (rest of tracking, - * input, eye params), and the hard layer/swapchain set (SetupLayer, - * CalculateEyeLayerDesc2, GetLayerTexture2) which need the 128-byte - * ovrpLayerDesc reversed first. */ +/* The rest of the surface (analysis/shim_surface.txt; buckets per + * docs/research/SHIM-SCOPE.md) is stub-to-constant or declared alongside its + * implementation. The layer/swapchain set (SetupLayer, CalculateEyeLayerDesc2, + * GetLayerTexture2) is implemented in layers.c against the 108-byte ovrpLayerDesc + * above. */ #ifdef __cplusplus } diff --git a/shim/src/core.c b/shim/src/core.c index 0fd7e94..0b65cec 100644 --- a/shim/src/core.c +++ b/shim/src/core.c @@ -361,7 +361,8 @@ OVRP_EXPORT ovrpResult ovrp_GetGPUFrameTime(float *outGpuTimeMs) { /* Lever A — dynamic resolution. Previously stubbed Unsupported, leaving the game's preset * scale=1.0 (full res always). We return scale<1 under GPU pressure; the game self-downscales - * its eye buffer (resolution = baseDensity * sqrt(scale)). See xr_runtime.c / game-perf-RE.md. */ + * its eye buffer (resolution = baseDensity * sqrt(scale)). See xr_runtime.c; the game-side + * RE notes behind this are private (not published). */ OVRP_EXPORT ovrpResult ovrp_GetAdaptiveGpuPerformanceScale2(float *outScale) { PT_FWD(ovrp_GetAdaptiveGpuPerformanceScale2, outScale); if (!outScale) return ovrpFailure_InvalidParameter; diff --git a/shim/src/xr_runtime.c b/shim/src/xr_runtime.c index d083697..a063f2f 100644 --- a/shim/src/xr_runtime.c +++ b/shim/src/xr_runtime.c @@ -260,7 +260,7 @@ static int submithook_level(void) { * 2 = (future) reproject: re-present the last-good eye image on a flagged frame. * Root cause is settled: UE renders a truncated (~28 vs ~198 draws) black frame under load; * the truncated frame is the RECOVERY frame following a stall, which we already detect as a - * dt>20ms HITCH. See analysis/lever2-detect-skip-black-handoff.md. */ + * dt>20ms HITCH. See docs/research/lever2-detect-skip-black-handoff.md. */ static int skipblack_level(void) { int v = 0; #ifdef __ANDROID__