NVIDIA DLSS, DLAA and Reflex (NGX + Vulkan, Linux and Windows, opt-in)

.github/workflows/vulkan-dlss.yml

@@ -0,0 +1,115 @@
+# NVIDIA DLSS is a local build's option: NVIDIA's SDK is never part of Hookshot or its downloads. This only checks that
+# hookshot_vk.dll still compiles and links with it, through llvm-mingw as players build it. It runs by hand, and on a push or
+# pull request only when a file DLSS's build depends on changed (the paths below), not on every push. scripts/ngx_sdk.py
+# fetches the SDK at its pinned release, SHA-256 checked, without DLSS's runtime: NVIDIA's license is accepted for that run
+# alone (--accept-nvidia-license), and nothing of it is uploaded or cached.
+name: Vulkan back end with NVIDIA DLSS
+
+on:
+  push:
+    branches: [main, dev]
+    paths:
+      - 'gpu/vk/vk_dlss*'
+      - 'gpu/vk/vk_reflex*'
+      - 'gpu/vk/vk_ngx_msvc_rt.cpp'
+      - 'gpu/vk/upscaler_rows.h'
+      - 'gpu/vk/dlss_math.h'
+      - 'gpu/vk/shaders/dlss_*'
+      - 'host/mingw_msvc_shims.c'
+      - 'nx2/oot_jitter.py'
+      - 'nx2/build.py'
+      - 'nx2/make_game.py'
+      - 'scripts/ngx_sdk.py'
+      - '.github/workflows/vulkan-dlss.yml'
+  pull_request:
+    paths:
+      - 'gpu/vk/vk_dlss*'
+      - 'gpu/vk/vk_reflex*'
+      - 'gpu/vk/vk_ngx_msvc_rt.cpp'
+      - 'gpu/vk/upscaler_rows.h'
+      - 'gpu/vk/dlss_math.h'
+      - 'gpu/vk/shaders/dlss_*'
+      - 'host/mingw_msvc_shims.c'
+      - 'nx2/oot_jitter.py'
+      - 'nx2/build.py'
+      - 'nx2/make_game.py'
+      - 'scripts/ngx_sdk.py'
+      - '.github/workflows/vulkan-dlss.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  vulkan-dlss:
+    name: Windows Vulkan back end with NVIDIA DLSS (llvm-mingw, link check)
+    runs-on: windows-2022
+    timeout-minutes: 45
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Check out pinned Vulkan headers
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: KhronosGroup/Vulkan-Headers
+          ref: 74d8a6cb930c68ef617b202c3ff3c59d919e086b # v1.4.345
+          path: _deps/cpm/vulkanheaders/v1.4.345
+          persist-credentials: false
+      - name: Check out pinned SPIR-V headers
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: KhronosGroup/SPIRV-Headers
+          ref: 04f10f650d514df88b76d25e83db360142c7b174 # vulkan-sdk-1.4.341.0
+          path: _deps/cpm/spirv-headers/vulkan-sdk-1.4.341.0
+          persist-credentials: false
+      - name: Check out pinned VulkanMemoryAllocator
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator
+          ref: 1d8f600fd424278486eade7ed3e877c99f0846b1 # v3.3.0
+          path: _deps/cpm/vulkanmemoryallocator/v3.3.0
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: '3.12'
+      - name: llvm-mingw version
+        id: llvm
+        run: echo "name=$(python -I scripts/release_parts.py llvm-mingw --name)" >> "$GITHUB_OUTPUT"
+      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ runner.temp }}/llvm
+          key: ${{ steps.llvm.outputs.name }}
+      - name: llvm-mingw
+        run: echo "HOOKSHOT_MINGW=$(python -I scripts/release_parts.py llvm-mingw "$RUNNER_TEMP/llvm")" >> "$GITHUB_ENV"
+      - name: NVIDIA's DLSS SDK (headers and nvsdk_ngx_s.lib)
+        run: python -I scripts/ngx_sdk.py --platform windows --build-only --accept-nvidia-license "$RUNNER_TEMP/ngx-sdk"
+      - name: hookshot_vk.dll with NVIDIA DLSS
+        env:
+          RX_VK_ONLY: '1'
+          RX_RELEASE: '1'
+        run: |
+          OOT_WORK="$RUNNER_TEMP/vk-work" RX_CPM="$GITHUB_WORKSPACE/_deps/cpm" HOOKSHOT_NGX_SDK="$RUNNER_TEMP/ngx-sdk" \
+            python -I nx2/build.py --standalone --jobs "$NUMBER_OF_PROCESSORS" | tee "$RUNNER_TEMP/vk-build.log"
+          test "${PIPESTATUS[0]}" -eq 0
+          grep -q "with NVIDIA DLSS" "$RUNNER_TEMP/vk-build.log"
+      # (what it loads is only Windows' own: the system DLLs and the UCRT's api-ms-win-crt-*. NVIDIA's runtime, nvngx_dlss.dll,
+      # is loaded by NGX at run time from the game folder's ngx folder, and its core, _nvngx.dll, from the driver's)
+      - name: Imports
+        run: |
+          dll="$RUNNER_TEMP/vk-work/sa/build/hookshot_vk.dll"
+          "$HOOKSHOT_MINGW/bin/llvm-objdump" -p "$dll" | sed -n 's/^ *DLL Name: //p' | tr -d '\r' | sort -u | tee "$RUNNER_TEMP/imports.txt"
+          if grep -viE '^(kernel32|user32|gdi32|advapi32)\.dll$|^api-ms-win-crt-[a-z0-9-]+\.dll$' "$RUNNER_TEMP/imports.txt"; then
+            echo "::error::hookshot_vk.dll with NVIDIA DLSS imports a DLL that is not Windows' own (above)"
+            exit 1
+          fi

.gitignore

@@ -34,3 +34,6 @@ __pycache__/
 # ---- Linux builds ----
 build-linux/
 *.so
+
+# ---- NVIDIA's DLSS SDK (scripts/ngx_sdk.py): NVIDIA's files, never committed ----
+ngx-sdk/

CONTRIBUTING.md

@@ -88,6 +88,32 @@ scripts/linux/appimage.sh   # the AppImage, in build-linux/
 The AppImage needs glibc 2.35 or newer and a Vulkan 1.3 driver with mesh shaders. `HOOKSHOT_JOBS` sets how many files
 compile at once. The README's [Linux section](readme.md#on-linux) has the details and the runtime paths.
 
+### NVIDIA DLSS (optional)
+
+DLSS (`gpu/vk/vk_dlss.cpp`) is built in only with NVIDIA's DLSS SDK, which is NVIDIA's, under NVIDIA's own license, and
+is never committed, bundled or uploaded: not in a PR, not in a release, not in a CI artifact. Fetch it for your own
+builds with `scripts/ngx_sdk.py` (it prints NVIDIA's license notice and needs `--accept-nvidia-license` or a typed yes),
+then build with `HOOKSHOT_NGX_SDK=<sdk folder>`:
+
+```powershell
+python -I scripts/ngx_sdk.py --platform windows C:\path\ngx-sdk     # headers, nvsdk_ngx_s.lib, nvngx_dlss.dll
+$env:HOOKSHOT_NGX_SDK = "C:\path\ngx-sdk"
+python -I nx2/make_game.py --nup "C:\path\your-game.nup" --out "C:\Games\Hookshot-dlss"
+```
+
+On Windows the llvm-mingw build links NVIDIA's static `nvsdk_ngx_s.lib` (built for Microsoft's static runtime) into
+`hookshot_vk.dll`, with `gpu/vk/vk_ngx_msvc_rt.cpp` and `host/mingw_msvc_shims.c` for what it needs of that runtime.
+`make_game.py` copies `nvngx_dlss.dll` into the game folder's `ngx` folder; never put NGX's core, `_nvngx.dll`, beside
+the game (it is the driver's). On Linux it is `--platform linux` (or `scripts/linux/ngx-sdk.sh`), with `libnvsdk_ngx.a`
+and `libnvidia-ngx-dlss.so`. A Windows game with DLSS can be built on Linux too, with `RX_TARGET=windows` as below.
+CI's `vulkan-dlss` workflow (`.github/workflows/vulkan-dlss.yml`) checks only that `hookshot_vk.dll` still links with the
+SDK. It runs by hand, and on a push or pull request only when a file DLSS's build depends on changes; it accepts NVIDIA's
+license for that run alone and uploads nothing.
+
+Never share a game folder built with the SDK. A change to the pinned release updates the file table and SHA-256s in
+`scripts/ngx_sdk.py` (and `tests/test_ngx_sdk.py`), and the release named in the builder's license text
+(`builder/HookshotBuilder/MainWindow.xaml.cs`).
+
 ### Hookshot Builder
 
 The builder is a .NET 8 WPF app. Open `builder/HookshotBuilder.sln` in Visual Studio 2022 with the .NET desktop
@@ -219,6 +245,9 @@ with an incompatible license, and do not paste decompiled game code or anything
 The third-party parts (Eden, suyu, Sirit, the Vulkan Memory Allocator, SDL, Opus, stb, zbic and the a64-kit tools)
 keep their own notices. Preserve them, and do not relicense their code.
 
+NVIDIA's DLSS SDK is not one of them: it is never in the repository, and nothing of it may be added (see
+[NVIDIA DLSS](#nvidia-dlss-optional)).
+
 ## Where to talk
 
 - **Issues:** [use the forms](https://github.com/NotRexed/Hookshot/issues/new/choose).

builder/HookshotBuilder/MainWindow.xaml

@@ -101,6 +101,7 @@
             <RowDefinition Height="Auto"/>
             <RowDefinition Height="Auto"/>
             <RowDefinition Height="Auto"/>
+            <RowDefinition Height="Auto"/>
           </Grid.RowDefinitions>
           <StackPanel>
             <TextBlock x:Name="FilesTitle" Style="{StaticResource Heading}" Text="Build your game"/>
@@ -173,6 +174,15 @@
             </StackPanel>
           </Grid>
 
+          <!-- NVIDIA DLSS: off unless ticked. Ticking it shows NVIDIA's license; the build downloads NVIDIA's SDK under it
+               (make_game.py, scripts/ngx_sdk.py). Nothing of NVIDIA's comes with the builder -->
+          <StackPanel Grid.Row="5" Margin="0,14,0,0">
+            <CheckBox x:Name="DlssTick" Style="{StaticResource Tick}" IsChecked="False" Click="DlssChanged"
+                      Content="NVIDIA DLSS (downloads NVIDIA's SDK under NVIDIA's license)"/>
+            <TextBlock Style="{StaticResource Note}" FontSize="12" Margin="26,4,0,0" TextWrapping="Wrap"
+                       Text="For NVIDIA RTX graphics cards. NVIDIA's files stay on this PC: never share a game folder built with them."/>
+          </StackPanel>
+
           </Grid>
           </ScrollViewer>
 

builder/HookshotBuilder/MainWindow.xaml.cs

@@ -259,6 +259,7 @@ sealed class BuilderSettings
         public string? Nup { get; set; }
         public string? Romfs { get; set; }
         public string? Exefs { get; set; }
+        public bool Dlss { get; set; }   // (NVIDIA DLSS ticked: NVIDIA's license was accepted)
     }
     static string SettingsPath => System.IO.Path.Combine(
         Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "HookshotBuilder", "builder-settings.json");
@@ -269,6 +270,7 @@ void ApplySettings()
         try { s = System.Text.Json.JsonSerializer.Deserialize<BuilderSettings>(File.ReadAllText(SettingsPath)); } catch (Exception) { }
         if (s == null) return;
         if (!string.IsNullOrEmpty(s.Out)) OutPath.Text = s.Out;
+        DlssTick.IsChecked = s.Dlss;
         if (s.Romfs != null && s.Exefs != null && Directory.Exists(s.Romfs) && File.Exists(System.IO.Path.Combine(s.Exefs, "main")))
         {
             romfs = s.Romfs;
@@ -290,7 +292,8 @@ void SaveSettings()
     {
         try
         {
-            var s = new BuilderSettings { Out = OutPath.Text, Nup = romfs == null ? chosenNup : null, Romfs = romfs, Exefs = exefs };
+            var s = new BuilderSettings { Out = OutPath.Text, Nup = romfs == null ? chosenNup : null, Romfs = romfs, Exefs = exefs,
+                                          Dlss = DlssTick.IsChecked == true };
             Directory.CreateDirectory(System.IO.Path.GetDirectoryName(SettingsPath)!);
             File.WriteAllText(SettingsPath, System.Text.Json.JsonSerializer.Serialize(s));
         }
@@ -689,7 +692,24 @@ async void StartBuild(object sender, RoutedEventArgs e)
         else if (chosenNup != null) args.AddRange(new[] { "--nup", chosenNup });
         else return;
         args.AddRange(new[] { "--out", OutPath.Text, "--language", lang.Code });
-        Run(tools, args);
+        Run(tools, args, dlss: DlssTick.IsChecked == true);
+    }
+
+    const string DlssLicense =
+        "NVIDIA DLSS is NVIDIA's, not Hookshot's. With it ticked, the build downloads NVIDIA's DLSS SDK (release v310.9.16) from " +
+        "github.com/NVIDIA/DLSS, under NVIDIA's own license, the NVIDIA RTX SDKs license:\n\n" +
+        "https://github.com/NVIDIA/DLSS/blob/9981c6350dc58c0ce21f024fd65e31e851c31689/LICENSE.txt\n\n" +
+        "Its files stay on this PC (in the builder's ngx-sdk folder, and nvngx_dlss.dll in the game folder's ngx folder). " +
+        "Hookshot never includes or shares them: never share a game folder built with them.\n\n" +
+        "Do you accept NVIDIA's license?";
+
+    /// The NVIDIA DLSS tick: NVIDIA's license first, and the tick stays only when it is accepted
+    void DlssChanged(object sender, RoutedEventArgs e)
+    {
+        if (DlssTick.IsChecked == true &&
+            MessageBox.Show(this, DlssLicense, "NVIDIA DLSS", MessageBoxButton.YesNo, MessageBoxImage.Information) != MessageBoxResult.Yes)
+            DlssTick.IsChecked = false;
+        SaveSettings();   // (kept at once, not only when Build is pressed: ticked and closed, it is still ticked next time)
     }
 
     static readonly (string Id, string Build, string Update)[] Stages =
@@ -719,7 +739,8 @@ void MakeRows(bool update)
         if (update) rows["read"].Small("Your game files are kept: the .nup isn't needed");
     }
 
-    void Run(Tools tools, List<string> args, bool keepRows = false)
+    /// dlss: NVIDIA DLSS, its license accepted: NVIDIA's SDK fetched into Storage.NgxSdk first (only what is missing), and built in
+    void Run(Tools tools, List<string> args, bool keepRows = false, bool dlss = false)
     {
         int? workers;
         try { workers = BuildWorkers.Selected(WorkerBox.SelectedItem); }
@@ -756,7 +777,8 @@ void Run(Tools tools, List<string> args, bool keepRows = false)
         clock.Start();
         Tick();
         if (Storage.WorkChosen && !args.Contains("--work")) args.AddRange(new[] { "--work", Storage.Work });   // (the build files where the player chose)
-        runner = new Runner(tools, args, workers);
+        if (dlss && !args.Contains("--fetch-ngx-sdk")) args.AddRange(new[] { "--fetch-ngx-sdk", "--accept-nvidia-license" });
+        runner = new Runner(tools, args, workers, dlss ? Storage.NgxSdk : null);
         runner.Line += l => Dispatcher.BeginInvoke(() => Line(l));
         runner.Finished += failure => Dispatcher.BeginInvoke(() => Ended(failure));
         runner.Start();
@@ -1146,7 +1168,10 @@ internal void UpdateBuild(Tools tools, string folder)
     {
         download = null;
         if (rows.TryGetValue("download", out var d)) { d.Done(); d.Small("Build tools checked"); }
-        Run(tools, new List<string> { "--update", folder }, keepRows: true);
+        // (a folder built with NVIDIA DLSS, its license accepted then, is built with it again)
+        var dlss = File.Exists(System.IO.Path.Combine(folder, "ngx", "nvngx_dlss.dll")) &&
+                   File.Exists(System.IO.Path.Combine(Storage.NgxSdk, "LICENSE.txt"));
+        Run(tools, new List<string> { "--update", folder }, keepRows: true, dlss: dlss);
     }
 
     // ================= the window =================

builder/HookshotBuilder/Runner.cs

@@ -60,22 +60,25 @@ sealed class Runner
     readonly Tools tools;
     readonly List<string> args;
     readonly int? workers;
+    readonly string? ngxSdk;
     Process? process;
     string? error;
     bool cancelled;
 
     public event Action<string>? Line;
     public event Action<string?>? Finished;
 
-    public Runner(Tools tools, List<string> args, int? workers = null)
+    /// ngxSdk: NVIDIA DLSS (the builder's tick): the folder of NVIDIA's DLSS SDK, as HOOKSHOT_NGX_SDK; null builds without it
+    public Runner(Tools tools, List<string> args, int? workers = null, string? ngxSdk = null)
     {
         this.tools = tools;
         this.args = args;
         if (workers is <= 0) throw new ArgumentOutOfRangeException(nameof(workers), "Build workers must be positive.");
         this.workers = workers;
+        this.ngxSdk = ngxSdk;
     }
 
-    static ProcessStartInfo Info(Tools tools, IEnumerable<string> args, int? workers = null)
+    static ProcessStartInfo Info(Tools tools, IEnumerable<string> args, int? workers = null, string? ngxSdk = null)
     {
         var si = new ProcessStartInfo(tools.Python)
         {
@@ -89,6 +92,9 @@ static ProcessStartInfo Info(Tools tools, IEnumerable<string> args, int? workers
         BuildWorkers.Apply(si, workers);
         // (written into the game folder's hookshot_version.txt: the game starts this app again to update, host/hos_update.c)
         if (Environment.ProcessPath != null) si.Environment["HOOKSHOT_BUILDER_EXE"] = Environment.ProcessPath;
+        // (NVIDIA DLSS: only when ticked. Without it, one set on the PC is not passed on either: a build is with DLSS only when asked)
+        if (ngxSdk != null) si.Environment["HOOKSHOT_NGX_SDK"] = ngxSdk;
+        else si.Environment.Remove("HOOKSHOT_NGX_SDK");
         // (the folder's own compiler, headers and libraries, when it has them: nothing of the PC's but Windows' own)
         var sets = new[] { ("EMSDK", "emsdk"), ("RX_CPM", "cpm"), ("WGPU_NATIVE", "wgpu-native") };
         foreach (var (name, folder) in sets)
@@ -109,7 +115,7 @@ public void Start()
         {
             try
             {
-                using var p = Process.Start(Info(tools, args, workers))!;
+                using var p = Process.Start(Info(tools, args, workers, ngxSdk))!;
                 process = p;
                 p.ErrorDataReceived += (_, e) => { if (e.Data != null) Line?.Invoke(e.Data); };
                 p.BeginErrorReadLine();

builder/HookshotBuilder/Storage.cs

@@ -36,6 +36,10 @@ public static string Work
 
     public static bool WorkChosen => !Same(Work, Base);
 
+    /// (NVIDIA DLSS, only when ticked) NVIDIA's DLSS SDK, downloaded under NVIDIA's license by the build (make_game.py
+    /// --fetch-ngx-sdk, scripts/ngx_sdk.py): HOOKSHOT_NGX_SDK. NVIDIA's files, never part of the builder or its downloads
+    public static string NgxSdk => Path.Combine(Base, "ngx-sdk");
+
     /// The build files go to a folder of their own in the one the player picked (null: back to the builder's own). What the last
     /// builds left at the old place goes: the next build would not look for it there
     public static void MoveWork(string? picked)