4 Commits

Author SHA1 Message Date
ruckus7382sfgsgdf
a939e9d0d1 Triforce v0.3.0
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-11 20:19:23 -06:00
ruckus7382sfgsgdf
035977a061 Triforce v0.2.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 22:37:38 -06:00
ruckus7382sfgsgdf
b855d86841 CONTRIBUTING: Triforce's own page (links, file names, logs)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 22:32:16 -06:00
ruckus7382sfgsgdf
a6bb7ffa09 CONTRIBUTING: Triforce's own, with its links, file names and logs
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 22:31:36 -06:00
13 changed files with 2090 additions and 336 deletions

View File

@@ -1,12 +1,13 @@
# Contributing to Hookshot
# Contributing to Triforce
Hookshot is a static recompilation of the Switch 2 *The Legend of Zelda: Ocarina of Time* remake: the game's AArch64
code is lifted to C, the Horizon OS and NVN2 are implemented natively, and the GPU work is replayed on Vulkan. No
emulator is involved, and the game is built on your PC from your own copy.
Triforce is a native PC port of the Switch 2 *The Legend of Zelda: Ocarina of Time* remake. The game's code is
translated to C and built on your own PC from your own copy of the game; the system and the graphics are rebuilt
natively, with the graphics replayed on Vulkan. No emulator is involved. Triforce builds on the open-source Hookshot
project (GPL-3.0), and its code keeps that license.
This page covers what to send, how to build and test it, and the rules that keep the project out of trouble. The
[development guide](docs/development.md) has the full pipeline and its commands; the [design notes](docs/design.md)
have the architecture and the lessons the code follows.
have the architecture.
## The rule with no exceptions
@@ -14,273 +15,135 @@ have the architecture and the lessons the code follows.
never will. That includes:
- the `.nup`, `romfs`, `exefs`, `.nso`, `.nca`, `.nsp`, `.xci` or `.nsz`/`.xcz` files, and any title keys;
- `work/` and everything in it: the extracted dump, `image.bin`, the lifted C, test builds, runs and screenshots;
- `hookshot.exe`, `hookshot_vk.dll`, `hookshot_programs.bin` (and its `hookshot_programs.idx`), `hookshot_pipelines.bin`,
`mkw_vk_pipelines.bin` and other build output;
- saves (`user/`), `hookshot_options.ini`, `hookshot_env.txt` and `language.txt`.
- `work/` and everything in it: the extracted dump, `image.bin`, the translated C, test builds, runs and screenshots;
- `Triforce.exe`, `triforce_vk.dll`, `triforce_shaders.bin`, `triforce_programs.bin` (and `.idx`),
`triforce_pipelines.bin`, `mkw_vk_pipelines.bin` and every other file a build or a run makes;
- saves (`user/`), `triforce_options.ini`, `triforce_env.txt` and `language.txt`.
Do not open an issue or a PR asking where to get the game, how to decrypt it, or for someone else's files. A
screenshot, a video and `hookshot_log.txt` are fine and often necessary; the log holds no game data.
Do not open an issue or a pull request asking where to get the game, how to decrypt it, or for someone else's files.
A screenshot, a video and `triforce_log.txt` are fine and often necessary; the log holds no game data.
`.gitignore` covers most of this, but check `git status` before you commit. If you are not sure whether a file is
game data, leave it out.
## Ways to help
## Reporting a problem
What to work on first, and the steps from claiming a problem to its release, are in the [workflow](docs/workflow.md):
priorities by severity and by how many players run the affected hardware, and the hardware tiers a change must not
break. Claim in Discord #dev-work before you start.
Open an [issue](https://github.com/ruckus7382sfgsgdf/CBeta0.2/issues) and include:
- the Triforce version (the release name, or the first line of `triforce_log.txt`);
- your graphics card, its driver version, and your Windows version;
- where you were in the game and what you did;
- the logs:
- **a game problem:** `triforce_log.txt` from your game folder (the folder with `Triforce.exe`). If you started the
game again after the problem, send `triforce_log.1.txt` too: each start keeps the four runs before it as
`triforce_log.1.txt` (the last) to `triforce_log.4.txt`.
- **a Setup or build problem:** `setup.log` from `%LOCALAPPDATA%\Programs\Triforce`, and for a failed build the text
from **Show details** on the build page.
Before you report:
- Try the [newest release](https://github.com/ruckus7382sfgsgdf/CBeta0.2/releases) first.
- Search the open issues; if yours is there, add your details to it.
- For graphics or performance problems, test without ReShade, overlays, shader-cache tools and frame-generation
injectors: they change what Triforce does.
- If graphics look wrong after an update, clearing the shader caches often helps: close the game and delete
`triforce_programs.bin`, `triforce_programs.idx`, `triforce_pipelines.bin`, `triforce_pipeline_states.bin`,
`triforce_computes.bin`, `mkw_vk_pipelines.bin` and `triforce_prepared.bin` from the game folder (never
`triforce_shaders.bin`). The next start prepares them again.
One topic per issue or pull request, in English, please.
## Ways to help
| | What |
|---|---|
| **Test on other hardware** | NVIDIA cards are the most tested; the README's [status table](readme.md#project-status) says what works where, and [tested configurations](docs/tested-configurations.md) lists the runs behind it (build, hardware, driver, where, fps). Reports from AMD and Intel cards, other NVIDIA drivers, other distributions and SteamOS are useful even when everything works: add a row there. |
| **Play further** | The tested area is the start of the game. Reaching new areas, cutscenes, menus and items finds problems the developer has not seen. |
| **Report what is broken** | Use the [issue forms](https://github.com/NotRexed/Hookshot/issues/new/choose): game problem, build problem or idea. Include the version, your hardware, where you were and `hookshot_log.txt`. |
| **Send a fix** | Fork, fix, test, open a pull request. Small, focused changes are easiest to review and merge. |
| **Improve the docs** | The README, the development guide and the design notes are part of the project. Corrections and clearer steps are welcome. |
## Before you open an issue or a PR
- Try the [newest release](https://github.com/NotRexed/Hookshot/releases/latest) first. It includes every fix before it.
- Search the open issues. If yours is already there, add your details instead of opening another.
- English, please.
- One topic per issue or pull request. Do not mix a fix with a refactor or a batch of unrelated changes.
- Report the version you actually ran: the release name, or the first line of `hookshot_log.txt`.
- Test without ReShade, shader-cache tools, overlays and frame-generation injectors when you report a graphics or
performance problem. They change what Hookshot does.
| **Test on other hardware** | NVIDIA cards are the most tested. Reports from AMD and Intel cards and other drivers are useful even when everything works. |
| **Play further** | Reaching new areas, cutscenes, menus and items finds problems nobody has seen yet. |
| **Report what is broken** | As above, with the version, your hardware, where you were and the log. |
| **Send a fix** | Fork, fix, test, open a pull request. Small, focused changes are easiest to review. |
| **Improve the docs** | Corrections and clearer steps are welcome. |
## Development setup
You need your own supported dump: program `0400486024DEC000`, update v131072, build `e0f3ccfa`. Other versions do
not work, and the build reads the dump where it lies without changing it. Builds need about 60 GB free and a run uses
about 10 GB of RAM. Build on an SSD if you can: a hard drive works, but takes much longer, and the builder warns you
before it starts.
You need your own supported copy of the game: program `0400486024DEC000`, update v131072, build `e0f3ccfa`. Other
versions do not work, and the build reads your files where they are without changing them. A build needs about 60 GB
free and takes around 40 minutes; a run uses about 10 GB of RAM. Build on an SSD if you can.
### Windows, from the command line
The easy way to get every tool a build needs is **Triforce Setup** from the
[releases](https://github.com/ruckus7382sfgsgdf/CBeta0.2/releases): it installs the tools (Python with its packages,
llvm-mingw, the Vulkan headers, FFmpeg, SDL2) into `%LOCALAPPDATA%\Programs\Triforce\tools`.
1. Install Python 3 from [python.org](https://www.python.org/downloads/) (not the Microsoft Store build: `python -I`
does not see packages installed there) and the pipeline's packages:
```powershell
python -m pip install -r requirements.txt
```
(the second line: the button prompts' packages. Without them the game shows the Switch's icons)
To build from a clone instead:
1. Install Python 3 from [python.org](https://www.python.org/downloads/) (not the Microsoft Store build) and the
pipeline's packages: `python -m pip install -r requirements.txt`.
2. Get [llvm-mingw](https://github.com/mstorsjo/llvm-mingw) (the `ucrt-x86_64` build) and set `HOOKSHOT_MINGW` to its
folder. Without it the build falls back to emsdk's clang at `C:\emsdk` with Visual Studio's C++ tools and the
Windows SDK (`HOOKSHOT_MSVC=1` forces that route).
3. Copy the pieces a clone does not carry from the `tools` folder Hookshot Builder installs. Run `HookshotBuilder.exe`
from the latest release once (releases no longer carry a `HookshotBuilder.zip`): the folder is
`%LOCALAPPDATA%\HookshotBuilder\versions\<version>\HookshotBuilder\tools`.
| From `tools` | To | Variable |
|---|---|---|
| `tools\cpm` | anywhere | `RX_CPM` points at it (Vulkan headers and FFmpeg; without it, system headers or `HOOKSHOT_*_HEADERS`, the standalone build stops) |
| `tools\wgpu-native` | anywhere | `WGPU_NATIVE` points at it (the WebGPU fallback renderer; without it the game is built without one) |
| `tools\third_party` | `third_party\` | (its `.dll`, `.exe`, `.lib` and `.sha1` files, to the same places: `a64emit`, `lld-link`, `zbic` and SDL2) |
| `tools\work` | `work\` | (hot-function list, link order, profile and icon; without it the game builds but runs slower) |
folder.
3. From the installed tools folder, point `RX_CPM` at `tools\cpm` and `WGPU_NATIVE` at `tools\wgpu-native`, and copy
`tools\third_party` into `third_party\` and `tools\work` into `work\`.
4. Run everything with `python -I` from the repository root.
### Linux
(Some environment variables still carry the older `HOOKSHOT_` name; they work as documented.).
Either use the `Hookshot-<version>-x86_64.AppImage` from the Releases page, or build the environment and the AppImage
yourself:
### Triforce Setup
```sh
scripts/linux/deps.sh # LLVM, Python packages, FFmpeg with dav1d, SDL2, Vulkan headers
scripts/linux/appimage.sh # the AppImage, in build-linux/
```
The AppImage needs glibc 2.35 or newer and a Vulkan 1.3 driver with mesh shaders. `HOOKSHOT_JOBS` sets how many files
compile at once. The README's [Linux section](readme.md#on-linux) has the details and the runtime paths.
### NVIDIA DLSS (optional)
DLSS (`gpu/vk/vk_dlss.cpp`) is built in only with NVIDIA's DLSS SDK, which is NVIDIA's, under NVIDIA's own license, and
is never committed, bundled or uploaded: not in a PR, not in a release, not in a CI artifact. Fetch it for your own
builds with `scripts/ngx_sdk.py` (it prints NVIDIA's license notice and needs `--accept-nvidia-license` or a typed yes),
then build with `HOOKSHOT_NGX_SDK=<sdk folder>`:
```powershell
python -I scripts/ngx_sdk.py --platform windows C:\path\ngx-sdk # headers, nvsdk_ngx_s.lib, nvngx_dlss.dll
$env:HOOKSHOT_NGX_SDK = "C:\path\ngx-sdk"
python -I nx2/make_game.py --nup "C:\path\your-game.nup" --out "C:\Games\Hookshot-dlss"
```
On Windows the llvm-mingw build links NVIDIA's static `nvsdk_ngx_s.lib` (built for Microsoft's static runtime) into
`hookshot_vk.dll`, with `gpu/vk/vk_ngx_msvc_rt.cpp` and `host/mingw_msvc_shims.c` for what it needs of that runtime.
`make_game.py` copies `nvngx_dlss.dll` into the game folder's `ngx` folder; never put NGX's core, `_nvngx.dll`, beside
the game (it is the driver's). On Linux it is `--platform linux` (or `scripts/linux/ngx-sdk.sh`), with `libnvsdk_ngx.a`
and `libnvidia-ngx-dlss.so`. A Windows game with DLSS can be built on Linux too, with `RX_TARGET=windows` as below.
CI's `vulkan-dlss` workflow (`.github/workflows/vulkan-dlss.yml`) checks only that `hookshot_vk.dll` still links with the
SDK. It runs by hand, and on a push or pull request only when a file DLSS's build depends on changes; it accepts NVIDIA's
license for that run alone and uploads nothing.
Never share a game folder built with the SDK. A change to the pinned release updates the file table and SHA-256s in
`scripts/ngx_sdk.py` (and `tests/test_ngx_sdk.py`), and the release named in the builder's license text
(`builder/HookshotBuilder/MainWindow.xaml.cs`).
### Hookshot Builder
The builder is a .NET 8 WPF app. Open `builder/HookshotBuilder.sln` in Visual Studio 2022 with the .NET desktop
workload, or build it from a developer prompt:
```powershell
dotnet build builder/HookshotBuilder.sln
```
You only need Visual Studio for the builder itself. The game build uses llvm-mingw.
The Windows app's **Build workers** choice applies to builds started from that window. **Automatic** keeps the existing
`HOOKSHOT_JOBS` override, or the build tools' free-memory policy when no override is set. A number overrides it for that
build's child process only; more workers need more memory and are not always faster. This choice is not saved: a new
window, including one started to update a game, uses Automatic again.
The launcher lives in `setup/`: a .NET Framework 4.8 WPF app, built with `powershell -File setup\build.ps1` (needs the
C# compiler from Visual Studio Build Tools). `setup\pack_tools.ps1` packs the tools zip a release carries. Never run a
development build's install, update or uninstall without `TRIFORCE_TEST_ROOT` set to a scratch folder: it would act
on your real install.
## Building
| Command | What it does |
|---|---|
| `python -I nx2/make_game.py --nup "C:\path\your-game.nup" --out "C:\Games\Hookshot" --language en-US` | Build a complete game folder from a `.nup`. A build takes about 40 minutes. |
| `python -I nx2/make_game.py --romfs "C:\path\romfs" --exefs "C:\path\exefs" --out "C:\Games\Hookshot"` | The same, from extracted folders. |
| `python -I nx2/make_game.py --nup "C:\path\your-game.nup" --out "C:\Games\Triforce" --language en-US` | Build a complete game folder from a `.nup`. |
| `python -I nx2/make_game.py --romfs "C:\path\romfs" --exefs "C:\path\exefs" --out "C:\Games\Triforce"` | The same, from extracted folders. |
| `python -I nx2/make_game.py --check --nup "C:\path\your-game.nup"` | Check the game and its version without building. |
| `python -I nx2/dump.py --dump <folder with exefs/ and romfs/> --set` | Record the dump in `work/dump.txt`. |
| `python -I nx2/lift.py --standalone --write` | Lift the game to C in `work/sa/gen`. |
| `python -I nx2/build.py --standalone --jobs 4` | Compile `work/sa/build/hookshot.exe` and `hookshot_vk.dll`. |
| `powershell -File scripts/run-vk.ps1 -Window -Seconds 120` | Run the standalone build with the Vulkan back end and take screenshots in `work/runs/<name>/shots`. |
| `python -I scripts/prof.py <stacks file>` | Read a profile sampled with `HOS_PROFILE`, `HOS_SAMPLE` and `HOS_SAMPLE_FILE`. |
Use a separate `--work` folder or `OOT_WORK` if you keep more than one dump around. The lifted C and every build are
local artifacts; they are never committed.
The translated C and every build are local files; they are never committed.
## Testing
### Game-free checks
These need no dump and are what CI runs, on every pull request and every push to `main`. One command runs them all:
The game-free checks need no game files:
```powershell
python -I -B tests/run_all.py
```
It runs every `tests/test_*.py` and `nx2/test_*.py` in its own process, the C++ unit tests under `gpu/vk/tests` and a
byte-compile of every tracked Python file, goes on after a failure, and ends with a table (slowest first) and every
failure's output. Name a check to run only the ones whose path contains it (`python -I -B tests/run_all.py ub_`). A new
`test_*.py` file is picked up by itself: no workflow to edit.
It runs every `tests/test_*.py` and `nx2/test_*.py`, the C++ unit tests under `gpu/vk/tests`, and a byte-compile of
every Python file, and ends with a table of results. Name a check to run only the ones whose path contains it. A new
`test_*.py` file is picked up by itself.
Some checks compile a small C or C++ fixture and need a compiler (`g++`, `gcc` or `clang++` on PATH), the SPIR-V
validator (`spirv-val`), the SPIR-V or Vulkan headers (`HOOKSHOT_SPIRV_HEADERS` / `HOOKSHOT_VULKAN_HEADERS`, or the CPM
cache in `RX_CPM` or `build-linux/deps/cpm`), or the `zstandard` package. A check whose tool is missing is skipped and
says so; CI passes `--strict`, which fails it instead. A check that cannot run in CI (a GPU, the game, a Visual Studio
prompt), or runs on one OS only, says so in its own file with `RUN_ALL_SKIP`; `--no-skip` runs it anyway.
When you add a fix, add a game-free test where the behavior can be tested without the game. For a renderer or runtime
fix, say what you saw before and after, on which GPU and driver, and where in the game.
### Checks that need your dump or a run
## Code conventions
These are slow and local, and they need `work/dump.txt` from `nx2/dump.py --set`:
- Match the file you are editing: its indentation, comment style and naming. Do not reformat unrelated code.
- Do not modify `third_party/`. Its parts are unmodified upstream copies, each with its notice in its own
`PROVENANCE.md`.
- New switches use the `RX_` prefix in the renderer and `HOS_` in the runtime, are off unless asked for, and cost
nothing while off.
- Rendering fixes must reproduce what the game itself does, not tuned factors that only look right on one screen.
- Python runs with `-I`; tests stay on the standard library. Keep line endings LF.
| Command | What it checks |
|---|---|
| `python -I nx2/test_insn.py` | Every instruction form the game uses, Unicorn against the lifted C. |
| `python -I nx2/test_leaf.py --calls` | Whole functions and call trees on the relocated image, native against Unicorn. |
| `python -I nx2/census.py --nx2` | The instruction census per module. |
| `python -I nx2/lower_test.py work/lowfail` | Shader programs that failed to lower. |
| `powershell -File scripts/run-vk.ps1 -Window` | An in-game run: screenshots, the flash detector, frame dumps and the profiler. |
## Pull requests
For a graphics fix, look at the screenshots in `work/runs/<name>/shots` and delete them afterwards; they reach
gigabytes and are derived from the game. The switches for scripted input, screenshots, frame dumps and profiles are in
the development guide's [reference](docs/development.md#switches-for-testing-and-debugging).
### When you add a fix or a check
- Add a game-free test where the behavior can be tested without the dump. The existing tests are small Python files
under `tests/` or `nx2/` that read source files and run them, or compile a tiny C++ fixture.
- Name it `tests/test_*.py` or `nx2/test_*.py`: `tests/run_all.py` picks it up by itself and CI runs it on every pull
request, so there is no workflow to edit. What it needs from the runner it declares in its own file, after its
docstring and imports, as plain literals `tests/run_all.py` reads without importing the test (its docstring has
the details); there is no central list to add a line to:
```python
RUN_ALL_ARGS = ["--cxx", "{cxx}", "--headers", "{vulkan_headers}"] # a compiler, headers, spirv-val ...
RUN_ALL_MODULES = ["zstandard"] # packages it imports
RUN_ALL_SKIP = {"windows": "POSIX signals: the Linux guard"} # cannot run in CI there (a GPU, the game,
# one OS only), and why
```
`{name}` is a tool the runner finds (`cxx`, `vulkan_headers`, `spirv_headers`, `spirv_val`, `glslang`, `dotnet`);
a check whose tool is missing is skipped, or fails with `--strict`. A test that needs none of this declares nothing.
- Keep the test fast: every check shares one CI job with a 20-minute limit. Make it pass on both Ubuntu and Windows
where it can.
- If the fix is in the renderer or the runtime, say what you saw before and after, on which GPU and driver, and in
which part of the game.
## Code and data conventions
- Match the file you are editing: there is no formatter configuration, so use the indentation, comment style and
naming around you. Do not reformat unrelated code in the same change.
- Keep OoT-specific code in new files where possible. `nx2/`, `host/` and `gpu/` are kept close to mkw-recomp so
upstream fixes can be applied as a patch; keeping the paths and the shared files recognizable is what makes that
work. Each sync names its new mkw-recomp base commit in the commit message.
- Do not modify `third_party/`. Its parts are unmodified upstream copies with their notices in `PROVENANCE.md`; add a
new folder and a provenance note rather than editing one.
- Treat the local mkw-recomp and Eglantine checkouts as read-only references: read from them, run them, never edit
them.
- New switches use the `RX_` prefix in the renderer and `HOS_` in the runtime. They are off, or neutral, unless
asked for, and they do not cost anything while off. Document them where the surrounding switches are documented.
- The GPU replay rules in [design notes, section 4](docs/design.md#4-the-lessons-from-mkw-as-rules-here) are not
suggestions: nothing the replay reads may come from live guest memory, waits are honoured per queue, and texture
and sampler registrations stay in submission order. A change that reads guest memory at replay time is a
regression, even if it looks right on one frame.
- Python runs with `-I`. Tests stay on the standard library so CI needs no install step; the pipeline's existing
dependencies (lz4, numpy, capstone, unicorn, zstandard) are the exception, not a reason to add more. So are the
button prompts' (fontTools, Pillow, astc-encoder-py, texture2ddecoder: `nx2/prompt_requirements.txt`), accepted for
`nx2/prompt_assets.py` and `nx2/prompt_draw.py` alone, at build time. Maintainers' agents reviewing a change: check
that these four are still used only there, and flag any other use. Keep line endings LF (`.gitattributes`).
- New code has to be GPL-compatible. See below.
## Commits and pull requests
1. Fork the repository and branch from `main`. Name the branch for the change: `fix/...`, `linux/...`, `builder/...`,
`docs/...`.
2. Keep the pull request to one topic. Bug fixes do not carry refactors, and two unrelated fixes are two PRs.
3. Write the title as a short imperative sentence, as the history does: "Stop scanning storage-buffer tables after
one pass", "Linux: a crash report gives the whole host stack". Start the body with why the PR is needed, in one or
two plain sentences a player could follow: the bug, the missing feature or the cost it removes ("The menu's text
is cut off at 4K", "First starts spend 20 s waiting on a few shaders"). Then say what changed, how it was tested
(GPU, driver, game area, fps before and after), and link the issue it fixes.
4. Include screenshots when the change shows on screen: graphics, the menu, the start-up screen, an overlay, a
message. Before and after for a fix, the new screen for a feature, and the sizes or settings it was checked at. A
screenshot of the game is fine; the rule above is about game files, not pictures of the game.
5. Run the relevant checks. CI must pass; a change that only works on your machine is not ready.
6. Rebase or merge `main` when it has moved, and resolve conflicts in your branch rather than in the review.
7. Do not include build output, dumps, generated files or a `.gitignore` bypass. Check `git status`.
Commit subjects decide the next release: write them as Conventional Commits (`feat:`, `fix:`, and `!` or
`BREAKING CHANGE:` for a break). The version rules, branches and changelog format are in
[docs/versioning.md](docs/versioning.md).
Maintainer commits record AI assistance with `Assisted-by:` and `Co-Authored-By:` trailers. If you used a tool, add
the trailers that describe it; if you wrote the change yourself, there is nothing to add.
1. Fork the repository and branch from `main`.
2. One topic per pull request: a fix does not carry a refactor.
3. Title: a short imperative sentence. Body: why it is needed, what changed, how it was tested (GPU, driver, game
area, fps before and after), and the issue it fixes.
4. Screenshots for anything that shows on screen, before and after.
5. No build output, dumps or generated files. Check `git status`.
## Licensing
Hookshot is free software under the [GNU General Public License, version 3 or later](LICENSE). By submitting a change
you agree to license it under those terms. Only send code you can license that way. Do not paste code from a project
with an incompatible license, and do not paste decompiled game code or anything generated from the dump into a PR.
Triforce is free software under the [GNU General Public License, version 3 or later](LICENSE), like the Hookshot code
it builds on. By submitting a change you agree to license it under those terms. Do not paste code from a project with
an incompatible license, and never paste decompiled game code or anything generated from the game files.
The third-party parts (Eden, suyu, Sirit, the Vulkan Memory Allocator, SDL, Opus, Dear ImGui, zstd, the Libertinus
fonts, zbic and the a64-kit tools) keep their own notices. Preserve them, and do not relicense their code.
fonts, zbic and the a64-kit tools) keep their own notices. Preserve them.
NVIDIA's DLSS SDK is not one of them: it is never in the repository, and nothing of it may be added (see
[NVIDIA DLSS](#nvidia-dlss-optional)).
## Where to talk
- **Issues:** [use the forms](https://github.com/NotRexed/Hookshot/issues/new/choose).
- **Discord:** https://discord.gg/EajnD2AJD9. Use the `hookshot-discussion` channel; the server is mainly for
web ports, and that channel is where Hookshot talk belongs.
- **Newest release:** https://github.com/NotRexed/Hookshot/releases/latest.
Thanks for testing, reporting and sending fixes. Every report from a different GPU and every area played further than
before moves the port forward.
Thanks for testing, reporting and sending fixes. Every report from a different GPU and every area played further
moves the port forward.

View File

@@ -1190,11 +1190,46 @@ void state_record(const Program& p, const NvnState& s, const Targets& at, VkPrim
if (!state_file) state_open_locked();
if (state_file && state_seen.insert(h).second) fwrite(&r, sizeof r, 1, state_file), fflush(state_file);
}
/// (perf push 11-11) Which shipped list this folder's notes were last made from, in triforce_states_applied.bin: the list's
/// contents and the translator, hashed. The lists were gone through only inside a prepare (a first start, a new translator, a
/// new seed): a folder prepared already that got a longer shipped list (an update with the same translator, a list copied in)
/// never noted its pipelines, and built each in play when first drawn (a lab folder with a 12067-pipeline list: 2687 built in
/// play, the list not read once). 0: there is no shipped list
uint64_t state_shipped_id() {
FILE* f = fopen(state_list_path("triforce_pipeline_states_shipped.bin").c_str(), "rb");
if (!f) return 0;
uint64_t h = 0xCBF29CE484222325ull ^ program_cache_stamp(), total = 0;
std::vector<uint8_t> buf(1 << 16);
for (size_t n; (n = fread(buf.data(), 1, buf.size(), f)) > 0; total += n)
for (size_t i = 0; i < n; i++) h = (h ^ buf[i]) * 1099511628211ull;
fclose(f);
return total > 12 ? (h | 1) : 0;
}
/// Whether the shipped list is one the notes were not made from yet
bool state_shipped_new() {
if (getenv("RX_VK_NO_STATE_LIST")) return false;
const uint64_t id = state_shipped_id();
if (!id) return false;
uint64_t had = 0;
if (FILE* f = fopen(state_list_path("triforce_states_applied.bin").c_str(), "rb")) {
if (fread(&had, 8, 1, f) != 1) had = 0;
fclose(f);
}
return had != id;
}
/// (prepare_run, the seed open) every pipeline of the state lists (the player's own and the shipped one): its program translated
/// when the program cache lacks it, then noted in triforce_pipelines.bin for precompile_run to build. RX_VK_NO_STATE_LIST=1: off
void state_list_prepare(void (*progress)(size_t done, size_t total)) {
if (getenv("RX_VK_NO_STATE_LIST")) return;
const auto t0 = std::chrono::steady_clock::now();
const uint64_t shipped_id = state_shipped_id();
struct Applied { // (written when the lists were gone through, however this returns)
uint64_t id;
~Applied() {
if (!id) return;
if (FILE* f = fopen(state_list_path("triforce_states_applied.bin").c_str(), "wb")) fwrite(&id, 8, 1, f), fclose(f);
}
} applied{shipped_id};
std::vector<StateRec> recs = state_list_read(state_list_path("triforce_pipeline_states_shipped.bin"));
const size_t shipped = recs.size();
for (const StateRec& r : state_list_read(state_list_path("triforce_pipeline_states.bin"))) recs.push_back(r);
@@ -1220,6 +1255,9 @@ void state_list_prepare(void (*progress)(size_t done, size_t total)) {
rec_program[i] = it->second;
}
std::atomic<size_t> next{0}, made{0}, missing{0};
// (perf push 11-11: why a program of the list has no key. 0 a header-only stage, 1 mesh on a GPU without, 2 a stage the
// seed lacks or has as another kind. Measured on OoT: all 2178 of 6150 are the last, vertex and fragment both absent)
std::atomic<size_t> why_missing[3]{};
const auto worker = [&] {
ub_thread_off(); // (a background thread: see ub_thread_off; the pipeline state list's builds raced the replay's updates)
SetThreadPriority(GetCurrentThread(), THREAD_PRIORITY_BELOW_NORMAL);
@@ -1230,7 +1268,15 @@ void state_list_prepare(void (*progress)(size_t done, size_t total)) {
std::unique_ptr<Program> p;
// (a mesh program on a GPU without mesh shaders is not made; one with a header-only stage is made in play)
if (!r.code[3] && (!r.mesh || dev.mesh_shader)) p = seed_program_of(r.code, r.mesh != 0, r.vattr, r.color_types, &want[i].key);
if (!want[i].key) missing++;
if (!want[i].key) {
missing++;
why_missing[r.code[3] ? 0 : r.mesh && !dev.mesh_shader ? 1 : 2]++;
static std::atomic<int> told{0};
if (getenv("RX_VK_SEED_CHECK") && told++ < 40)
logf("vk: state list: no key for %016llx %016llx %016llx %016llx mesh %u",
(unsigned long long)r.code[0], (unsigned long long)r.code[1], (unsigned long long)r.code[2],
(unsigned long long)r.code[3], r.mesh);
}
if (p) {
if (!p->failed) made++;
for (Stage& st : p->stages)
@@ -1311,6 +1357,10 @@ void state_list_prepare(void (*progress)(size_t done, size_t total)) {
"by their textures (%zu made), %zu noted, %zu whose program variant was not made, in %.1f s", recs.size(), shipped,
want.size(), made.load(), missing.load(), variant_of.size(), variants_made.load(), noted_n, no_variant,
std::chrono::duration<double>(std::chrono::steady_clock::now() - t0).count());
if (missing.load())
logf("vk: state list: the %zu programs without a key: %zu with a header-only stage, %zu mesh (none on this GPU), %zu with a "
"stage the game's shader list lacks (made in play)", missing.load(), why_missing[0].load(), why_missing[1].load(),
why_missing[2].load());
}
// ---- (hookshot) Stage libraries, as TotK Recomp's runtime/vk_pipeline.c: the part of a pipeline that costs is its shaders, and with
@@ -2060,8 +2110,10 @@ struct HandleHit {
uint64_t destroy_gen;
bool sampling; // (its use reads the texture's contents)
uint64_t tex_epoch; // (the texture epoch it was last touched in)
bool known = true; // (Triforce: the slot is registered: with no view, a texture whose image is not there yet)
};
TLS_OBJECT(handle_hits, std::unordered_map<uint64_t, HandleHit>)
thread_local bool view_slot_known = true; // (Triforce: the last texture_view_of's slot was a registered one)
// (hookshot) RX_VK_TRACE_TEX=<w>x<h>,...: each draw sampling a texture of that size is logged with its state, every 30th frame, 600 lines: a
// model that does not show is found by its textures, and whether the game draws it, and how, read from the line
thread_local const Texture* trace_tex_hit = nullptr;
@@ -2125,6 +2177,7 @@ VkImageView texture_view_of(uint32_t handle, VkImageViewType want, ViewUse use,
}
if (tex_out) *tex_out = it->second.tex;
if (level_out) *level_out = it->second.level;
view_slot_known = it->second.known;
return it->second.view;
}
ParLock lk;
@@ -2141,6 +2194,31 @@ VkImageView texture_view_of(uint32_t handle, VkImageViewType want, ViewUse use,
if (tex) level = image_level(tex, has_view ? view_level(&v) : 0);
}
if (!view) { // (what a shader reads as the dummy instead: once per texture slot)
{ // (Triforce, diagnostics) RX_VK_LOG_DUMMY=1: every 10 s, the slots that were resolved to the dummy in the last second
static const bool log_dummy = getenv("RX_VK_LOG_DUMMY") != nullptr;
if (log_dummy) {
struct Seen { int64_t n = 0; std::chrono::steady_clock::time_point last; char desc[200]; };
static std::unordered_map<uint32_t, Seen> seen;
static auto next = std::chrono::steady_clock::now() + std::chrono::seconds(10);
const auto now = std::chrono::steady_clock::now();
Seen& d = seen[handle & 0xFFFFF];
d.n++, d.last = now;
if (!known) snprintf(d.desc, sizeof d.desc, "not registered");
else snprintf(d.desc, sizeof d.desc, "%s; target %d format %#x %ux%ux%u levels %u gpu %#llx view %s (format %#x target %d) want %d use %d",
tex ? "no view of it" : "no image for it", t.d.target, t.d.format, t.d.width, t.d.height, t.d.depth, t.d.levels,
(unsigned long long)t.gpu, has_view ? "yes" : "no", has_view && v.set_format ? v.format : 0,
has_view && v.set_target ? v.target : -1, (int)want, (int)use);
if (now >= next) {
next = now + std::chrono::seconds(10);
int k = 0;
for (auto& [slot, e] : seen)
if (now - e.last < std::chrono::seconds(1) && k++ < 48)
logf("vk: dummy: slot %#x resolved %lld times in 10 s: %s", slot, (long long)e.n, e.desc);
logf("vk: dummy: %d slots resolved to the dummy in the last second", k);
for (auto& [slot, e] : seen) e.n = 0;
}
}
}
static std::unordered_map<uint32_t, int> told;
if (told.size() < 64 && !told[handle & 0xFFFFF]++) {
if (!known)
@@ -2153,7 +2231,8 @@ VkImageView texture_view_of(uint32_t handle, VkImageViewType want, ViewUse use,
has_view && v.set_format ? v.format : 0, has_view && v.set_target ? v.target : -1, (int)want, (int)use);
}
}
handle_hits()[key] = {view, tex, level, version, dgen, use == ViewUse::Sample || use == ViewUse::Storage, texture_epoch()};
handle_hits()[key] = {view, tex, level, version, dgen, use == ViewUse::Sample || use == ViewUse::Storage, texture_epoch(), known};
view_slot_known = known;
if (tex_out) *tex_out = tex;
if (level_out) *level_out = level;
return view;
@@ -2328,6 +2407,7 @@ bool dump_sampled_wanted(uint64_t key) {
} // (RX_VK_DUMP: the storage images the descriptors let the program write)
TLS_OBJECT(dump_inputs, std::string) // (and what it samples)
int64_t st_dummy_textures; // (textures sampled as the dummy: no image for the handle)
int64_t st_dummy_known; // (Triforce: of those, registered textures: their image not made or not uploaded yet)
void dump_input(char kind, uint32_t index, uint32_t handle, const Texture* tex) {
char b[160];
@@ -2877,7 +2957,7 @@ void build_descriptors(const NvnState& s, const Program& p) {
tex ? tex->width : 0, tex ? tex->height : 0, tex ? tex->layers : 0, tex ? (void*)tex->image : nullptr,
(void*)view, view ? "" : " (dummy)");
if (view && tex && tex->gpu_written) draw_sampled().push_back(tex);
if (!view) view = dummies.view[(int)vt], st_dummy_textures += handle != 0;
if (!view) view = dummies.view[(int)vt], st_dummy_textures += handle != 0, st_dummy_known += handle != 0 && view_slot_known;
dw().imgs.push_back({sampler_for((int)(handle >> 20), d.is_depth), view, VK_IMAGE_LAYOUT_GENERAL});
}
w.pImageInfo = &dw().imgs[first];
@@ -2942,6 +3022,10 @@ TLS_OBJECT(pushed, std::array<Pushed, 2>) // [graphics, compute]
/// to it)
VkPipelineCache shared_pipeline_cache() { return pcache; }
void draw_skip_report(double frames) { skip_report_impl(frames), fine_report(frames); }
/// (Triforce) how many texture bindings have sampled the dummy so far (a texture with no image yet: left for a later frame, not
/// made, evicted): RX_VK_FRAME_TRACE's last column, the measure of materials showing flat while their textures come in
/// Registered textures only: OoT binds one handle of no registered slot (0x3126f) in ~18 places a frame, always the dummy
int64_t draw_dummy_textures() { return st_dummy_known; }
void descriptors_disturbed() {
pushed()[0].cmd = pushed()[1].cmd = VK_NULL_HANDLE;
}
@@ -7102,6 +7186,15 @@ bool prepare_run(void (*progress)(size_t done, size_t total), bool background) {
logf("vk: the shader list was hashed (%.0f MB in %.0f ms): written since the last check, or too close to it to go by its time",
prepared_for.seed_size / 1048576.0, hash_ms);
if (why == PrepareWhy::None && !getenv("RX_VK_PREPARE_AGAIN")) {
// (perf push 11-11: a shipped state list the notes were not made from, in a folder prepared already: its pipelines are
// noted now, for the precompile that follows, as a prepare would have. See state_shipped_id)
if (!background && state_shipped_new()) {
logf("vk: the shipped pipeline list is not the one this folder's notes were made from: its pipelines are noted now");
if (seed_open()) {
state_list_prepare(nullptr);
seed_close();
}
}
if (getenv("RX_VK_SEED_CHECK")) seed_open();
if (prepared_for.warmed == warmed || background) return false;
// (translated, and the driver's part is another driver's, or of before the libraries were wanted: that part alone, no
@@ -7279,6 +7372,47 @@ void prepare_background() {
}).detach();
}
// ---- (perf push 11-11) The precompile on a PC with little RAM. Every pipeline built here is kept for the session, with its
// program: measured at a fresh Market (RTX 4070 SUPER), the process holds 12.9 GB in RAM without the precompile, 13.4 GB with
// 4704 graphics and 275 compute pipelines, 15.7 GB with 8550 and 1650; after a tour of ten areas 18.6 against 20.6 GB. What
// the precompile is for is the compile, which the caches keep (ours, mkw_vk_pipelines.bin, and the driver's): with them warm,
// the same runs without it built 1462 and 4046 pipelines in play in 357 and 1639 ms in all (0.2-0.4 ms each), with as many
// frames over 40, 100 and 250 ms as with it. So where RAM is short (under 20 GB in the PC: the 16 GB ones, whose logs show the
// system taking pages back all through play) a pipeline is built before the game once, on the first start that has its note,
// and that start records it (triforce_pipelines.bin.built, for this translator and driver); later starts leave it to its first
// draw, and neither it nor its program is in RAM until then.
// The price, same tour: of ~4050 pipelines then built in play, ten or twelve submissions spend 10-65 ms on them (some in frames
// that were slow anyway, an area's arrival; three or four make a 40 ms frame of their own), and one in two tours had a
// pipeline the caches missed (508 ms). So it is not the default: RX_VK_PRECOMPILE_KEEP=auto: this rule where the PC has under
// 20 GB of RAM; =0: on any PC; unset or 1: every start builds and keeps all, as before ----
constexpr uint64_t kBuiltComputes = 0xC04D50555445D001ull; // (in the record: the compute programs' pipelines were built)
bool precompile_keeps_all() {
const char* e = getenv("RX_VK_PRECOMPILE_KEEP");
if (!e) return true;
if (strcmp(e, "auto")) return atoi(e) != 0;
#ifdef _WIN32
MEMORYSTATUSEX ms{};
ms.dwLength = sizeof ms;
if (GlobalMemoryStatusEx(&ms)) return ms.ullTotalPhys >= (20ull << 30);
#endif
return true;
}
std::unordered_set<uint64_t> built_read(uint64_t stamp) {
std::unordered_set<uint64_t> keys;
if (FILE* f = fopen((pipe_notes_path() + ".built").c_str(), "rb")) {
uint64_t v = 0;
if (fread(&v, 8, 1, f) == 1 && v == stamp)
while (fread(&v, 8, 1, f) == 1) keys.insert(v);
fclose(f);
}
return keys;
}
void built_write(uint64_t stamp, const std::unordered_set<uint64_t>& keys) {
std::vector<uint64_t> all{stamp};
all.insert(all.end(), keys.begin(), keys.end());
if (FILE* f = fopen((pipe_notes_path() + ".built").c_str(), "wb")) fwrite(all.data(), 8, all.size(), f), fclose(f);
}
void precompile_run(void (*progress)(size_t done, size_t total)) {
const auto t0 = std::chrono::steady_clock::now();
// (a start that dies in here would die in here every time, the notes being what it builds from: a player saw the console reach
@@ -7312,12 +7446,29 @@ void precompile_run(void (*progress)(size_t done, size_t total)) {
std::lock_guard lk(state_mu);
if (!state_file) state_open_locked();
}
// (little RAM, see precompile_keeps_all: the pipelines an earlier start built for these caches are left to their first draw)
const bool light = !precompile_keeps_all();
const uint64_t built_stamp = warmed_stamp(gpl_wanted());
std::unordered_set<uint64_t> built;
const size_t noted_n = notes.size();
bool computes_built = false;
if (light) {
built = built_read(built_stamp);
computes_built = built.count(kBuiltComputes) != 0;
std::erase_if(notes, [&](const std::unique_ptr<PipeNote>& n) { return built.count(n->key) != 0; });
logf("vk: precompile: RAM spared (RX_VK_PRECOMPILE_KEEP=1: as before): %zu of %zu noted pipelines were built by "
"an earlier start and are left to their first draw%s", noted_n - notes.size(), noted_n,
computes_built ? ", the compute programs' too" : "");
}
std::vector<uint64_t> building; // (their keys, for the record once they are built)
if (light)
for (const auto& n : notes) building.push_back(n->key);
std::unordered_set<uint64_t> wanted;
for (const auto& n : notes) wanted.insert(n->prog);
// (the compute programs: those play dispatched (triforce_computes.bin), or every kept one when there is no list yet)
const char* which = getenv("RX_VK_PRECOMPILE_COMPUTES");
const std::unordered_set<uint64_t> used = computes_read();
const bool all_computes = which ? !strcmp(which, "all") : used.empty();
const std::unordered_set<uint64_t> used = computes_built ? std::unordered_set<uint64_t>{} : computes_read();
const bool all_computes = !computes_built && (which ? !strcmp(which, "all") : used.empty());
if (!all_computes && !(which && !strcmp(which, "none"))) wanted.insert(used.begin(), used.end());
std::vector<Program*> computes, fallbacks;
const size_t programs_n = program_cache_load_some(wanted, [&](Program& p) {
@@ -7431,6 +7582,13 @@ void precompile_run(void (*progress)(size_t done, size_t total)) {
} else {
for (std::thread& t : threads) t.join();
delete pre;
// (little RAM: what this start built is on disk before the record says so, and the next start leaves it out)
if (light && !prepare_stopped() && (!building.empty() || !computes_built)) {
built.insert(building.begin(), building.end());
built.insert(kBuiltComputes);
pipeline_cache_save(true);
built_write(built_stamp, built);
}
}
logf("vk: precompile: %zu programs, %zu graphics and %zu compute pipelines, %zu mesh fallback programs in %.0f ms (%.0f ms "
"of it the caches opened, the notes and programs read)", programs_n, graphics_n, computes_n, fallbacks_n,

View File

@@ -65,6 +65,7 @@ void dry_marks_begin(); // (at the start of each dry pass: the last targets it
void draw_stats(int64_t* draws, int64_t* skipped, int64_t* dispatches, int64_t* pipelines);
void draw_stats2(int64_t* passes, int64_t* mesh, double* pipeline_ms);
void draw_stats3(int64_t* pending_skips, int64_t* waits, double* wait_ms);
int64_t draw_dummy_textures(); // (Triforce: texture bindings that sampled the dummy so far: RX_VK_FRAME_TRACE)
/// (hookshot) pipelines linked from stage libraries in the draw, and the libraries asked of the driver for them: had, and cold;
/// of the cold, those a worker has built since, and the workers' time in them. False: no stage libraries (RX_VK_GPL)
bool draw_stats4(int64_t* links, double* link_ms, int64_t* lib_hits, int64_t* lib_cold, int64_t* lib_built, double* lib_build_ms);

View File

@@ -210,6 +210,9 @@ void memory_drop_shadow(uint64_t guest, uint64_t size); // (a write the captur
/// when any write-back ever did
uint64_t memory_writeback_value(uint64_t guest, uint64_t size, bool* ever);
void memory_note_readback(uint64_t guest, uint64_t size); // (PR 430) a CPU read of GPU results: see memory_rb_refresh
/// (Triforce) around the write of an NVN event's word by a command buffer's signal: its write-back is not one the captures of
/// its page wait for (vk_memory.cpp). This thread's bindings while on
void memory_bind_event_write(bool on);
bool memory_rb_refresh(VkCommandBuffer up);
void memory_rb_recording_begun(); // (hookshot) at a recording's start, on its thread: the submission it joins (memory_rb_refresh)
void memory_rb_segments_begin(uint64_t base, uint64_t n); // (and a parallel replay's segments: their order, base on)
@@ -219,11 +222,12 @@ void memory_note_gpu_write(uint64_t gpu, uint64_t size);
uint64_t vk_timeline_completed();
void vk_timeline_wait(uint64_t v);
uint32_t memory_generation();
uintptr_t memory_stamp_who(uint64_t guest, uint32_t* gen, uintptr_t* anchor); // (RX_VK_STAMP_SRC: who wrote that page last)
/// 1: a page of [guest, guest + size) was written after generation gen; 0: none was
bool memory_written_since(uint64_t guest, uint64_t size, uint32_t gen);
void memory_stamp(uint64_t guest, uint64_t size); // a write the watch does not see (GPU writes, host writes)
/// The page runs of [guest, guest + size) written after gen, as byte ranges from guest (appended to out)
void memory_written_runs(uint64_t guest, uint64_t size, uint32_t gen, std::vector<std::pair<uint64_t, uint64_t>>& out);
void memory_written_runs(uint64_t guest, uint64_t size, uint32_t gen, std::vector<std::pair<uint64_t, uint64_t>>& out, bool tex = false);
uint64_t memory_pages_collected(); // (statistics)
/// An NVN format as Vulkan stores it (vk_formats.cpp): ASTC is decoded to RGBA8, block_w x block_h
@@ -271,6 +275,19 @@ bool create_buffer(uint64_t size, VkBufferUsageFlags usage, bool host_visible, V
void destroy_buffer(VkBuffer buffer, VmaAllocation allocation);
/// A buffer in VRAM only (within the driver's budget), or false
bool create_device_buffer(uint64_t size, VkBufferUsageFlags usage, VkBuffer& buffer, VmaAllocation& allocation, bool dedicated = false);
/// (Triforce) device memory for a piece of a sparse buffer, and its release (vk_vma.cpp)
bool vma_piece_alloc(uint64_t size, uint64_t alignment, uint32_t type_bits, VmaAllocation& allocation, VkDeviceMemory& memory,
uint64_t& offset);
void vma_piece_free(VmaAllocation allocation);
/// (Triforce) the mirrors' pieces made resident in this recording, bound before it is submitted (vk_memory.cpp)
void memory_mirror_binds_flush();
bool memory_mirror_bind_wait(VkSemaphoreSubmitInfo* wait); // (and the wait a queue submission makes for those binds)
/// (Triforce, vk_memory.cpp) The memory handling played on NVIDIA cards only (mirrors in pieces, compacted textures): on there,
/// and on trial on a card of another make until triforce_memtrial.txt says it passed or failed. tick: at the 600th presents;
/// device_lost: from device_lost()
bool memory_trial_on();
void memory_trial_tick();
void memory_trial_device_lost();
/// Device-local memory this process uses and what the driver allows it now (VK_EXT_memory_budget), summed over the
/// device-local heaps; false when unknown
bool vram_usage(uint64_t* used, uint64_t* budget, uint64_t* block_free = nullptr);

View File

@@ -885,6 +885,7 @@ void prepare_with_screen() {
std::thread worker([] {
const bool update = prepare_is_update(); // (an update, RX_VK_PREPARE_BACKGROUND=1: what the notes name now, the rest in play)
const bool prepared = !update && prepare_run(prep_progress, false);
if (update) state_list_run(); // (as the start without a screen does, below: the state lists' pipelines before the precompile)
if (prepared && !prepare_stopped()) { // (a first start only: the pipelines the notes predict, into the driver's cache)
prep_done.store(0), prep_total.store(0);
prep_stage.store(1);

File diff suppressed because it is too large Load Diff

View File

@@ -180,6 +180,8 @@ void queue_flush_locked() { // (dev.present_mu held)
si.pCommandBufferInfos = pend.cbs.data();
si.signalSemaphoreInfoCount = n;
si.pSignalSemaphoreInfos = sig;
VkSemaphoreSubmitInfo bind_wait; // (Triforce: after the memory of the mirrors' new pieces is bound, vk_memory.cpp)
if (memory_mirror_bind_wait(&bind_wait)) si.waitSemaphoreInfoCount = 1, si.pWaitSemaphoreInfos = &bind_wait;
PROF(PROF_QSUBMIT);
const VkResult res = vkQueueSubmit2(dev.queue, 1, &si, VK_NULL_HANDLE);
static int failures;
@@ -355,6 +357,8 @@ void submit_recording(Recording& r, bool signal_value = true, uint64_t signal_at
return;
}
PROF(PROF_QSUBMIT);
VkSemaphoreSubmitInfo bind_wait; // (Triforce: after the memory of the mirrors' new pieces is bound, vk_memory.cpp)
if (memory_mirror_bind_wait(&bind_wait)) si.waitSemaphoreInfoCount = 1, si.pWaitSemaphoreInfos = &bind_wait;
const VkResult res = vkQueueSubmit2(dev.queue, 1, &si, r.fence);
r.submitted = res == VK_SUCCESS;
static int failures;
@@ -732,7 +736,9 @@ void replay(VkCommandBuffer& cmd, NvnState& s, const uint8_t* p, const uint8_t*
end_pass(cmd);
GprofSpan gp(cmd, "event signal (barrier, write, barrier)");
full_barrier(cmd);
memory_bind_event_write(true); // (Triforce: not a write-back the captures of its page wait for)
gpu_write(cmd, e.gpu, &v, 4);
memory_bind_event_write(false);
break;
}
case NOP_WAIT_EVENT: { // (a wait for an event another queue's work signals: submit_job orders them)
@@ -1282,10 +1288,76 @@ void maybe_split(VkCommandBuffer& cmd) {
// (hookshot) One cause of those is gone: the dry pass did not mark the targets of a clear (NOP_CLEAR_COLOR in replay()). With
// that, Castle Town's market and eight other places showed no black frame on 3 to 8 threads; the Kakariko walk was not run
// again, so it stays off. On a 9950X3D the replay's wall time in the market goes from 10.9 ms a frame to 7.75 on 3 threads.
int par_threads() {
static const int n = std::clamp(getenv("RX_VK_PARALLEL") ? atoi(getenv("RX_VK_PARALLEL")) : 0, 0, 8);
// (Triforce) RX_VK_PARALLEL_AUTO=<n> (2 to 8): the parallel replay on <n> threads where it is the faster of the two, measured
// as the game runs. On three threads it is faster where the replay is the frame's limit and slower where the GPU is: at the
// Castle Town save 67.1 fps against 58.8 (RTX 4070 SUPER, 2560 x 1440, windowed), on a tour of Hyrule Field, Kakariko and
// Lake Hylia 59.5 and 61.9 against 64.8 and 66.7 (its recordings done sooner, the game's thread only waits longer for the
// GPU, and the dry pass and the hand-over are not free); the flicker counts of the frame log were the same either way.
// par_tune_present tries the other way for a moment every so often and keeps the one whose frames are shorter.
// RX_VK_PARALLEL=<n> still means always, as before.
// EXPERIMENTAL, off unless asked for: its first runs (2026-11-11) gained nothing, 54.7 fps against 58.9 standing in Castle Town
// and 60.4 against 61.7 on the tour. The frame time of a scene with a crowd moves by 2 ms within seconds (one trial read 18.59
// and then 16.44 ms for the same way), more than the difference being measured, so the trials decide on noise
int par_threads_max() {
static const int n = [] {
if (const char* e = getenv("RX_VK_PARALLEL")) return std::clamp(atoi(e), 0, 8);
if (const char* e = getenv("RX_VK_PARALLEL_AUTO")) return std::clamp(atoi(e), 0, 8);
return 0;
}();
return n;
}
bool par_auto() {
static const bool v = !getenv("RX_VK_PARALLEL") && par_threads_max() >= 2;
return v;
}
bool par_auto_on = false; // (the replay thread's: the parallel replay is the one in use now)
int par_threads() {
const int n = par_threads_max();
return par_auto() && !par_auto_on ? 0 : n;
}
/// At each present (the replay thread): the tuner. Every kEvery presents it times kTake frames as they are, kTake the other way
/// (after kSettle to settle) and kTake as they were again, and changes over when the other way's mean frame was at least 4%
/// shorter than both: a scene that changed under the trial does not pass for a gain. Frames over 60 ms (a load) are left out
void par_tune_present() {
if (!par_auto()) return;
constexpr int kEvery = 900, kTake = 80, kSettle = 24;
static auto last = std::chrono::steady_clock::now();
const auto now = std::chrono::steady_clock::now();
const double ms = std::chrono::duration<double, std::milli>(now - last).count();
last = now;
static int phase = 0, n = 0, cnt[3];
static double sum[3];
static int64_t frames = 0, next_trial = 600, st_trials = 0, st_changes = 0;
frames++;
if (phase == 0) {
if (frames < next_trial) return;
phase = 1, n = 0;
sum[0] = sum[1] = sum[2] = 0, cnt[0] = cnt[1] = cnt[2] = 0;
return;
}
const int k = phase - 1;
n++;
if (n > (phase == 1 ? 0 : kSettle) && ms <= 60.0) sum[k] += ms, cnt[k]++;
if (n < (phase == 1 ? kTake : kSettle + kTake)) return;
n = 0;
if (phase == 1) {
par_auto_on = !par_auto_on, phase = 2;
} else if (phase == 2) {
par_auto_on = !par_auto_on, phase = 3;
} else {
phase = 0, st_trials++;
const bool ok = cnt[0] >= kTake * 3 / 4 && cnt[1] >= kTake * 3 / 4 && cnt[2] >= kTake * 3 / 4;
const double a = cnt[0] ? sum[0] / cnt[0] : 0, b = cnt[1] ? sum[1] / cnt[1] : 0, c = cnt[2] ? sum[2] / cnt[2] : 0;
const bool better = ok && b < std::min(a, c) * 0.96;
if (better) par_auto_on = !par_auto_on, st_changes++;
next_trial = frames + (better ? kEvery : kEvery * 2);
if (better || st_trials <= 8 || st_trials % 20 == 0)
logf("vk: parallel replay, trial %lld: %s %.2f ms a frame, the other way %.2f, %s again %.2f: %s (%lld changes so far)",
(long long)st_trials, par_auto_on != better ? "parallel" : "serial", a, b, par_auto_on != better ? "parallel" : "serial", c,
better ? (par_auto_on ? "parallel from now on" : "serial from now on") : (ok ? "as it was" : "not measured (a load)"),
(long long)st_changes);
}
}
struct ParPool {
std::mutex mu;
std::condition_variable cv, done;
@@ -1531,6 +1603,8 @@ const uint8_t* replay_handle(VkCommandBuffer& cmd, const uint8_t* h, bool may_st
si.pCommandBufferInfos = cb;
std::lock_guard lk(dev.present_mu);
queue_flush_locked();
VkSemaphoreSubmitInfo bind_wait; // (Triforce: after the memory of the mirrors' new pieces is bound, vk_memory.cpp)
if (memory_mirror_bind_wait(&bind_wait)) si.waitSemaphoreInfoCount = 1, si.pWaitSemaphoreInfos = &bind_wait;
const VkResult res = vkQueueSubmit2(dev.queue, 1, &si, j->r->fence);
j->r->submitted = res == VK_SUCCESS;
if (res != VK_SUCCESS) logf("vk: segment submit %llu failed (%d)", (unsigned long long)j->r->value, (int)res);
@@ -2559,6 +2633,7 @@ uint32_t crc32(const uint8_t* p, size_t n, uint32_t c = 0xFFFFFFFFu) {
/// closed (issue 1275: captures kept 25 -> 6527, staging 256 -> 1408 MB). Now the report once (a thread that sees the loss
/// too waits for it, instead of ending the process before it is written), then the process ends as replay_fatal does
[[noreturn]] void device_lost() {
memory_trial_device_lost(); // (Triforce: with the memory handling on trial on this card: off from the next start)
static std::once_flag once;
std::call_once(once, checkpoints_report);
replay_fatal("the GPU device was lost (VK_ERROR_DEVICE_LOST): the driver stopped or reset the GPU, and nothing sent "
@@ -2837,7 +2912,8 @@ void status_tick() {
std::string dir(exe, n);
FILE* f = fopen((dir.substr(0, dir.find_last_of("\\/") + 1) + "triforce_frames.csv").c_str(), "w");
if (f) fprintf(f, "frame,ms,pipe_waits,pipe_wait_ms,left_out,translate_ms,uploads,upload_mb,textures,memsync_ms,pipelines_ms,"
"uploads_ms,programs_ms,slot_wait_ms,gpu_behind_ms,draw_ms,desc_ms,cmds_ms,tex_lookup_ms,textures_gone\n");
"uploads_ms,programs_ms,slot_wait_ms,gpu_behind_ms,draw_ms,desc_ms,cmds_ms,tex_lookup_ms,textures_gone,"
"dummies,draws\n");
return f;
}();
if (trace && last_ns) {
@@ -2851,12 +2927,17 @@ void status_tick() {
const auto dp = [](int i) { return (prof_ns[i] - l_prof[i]) / 1e6; };
static uint64_t l_gone;
const uint64_t gone = texture_destroy_generation();
fprintf(trace, "%llu,%.2f,%lld,%.2f,%lld,%.1f,%lld,%.2f,%zu,%.2f,%.2f,%.2f,%.2f,%.2f,%.2f,%.2f,%.2f,%.2f,%.2f,%llu\n",
static int64_t l_dummy, l_draws; // (Triforce: the bindings that sampled the dummy, and the draws, this frame)
const int64_t dummy = draw_dummy_textures();
int64_t draws_now = 0, sk_now = 0, di_now = 0, pl_now = 0;
draw_stats(&draws_now, &sk_now, &di_now, &pl_now);
fprintf(trace, "%llu,%.2f,%lld,%.2f,%lld,%.1f,%lld,%.2f,%zu,%.2f,%.2f,%.2f,%.2f,%.2f,%.2f,%.2f,%.2f,%.2f,%.2f,%llu,%lld,%lld\n",
(unsigned long long)frames, (now_ns - last_ns) / 1e6, (long long)(pw - l_pw), pwms - l_pwms, (long long)(ps - l_ps),
tr - l_tr, (long long)(up - l_up), (upb - l_upb) / 1048576.0, texture_count(), dp(PROF_MEMSYNC), dp(PROF_PIPE),
dp(PROF_UPLOAD), dp(PROF_PROGRAM), dp(PROF_SLOTWAIT), (st_wait_ns - l_wait) / 1e6, dp(PROF_DRAW), dp(PROF_DESC),
dp(PROF_CMDS), dp(PROF_TEXGET), (unsigned long long)(gone - l_gone));
l_gone = gone;
dp(PROF_CMDS), dp(PROF_TEXGET), (unsigned long long)(gone - l_gone), (long long)(dummy - l_dummy),
(long long)(draws_now - l_draws));
l_gone = gone, l_dummy = dummy, l_draws = draws_now;
if (frames % 60 == 0) fflush(trace);
l_ps = ps, l_pw = pw, l_pwms = pwms, l_up = up, l_upb = upb, l_tr = tr, l_wait = st_wait_ns;
std::memcpy(l_prof, prof_ns, sizeof l_prof);
@@ -2964,6 +3045,7 @@ void do_present(const nvn_tex* t, const int crop[4]) {
full_barrier(r.cmd);
presents++;
presents_now = presents;
par_tune_present(); // (Triforce: RX_VK_PARALLEL_AUTO)
wide_sides_tick();
if (presents == 1) hang_watch_start();
{ // (EvilBoyce, diagnostics) RX_VK_WATCH_CPU=<present>:<gpu address>[,...] (hex addresses): from that present on, the
@@ -4178,7 +4260,7 @@ bool replay_start() {
VkSemaphoreCreateInfo si{VK_STRUCTURE_TYPE_SEMAPHORE_CREATE_INFO};
vkCreateSemaphore(dev.device, &si, nullptr, &f.acquired);
}
if (par_threads() >= 2 && !init_pools_make(pi)) return false; // (last: nothing after it fails and leaves them made)
if (par_threads_max() >= 2 && !init_pools_make(pi)) return false; // (last: nothing after it fails and leaves them made)
logf("vk: replay ready (%s; push descriptors %s (%u), extended dynamic state 3 %s, custom border colours %s)",
dev.offscreen ? "offscreen" : "window", dev.push_descriptor ? "yes" : "no", dev.max_push_descriptors,
dev.eds3_blend ? "yes" : "no", dev.custom_border_color ? "yes" : "no");

View File

@@ -241,7 +241,21 @@ std::unordered_map<uint64_t, std::vector<Pooled>> target_pool; // by pool_key_
uint64_t pool_bytes, pool_n, st_pool_reused, st_pool_made, st_pool_destroyed;
bool pool_pressed; // (VRAM near what the driver allows: texture_frame's budget)
bool compact_on() { // (hookshot, RX_VK_COMPACT=1: the textures in a pool of their own, compacted: compact_step)
static const bool v = getenv("RX_VK_COMPACT") && atoi(getenv("RX_VK_COMPACT")) != 0;
// (Triforce) on by default on NVIDIA cards (RX_VK_COMPACT=0: off; =1: on, any card). Measured there: an RTX 4070 SUPER
// played with it since 2026-11-10 (a 584,000-present session, 132 compactions, no fault; 85 -> 80.6 fps after a six-area
// tour against 81 -> 64 without), and with the allowance held to 7300 MB (RX_VK_TEST_ALLOWED_MB, an 8 GB card's) a tour of
// Hyrule Field, Kakariko, Lake Hylia and Kokiri peaked at 7165 MB of VRAM against 8565 without (over the allowance in 2 of
// 12 reports against 11) at 69 fps against ~64. On an 8 GB card what is over the allowance is paged to system memory, and
// the textures and render targets evicted to get back under it are made and uploaded again, 58 to 190 ms a frame (an
// RX 5700 XT's and an RTX 3060's logs, 2026-11-11). Not measured on AMD or Intel: as it was there until someone does
// (Triforce, later that day) and on trial on the other makes' cards: memory_trial_on (vk_memory.cpp), which turns it off by
// itself on a PC where a session with it loses the GPU or two end in a crash
static const bool v = [] {
if (const char* e = getenv("RX_VK_COMPACT")) return atoi(e) != 0;
const bool on = memory_trial_on();
if (on) logf("vk: the textures' VRAM is compacted (RX_VK_COMPACT=0: off)");
return on;
}();
return v;
}
uint64_t pool_cap() {
@@ -1297,6 +1311,7 @@ struct UpSlow { int64_t ns; uint32_t w, h, layers, nvn; int route; uint64_t byte
std::vector<UpSlow> up_slowest;
std::mutex up_mu; // (uploads may come from a parallel replay's threads)
std::atomic<int64_t> frame_upload_ns{0}; // (this frame's time in upload(), every thread's)
std::atomic<int> frame_astc_admitted{0}; // (Triforce: this frame's new ASTC textures asked about so far: upload_defer)
std::atomic<int64_t> st_deferred{0}, st_deferred_frame{0};
void upload_frame_report() {
std::lock_guard lk(up_mu);
@@ -1589,11 +1604,13 @@ bool upload_inner(Texture& tex, const Ranges* dirty) {
/// What the CPU wrote of a texture's storage since gen, as byte ranges from its start. A texture in a virtual
/// (sparse) pool is looked at page by page through its mapping, and is all dirty when its mapping changed.
bool texture_dirty(Texture& tex, uint32_t gen, Ranges& out) {
/// same_ok (Triforce): a capture's stamp of a page with the bytes of its last copy is no write (vk_memory.cpp page_gen_tex): only
/// for an uploaded texture's "written since my upload?"
bool texture_dirty(Texture& tex, uint32_t gen, Ranges& out, bool same_ok = false) {
out.clear();
constexpr uint64_t kVirtual = 1ull << 40, kVPage = 1ull << 16;
if (tex.gpu < kVirtual) {
memory_written_runs(tex.guest, tex.guest_size, gen, out);
memory_written_runs(tex.guest, tex.guest_size, gen, out, same_ok);
return !out.empty();
}
// (the page walk only when the GPU mappings changed: the terrain's sparse arrays span over 1 GB, 64 KB pages,
@@ -1661,7 +1678,7 @@ bool texture_dirty(Texture& tex, uint32_t gen, Ranges& out) {
const size_t remaps = out.size();
for (const Texture::Run& r : tex.runs) {
in_run.clear();
memory_written_runs(r.guest, r.n, gen, in_run);
memory_written_runs(r.guest, r.n, gen, in_run, same_ok);
for (const auto& [lo, hi] : in_run) {
if (out.size() > remaps && out.back().second == r.off + lo) out.back().second = r.off + hi;
else out.push_back({r.off + lo, r.off + hi});
@@ -1693,6 +1710,14 @@ void destroy_later(Texture& tex) {
}
d.memory = tex.sparse_chunks;
dead.push_back(std::move(d));
if (tex.twin3d) { // (Triforce: its one-slice 3D copy goes with it)
Dead t{tex.last_value, tex.twin3d, tex.twin3d_alloc, {}, {}};
for (auto& kv : tex.twin3d_views)
if (kv.second) t.views.push_back(kv.second);
dead.push_back(std::move(t));
tex.twin3d = VK_NULL_HANDLE, tex.twin3d_alloc = nullptr;
tex.twin3d_views.clear();
}
total_bytes -= std::min(total_bytes, tex.bytes + tex.pad);
}
@@ -2175,6 +2200,7 @@ VkCommandBuffer upload_command_buffer() {
}
bool texture_uploads_recorded() {
if (memory_rb_refresh(up_cmd)) up_used = true; // (PR 430: readback pages from guest memory, last of the uploads)
memory_mirror_binds_flush(); // (Triforce: the memory of the mirrors' new pieces, bound before this recording is submitted)
memory_table_flush(); // (vk_memory.cpp: the page table's changes, after this recording's mirror copies)
if (up_used) full_barrier(up_cmd); // (before the recording that reads them)
return up_used;
@@ -2315,6 +2341,13 @@ namespace {
bool upload_defer(const Texture& tex) {
static const int64_t budget_ns = (int64_t)(getenv("RX_VK_UPLOAD_BUDGET_MS") ? atof(getenv("RX_VK_UPLOAD_BUDGET_MS")) : 40.0) * 1000000;
if (!budget_ns || !upload_defer_ok || tex.uploaded || !tex.astc || tex.gpu_written) return false;
// (Triforce) and the first RX_VK_UPLOAD_MIN_ASTC of a frame (24) are never left for later. The budget counts every upload of
// the frame, and a frame whose other uploads took it all left every new ASTC texture on the placeholder: on a card at its
// VRAM allowance the render targets evicted and made again are uploaded from memory on the CPU, 58 to 190 ms a frame for
// frames on end (an RX 5700 XT's log, 2026-11-11: 8,586 textures left for later in one session), and the materials stayed
// flat white or blue for as long as that went on. An ASTC upload is decoded on the GPU: its part of such a frame is small
static const int min_astc = getenv("RX_VK_UPLOAD_MIN_ASTC") ? std::max(0, atoi(getenv("RX_VK_UPLOAD_MIN_ASTC"))) : 24;
if (frame_astc_admitted.fetch_add(1, std::memory_order_relaxed) < min_astc) return false;
if (frame_upload_ns.load(std::memory_order_relaxed) < budget_ns) return false;
st_deferred.fetch_add(1, std::memory_order_relaxed), st_deferred_frame.fetch_add(1, std::memory_order_relaxed);
return true;
@@ -2402,7 +2435,7 @@ Texture* texture_touch(Texture* tex, bool for_sampling) {
"%llu)", tex->id, (unsigned long long)tex->gpu, tex->width, tex->height, tex->layers, tex->nvn_format,
(unsigned long long)frame_no, (unsigned long long)tex->last_written);
}
if (tex->uploaded && !gpu_dirty && !texture_dirty(*tex, since, dirty)) return tex;
if (tex->uploaded && !gpu_dirty && !texture_dirty(*tex, since, dirty, !tex->gpu_written)) return tex;
const uint32_t gen = memory_generation();
// (storage render targets took last, which the CPU has not written since: nothing to upload, the memory holds
// nothing the GPU's images did not replace. The game's transient heaps move with the dynamic resolution, and a
@@ -2488,6 +2521,35 @@ Texture* texture_touch(Texture* tex, bool for_sampling) {
// (hookshot) a BC3 image whose last upload failed waits before the next try: its upload stages the whole ASTC source (some
// 200 MB for a terrain array), not to be repeated every submission while the memory it needs is not there
if (tex->bc && !tex->uploaded && tex->bc_retry_frame > frame_no) return tex;
// (Triforce, RX_VK_STAMP_SRC=1, a diagnostic: a texture of 1 MB or more uploaded again: who wrote its first dirty page (the
// write watch 1, a capture 2, else a caller of memory_stamp, placed by memory_stamp's own address), and whether its memory
// holds other bytes than at its last upload at all. 400 lines)
static const bool stamp_src = getenv("RX_VK_STAMP_SRC") != nullptr;
if (stamp_src && tex->uploaded && tex->guest_size >= (1u << 20)) {
static int told;
static std::unordered_map<uint32_t, int> times; // (RX_VK_STAMP_SRC=<n>: only a texture's n-th such upload and later)
static const int from_nth = std::max(1, atoi(getenv("RX_VK_STAMP_SRC")));
const uint64_t h = guest_hash(*tex);
if (++times[tex->id] >= from_nth && told++ < 400) {
uint64_t part = 0;
for (const auto& r : dirty) part += r.second - r.first;
const uint64_t off = dirty.empty() ? 0 : dirty[0].first;
const uint64_t guest = tex->gpu < (1ull << 40) ? tex->guest + off : host->gpu_guest(tex->gpu + off);
uint32_t pg = 0;
uintptr_t anchor = 0;
const uintptr_t who = guest ? memory_stamp_who(guest, &pg, &anchor) : 0;
logf("vk: stamp src: #%u %#llx %ux%u x%u NVN %#x uploaded again (%d) at frame %llu: %llu of %llu KB dirty in %zu ranges%s; bytes %s; "
"page %#llx gen %u (uploaded at %u) by %s%+lld", tex->id, (unsigned long long)tex->gpu, tex->width, tex->height,
tex->layers, tex->nvn_format, times[tex->id], (unsigned long long)frame_no, (unsigned long long)(part >> 10),
(unsigned long long)(tex->guest_size >> 10), dirty.size(), gpu_dirty ? " (a GPU buffer wrote it)" : "",
!tex->verify_hash ? "not hashed before" : h == tex->verify_hash ? "THE SAME as at its last upload" : "changed",
(unsigned long long)guest, pg, since, who == 1 ? "the write watch" : who == 2 ? "a capture" : who ? "memory_stamp" : "unknown",
who > 2 ? (long long)(who - anchor) : 0ll);
}
tex->verify_hash = h;
} else if (stamp_src && tex->guest_size >= (1u << 20)) {
tex->verify_hash = guest_hash(*tex);
}
const auto up0 = std::chrono::steady_clock::now();
const bool up_ok = upload(*tex, partial || sparse_written ? &dirty : nullptr);
{ // (an upload over 15 ms: what it was, 60 of them)
@@ -2565,6 +2627,84 @@ Texture* texture_touch(Texture* tex, bool for_sampling) {
return tex;
}
/// (Triforce, 2026-11-11) A flat texture sampled by a program whose instruction is a 3D sample: a one-slice 3D image with its
/// texels, and a 3D view of that. Vulkan has no 3D view of a 2D image, so such a binding had no view and read zeros (a null
/// descriptor). The console's GPU samples by the texture's own header whatever the instruction says: a flat texture's texel at
/// (u, v), the third coordinate unused, which a one-slice 3D image gives for any w. OoT's water in Zora's River binds one of
/// the game's 4 x 4 textures so (slot 0x102, 44 lookups in 10 s; its ripples ran in slow motion). Small plain textures only:
/// one layer copied, up to 1024 x 1024, not depth, not kept as BC3. Copied again at a lookup after the texture's contents
/// changed (an upload, or the GPU writing it): the lookups are cached by slot, so one the GPU draws every frame is a frame or
/// more behind here. RX_VK_NO_TWIN3D=1: no such view, as before
VkImageView twin3d_view(Texture* tex, VkFormat f, uint32_t level0, uint32_t nlevels, uint32_t layer, const VkComponentMapping& cm) {
static const bool off = getenv("RX_VK_NO_TWIN3D") != nullptr;
if (off || tex->type != VK_IMAGE_TYPE_2D || tex->sparse || tex->bc || tex->samples != VK_SAMPLE_COUNT_1_BIT ||
tex->aspect != VK_IMAGE_ASPECT_COLOR_BIT || is_bc(tex->format) || is_astc(tex->format) ||
(uint64_t)tex->width * tex->height > 1024ull * 1024 || !tex->image)
return VK_NULL_HANDLE;
VkCommandBuffer cmd = VK_NULL_HANDLE;
if (!tex->twin3d) {
VkImageCreateInfo ci{VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO};
ci.imageType = VK_IMAGE_TYPE_3D;
ci.format = tex->format;
ci.extent = {tex->width, tex->height, 1};
ci.mipLevels = tex->levels;
ci.arrayLayers = 1;
ci.samples = VK_SAMPLE_COUNT_1_BIT;
ci.tiling = VK_IMAGE_TILING_OPTIMAL;
ci.usage = VK_IMAGE_USAGE_SAMPLED_BIT | VK_IMAGE_USAGE_TRANSFER_DST_BIT;
ci.flags = VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT; // (the view's format may be another of its class: sRGB or not)
if (!create_image(ci, tex->twin3d, tex->twin3d_alloc, false, false, false)) {
tex->twin3d = VK_NULL_HANDLE, tex->twin3d_alloc = nullptr;
return VK_NULL_HANDLE;
}
cmd = upload_cmd();
VkImageMemoryBarrier2 b{VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2};
b.srcStageMask = b.dstStageMask = VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT;
b.dstAccessMask = VK_ACCESS_2_MEMORY_READ_BIT | VK_ACCESS_2_MEMORY_WRITE_BIT;
b.oldLayout = VK_IMAGE_LAYOUT_UNDEFINED, b.newLayout = VK_IMAGE_LAYOUT_GENERAL;
b.srcQueueFamilyIndex = b.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
b.image = tex->twin3d;
b.subresourceRange = {VK_IMAGE_ASPECT_COLOR_BIT, 0, VK_REMAINING_MIP_LEVELS, 0, 1};
VkDependencyInfo di{VK_STRUCTURE_TYPE_DEPENDENCY_INFO};
di.imageMemoryBarrierCount = 1, di.pImageMemoryBarriers = &b;
vkCmdPipelineBarrier2(cmd, &di);
tex->twin3d_value = ~0ull, tex->twin3d_written = ~0ull;
static int told;
if (told++ < 12)
logf("vk: texture #%u %#llx %ux%u levels %u NVN %#x is sampled as a 3D texture: a one-slice 3D copy of it made", tex->id,
(unsigned long long)tex->gpu, tex->width, tex->height, tex->levels, tex->nvn_format);
}
if (tex->twin3d_value != tex->upload_value || tex->twin3d_written != tex->last_written || tex->twin3d_layer != layer) {
if (!cmd) cmd = upload_cmd();
full_barrier(cmd, "barrier (a flat texture's 3D copy: before)");
std::vector<VkImageCopy> rs;
for (uint32_t l = 0; l < tex->levels; l++) {
VkImageCopy r{};
r.srcSubresource = {VK_IMAGE_ASPECT_COLOR_BIT, l, layer, 1};
r.dstSubresource = {VK_IMAGE_ASPECT_COLOR_BIT, l, 0, 1};
r.extent = {std::max(1u, tex->width >> l), std::max(1u, tex->height >> l), 1};
rs.push_back(r);
}
vkCmdCopyImage(cmd, tex->image, VK_IMAGE_LAYOUT_GENERAL, tex->twin3d, VK_IMAGE_LAYOUT_GENERAL, (uint32_t)rs.size(), rs.data());
full_barrier(cmd, "barrier (a flat texture's 3D copy: after)");
tex->twin3d_value = tex->upload_value, tex->twin3d_written = tex->last_written, tex->twin3d_layer = layer;
}
uint64_t key = mix((uint64_t)f, (uint64_t)level0 << 32 | nlevels);
key = mix(key, (uint64_t)cm.r << 24 | (uint64_t)cm.g << 16 | (uint64_t)cm.b << 8 | cm.a);
const auto it = tex->twin3d_views.find(key);
if (it != tex->twin3d_views.end()) return it->second;
VkImageViewCreateInfo vi{VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO};
vi.image = tex->twin3d;
vi.viewType = VK_IMAGE_VIEW_TYPE_3D;
vi.format = f;
vi.components = cm;
vi.subresourceRange = {VK_IMAGE_ASPECT_COLOR_BIT, level0, nlevels, 0, 1};
VkImageView view = VK_NULL_HANDLE;
if (vkCreateImageView(dev.device, &vi, nullptr, &view) != VK_SUCCESS) view = VK_NULL_HANDLE;
tex->twin3d_views[key] = view;
return view;
}
VkImageView texture_view(Texture* tex, const nvn_tex* t, const nvn_view* v, VkImageViewType type, ViewUse use,
VkFormat* format_out, VkFormat force_format) {
if (!tex) return VK_NULL_HANDLE;
@@ -2615,6 +2755,7 @@ VkImageView texture_view(Texture* tex, const nvn_tex* t, const nvn_view* v, VkIm
else if (type == VK_IMAGE_VIEW_TYPE_2D && nlayers > 1) nlayers = 1;
else if (type == VK_IMAGE_VIEW_TYPE_1D && nlayers > 1) nlayers = 1;
}
int twin_layer = -1; // (Triforce: a flat texture wanted as 3D: the layer its 3D copy is of)
// the shader's type over the image's: what Vulkan allows of them
switch (type) {
case VK_IMAGE_VIEW_TYPE_1D: case VK_IMAGE_VIEW_TYPE_1D_ARRAY:
@@ -2636,7 +2777,11 @@ VkImageView texture_view(Texture* tex, const nvn_tex* t, const nvn_view* v, VkIm
if (type == VK_IMAGE_VIEW_TYPE_2D) nlayers = 1;
break;
case VK_IMAGE_VIEW_TYPE_3D:
if (tex->type != VK_IMAGE_TYPE_3D) return VK_NULL_HANDLE;
if (tex->type != VK_IMAGE_TYPE_3D) {
// (Triforce: a flat texture sampled as a 3D one: its one-slice 3D copy, twin3d_view above)
if (use != ViewUse::Sample) return VK_NULL_HANDLE;
twin_layer = (int)layer0;
}
layer0 = 0, nlayers = 1;
break;
case VK_IMAGE_VIEW_TYPE_CUBE: case VK_IMAGE_VIEW_TYPE_CUBE_ARRAY:
@@ -2675,6 +2820,10 @@ VkImageView texture_view(Texture* tex, const nvn_tex* t, const nvn_view* v, VkIm
nf, (int)f, sw[0], sw[1], sw[2], sw[3], d.swizzle_r, d.swizzle_g, d.swizzle_b, d.swizzle_a,
v && v->set_swizzle ? 1 : 0);
}
if (twin_layer >= 0) {
if (format_out) *format_out = f;
return twin3d_view(tex, f, level0, nlevels, (uint32_t)twin_layer, cm);
}
uint64_t key = mix((uint64_t)use, (uint64_t)type);
key = mix(key, (uint64_t)f << 32 | aspect);
key = mix(key, (uint64_t)level0 << 48 | (uint64_t)nlevels << 32 | (uint64_t)layer0 << 16 | nlayers);
@@ -3948,6 +4097,7 @@ uint64_t preset_texture_budget(uint64_t preset_mb, bool preset_applies, bool vra
void texture_frame(uint64_t completed) {
upload_frame_report();
frame_upload_ns.store(0, std::memory_order_relaxed);
frame_astc_admitted.store(0, std::memory_order_relaxed);
if (const int64_t d = st_deferred_frame.exchange(0, std::memory_order_relaxed)) {
// (the views and descriptor sets resolved to the placeholder this frame go stale, as when textures go: the next frame
// looks those textures up again, and uploads them)
@@ -4129,6 +4279,7 @@ void texture_frame(uint64_t completed) {
}
if (budget < evict_to) evict_to = 0; // (hookshot, RX_VK_COMPACT: the driver's limit asks for more: 7/8 of that, as before)
if (frame_no % 600 == 0) {
memory_trial_tick(); // (Triforce: the memory handling on trial on this card, vk_memory.cpp)
vma_log_heaps();
vma_log_image_blocks();
{

View File

@@ -90,6 +90,13 @@ struct Texture {
uint64_t wb_value = 0; // (the submission whose own commands write its texels into its memory; 0: none)
uint64_t pool_key = 0; // (a render target's image: its create info's key in the pool it goes to when the texture does)
std::unordered_map<uint64_t, VkImageView> views;
// (Triforce) a flat texture a program samples as a 3D one: its one-slice 3D copy (vk_texture.cpp twin3d_view), the layer it
// was copied from and the texture's contents it was copied at
VkImage twin3d = VK_NULL_HANDLE;
VmaAllocation twin3d_alloc = nullptr;
uint32_t twin3d_layer = 0;
uint64_t twin3d_value = ~0ull, twin3d_written = ~0ull;
std::unordered_map<uint64_t, VkImageView> twin3d_views;
};
/// Makes texels [x, x + w) x [y, y + h) of level `level`, layers [first, first + count), of a sparse texture resident

View File

@@ -182,7 +182,40 @@ bool image_compact_pass_end(uint64_t* freed_bytes, uint32_t* freed_blocks) {
return compact_over(freed_bytes, freed_blocks);
}
bool create_image_inner(const VkImageCreateInfo& ci, VkImage& image, VmaAllocation& allocation, bool dedicated, bool target, bool textures);
/// (Triforce) An image that takes over 3 ms to make: what it was, how long, and whether its pool took a new block for it (60
/// lines). A player's session had frames of 50 to 150 ms in play that were all "texture lookups", 24 render targets made in one
bool create_image(const VkImageCreateInfo& ci, VkImage& image, VmaAllocation& allocation, bool dedicated, bool target, bool textures) {
const auto blocks = [&]() -> uint32_t {
VmaPool pool = textures ? texture_pool : target ? target_image_pool : image_pool;
if (!pool) return 0;
VmaStatistics st{};
vmaGetPoolStatistics(vma, pool, &st);
return st.blockCount;
};
const uint32_t before = blocks();
const auto t0 = std::chrono::steady_clock::now();
const bool ok = create_image_inner(ci, image, allocation, dedicated, target, textures);
const double ms = std::chrono::duration<double, std::milli>(std::chrono::steady_clock::now() - t0).count();
static std::atomic<int> told{0};
static std::atomic<int64_t> n{0}, slow{0};
static std::atomic<int64_t> slow_us{0};
n++;
if (ms > 3.0) {
slow++, slow_us += (int64_t)(ms * 1000);
if (told++ < 60) {
uint64_t used = 0, allowed = 0, block_free = 0;
vram_usage(&used, &allowed, &block_free);
logf("vk: an image took %.1f ms to make: %ux%u x%u levels %u format %d (%s)%s; its pool's blocks %u -> %u; VRAM %llu of %llu "
"MB, %llu MB free in the blocks; %lld of %lld images so far took over 3 ms (%.0f ms in all)", ms, ci.extent.width,
ci.extent.height, ci.arrayLayers, ci.mipLevels, (int)ci.format, textures ? "a texture" : target ? "a render target" : "other",
ok ? "" : ", NOT made", before, blocks(), (unsigned long long)(used >> 20), (unsigned long long)(allowed >> 20),
(unsigned long long)(block_free >> 20), (long long)slow.load(), (long long)n.load(), slow_us.load() / 1000.0);
}
}
return ok;
}
bool create_image_inner(const VkImageCreateInfo& ci, VkImage& image, VmaAllocation& allocation, bool dedicated, bool target, bool textures) {
VmaAllocationCreateInfo ai{};
ai.usage = VMA_MEMORY_USAGE_AUTO_PREFER_DEVICE;
// (in VRAM or not at all: an image VMA puts in system memory when VRAM is full is read over PCIe every frame,
@@ -278,6 +311,23 @@ bool create_device_buffer(uint64_t size, VkBufferUsageFlags usage, VkBuffer& buf
if (dedicated) ai.flags |= VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT;
return vmaCreateBuffer(vma, &bi, &ai, &buffer, &allocation, nullptr) == VK_SUCCESS;
}
/// (Triforce) Device memory for a piece of a sparse buffer (vk_memory.cpp's mirrors in pieces): size bytes at that alignment,
/// of a type in type_bits, within the driver's budget; the memory and the offset in it to bind
bool vma_piece_alloc(uint64_t size, uint64_t alignment, uint32_t type_bits, VmaAllocation& allocation, VkDeviceMemory& memory,
uint64_t& offset) {
VkMemoryRequirements req{};
req.size = size, req.alignment = alignment, req.memoryTypeBits = type_bits;
VmaAllocationCreateInfo ai{};
ai.requiredFlags = VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT;
if (dev.memory_budget) ai.flags = VMA_ALLOCATION_CREATE_WITHIN_BUDGET_BIT;
VmaAllocationInfo info{};
if (vmaAllocateMemory(vma, &req, &ai, &allocation, &info) != VK_SUCCESS) return false;
memory = info.deviceMemory, offset = info.offset;
return true;
}
void vma_piece_free(VmaAllocation allocation) {
vmaFreeMemory(vma, allocation);
}
/// (every heap: what VMA has in blocks and allocations there, what the process uses of it, its budget; one line)
/// The image pools: their blocks, the images in them, and the free ranges between them (every 600 presents, with the heaps)
void vma_log_image_blocks() {

View File

@@ -78,7 +78,7 @@ def main():
waits["%s: %s" % (th, guest_frame(frames))] += 1
if not is_game(th):
vk["%s %s: %s" % (th, "runs" if r else "waits", frames[0] if not r else
next((f for f in frames if f.startswith("hookshot_vk:")), frames[0]))] += 1
next((f for f in frames if f.startswith(("triforce_vk:", "hookshot_vk:"))), frames[0]))] += 1
for k, c in waits.most_common(top):
print(" %5.1f%% %s" % (100.0 * c / max(1, len(idle)), k))
print(" (renderer threads then)")

View File

@@ -29,8 +29,8 @@ def load_map(path, base):
# The modules whose frames are Hookshot's own code (the game and the runtime, the renderer): Windows, then Linux
GAME_MODS = ("hookshot.exe", "hookshot")
VK_MODS = ("hookshot_vk.dll", "hookshot_vk.so")
GAME_MODS = ("Triforce.exe", "hookshot.exe", "hookshot") # (Triforce's names first; upstream's kept for its samples)
VK_MODS = ("triforce_vk.dll", "hookshot_vk.dll", "hookshot_vk.so")
RUN_MODS = GAME_MODS + VK_MODS
@@ -53,7 +53,7 @@ def load_symbols(folder=None):
Windows build, the binaries of the Linux one"""
folder = folder or os.environ.get("RX_MAPS", BUILD)
maps = {}
for mod in ("hookshot_vk.dll", "hookshot.exe"):
for mod in ("triforce_vk.dll", "Triforce.exe", "hookshot_vk.dll", "hookshot.exe"):
mp = os.path.join(folder, mod[:-4] + ".map")
if os.path.exists(mp):
maps[mod] = load_map(mp, 0x180000000 if mod.endswith(".dll") else 0x140000000)

View File

@@ -7,7 +7,8 @@ param(
[Parameter(Mandatory = $true)][string]$Tag,
[string]$Deps = 'D:\src\release\triforce-deps',
[string]$Out = (Join-Path $PSScriptRoot 'out\release'),
[switch]$AllowNoCompiler
[switch]$AllowNoCompiler,
[switch]$AllowNoStateList
)
$ErrorActionPreference = 'Stop'
$repo = Split-Path $PSScriptRoot
@@ -45,6 +46,17 @@ New-Item -ItemType Directory -Force $work | Out-Null
foreach ($n in 'hot_funcs.txt', 'hot_order.txt', 'hookshot_pieces.prof') {
if (Test-Path (Join-Path $repo "work\$n")) { Copy-Item (Join-Path $repo "work\$n") $work }
}
# 3b. the pipeline state list (nx2/pipeline_states.py --out work\pipeline_states.bin <lists from play>): nx2/make_game.py puts it
# beside the game as triforce_pipeline_states_shipped.bin and the first start builds its pipelines before the title. Without it
# every player compiles each pipeline when it is first drawn: the stutter of every first visit (v0.2.0 shipped none: "0 shipped"
# in every log). Hashes and draw state only, no game code.
$states = Join-Path $repo 'work\pipeline_states.bin'
if (Test-Path $states) {
Copy-Item $states $work
"work: pipeline state list, {0:N0} pipelines" -f (((Get-Item $states).Length - 12) / 528)
} elseif (-not $AllowNoStateList) {
throw "no work\pipeline_states.bin: players would compile every pipeline in play. Make it with nx2/pipeline_states.py --out (or -AllowNoStateList)"
}
if (Test-Path (Join-Path $repo 'work\image')) { robocopy (Join-Path $repo 'work\image') (Join-Path $work 'image') /E /NFL /NDL /NJH /NJS /NP | Out-Null }
Add-Type -AssemblyName System.Drawing