daniel-lynch--ovrplugin-openxr-shim/tools/desktop-harness

Desktop harness — drive the shim against Monado on a PC

The shim is normally exercised only on a Quest (inside RE4's APK). This harness lets you run its OpenXR path on a Linux desktop, headless, against Monado's simulated HMD — no headset, no game, no libUE4. It's the fast iteration loop for the Steam Frame / Monado / Lepton bring-up.

What it is

harness.c stands in for the game (UE4 + OculusHMD). It creates a Vulkan instance/device the way UE's VulkanRHI does, then calls our ovrp_* exports in UE's order:

PreInitialize3 -> Get{Instance,Device}ExtensionsVk -> Initialize5
  -> CalculateEyeLayerDesc2 -> SetupLayer            (once)
  -> per frame: Update3, WaitToBeginFrame, BeginFrame4, GetLayerTexture2,
                (clear the eye image), EndFrame4
  -> Shutdown2

The shim does the real OpenXR work underneath — xrCreateInstance, xrGetSystem, xrCreateSession (Vulkan binding), xrCreateSwapchain, the xrWaitFrame/Begin/EndFrame loop — against whatever runtime the OpenXR loader selects. Here that's Monado's simulated HMD with the NULL compositor (renders nowhere), so it runs over SSH / in CI.

It ships nothing from Capcom/Epic/Meta — it only calls our own public ovrp_* ABI.

Prereqs (Debian/Ubuntu)

sudo apt-get install monado-service libopenxr1-monado libopenxr-loader1 libopenxr-dev \
                     libvulkan-dev

Build & run

shim/build_host.sh            # builds build/host/libOVRPlugin.so + build/host/harness
tools/desktop-harness/run.sh  # brings up monado-service headless, runs 300 frames
tools/desktop-harness/run.sh 1000   # custom frame count

Logs land in build/host/monado.log and build/host/harness.log.

The scene (pose→view validation)

Each frame the harness queries the shim's per-eye pose (ovrp_GetNodePoseState3 for EyeLeft/EyeRight, with true IPD separation) and FOV, builds per-pixel world rays, and renders a world-locked procedural scene — checkerboard floor 1.6 m below the eye, sky gradient, and an orbiting sun — into the acquired eye image. This exercises the shim's pose/FOV math: the two eyes show correct stereo parallax, and the world counter-moves as the head pose changes (Monado's simulated HMD sways, so there's real motion). The first few frames log per-eye pose + FOV. CPU-rendered (fine at the sim's 128×128; it's a test tool, not a fast path).

Watch it (windowed)

VISIBLE=1 uses Monado's main compositor (mirror window) + the imgui debug GUI instead of the NULL compositor, so you can watch the scene (floor grid, horizon, orbiting sun, stereo parallax) and inspect swapchains. Needs a display — run it from the physical desktop session, not over SSH, and give it a big frame count:

VISIBLE=1 tools/desktop-harness/run.sh 3600

What "pass" looks like

harness.log should show the lifecycle succeed and frames present:

[harness] PreInitialize3 OK (XrInstance + system up)
[harness] VkInstance created
[harness] VkDevice + graphics queue (family 0) created
[harness] Initialize5 OK (XrSession created)
[harness] SetupLayer OK layerId=0 swapchainStages=3
[harness] ...
[harness] loop done: NNN/NNN frames presented
[harness] Shutdown2 OK — clean exit

Exit code 0 = frames presented; 2 = ran but presented nothing (session never reached the running state — check monado.log); 1 = a hard failure.

Limits / notes

• This validates the OpenXR + Vulkan binding + frame loop + swapchain path. It does not reproduce the game-thread/render-thread pacing or GPU load that drove the on-Quest "ghost"; those are device-side behaviours. It's for ABI/path correctness and porting to new runtimes, not perf tuning.
• The Android session path (XR_KHR_android_create_instance, xrInitializeLoaderKHR, the JavaVM/Activity chain) is #ifdef __ANDROID__-guarded in xr_runtime.c / android_init.c, so the same sources serve both targets.
• passthru.c (P4 native forwarding) is Android-only; on host its arm64 trampolines fall back to plain stubs and passthru stays inactive.