diff --git a/BUILDING.md b/BUILDING.md index 944c20c8..2e416210 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1,52 +1,52 @@ # Building WrongGPU -From a clean Windows install to a built launcher (`WrongGPU.exe`) with its embedded payload. Everything below runs on -the CPU: no build or unit-test step needs a GPU. Steps that do use a GPU (device tests, timing, game tests) are listed -at the end and are optional. +Build `WrongGPU.exe` and its embedded payload from a clean Windows installation. The build and unit tests run on the +CPU and need no GPU. The optional device tests, timing tools, and game tests at the end need a GPU. ## 1. Tools | Tool | Version used for 0.6.0 | Used for | |---|---|---| | Windows | 10 or 11, x64 | | -| Visual Studio 2026 (Community is enough), workload "Desktop development with C++" | 18.x; MSVC 19.51 (toolset 14.51); its bundled CMake 4.3 and Ninja 1.13 | every C++ build | -| Windows SDK | 10.0.26100 | D3D12 / DXGI headers and libraries, `dxcapi.h` | -| Python | 3.12 (64-bit) | build scripts, reference, tests | -| NumPy | 2.x (2.5 tested) | reference and tests (`python -m pip install numpy`) | -| AMD HIP SDK for Windows | 7.2 (ROCm clang 21) | HIP kernels for gfx1201 / gfx1200 and the runtime library | -| Microsoft DirectX Shader Compiler (DXC) | v1.10.2605.24 (the release zip: `dxc.exe`, `dxv.exe`, `dxcompiler.dll`) | Direct3D 12 kernels | -| AMD Radeon GPU Analyzer (RGA) | 2.15 | the Direct3D 12 kernels' register check | -| Git | any recent | | +| Visual Studio 2026, Community or another edition, with the "Desktop development with C++" workload | 18.x; MSVC 19.51 (toolset 14.51); bundled CMake 4.3 and Ninja 1.13 | Every C++ build | +| Windows SDK | 10.0.26100 | D3D12 and DXGI headers and libraries, `dxcapi.h` | +| Python | 3.12, 64-bit | Build scripts, references, and tests | +| NumPy | 2.x; 2.5 tested | References and tests. Install with `python -m pip install numpy`. | +| AMD HIP SDK for Windows | 7.2, ROCm clang 21 | HIP kernels for gfx1201 and gfx1200, and the runtime library | +| Microsoft DirectX Shader Compiler (DXC) | v1.10.2605.24. Use the release zip containing `dxc.exe`, `dxv.exe`, and `dxcompiler.dll`. | Direct3D 12 kernels | +| AMD Radeon GPU Analyzer (RGA) | 2.15 | Register checks for the Direct3D 12 kernels | +| Git | Any recent version | | -Optional: Pillow (two research tools), MinGW-w64 GCC 13 and Wine 9 (development builds and Linux tests; never used for -a release). +Pillow is optional for two research tools. MinGW-w64 GCC 13 and Wine 9 are optional for development builds and Linux +tests. Releases never use them. -The exact DXC and HIP SDK versions matter if you want the kernels to come out bit-identical to a release (see 6). +Use the exact DXC and HIP SDK versions to reproduce a release's kernels bit for bit. See +[Comparing kernels with a release](#comparing-kernels-with-a-release). ## 2. Where the build finds the tools -No path of the developer's PC is written in the repository. The tools are found through environment variables, with -these defaults: +The repository contains no paths from a developer's PC. Build scripts find tools through these environment variables +and defaults. | Variable | Meaning | Default | |---|---|---| -| `WG_TOOLCHAINS` | folder that holds `dxc-v1.10.2605.24\` (the DXC release zip, unpacked) and `rga-2.15\` (the RGA zip, unpacked) | `\toolchains` (ignored by git) | -| `WG_DXC_DIR` | DXC's `bin\x64` folder (overrides `WG_TOOLCHAINS`) | `%WG_TOOLCHAINS%\dxc-v1.10.2605.24\bin\x64` | -| `WG_RGA` | `rga.exe` (overrides `WG_TOOLCHAINS`) | `%WG_TOOLCHAINS%\rga-2.15\rga.exe` | -| `ROCM_PATH` | HIP SDK folder. Scripts with a `--rocm` argument default to it (the argument wins); the others read it | `C:\Program Files\AMD\ROCm\7.2` | -| `VSDEVCMD` | Visual Studio's `VsDevCmd.bat` (the kernel scripts build two small helper tools); for another edition e.g. `C:\Program Files\Microsoft Visual Studio\18\Professional\Common7\Tools\VsDevCmd.bat` (or `...\18\Enterprise\...`) | `C:\Program Files\Microsoft Visual Studio\18\Community\Common7\Tools\VsDevCmd.bat` | -| `CXX`, `WG_K_RT_CXX`, `WG_K_RT_BUILD`, `WG_CONVERTER_EXE` | Model K table tests (`clean\k\tests\test_k_runtime_tables`, `test_k_runtime_pack`): the compiler is `%CXX%`, else clang++ / g++ on PATH, else the HIP SDK's clang++, else MSVC (`WG_K_RT_CXX=msvc` picks MSVC first); their build folder; an already built converter. With no compiler found the tests skip themselves with that reason | temporary folder; converter built from source | -| `WG_BUILD_ROOT` | default output root of the scripts that have one | `\build` (ignored by git) | -| `WG_DX12_JOBS`, `WG_RR_JOBS` | parallel kernel compiles | number of CPUs (max 12) / 8 | -| `WG_GPU_LOCK` | optional: a script run as `python --timeout -- ` around GPU jobs | unset: GPU jobs run directly | -| `WRONGGPU_HIP_RUNTIME` | the HIP runtime the launcher's probe loads (tests: the stand-in of step 5.1) | the system's | - -Set `ROCM_PATH` to the HIP SDK folder (the commands below also pass it as `--rocm`). Remove `HIP_PATH`, `LLVM_PATH`, -`HIP_DEVICE_LIB_PATH` and `HIP_CLANG_PATH` from the build's environment unless you set them on purpose; the scripts give -the HIP compiler the folder explicitly. - -Open a "x64 Native Tools Command Prompt for VS 2026" (or call `vcvars64.bat`) for every step below, at the repository -root. The commands write into `out\`; any folder outside the repository works the same. +| `WG_TOOLCHAINS` | Folder containing the unpacked DXC release in `dxc-v1.10.2605.24\` and the unpacked RGA release in `rga-2.15\`. | `\toolchains`, ignored by git | +| `WG_DXC_DIR` | DXC's `bin\x64` folder. Overrides `WG_TOOLCHAINS`. | `%WG_TOOLCHAINS%\dxc-v1.10.2605.24\bin\x64` | +| `WG_RGA` | Path to `rga.exe`. Overrides `WG_TOOLCHAINS`. | `%WG_TOOLCHAINS%\rga-2.15\rga.exe` | +| `ROCM_PATH` | HIP SDK folder. Scripts with a `--rocm` argument default to this variable, and the argument takes precedence. Other scripts read the variable. | `C:\Program Files\AMD\ROCm\7.2` | +| `VSDEVCMD` | Visual Studio's `VsDevCmd.bat`, used by the kernel scripts to build two small helper tools. For another edition, use a path such as `C:\Program Files\Microsoft Visual Studio\18\Professional\Common7\Tools\VsDevCmd.bat` or `...\18\Enterprise\...`. | `C:\Program Files\Microsoft Visual Studio\18\Community\Common7\Tools\VsDevCmd.bat` | +| `CXX`, `WG_K_RT_CXX`, `WG_K_RT_BUILD`, `WG_CONVERTER_EXE` | Compiler and build settings for the Model K table tests `clean\k\tests\test_k_runtime_tables` and `test_k_runtime_pack`. The tests try `%CXX%`, clang++ or g++ on `PATH`, the HIP SDK's clang++, then MSVC. Set `WG_K_RT_CXX=msvc` to try MSVC first. The other variables set their build folder and an existing converter. If the tests find no compiler, they skip and report why. | Temporary build folder; converter built from source | +| `WG_BUILD_ROOT` | Default output root for scripts that support one. | `\build`, ignored by git | +| `WG_DX12_JOBS`, `WG_RR_JOBS` | Parallel kernel compilation limits. | The CPU count, capped at 12, for DX12; 8 for Ray Reconstruction | +| `WG_GPU_LOCK` | Optional lock command run as `python --timeout -- ` around GPU jobs. | Unset; GPU jobs run directly | +| `WRONGGPU_HIP_RUNTIME` | HIP runtime loaded by the launcher's probe in test builds. Step 5.1 builds a stand-in for tests. | The system's HIP runtime | + +Set `ROCM_PATH` to the HIP SDK folder. The commands below also pass it through `--rocm`. Unless you set them +intentionally, remove `HIP_PATH`, `LLVM_PATH`, `HIP_DEVICE_LIB_PATH`, and `HIP_CLANG_PATH` from the build environment. +The scripts pass the HIP compiler folder explicitly. + +Open an **x64 Native Tools Command Prompt for VS 2026**, or call `vcvars64.bat`, at the repository root. Use that prompt +for every step. These commands write to `out\`. You can use a folder outside the repository instead. ## 3. Kernels and runtime @@ -57,32 +57,32 @@ set ROCM_PATH=C:\Program Files\AMD\ROCm\7.2 rem 3.1 Ray Reconstruction kernels (DXIL), its tables, wronggpu_rr_runtime.dll objects and the D3D12 test host python -m clean.rr_f.runtime.tools.build --out out\rr-rt -rem 3.2 the Direct3D 12 kernels of Model M, Model L and Model K (DXIL + out\runtime\dx12\manifest.json), with the RGA +rem 3.2 Direct3D 12 kernels for Model M, Model L and Model K (DXIL + out\runtime\dx12\manifest.json), with the RGA rem register check python clean\dx12\build_dx12.py --out out\runtime --model-l --model-k -rem 3.3 the HIP code objects (gfx1201 and gfx1200) and the one runtime library wronggpu_runtime.dll -rem (Model M, Model L, Model K and Ray Reconstruction linked in; Model K is in unless --no-model-k) +rem 3.3 HIP code objects (gfx1201 and gfx1200) and one runtime library, wronggpu_runtime.dll +rem (Model M, Model L, Model K and Ray Reconstruction linked in; Model K is included unless --no-model-k is used) python clean\runner\build.py --rocm "%ROCM_PATH%" --out out\runtime --extra-archs gfx1200 --model-l --with-rr out\rr-rt\obj ``` -3.2 takes the longest (two of its kernels take several minutes each in DXC). Lower `WG_DX12_JOBS` / `WG_RR_JOBS` on a -busy PC. +Step 3.2 takes the longest. DXC compiles two of its kernels for several minutes each. Lower `WG_DX12_JOBS` or +`WG_RR_JOBS` on a busy PC. ## 4. FSR front end, Ray Reconstruction plugin, shared settings, converter ```bat set CMAKE_FLAGS=-G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_POLICY_DEFAULT_CMP0091=NEW -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded -rem 4.1 FSR front end: amd_fidelityfx_dx12.dll (and WrongGPU.asi for OptiScaler before 0.10), with the Model L and -rem Model K entries (WG_MODEL_L defaults to OFF, WG_MODEL_K to ON: both are set here) -cmake -S clean\fsr -B out\frontend %CMAKE_FLAGS% -DWG_MODEL_K=ON -DWG_MODEL_L=ON -DWG_BUILD_ID=0.6.0 -DWG_BUILD_ASI=ON +rem 4.1 FSR front end: amd_fidelityfx_dx12.dll (and WrongGPU.asi for OptiScaler before 0.10), with Model L and +rem Model K entries (WG_MODEL_L defaults to OFF and WG_MODEL_K to ON; both are set explicitly here) +cmake -S clean\fsr -B out\frontend %CMAKE_FLAGS% -DWG_MODEL_K=ON -DWG_MODEL_L=ON -DWG_BUILD_ID=0.6.5 -DWG_BUILD_ASI=ON cmake --build out\frontend -rem 4.2 Ray Reconstruction plugin: out\rr-proxy\hook\WrongGPU-RR.asi (--no-tests: see 7 for its tests) +rem 4.2 Ray Reconstruction plugin: out\rr-proxy\hook\WrongGPU-RR.asi (--no-tests: see section 7 for its tests) python clean\rr_f\proxy\tools\build.py --out out\rr-proxy --no-tests -rem 4.3 shared settings and converter (both are also built as part of the launcher) +rem 4.3 Shared settings and converter (the launcher also builds both) cmake -S clean\wgshared -B out\wgshared %CMAKE_FLAGS% cmake --build out\wgshared cmake -S clean\converter -B out\converter %CMAKE_FLAGS% @@ -93,9 +93,9 @@ cmake --build out\converter ### 5.1 Payload folders -The launcher embeds two folders: +The launcher embeds files from two folders: -``` +```text out\payload\amd_fidelityfx_dx12.dll from out\frontend out\payload\plugins\WrongGPU.asi from out\frontend out\payload\wronggpu_runtime.dll from out\runtime @@ -106,6 +106,8 @@ out\rr\plugins\WrongGPU-RR.asi from out\rr-proxy\hook out\rr\interposer.json clean\rr_f\proxy\binding\interposer.json ``` +Create the folders and copy the files: + ```bat mkdir out\payload\plugins out\rr\plugins copy /y out\frontend\amd_fidelityfx_dx12.dll out\payload\ @@ -118,13 +120,13 @@ copy /y out\rr-proxy\hook\WrongGPU-RR.asi out\rr\plugins\ copy /y clean\rr_f\proxy\binding\interposer.json out\rr\ ``` -`wronggpu_runtime.build.json` is the build manifest that `clean\runner\build.py` writes next to the runtime library. -The payload packager (`clean\installer\tools\make_payload.py`) refuses a runtime library without it, or one whose -SHA-256 does not match it, so keep the two together and do not change the library after the build (no signing or -stripping). The manifest is read for that check and is not shipped. +`clean\runner\build.py` writes `wronggpu_runtime.build.json` next to the runtime library. The payload packager, +`clean\installer\tools\make_payload.py`, refuses a runtime without this manifest or with a SHA-256 that differs from +the manifest. Keep the library and manifest together. Do not change the library after building it, including signing +or stripping it. The packager reads the manifest for this check but does not ship it. -For tests, build the HIP runtime stand-in and point `WRONGGPU_HIP_RUNTIME` at it, so no test loads the real HIP -runtime: +For tests, build the HIP runtime stand-in and point `WRONGGPU_HIP_RUNTIME` at it. This prevents tests from loading the +real HIP runtime: ```bat mkdir out\mockhip && cl /nologo /LD /O2 clean\installer\tests\mock_hip.c /Fe:out\mockhip\amdhip64_7.dll /Fo:out\mockhip\ @@ -135,17 +137,20 @@ set WRONGGPU_HIP_RUNTIME=%CD%\out\mockhip\amdhip64_7.dll ```bat cmake -S clean\installer -B out\launcher %CMAKE_FLAGS% -DWRONGGPU_PAYLOAD_DIR=%CD%\out\payload -DWRONGGPU_RR_DIR=%CD%\out\rr ^ - -DWRONGGPU_VERSION=0.6.0 -DWRONGGPU_BUILD_ID=0.6.0 -DWRONGGPU_PAYLOAD_NAME=0.6.0 -DWRONGGPU_TESTING=OFF ^ + -DWRONGGPU_VERSION=0.6.5 -DWRONGGPU_BUILD_ID=0.6.5 -DWRONGGPU_PAYLOAD_NAME=0.6.5 -DWRONGGPU_TESTING=OFF ^ -DWRONGGPU_PRESET_K=ON -DWRONGGPU_MODEL_K=ON -DWRONGGPU_MODEL_L=ON -DWRONGGPU_DIRECT_ROUTE=OFF cmake --build out\launcher ``` -`out\launcher\WrongGPU.exe` is the launcher, with the per-game choices Model L and -Model K (`WRONGGPU_MODEL_L` and `WRONGGPU_MODEL_K` default to OFF, so the release sets them). The converter maps it embeds come from `data\` (`WRONGGPU_MAP`, -`WRONGGPU_MAP_F`, `WRONGGPU_MAP_K` override them). +The build creates `out\launcher\WrongGPU.exe` with the per-game Model L and Model K choices. +`WRONGGPU_MODEL_L` and `WRONGGPU_MODEL_K` default to `OFF`, so the release command enables them. The launcher's +converter maps come from `data\`. Override them with `WRONGGPU_MAP`, `WRONGGPU_MAP_F`, `WRONGGPU_MAP_K`, and +`WRONGGPU_MAP_L`. ## 6. Tests (CPU) +Run the C++ and Python CPU tests: + ```bat ctest --test-dir out\converter --output-on-failure ctest --test-dir out\wgshared --output-on-failure @@ -153,12 +158,12 @@ ctest --test-dir out\launcher --output-on-failure ctest --test-dir out\launcher\converter --output-on-failure ctest --test-dir out\frontend --output-on-failure -R "unit|hosted|diagnostic|support" -E "overlay|split|d3d12" -rem Python unit tests. Folders without a GPU module can be discovered whole: +rem Python unit tests. Discover folders without a GPU module as a whole: python -m unittest discover -s clean\tests -t . python -m unittest discover -s clean\rr_f\tests -t . python -m unittest discover -s clean\rr_f\head\tests -t . -rem Folders with GPU modules (clean\k\tests, clean\rr_f\runtime\tests): one module at a time, leaving out the GPU -rem modules listed below, e.g. +rem For folders with GPU modules (clean\k\tests and clean\rr_f\runtime\tests), run one module at a time and leave out +rem the GPU modules listed below. For example: python -m unittest clean.k.tests.test_k_reference clean.k.tests.test_k_runtime_tables clean.k.tests.test_k_runtime_pack python -m unittest clean.rr_f.runtime.tests.test_rr_retire rem Test folders without __init__.py (clean\dx12\tests, clean\fsr\tests, clean\rr_f\proxy\tests) run from their own @@ -170,77 +175,109 @@ python -m unittest discover -s clean\rr_f\proxy\tests -t clean\rr_f\proxy\tests python -m unittest discover -s clean\rr_f\proxy\tests -t clean\rr_f\proxy\tests -p test_gen_forwarding.py ``` -`clean\runtime\tests\test_wmma_probe.cpp` checks Model M's driver-channel probe (`clean\runtime\wmma_probe.h`) on -any host: build it with any C++17 compiler (`clang++ -std=c++17 test_wmma_probe.cpp`) and run it; exit status 0 when -it passes. `clean\dx12\tests\native_probe_test.cpp` runs the same probe on the GPU (see 7). +`clean\runtime\tests\test_wmma_probe.cpp` checks Model M's driver-channel probe in `clean\runtime\wmma_probe.h` on any +host. Build it with any C++17 compiler, such as `clang++ -std=c++17 test_wmma_probe.cpp`, and run it. A passing test +exits with status 0. `clean\dx12\tests\native_probe_test.cpp` runs the same probe on the GPU, as described in section +7. + +The wgshared ctest runs the scripts in `clean\wgshared\tests\*.py`. The Ray Reconstruction plugin build with +`--no-tests` still builds its CPU test executables. Run them as the build script does: -`clean\wgshared\tests\*.py` are scripts that the wgshared ctest runs. The Ray Reconstruction plugin's CPU tests are -executables that `clean\rr_f\proxy\tools\build.py --no-tests` builds; run them as that script does: -`out\rr-proxy\core\test_proxy_core.exe`, `test_probe_core.exe`, `test_setupapi_identity.exe`, -`test_ngx_rr.exe ` and `test_replay_profile.exe `. Its other test executables create a Direct3D 12 device (see 7). +- `out\rr-proxy\core\test_proxy_core.exe` +- `test_probe_core.exe` +- `test_setupapi_identity.exe` +- `test_ngx_rr.exe ` +- `test_replay_profile.exe ` -Some Python test modules need a GPU and must be left out of a CPU run: in `clean\k\tests` the modules -`test_k_hidden_guard`, `test_k_input_uniforms`, `test_k_interop_timing`, `test_k_norm_r16`, `test_k_output_arithmetic`, -`test_k_output_selector`, `test_k_runtime_gpu`, `test_k_tiled_input`; `clean\rr_f\proxy\tests\test_capture_replay`, -`clean\rr_f\runtime\tests\test_model_pack`, and `clean\tests\test_no_model_k` when `WG_NO_K_BUILD` is set (without it, -its library part skips itself and the rest runs on the CPU). Tests that need files outside the -repository (the synthetic converter library stand-ins `WGC_SYNTH_BINS`, a model file `WG_RR_MODEL`, a capture folder -`WG_RR_CAPTURE`) skip themselves when those are not given. +The plugin's other test executables create a Direct3D 12 device and belong to the GPU steps in section 7. + +Leave these GPU-only Python modules out of a CPU run: + +- In `clean\k\tests`: `test_k_hidden_guard`, `test_k_input_uniforms`, `test_k_interop_timing`, `test_k_norm_r16`, + `test_k_output_arithmetic`, `test_k_output_selector`, `test_k_runtime_gpu`, and `test_k_tiled_input`. +- In `clean\rr_f\proxy\tests`: `test_capture_replay`. +- In `clean\rr_f\runtime\tests`: `test_model_pack`. +- In `clean\tests`: `test_no_model_k` when `WG_NO_K_BUILD` is set. Without that variable, its library part skips itself + and the rest runs on the CPU. + +Tests that need files outside the repository skip themselves when those files are not provided. These files include +the synthetic converter library stand-ins in `WGC_SYNTH_BINS`, a model file in `WG_RR_MODEL`, and a capture folder in +`WG_RR_CAPTURE`. ### Comparing kernels with a release -The kernels are deterministic for a given DXC / HIP SDK version: `out\rr-rt\kernels.json` (name, arguments, SHA-256 of -each DXIL) and `out\runtime\dx12\manifest.json` (SHA-256 of each DXIL) can be compared with another build of the same -source: for `kernels.json`, compare each kernel's `nargs` and `sha256`. +Kernels are deterministic for a given DXC and HIP SDK version. Compare another build of the same source through +`out\rr-rt\kernels.json` and `out\runtime\dx12\manifest.json`. The first file contains each DXIL kernel's name, +arguments, and SHA-256. Compare each kernel's `nargs` and `sha256`. The second file contains each DXIL kernel's +SHA-256. -The code objects `out\runtime\*.co` and `out\runtime\gfx1200\*.co` of builds made with `-cuid` (the compilation-unit -id that `clean\runner\build.py` now fixes) can be compared file by file. In a check of two build folders, all 54 -compiled code objects (gfx1201 and gfx1200) were byte-identical. +Builds made with `-cuid`, which `clean\runner\build.py` now fixes as the compilation-unit ID, produce code objects that +can be compared file by file. Compare `out\runtime\*.co` and `out\runtime\gfx1200\*.co`. In one check of two build +folders, all 54 compiled code objects across gfx1201 and gfx1200 were byte-identical. -Release 0.6.0 was built without `-cuid`, so none of its code objects is byte-identical to a new build: the -`__hip_cuid_...` symbol differs. Compare the `.text` and `.note` sections instead (extract them with an ELF tool, for -example `llvm-objcopy --dump-section`); they were identical in all 54, as was the section list. The `.rodata` section -was identical in 52. In `post_w64__orig.co` (both targets) it moves by 64 bytes, and its 93 kernel descriptors differ -only in their code-entry offset, by that amount; so do not use `.rodata` as the comparison for 0.6.0. +Release 0.6.0 was built without `-cuid`, so none of its code objects is byte-identical to a new build. The +`__hip_cuid_...` symbol differs. Extract and compare the `.text` and `.note` sections instead, using an ELF tool such +as `llvm-objcopy --dump-section`. In the comparison, those sections and the section list were identical in all 54 code +objects. The `.rodata` section was identical in 52. In `post_w64__orig.co` for both targets, `.rodata` moves by 64 +bytes, and its 93 kernel descriptors differ only in their code-entry offset by that amount. Do not use `.rodata` to +compare a new build with 0.6.0. ## 7. GPU steps (optional; not needed to build) -These load a Direct3D 12 or HIP device: the front end's D3D12 tests (`ctest --test-dir out\frontend -E -"unit|hosted|diagnostic|support"`), the Ray Reconstruction plugin's full test run (`clean\rr_f\proxy\tools\build.py` -without `--no-tests`), `clean\runtime\interop\tests` (the D3D12 interop harness), `clean\dx12\tests`, the Ray -Reconstruction end-to-end test (`clean\rr_f\runtime\tests\e2e.py`), the timing tools, and the GPU test modules listed -in 6. Run them on an RX 9000-series card; `WG_GPU_LOCK` can serialise them when several shells share one GPU. +The following steps load a Direct3D 12 or HIP device: + +- The front end's D3D12 tests: `ctest --test-dir out\frontend -E "unit|hosted|diagnostic|support"`. +- The Ray Reconstruction plugin's full test run: `clean\rr_f\proxy\tools\build.py` without `--no-tests`. +- The D3D12 interop tests in `clean\runtime\interop\tests`. +- The tests in `clean\dx12\tests`. +- The Ray Reconstruction end-to-end test, `clean\rr_f\runtime\tests\e2e.py`. +- The timing tools and the GPU test modules listed in section 6. + +Run them on an RX 9000-series card. `WG_GPU_LOCK` can serialise GPU jobs when several shells share one GPU. ## 8. Model L and Model K in the build -Since 0.6.5, the builds that players get include Model L and Model K next to Model M: Model M stays the default for -every game, and Model L and Model K are choices per game (`set model=L` / `model=K`, or the WrongGPU Model L / K -entry in OptiScaler's menu). The release commands above build all three parts with them: 3.2 `--model-l --model-k`, -3.3 `--model-l` (Model K is in the runtime unless `--no-model-k`), 4.1 `-DWG_MODEL_K=ON -DWG_MODEL_L=ON`, 5.2 -`-DWRONGGPU_PRESET_K=ON -DWRONGGPU_MODEL_K=ON -DWRONGGPU_MODEL_L=ON`. The three parts must agree: a launcher with a -choice its front end or runtime lacks offers a model that cannot run. +Player builds since 0.6.5 include Model L and Model K alongside Model M. Model M remains the default for every game. +Choose Model L or Model K per game with `set model=L` or `model=K`, or through the **WrongGPU Model L** or +**WrongGPU Model K** entry in OptiScaler's menu. + +The release commands above enable the models in all three components: + +- Step 3.2 uses `--model-l --model-k`. +- Step 3.3 uses `--model-l`. Model K is included unless `--no-model-k` is used. +- Step 4.1 uses `-DWG_MODEL_K=ON -DWG_MODEL_L=ON`. +- Step 5.2 uses `-DWRONGGPU_PRESET_K=ON -DWRONGGPU_MODEL_K=ON -DWRONGGPU_MODEL_L=ON`. + +The launcher, front end, and runtime must support the same models. A launcher choice that the front end or runtime +lacks offers a model that cannot run. -A Model M-only build (for comparisons; not a release) changes those lines to: +For a Model M-only comparison build, not a release, replace those commands with: ```bat -rem 3.2 / 3.3: no Model L or Model K kernels or code objects +rem 3.2 and 3.3: no Model L or Model K kernels or code objects python clean\dx12\build_dx12.py --out out\runtime python clean\runner\build.py --rocm "%ROCM_PATH%" --out out\runtime --extra-archs gfx1200 --no-model-k --with-rr out\rr-rt\obj -rem 4.1 front end: no Model L or Model K entry +rem 4.1 Front end: no Model L or Model K entry cmake -S clean\fsr -B out\frontend %CMAKE_FLAGS% -DWG_MODEL_K=OFF -DWG_MODEL_L=OFF -DWG_BUILD_ID=dev-m -DWG_BUILD_ASI=ON -rem 5.2 launcher: Model M only +rem 5.2 Launcher: Model M only cmake -S clean\installer -B out\launcher %CMAKE_FLAGS% -DWRONGGPU_PAYLOAD_DIR=%CD%\out\payload -DWRONGGPU_RR_DIR=%CD%\out\rr ^ - -DWRONGGPU_VERSION=0.6.0 -DWRONGGPU_BUILD_ID=dev-m -DWRONGGPU_PAYLOAD_NAME=0.6.0 -DWRONGGPU_TESTING=OFF ^ + -DWRONGGPU_VERSION=0.6.5 -DWRONGGPU_BUILD_ID=dev-m -DWRONGGPU_PAYLOAD_NAME=0.6.5 -DWRONGGPU_TESTING=OFF ^ -DWRONGGPU_PRESET_K=OFF -DWRONGGPU_DIRECT_ROUTE=OFF ``` -`-DWRONGGPU_MODEL_K=ON` needs `-DWRONGGPU_PRESET_K=ON` (configuring without it stops with an error) and the front end and -runtime of the same build. Model K runs its exact network: nothing in these builds, the launcher or the front end offers or -sets another mode of it. CI's CPU test jobs configure the launcher and front end with Model K off; the front end's build -also tests the other state of Model K (`fsr_frontend_model_k_unit` in a build with `-DWG_MODEL_K=OFF`, -`fsr_frontend_no_model_k_unit` in one with it ON), and the launcher's `model-choice-k` and `model-choice-k-only` tests run the K choice whatever the build's option is. -`clean\installer\tests\run_model_k_tests.py` (its header says how to prepare the payload, the test maps and a launcher with -the choices on) runs the choice end to end on generated fixtures, with no game and no GPU. +`-DWRONGGPU_MODEL_K=ON` requires `-DWRONGGPU_PRESET_K=ON`. Configuration stops with an error without it. Use a front +end and runtime from the same build. + +Model K runs its exact network by default. The launcher and front end do not offer or set another mode. The optional +`k_approx` runtime setting is documented in the +[0.6.5 release notes](clean/installer/RELEASE-NOTES.md#model-k-new). + +CI's CPU test jobs configure the launcher and front end with Model K off. The front end also tests both states through +`fsr_frontend_model_k_unit` in a build with `-DWG_MODEL_K=OFF` and `fsr_frontend_no_model_k_unit` in a build with it +on. The launcher's `model-choice-k` and `model-choice-k-only` tests exercise the K choice regardless of the build +option. + +`clean\installer\tests\run_model_k_tests.py` runs the choice end to end on generated fixtures without a game or GPU. +Its header explains how to prepare the payload, test maps, and a launcher with the choices enabled. diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index ccca03a6..de4ddfa8 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -1,92 +1,127 @@ # Game compatibility -These notes apply to **WrongGPU 0.6.5**: Model M (the default), Model L and Model K (both off by default) and Ray -Reconstruction through the **WrongGPU edition of OptiScaler**, set up by the WrongGPU launcher. Each result is as last -tested: Cyberpunk 2077 was re-tested with 0.6.5, and the other rows keep the version they were tested with. "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). +These results apply to **WrongGPU 0.6.5**, set up by the WrongGPU launcher. Model M is the default. Model L and Model K +are off by default. Games use the **WrongGPU edition of OptiScaler** unless a game-specific note says otherwise. + +Model M means super resolution only. Ray Reconstruction means that WrongGPU's own Ray Reconstruction ran in the game. +Each result keeps the WrongGPU version that was tested. Cyberpunk 2077 was re-tested with 0.6.5. See +[How to add your game](#how-to-add-your-game) to report another result. ## Tested games -Tested on a Radeon RX 9070 XT, with WrongGPU 0.6.0 unless a row says otherwise. +Tests used a Radeon RX 9070 XT and WrongGPU 0.6.0 unless a row says otherwise. | Game | Model M | Ray Reconstruction | Notes | | --- | --- | --- | --- | -| **Cyberpunk 2077** | Yes | Yes | Our main test game. Re-tested with 0.6.5 at 1080p: Model M at Quality and DLAA, Model L and Model K at Quality, and Ray Reconstruction with path tracing, with 0 failures logged. | -| **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. | +| **Cyberpunk 2077** | Yes | Yes | The main test game. See the [0.6.5 retest](#cyberpunk-2077-retest). | +| **Borderlands 4** | Yes, tested with 0.4.5 | Yes | Requires one `Engine.ini` setting. See the [setup and timing notes](#borderlands-4-notes). | +| **RESIDENT EVIL requiem** | Yes | Yes, experimental | Requires your own REFramework. See the [game notes](#resident-evil-requiem-notes). | +| **Hogwarts Legacy** | Yes | Not available | The game's November 2026 update greyed out its Ray Reconstruction option. WrongGPU's Ray Reconstruction is unavailable, and the launcher does not offer it. Ray Reconstruction worked before that update. | +| **Marvel's Spider-Man 2** | Yes. Choose **FSR** because the game's menu does not offer DLSS. | Experimental opt-in, not recommended | Ray Reconstruction often freezes the GPU or crashes. The [release notes](clean/installer/RELEASE-NOTES.md#experimental-ray-reconstruction-in-spider-man-2) explain the opt-in. | | **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 or 0.6.5. | +| **The Witcher 3 Remastered** | Earlier version, 0.4.5 | — | Not retested with 0.6.0 or 0.6.5. | | **Control** | Earlier versions | — | Not retested with 0.6.0 or 0.6.5. This result does not cover Control Resonant. | | **Crimson Desert** | Earlier versions | — | Not retested with 0.6.0 or 0.6.5. | | **Ratchet & Clank: Rift Apart** | Earlier versions | — | Not retested with 0.6.0 or 0.6.5. | | **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). | +| **Other games** | Experimental and unverified | Experimental and unverified | OptiScaler support and the launcher accepting a game do not establish WrongGPU compatibility. [Send a report](https://github.com/phantoslayer21/wronggpu/issues/new?template=game-compatibility-report.yml). | + +### Cyberpunk 2077 retest + +WrongGPU 0.6.5 was tested at 1080p with Model M at Quality and DLAA, Model L and Model K at Quality, and Ray +Reconstruction with path tracing. The test logged 0 failures. + +### Borderlands 4 notes + +Ray Reconstruction needs one `Engine.ini` setting, which the game removes on every start. After installation, the +launcher offers two choices. **Fix it for me** adds the setting and makes the file read-only. Uninstalling WrongGPU +undoes both changes. **Show me how** provides the manual steps. + +The game creates Ray Reconstruction itself, so it needs the WrongGPU edition of OptiScaler. + +### RESIDENT EVIL requiem notes + +Install **REFramework** yourself before installing WrongGPU. The game blocks OptiScaler without it. WrongGPU never +installs, downloads, or replaces REFramework, and the launcher reports when it is missing. + +To use Ray Reconstruction, set the game's **Ray Tracing** setting to **Path Tracing** and its upscaler to **DLSS**. The +game prepares Ray Reconstruction at its first start, not in the launcher. + +A single frame can very occasionally become far too bright or too dark at a scene change. See +[Known limits](#known-limits). + +## Test coverage and the Borderlands 4 timing 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. +Results from earlier WrongGPU versions are labelled as such. The Borderlands 4 figure is the GPU time per frame that +WrongGPU's Ray Reconstruction runtime logged for its instance 1 (the `runtime: instance 1 timing` lines of +`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 in the logged timing windows, render 642x361, output 1920x1080. The instance was destroyed after 36044 +frames with 0 failed. The last line of that log, "RR instances created 0, RR evaluates 0", counts only the +game-interface route. Borderlands 4 creates Ray Reconstruction itself through the direct route, so those zeros are +expected and do not mean that Ray Reconstruction did not run. 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 Model L 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 +- Use a **DirectX 12 game supported by OptiScaler**. Its upscaler inputs must provide the color, depth, and motion + information that WrongGPU needs. Choose **DLSS** as the game's upscaler. +- Use a **Radeon RX 9070 or RX 9070 XT** and a recent AMD Adrenalin driver. The RX 9060 XT and RX 9060 are supported + but not yet tested. Older Radeon cards are unsupported in this release. +- No AMD HIP runtime is needed for upscaling or Ray Reconstruction. The optional sparkle guard and frame capture use + it. +- Keep a local DLSS super-resolution file of version **310.5 or newer** for Model M and Model L. Model K is converted from + a DLSS file from one of your games. Ray Reconstruction needs a **DLSS Ray Reconstruction file of version 310.7 or + newer**. Each file can come from any game or app on your PC, not necessarily the game you play. The launcher looks + for these files 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, such as Unreal Engine games with their own plugin, need the WrongGPU edition of OptiScaler. -- **No anti-cheat.** Do not bypass a launcher refusal. +- **Do not test a game with anti-cheat.** Do not bypass a launcher refusal. -Older Radeon cards, DirectX 11 and Vulkan are unsupported in this release. +DirectX 11 and Vulkan are unsupported in this release. ## Known limits -- A rare crash at game start can happen; restarting the game fixes it. -- 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. -- Model L and Model K (new in 0.6.5, off by default) are still under test. Model L is tested for super resolution in - Cyberpunk 2077 and RESIDENT EVIL requiem, Model K in Cyberpunk 2077 (see the release notes). -- Radeon RX 9060 XT / RX 9060: supported, not yet tested. +- A rare crash can happen at game start. Restarting the game fixes it. +- Ray Reconstruction can show visual artifacts, such as ghosting on thin lines in reflections or blotches in + Cyberpunk 2077 with path tracing. +- In RESIDENT EVIL requiem, a single frame can very occasionally become far too bright or too dark at a scene change, + after loading a save, or during flashes of lightning. It lasts one frame. +- Model L and Model K were added in 0.6.5, are off by default, and are still under test. Model L is tested for super + resolution in Cyberpunk 2077 and RESIDENT EVIL requiem. Model K is tested in Cyberpunk 2077. See the + [release notes](clean/installer/RELEASE-NOTES.md#known-issues). +- The Radeon RX 9060 XT and RX 9060 are supported but 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. +- After an AMD driver update or a WrongGPU update, the launcher prepares Ray Reconstruction again in the background. A + game started before that finishes prepares it at its first start. +- WrongGPU passes through frames that the network cannot use or sends them to AMD FSR, then continues with the next + normal frame. Examples include a render size larger than the output and textures that are too small during an intro. ## 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, Model L or Model K (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 +1. Follow [Testing WrongGPU in other games](docs/TESTING-OTHER-GAMES.md). Use a game without anti-cheat and complete + at least one longer play session. Confirm that the FPS overlay or the game page's **Last run** shows WrongGPU's + Model M, Model L, Model K, or Ray Reconstruction running. Record your settings. +2. Submit the [game compatibility form](https://github.com/phantoslayer21/wronggpu/issues/new?template=game-compatibility-report.yml) + or post in #bug-reports on the [WrongGPU Discord server](https://discord.gg/745z9MfKwm). Include the zip from + **Collect logs**. +3. Optionally open a pull request that adds a row to the table. Include the game, the Model M and Ray Reconstruction + results, the GPU, the driver, the WrongGPU version, and a link to your report. Include the source log line for every + timing, together with the game, resolution, mode, and WrongGPU version. One report marks a game as "reported". A maintainer moves it to "tested" after checking it. -## Testing and reports +## Check what ran before reporting + +AMD FSR frames and passed-through frames are not Model M, Model L, Model K, or Ray Reconstruction results. Check the +FPS overlay for **DLSS → WrongGPU Model M**, **WrongGPU Model L**, **WrongGPU Model K**, or **DLSS → WrongGPU RR**. +Also check the game page's **Last run**. -Follow [Testing WrongGPU in other games](docs/TESTING-OTHER-GAMES.md). AMD FSR frames and passed-through frames are not -Model M, Model L, Model K or Ray Reconstruction results: check the FPS overlay ("DLSS → WrongGPU Model M", the upscaler -**WrongGPU Model L** or **WrongGPU Model K** when you chose one of those, or "DLSS → WrongGPU RR") and the game page's -**Last run**. +Identify the game build, GPU, driver, WrongGPU version, output resolution, input upscaler, and quality mode. State +whether Ray Reconstruction was on and include its mode. Attach the support zip from **Collect logs** on the game's +page in the launcher. Include reproduction steps, visual problems, and matched performance comparisons. -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. +Community reports help establish compatibility, but no fixed report count automatically makes a game validated. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 58ff431e..399d0947 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,30 +1,31 @@ # Contributing to WrongGPU -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). +WrongGPU is a community project and a clean-room implementation. Every contribution must follow the rules in +[docs/CLEAN-ROOM.md](docs/CLEAN-ROOM.md). Read this page before opening a pull request. + +Start with the [welcome discussion](https://github.com/phantoslayer21/wronggpu/discussions/1). You can propose a change +from [ROADMAP.md](ROADMAP.md), report a game through [COMPATIBILITY.md](COMPATIBILITY.md), or help with +[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)). +1. Open a pull request against `main`. Include the clean-room statement in your first pull request and sign off every + commit. The pull-request template has checkboxes for both. +2. Wait for CI on the Windows runner defined in `.github/workflows/ci.yml`. It must pass these checks: + - [REUSE](https://reuse.software) lint validates the licence and copyright data in `REUSE.toml` and checks that it covers every file. + - The line-ending check preserves files exactly as committed. `.gitattributes` sets `* -text` and forbids CR LF. + - CPU builds and tests cover the converter, shared settings, FSR front end, launcher core, and Ray Reconstruction + plugin. CI also runs the CPU Python tests through `tools/ci/run_python_tests.py`. + + CI has no GPU. It does not build kernels or the runtime library, and it runs no GPU tests. +3. Wait for the maintainer's manual checks: + - Before every merge, the maintainer privately scans the pull request for material that must not appear in a clean + implementation and checks the clean-room statement. + - Someone who did not write the change reviews it. + - A change to kernels, the runtime, the front end, or the Ray Reconstruction plugin needs a test on a Radeon RX + 9000-series card. +4. The project owner merges the pull request. Only the owner builds, tests on real hardware, and publishes official + releases. See [RELEASING.md](RELEASING.md). ## The clean-room statement @@ -44,49 +45,53 @@ own PC are still very welcome. ## Sign-off (Developer Certificate of Origin) -Every commit carries a sign-off line, which certifies the [Developer Certificate of Origin 1.1](https://developercertificate.org/): +Sign off every commit to certify the [Developer Certificate of Origin 1.1](https://developercertificate.org/): -``` +```text Signed-off-by: Your Name ``` -`git commit -s` adds it. Pull requests with commits that are not signed off are not merged. +Use `git commit -s` to add the line. Pull requests with commits that are not signed off are not merged. ## What you may use -- Public documentation: AMD's RDNA 4 ISA and WMMA documentation, HIP / ROCm documentation and headers, LLVM AMDGPU - documentation, Microsoft's Direct3D 12 / DXIL / Win32 documentation, AMD's public FidelityFX API, papers and +- Public documentation: AMD's RDNA 4 ISA and WMMA documentation, HIP and ROCm documentation and headers, LLVM AMDGPU + documentation, Microsoft's Direct3D 12, DXIL, and Win32 documentation, AMD's public FidelityFX API, papers, and general literature. - Your own measurements on your own hardware with synthetic data. -- Third-party code only under one of these licences: MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0, zlib, ISC, Boost - (BSL-1.0). Nothing under GPL, LGPL, AGPL or a licence without the right to redistribute in source and binary form; - 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. - -## Every change - -- 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 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 and game reports - -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). +- Third-party code under MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0, zlib, ISC, or Boost (BSL-1.0). Do not use code + under GPL, LGPL, AGPL, or a licence that does not allow source and binary redistribution. Do not use code whose + licence forbids reverse engineering. Get a maintainer's approval before adding code that ends up in a shipped + binary. List every new component in [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES) and `REUSE.toml`. + +Never add files from the original upscaler, including DLLs, headers, and model data. Never add model weights, data +derived from them, game files, game screenshots, game frame captures, or binaries. + +## What every change needs + +- Add an MIT SPDX licence line to every new source file. Use `SPDX-License-Identifier` followed by `MIT`, as in the + existing source files. Cover files that cannot carry a header, such as JSON, in `REUSE.toml`. The `**` rule in + `REUSE.toml` already covers every file, so REUSE lint passes without a header. Reviewers catch a missing header + instead. +- In the pull request, identify the basis of each new or substantially changed file. Name the public document, test + result, or your own design. +- Add tests with synthetic data for the changed behavior. Run the CPU tests locally with + [BUILDING.md](BUILDING.md#6-tests-cpu). CI runs the same tests. +- Keep absolute local paths, user names, and machine names out of code, scripts, and documents. Use the environment + variables in [BUILDING.md](BUILDING.md#2-where-the-build-finds-the-tools) to find tools. +- If a kernel change should keep the output bit-identical, say so and show the comparison described in + [BUILDING.md](BUILDING.md#comparing-kernels-with-a-release). +- Attach every timing or quality figure in a document to its measurement record. Include the game, resolution, mode, + build, and log or result file. Do not publish a number without its record. + +## Report bugs and game results + +Use the **Bug report** issue template for problems and the **Game compatibility report** template for game behavior. +They add the `bug` and `game-compatibility` labels respectively. See +[How to add your game](COMPATIBILITY.md#how-to-add-your-game) for the game-testing process. + +For a visual problem, include the game, scene, settings, GPU, driver, and the zip from the launcher's **Collect logs**. +Check the zip before sharing it because it can contain your Windows user name. Do not attach the upscaler's DLLs or +other copyrighted game files. + +Use the [WrongGPU Discord server](https://discord.gg/745z9MfKwm) for questions and discussion. diff --git a/README.md b/README.md index c3485b12..de7c029c 100644 --- a/README.md +++ b/README.md @@ -4,46 +4,44 @@ WrongGPU runs its own implementation of the neural networks behind DLSS super resolution (Model M) and DLSS Ray Reconstruction on Radeon RX 9000-series cards. The networks' weights come from your own DLSS files; the arithmetic is -WrongGPU's, so the output is close to DLSS's but not the same. Its launcher sets up each of your games and gets -the WrongGPU edition of OptiScaler for them. From -this source onward, WrongGPU's source code and its official builds are under the MIT licence (see [Licence](#licence)). +WrongGPU's, so the output is close to DLSS's but not the same. Its launcher sets up each of your games and gets the +WrongGPU edition of OptiScaler for them. -**Download:** the [Releases page](https://github.com/phantoslayer21/wronggpu/releases) (latest: [0.6.5](https://github.com/phantoslayer21/wronggpu/releases/tag/v0.6.5), a pre-release). +**Download:** the [Releases page](https://github.com/phantoslayer21/wronggpu/releases) (latest: +[0.6.5](https://github.com/phantoslayer21/wronggpu/releases/tag/v0.6.5), a pre-release). **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 - Windows 10 or 11 and a recent AMD Adrenalin driver. - A Radeon RX 9070 or RX 9070 XT. The RX 9060 / RX 9060 XT is supported but not yet tested; older Radeon cards are not - supported. No AMD HIP runtime is needed (only the optional sparkle guard uses it). + supported. No AMD HIP runtime is needed for upscaling or Ray Reconstruction; the optional sparkle guard and frame + capture use it. - A DirectX 12 game; games with anti-cheat are never supported. -- An internet connection the first time (the launcher downloads the WrongGPU edition of OptiScaler). +- An internet connection the first time, so the launcher can download the WrongGPU edition of OptiScaler. - DLSS files already on your PC, from any game or app: a DLSS super resolution file of version 310.5 or newer for - Model M, and a DLSS Ray Reconstruction file of version 310.7 or newer for Ray Reconstruction. WrongGPU converts them - on your PC; the download contains no files or model data of that vendor, and the converted model files are yours - alone (please don't share them). + Model M and Model L, and a DLSS Ray Reconstruction file of version 310.7 or newer for Ray Reconstruction. Model K is + also converted from a DLSS file from one of your games. WrongGPU converts them on your PC; the download contains no + files or model data of that vendor, and the converted model files are yours alone (please don't share them). ### Install in three steps -1. Download `WrongGPU-.zip` from the Releases page, extract it and run `WrongGPU-.exe` (it is not +1. Download `WrongGPU-.zip` from the Releases page, extract it and run `WrongGPU-.exe`. It is not code-signed: if Windows SmartScreen warns, choose **More info → Run anyway** after checking the file name and the - published SHA-256). + published SHA-256. 2. Pick **Install for this user** or **Run portable**, open a game in the Library and click **Install**. -3. In the game, choose DLSS as the upscaler (with DLSS Ray Reconstruction where the game offers it). The game's page in - the launcher shows what ran under **Last run**; **More → Uninstall WrongGPU** puts the game's own files back exactly. +3. In the game, choose DLSS as the upscaler, with DLSS Ray Reconstruction where the game offers it. The game's page in + the launcher shows what ran under **Last run**. **More → Uninstall WrongGPU** puts the game's own files back exactly. + +Borderlands 4 needs one Engine.ini setting for Ray Reconstruction; the launcher offers to add it. RESIDENT EVIL requiem +needs REFramework, which you install yourself. -Borderlands 4 needs one Engine.ini setting for Ray Reconstruction (the launcher offers to add it); RESIDENT EVIL -requiem needs REFramework, which you install yourself. +### Tested games -### Games (tested on an RX 9070 XT; results as tested in 0.6.0 unless a row says otherwise) +Tested on an RX 9070 XT, with results from 0.6.0 unless a row says otherwise. | Game | Model M | Ray Reconstruction | |---|---|---| @@ -58,37 +56,43 @@ requiem needs REFramework, which you install yourself. 0.6.5 was re-tested in Cyberpunk 2077 at 1080p: Model M at Quality and at DLAA, Model L and Model K at Quality, and Ray Reconstruction with path tracing, with 0 failures logged. -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.5: A rare crash at game start can happen; restarting the game -fixes it. In some games or scenes you may still see visual bugs, such as artifacts or flicker; with Ray Reconstruction -these include ghosting on thin lines in reflections and blotches in Cyberpunk 2077 with path tracing. In RESIDENT EVIL -requiem a single frame very occasionally comes out far too bright or too dark at a scene change. Full details: the -release notes ([clean/installer/RELEASE-NOTES.md](clean/installer/RELEASE-NOTES.md)). - -### Model L and Model K (new in 0.6.5, off by default) - -Model L and Model K are two more super-resolution models you can choose per game; Model M stays the default. Each is -converted once on your PC from a DLSS model file of one of your games (`WrongGPU.exe model convert --preset=L` or -`--preset=K`) and chosen per game with `WrongGPU.exe set "" model=L` (or `model=K`), or in -OptiScaler's menu. Both are still under test. Cyberpunk 2077 at 1080p Quality on an RX 9070 XT, standing still at the -same spot, measured one right after the other: the model's GPU time per frame (all of its kernels) is 1.03 ms with -Model K and 1.17 ms with Model M -([clean/k/records/cp2077-model-k-timing-2026-11-15.json](clean/k/records/cp2077-model-k-timing-2026-11-15.json)), -and 2.67 ms with Model L, measured the same way in a later sitting with Model M again at 1.17 ms -([clean/l/records/cp2077-model-l-timing-2026-11-16.json](clean/l/records/cp2077-model-l-timing-2026-11-16.json)). - -Faster kernels in 0.6.5, same output: Model L's Swin stage takes 7.0 µs less per frame and its decoder stage 2.5 µs -less at 1440p Quality, and 2.5 µs and 1.0 µs less at 1080p Quality; Model M's final (post) stage takes 2.5 µs less at -1440p Quality and 1.5 µs less at 1080p Quality. The output does not change. Measured on an RX 9070 XT in our offline -benchmark, which runs frames back to back (five rounds, the median difference per stage); in a game the saving per -frame can differ. - -### Something broken? - -On the game's page in the launcher, click **Collect logs**. It makes a zip on your PC and uploads nothing; check it -before you share it (it can contain your Windows user name and local paths). Post it in #bug-reports on the -[Discord server](https://discord.gg/745z9MfKwm) or attach it to a [GitHub issue](https://github.com/phantoslayer21/wronggpu/issues), -with the game, the scene and your settings. +Other games are experimental. See [COMPATIBILITY.md](COMPATIBILITY.md) for the full list, each game's requirements and +how to add your game. + +### Model L and Model K + +Model L and Model K are two more super-resolution models, new in 0.6.5, off by default and still under test. Model M +stays the default. Each is converted once on your PC from a DLSS model file of one of your games: + +```bat +WrongGPU.exe model convert --preset=L +WrongGPU.exe model convert --preset=K +``` + +Choose one per game with `WrongGPU.exe set "" model=L` (or `model=K`), or in OptiScaler's menu. + +In Cyberpunk 2077 at 1080p Quality on an RX 9070 XT, standing still at the same spot and measured one right after the +other, the model's GPU time per frame (all of its kernels) was 1.03 ms with Model K and 1.17 ms with Model M +([measurement](clean/k/records/cp2077-model-k-timing-2026-11-15.json)). Model L took 2.67 ms, measured the same way in +a later sitting with Model M again at 1.17 ms +([measurement](clean/l/records/cp2077-model-l-timing-2026-11-16.json)). + +Faster kernels in 0.6.5 produce the same output. Model L's Swin stage takes 7.0 µs less per frame and its decoder stage +2.5 µs less at 1440p Quality, and 2.5 µs and 1.0 µs less at 1080p Quality. Model M's final (post) stage takes 2.5 µs +less at 1440p Quality and 1.5 µs less at 1080p Quality. These are median differences per stage over five rounds of an +offline benchmark running frames back to back on an RX 9070 XT; in a game the saving per frame can differ. + +### Known issues and troubleshooting + +- A rare crash at game start can happen; restarting the game fixes it. +- Some games or scenes can still show visual bugs, such as artifacts or flicker. With Ray Reconstruction these include + ghosting on thin lines in reflections and blotches in Cyberpunk 2077 with path tracing. +- In RESIDENT EVIL requiem, a single frame very occasionally comes out far too bright or too dark at a scene change. + +Full details are in the [0.6.5 release notes](clean/installer/RELEASE-NOTES.md). For help, click **Collect logs** on the +game's page in the launcher. It makes a zip on your PC and uploads nothing. Check the zip before sharing it: it can +contain your Windows user name and local paths. Post it in #bug-reports on [Discord](https://discord.gg/745z9MfKwm) or +attach it to a [GitHub issue](https://github.com/phantoslayer21/wronggpu/issues), with the game, scene and your settings. WrongGPU is free. If you want to support development, there is an optional tip jar on [Ko-fi](https://ko-fi.com/wronggpu); it is never required. @@ -96,46 +100,33 @@ WrongGPU is free. If you want to support development, there is an optional tip j ## For developers WrongGPU is an independent, clean-room implementation: the clean team that wrote its code never saw DLSS source code, -disassembly or another port's kernels (see [docs/CLEAN-ROOM.md](docs/CLEAN-ROOM.md), which also says who made what: the -converter maps and test vectors in `data/` come from the separate spec team, and a few launcher / front-end helpers were -adapted from WrongGPU 0.2.0 code). No NVIDIA DLSS file is included in this repository or in WrongGPU's packages. The network's weights come from the player's own DLSS file -(`nvngx_dlss.dll` / `nvngx_dlssd.dll`, for DLSS super resolution and DLSS Ray Reconstruction): WrongGPU's converter -reads it on the player's PC and writes WrongGPU's own model file there. Nothing from that file is ever redistributed. - -This repository is the source of WrongGPU: it was first published as one snapshot of 0.6.0, and it now carries the -source of 0.6.5 (tag `v0.6.5`). The documents under `clean/` are the -implementation's own design and format notes (per-file provenance records are kept privately by the maintainer). They refer to the clean-room specification ("spec 02", -"page 51", ...), to the clean team's questions (`QUESTIONS.md`, `ANSWERS.md`) and to internal results notes -(`results/...`); those are not part of this repository. +disassembly or another port's kernels. [docs/CLEAN-ROOM.md](docs/CLEAN-ROOM.md) describes the process and who made what: +the converter maps and test vectors in `data/` come from the separate spec team, and a few launcher / front-end helpers +were adapted from WrongGPU 0.2.0 code. No NVIDIA DLSS file is included in this repository or in WrongGPU's packages. The +network's weights come from the player's own DLSS file (`nvngx_dlss.dll` / `nvngx_dlssd.dll`, for DLSS super resolution +and DLSS Ray Reconstruction): WrongGPU's converter reads it on the player's PC and writes WrongGPU's own model file +there. Nothing from that file is ever redistributed. + +This repository was first published as one snapshot of 0.6.0 and now carries the source of 0.6.5 (tag `v0.6.5`). The +documents under `clean/` are the implementation's design and format notes. They refer to the clean-room specification, +internal questions and answers, and internal results notes that are not part of this repository. Per-file provenance +records are kept privately by the maintainer. ### How it works -``` - player's DLSS file ──> converter (clean/converter) ──> model.wgcm (on the player's PC, never shipped) - │ - game ──> OptiScaler / FSR interface ──> FSR front end (clean/fsr) ──> runtime (clean/runtime, clean/rr_f/runtime) - │ - Direct3D 12 kernels (clean/dx12, clean/rr_f/kernels) or HIP kernels (clean/kernels) +```text +player's DLSS file ──> converter (clean/converter) ──> model.wgcm (on the player's PC, never shipped) + │ +game ──> OptiScaler / FSR interface ──> FSR front end (clean/fsr) ──> runtime (clean/runtime, clean/rr_f/runtime) + │ + Direct3D 12 kernels (clean/dx12, clean/rr_f/kernels) or HIP kernels (clean/kernels) ``` -- **Converter** (`clean/converter`): finds the network's tensors in the player's file using a map - (`data/preset-M.v1.map.json`, `data/preset-F.v1.map.json`: offsets, strides and digests, no weights) and writes - them as WrongGPU's model file. -- **Runtime** (`clean/runtime`, Ray Reconstruction in `clean/rr_f`): runs the network once per frame on the game's - Direct3D 12 device: input encoder, Swin transformer blocks, coefficient decoder, output reconstruction and filter, - auto-exposure; for Ray Reconstruction its window blocks, head, output stage and resolve. -- **Kernels**: Direct3D 12 compute shaders (`clean/dx12/kernels`, `clean/rr_f/kernels`, compiled with DXC) and HIP - kernels for gfx1201 / gfx1200 (`clean/kernels`, compiled with the AMD HIP SDK). -- **FSR front end** (`clean/fsr`): a FidelityFX API provider (`amd_fidelityfx_dx12.dll`) that OptiScaler or the game - calls as its upscaler; it hands each frame to the runtime, or to AMD's FSR when WrongGPU cannot run. -- **Ray Reconstruction plugin** (`clean/rr_f/proxy`): an ASI plugin that answers the game's Ray Reconstruction calls. -- **Launcher** (`clean/installer`): finds the games, installs and uninstalls WrongGPU per game (byte-exact restore), - gets OptiScaler, runs the converter, and shows what ran. -- **Reference and tests**: NumPy reference implementations (`clean/reference`, `clean/k/reference`, - `clean/rr_f/reference`), synthetic test vectors (`data/`, `clean/**/tests`), equivalence tools (`clean/equiv`). - No model data and no game frame captures are included. Test data is synthetic, except the launcher's log fixtures - (`clean/installer/tests/logs/`), some of which are trimmed excerpts of WrongGPU's own logs from game sessions, with - process ids, device pointers and paths replaced (see that folder's README.md and docs/CLEAN-ROOM.md). +The converter finds tensors using maps (`data/preset-M.v1.map.json`, `data/preset-F.v1.map.json`) containing offsets, +strides and digests, but no weights. The runtime runs the network once per frame on the game's Direct3D 12 device. The +FSR front end hands each frame to the runtime, or to AMD's FSR when WrongGPU cannot run. The Ray Reconstruction plugin +(`clean/rr_f/proxy`, an ASI plugin) answers the game's Ray Reconstruction calls. The launcher finds games, installs and +uninstalls WrongGPU with byte-exact restore, gets OptiScaler, runs the converter and shows what ran. ### Repository layout @@ -146,30 +137,41 @@ implementation's own design and format notes (per-file provenance records are ke | `clean/dx12` | Direct3D 12 kernels of Model M and their build (`build_dx12.py`) | | `clean/rr_f` | Ray Reconstruction: reference, kernels, runtime, plugin, tests | | `clean/k` | Model K (a per-game choice since 0.6.5, off by default) | -| `clean/fsr` | FSR front end (FidelityFX API provider) | +| `clean/fsr` | FSR front end (FidelityFX API provider, `amd_fidelityfx_dx12.dll`) | | `clean/installer` | the WrongGPU launcher | | `clean/wgshared` | settings registry shared by the front end, the plugin and the launcher | | `clean/reference`, `clean/equiv`, `clean/tests` | NumPy references, equivalence tools, unit tests | | `clean/third_party` | AMD FidelityFX SDK headers (MIT) | | `data` | converter maps and synthetic test vectors | +Model M's runtime includes the input encoder, Swin transformer blocks, coefficient decoder, output reconstruction and +filter, and auto-exposure. Ray Reconstruction adds its window blocks, head, output stage and resolve. Direct3D 12 compute +shaders are compiled with DXC; HIP kernels for gfx1201 / gfx1200 are compiled with the AMD HIP SDK. Model K also has +NumPy reference code in `clean/k/reference`, and Ray Reconstruction in `clean/rr_f/reference`. + +Tests use synthetic vectors in `data/` and `clean/**/tests`; no model data or game frame captures are included. The only +non-synthetic test data is in `clean/installer/tests/logs/`: some fixtures are trimmed excerpts of WrongGPU's own game +logs, with process ids, device pointers and paths replaced. See that folder's README.md and docs/CLEAN-ROOM.md. + 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: +WrongGPU is developed in the open by its community. Start with the +[welcome discussion](https://github.com/phantoslayer21/wronggpu/discussions/1). The project owner reviews and merges +changes, and builds and publishes the official releases. -- **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 +- **Players:** test games and report them using [COMPATIBILITY.md](COMPATIBILITY.md), or 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 + is to [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. +Every pull request needs the clean-room statement and a `Signed-off-by` line on each commit, as +[CONTRIBUTING.md](CONTRIBUTING.md) explains. CI checks licences, line endings, and CPU builds and tests on Windows. A +maintainer then performs a clean-room scan and review. Changes to kernels, the runtime, the front end or the Ray +Reconstruction plugin also need a test on a Radeon RX 9000-series card before the owner merges. ## Licence diff --git a/RELEASING.md b/RELEASING.md index fddd1024..5ca2bc0e 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,52 +1,60 @@ # 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). +This page explains how the project owner makes an official WrongGPU release. Contributors do not perform these steps. +The process covers the work between merging a pull request and publishing 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. +Only the project owner builds, tests, and publishes official releases. Pull requests merge into `main` as usual, but +the owner decides separately whether to make a release. Nobody else uploads release packages or creates release tags. -## 1. The source of a release +## 1. Identify the source -- 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 +- Build the release from **one commit on `main` in this repository**. Publish that commit before the release so anyone + can inspect exactly what was built. +- Point the release tag, such as `v0.6.5`, at that commit. Never move a tag after publishing it. Release a fix as 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). +- Set the version through the build options in [BUILDING.md](BUILDING.md). Use `-DWG_BUILD_ID=...` for the front end. + Use `-DWRONGGPU_VERSION=...`, `-DWRONGGPU_BUILD_ID=...`, and `-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`. +The owner builds from a fresh checkout of the release commit on the owner's own PC. Follow [BUILDING.md](BUILDING.md) +to build the kernels, runtime library, FSR front end, Ray Reconstruction plugin, payload, and launcher. + +Before uploading anything, complete all of these checks: + +- Pass the CPU tests in [BUILDING.md](BUILDING.md#6-tests-cpu). These are the same tests that CI runs on every pull + request. +- Pass the GPU tests on a Radeon RX 9000-series card. +- Use the launcher to install, run, and uninstall the release in real games, including every game named in the release + notes. +- Check that the package contains only WrongGPU's own files and their notices. It must contain no file from the + original upscaler, no model data, and no OptiScaler file. The launcher downloads OptiScaler from its own release. + +## 3. Prepare and check the release notes + +- Keep the notes in `clean/installer/RELEASE-NOTES.md` and review them through a pull request like any other change. +- Link the notes to the release page, which lists the **SHA-256 of the zip**. Link them also to `SHA256SUMS.txt` + inside the zip, which lists the SHA-256 of every file in the package. +- Trace every figure in the release notes, release page, and README to its measurement record. This includes timings, + quality figures, version requirements, and hardware lists. Record the game, resolution, mode, WrongGPU build, and + log or result file. Leave out any figure without a record. +- Before publishing, have someone who did not write the texts compare every figure across the README, release page, + and release notes, and against its record. A mismatch or untraced figure blocks the release until someone fixes or + removes it. + +## 4. Publish the package + +Only the owner can order an upload to the Releases page. Attach these items to the tag selected in step 1: + +- `WrongGPU-.zip`. +- The package's SHA-256 file. +- The release notes. + +Mark pre-releases as pre-releases. After publishing, download the package and check it against both the SHA-256 on the +release page and the entries in `SHA256SUMS.txt`. ## Licence of releases diff --git a/ROADMAP.md b/ROADMAP.md index bf78fc1f..0e349e7f 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,39 +1,41 @@ # 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 +These are plans, not promises. They have no dates, and their order can change with contributor interest and test +results from real hardware. 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). +[CONTRIBUTING.md](CONTRIBUTING.md), including the clean-room statement, sign-off, and testing rules. -## Next release (0.6.1) +## Game fixes and test tooling -- **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. +- **Hogwarts Legacy:** restore Ray Reconstruction. The game's November 2026 update greyed out its Ray Reconstruction + option, and the cause is still unknown. +- **RESIDENT EVIL requiem:** find the cause of the rare single overexposed or underexposed frame at a scene change. +- **Ray Reconstruction test setup:** make the end-to-end test (`clean/rr_f/runtime/tests/e2e.py`) set the compile-wait + setting that it needs. +- **Launcher build:** fix the remaining compiler warnings. ## 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. +Reduce Ray Reconstruction's GPU time per frame on RX 9000 cards without changing its output. Possible work includes +faster kernels for the body and output stages, fewer passes, and better use of the hardware's matrix instructions. + +A change intended to keep the output bit-identical must include the comparison described in +[BUILDING.md](BUILDING.md#comparing-kernels-with-a-release) and pass a GPU test 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. +The kernels currently target RDNA 4 (gfx1201 and gfx1200). Supporting RDNA 3 cards would require kernels without +RDNA 4's FP8 matrix instructions, followed by output and performance testing. The first step is an investigation. +RDNA 3 is not supported now. ## 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. +WrongGPU currently supports DirectX 12 games on Windows. A Vulkan path for Vulkan games and DirectX 12 games under +Proton on Linux would require a Vulkan executor for the runtime and a way to receive the game's upscaler inputs. The +first step is 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. +- More tests for code with insufficient coverage, especially CPU tests that CI can run. +- Clearer build instructions and corrections to [BUILDING.md](BUILDING.md) based on a fresh build. diff --git a/SECURITY.md b/SECURITY.md index afd86bc9..ec8a026e 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,16 +1,16 @@ # Security policy -WrongGPU's launcher installs files into game folders, can run elevated for that, and downloads OptiScaler from a -pinned release (URL, size and SHA-256 are fixed in `clean/installer/src/wg_core/optiedition.h`). The front end and the -plugin run inside games. Please report security problems in any of these privately. +WrongGPU's launcher installs files into game folders, can run elevated to do so, and downloads OptiScaler from a pinned +release. The URL, size, and SHA-256 are fixed in `clean/installer/src/wg_core/optiedition.h`. The FSR front end and the +Ray Reconstruction plugin run inside games. Report security problems in any of these components privately. -## Reporting a vulnerability +## Report a vulnerability -Use GitHub's private vulnerability reporting: on this repository's **Security** tab, choose **Report a -vulnerability**. Please do not open a public issue for a security problem. +Use GitHub's private vulnerability reporting. Open this repository's **Security** tab and choose **Report a +vulnerability**. Do not open a public issue for a security problem. -Include what you found, the version (or commit), and how to reproduce it. We will acknowledge the report, keep you -informed, and credit you in the release notes of the fix unless you prefer otherwise. +Include what you found, the affected version or commit, and reproduction steps. We will acknowledge the report and keep +you informed. We will credit you in the release notes for the fix unless you prefer otherwise. ## Supported versions @@ -18,6 +18,16 @@ Only the latest release receives security fixes. ## Scope -In scope: the launcher (`clean/installer`), the FSR front end (`clean/fsr`), the Ray Reconstruction plugin -(`clean/rr_f/proxy`), the runtime libraries and the converter. Out of scope: OptiScaler itself (report to its project), -the games, AMD's drivers and runtimes, and the original upscaler's files. +In scope: + +- The launcher in `clean/installer`. +- The FSR front end in `clean/fsr`. +- The Ray Reconstruction plugin in `clean/rr_f/proxy`. +- The runtime libraries and the converter. + +Out of scope: + +- OptiScaler itself. Report its security problems to the OptiScaler project. +- Games. +- AMD's drivers and runtimes. +- The original upscaler's files. diff --git a/docs/CLEAN-ROOM.md b/docs/CLEAN-ROOM.md index 7950cae9..a7fe7457 100644 --- a/docs/CLEAN-ROOM.md +++ b/docs/CLEAN-ROOM.md @@ -88,10 +88,10 @@ tensor shapes, offsets and strides, conversions, and a line naming the product a ## This repository -This repository is a snapshot of the source of WrongGPU 0.6.0, prepared for publication (one commit, no private -history). Left out: the +This repository was first published as a snapshot of WrongGPU 0.6.0, prepared for publication with one commit and no +private history. It now carries the source of WrongGPU 0.6.5. Not included: the specification, the clean team's questions and answers, the spec team's results notes, the team's own tools (for -example `tools/gpu_lock.py`, `tools/nv_leak_scan.py`) and the team's own build-machine tooling, and scratch probes that +example `tools/gpu_lock.py` and `tools/nv_leak_scan.py`), the team's build-machine tooling, and scratch probes that nothing builds. ## For contributors diff --git a/docs/TESTING-OTHER-GAMES.md b/docs/TESTING-OTHER-GAMES.md index b34934d6..c06f4763 100644 --- a/docs/TESTING-OTHER-GAMES.md +++ b/docs/TESTING-OTHER-GAMES.md @@ -1,72 +1,129 @@ # 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. +Test **WrongGPU 0.6.5** and its launcher in another DirectX 12 game. This guide helps you produce a useful report and +distinguish WrongGPU's results from AMD FSR and passed-through frames. See +[Game compatibility](../COMPATIBILITY.md) for current 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. +- **Do not test games with anti-cheat.** Do not bypass a launcher refusal. +- Use a **Radeon RX 9070 or RX 9070 XT** with a recent AMD Adrenalin driver. The RX 9060 XT and RX 9060 are supported + but untested. Report which card you use and how much video memory it has. The default Direct3D 12 path needs no HIP + runtime. +- Back up your saves. The launcher backs up every game file that it replaces and restores those files when you + uninstall WrongGPU. + +## Install WrongGPU for the game + +1. Download and extract [WrongGPU 0.6.5](https://github.com/phantoslayer21/wronggpu/releases/tag/v0.6.5), then run + `WrongGPU-0.6.5.exe`. +2. If the game is not in the Library, choose **Add game** and select the game's folder or executable. +3. Open the game's page and click **Install**. The launcher downloads the WrongGPU edition of OptiScaler. It also + finds usable DLSS files on your PC from any game or app. Model M and Model L need a DLSS file of version 310.5 or + newer. Model K is converted from a DLSS file from one of your games. Ray Reconstruction needs a DLSS Ray Reconstruction file + of version 310.7 or newer. For Ray Reconstruction, the launcher also prepares its GPU code. +4. Before starting the game, click **Turn on the FPS overlay** on the game's page. +5. Start the game and choose **DLSS** as its upscaler. Start in **Quality** mode. Turn on DLSS Ray Reconstruction if + the game offers it. -## Install +## Check the game -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). +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. Where the game allows it, include camera motion, thin geometry, foliage, moving + objects, particles, reflections, and scene transitions. +3. Look for flicker, ghosting, smearing, wrong colors, UI problems, stutter, crashes, or a black screen. Record the + scene and settings that trigger each problem. +4. For a matched visual comparison, switch to AMD FSR in **OptiScaler's menu** (Insert). Switch back to WrongGPU + before recording WrongGPU results. +5. Test resolution changes, quality switches, upscaler switches, and fresh game starts separately. Record memory + growth, errors, and whether WrongGPU resumes. -## Check the game +## Test Model L or Model K + +Model L is a larger super-resolution model than Model M. Model K is a different super-resolution network. Both are off +by default and selected per game. Test Model M first, then test Model L or Model K in the same game so you can compare +the results. + +### Prepare the model data + +For Model L, find a DLSS file of version 310.5 or newer that contains Model L's data. The file can come from any game +or app. From a command prompt in WrongGPU's folder, run: + +```bat +WrongGPU.exe model convert --preset=L +``` + +Add `--model=` to choose the file yourself. If no file on your PC contains Model L's data, the +command says so and changes nothing. + +For Model K, use a DLSS file from one of your games and run: + +```bat +WrongGPU.exe model convert --preset=K +``` -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. - -## Test Model L (WrongGPU 0.6.5 and later) - -Model L is a second, larger super-resolution model. It is off by default; you choose it per game. Test Model M first -(above), then Model L in the same game, so the two can be compared. - -1. **Prepare Model L's data once.** It is converted on your PC from a DLSS file of version 310.5 or newer that - contains Model L's data, from any game or app: - `WrongGPU.exe model convert --preset=L` (add `--model=` to pick the file yourself). If no - file on your PC has the data, it says so and nothing changes. -2. **Choose Model L for the game**, either way: - - `WrongGPU.exe set "" model=L` while the game is closed (`model=M` goes back). The game then - starts with Model L. - - In the game, in **OptiScaler's menu** (Insert), choose **WrongGPU Model L** as the upscaler. -3. **Check that Model L really runs.** The FPS overlay should show **DLSS → WrongGPU Model L**, and the game page's - **Last run** should say Model L after you quit. If it shows Model M, Model L did not start: say so in the report and - attach Collect logs (they say why). -4. **Play the same scenes as with Model M**, in the same DLSS mode and output resolution. Look especially for - ghosting behind moving objects, smearing, flicker on thin lines and foliage, and how quickly detail returns after - a camera cut. Note anything that looks better or worse than Model M. -5. **Measure Model L against Model M**, as in "Compare performance" below: Model M, then Model L, then Model M again, - same scene and settings. Model L costs noticeably more GPU time than Model M, so a lower frame rate is expected; - the release notes give measured times. Report both results. -6. In the report, say which model each result is for, and whether the game's colour was HDR or SDR, if you know - (the game's HDR setting). +WrongGPU converts the data on your PC. It does not download or ship the model data. + +### Choose the model + +Close the game. To choose Model L or Model K, run the corresponding command: + +```bat +WrongGPU.exe set "" model=L +WrongGPU.exe set "" model=K +``` + +The game then starts with that model. Use `model=M` to return to Model M. + +You can instead open **OptiScaler's menu** (Insert) in the game and choose **WrongGPU Model L** or **WrongGPU Model +K** as the upscaler. + +### Check and compare the model + +1. Check the FPS overlay for **DLSS → WrongGPU Model L** or **DLSS → WrongGPU Model K**. After quitting, check that + **Last run** names the same model. If it shows Model M, the selected model did not start. Say so in the report and + attach **Collect logs**, which records why. +2. Play the same scenes as with Model M, using the same DLSS mode and output resolution. Look for ghosting behind + moving objects, smearing, and flicker on thin lines and foliage. Check how quickly detail returns after a camera + cut. Record anything that looks better or worse than Model M. +3. Follow [Compare performance](#compare-performance), but measure Model M, then Model L or Model K, then Model M + again. Keep the scene and settings unchanged. The + [0.6.5 release notes](../clean/installer/RELEASE-NOTES.md#model-l-new) record higher GPU time for Model L than + Model M in a matched Cyberpunk 2077 test, so a lower frame rate is expected with Model L. Report both results. +4. Identify the model for every result. For Model L, also state whether the game used HDR or SDR color if you know. + Check the game's HDR setting. ## 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. +Use the same scene, output resolution, input upscaler, quality mode, and graphics settings for every run. Keep frame +generation, dynamic resolution, V-sync, and frame caps unchanged, and report 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 FSR runs differ substantially, repeat the comparison before claiming a +gain. + +For Model L or Model K, use the Model M, alternative model, Model M sequence described above instead. -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. +The time that **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: +Use [GitHub's game compatibility form](https://github.com/phantoslayer21/wronggpu/issues/new?template=game-compatibility-report.yml) +or the **#bug-reports** channel on 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, and which model (Model M or Model L) each result is for. -- Reproduction steps, screenshots or clips, and matched FPS / 1% low results. -- The ZIP from **Collect logs** on the game's page in the launcher. +- The game name, store, and version or build. +- The WrongGPU version, GPU and video memory, AMD driver, and Windows version. +- The output resolution, input upscaler, quality mode, and graphics settings. +- Whether Ray Reconstruction was on and its mode. +- What the FPS overlay and **Last run** showed, and which model each result used. +- Reproduction steps, screenshots or clips, and matched average FPS and 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. +Review the zip before posting it. System information and file paths can include your Windows user name. 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. +To remove WrongGPU from the game, choose **More → Uninstall WrongGPU** on the game's page. The launcher restores the +game's own files.