Add the FSR 3.1 shader passes and the script that compiles them

.github/workflows/source-regressions.yml

@@ -56,7 +56,7 @@ jobs:
         run: python -m pip install --disable-pip-version-check --no-deps zstandard==0.25.0
       - name: Compilers and the SPIR-V validator
         if: runner.os == 'Linux'
-        run: sudo apt-get update && sudo apt-get install -y g++ clang spirv-tools
+        run: sudo apt-get update && sudo apt-get install -y g++ clang spirv-tools glslang-tools
 
       # (the steps below all run when one before them failed, so one run shows every failure)
       - name: Check Windows native source regressions

scripts/fsr3_shaders.py

@@ -0,0 +1,129 @@
+"""Compile AMD's FSR 3.1 upscaler passes into the SPIR-V headers gpu/vk uses.
+
+The FidelityFX SDK ships each pass as GLSL that includes the SDK's own GPU headers, so the eleven
+variants below are the same eight passes compiled with different options. They are checked in like
+every other shader in gpu/vk/shaders, so a clone builds without glslang; this script regenerates
+them, and --check proves the checked-in files still match their sources (tests/test_fsr3_shaders.py).
+
+    python -I -B scripts/fsr3_shaders.py            # write gpu/vk/shaders/fsr3_*_comp_spv.h
+    python -I -B scripts/fsr3_shaders.py --check    # compare instead of writing
+"""
+import argparse
+import difflib
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SDK = ROOT / "third_party/fidelityfx-sdk"
+GPU = SDK / "include/FidelityFX/gpu"
+PASSES = SDK / "shaders/fsr3upscaler"
+OUT = ROOT / "gpu/vk/shaders"
+
+# The option set the renderer records these passes under. Each one is a promise about the inputs,
+# which are the ones vk_draw.cpp builds for FSR 4.1: the colour is tonemapped and square-root encoded
+# (LDR, values in [0, 1]), the motion is low-resolution and not jittered, and the depth is standard
+# (0 near, 1 far, not inverted). They have to match what gpu/vk/vk_fsr3.cpp hands the passes, which is
+# why they live in one place, and tests/test_fsr3_shaders.py pins them.
+OPTIONS = [
+    "-DFFX_GPU=1",
+    "-DFFX_GLSL=1",
+    "-DFFX_FSR3UPSCALER_OPTION_UPSAMPLE_USE_LANCZOS_TYPE=2",
+    "-DFFX_FSR3UPSCALER_OPTION_REPROJECT_USE_LANCZOS_TYPE=0",
+    "-DFFX_FSR3UPSCALER_OPTION_HDR_COLOR_INPUT=0",
+    "-DFFX_FSR3UPSCALER_OPTION_LOW_RESOLUTION_MOTION_VECTORS=1",
+    "-DFFX_FSR3UPSCALER_OPTION_JITTERED_MOTION_VECTORS=0",
+    "-DFFX_FSR3UPSCALER_OPTION_INVERTED_DEPTH=0",
+]
+
+# name, the pass GLSL it compiles, extra defines. The _nowave variants are for devices without the
+# subgroup operations the single-pass downsampler prefers.
+VARIANTS = [
+    ("prepare_inputs", "prepare_inputs", []),
+    ("luma_pyramid", "luma_pyramid", []),
+    ("luma_pyramid_nowave", "luma_pyramid", ["-DFFX_SPD_NO_WAVE_OPERATIONS=1"]),
+    ("shading_change_pyramid", "shading_change_pyramid", []),
+    ("shading_change_pyramid_nowave", "shading_change_pyramid", ["-DFFX_SPD_NO_WAVE_OPERATIONS=1"]),
+    ("shading_change", "shading_change", []),
+    ("prepare_reactivity", "prepare_reactivity", []),
+    ("luma_instability", "luma_instability", []),
+    ("accumulate", "accumulate", []),
+    ("accumulate_sharpen", "accumulate", ["-DFFX_FSR3UPSCALER_OPTION_APPLY_SHARPENING=1"]),
+    ("rcas", "rcas", []),
+]
+
+
+def compile_one(glslang, name, pass_name, extra, out_path, target_env, variable=True):
+    """Compile one variant. With `variable`, glslang writes a C header; without it, binary SPIR-V,
+    which is what spirv-val reads."""
+    defines = list(OPTIONS)
+    if not any("APPLY_SHARPENING" in d for d in extra):
+        defines.append("-DFFX_FSR3UPSCALER_OPTION_APPLY_SHARPENING=0")
+    cmd = [glslang, "-V", "--quiet", "-S", "comp",
+           "-I" + str(GPU), "-I" + str(GPU / "fsr3upscaler"),
+           *defines, *extra]
+    if variable:
+        cmd += ["--variable-name", f"FSR3_{name.upper()}_COMP_SPV"]
+    cmd += ["-o", str(out_path),
+            str(PASSES / f"ffx_fsr3upscaler_{pass_name}_pass.glsl"),
+            "--target-env", target_env]
+    subprocess.run(cmd, check=True)
+
+
+def comparable(header_text):
+    """The header without glslang's own version comment on its first line, which changes with every
+    glslang release while the SPIR-V below it does not."""
+    lines = header_text.splitlines()
+    if lines and lines[0].lstrip().startswith("//"):
+        lines = lines[1:]
+    return "\n".join(lines) + "\n"
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--glslang", default=None, help="glslangValidator; found on PATH by default")
+    p.add_argument("--spirv-val", default=None, help="spirv-val, to validate each module")
+    p.add_argument("--target-env", default="spirv1.3")
+    p.add_argument("--check", action="store_true", help="compare with the checked-in headers")
+    a = p.parse_args()
+    glslang = a.glslang or shutil.which("glslangValidator") or shutil.which("glslang")
+    if not glslang:
+        print("glslangValidator not found; pass --glslang", file=sys.stderr)
+        return 2
+
+    bad = []
+    with tempfile.TemporaryDirectory(prefix="fsr3-shaders-") as tmp:
+        for name, pass_name, extra in VARIANTS:
+            header = OUT / f"fsr3_{name}_comp_spv.h"
+            made = Path(tmp) / header.name
+            compile_one(glslang, name, pass_name, extra, made, a.target_env)
+            if a.spirv_val:
+                spv = Path(tmp) / f"{name}.spv"
+                compile_one(glslang, name, pass_name, extra, spv, a.target_env, variable=False)
+                subprocess.run([a.spirv_val, str(spv)], check=True)
+            if a.check:
+                have = comparable(header.read_text()) if header.exists() else ""
+                want = comparable(made.read_text())
+                if have != want:
+                    bad.append(name)
+                    if not have:
+                        print(f"{header.name}: missing", file=sys.stderr)
+                    else:
+                        diff = difflib.unified_diff(have.splitlines(), want.splitlines(),
+                                                    "checked in", "regenerated", n=0, lineterm="")
+                        print("\n".join(list(diff)[:12]), file=sys.stderr)
+            else:
+                shutil.copyfile(made, header)
+                print(f"wrote {header.relative_to(ROOT)} ({header.stat().st_size} bytes)")
+    if bad:
+        print(f"{len(bad)} header(s) do not match their source: {', '.join(bad)}", file=sys.stderr)
+        return 1
+    print(f"fsr3 shaders: {len(VARIANTS)} {'match' if a.check else 'written'}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/run_all.py

@@ -36,6 +36,7 @@
     "tests/test_lower_register_markers.py": ["--cxx", "clang++"],
     "tests/test_text_speed.py": ["--cc", "gcc"],
     "tests/test_upscale_fallback.py": ["--cxx", "g++"],
+    "tests/test_fsr3_shaders.py": ["--glslang", "{glslang}", "--spirv-val", "{spirv_val}"],
     "tests/test_taau_env_lookup.py": ["--cxx", "g++"],
     "tests/test_target_overlap.py": ["--cxx", "g++"],
     "tests/test_menu_hit.py": ["--cxx", "g++"],
@@ -116,6 +117,7 @@ def find_tools():
         "spirv_headers": header_dir("HOOKSHOT_SPIRV_HEADERS", "spirv-headers", os.path.join("spirv", "unified1", "spirv.h")),
         "vulkan_headers": header_dir("HOOKSHOT_VULKAN_HEADERS", "vulkanheaders", os.path.join("vulkan", "vulkan.h")),
         "spirv_val": which("spirv-val"),
+        "glslang": which("glslangValidator", "glslang"),
         "cxx": which(os.environ.get("CXX", ""), "clang++", "g++", "c++"),
     }
 

tests/test_fsr3_shaders.py

@@ -0,0 +1,52 @@
+"""The checked-in FSR 3.1 pass shaders still match the FidelityFX SDK sources they came from.
+
+gpu/vk/shaders/fsr3_*_comp_spv.h are generated from third_party/fidelityfx-sdk by
+scripts/fsr3_shaders.py and checked in like every other shader here, so a clone builds without
+glslang. That only stays true if the headers and their sources cannot drift apart, which is what
+this check is for: it recompiles every variant and compares. It also validates each module, so a
+pass that compiles but is not valid SPIR-V is caught here rather than on a device.
+
+python -I -B tests/test_fsr3_shaders.py [--glslang glslangValidator] [--spirv-val spirv-val]
+"""
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+# What the renderer hands the passes (vk_draw.cpp and FSR 4.1's own inputs: tonemapped and square-root encoded colour, standard
+# depth, render-pixel motion, jitter told separately). scripts/fsr3_shaders.py compiles them for exactly this; a value here
+# changing means changing the renderer too.
+OPTIONS_RENDERER_NEEDS = {
+    "FFX_FSR3UPSCALER_OPTION_HDR_COLOR_INPUT": "0",
+    "FFX_FSR3UPSCALER_OPTION_INVERTED_DEPTH": "0",
+    "FFX_FSR3UPSCALER_OPTION_LOW_RESOLUTION_MOTION_VECTORS": "1",
+    "FFX_FSR3UPSCALER_OPTION_JITTERED_MOTION_VECTORS": "0",
+}
+
+
+def check_options():
+    source = (ROOT / "scripts/fsr3_shaders.py").read_text(encoding="utf-8")
+    for name, value in OPTIONS_RENDERER_NEEDS.items():
+        if f'"-D{name}={value}"' not in source:
+            raise SystemExit(f"scripts/fsr3_shaders.py does not compile with {name}={value}")
+
+
+def main():
+    check_options()
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--glslang")
+    p.add_argument("--spirv-val")
+    a = p.parse_args()
+    cmd = [sys.executable, "-I", "-B", str(ROOT / "scripts/fsr3_shaders.py"), "--check"]
+    if a.glslang:
+        cmd += ["--glslang", a.glslang]
+    if a.spirv_val:
+        cmd += ["--spirv-val", a.spirv_val]
+    subprocess.run(cmd, check=True)
+
+
+if __name__ == "__main__":
+    main()

third_party/fidelityfx-sdk/LICENSE.txt

@@ -0,0 +1,21 @@
+This file is part of the FidelityFX SDK.
+
+Copyright (C) 2024 Advanced Micro Devices, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files(the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and /or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions :
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

third_party/fidelityfx-sdk/PROVENANCE.md

@@ -0,0 +1,24 @@
+# FidelityFX SDK
+
+AMD FidelityFX SDK, used for the FSR 3.1 upscaler's GPU sources. Unmodified upstream copy.
+
+- Upstream: https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK
+- Version: v1.1.4, commit `c6efa6bf7f2027b3ec94f28578bb5965eabb9e55`
+- License: MIT, in `LICENSE.txt`. Keep it with any distribution.
+
+What is here and why:
+
+| | |
+|---|---|
+| `include/FidelityFX/gpu/` | The GPU-side headers the passes include: the common core, `fsr1/`, `spd/` (the single-pass downsampler the pyramids use) and `fsr3upscaler/` |
+| `shaders/fsr3upscaler/*.glsl` | The eight upscaler passes, as AMD ships them |
+| `LICENSE.txt` | AMD's MIT notice |
+
+No runtime library is needed, and none is included: the passes are compiled from these sources into
+`gpu/vk/shaders/fsr3_*_comp_spv.h` by `scripts/fsr3_shaders.py`, which is also what
+`tests/test_fsr3_shaders.py` runs to prove the checked-in headers still match. This is the SDK-source
+route rather than AMD's FidelityFX API, which would load AMD's own Vulkan runtime and is Windows
+only.
+
+Nothing in this folder is edited. A change belongs in a new folder with its own note, per
+`CONTRIBUTING.md`.