From b4b84789d7801ba52302768063de3461eb5945ac Mon Sep 17 00:00:00 2001 From: xXJsonDeruloXx Date: Wed, 14 Oct 2026 12:16:48 -0400 Subject: [PATCH] docs: add HelixSR integration plan --- docs/development/helixsr-integration-plan.md | 202 +++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 docs/development/helixsr-integration-plan.md diff --git a/docs/development/helixsr-integration-plan.md b/docs/development/helixsr-integration-plan.md new file mode 100644 index 0000000000..8c0eb2459a --- /dev/null +++ b/docs/development/helixsr-integration-plan.md @@ -0,0 +1,202 @@ +# HelixSR integration plan + +Status: research only, nothing tested on the Thor yet. Reviewed 2026-10-13 against HelixSR 1.9.0 +(pre-release, 2026-10-13) and 1.8.1 (latest stable). + +## What HelixSR is + +[HelixSR](https://github.com/lonewolf0622/HelixSR) runs NVIDIA's DLSS "Model E" super-resolution +network as plain D3D12 compute shaders (cs_6_6, 16-bit types, wave intrinsics), so it needs no +Tensor Cores and no NVIDIA driver. It is built for AMD RDNA on Proton and Windows. It works like +DLSS: it uses DLSS jitter and render sizes and offers every mode from DLAA to Ultra Performance. +It does super resolution only, with no frame generation of its own. + +- **Closed source.** It ships under the HelixSR Freeware License: you may run it and redistribute + it unmodified and complete, but you may not modify, decompile or disassemble it. The setup + scripts are readable but fall under the same license (scripts up to 1.8.1 are Apache 2.0). +- **No NVIDIA material in the download.** The setup downloads NVIDIA's `nvngx_dlss.dll` 310.7.0 + from `github.com/NVIDIA/DLSS`, after asking and with a pinned SHA-256. It then pulls the PTX + kernels and weights out of it, translates PTX to HLSL (`ptx2hlsl.py`) and compiles them with + DXC. The result is embedded in HelixSR's DLL. **The built DLL contains NVIDIA's network and + must never be redistributed**, so DroidDeck cannot ship a ready-made one. It has to be built on + the device. +- **Three ways into a game** (`setup/helixsr_install.py`): + - **f**: replaces the game's FSR 3.1 DLL (`amd_fidelityfx_upscaler_dx12.dll` / + `amd_fidelityfx_dx12.dll`) and keeps the original as `*.original.dll`. Select **AMD FSR** in + the game. + - **o**: installs the official OptiScaler 0.9.4 (as `dxgi.dll` and similar) with its FSR 3.1 + backend pointed at HelixSR. Select **DLSS**, XeSS or FSR 2 in the game. + - **d** (experimental): installs a `dxgi.dll` loader plus HelixSR as `nvngx.dll`. The loader + spoofs an NVIDIA GPU and answers the DLSS signature check. + + Everything replaced goes to `HelixSR/backup`, and uninstall puts it back. +- **Runtime knobs:** `helixsr.ini` next to the DLL (`[Upscaling] Int8`, `NetworkResolution`, + `UpscaleFilter`; `[Sharpening]`; `[Compatibility] WaveSize`), and the environment variable + `HELIXSR_INT8`. It writes `helixsr.log` next to the DLL. +- **Cost on the developer's BC-250** (RDNA1 at 2 GHz): 1.13 ms for 720p→1080p Quality and + 0.75 ms for 360p→1080p Ultra Performance. + +## The Adreno state of the art (the video) + +The video, ["DLSS on Adreno | HelixSR Tested on Odin 3"](https://youtu.be/ZW670_3U7bE) (blackheart909, +2026-10-12), shows an **unofficial HelixSR 1.8.0 adaptation** running on an Odin 3 (Adreno 830) +under Armada Linux, through the FSR 3 slot. PRAGMATA works, with a "performance hit" its author +says still needs optimising, and slow startup and loading. Witcher 3 shows black flickering on +fast camera moves that is still unsolved. The description says the Thor/Android port "has not been +verified running". + +How their port works ([HelixSR-Snapdragon-V762](https://github.com/dawoodtogoo2020-code/HelixSR-Snapdragon-V762), +[HelixSR-Decky-Armada](https://github.com/dawoodtogoo2020-code/HelixSR-Decky-Armada)): + +1. They run HelixSR 1.8.0 in a probe under Proton ARM64 with vkd3d-proton (`44cf7c2`), and dump the + SPIR-V for four kernels with `VKD3D_SHADER_DUMP_PATH`. +2. They rewrite that SPIR-V so that wave32 logic runs on a physical 64-lane subgroup. Bindless CBV + accesses are split into subgroup-uniform loads, because two logical waves now share one + subgroup and the CBV index is no longer uniform across it. +3. They install the rewritten shaders as runtime overrides. The pipeline is pinned by hash to + 1.8.0. Users must provide the "private" dumps themselves, and the README says the extraction + is not clean yet. + +The HelixSR author allowed this in [issue #3](https://github.com/lonewolf0622/HelixSR/issues/3). + +**Why we probably do not need any of that:** Adreno has no wave32. Turnip's subgroup sizes are 64 +and 128, so 1.8.x's `[WaveSize(32)]` kernels cannot run as written. **1.9.0 fixes this upstream +for Vega:** + +- The setup now builds every kernel twice, once as `[WaveSize(32)]` and once as `[WaveSize(64)]` + (the `_w64` variants, with cross-lane reads through LDS on `k5*`, `k7`, `k9`–`k11`). +- At run time the DLL probes the device's lane range. Its log strings include "device lanes + %u..%u" and "the GPU has no wave32 ... every kernel at 64 lanes". +- `[Compatibility] WaveSize = 64` forces the 64-lane path. + +On vkd3d-proton over Turnip, `WaveLaneCountMin` should come back as 64, so **unmodified 1.9.0 +should choose wave64 for every kernel by itself**. That would make the SPIR-V patching and its +CBV-split workaround unnecessary. It should also remove the most likely cause of the Witcher 3 +flicker, which is 32-on-64 emulation. This is the first thing to verify on the device (Phase 0). + +## Fit with DroidDeck + +| HelixSR needs | DroidDeck today | +| --- | --- | +| D3D12 + SM 6.6, 16-bit types, `WaveSize(64)` → `VK_EXT_subgroup_size_control` | vkd3d-proton per Proton build, `VKD3D_SHADER_MODEL=6_9` / FL `12_2` by default; Turnip a7xx (subgroup 64..128, fp16) | +| Python 3 + numpy to build the network | Debian arm64 rootfs already has `python3` (`droiddeck-game-env` is Python); numpy is one apt package | +| `launch_synth` (prebuilt only for x86-64 Linux and Windows) | Build it from the shipped `model.cpp` with arm64 `g++` (the setup does this itself when no prebuilt runs), or run the x86 one under FEX | +| DXC (the setup runs the Windows `dxc.exe` through Proton's Wine) | Either Windows DXC through our ARM64 Proton plus FEX (slow but no new code), or an aarch64 Linux `dxc` built in our CI from Microsoft's MIT/NCSA source (fast, preferred) | +| `nvngx_dlss.dll` 310.7.0 (or 310.2) | Download from NVIDIA after user consent, or reuse a copy already in an installed game (`--dlss `), like `Lossless.kt` reuses Steam's `Lossless.dll` | +| Per-game DLL placement + `WINEDLLOVERRIDES` for `dxgi`-named OptiScaler / loader | Per-game profiles, launch wrapper `droiddeck-game-env` that already stages component files before Proton starts | +| Somewhere to turn it on | Components page (packages) + per-game Game environment profile | + +`setup/helixsr-setup.sh` refuses to run on anything but x86-64 (`uname -m`), and we may not modify +it. So **DroidDeck drives `setup/helixsr_setup.py` directly**, the same way the `.sh` does. That +counts as running the scripts, not modifying them: + +``` +python3 setup/helixsr_setup.py --yes --dxc [--dlss ] +``` + +## Plan + +### Phase 0: feasibility on the Thor (manual, needs the device) + +Goal: find out whether stock 1.9.0 runs on Adreno 740, what it costs, and whether it looks right, +before any app code is written. + +1. In the rootfs: + - `apt install python3-numpy g++`. + - Get DXC: start with Windows `dxc.exe` through ARM64 Proton, and time it against an aarch64 + `dxc` built on the Mac with Docker. + - Run `helixsr_setup.py` with `--dlss` pointing at a 310.7.0 DLL. Record wall time, peak RAM + and thermals. +2. Install by hand into one FSR 3.1 game using the **f** way. PRAGMATA is a good first pick + because the video has a reference. +3. Read `helixsr.log`: + - The `wave size:` line should say `device lanes 64..128 ... network kernels wave64`. + - Note the `int8 network:` line. Qualcomm is probably "no fast int8". Try `HELIXSR_INT8=1`, + since a7xx Turnip exposes `VK_KHR_shader_integer_dot_product`. +4. Measure the upscale pass with the Perf HUD at 1080p output in Quality, Performance and Ultra + Performance, and compare against the game's own FSR 3.1. Back-of-envelope: Adreno 740 has about + a third of the BC-250's fp16 throughput and about a seventh of its memory bandwidth, so expect + **roughly 4–10 ms** at 720p→1080p. Ultra Performance or Performance mode may be the only + practical ones on the Thor. +5. Repeat with Witcher 3 (the DLSS game in the video) using the **o** way, to test OptiScaler under + our Proton/FEX and to check the flicker. +6. If the kernels fail, gather `VKD3D_SHADER_DUMP_PATH` dumps and the vkd3d log. Failures are + driver bugs we can fix in our own Turnip or vkd3d builds, not HelixSR bugs we may patch. + +Go/no-go: wave64 runs, the image is correct, and the cost at some mode is below what a native +resolution step would save. + +### Phase 1: HelixSR as a component (build the network on device) + +- **Package entry.** Add `HelixSR` to the Components catalog. Download the official release zip + from GitHub releases, pinned to version and SHA-256, and never mirror it (the license allows + only unmodified, complete redistribution; fetching from upstream avoids any question). Show the + HelixSR license, plus NVIDIA's DLSS license notice before the DLSS download. +- **DXC.** Ship it as a DroidDeck-built package (aarch64 Linux `dxc`, pinned to the same DXC + release HelixSR pins: v1.9.2607), with our own license notice. +- **Build job.** + - Runs on the existing background queue (`AutoComponents`-style: low priority, `nice`/`ionice`, + waits while a session runs, and waits on battery saver or thermal limits). + - Steps: unpack the zip, `apt`-free check for numpy (or bundle numpy in the rootfs image), find + the DLSS DLL, run `helixsr_setup.py`, and parse its `[helixsr-setup]` progress lines into the + UI progress bar. + - Output goes to a DroidDeck-owned folder in the rootfs, for example + `/root/.local/share/droiddeck/helixsr//`. +- **DLSS source.** First look for `nvngx_dlss.dll` 310.7.0 or 310.2 in installed Steam, GOG or + Epic games, the same way `Lossless.kt` finds Lossless.dll. Otherwise offer the NVIDIA download + after explicit consent. Delete the DLL afterwards, as the setup does. +- **Rebuilds.** Rebuild when the HelixSR version changes, and keep the previous build until the new + one succeeds. + +### Phase 2: per-game upscaler injection + +- Add **Upscaler** to the per-game profile: *Off* / *HelixSR (FSR 3.1 slot)* / *HelixSR via + OptiScaler (DLSS/XeSS/FSR2)*. Show only the ways that work for that game's files (scan the game + folder for the FSR 3.1 / `nvngx_dlss.dll` / XeSS DLLs, as `droiddeck-game-env`'s `game_files` + does). +- **Applying it.** Start with option (a) and keep (b) as a fallback. + - **(a)** Call HelixSR's own installer with `HOME` pointed at an empty directory, so its Steam + scan finds nothing, plus `--folder `. It keeps HelixSR's backups, markers and uninstall + behaviour exactly. + - **(b)** Use DroidDeck's own file sync. It does the documented manual-install steps with our + own managed-file manifest, the same pattern as the per-game DXVK/VKD3D overrides. + - **When:** at profile change, never mid-session. Re-check at launch in `droiddeck-game-env`, + because a Steam update or "verify files" puts the game's DLLs back. When that happens, + re-apply quietly or show a notice. +- **Environment.** + - The **o** way: add `WINEDLLOVERRIDES=dxgi=n,b` (or whatever DLL name OptiScaler took) to the + game's environment. + - Expose `HELIXSR_INT8` and generate a `helixsr.ini` (Int8, WaveSize, sharpening, + NetworkResolution) from profile settings rather than asking users to edit an ini. +- **Turning it off** runs the uninstall and restores the originals. Reset game profile must do the + same. +- **Leave out the experimental d way** (DLSS loader and NVIDIA spoof): it is unsafe with + anti-cheat, tested only on desktop Linux, and depends on nvapi on ARM Proton. Revisit later. + +### Phase 3: in-session UX and diagnostics + +- Show the active upscaler and the `helixsr.log` wave/int8 lines in the Perf HUD or session + overlay, and attach `helixsr.log` and `OptiScaler.log` to session log shares (`SessionLogShare`). +- Explain the Insert-key OptiScaler menu for pad users. Map it to a pad combo, or document the + QAM shortcut. +- Add `docs/development/helixsr.md` and an entry in Components' license notices (OptiScaler + GPL-3.0, fakenvapi MIT, AMD FidelityFX license; all of these come from the official zip). + +## Risks and open questions + +- **Performance on Adreno 740** is the deciding factor, and the Odin 3 (830) already reports a + visible hit. Without fp16 dot or int8 acceleration, HelixSR may only be worthwhile in Ultra + Performance or with `NetworkResolution` reduced. +- **Licensing.** HelixSR's license forbids modification but allows running and unmodified + redistribution. We only download, run and copy its files as its own installer does, which is + fine. The built DLL contains NVIDIA's network, so it must never leave the device: no cloud + backup of game folders with it, and keep it out of log shares and save-sync. Ask the author + (issue or Discord) whether a DroidDeck integration that drives `helixsr_setup.py` directly is + welcome. It costs nothing and they have been receptive (issue #3). +- **Project velocity.** Seven releases in a week, and 1.9.0 is a pre-release with an open int8 + flicker bug (#44). Pin versions and let users choose stable or latest. +- **Build cost on device.** The PC build takes about a minute. On the Thor, with DXC under + Proton/FEX, it could take tens of minutes, which is why the native aarch64 `dxc` matters. +- **OptiScaler under ARM64 Proton + FEX** has not been tested in DroidDeck. That needs testing + for the **o** way to be useful. +- **D3D12 only.** DX11 games need OptiScaler's DX11-on-12 path, which is out of scope.