diff --git a/docs/architecture.md b/docs/architecture.md index 9fb7060e..2abe159a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -223,8 +223,9 @@ keeps per-core data without locks and relies on that, so the host models it (`ru whose size it uses, is made whole (`gfx_shader.c` `reflect_exact`). `auto` picks by the device-local budget. - Occlusion queries never block the CPU; a result that is not ready counts as visible. - Allocation: Vulkan Memory Allocator. Debugging: Vulkan validation layers, per-pass frame dumps (`NX2NAVI_DUMP`, - `vk_dump.c`), a sampling profiler (`NX2NAVI_PROFILE`, `tools/prof_report.py`) and a flight recorder - (`NX2NAVI_FLIGHT`). RenderDoc cannot capture, because it hides `VK_EXT_external_memory_host` from the application. + `vk_dump.c`), a sampling profiler (`NX2NAVI_PROFILE`, `tools/prof_report.py`), a flight recorder + (`NX2NAVI_FLIGHT`) and bug captures, which a player's F8 writes and a test run starts from (`bugcap.c`, + [bug-capture.md](bug-capture.md)). RenderDoc cannot capture, because it hides `VK_EXT_external_memory_host` from the application. Maxwell behaviour the back end has to match: [maxwell.md](maxwell.md). diff --git a/docs/bug-capture.md b/docs/bug-capture.md new file mode 100644 index 00000000..3120a6a1 --- /dev/null +++ b/docs/bug-capture.md @@ -0,0 +1,120 @@ +# Bug captures + +A bug capture records where and how the game was when a player saw something wrong, so that the bug can be looked for +again at that place instead of somewhere else. The player presses **F8**; a test run then starts from what the press +wrote. Code: `runtime/bugcap.c`, `tools/capture_run.py`. Ocarina of Time 1.1.1 (the place and the camera come from the +debug tools, `runtime/debug_tools.c`); on other game versions a capture still has the picture, the timing, the +settings and the save. + +## For the player + +When you see a bug, press **F8** while the game window is in front. About a second later a note at the top of the +screen says *Bug capture 3 saved* with the folder's name. Tell whoever looks into the bug the number ("capture 3") and +what you saw; nothing else is needed. Press it as often as you like: each press is its own capture, and a press while +the one before is still being written is skipped. + +The captures are in the game folder under `logs\captures`, one folder each, named by number and time +(`003-20261113-141502`). *Menu > Open log folder* shows `logs`. A capture is between one and a few megabytes; delete +old ones whenever you like. Nothing leaves your PC: a capture is files on your disk. + +## What a capture holds + +| File | What | +|---|---| +| `capture.txt` | Written last: a folder that has it is complete. `key = value` lines under `[sections]`, see below | +| `frame.png` | The frame on screen as the window got it, the overlay included, without the capture's own note (an HDR picture converted to sRGB) | +| `frames.tsv` | The last 600 presents before the press and the 30 after: frame, interval and replay time in ms | +| `log-tail.txt` | The last 256 KB of the run's log | +| `settings.ini` | Every setting that had a value (from `nx2navi.ini`, the menu or the environment) as `nx2navi.ini` lines, without the private ones (`runtime/cfg_private.h`) | +| `NX2navi-save-