diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..0d267bcb --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# The project owner reviews and merges every pull request. +* @phantoslayer21 diff --git a/.github/ISSUE_TEMPLATE/game-compatibility-report.yml b/.github/ISSUE_TEMPLATE/game-compatibility-report.yml new file mode 100644 index 00000000..92059d3f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/game-compatibility-report.yml @@ -0,0 +1,122 @@ +name: Game compatibility report +description: Report how WrongGPU behaves in a game +title: "[Game] " +labels: ["game-compatibility"] +body: + - type: markdown + attributes: + value: | + WrongGPU 0.6.0's tested games are listed in COMPATIBILITY.md. Other games are experimental. + Use only games without anti-cheat. Do not attach DLSS files or converted model files. + - type: input + id: game + attributes: + label: Game name + placeholder: "Example: Borderlands 4" + validations: + required: true + - type: input + id: game_version + attributes: + label: Game version or build + description: Shown in the game's menu or its store's update information. + validations: + required: true + - type: dropdown + id: store + attributes: + label: Where did you get the game? + options: [Steam, GOG, Epic Games Store, Xbox / Microsoft Store, Other] + validations: + required: true + - type: dropdown + id: api + attributes: + label: Graphics API the game used + options: [DirectX 12, DirectX 11, Vulkan, Not sure] + validations: + required: true + - type: input + id: upscalers + attributes: + label: Upscaling options the game offers + placeholder: "AMD FSR 3, AMD FSR 4, DLSS, XeSS" + validations: + required: true + - type: input + id: other_mods + attributes: + label: Other mods or overlays running + description: For example OptiScaler, ReShade, Cyber Engine Tweaks or MSI Afterburner. Write "none" if there are none. + validations: + required: true + - type: dropdown + id: result + attributes: + label: What happened? + options: + - Works well + - Works, with visual problems + - Game crashes or freezes + - Black or white screen + - No DLSS or other upscaler option + - WrongGPU does not become active (the overlay or Last run shows something else) + - Launcher refused or failed + - Other + validations: + required: true + - type: input + id: model_state + attributes: + label: WrongGPU state and test duration + description: Did the FPS overlay show DLSS → WrongGPU Model M (or WrongGPU RR), and what did Last run show? Did it stay active, and for how long? + validations: + required: true + - type: textarea + id: details + attributes: + label: Details + description: What looked wrong, when it happens and anything that changed it. Include reproduction steps and any flicker, ghosting, wrong colors, UI problems or stutter. + validations: + required: true + - type: input + id: settings + attributes: + label: Settings used + description: Output resolution, upscaler and quality mode, Ray Reconstruction on or off and its mode, ray tracing, frame generation, dynamic resolution and sharpening. + placeholder: "2560x1440, DLSS Quality, RR Fast, path tracing on, FG off, dynamic resolution off" + validations: + required: true + - type: input + id: fps + attributes: + label: Matched performance comparison (optional) + placeholder: "AMD FSR: average / 1% low; WrongGPU: average / 1% low; overlay ms in each mode" + - type: input + id: system + attributes: + label: Graphics card, driver, Windows version + placeholder: "RX 9070 XT, Adrenalin version, Windows 11 version" + validations: + required: true + - type: input + id: installer + attributes: + label: WrongGPU version + placeholder: "0.6.0" + validations: + required: true + - type: textarea + id: logs + attributes: + label: Logs and screenshots + description: Attach the ZIP from Collect logs on the game's page in the launcher, plus screenshots or a clip of any problem. Review logs before sharing; paths may include your Windows user name. See docs/TESTING-OTHER-GAMES.md. + - type: checkboxes + id: confirm + attributes: + label: Confirmations + options: + - label: This game has no anti-cheat, and I did not bypass a launcher refusal. + required: true + - label: I understand compatibility is experimental and tested at my own risk. + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index cdb65dd0..4eb29f39 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,13 +1,21 @@ **What this changes and why** -**How it was tested** (CPU tests of BUILDING.md; GPU or game tests if any, with synthetic data) +**What each new or substantially changed file is based on** (public document, test result or own design) + +**How it was tested** (CI runs the CPU tests; say what else you ran: GPU or game tests, with synthetic data) **Checklist** -- [ ] I have made the clean-room statement of CONTRIBUTING.md (first pull request: copy it here). -- [ ] Every commit has a `Signed-off-by:` line. -- [ ] New source files carry `SPDX-License-Identifier: MIT`; this description says what each new or changed file is - based on. -- [ ] No files of the original upscaler (see CONTRIBUTING.md), no model data, game files, captures, screenshots or binaries; no paths, user or machine names of - my PC. +- [ ] I make the clean-room statement of + [CONTRIBUTING.md](https://github.com/phantoslayer21/wronggpu/blob/main/CONTRIBUTING.md#the-clean-room-statement) + for this and all my contributions (required once, in my first pull request). +- [ ] Every commit has a `Signed-off-by:` line (`git commit -s`; Developer Certificate of Origin 1.1). +- [ ] New source files carry the SPDX licence line for MIT, or are covered in `REUSE.toml`. +- [ ] No files of the original upscaler (see CONTRIBUTING.md), no model data, game files, captures, screenshots or + binaries; no paths, user or machine names of my PC. - [ ] Any new third-party component is under a permitted licence and listed in THIRD-PARTY-NOTICES and REUSE.toml. -- [ ] Kernel changes meant to be bit-identical: the comparison is shown. +- [ ] Numbers in documents come with their measurement record. +- [ ] Kernel or runtime changes: I say whether the output is meant to stay bit-identical and show the comparison. + +A maintainer scans every pull request on their side before merge (clean-room gate), reviews it, and tests it on a GPU +when the change touches kernels, the runtime, the front end or the Ray Reconstruction plugin (CONTRIBUTING.md, "How a +pull request gets merged"). diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000..1cc10255 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,90 @@ +# CPU checks for every pull request and for main: licence (REUSE), line endings, the CPU builds and the CPU test set. +# No GPU job: kernels, the runtime library and the GPU tests are built and run by the maintainer (CONTRIBUTING.md). +name: CI + +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + checks: + name: Licence and line endings + runs-on: windows-2022 + steps: + - uses: actions/checkout@v4.2.2 + - uses: actions/setup-python@v5.3.0 + with: + python-version: "3.12" + - name: Line endings + run: python tools/ci/check_line_endings.py + - name: Licence (REUSE) + run: | + $PSNativeCommandUseErrorActionPreference = $true + python -m pip install --disable-pip-version-check reuse==5.0.2 + reuse lint + + build-and-test: + name: CPU build and tests + runs-on: windows-2022 + timeout-minutes: 90 + env: + CMAKE_BUILD_PARALLEL_LEVEL: "4" + PYTHONDONTWRITEBYTECODE: "1" + steps: + - uses: actions/checkout@v4.2.2 + - uses: actions/setup-python@v5.3.0 + with: + python-version: "3.12" + - name: Python packages + run: python -m pip install --disable-pip-version-check numpy ninja + - uses: ilammy/msvc-dev-cmd@v1.13.0 + with: + arch: x64 + - name: Converter + run: | + $PSNativeCommandUseErrorActionPreference = $true + cmake -S clean/converter -B out/converter -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_POLICY_DEFAULT_CMP0091=NEW -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded + cmake --build out/converter + ctest --test-dir out/converter --output-on-failure + - name: Shared settings + run: | + $PSNativeCommandUseErrorActionPreference = $true + cmake -S clean/wgshared -B out/wgshared -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_POLICY_DEFAULT_CMP0091=NEW -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded + cmake --build out/wgshared + ctest --test-dir out/wgshared --output-on-failure + - name: FSR front end (CPU tests) + run: | + $PSNativeCommandUseErrorActionPreference = $true + cmake -S clean/fsr -B out/frontend -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_POLICY_DEFAULT_CMP0091=NEW -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded -DWG_MODEL_K=OFF -DWG_BUILD_ID=ci -DWG_BUILD_ASI=ON + cmake --build out/frontend + ctest --test-dir out/frontend --output-on-failure -R "unit|hosted|diagnostic|support" -E "overlay|split|d3d12" + - name: HIP runtime stand-in for the launcher tests + run: | + $PSNativeCommandUseErrorActionPreference = $true + New-Item -ItemType Directory -Force out/mockhip | Out-Null + cl /nologo /LD /O2 clean/installer/tests/mock_hip.c /Fe:out/mockhip/amdhip64_7.dll /Fo:out/mockhip/ + "WRONGGPU_HIP_RUNTIME=$PWD\out\mockhip\amdhip64_7.dll" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8 + - name: Launcher core (CPU tests) + run: | + $PSNativeCommandUseErrorActionPreference = $true + cmake -S clean/installer -B out/launcher-tests -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_POLICY_DEFAULT_CMP0091=NEW -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded -DWRONGGPU_PAYLOAD_DIR="$PWD/out/no-payload" -DWRONGGPU_TESTING=OFF -DWRONGGPU_PRESET_K=OFF -DWRONGGPU_DIRECT_ROUTE=OFF + cmake --build out/launcher-tests --target wg-core-tests launcher-core-tests coexist-core-tests + ctest --test-dir out/launcher-tests --output-on-failure -R "^(wg-core|launcher-core|coexist-core|source-size|wording)$" + - name: Ray Reconstruction plugin (build and CPU tests) + run: | + $PSNativeCommandUseErrorActionPreference = $true + $env:VSDEVCMD = Join-Path $env:VSINSTALLDIR 'Common7\Tools\VsDevCmd.bat' + python clean/rr_f/proxy/tools/build.py --out out/rr-proxy --no-tests + python tools/ci/run_proxy_core_tests.py out/rr-proxy + "WG_RR_PROXY_BUILD=$PWD\out\rr-proxy" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8 + - name: Python tests (CPU) + run: python tools/ci/run_python_tests.py --jobs 3 diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md new file mode 100644 index 00000000..e1d08df0 --- /dev/null +++ b/COMPATIBILITY.md @@ -0,0 +1,88 @@ +# Game compatibility + +These notes apply to **WrongGPU 0.6.0**: Model M and Ray Reconstruction through the **WrongGPU edition of OptiScaler**, +set up by the WrongGPU launcher. "Ray Reconstruction" means WrongGPU's own Ray Reconstruction ran in the game; Model M +means super resolution only. This page grows with the community's reports: see [How to add your game](#how-to-add-your-game). + +## Tested games + +Tested on a Radeon RX 9070 XT. + +| Game | Model M | Ray Reconstruction | Notes | +| --- | --- | --- | --- | +| **Cyberpunk 2077** | Yes | Yes | Our main test game. | +| **Borderlands 4** | Yes (tested with 0.4.5) | Yes | Ray Reconstruction needs one Engine.ini setting, and the game removes it on every start. After the install the launcher asks: **Fix it for me** adds the setting and makes the file read-only (uninstalling WrongGPU undoes both); **Show me how** gives the steps. The game creates Ray Reconstruction itself, so it needs the WrongGPU edition of OptiScaler. About 1.6 ms a frame at 1080p output (from 642x361): 1.589 ms in `clean/installer/tests/logs/bl4-rr-only.log`. | +| **RESIDENT EVIL requiem** | Yes | Yes, experimental | Needs **REFramework**, installed by you first: the game blocks OptiScaler without it. WrongGPU never installs, downloads or replaces REFramework; the launcher tells you when it is missing. Ray Reconstruction runs when the game's **Ray Tracing** setting is **Path Tracing** and its upscaler is **DLSS**. The game prepares Ray Reconstruction at its first start, not in the launcher. Very occasionally a single frame comes out far too bright or too dark at a scene change (see Known limits). | +| **Hogwarts Legacy** | Yes | Not available | Since the game's November 2026 update its Ray Reconstruction option is greyed out and WrongGPU's Ray Reconstruction isn't available, so the launcher doesn't offer it there. Ray Reconstruction worked before that update. | +| **Marvel's Spider-Man 2** | Yes (choose **FSR** as the game's upscaler: its menu doesn't offer DLSS) | Experimental opt-in, not recommended | With Ray Reconstruction the game often freezes the GPU or crashes. The release notes explain the opt-in for those who want to try it anyway. | +| **LEGO Batman** | Yes | Not offered | The game's menu has no Ray Reconstruction option. | +| **The Witcher 3 Remastered** | Earlier version (0.4.5) | — | Not retested with 0.6.0. | +| **Control** | Earlier versions | — | Not retested with 0.6.0. This result does not cover Control Resonant. | +| **Crimson Desert** | Earlier versions | — | Not retested with 0.6.0. | +| **Ratchet & Clank: Rift Apart** | Earlier versions | — | Not retested with 0.6.0. | +| **007 First Light** | Unsupported | Unsupported | Crashes at start under OptiScaler. | +| **Other games** | Experimental / unverified | Experimental / unverified | OptiScaler support and the launcher accepting a game alone do not establish WrongGPU compatibility. [Send a report](https://github.com/phantoslayer21/wronggpu/issues/new?template=game-compatibility-report.yml). | + +A successful run does not cover every game build, graphics setting, quality mode or frame-generation configuration. +Results from earlier WrongGPU versions are labelled as such. The Borderlands 4 figure is Ray Reconstruction's own GPU +time per frame, from `clean/installer/tests/logs/bl4-rr-only.log`, a trimmed excerpt of WrongGPU's plugin log from a +test run (about 1.59 ms per frame, render 642x361, output 1920x1080). The Ray Reconstruction mode and the WrongGPU +version of that run are not recorded in the excerpt. + +## Requirements for another game + +- A **DirectX 12 game supported by OptiScaler**, with upscaler inputs that provide the color, depth and motion + information WrongGPU needs. Choose **DLSS** as the game's upscaler. +- **Radeon RX 9070 or RX 9070 XT** (RX 9060 XT / RX 9060 supported, not yet tested) and a recent AMD Adrenalin driver. + No AMD HIP runtime is needed. +- A local DLSS super resolution file of version **310.5 or newer** for Model M and, for Ray Reconstruction, a **DLSS Ray + Reconstruction file 310.7 or newer**, each from any game or app on your PC (not necessarily the game you play). The + launcher looks for them in your installed games. +- For Ray Reconstruction, the game must use DLSS Ray Reconstruction through game interface version 2.7, 2.8 or 2.14, or + create it directly. Games on other game interface versions keep their own denoiser. Games that create Ray + Reconstruction themselves (for example Unreal Engine games with their own plugin) need the WrongGPU edition of + OptiScaler. +- **No anti-cheat.** Do not bypass a launcher refusal. + +Older Radeon cards, DirectX 11 and Vulkan are unsupported in this release. + +## Known limits + +- Ray Reconstruction can still show occasional visual artifacts, such as ghosting on thin lines in reflections, or + blotches in Cyberpunk 2077 with path tracing. +- RESIDENT EVIL requiem: very occasionally a single frame comes out far too bright or too dark at a scene change (after + loading a save, or during flashes of lightning). It lasts one frame. +- Preset K is not included in 0.6.0. +- Radeon RX 9060 XT / RX 9060: supported, not yet tested. +- Without a DLSS Ray Reconstruction file of version 310.7 or newer on your PC, the game keeps its own denoiser and the + launcher says so. +- After an AMD driver update (or a WrongGPU update) the launcher prepares Ray Reconstruction again in the background; a + game started before that is done prepares it at its first start. +- Frames the network can't use (for example a render size larger than the output, or textures too small during an + intro) are passed through or go to AMD FSR, and WrongGPU carries on with the next normal frame. + +## How to add your game + +Anyone can add a game to this page. + +1. Test it as [Testing WrongGPU in other games](docs/TESTING-OTHER-GAMES.md) describes: a game without anti-cheat, the + FPS overlay or the game page's **Last run** showing that WrongGPU's Model M (or Ray Reconstruction) really ran, at + least one longer play session, and the settings you used. +2. Report it with the [game compatibility form](https://github.com/phantoslayer21/wronggpu/issues/new?template=game-compatibility-report.yml) + (or in #bug-reports on the [WrongGPU Discord server](https://discord.gg/745z9MfKwm)), with the zip from **Collect + logs**. +3. Optionally open a pull request that adds a row to the table above: the game, Model M and Ray Reconstruction + results, what you tested on (GPU, driver, WrongGPU version) and a link to your report. A timing goes in only with + the log line it comes from (game, resolution, mode, WrongGPU version). One report marks a game as "reported"; a + maintainer moves it to "tested" after checking it. + +## Testing and reports + +Follow [Testing WrongGPU in other games](docs/TESTING-OTHER-GAMES.md). AMD FSR frames and passed-through frames are not +Model M or Ray Reconstruction results: check the FPS overlay ("DLSS → WrongGPU Model M" or "DLSS → WrongGPU RR") and +the game page's **Last run**. + +Identify the game build, GPU and driver, WrongGPU version, output resolution, input upscaler, quality mode and whether +Ray Reconstruction was on (and its mode). Include the support zip from **Collect logs** on the game's page in the +launcher, reproduction steps, visual problems and matched performance comparisons. Community reports help establish +compatibility, but no fixed report count automatically makes a game validated. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3723f5e..58ff431e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,23 +1,46 @@ # Contributing to WrongGPU -Thank you for helping. WrongGPU is a clean-room implementation (see [docs/CLEAN-ROOM.md](docs/CLEAN-ROOM.md)), and that -only holds if every contribution is clean too. Please read this whole page before you open a pull request. +WrongGPU is a community project: anyone can propose changes by pull request. It is also a clean-room implementation +(see [docs/CLEAN-ROOM.md](docs/CLEAN-ROOM.md)), and that only holds if every contribution is clean too. Please read +this whole page before you open a pull request. Ideas and plans: [ROADMAP.md](ROADMAP.md). Game results: +[COMPATIBILITY.md](COMPATIBILITY.md). New here? Read the [welcome discussion](https://github.com/phantoslayer21/wronggpu/discussions/1); +a good first task is [building from a fresh clone](https://github.com/phantoslayer21/wronggpu/issues/2). + +## How a pull request gets merged + +1. You open a pull request against `main`, with the clean-room statement (first pull request) and every commit signed + off (see below). The pull-request template has checkboxes for both. +2. **CI** runs on a Windows runner (`.github/workflows/ci.yml`); it must pass: + - licence check: [REUSE](https://reuse.software) lint (the licence and copyright data in `REUSE.toml` is valid and + covers every file); + - line endings: files are stored exactly as committed (`.gitattributes` is `* -text`; no CR LF); + - CPU builds and tests: the converter, the shared settings, the FSR front end, the launcher core and the Ray + Reconstruction plugin with their CPU tests, and the CPU Python test set (`tools/ci/run_python_tests.py`). + CI has no GPU: kernels and the runtime library are not built there, and no GPU test runs. +3. **Checks by a maintainer, by hand, before merge:** + - **Clean-room gate:** every pull request is scanned on the maintainer's side before it is merged (a private scan + for material that must not appear in a clean implementation), and the clean-room statement is checked. + - **Review** by someone who did not write the change. + - **A GPU test on real hardware** (a Radeon RX 9000-series card) when the change touches kernels, the runtime, + the front end or the Ray Reconstruction plugin. +4. The project owner merges. Releases are built, tested on real hardware and published by the owner (see + [RELEASING.md](RELEASING.md)). ## The clean-room statement -Every contributor makes this statement, once, in their first pull request (copy it into the description), and it -applies to every later contribution. In it, "the original upscaler" means NVIDIA DLSS (super resolution and Ray +Every contributor makes this statement, once, in their first pull request (tick the box in the template; it then +applies to every later contribution). In it, "the original upscaler" means NVIDIA DLSS (super resolution and Ray Reconstruction), together with its SDK (NGX, Streamline), its runtime and its model files. > I have never seen, and while working on WrongGPU I will not look at, any of the following: the original upscaler's > binaries or their disassembly, decompilation or GPU assembly; its source code or SDK internals that are not public > documentation; leaked or decompiled upscaler or denoiser code of any vendor; another project's port or > reimplementation of the original upscaler's networks or their kernels. I have not used the original upscaler's -> learned weights, or data computed from them, to write or test my contribution. My contribution is my own work, or third-party code under a -> licence listed in CONTRIBUTING.md, and I have the right to submit it under the MIT licence. +> learned weights, or data computed from them, to write or test my contribution. My contribution is my own work, or +> third-party code under a licence listed in CONTRIBUTING.md, and I have the right to submit it under the MIT licence. -If you cannot make this statement, please do not contribute code; bug reports and test results from your own games -are still welcome. +If you cannot make this statement, please do not contribute code; bug reports, game reports and test results from your +own PC are still very welcome. ## Sign-off (Developer Certificate of Origin) @@ -27,7 +50,7 @@ Every commit carries a sign-off line, which certifies the [Developer Certificate Signed-off-by: Your Name ``` -`git commit -s` adds it. Pull requests with unsigned commits are not merged. +`git commit -s` adds it. Pull requests with commits that are not signed off are not merged. ## What you may use @@ -40,22 +63,30 @@ Signed-off-by: Your Name nothing that forbids reverse engineering. Code that ends up in a shipped binary needs a maintainer's approval first. List every new component in [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES) and in `REUSE.toml`. -Never add: files of the original upscaler of any kind (DLLs, headers, model data), model weights or data derived from them, game files, -screenshots or frame captures from games, or binaries. +Never add: files of the original upscaler of any kind (DLLs, headers, model data), model weights or data derived from +them, game files, screenshots or frame captures from games, or binaries. ## Every change -- An `SPDX-License-Identifier: MIT` line at the top of every new source file (files that cannot carry one, such as - JSON, are listed in `REUSE.toml`). +- An SPDX licence line for MIT (`SPDX-License-Identifier` followed by `MIT`, as at the top of every source file) in + every new source file; files that cannot carry one, such as JSON, are covered in `REUSE.toml`. The `**` rule in + `REUSE.toml` already covers every file, so CI's REUSE lint passes without a header: a missing header is caught in + review, not by CI. - In the pull request, say for each new or substantially changed file what it is based on (public document, test result or own design). -- Tests with synthetic data for what you change; the CPU tests of [BUILDING.md](BUILDING.md) pass. +- Tests with synthetic data for what you change; the CPU tests pass (CI runs them; locally: [BUILDING.md](BUILDING.md)). - No absolute paths of your PC, user names or machine names in code, scripts or documents. Tools are found through the environment variables in BUILDING.md. - Kernels: if a change is meant to keep the output bit-identical, say so and show the comparison (BUILDING.md, section 6). +- Numbers in documents (timings, quality figures): only with the measurement they come from (game, resolution, mode, + build, the log or result file). No number without its record. -## Bug reports +## Bug reports and game reports -Use the issue templates. For a visual problem in a game: the game, the scene, your settings, your GPU and driver, and -the zip from the launcher's **Collect logs**. Please do not attach the upscaler's DLLs or other copyrighted game files. +Use the issue templates: **Bug report** for problems (label `bug`), **Game compatibility report** for how a game +behaves (label `game-compatibility`) (see +[COMPATIBILITY.md](COMPATIBILITY.md), "How to add your game"). For a visual problem: the game, the scene, your settings, +your GPU and driver, and the zip from the launcher's **Collect logs** (check it first: it can contain your Windows user +name). Please do not attach the upscaler's DLLs or other copyrighted game files. Questions and discussion: the +[WrongGPU Discord server](https://discord.gg/745z9MfKwm). diff --git a/README.md b/README.md index 720e4dfc..f15255ae 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,11 @@ this source onward, WrongGPU's source code and its official builds are under the **Help and bug reports:** the [WrongGPU Discord server](https://discord.gg/745z9MfKwm) (channel #bug-reports) or [GitHub issues](https://github.com/phantoslayer21/wronggpu/issues). +**WrongGPU is a community project.** Anyone can report games, fix bugs, write tests or work on the +[roadmap](ROADMAP.md) by pull request; see [Contributing](#contributing). Start with the +[welcome discussion](https://github.com/phantoslayer21/wronggpu/discussions/1). The project owner reviews and merges, +and builds and publishes the official releases. + ## For players ### What you need @@ -41,14 +46,15 @@ requiem needs REFramework, which you install yourself. | Game | Model M | Ray Reconstruction | |---|---|---| | Cyberpunk 2077 | yes | yes (main test game) | -| Borderlands 4 | yes | yes, with the Engine.ini setting | +| Borderlands 4 | yes (tested with 0.4.5) | yes, with the Engine.ini setting | | RESIDENT EVIL requiem | yes | yes, experimental (needs your own REFramework) | | Hogwarts Legacy | yes | not available since the game's November 2026 update | | Marvel's Spider-Man 2 | yes (choose FSR in the game) | experimental opt-in, not recommended | | LEGO Batman | yes | the game offers none | | 007 First Light | not supported (crashes at start under OptiScaler) | | -Other games are experimental. Known issues in 0.6.0: Ray Reconstruction can still show occasional artifacts (ghosting +Other games are experimental; the full list, with requirements and how to add your game, is +[COMPATIBILITY.md](COMPATIBILITY.md). Known issues in 0.6.0: Ray Reconstruction can still show occasional artifacts (ghosting on thin lines in reflections, blotches in Cyberpunk 2077 with path tracing); in RESIDENT EVIL requiem a single frame can very occasionally come out far too bright or dark at a scene change. Full details: the release notes ([clean/installer/RELEASE-NOTES.md](clean/installer/RELEASE-NOTES.md)). @@ -122,10 +128,24 @@ implementation's own design and format notes (per-file provenance records are ke | `clean/third_party` | AMD FidelityFX SDK headers (MIT) | | `data` | converter maps and synthetic test vectors | -Building: [BUILDING.md](BUILDING.md). Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) (every contributor makes the -clean-room statement described there). Security issues: [SECURITY.md](SECURITY.md). Code of conduct: +Building: [BUILDING.md](BUILDING.md). Security issues: [SECURITY.md](SECURITY.md). Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). +## Contributing + +WrongGPU is developed in the open by its community. Ways to help: + +- **Players:** test games and report them ([COMPATIBILITY.md](COMPATIBILITY.md), "How to add your game"); report + bugs with the launcher's **Collect logs** zip. +- **Developers:** pick an item from [ROADMAP.md](ROADMAP.md) or an open issue, and open a pull request. A good first + step: [build WrongGPU from a fresh clone](https://github.com/phantoslayer21/wronggpu/issues/2) and report where + BUILDING.md breaks. + +Every pull request: the clean-room statement and a `Signed-off-by` line on each commit ([CONTRIBUTING.md](CONTRIBUTING.md)), +passing CI (licence, line endings, CPU builds and tests on Windows), then a maintainer's clean-room scan, review and, +when the change touches kernels, the runtime, the front end or the Ray Reconstruction plugin, a test on a Radeon +RX 9000-series card before the owner merges. + ## Licence From this source onward, WrongGPU's source code and the official WrongGPU builds made from it are under the MIT licence diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 00000000..fddd1024 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,54 @@ +# Releasing WrongGPU + +How an official WrongGPU release is made. Contributors don't need to do any of this; it explains what happens between +a merged pull request and a download on the [Releases page](https://github.com/phantoslayer21/wronggpu/releases). + +## Who releases + +Only the project owner builds, tests and publishes official releases. Pull requests are merged into `main` as usual; +a release is a separate decision. Nobody else uploads release packages or creates release tags. + +## 1. The source of a release + +- A release is built from **one commit on `main` of this repository**. That commit is public before the release is + published, so anyone can see exactly what was built. +- The release tag (for example `v0.6.1`) points at that commit. Tags are never moved after publishing; a fix is a new + version. +- The version number is set in the build options of BUILDING.md (`-DWG_BUILD_ID=...` for the front end; + `-DWRONGGPU_VERSION=...`, `-DWRONGGPU_BUILD_ID=...`, `-DWRONGGPU_PAYLOAD_NAME=...` for the launcher). + +## 2. Build and test on real hardware + +- The owner builds the release on the owner's own PC from a fresh checkout of that commit, with the tools and steps of + [BUILDING.md](BUILDING.md): kernels, runtime library, FSR front end, Ray Reconstruction plugin, payload, launcher. +- Before anything is uploaded: + - the CPU tests of BUILDING.md pass (the same set CI runs on every pull request); + - the GPU tests pass on a Radeon RX 9000-series card; + - the release is installed, used and uninstalled in real games with the launcher, including the games named in the + release notes; + - the package contains only WrongGPU's own files and their notices: no file of the original upscaler, no model data, + no OptiScaler file (the launcher downloads OptiScaler from its own release). + +## 3. The release notes + +- The notes live in the repository (`clean/installer/RELEASE-NOTES.md`) and go through a pull request like any other + change. +- They point to the release page, which lists the **SHA-256 of the zip**, and to `SHA256SUMS.txt` inside the zip, which + lists the SHA-256 of every file in it, so a download can be checked. +- **The number rule:** every figure in the release notes, the release page and the README (timings, quality figures, + version requirements, hardware lists) is traced to its measurement record: which game, resolution, mode, WrongGPU + build and log or result file. A figure without a record is left out. Before publishing, someone who did not write + the texts compares every figure across the README, the release page and the release notes, and against its record; + a mismatch or an untraced figure blocks the release until it is fixed or removed. + +## 4. Publishing + +- Uploaded to the Releases page only on the owner's order: the package (`WrongGPU-.zip`), its SHA-256 file + and the release notes, attached to the tag of step 1. +- Pre-releases are marked as such. +- After publishing, the downloaded package is checked against the SHA-256 on the release page and in `SHA256SUMS.txt`. + +## Licence of releases + +From the source of this repository onward, official builds are under the MIT licence, the same as the source +([LICENSE](LICENSE)); the package carries the licence text and the third-party notices. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 00000000..bf78fc1f --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,39 @@ +# Roadmap + +What the project would like to work on next. These are plans, not promises: there are no dates, and the order can +change with what contributors pick up and what testing on real hardware shows. Discuss an item in its issue or on the +[WrongGPU Discord server](https://discord.gg/745z9MfKwm) before starting a large change. Every contribution follows +[CONTRIBUTING.md](CONTRIBUTING.md) (clean-room statement, sign-off, tests). + +## Next release (0.6.1) + +- **Preset K** back as a second Model choice (the code is in `clean/k`; it is built and tested, but not offered in + 0.6.0). +- **Hogwarts Legacy:** Ray Reconstruction again. Its Ray Reconstruction option has been greyed out since the game's + November 2026 update; the cause is not yet known. +- **RESIDENT EVIL requiem:** find the cause of the rare single over- or under-exposed frame at a scene change. +- Test tooling: the Ray Reconstruction end-to-end test (`clean/rr_f/runtime/tests/e2e.py`) should set the compile-wait + setting it needs by itself; tidy the remaining compiler warnings of the launcher build. + +## Ray Reconstruction speed + +Make Ray Reconstruction cheaper per frame on RX 9000 cards without changing its output: faster kernels for the body +stages and the output stage, fewer passes, better use of the hardware's matrix instructions. Any change that is meant +to keep the output bit-identical shows the comparison (BUILDING.md, section 6) and is checked on a GPU before merge. + +## More hardware: RDNA 3 + +Today the kernels target RDNA 4 (gfx1201 / gfx1200). Running on RDNA 3 cards needs kernels without RDNA 4's +FP8 matrix instructions and a check of what the results and the speed would be. This starts as an investigation. + +## Vulkan and Linux + +Today WrongGPU works with DirectX 12 games on Windows. A Vulkan path (for Vulkan games, and for DirectX 12 games under +Proton on Linux) would need a Vulkan executor for the runtime and a way to receive the game's upscaler inputs there. +This starts as a design discussion. + +## Always welcome + +- Game reports and additions to [COMPATIBILITY.md](COMPATIBILITY.md). +- Tests for code without enough of them, especially CPU tests that CI can run. +- Documentation: clearer build steps, fixes to BUILDING.md from your own fresh build. diff --git a/clean/rr_f/proxy/tools/build.py b/clean/rr_f/proxy/tools/build.py index 2b8fc4c6..bddd9587 100644 --- a/clean/rr_f/proxy/tools/build.py +++ b/clean/rr_f/proxy/tools/build.py @@ -403,6 +403,7 @@ def main(): ap.add_argument("--proxy-name", help="file name of the built release proxy, or 'interposer'") ap.add_argument("--probe-name", help="file name of the built probe proxy, or 'interposer'") a = ap.parse_args() + a.out = os.path.abspath(a.out) # the compiles run inside the output folder os.makedirs(a.out, exist_ok=True) if a.binding: try: diff --git a/docs/TESTING-OTHER-GAMES.md b/docs/TESTING-OTHER-GAMES.md new file mode 100644 index 00000000..0b196a22 --- /dev/null +++ b/docs/TESTING-OTHER-GAMES.md @@ -0,0 +1,47 @@ +# Testing WrongGPU in other games + +This guide applies to **WrongGPU 0.6.0** and its launcher. See [game compatibility](../COMPATIBILITY.md) for current results. It helps produce a useful report without confusing AMD FSR or passed-through frames with WrongGPU's own results. + +## Before you start + +- Use a **DirectX 12 game supported by OptiScaler**. +- **Do not test in games with anti-cheat**, and do not bypass a launcher refusal. +- Use an **RX 9070 or RX 9070 XT** and a recent AMD Adrenalin driver (no HIP runtime needed). The RX 9060 XT / RX 9060 is supported but untested; say which card and how much video memory it has when you report. +- Back up your saves. The launcher backs up every game file it replaces and puts them back when you uninstall. + +## Install + +1. Download and extract [WrongGPU 0.6.0](https://github.com/phantoslayer21/wronggpu/releases/tag/v0.6.0) and run `WrongGPU-0.6.0.exe`. +2. If the game isn't in the Library, use **Add game** and pick the game's folder or exe. +3. Open the game's page and click **Install**. The launcher gets the WrongGPU edition of OptiScaler, finds a usable DLSS file on your PC, from any game or app (310.5 or newer for Model M, a DLSS Ray Reconstruction file 310.7 or newer for Ray Reconstruction) and, for Ray Reconstruction, prepares its GPU code. +4. Turn on the FPS overlay with the game page's **Turn on the FPS overlay** button before you start the game. +5. Start the game and choose **DLSS** as its upscaler, initially in **Quality** mode (and DLSS Ray Reconstruction if the game has it). + +## Check the game + +1. Let startup finish. The FPS overlay should show **DLSS → WrongGPU Model M**, or **DLSS → WrongGPU RR** and its mode. After you quit, the game page's **Last run** shows what ran. +2. Play for at least 10 minutes. Include camera motion, thin geometry, foliage, moving objects, particles, reflections and scene transitions where available. +3. Check for flicker, ghosting, smearing, wrong colors, UI problems, stutter, crashes or a black screen. Write down the scene and settings that trigger a problem. +4. For a matched visual comparison, switch to AMD FSR in **OptiScaler's menu** (Insert), then return to WrongGPU before recording WrongGPU results. +5. Test resolution changes, quality switches, upscaler switches and fresh game starts separately. Note memory growth, errors and whether WrongGPU resumes. + +## Compare performance + +Use the same scene, output resolution, input upscaler, quality mode and graphics settings. Keep frame generation, dynamic resolution, V-sync and frame caps the same between runs, and say whether they are on. For a straightforward comparison, turn frame generation and dynamic resolution off. + +Let the scene settle before recording. Measure AMD FSR, then WrongGPU, then AMD FSR again. Report average FPS and 1% lows if your tool provides them. If the two AMD runs differ a lot, repeat the comparison before claiming a gain. The time **Last run** shows for Ray Reconstruction is its own time per frame, not the game's frame time. + +## Send the report + +Use [GitHub's game compatibility form](https://github.com/phantoslayer21/wronggpu/issues/new?template=game-compatibility-report.yml) or the **#bug-reports** channel of the [WrongGPU Discord server](https://discord.gg/745z9MfKwm). Include: + +- Game name, store and version/build. +- WrongGPU version, GPU and video memory, AMD driver and Windows version. +- Output resolution, input upscaler, quality mode, graphics settings, and Ray Reconstruction on or off (and its mode). +- What the FPS overlay and **Last run** showed. +- Reproduction steps, screenshots or clips, and matched FPS / 1% low results. +- The ZIP from **Collect logs** on the game's page in the launcher. + +Review the ZIP before posting: system information and file paths may include your Windows username. Do not include DLSS files or converted model files. + +To remove WrongGPU from the game, use **More → Uninstall WrongGPU** on the game's page; it puts the game's own files back. diff --git a/tools/ci/check_line_endings.py b/tools/ci/check_line_endings.py new file mode 100644 index 00000000..98b53439 --- /dev/null +++ b/tools/ci/check_line_endings.py @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: MIT +"""Line-ending check (CI): every tracked file is stored as committed, without line-ending conversion. + +The repository's .gitattributes says `* -text`: git never converts line endings, so the converter maps and the test +vectors keep the exact bytes their SHA-256 digests describe. This check fails when + - .gitattributes no longer starts the rules with `* -text`, or + - a tracked text file holds a CR LF pair (the repository is LF only; a CRLF file needs a deliberate exception here), or + - git reports any file as a text file under conversion (`attr/text` or `attr/text=auto` in `git ls-files --eol`). +Run from the repository root: python tools/ci/check_line_endings.py +""" +import subprocess +import sys +from pathlib import Path + +CRLF_ALLOWED = set() # repository-relative paths of files that are meant to hold CR LF (none today) + + +def main(): + root = Path(subprocess.check_output(['git', 'rev-parse', '--show-toplevel'], text=True).strip()) + problems = [] + rules = [l.strip() for l in (root / '.gitattributes').read_text(encoding='utf-8').splitlines() + if l.strip() and not l.lstrip().startswith('#')] + if not rules or rules[0].split()[:2] != ['*', '-text']: + problems.append('.gitattributes: the first rule must be "* -text" (found %r)' % (rules[0] if rules else None)) + eol = subprocess.check_output(['git', 'ls-files', '--eol', '-z'], cwd=root).decode('utf-8').split('\0') + checked = 0 + for entry in eol: + if not entry: + continue + meta, path = entry.split('\t', 1) + fields = meta.split() + index_eol, attr = fields[0], fields[2] if len(fields) > 2 else '' + checked += 1 + if attr.startswith('attr/text') or attr.startswith('attr/auto'): + problems.append('%s: converted by git (%s)' % (path, attr)) + if index_eol in ('i/crlf', 'i/mixed') and path not in CRLF_ALLOWED: + problems.append('%s: CR LF in the committed file (%s)' % (path, index_eol)) + for p in problems: + print(p) + print('line endings: %d files checked, %d problem(s)' % (checked, len(problems))) + return 1 if problems else 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/tools/ci/run_proxy_core_tests.py b/tools/ci/run_proxy_core_tests.py new file mode 100644 index 00000000..20a22ff7 --- /dev/null +++ b/tools/ci/run_proxy_core_tests.py @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: MIT +"""Run the Ray Reconstruction plugin's CPU test executables (CI, and locally), as clean/rr_f/proxy/tools/build.py runs +them, after `python clean/rr_f/proxy/tools/build.py --out --no-tests`. That build still builds and runs the +WARP-based probe and hook tests (build.py: the probe test's fake game host and the hook tests' WARP sequence); it skips +only the Python unit tests and the core executables, and this script runs the core executables. The plugin's other +test executables create a Direct3D 12 device and are not run here (BUILDING.md, section 7). +Usage (from the repository root): python tools/ci/run_proxy_core_tests.py +""" +import glob +import os +import subprocess +import sys + + +def main(): + out = sys.argv[1] + core = os.path.join(out, 'core') + data = os.path.join('clean', 'rr_f', 'proxy', 'tests', 'data') + runs = [('core', [os.path.join(core, 'test_proxy_core.exe')]), + ('probe core', [os.path.join(core, 'test_probe_core.exe')]), + ('setupapi identity', [os.path.join(core, 'test_setupapi_identity.exe')])] + runs += [('RR provider ' + os.path.basename(f), [os.path.join(core, 'test_ngx_rr.exe'), f]) + for f in sorted(glob.glob(os.path.join(data, '*-rr-frames.json')))] + runs += [('replay ' + os.path.basename(f), [os.path.join(core, 'test_replay_profile.exe'), f]) + for f in sorted(glob.glob(os.path.join(data, '*-traffic.json')))] + bad = 0 + for name, args in runs: + r = subprocess.run(args, capture_output=True, text=True, timeout=1800) + last = (r.stdout + r.stderr).strip().splitlines()[-1:] or [''] + print('%-45s exit %d %s' % (name, r.returncode, last[0][:150]), flush=True) + if r.returncode != 0: + bad += 1 + print((r.stdout + r.stderr)[-4000:], flush=True) + print('plugin CPU tests: %d run, %d failed' % (len(runs), bad)) + return 1 if bad else 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/tools/ci/run_python_tests.py b/tools/ci/run_python_tests.py new file mode 100644 index 00000000..c0383024 --- /dev/null +++ b/tools/ci/run_python_tests.py @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: MIT +"""Run the CPU Python test set (CI, and locally): every clean/**/test_*.py except the modules that need a GPU device. + +Each module runs in its own process (package folders with `python -m unittest `, folders without __init__.py +with `discover` in that folder). Skips are fine (each module states its reason: the host lane emulator needs Linux, a +compiler or a file that is not in the repository, an opt-in GPU variable); a failure or an error fails the run. +`clean/wgshared/tests/*.py` are scripts that the wgshared ctest runs, so they are not run here. +Run from the repository root: python tools/ci/run_python_tests.py [--jobs N] +""" +import argparse +import concurrent.futures as cf +import os +import re +import subprocess +import sys +import time +from pathlib import Path + +GPU_MODULES = { # load a D3D12 / HIP device (BUILDING.md, section 6) + 'clean/k/tests/test_k_hidden_guard.py', 'clean/k/tests/test_k_input_uniforms.py', + 'clean/k/tests/test_k_interop_timing.py', 'clean/k/tests/test_k_norm_r16.py', + 'clean/k/tests/test_k_output_arithmetic.py', 'clean/k/tests/test_k_output_selector.py', + 'clean/k/tests/test_k_runtime_gpu.py', 'clean/k/tests/test_k_tiled_input.py', + 'clean/rr_f/proxy/tests/test_capture_replay.py', 'clean/rr_f/runtime/tests/test_model_pack.py', +} +RUN_ELSEWHERE = {'clean/wgshared/tests/test_dummy_extension.py', 'clean/wgshared/tests/test_gen_registry.py'} + + +def run_one(root, rel, timeout): + d = (root / rel).parent + if (d / '__init__.py').exists(): + args = [sys.executable, '-B', '-m', 'unittest', '-q', rel[:-3].replace('/', '.')] + else: + args = [sys.executable, '-B', '-m', 'unittest', 'discover', '-q', '-s', str(d), '-t', str(d), '-p', Path(rel).name] + t0 = time.time() + try: + r = subprocess.run(args, cwd=root, capture_output=True, text=True, timeout=timeout) + out, rc = r.stdout + r.stderr, r.returncode + except subprocess.TimeoutExpired as e: + # TimeoutExpired carries the captured output as bytes, even with text=True + out = ''.join(s.decode(errors='replace') if isinstance(s, bytes) else (s or '') for s in (e.stdout, e.stderr)) + rc = 'timeout' + ran = re.findall(r'Ran (\d+) tests?', out) + skipped = re.findall(r'skipped=(\d+)', out) + return rel, rc, int(ran[-1]) if ran else 0, int(skipped[-1]) if skipped else 0, time.time() - t0, out + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument('--jobs', type=int, default=2) + ap.add_argument('--timeout', type=int, default=2400) + a = ap.parse_args() + root = Path(subprocess.check_output(['git', 'rev-parse', '--show-toplevel'], text=True).strip()) + os.environ.setdefault('PYTHONDONTWRITEBYTECODE', '1') + files = sorted(p.relative_to(root).as_posix() for p in (root / 'clean').rglob('test_*.py')) + todo = [f for f in files if f not in GPU_MODULES and f not in RUN_ELSEWHERE] + print('python tests: %d files, %d run here, %d GPU modules left out, %d run by ctest' + % (len(files), len(todo), len(GPU_MODULES & set(files)), len(RUN_ELSEWHERE & set(files))), flush=True) + failed, total_ran, total_skipped = [], 0, 0 + with cf.ThreadPoolExecutor(max(1, a.jobs)) as ex: + for rel, rc, ran, skipped, secs, out in ex.map(lambda f: run_one(root, f, a.timeout), todo): + total_ran += ran + total_skipped += skipped + print('%-60s exit %-7s ran %4d skipped %3d %5.0f s' % (rel, rc, ran, skipped, secs), flush=True) + if rc != 0: + failed.append(rel) + print(out[-6000:], flush=True) + print('python tests: %d ran, %d skipped, %d module(s) failed%s' % (total_ran, total_skipped, len(failed), + (': ' + ', '.join(failed)) if failed else ''), flush=True) + return 1 if failed else 0 + + +if __name__ == '__main__': + sys.exit(main())