feat(menu): add isolated DLSS5 sessions with F1 controls and reset #1542

Open

mikaba-eu wants to merge 14 commits from mikaba-eu/pr/linux-dlss-adapter into main

mikaba-eu commented

2026-11-10 07:31:09 +00:00

(Migrated from github.com)

The adapter verifies a private integration manifest, uses private tmpfs IPC and a dedicated Proton prefix, scopes the Vulkan layer to the child game, persists selected preferences and tears down only its own session. Recovery tracks replacement helper metadata using process identity checks and waits boundedly for the replacement before private wineserver teardown. Ended sessions retain archived status without recreating IPC.

The F1 Graphics page exposes all 19 external enhancement settings through basic/advanced controls and reports model availability. A bounded versioned file protocol separates the renderer from the external shared-memory ABI: native file I/O and Python control/persistence run on workers, complete requests are validated before application, and helper polling occurs only while the page is open. The former local F10 companion-menu workflow is removed. This is separate from Hookshot's built-in NVIDIA DLSS support.

Three source patches for external revision c77b64c cover stable host mappings, image-owned presentation completion and swapchain access masks. That code retains the external AGPL-3.0 license. The newer GPU-image transport/per-queue work is a separate external-repository change and is not required by this adapter. No global layer registration, download, system security change or player profile is included.

Validation: 17 adapter lifecycle cases and 11 bridge behavior cases pass; native client/menu checks cover worker exchange, stale/unavailable state, full-setting requests and menu routing. All 365 eligible Linux source checks passed, with 14 documented platform/tool skips, across the serial suite and fixture/upstream follow-ups on ddafc1f9. The isolated renderer compiled successfully before the latest HDR/FSR merge; final combined-build and foreground acceptance results are recorded below. Prior integrated helper recovery verified replacement shutdown and exported-FD cleanup. Model activity is not a guarantee of visual quality, and this adapter does not claim a performance gain.

The Reset DLSS5 settings action restores and saves all 19 factory values with one Enter/controller-confirm/click activation; arrows do nothing and pending/unavailable sessions disable it. The adapter validates a complete factory snapshot and forces exact values for reset, including sub-percent values hidden by UI rounding. Regular edits preserve untouched precision. Default values and behavior are documented.

The reset addition passed 25 affected native-menu, adapter, bridge and analysis checks after the prior complete source coverage. The final combined Linux renderer compiled and linked successfully, with unchanged host ABI. Upstream release-only changes through 2e62a977 also passed the two affected release/update checks.

Native F1 settings and reset:

Foreground Linux/NVIDIA acceptance used copied saves/preferences and the final combined runtime (host source d527692a, renderer bae50216): real keyboard navigation changed Detail80→85%, advanced Apply model1→0→1, and saved values reappeared after a fresh session. Closing F1 then pressing F10 opened no companion menu. The final Reset action ignored arrows, restored all19 helper values and the saved JSON exactly to factory defaults, and those defaults reloaded after another fresh session. Native game-options hashes were unchanged; presentation/helper/composition counters continued advancing and logs showed no transport quarantine. Screenshots above are from the final reset build. This validates the combined runtime's UI/lifecycle, not every platform or an FPS gain.

The optional external enhancement needs its own helper lifetime, private IPC and usable in-game controls. This adds isolated Linux DLSS5VKLayer sessions and native F1 Graphics settings, refreshed onto current upstream without bundling model/runtime binaries or game data. Implemented with GPT-6 Astra medium & xhigh. The adapter verifies a private integration manifest, uses private tmpfs IPC and a dedicated Proton prefix, scopes the Vulkan layer to the child game, persists selected preferences and tears down only its own session. Recovery tracks replacement helper metadata using process identity checks and waits boundedly for the replacement before private wineserver teardown. Ended sessions retain archived status without recreating IPC. The F1 Graphics page exposes all 19 external enhancement settings through basic/advanced controls and reports model availability. A bounded versioned file protocol separates the renderer from the external shared-memory ABI: native file I/O and Python control/persistence run on workers, complete requests are validated before application, and helper polling occurs only while the page is open. The former local F10 companion-menu workflow is removed. This is separate from Hookshot's built-in NVIDIA DLSS support. Three source patches for external revision c77b64c cover stable host mappings, image-owned presentation completion and swapchain access masks. That code retains the external AGPL-3.0 license. The newer GPU-image transport/per-queue work is a separate external-repository change and is not required by this adapter. No global layer registration, download, system security change or player profile is included. Validation: 17 adapter lifecycle cases and 11 bridge behavior cases pass; native client/menu checks cover worker exchange, stale/unavailable state, full-setting requests and menu routing. All **365 eligible Linux source checks passed**, with 14 documented platform/tool skips, across the serial suite and fixture/upstream follow-ups on `ddafc1f9`. The isolated renderer compiled successfully before the latest HDR/FSR merge; final combined-build and foreground acceptance results are recorded below. Prior integrated helper recovery verified replacement shutdown and exported-FD cleanup. Model activity is not a guarantee of visual quality, and this adapter does not claim a performance gain. The **Reset DLSS5 settings** action restores and saves all 19 factory values with one Enter/controller-confirm/click activation; arrows do nothing and pending/unavailable sessions disable it. The adapter validates a complete factory snapshot and forces exact values for reset, including sub-percent values hidden by UI rounding. Regular edits preserve untouched precision. [Default values and behavior](https://github.com/mikaba-eu/Hookshot/blob/43824c27a46105200ca2fed2b3adf7aa2ce4056d/docs/external-enhancement-settings.md) are documented. The reset addition passed 25 affected native-menu, adapter, bridge and analysis checks after the prior complete source coverage. The final combined Linux renderer compiled and linked successfully, with unchanged host ABI. Upstream release-only changes through `2e62a977` also passed the two affected release/update checks. Native F1 settings and reset: ![Native F1 basic settings and Reset DLSS5 settings](https://raw.githubusercontent.com/mikaba-eu/Hookshot/43824c27a46105200ca2fed2b3adf7aa2ce4056d/docs/images/dlss5-f1-basic.png) ![Native F1 advanced settings](https://raw.githubusercontent.com/mikaba-eu/Hookshot/43824c27a46105200ca2fed2b3adf7aa2ce4056d/docs/images/dlss5-f1-advanced.png) Foreground Linux/NVIDIA acceptance used copied saves/preferences and the final combined runtime (host source `d527692a`, renderer `bae50216`): real keyboard navigation changed Detail80→85%, advanced Apply model1→0→1, and saved values reappeared after a fresh session. Closing F1 then pressing F10 opened no companion menu. The final Reset action ignored arrows, restored all19 helper values and the saved JSON exactly to factory defaults, and those defaults reloaded after another fresh session. Native game-options hashes were unchanged; presentation/helper/composition counters continued advancing and logs showed no transport quarantine. Screenshots above are from the final reset build. This validates the combined runtime's UI/lifecycle, not every platform or an FPS gain.

hckrman101 commented

2026-11-10 17:49:34 +00:00

(Migrated from github.com)

Heads-up: this conflicts with main now (a lot landed today). Could you merge main into the branch (or rebase) and resolve the conflicts? Thanks!

mikaba-eu commented

2026-11-10 19:14:30 +00:00

(Migrated from github.com)

Merged current main (1392ea3) and resolved the conflicts, preserving upstream replacements where they supersede our changes. Migrated local tests to the new per-test runner declarations. Independent source suites and the combined suite pass; fresh Linux gameplay results and limitations are recorded in the updated description. Hyrule Field and a warm Forest run completed the short movement tests, but camera hitches remain; earlier memory-guard stops and the incomplete Market event are not reported as passes. AI-assisted development: GPT-6-Astra (medium and xhigh).

Merged current main (`1392ea3`) and resolved the conflicts, preserving upstream replacements where they supersede our changes. Migrated local tests to the new per-test runner declarations. Independent source suites and the combined suite pass; fresh Linux gameplay results and limitations are recorded in the updated description. Hyrule Field and a warm Forest run completed the short movement tests, but camera hitches remain; earlier memory-guard stops and the incomplete Market event are not reported as passes. AI-assisted development: GPT-6-Astra (medium and xhigh).

mikaba-eu commented

2026-11-10 19:39:29 +00:00

(Migrated from github.com)

Refreshed again to main 117eae7 and resolved the new Anti-Lag source-fixture conflict. Complete Linux source suite re-run: 305 passed, 0 failed, 18 skipped. Existing gameplay evidence remains explicitly tied to its tested build.

Refreshed again to main `117eae7` and resolved the new Anti-Lag source-fixture conflict. Complete Linux source suite re-run: 305 passed, 0 failed, 18 skipped. Existing gameplay evidence remains explicitly tied to its tested build.

hckrman101 commented

2026-11-11 15:51:04 +00:00

(Migrated from github.com)

Heads-up: this conflicts with main now. Could you rebase onto main and resolve the conflicts? Thanks!

Joey-Magnus (Migrated from github.com) reviewed

2026-11-11 20:06:11 +00:00

Joey-Magnus (Migrated from github.com) left a comment

This is careful work. The menu rows only appear when HOS_DLSS5_CONTROL names an absolute folder, menu_tick returns at once otherwise, the file protocol is bounded and fully validated before anything is applied, and the Python adapter only signals processes it can prove are its own (start-time stamps, its own child's process group). At the PR's head on Linux, all six tests/test_dlss5_*.py and the three menu fixtures you updated (test_framegen_preset, test_rumble_menu, test_stick_dead_zone) pass, and the fixture updates add stubs rather than weakening any check. At about 2,600 lines I concentrated on the in-tree native side (gpu/vk/dlss5_controls.h, the vk_menu.cpp changes), the adapter's process and file handling, and repository rules; I skimmed the external patches but didn't review them line by line.

should fix: GitHub shows this PR as conflicting again, and a local merge with current main gives four conflict hunks in gpu/vk/vk_menu.cpp (the includes, the Row table, save() and menu_tick). CI also hasn't run beyond the title check, so the Windows and llvm-mingw builds of the new header and menu code are still unverified. Please rebase and let CI run.
should fix gpu/vk/vk_menu.cpp:61: HOS_DLSS5_CONTROL is a new runtime switch, but it isn't in docs/development.md's switch table, which CONTRIBUTING.md asks for ("Document them where the surrounding switches are documented"). docs/external-enhancement-settings.md covers the settings, not the switch.
should fix docs/images/dlss5-f1-basic.png, docs/images/dlss5-f1-advanced.png: these commit 1.6 MB of in-game screenshots into the repository's history. The repo currently tracks no game imagery, just the logo. Screenshots belong in the PR description (CONTRIBUTING.md, Commits and pull requests), where they're fine. Please host them as PR attachments and drop the files and the doc links to them.
should fix patches/dlss5/*.patch: these are patches to an AGPL-3.0 project, and the README says they stay under AGPL. Combining with GPLv3 is allowed (GPLv3 §13), but the repo's convention for third-party material is a folder with a note in PROVENANCE.md (upstream, pinned revision, licence). Please add that entry so the mixed licence is recorded where people look for it.
minor tests/test_dlss5_mapping.py, tests/test_dlss5_present_sync.py: both read the external checkout under work/dlss5/source and skip silently without it, while run_all.py still reports them as passed (0.0 s here). CI never sees work/, so the three patches are never exercised. Either say so with RUN_ALL_SKIP (both OSes, "needs the external DLSS5VKLayer checkout") so the table shows a skip, or drop them from tests/.
question (maintainer): the rows sit on the Graphics tab beside Hookshot's real NVIDIA DLSS rows, and are named "DLSS5 enhancement" and "Reset DLSS5 settings". "DLSS" is NVIDIA's name, and this is a different, third-party thing. Players and bug reports will likely mix them up. Would a neutral name (e.g. "External enhancement", which the docs file already uses) be acceptable?
question (maintainer): scope. Most of this PR (the adapter, the patch set, the Proton or Wine helper management) supports one external, Linux-only, developer-supplied tool. The in-tree part the game needs is small: the file-protocol client and the menu rows. It may be worth deciding whether the adapter and patches should live in the external project or a separate repo, with Hookshot carrying only the client and rows behind HOS_DLSS5_CONTROL.

This is careful work. The menu rows only appear when `HOS_DLSS5_CONTROL` names an absolute folder, `menu_tick` returns at once otherwise, the file protocol is bounded and fully validated before anything is applied, and the Python adapter only signals processes it can prove are its own (start-time stamps, its own child's process group). At the PR's head on Linux, all six `tests/test_dlss5_*.py` and the three menu fixtures you updated (`test_framegen_preset`, `test_rumble_menu`, `test_stick_dead_zone`) pass, and the fixture updates add stubs rather than weakening any check. At about 2,600 lines I concentrated on the in-tree native side (`gpu/vk/dlss5_controls.h`, the `vk_menu.cpp` changes), the adapter's process and file handling, and repository rules; I skimmed the external patches but didn't review them line by line. - **should fix**: GitHub shows this PR as conflicting again, and a local merge with current main gives four conflict hunks in `gpu/vk/vk_menu.cpp` (the includes, the `Row` table, `save()` and `menu_tick`). CI also hasn't run beyond the title check, so the Windows and llvm-mingw builds of the new header and menu code are still unverified. Please rebase and let CI run. - **should fix** `gpu/vk/vk_menu.cpp:61`: `HOS_DLSS5_CONTROL` is a new runtime switch, but it isn't in `docs/development.md`'s switch table, which CONTRIBUTING.md asks for ("Document them where the surrounding switches are documented"). `docs/external-enhancement-settings.md` covers the settings, not the switch. - **should fix** `docs/images/dlss5-f1-basic.png`, `docs/images/dlss5-f1-advanced.png`: these commit 1.6 MB of in-game screenshots into the repository's history. The repo currently tracks no game imagery, just the logo. Screenshots belong in the PR description (CONTRIBUTING.md, *Commits and pull requests*), where they're fine. Please host them as PR attachments and drop the files and the doc links to them. - **should fix** `patches/dlss5/*.patch`: these are patches to an AGPL-3.0 project, and the README says they stay under AGPL. Combining with GPLv3 is allowed (GPLv3 §13), but the repo's convention for third-party material is a folder with a note in `PROVENANCE.md` (upstream, pinned revision, licence). Please add that entry so the mixed licence is recorded where people look for it. - **minor** `tests/test_dlss5_mapping.py`, `tests/test_dlss5_present_sync.py`: both read the external checkout under `work/dlss5/source` and skip silently without it, while `run_all.py` still reports them as passed (0.0 s here). CI never sees `work/`, so the three patches are never exercised. Either say so with `RUN_ALL_SKIP` (both OSes, "needs the external DLSS5VKLayer checkout") so the table shows a skip, or drop them from `tests/`. - **question** (maintainer): the rows sit on the Graphics tab beside Hookshot's real NVIDIA DLSS rows, and are named "DLSS5 enhancement" and "Reset DLSS5 settings". "DLSS" is NVIDIA's name, and this is a different, third-party thing. Players and bug reports will likely mix them up. Would a neutral name (e.g. "External enhancement", which the docs file already uses) be acceptable? - **question** (maintainer): scope. Most of this PR (the adapter, the patch set, the Proton or Wine helper management) supports one external, Linux-only, developer-supplied tool. The in-tree part the game needs is small: the file-protocol client and the menu rows. It may be worth deciding whether the adapter and patches should live in the external project or a separate repo, with Hookshot carrying only the client and rows behind `HOS_DLSS5_CONTROL`.

Joey-Magnus (Migrated from github.com) reviewed

2026-11-11 21:45:57 +00:00

Joey-Magnus (Migrated from github.com) left a comment

No new commits since my review at 43824c2, and the merge with main still conflicts in gpu/vk/vk_menu.cpp. Before the author spends time on another rebase, two questions need a maintainer answer.

Scope. Most of the 2,600 lines are the Linux-only adapter, the Proton prefix management and three AGPL-3.0 patches to an external project. Should Hookshot carry those, or only the file-protocol client and the menu rows behind HOS_DLSS5_CONTROL?
Naming. The rows say "DLSS5" next to Hookshot's real NVIDIA DLSS rows.

The other open points are the author's to fix:

the 1.6 MB of in-game screenshots under docs/images/, which the repo doesn't track (they belong in the PR description);
a PROVENANCE.md entry for patches/dlss5/;
HOS_DLSS5_CONTROL missing from docs/development.md;
the two tests that always skip without the external checkout but still report as passed.

#1543's tests/test_analysis_dlss.py depends on this PR's scripts/dlss5_api.py, so the two shouldn't be decided separately.

No new commits since my review at 43824c2, and the merge with main still conflicts in `gpu/vk/vk_menu.cpp`. Before the author spends time on another rebase, two questions need a maintainer answer. - **Scope.** Most of the 2,600 lines are the Linux-only adapter, the Proton prefix management and three AGPL-3.0 patches to an external project. Should Hookshot carry those, or only the file-protocol client and the menu rows behind `HOS_DLSS5_CONTROL`? - **Naming.** The rows say "DLSS5" next to Hookshot's real NVIDIA DLSS rows. The other open points are the author's to fix: - the 1.6 MB of in-game screenshots under `docs/images/`, which the repo doesn't track (they belong in the PR description); - a `PROVENANCE.md` entry for `patches/dlss5/`; - `HOS_DLSS5_CONTROL` missing from `docs/development.md`; - the two tests that always skip without the external checkout but still report as passed. #1543's `tests/test_analysis_dlss.py` depends on this PR's `scripts/dlss5_api.py`, so the two shouldn't be decided separately.

Commenting is not possible because the repository is archived.

No reviewers