phaneron/Kelsidavis-WoWee
1
0
Fork 0
mirror of https://github.com/Kelsidavis/WoWee.git synced 2026-03-23 15:50:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 41
Kelsidavis-WoWee/docs/AMD_FSR2_INTEGRATION.md
Kelsi bae32c1823 Add FSR3 Generic API path and harden runtime diagnostics 
- AmdFsr3Runtime now probes both the legacy ffxFsr3* API and the newer
  generic ffxCreateContext/ffxDispatch API; selects whichever the loaded
  runtime library exports (GenericApi takes priority fallback)
- Generic API path implements full upscale + frame-generation context
  creation, configure, dispatch, and destroy lifecycle
- dlopen error captured and surfaced in lastError_ on Linux so runtime
  initialization failures are actionable
- FSR3 runtime init failure log now includes path kind, error string,
  and loaded library path for easier debugging
- tools/generate_ffx_sdk_vk_permutations.sh added: auto-bootstraps
  missing VK permutation headers; DXC auto-downloaded on Linux/Windows
  MSYS2; macOS reads from PATH (CI installs via brew dxc)
- CMakeLists: add upscalers/include to probe include dirs, invoke
  permutation script before SDK build, scope FFX pragma/ODR warning
  suppressions to affected TUs, add runtime-copy dependency on wowee
- UI labels updated from "FSR2" → "FSR3" in settings, tuning panel,
  performance HUD, and combo boxes
- CI macOS job now installs dxc via Homebrew for permutation codegen
2026-03-09 12:51:59 -07:00

3.7 KiB
Raw Blame History

AMD FSR2 Integration Notes

WoWee supports two FSR2 backends at runtime:

  • AMD FidelityFX SDK backend (preferred when available).
  • Internal fallback backend (used when AMD SDK prerequisites are not met).

SDK Location

AMD SDK checkout path:

extern/FidelityFX-FSR2

FidelityFX SDK checkout path (framegen extern):

extern/FidelityFX-SDK (default branch main from WoWee's fork in build scripts and CI)

Override knobs for local build scripts:

  • WOWEE_FFX_SDK_REPO (default: https://github.com/Kelsidavis/FidelityFX-SDK.git)
  • WOWEE_FFX_SDK_REF (default: main)

Detection expects:

  • extern/FidelityFX-FSR2/src/ffx-fsr2-api/ffx_fsr2.h
  • extern/FidelityFX-FSR2/src/ffx-fsr2-api/vk/shaders/ffx_fsr2_accumulate_pass_permutations.h
  • If permutation headers are missing in the SDK checkout, WoWee CMake copies a vendored snapshot from:
    • third_party/fsr2_vk_permutations

Build Flags

  • WOWEE_ENABLE_AMD_FSR2=ON (default): attempt AMD backend integration.
  • WOWEE_ENABLE_AMD_FSR3_FRAMEGEN=ON (default): build AMD FSR3 framegen interface probe when FidelityFX-SDK headers are present.
  • WOWEE_HAS_AMD_FSR2 compile define:
    • 1 when AMD SDK prerequisites are present.
    • 0 when missing, in which case internal fallback remains active.
  • WOWEE_HAS_AMD_FSR3_FRAMEGEN compile define:
    • 1 when FidelityFX-SDK FI/OF/FSR3+VK headers are detected.
    • 0 when headers are missing (probe target disabled).

Runtime note:

  • Renderer/UI expose a persisted experimental framegen toggle.
  • Runtime loader is Path A only (official AMD runtime library).
  • Path A runtime build now auto-runs tools/generate_ffx_sdk_vk_permutations.sh to ensure required VK permutation headers exist for FSR2/FSR3 upscaler shader blobs.
  • You can point to an explicit runtime binary with:
    • WOWEE_FFX_SDK_RUNTIME_LIB=/absolute/path/to/libffx_fsr3_vk.so (or .dll / .dylib).
  • If no official runtime is found, frame generation is disabled cleanly (Path C).

Current Status

  • AMD FSR2 Vulkan dispatch path is integrated and used when available.
  • UI displays active backend in settings (AMD FidelityFX SDK or Internal fallback).
  • Runtime settings include persisted FSR2 jitter tuning.
  • FidelityFX-SDK extern is fetched across platforms (default: Kelsidavis/FidelityFX-SDK on main).
  • Startup safety behavior remains enabled:
    • persisted FSR2 is deferred until IN_WORLD
    • startup falls back unless WOWEE_ALLOW_STARTUP_FSR2=1

FSR Defaults

  • Quality default: Native (100%)
  • UI quality order: Native, Ultra Quality, Quality, Balanced
  • Default sharpness: 1.6
  • Default FSR2 jitter sign: 0.38
  • Performance preset is intentionally removed.

CI Notes

  • build-linux-amd-fsr2 clones AMD's repository and configures with WOWEE_ENABLE_AMD_FSR2=ON.
  • All build jobs clone:
    • GPUOpen-Effects/FidelityFX-FSR2 (master)
    • Kelsidavis/FidelityFX-SDK (main) by default
  • Linux CI validates FidelityFX-SDK Kits framegen headers:
    • upscalers/fsr3/include/ffx_fsr3upscaler.h
    • framegeneration/fsr3/include/ffx_frameinterpolation.h
    • framegeneration/fsr3/include/ffx_opticalflow.h
    • backend/vk/ffx_vk.h
  • Runtime build path auto-bootstrap:
    • Linux downloads DXC automatically when missing.
    • Windows (MSYS2) downloads DXC automatically when missing.
    • macOS expects dxc to be available in PATH (CI installs it via Homebrew).
  • CI builds wowee_fsr3_framegen_amd_vk_probe when that target is generated by CMake for the detected SDK layout.
  • Some upstream SDK checkouts do not include generated Vulkan permutation headers.
  • WoWee bootstraps those headers from the vendored snapshot so AMD backend builds remain cross-platform and deterministic.
  • If SDK headers are missing entirely, WoWee still falls back to the internal backend.