feat: Cardboard VR mode with ARM64 SteamVR (#704)

* feat: add Cardboard mode with side-by-side lens-distorted eyes and 3DoF head tracking

* fix: derive the Cardboard field of view from the panel and recentre fully when far from upright

* feat: share the Cardboard head pose with the guest and add a SteamVR driver for it

* feat: run SteamVR's compositor on Turnip/KGSL with a display-extension layer and a driver-direct HMD

* feat: show SteamVR frames in Cardboard mode through a driver-side presenter and a fake direct-mode display

* feat: install and start SteamVR for Cardboard mode from the session drawer

* docs: describe Cardboard mode and the SteamVR path

* feat: drive SteamVR hands from the game pad and keep the Cardboard headset out of standby

* docs: record where the SteamVR dashboard stops

* fix: map Cardboard head tracking to the screen's axes and keep turns about the real vertical as yaw

* fix: give Cardboard its previous picture back when SteamVR stops

* fix: report sem_otime from emulated SysV semaphores so SteamVR's web helper can start

* fix: bridge SteamVR's shared semaphores across processes and keep Steam alive while SteamVR runs

* feat: present SteamVR straight to DroidDeck's compositor at panel resolution

* docs: update Cardboard VR notes for the dashboard, semaphore bridge and direct presenter

* fix: keep Wine and FEX signal handlers in the VR layer; add semaphore tracing

* fix: clear a stale SteamVR active marker on status

* fix: clear only an old SteamVR active marker

* fix: unblock SteamVR clients on Turnip and keep Steam's web helper alive across SteamVR runs

* fix: judge shared waits before a submit's own signals and on Vulkan 1.0 devices

* docs: record VR games, SteamVR Home and OpenXR results on the Thor

* docs: add Cardboard VR learnings from the Thor bring-up

* docs: add Cardboard VR screenshots from the Thor

* fix: keep the VR layer's display stand-in to SteamVR runs and clear a leftover marker at session start

* fix: report SteamVR start and stop failures from the helper's exit code
This commit is contained in:
Kurt Himebauch authored and GitHub committed 2026-10-13 14:36:56 +00:00
1 parent 92d038b428
commit f4b0ab6867
57 files changed
+17799 -15

No files matched your search

@@ -540,6 +540,38 @@ def quit_game(agent_dir, app_id, timeout):
# --- Requests ------------------------------------------------------------------------------------
VR_HELPER = "/usr/local/bin/droiddeck-steamvr"
VR_ACTIONS = ("status", "install", "start", "stop")
def steamvr(req):
"""Cardboard mode's SteamVR: a fixed helper with four actions, unlike exec (no command line from
the request). install downloads 571 MB, so it runs detached and status reports it."""
action = req.get("action", "status")
if action not in VR_ACTIONS:
raise AgentError("INVALID_REQUEST", "vr action must be one of " + ", ".join(VR_ACTIONS))
helper = os.environ.get("DROIDDECK_VR_HELPER", VR_HELPER)
if not os.path.isfile(helper):
raise AgentError("UNAVAILABLE", "this runtime has no " + helper)
if action == "install":
state = Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / "droiddeck-steamvr"
state.mkdir(parents=True, exist_ok=True)
with open(state / "install.log", "ab") as log_file:
subprocess.Popen(["sh", helper, "install"], stdin=subprocess.DEVNULL, stdout=log_file,
stderr=subprocess.STDOUT, start_new_session=True)
return {"action": action, "started": True}
done = subprocess.run(["sh", helper, action], stdin=subprocess.DEVNULL, capture_output=True,
timeout=request_timeout(req, 30))
out = done.stdout.decode("utf-8", "replace").strip()
result = {"action": action, "exitCode": done.returncode, "output": out[-2000:]}
if action == "status":
for part in out.split():
key, _, value = part.partition("=")
if key in ("installed", "running", "installing", "driver"):
result[key] = value == "1"
return result
def run_exec(req):
argv = req.get("argv")
if not isinstance(argv, list) or not argv or not all(isinstance(a, str) and "\0" not in a for a in argv):
@@ -656,6 +688,8 @@ def handle(agent_dir, req):
return steam_selection(agent_dir, request_timeout(req, 5))
if kind == "quit":
return quit_game(agent_dir, req.get("appId"), request_timeout(req, 15))
if kind == "vr":
return steamvr(req)
raise AgentError("UNKNOWN_REQUEST", "Unknown agent request '%s'" % kind)
@@ -165,6 +165,9 @@ export XDG_DATA_HOME=${XDG_DATA_HOME:-$HOME/.local/share}
export XDG_CONFIG_HOME=${XDG_CONFIG_HOME:-$HOME/.config}
export XDG_CACHE_HOME=${XDG_CACHE_HOME:-$HOME/.cache}
mkdir -p "$XDG_DATA_HOME" "$XDG_CONFIG_HOME" "$XDG_CACHE_HOME"
# No SteamVR runs at session start. A marker left by a session that died with SteamVR up would put
# the Cardboard VR layer's display stand-in into this one (docs/cardboard-vr.md).
rm -f "${XDG_RUNTIME_DIR:-/run/droiddeck}/droiddeck-steamvr/active"
if [ "$mode" = lxqt ] || [ "$mode" = desktop ]; then
/usr/local/bin/droiddeck-desktop-bookmarks || true
fi
@@ -0,0 +1,117 @@
#!/bin/sh
# SteamVR for Cardboard mode (docs/cardboard-vr.md). Experimental.
#
# droiddeck-steamvr status one line: installed=0|1 running=0|1 installing=0|1 driver=0|1
# droiddeck-steamvr install fetch Valve's ARM64 SteamVR (the Steam Frame's package) into /opt/steamvr
# droiddeck-steamvr start start SteamVR with the DroidDeck Cardboard driver
# droiddeck-steamvr stop stop it
#
# SteamVR renders through the driver (tools/vr/src/driver_droiddeck.cpp) into an overlay window that
# gamescope shows over everything; the app's Cardboard pass, with a side-by-side source, puts the lens
# on it. vrcompositor needs the Vulkan layer (tools/vr/src/vk_layer_droiddeck_vr.c) on Turnip/KGSL.
set -u
steamvr=${STEAMVR:-/opt/steamvr}
vrdir=${DROIDDECK_VR_DIR:-/usr/local/lib/droiddeck-vr}
driver=$vrdir/droiddeck
layer=$vrdir/layer
logs=$HOME/.local/share/Steam/logs
state=${XDG_RUNTIME_DIR:-/tmp}/droiddeck-steamvr
mkdir -p "$state"
# The Steam Frame's SteamVR, from Valve's package server; the same build the Frame's SteamOS ships.
PKG_URL=https://steamdeck-packages.steamos.cloud/archlinux-deckard-hotfixes/release/0.3.x/deckard-steamvr-rel-r25358740%2B28b72a4f-1-aarch64.pkg.tar.zst
PKG_SHA256=90a600775eb3e8856dc475f83166a93a290a0b1f3b4e82a69c8e2a8f06b9ddc9
running() { pgrep -x vrserver >/dev/null 2>&1; }
installed() { [ -x "$steamvr/bin/linuxarm64/vrstartup" ]; }
stop() {
rm -f "$state/active"
for n in vrcompositor vrserver vrmonitor vrdashboard vrstartup vrwebhelper; do
for p in $(pgrep -x "$n"); do kill "$p" 2>/dev/null; done
done
# pgrep -x matches 15 characters of the name at most.
for p in $(pgrep -f "$steamvr/bin/linuxarm64/vrcompositor-launcher"); do kill "$p" 2>/dev/null; done
# A process that exited on its own meanwhile is not a failure: the app reads this exit code.
return 0
}
case "${1:-status}" in
status)
i=0; installed && i=1
r=0; running && r=1
# A session that died with SteamVR up leaves the marker behind; it would keep the layer active.
# Only an old one: vrserver takes a while to appear after start, and Steam's web helper needs the
# marker from the start.
if [ "$r" = 0 ] && [ -n "$(find "$state/active" -mmin +2 2>/dev/null)" ]; then rm -f "$state/active"; fi
n=0; [ -f "$state/installing" ] && n=1
d=0; [ -f "$driver/bin/linuxarm64/driver_droiddeck.so" ] && [ -f "$layer/libVkLayer_droiddeck_vr.so" ] && d=1
echo "installed=$i running=$r installing=$n driver=$d"
;;
install)
installed && { echo "SteamVR is already in $steamvr"; exit 0; }
[ -f "$state/installing" ] && { echo "already installing"; exit 0; }
: > "$state/installing"
trap 'rm -f "$state/installing"' EXIT
cache=$HOME/.cache/droiddeck-vr
mkdir -p "$cache"
pkg=$cache/steamvr.pkg.tar.zst
echo "downloading SteamVR (571 MB) from Valve's package server"
curl -fsSL --retry 5 -C - -o "$pkg" "$PKG_URL" || { echo "download failed"; exit 1; }
echo "$PKG_SHA256 $pkg" | sha256sum -c - >/dev/null 2>&1 || { echo "checksum mismatch: removing the download"; rm -f "$pkg"; exit 1; }
tmp=$cache/extract
rm -rf "$tmp" && mkdir -p "$tmp"
zstd -dc "$pkg" | tar -x -C "$tmp" opt/steamvr || { echo "extract failed"; rm -rf "$tmp"; exit 1; }
mkdir -p "$(dirname "$steamvr")"
rm -rf "$steamvr" && mv "$tmp/opt/steamvr" "$steamvr" && rm -rf "$tmp" "$pkg"
echo "SteamVR installed in $steamvr"
;;
stop)
stop
;;
start)
installed || { echo "SteamVR is not installed (droiddeck-steamvr install)"; exit 1; }
[ -f "$driver/bin/linuxarm64/driver_droiddeck.so" ] || { echo "the Cardboard driver is missing from $driver"; exit 1; }
stop
sleep 1
mkdir -p "$HOME/.config/openvr" "$HOME/.config/openxr/1" "$logs" "$HOME/.local/share/Steam/config"
cat > "$HOME/.config/openvr/openvrpaths.vrpath" <<JSON
{
"config": ["$HOME/.local/share/Steam/config"],
"external_drivers": ["$driver"],
"jsonid": "vrpathreg",
"log": ["$logs"],
"runtime": ["$steamvr"],
"version": 1
}
JSON
ln -sf "$steamvr/steamxr_linuxarm64.json" "$HOME/.config/openxr/1/active_runtime.json"
# vrcompositor asks for VK_KHR_display, which makes Turnip/KGSL report no GPU at all; the layer stands
# in for a display. gamescope's implicit WSI layer stays out of SteamVR's processes.
export VK_LAYER_PATH="$layer${VK_LAYER_PATH:+:$VK_LAYER_PATH}"
export VK_INSTANCE_LAYERS="VK_LAYER_DROIDDECK_vr${VK_INSTANCE_LAYERS:+:$VK_INSTANCE_LAYERS}"
export VK_LOADER_LAYERS_DISABLE="${VK_LOADER_LAYERS_DISABLE:-~implicit~}"
# SteamVR's web helper (the dashboard) checks the X server with xset, which the runtime lacks.
shims=$state/shims
mkdir -p "$shims"
if ! command -v xset >/dev/null 2>&1; then
printf '#!/bin/sh\n# xset stand-in for vrwebhelper.sh: "q" only checks the display answers.\nexec xprop -root -display "${DISPLAY:-:0}" _NET_SUPPORTED >/dev/null 2>&1\n' > "$shims/xset"
chmod +x "$shims/xset"
export PATH="$shims:$PATH"
fi
# While this file exists, the layer is active in every Vulkan instance of the session, not only
# SteamVR's: Steam's web helper shares its in-VR overlay with SteamVR and needs it too.
: > "$state/active"
cd "$steamvr/bin/linuxarm64" || exit 1
setsid ./vrstartup > "$state/vrstartup.log" 2>&1 < /dev/null &
echo "SteamVR starting; logs in $logs and $state/vrstartup.log"
;;
*)
echo "usage: droiddeck-steamvr status|install|start|stop" >&2
exit 2
;;
esac
+15 -3
View File
@@ -43,8 +43,14 @@ struct sem_header {
uint32_t key;
uint32_t mode;
int32_t creator_pid;
int32_t pad[11];
/* What IPC_STAT reports as sem_otime / sem_ctime (seconds). The usual race-free init has the
* creator semop the new set once, and every other process wait until sem_otime is non-zero;
* SteamVR's web helper spins on exactly that. */
_Atomic uint32_t otime;
_Atomic uint32_t ctime;
int32_t pad[9];
};
_Static_assert(sizeof(struct sem_header) == 64, "semaphore files written by older sessions keep their layout");
/* The counters follow the header, one 32-bit word each (a futex word). */
struct sem_map { int id; struct sem_header *hdr; size_t len; };
@@ -176,7 +182,8 @@ int semget(key_t key, int nsems, int semflg) {
size_t len = sizeof(struct sem_header) + (size_t)nsems * sizeof(int32_t);
if (ftruncate(fd, (off_t)len) != 0) { close(fd); return -1; }
struct sem_header h = {.magic = SEM_MAGIC, .nsems = (uint32_t)nsems, .key = (uint32_t)key,
.mode = (uint32_t)(semflg & 0777), .creator_pid = (int32_t)getpid()};
.mode = (uint32_t)(semflg & 0777), .creator_pid = (int32_t)getpid(),
.ctime = (uint32_t)time(NULL)};
if (pwrite(fd, &h, sizeof(h), 0) != (ssize_t)sizeof(h)) { close(fd); return -1; }
} else {
struct sem_header h;
@@ -222,6 +229,7 @@ int semtimedop(int semid, struct sembuf *sops, size_t nsops, const struct timesp
}
if (sops[i].sem_op < 0) futex(w, FUTEX_WAKE, INT_MAX, NULL); /* zero-waiters see the change */
}
atomic_store(&h->otime, (uint32_t)time(NULL));
return 0;
}
@@ -256,6 +264,7 @@ int semctl(int semid, int semnum, int cmd, ...) {
if (semnum < 0 || (uint32_t)semnum >= h->nsems) { errno = EINVAL; return -1; }
atomic_store(&words[semnum], (int32_t)(intptr_t)arg.buf);
futex(&words[semnum], FUTEX_WAKE, INT_MAX, NULL);
atomic_store(&h->ctime, (uint32_t)time(NULL));
return 0;
case GETALL:
for (uint32_t i = 0; i < h->nsems; i++) arg.array[i] = (unsigned short)atomic_load(&words[i]);
@@ -265,6 +274,7 @@ int semctl(int semid, int semnum, int cmd, ...) {
atomic_store(&words[i], arg.array[i]);
futex(&words[i], FUTEX_WAKE, INT_MAX, NULL);
}
atomic_store(&h->ctime, (uint32_t)time(NULL));
return 0;
case GETPID: return h->creator_pid;
case GETNCNT: case GETZCNT: return 0;
@@ -275,8 +285,10 @@ int semctl(int semid, int semnum, int cmd, ...) {
arg.buf->sem_perm.gid = arg.buf->sem_perm.cgid = getgid();
arg.buf->sem_perm.mode = (unsigned short)h->mode;
arg.buf->sem_nsems = h->nsems;
arg.buf->sem_otime = (time_t)atomic_load(&h->otime);
arg.buf->sem_ctime = (time_t)atomic_load(&h->ctime);
return 0;
case IPC_SET: return 0;
case IPC_SET: atomic_store(&h->ctime, (uint32_t)time(NULL)); return 0;
default: errno = EINVAL; return -1;
}
}
+4 -2
View File
@@ -47,9 +47,11 @@ static int is_status_path(const char *path) {
}
/* Chromium stands its hang watchdogs down when it sees a tracer, and the client's web helper does
* not come up within their patience here: it is left reading the truth. */
* not come up within their patience here: it is left reading the truth. SteamVR's web helper (the
* dashboard, Cardboard mode's SteamVR) is the same Chromium and stalls the same way. */
static int is_web_helper(void) {
return strcmp(program_invocation_short_name, "steamwebhelper") == 0;
return strcmp(program_invocation_short_name, "steamwebhelper") == 0 ||
strcmp(program_invocation_short_name, "vrwebhelper") == 0;
}
static int write_all(int fd, const char *data, size_t len) {