The 0.6 crashes after warps and area changes fixed (no write-back into memory the capture leaves out), invisible objects fixed (occlusion gate), DLSS frame generation flicker fixed, achievements, the renderer built with a play profile, faster translated game code, helper threads judged on settled scenes, memory, shader preparation, audio effects, launcher, controls and Linux fixes.
299 KiB
Hookshot (oot-recomp)
Hookshot is the port's name (as Skybound is TOTKPort's and BlueShell is mkw-recomp's); the maintainer's repository
folder stays oot-recomp. The game builds as Triforce.exe + triforce_vk.dll (triforce + triforce_vk.so on Linux).
A static recompilation of the Switch 2 The Legend of Zelda: Ocarina of Time remake to native x86-64 Windows and Linux:
the game's code lifted to C (NotRexed's a64-kit, Rexcomp's AArch64 kit), the Horizon OS and NVN2 implemented
natively, the GPU work replayed on Vulkan. It is a fork of mkw-recomp (..\mkw-recomp, Mario Kart World), whose
paths it keeps so MKW's fixes apply here.
No game files are in this repository. The dump is read where it lies (work/dump.txt); everything made from it
(modules, image, lifted C, builds, runs) goes to work/, which git ignores.
Status: the game plays; the README's status table says how far. The design, its stages and the lessons carried over from MKW: design.md.
Use
Requirements: Python 3 with pip install -r requirements.txt (lz4, numpy, capstone, unicorn 2.1,
zstandard, and the button-prompt packages); a compiler: on Windows llvm-mingw
(HOOKSHOT_MINGW, or an llvm-mingw folder in the clone), else emsdk's clang at C:\emsdk (or EMSDK) with Visual
Studio's C++ tools; on Linux clang and lld. For the Vulkan back end: distro Vulkan / SPIR-V / VMA headers under
/usr, or HOOKSHOT_VULKAN_HEADERS / HOOKSHOT_SPIRV_HEADERS / HOOKSHOT_VMA_HEADERS, or a CPM package cache
(RX_CPM, else cpm in the clone, else the old caches in mkw-recomp's work/eg or ..\Eglantine\.cache\cpm).
Without those the standalone build stops. CONTRIBUTING.md has the rest.
Run everything with python -I from this folder.
| Command | What |
|---|---|
python -I nx2/nup.py <file.nup> --extract work/dump |
the .nup dump package to work/dump/exefs + romfs (newest title; ZBIC NSOs made plain by nx2/unpack.py) |
python -I nx2/dump.py --dump <folder with exefs/ and romfs/> --set |
what the dump is (Switch 1 or 2, ids, modules, SDK, NVN); --set records it in work/dump.txt |
python -I nx2/lift.py [--write] |
image + discovery + coverage (work/image/coverage.txt); --write emits the C to work/gen |
python -I nx2/census.py --nx2 |
instruction census per module, after the Switch 2 forms |
python -I nx2/test_insn.py [--per 6 --states 12] |
every instruction form the game uses, Unicorn vs lifted C |
python -I nx2/test_leaf.py [--count 3000 --states 4] [--calls] |
random whole functions (or call trees), Unicorn vs recompiled native code on the real image |
python -I nx2/lift.py --standalone --write then python -I nx2/build.py --standalone --jobs 4 |
the standalone game: work/sa/build/hookshot.exe + hookshot_vk.dll |
powershell -File scripts/run-vk.ps1 [-Window] [-Seconds 120] [-Name x] |
a muted test run on Vulkan, with screenshots in work/runs/<name>/shots |
python -I scripts/prof.py <stacks file> |
a profile sampled with HOS_PROFILE=<seconds> + HOS_SAMPLE=<thread> + HOS_SAMPLE_FILE=<stacks file> (the sampler runs only with HOS_PROFILE set), named from the linker maps |
The dump can also come from OOT_DUMP (its folder) or OOT_EXEFS; OOT_WORK moves the work folder.
The built game's own arguments (image.bin, --romfs, --user, --trace, --prepare-shaders) are in the README's
Running the game from the command line.
Scripted test input (HOS_INPUT_SCRIPT and HOS_INPUT_LIVE) is applied before the window-focus check. A log saying
the game window is not in front does not mean those presses were discarded. HOS_HEADLESS and
HOS_WINDOW_NOACTIVATE change window creation, not this input routing. The game must still reach a state that reads
and responds to the supplied controller input.
Physical keyboard and mouse input stays with the foreground window. Physical controllers can also play in the
background when the existing "Controller in background" option or HOS_INPUT_BACKGROUND=1 enables them;
HOS_INPUT_BACKGROUND=0 overrides that option. With HOS_INPUT_EXCLUSIVE set (to any value, 0 too) the script
alone drives the game until 5 s after its last press; without it the player's devices add to the script's presses. It
is not a focus override.
Switches for testing and debugging
The running game reads its switches from the environment or from hookshot_env.txt beside image.bin (one
NAME=VALUE a line, # for notes; HOS_ENV_FILE=<path> reads that file instead). The build reads its own from the
environment. The README has the ones players are asked to try (RX_VK_ASTC_RGBA8, RX_VK_LOW_SPEC,
RX_VK_MOVIE_UPSCALE, RX_VK_SKIP_CODE, HOS_OOT_CHEATS). There are several hundred more, most of them one-off
experiments: grep -rn 'getenv("' host gpu/vk lists them, and the comment where each is read says what it does.
"Set" below means any value, 0 included.
RX_VK_MESH_NOCULL=<prefix,...> turns off the culling in the task shaders whose native code key starts with one of
the prefixes. On a Steam Deck, RX_VK_MESH_NOCULL=2c56dc1006942f74 avoids the same hang without leaving anything out:
that task shader walks a coarse depth grid cell by cell for every meshlet and ends with
visible = (result & 1) | (c3[2320] & 4), bit 4 being the game's own "draw everything". The switch makes that answer
true, and dead code elimination removes the grid walk, so every meshlet is drawn and the rasterizer clips what is off
screen. It costs some GPU time on cards that cull quickly, so it is off unless set. The log says
"culling off, every meshlet drawn" for each task shader it changed.
Running a test
| Switch | What it does |
|---|---|
HOS_HEADLESS (set) |
No window: the renderer draws offscreen, for screenshots and frame dumps |
HOS_WINDOW_SIZE=<w>x<h> |
The window's size in pixels (1280x720 by default, wider for an ultrawide picture; 64 to 16384 a side) |
HOS_WINDOW_NOACTIVATE (set) |
The window opens behind the others and does not take the focus (Windows) |
HOS_FULLSCREEN=1 |
Starts in fullscreen; the Insert menu's Fullscreen row is then left alone |
HOS_ALT_MENU=1 |
(Triforce, 11-22, after Casual Gamer's #dev-fixes post) A lone Alt is left to Windows, as before: it enters the menu loop on the window's thread, which during the start-up screen is the one waiting for the shaders, and the screen froze until a key was pressed. By default the window, which has no menu bar, answers that command itself (host/display.c keymenu_dropped, tests/test_alt_menu.py); Alt+Space's system menu, Alt+Enter, F10 and Alt+F4 are as they were |
HOS_AUDIO=0 |
No sound device is opened (the mixer still runs); scripts/run-vk.ps1 sets it unless -Sound |
HOS_AUDIO_EFFECTS=0 |
The game's plain reverb, delay and biquad filter effects on its mixes and its splitter destinations' biquad filters are accepted and left out, as before they were emulated (the sound unfiltered and at full level: the "Volcano eruption audio bugged" ticket); the I3DL2 reverb still runs. By default they run on the mix buffers in the order the game added them (host/nn_audio.c "mix effects"; tests/test_audio_mix_effects.py) |
HOS_LANGUAGE=<code> |
The game's language for this run, a code from language.txt |
HOS_OUTPUT_RES=<0..3>, HOS_HANDHELD=1, HOS_ASPECT=<ratio> |
Over the options file: the output resolution (0 2048x1152, 1 2560x1440, 2 3840x2160, 3 1920x1080), the handheld profile, a picture wider than 16:9 (2.3889 for 3440x1440; the Ultrawide row's 21:9 is 2.3704, 64:27, and its 32:9 3.5556) |
HOS_DYNRES=0, HOS_REALTIME_STEP=0, HOS_TEXT_SPEED=<0..3> |
Over the options file: Resolution 100% (non-zero: Auto), Game speed Per frame (1: Real time), Text speed |
RX_VK_FIRST_START_AUTO=1, RX_VK_FIRST_START_AUTO=<MB> |
(Triforce, 11-22, the performance audit's PRESENT-46, after Source A's; off by default) A first start sized to the card: with no options file, RX_VK_LOW_SPEC not asked and HOS_DYNRES not set, a weak card starts with the Render resolution row at 50% in place of Auto, or at 33% for an integrated GPU beside 4 processor threads or fewer (gpu/vk/first_start.h, gpu/vk/vk_menu.cpp menu_first_start, called from mkwvk_init once the device is made). Weak is Source A's tier 1: an integrated GPU (a handheld's is one; the SteamDeck variable is not read, it took desktops for handhelds), a card without mesh shaders, or 4.5 GB of video memory or less. Only that row is set: the upscaler, the textures and the output stay, and nothing is saved, so each start chooses again until the player saves options. A number over 1 plays a card of that many MB (the lab: =4096 on a large card). Not set or =0: as before. Off until the owner decides what a first start on a weak card gets; unmeasured (Source A states no gain and tried it on one RTX 4070 Ti). One menu: first start: line says the choice |
HOS_STEP_STEADY=0 |
(Triforce, on by default since the lab's A/B; =0 the mean of the last five as before) The game's real-time step kept steady, after NX2navi's steady step (host/step_steady.h, host/nn_vi.c realtime_step): the mean of the last 12 present intervals without their longest and shortest in place of the mean of the last five (HOS_REALTIME_WINDOW), the paced period itself where that mean is within 3% of it, and what the display showed and the game was not given repaid at a 64th a frame, 10% of the step at most (a quarter second owed at most). A cap the game holds steps it by the period exactly, and a hitch is paid back over most of a second instead of in the next five frames (a 50 ms frame at 240: 200 frames of at most 10% more, where the mean of five gave five steps of 13 ms). Game time still follows the clock |
RX_VK_FG_KEEP=1 |
(Triforce, 11-21, the performance audit's PRESENT-18) Frame generation's images are kept once made, as before. The default lets them go after 120 presents in a row with frame generation off (about two seconds at 60, so a row stepped through keeps them): the built-in interpolation's frames and made-frame sets, which stayed in VRAM until a resize after it was turned off or left for NVIDIA's own, and AMD FSR 4 frame generation's four images of the picture without the HUD once that row is left. The display thread is drained and the GPU idle first; they are made again at the next frame that needs them. The log says how many MB went (gpu/vk/framegen_idle.h, vk_framegen.cpp framegen_idle) |
RX_VK_CAPTURE_TABLES=0 |
(Triforce, 11-21, the upscaler audit's UPS-02) The stored draws' two tables as std::unordered_map, emptied and filled every frame, as before. While NVIDIA DLSS, AMD FSR 4 or AMD FSR 3.1 upscales, every plain draw into the scene stores its positions and is drawn again into the motion vectors; the count of a model's draws and the frame before's draws by their key took a node from the heap for every stored draw every frame (about 1,400 of each in the owner's log, whose status line said 0.65 ms of CPU a frame for the stored draws in all). The default keeps their memory from frame to frame, so a frame the size of the one before takes nothing from the heap, and gives the next frame's list of draws its room at once. The status line's ms CPU a frame is the measure (gpu/vk/capture_tables.h, vk_temporal.cpp capture_motion). Not built or run in the game when it was written |
RX_VK_REDRAW_STATE=0 |
(Triforce, 11-21, the upscaler audit's UPS-03) Every stored draw drawn again into the motion vectors sets the primitive topology, the primitive restart and its index buffer before it draws, as before. The default sets each only where the draw's differs from what the pass has set so far (its first draw sets all three): about 900 draws a frame are drawn again in the owner's log, nearly all of them triangle lists without restart, so two commands a draw are left out, and the index buffer's where two draws in a row bind the same one at the same offset (gpu/vk/redraw_state.h, vk_temporal.cpp capture_motion). Not built or run in the game when it was written |
RX_VK_DLSS_MODE_SLACK=0 |
(Triforce, 11-22, the performance audit's PRESENT-38) DLSS's quality mode found strictly, as before: a render size is a mode's only inside the range NGX answers. Not set: a size outside a range by a rounding (a 64th of the range's largest size, 2 pixels at least: gpu/vk/dlss_checks.h mode_for) is that mode's, so the Render resolution row's 33% at 2560x1440 (854x480, NGX's is 853x480) draws with DLSS and not the game's own upscale; and the feature there is is let go only once a mode took the new size. The lab's dlssstrict phases switch it within a run |
RX_VK_DLSS_MODEL_SETTLE=<frames> |
(Triforce, 11-21, the performance audit's PRESENT-37) The DLSS model row steps K, M, L, NVIDIA's default and applies live: going from K to L made a feature for M on the way, tens of ms each, and NGX keeps a released feature's video memory for some seconds. A new preset is taken once the row has held it for <frames> frames, 30 when not set; the feature already made draws on meanwhile, and with no feature the row's preset is taken at once. 0: at once, as before (gpu/vk/dlss_checks.h PresetSettle, vk_dlss.cpp prepare) |
RX_VK_DLSS_CNN_VRAM=1 |
(Triforce, 11-22, the performance audit's PRESENT-36, after Source A's and Source B's; off by default) On a card with less than 7 GB of video memory the DLSS model row's K (the default) asks NGX for preset E, NVIDIA's last CNN model, and the row reads "CNN (E)" (gpu/vk/upscaler_rows.h cnn_for_vram, gpu/vk/vk_dlss.cpp wanted_preset, dlss_cnn_vram). M, L and NVIDIA's default stay as chosen, RX_VK_DLSS_PRESET goes over it, and cards of 7 GB and more are not touched. Source A measured it on a 6 GB laptop RTX 3050 (1080p, DLSS Performance, one run a preset): 15.75 to 14.20 ms of GPU a frame, NGX's own memory 85 to 58 MB. Off here, as in Source B: preset E ghosts more on grass and thin objects at the smallest render sizes and NVIDIA marks it deprecated, so the picture is the owner's to look at first. A DLSS runtime without E falls back to NVIDIA's default; RX_VK_DLSS_LOG=1 shows the preset NGX took. One vk: NVIDIA DLSS: ... MB of video memory: the K row draws with preset E line says it is in use; RX_VK_TEST_CARD_MB=6144 plays a 6 GB card |
RX_VK_DLSS_FEATURE_MAX=1 |
(Triforce, 11-21, the upscaler audit's UPS-01) NVIDIA DLSS's feature made for the largest render size its quality mode allows, whatever the Render resolution row says, as before. NGX answers that largest size as the output's own, so at a fixed share the feature was made for 2.25 times the pixels it was ever given at Quality (4 at Performance, 9 at Ultra Performance), and the chain's colour, depth and motion images with it; the owner's log has DLSS's own video memory at 1069 MB for such a feature with preset M, where NVIDIA's table has 456 MB at 4K, and NVIDIA's guide says the cost of presets L and M follows the size the feature is initialized for. The default makes a fixed share's feature for its own render size; the row's Auto (the game's dynamic resolution), and any run in which the render size is seen changing under one output, make it for the mode's whole range as before (one feature made again when that is first seen). DLAA's is the output's either way. The feature N made line says which, and the status line's its own ... MB and its images ... MB are the measure (gpu/vk/dlss_feature.h, vk_dlss.cpp prepare). Not built or run in the game when it was written |
RX_VK_DLSS_PREWARM=1 |
(Triforce, 11-22, the performance audit's PRESENT-32, after Source A's: its first step; off by default) NVIDIA DLSS at the output's size takes the scaled quality mode whose range holds that size, and only NVIDIA DLAA the one-size mode (gpu/vk/dlss_checks.h dlaa_feature, gpu/vk/vk_dlss.cpp prepare). With the Render resolution row at Auto the game starts at the output's size and lowers it some frames later: before, a one-size feature and then a second one made in play (Source A's save load-in: 119 ms, then 29.5 ms 17 frames on); with the switch one feature, for its mode's whole range. Off by default because DLSS at full size then draws with the scaled mode's network, not DLAA's: a picture to compare first. The rest of the entry is not built: making the feature, the chain's images and a first evaluation ahead in a light frame (a title or loading screen) needs the first gameplay upscale's sizes and colour kind before it has happened, which only a run with DLSS can settle. tests/test_dlss_prewarm.py runs the decisions over a load-in |
RX_VK_FRAMEGEN_REFRESH=1 |
(Triforce, 11-21, the upscaler audit's UPS-05; off unless set) The Frame generation row's 2x to 8x make no more frames for each of the game's than the display's refreshes that fall in one frame of the game: the game's recent frame time over the display's period, rounded up, a tenth of a refresh forgiven, never more than the row's number and never fewer than the game's own frame. Without it the row's number is made whatever the display shows: the owner's log has 5x on a 165 Hz display with the game near 66 frames a second, 331 frames a second presented, each present call 2.2 to 3.0 ms (0.03 ms without frame generation) and the display thread's line 0 frames shown on time, 1655 late. Auto and AMD FSR's row are not touched. A vk: frame interpolation: N frame(s) for each of the game's line says each change (gpu/vk/framegen_refresh.h, vk_framegen.cpp framegen_record). Not built or run in the game when it was written |
RX_VK_FRAMEGEN=0, RX_VK_FRAMEGEN_MULT=<0..9>, RX_VK_PACE=0, RX_VK_UPSCALE=<0..2> |
No frame generation whatever the menu says; over the options file: the Frame generation row's value (0 Off, 1 Auto, 2 to 8 the multiplier, 9 AMD FSR frame generation: a lab run's pin for each generator; gpu/vk/framegen_rows.h env_row), frame pacing, the upscaling filter |
RX_VK_FG_OWN_MOTION=0 |
(Triforce, FG-4) Frame generation's motion the camera's alone, as before, for comparing. Without it, while NVIDIA DLSS or AMD FSR 4 upscale, the depth and motion frame generation takes (AMD's, NVIDIA DLSS frame generation, FSR 3.1's interpolation) are made from the upscaler chain's frame, with what moves by itself drawn into the motion (gpu/vk/vk_temporal.cpp fg_inputs_from_chain, gpu/vk/vk_fsr3_inputs.cpp chain_motion): also where the gameplay network does not translate on the card and the upscaler draws it in its place (RDNA 3), where they were never made before and AMD's frame generation made no frame |
RX_VK_DLSSG_OWN_MOTION=1 |
(Triforce, 11-22) NVIDIA DLSS frame generation is given the upscaler chain's motion, as before (RX_VK_FG_OWN_MOTION above). By default it is given the camera's alone, from FSR's inputs: with the chain's the owner's flicker of the whole picture while the camera moved came back on 11-22, with frame generation at 2x and DLSS at 50%, and it stayed with the upscaler audit's commits set back; with RX_VK_FG_OWN_MOTION=0 it was gone. DLSS frame generation finds what moves by itself with its own optical flow. AMD's frame generation and FSR 3.1's interpolation keep the chain's (gpu/vk/fg_motion.h, vk_fsr3_inputs.cpp chain_motion). Not built when it was written: the same as the run with RX_VK_FG_OWN_MOTION=0, for DLSS frame generation alone |
RX_VK_DLSSG_CLIP=0 |
(Triforce, 11-20) NVIDIA DLSS frame generation is given the game's own camera matrices, as before, for comparing. Without it they are in the clip space of the depth it is given (FSR's copy, 1 at the near plane): the game's clip z runs from -1 at the near plane to 1 at the far one, and with its matrices that depth read as a clip z put what is far next to the camera, which showed as a flicker of the whole picture while the camera moved (gpu/vk/dlss_math.h depth_clip_projection, gpu/vk/vk_dlssg.cpp frame) |
RX_VK_FG_HUDLESS=0 |
(Triforce, FG-2) No picture without the HUD is taken for AMD's frame generation, so its library makes no frame (the game's frame alone): a test. Without it the gameplay upscale's output is taken before the HUD is drawn into it, sRGB-encoded as the game's last pass encodes it, and given as HUDLessColor (gpu/vk/vk_framegen.cpp framegen_hudless_note, hudless_for); a present without it shows the game's frame alone; with HDR Native or RenoDX's RGBA16F scene AMD's library is not asked and the renderer's own makes the frame, as at 2x |
RX_VK_FRAMEGEN_FINE=0 |
Frame generation's own made frames (Auto, 2x to 8x) the old way: a vector per 16x16 pixels in steps of 4 pixels, a blend of four of them per pixel, a pixel alike in both frames taken as still. Without it, a vector per 8x8 pixels to a fraction of a pixel, settled among its neighbours, and one motion per pixel (gpu/vk/vk_framegen.cpp fine_vectors, shaders/fg_fine_*.comp), which keeps moving straight lines straight and thin lines drawn (tests/test_framegen_lines.py measures both) |
RX_VK_PACE_SMOOTH=0 |
(Triforce, on by default since the lab's A/B; =0 off) The Frame pacing row on the plain present too, without frame generation: with the row on, a picture of the game's that comes sooner than seven eighths of the recent interval after the last one waits for that, its blit on the queue and the queue's lock let go; a late one goes at once, and none waits more than 50 ms (gpu/vk/present_smooth.h, after NX2navi's pace_smooth). Without it the row spaces only frame generation's frames, as before. With RX_VK_PRESENT_THREAD=0 the present is on the game's presenting thread, so a wait also holds that thread's next frame: what that does to the rate under the cap is for a measurement before it is on. A vk: frame pacing line every 1200 pictures says how many waited and how long |
RX_VK_PRESENT_THREAD=1 |
(off by default since the lab showed no gain) (Triforce, on by default; =0 as before) The game's presents go out from a present thread of their own (gpu/vk/present_thread.h, after NX2navi's present thread): the presenting thread records and submits the blit as before (the frame fence, the swapchain's image, the overlays, the bug capture's copy and the frame log's: the same commands in the same order on the queue), then hands the pacing's wait (RX_VK_PACE_SMOOTH) and the present call to that thread and goes on to its next frame; the next present waits first until the one handed over is out, so one is in hand at most. Not with frame generation, NVIDIA DLSS frame generation or AMD Anti-Lag 2 (presents and stages of their own); NVIDIA Reflex's present markers carry their frame's id. The vk: a frame's present line every 120 presents says how many went out from it, the presenting thread's time in the present and how much of it was the wait for the present before, and the pacing's wait and the present call (on whichever thread); the stall line's present is the presenting thread's, with that wait named |
RX_VK_ACQUIRE_FENCE=0 |
(Triforce, on by default; =0 as before) The swapchain's image waited for on the CPU, not on the replay's queue (gpu/vk/vk_replay.cpp present_image, image_free): the acquire signals a fence, the present waits for it, at most 250 ms, before it records anything for the image, and the blit's submit waits for nothing. AMD's Windows driver returns from the acquire at once, the image not yet free: with the window covered (Alt+Tab, another window or OBS in front) the blit's wait for the acquire held the queue, every later submit queued behind it, and the game froze for as long as the cover. An image not free in time is held (vk: swapchain image ... held): no frame is shown, the game goes on, and the next presents look at it again without waiting until it is back. The wait counts as the pacing's in the present line. With DLSS frame generation the acquire's semaphore as before |
RX_VK_SURFACE_RECOVER=0 |
(Triforce, 11-22, the performance audit's PRESENT-45, after Source A's; on by default) A lost window surface is not handled, as before: after VK_ERROR_SURFACE_LOST_KHR (a display driver reset, a monitor change, a remote session) every acquire fails without a word and the picture stays frozen until a restart. Not set, an acquire, a present or a swapchain's creation that answers it lets go of what hangs on the surface, in order: the present thread's present out, the device idle, the overlays' views, the images' semaphores, the swapchain, then the surface (gpu/vk/vk_main.cpp invalidate_lost_surface); and the next present's create_swapchain first makes a surface for the window again with the startup's calls (open_window_surface), only while the window has a size (a minimized window waits), one try each 250 ms at most, with the presents' own queue chosen again for it. A loss seen on the present thread is only noted there and handled by the next present. Nothing changes while no surface is lost (every new statement is behind that result or a missing surface, and the startup's own code is as it was), nor while NVIDIA DLSS frame generation runs (the swapchain is Streamline's). vk: the window's surface is lost and ... is made again lines say it. Never seen on a real driver here, and the window's path is not in the scripted (headless) runs: tests/test_present_surface_lost.py runs the code against a model of a driver that loses its surface at each call |
RX_VK_REFLEX_LIMIT=1 |
(Triforce, off by default) With the NVIDIA Reflex row on and no frame generation, Reflex's sleep holds the Game frame rate cap (the sleep mode's minimum interval) where each frame starts, in place of the game's own wait; and with DLSS frame generation, Streamline's Reflex holds it the same way (gpu/vk/vk_dlssg.cpp pace; options_version 7: the Reflex frame limit row is gone, and this is its only switch until that path has been played on an RTX 40/50 card; vk: dlssg: frame limit: lines say who holds it): one wait a frame, timed by the driver (gpu/vk/vk_reflex.cpp reflex_pace, the rule gpu/vk/dlssg_pace.h's; after NX2navi's low_latency). The game's own wait holds a movie, a frame RivaTuner holds, a window that showed nothing for 200 ms, and the rest of the run once over half of 60 frames came sooner than three quarters of the period, or when the driver refuses the interval. vk: NVIDIA Reflex: frame limit: lines say who holds it; the Full overlay's Frame limit line says NVIDIA Reflex after the rate. |
HOS_PACE_HANDOFF=0 |
The game's own wait paces every frame, with DLSS frame generation's Reflex too and whether RivaTuner Statistics Server runs: the renderer is never asked whether another limiter holds a frame, and RivaTuner gets no limit from the game (host/nn_vi.c pace_handed, gpu/vk/vk_pace.cpp) |
HOS_MEM_QUERY_USED=0 |
(Triforce, 11-19) nn::os::QueryMemoryInfo answers the memory in use as the program and the system's part only, as before. By default it is the program, the heap and every page the game mapped beyond it, at most the total, as Horizon answers (host/hos_mem.c query_used): the game's resource cache sizes what it may still take from it, and without it kept every area it ever loaded (12.5 GB of its 9809 MB after four areas). Needs the census on (HOS_MEM_CENSUS). HOS_MEM_QUERY_SLACK_MB=<MB> (1024 by default): that much less of the game's pages answered as in use, room for its cache beyond a Switch's (our game needs ~3.2 GB of regions at a save load where a Switch leaves ~2.8; with 0 it evicted in every scene) |
HOS_OBJ_CACHE=<n> |
(Triforce) The per-thread cache that finds a guest nn::os object (mutex, event, condition variable ...) by its address (host/nn_os_sync.c obj_lookup_cached, tests/test_obj_cache_size.py): by default 16,384 entries, four ways to a 64-byte set picked by murmur3's finalizer, the oldest way replaced; 256 KB a thread, allocated at its first lookup. The direct-mapped cache missed at nearly every step of the game's walk over some 4,000 mutexes 0x80 apart. n: 256 to 65,536 entries (down to a power of two); 0: the direct-mapped 4,096 entries, as before. Every 10 s the log's sync: object cache line counts the lookups and misses |
HOS_NO_OBJ_CACHE=1 |
No per-thread object cache at all (either kind): every nn::os call looks its object up in the shared table |
HOS_GUEST_MEMFD=0, =1 |
(Linux) The guest window as a memfd's, its pages handed to the GPU as dma-bufs (udmabuf), where /dev/udmabuf can be opened: amdgpu checks every page of a host-pointer import again at each submission, 15-45 ms a submission in Kokiri. (Triforce, 11-21) Also where udmabuf's size_limit_mb cannot be read (Flatpak and other sandboxes hide /sys/module): its default, 64 MB, is assumed and the log says so; only a limit that reads 0 keeps the window anonymous. The log's mem: the guest window is a memfd's line. =0: anonymous memory, host-pointer imports; =1: the memfd all the same |
HOS_MEM_TRACE=1 |
(Triforce, lab) Logs every address region and page call of the game with its size and caller (memtrace: lines; a region's with its call stack) and every QueryMemoryInfo answer |
RX_VK_WB_EXCL_CLIP=0 |
(Triforce, 11-22; on by default with RX_VK_CAP_ONLY_GPU=1) A written binding is copied back to guest memory whole at the submission's end, as in 0.6.0. By default the parts of it in memory the capture leaves out (heap memory between the game's pools inside an imported chunk) are not: the collection does not stamp the CPU's writes there, so the mirror's bytes there are stale, and the write-back diff copied them over the game's newer ones. A pointer table's bare entry (its 64-byte head marked written, gpu/vk/vk_draw.cpp) did so over a heap block 0x18 past its base: the 0.6.0 crashes at area changes in guest 0x803b44e0 (a block header of 0x9ed00000001 or 0x1aa88000013fe), 0x80a30a00 and 0x80a31030 (gpu/vk/wb_excl_clip.h, gpu/vk/vk_memory.cpp gpu_buffer_bind; tests/test_wb_excl_clip.py). The first 20 clipped write-backs are logged (vk: write-back of ... not copied back) |
HOS_FPS_STEADY=0, =1, =2 |
(Triforce, off by default: the Frame pacing row's two Steady values, over them) 1 any rate, 2 steps of the display's refresh: the game's frames paced to a period this PC holds in the scene, never shorter than the Game frame rate cap's (host/pace_steady.h, host/nn_vi.c steady_period). The rate is chosen by probes (pace_steady_probed): 32 frames at the cap, unpaced, the last 24 of them measured, at the start, 2 s after a load, at least every 12 s, and when a quarter of the last 64 frames ran late (2 s after the last probe at the soonest, twice that each time a probe changes nothing, up to 12 s); the rate becomes the first the last three probes' 90th percentile fits in with 2% to spare where that is slower, or the first it fits in with 5% to spare where that is faster. A frame paced slower does more work (the lab's Market: 11.6 ms unpaced, 15.5 ms paced at 55 fps), so the frames' own measure as they run chased the rate down; frames late now only bring a probe on, and the rate is never under what a probe shows the PC holds. HOS_FPS_STEADY_PROBE=0: no probes, the rule below as before. Without probes: what a frame took is its present interval less the longest of the pacing's waits in it (the acquire's, on the presenting thread or another, and the present's hold), and what it needed the interval less all of them (OoT's main thread and Presentation Thread take turns; where the waits add up to the whole interval, the longest: pace_steady_measure); a quarter of the last 64 frames that took more than the period lowers it at once to the first rate their 90th percentile fits in with 2% to spare, and once it has held 3 s since a raise (6 s since a lowering, doubled for each lowering within 30 s of a raise, up to 120 s, and back to 6 s at a load) it rises to the fastest rate the 90th percentile of what the last 512 frames needed fits in with 5% to spare (one rate at a time where the game acquires on another thread). A frame that took over 2.5 times the median of the last 64 (hitches among them), a present interval over 250 ms, and the frames of the 2 s after such a load (the scene is not its measure yet) are left out; the first lowering after a load waits for 128 frames of the new scene and takes their 90th percentile. The acquire's wait starts the frames a period apart (the steady step then gives the game the period as its time step) and the present holds each picture of the game's to the period after the last, less a 64th of it (gpu/vk/present_smooth.h present_smooth_paced_at, with or without the Frame pacing row; not with frame generation). Another limiter holding the frames (RivaTuner, Reflex) puts the cap back while it does. vi: steady frame rate: lines at each change say what the frames needed, and every 5 s what the rule was given (what the frames took and needed at p50 and p90, the present interval's p50, the waits a frame by kind, the frames kept and left out by reason, how many of the last 64 kept were late, and the probes and what the last three took unpaced); the vk: frame pacing line counts the present's holds |
HOS_FPS_STEADY_PROBE=0 |
(Triforce, with HOS_FPS_STEADY or the Steady frame rate row) No unpaced probes: the rate by the frames' own measure as they run, as before test31 (host/pace_steady.h pace_steady_probed, host/nn_vi.c steady_period); the frames' work grows when they are paced slower, and that rule slides down |
HOS_PACE_SPIN=0, HOS_PACE_SPIN=<microseconds> |
(Triforce) The game's own frame wait on the high-resolution timer for the whole wait, as before, which wakes up to about 0.5 ms after the frame's time. By default the timer takes the wait up to 0.6 ms before the frame's time and the rest is yielded away on the clock, so the frame starts on its time (host/pace_wait.h, host/nn_vi.c pace_sleep); a number is another margin. Every 5 s in which frames waited a vi: frame waits line says how long after their time the waits ended, on average and at most |
HOS_RTSS=0 |
RivaTuner Statistics Server is left out entirely: nothing of it is read or loaded and its profile is not touched; a line triforce_rtss_profile.txt holds from a run that did not close is only reported in the log (gpu/vk/rtss_limit.cpp, The options file below) |
HOS_RTSS_DLSSG=1 |
With DLSS frame generation RivaTuner is tried as the limiter too, at the cap times the multiplier in effect, with every safeguard (off: the game's own wait or Reflex, gpu/vk/pace_rule.h says why) |
RX_VK_DEVICE=<n> |
The graphics card listed as vk: device <n> in the log, over the menu's GPU device |
HOOKSHOT_NO_UPDATE_CHECK=1 |
No look for a newer release at the start |
HOS_SINGLE_INSTANCE=0 |
(Triforce) No lock on the game folder: as before, a second copy of the game starts on a folder one already runs from. By default the first holds a lock named after its game folder (host/hos_instance.h), taken before the log is opened; a second copy waits up to 5 s for one that is ending (20 s after the menu's Restart), then says in a message box which process holds the folder and ends (a --prepare-shaders run or HOS_HEADLESS: an @@error line, and the prepare ends as one with no Vulkan). Other folders (the lab's copy, the owner's game) never meet. The log's instance: line says what this run did |
HOS_TRACE=1 |
Every Horizon call logged, as --trace does |
HOS_SAVE_EXPORT_DIR=<folder> |
Where the System tab's Export save rows write their zip, in place of the Downloads folder (set in the environment; tests/test_save_share.py uses it) |
HOS_SAVE_LOCK=0, TRIFORCE_SAVE_LOCK=0 |
(Triforce) The save's lock between the game and Setup: the game holds <user>\save.lock open without sharing from its first save mount to its end, and Setup's Convert saves holds it across its copy (host/save_tx.h save_tx_lock, setup/Guard.cs SaveLock). A running game makes Setup refuse the copy; a game started during one waits for it (30 s at most) before it reads its save. HOS_SAVE_LOCK=0: the game takes none; TRIFORCE_SAVE_LOCK=0: Setup takes none and only looks at the running programs, as before |
RX_BACKEND=<name> |
Unset or vulkan: hookshot_vk.dll; any other value but eden: the WebGPU renderer, when the exe was built with one |
Input for scripted runs
| Switch | What it does |
|---|---|
HOS_INPUT_SCRIPT=<presses> |
Presses timed from the game's first controller read |
HOS_INPUT_LIVE=<file> |
A file the test appends lines of presses to, read every 30 ms; each line's times count from when it is read. A line !cheat <n> sends a Cheats page action, !synclog logs the NVN syncs (!dump, !shots, !rdoc and !flasharm are the WebGPU renderer's) |
HOS_INPUT_FRAME_CLOCK=1 |
The script's time runs at 60 game frames a second instead of the wall clock |
HOS_INPUT_EXCLUSIVE, HOS_INPUT_BACKGROUND, HOS_INPUT_SCRIPT_BACKGROUND (set) |
As above; the last lets every device count while the window is behind another one |
RX_VK_MENU_SCRIPT=<seconds>:<key>,... |
Timed Insert menu keys: INS, UP, DOWN, LEFT, RIGHT, ESC, ENTER, TABL, TABR |
RX_VK_UI_PROMPTS=pad or keys |
The menu's button prompts for a controller or the keys, whatever was used last (screenshots) |
RX_VK_UI_GAME_FONT=0 |
The menu, the counter and the start-up screen in the included Libertinus, not the game's own font |
The presses are <seconds>:<button>[+<button>...][/<ms>], separated by commas, for example 2:A,5.5:LUP/1500,9:ZL+R.
The buttons are A B X Y L R ZL ZR PLUS MINUS LS RS LEFT UP RIGHT DOWN, and the sticks pushed to their edge LUP LDOWN LLEFT LRIGHT RUP RDOWN RLEFT RRIGHT. A press is held for 200 ms unless /<ms> says otherwise. The names are
case-sensitive, and an unknown one is ignored.
Pictures and frames
| Switch | What it does |
|---|---|
RX_VK_SHOTS=<dir> |
A PNG every RX_VK_SHOT_EVERY presents (300) as vk_<present>.png, at RX_VK_SHOT_W x RX_VK_SHOT_H (1280x720) |
RX_VK_FLASH=1 |
The flash detector, with RX_VK_SHOTS and RX_VK_SHOT_EVERY=1: writes the frames around a flash and dumps the next one |
RX_VK_FRAMELOG=<file> |
Every frame shown, at 320x180, while <file>.go exists; python -I scripts/framelog.py <file> finds the flashes |
RX_VK_DUMP=<present>[+<count>][,...] |
Every step of the frame after that present as PNGs, in dump_<present> under RX_VK_DUMP_DIR (or RX_VK_SHOTS, or the current folder); RX_VK_DUMP_STEPS=<lo>-<hi> and RX_VK_DUMP_PROGS=<key>,... narrow it |
RX_VK_PASS_TRACE=1 |
The passes of the last frames, logged at a flash or a dark frame (RX_VK_PASS_TRACE_AT=<n>: every n-th present) |
RX_VK_PROBE=1 or 2 |
The centre texel after every pass: probe_<frame>.txt at a flash (1), or probe_all_<n>.txt at speed (2); python -I scripts/probe.py reads them |
RX_VK_DUMP_FAILED=<dir> |
The native code of every program that does not translate, for nx2/lower_test.py (game data: keep it local) |
Time and profiles
| Switch | What it does |
|---|---|
HOS_PROFILE=<seconds> |
Every interval, the busiest threads in the log; it also starts the samplers below |
HOS_SAMPLE=<thread> + HOS_SAMPLE_FILE=<file> |
One thread's stacks, sampled every millisecond (needs HOS_PROFILE); python -I scripts/prof.py <file> reads them |
HOS_SAMPLE_ALL=<file> |
Every game and renderer thread every 2 ms while <file>.go exists (needs HOS_PROFILE); scripts/crit.py, scripts/vkprof.py and scripts/hotlist.py read it (on Linux with RX_MAPS=<game folder>: they name frames from its hookshot and hookshot_vk.so) |
HOS_THREAD_TIMES=<seconds> |
Every interval, the threads that used over 5% of a core |
HOS_FPS_LOG (set), HOS_PRESENT_TRACE=<csv> |
The game's frame limiter, VRR flags and nominal rate every 300 presents; a CSV line per game present |
RX_VK_FRAME_LOG=<csv> |
A CSV line per present: frame, seconds, frame time in ms |
RX_VK_FRAME_TRACE=1 |
A line a frame in triforce_frames.csv beside the game (the lab's scenarios keep it as frames.csv): present to present, the waits for shaders and pipelines, the uploads, and the replay's parts (memsync_ms ... tex_lookup_ms: the draws' parts are sampled and summed over every thread that records). (Triforce, wp20, gpu/vk/frame_trace.h) Then each frame split as the stall line splits a long one: replay_ms (the submits and the present phase), present_ms, dispatch_ms, qsubmit_ms, par_wait_ms (the replay thread's waits for its helpers' segments), outside_ms (the frame less the replay and the present: the game's own update), game_wait_ms (the game's fence waits), captures_ms (the captures at its submits), wb_wait_ms and wb_held_ms (the waits for write-backs, and their part after the writer's recording was done: RX_VK_WB_WAIT_REC), qs_bg_ms (the queue submits beside a background import), gpu_waits_ms ((Triforce, 11-22, the performance audit's SYNC-27) every thread's time in calls that block on the GPU, RX_VK_GPU_WAITS below). python -I scripts/frame_rank.py <run folder or csv> ranks what made the frames over the 99th percentile and over 1.5x the median by these, per window (the Market, the tour's stays, the loads) |
RX_VK_SETTLE_GATE=1, =2 |
(Triforce, 11-22, off by default; the performance audit's SYNC-29, after Source A's; gpu/vk/settle_gate.h) A CPU read that lets the stopped queues whose waits are met go on (the readback's look, which RX_VK_RB_SETTLE=1 turns on, and the two looks made for a range a texture may be in) takes the order's lock whenever a queue is stopped, and that lock is held through whole replays and presents. With the gate a site looks only while a queue is stopped and the CPU has signalled an event since the last finished look, or a stopped queue waits on an event whose value is read from guest memory; any other met wait was met by a signal in the stream, and the thread that replayed it looked before it let the lock go. 1: the readback's look; 2: the texture sites' too (new ground: those looks order the exposure meter's readback, so 2 needs the lab's flicker count). Unset or 0: every look as before. The RX_VK_LAB_AB knobs settlegate and texgate are 1 and 2 in their phases (rbsettle+settlegate is the pair the audit asks for). The 3000-readback line and the texture catch-ups' 300-call line count the looks made and skipped |
RX_VK_READBACK_LATE=<rule>[,<rule>], RX_VK_LOG_READBACK_RANGES=1 |
(Triforce, 11-22, the performance audit's SYNC-19, after Source A's; gpu/vk/readback_late.h) Ranges the CPU reads back without the wait for their write-back, from what guest memory holds (the last write-back made): a rule is a size in hex (3980: every range of 0x3980 bytes, the culling camera block Source A reads late by default) or newest (a range whose writer is the newest submission handed out: the game cannot have waited for it). Unset: no rule, every readback waits as before, until the lab has run it where the waits are long (a handheld, an AMD iGPU, a weak discrete card); =0: none either. The RX_VK_LAB_AB knob rblate is 3980 in its phases. A late read hands the game the frame before's values, and when the CPU resets a range read late the pending write-back lands over its reset (the exposure meter's flashes): newest can catch that meter, so it is never a default. RX_VK_LOG_READBACK_RANGES=1: with every 3000-readback line, the 12 ranges that waited longest (readbacks, waits, ms, how often their writer was the newest submission, how often read late), to find such ranges on other hardware; nothing is noted without it |
RX_VK_WB_WAIT_REC=1, =2 |
(Triforce, off by default; the handoff's §12.9, gpu/vk/wb_rec_wait.h) A wait for a write-back still on the GPU (a capture's late pages on the game's submitting thread, a read or binding of a page put off) ends once the recording its submission was finished in is done on the GPU, not when the submissions' timeline reaches it: that timeline is held below any submission stopped at an event wait, and the lab's Market had 20-46 ms waits of the game's thread with the GPU 4 submissions behind. Whatever the switch, the wait for the recording comes first and the rest is counted: the stall line's N of them X ms after their writer's recording was done, the late: line's ms of the wait after the recording that finished it was done, the frame trace's wb_held_ms. Off: the captures' late-page wait orders something not known yet (RX_VK_LATE_NEW), so it is tried with the lab's flicker count first. (Triforce, 11-22, the performance audit's SYNC-122, after Source B's) The reads' side: a readback whose write-back is not recorded yet waited on the submissions' timeline with no bound and no second look; it is counted now (the 3000-readback line's second line), and the stall line names the held part by caller (takes, reads, binds, readbacks). The variable is a mode: 1 as above, and such a readback waits in 1 ms slices, looks its writer's recording up between them and ends with it; 2 is the check, where no wait ends earlier and the readback's slices count the part after the recording was done (what 1 would not have waited); unset, 0 or any other text: off, one wait as before. The check of the pages a later write-back changes (the audit's SYNC-101) is not built. RX_VK_TL_REC=1 and the lab knob tlrec ended a capture's wait at a submission's first part, before its burst's write-backs were recorded: they now end it at the recording the submission was finished in, as =1 here does; RX_VK_TL_REC=2 keeps the old lookup |
RX_VK_LATE_INLINE=1 |
(Triforce, 11-22, the performance audit's MEM-80, after Source B's; gpu/vk/late_inline.h; off unless set, not yet run in the game) A late page (one the CPU wrote while a submission still on the GPU writes it back) is waited for and taken again by default (RX_VK_LATE_QUEUE: at the queue's next submit). RX_VK_LATE_NEW=1 (knob latenew) turns four no-wait rules on, each of which brought brightness steps back at the Castle Town save. This turns on the partial rule alone (knob lateinline): a page only part of which a submission on the GPU writes back has its other parts synced from the capture, no wait; pages of pools with no mirror, texture storage, pages written back whole and pages whose write-backs' ranges are not known are waited for as by default. The partial rule, here and under RX_VK_LATE_NEW, now asks which ranges are still on the GPU against the progress the capture read before its copies, not a second read at the take: a write-back done between the two counts as in flight, and its range is not synced from the older copy. RX_VK_LOG_LATE shows the pages waited for |
RX_VK_PASS_TIMING=1 or 2 |
GPU time per pass (2: per program too), logged every 600 presents |
RX_VK_SLOW_LOG=<ms> |
The replay's times for each frame that took longer than this |
RX_VK_STALL_LOG=<ms> or 0 |
On in every run (gpu/vk/stall_watch.h): every 600 of the game's frames a vk: frame times line (the longest frame and how many were over 33, 50, 100 and 250 ms, present to present and in the replay's own time), and for each frame of 50 ms or more a vk: stall line of where its time went: the replay's phases, memory sync's parts, the waits for write-backs still on the GPU (how far ahead, and whether behind a present's blit), the waits for shaders or pipelines, the uploads, the pools imported where they were bound, the GPU behind, the present (its image, fence, call and Reflex's sleep), the game's fence waits, the rest, and a pool's trial in guest memory if one is under way (RX_VK_DEMOTE_QUICK); and the new textures left for the next frame and whether the frame's picture was held (RX_VK_HOLD_MS), whose holds the 600-frame line counts too. At most 3 stall lines a second and 1500 a session. <ms>: the stall line's threshold; 0: neither line |
RX_VK_LOCK_CENSUS=1 |
(Triforce, 11-22, the performance audit's THREAD-68, after Source B's; off unless set) The lock census: who holds the lock a thread waits for. A lock that is busy when a thread comes for it notes the waiter, the thread that held it and how long the wait was, and every 10 s a thread of the census's own logs the 12 pairs that waited longest, as vk: lock census: <waiter> <- <holder> (<lock>) x ms/s (n/s, y us each). Counted: replay_mu, sync_order_mu, held_mu, and in vk_memory.cpp pools_mu, sync_mu and cap_mu. Threads are named by their descriptions (the game's threads and the renderer's own have them). Off, each lock is taken exactly as before; on, a free lock is one try and a store, and only a busy one reads the clock. The holder is read without the lock, so one that lets go at that moment can be misnamed. With RX_VK_LAB_AB naming a knob lockcensus it counts only in that knob's phases. Only the counting of Source B's is here, not its sampling of the holders' stacks (gpu/vk/lock_census.h) |
HOS_STALL_HOST=0 |
(Triforce, 11-22, the performance audit's OS-51, after Source B's; on whenever the stall line is) The stall line names a long frame's time on the replay's side and calls the rest outside the replay and the present. A present that comes RX_VK_STALL_LOG's threshold (50 ms) or more after the last one also logs the host's part of that frame, a vi: stall, the host's part line: the game's file reads, writes, flushes and save commits (how many, MB, their time and the longest one), the discards, zero-fills and decommits of memory it let go and the give-back's passes, the waits for a virtual core summed over the game's threads, the process's page faults (soft and hard together) and its CPU time in the kernel and in its own code. Causes that did not happen are left out; none of the host's causes rules them out. At most 3 lines a second and 1500 in a session, as the stall line. It costs a clock read before and after each counted call and two system calls a present. 0: none of it; so with RX_VK_STALL_LOG=0 (host/stall_host.h, host/mkw_glue.c hos_stall_host_presented) |
RX_VK_SLOW_TAKE_MS=<ms> or 0 |
(Triforce, 20 by default) A submit-time capture take that long or longer (gpu/vk/vk_memory.cpp take_capture): a vk: slow capture take line with where its time went (the marks and late pages, the pools lock, the retires, the stamps, the texture shadow, the buffer kept or given back), the first 200 of them. A Linux RTX 4090 near the Market stuttered with memory sync [capture taken 30 to 110 ms] while the 600-take average said 1.3 ms. 0: none |
HOS_PGO=<file> |
In a run of an RX_PGO=gen build: <file>.reset clears the counters, <file>.dump writes them to <file>. It is read before hookshot_env.txt, so set it in the environment |
The GPU
| Switch | What it does |
|---|---|
RX_VK_VALIDATION (set) |
The Khronos validation layer |
RX_VK_CHECKPOINTS=0 |
No NVIDIA checkpoints (on by default; after a lost device they name the draw it stopped at). (Triforce) The boundaries between a frame's work have markers too: the write-back diff pass, each recording's start, uploads and end, the present's blit and its menu (gpu/vk/checkpoint_kinds.h); the report reads the two stages' last markers together, says what followed the last one reached, and logs the switches, the queue's timeline and the mirrors' piece binds the submits wait for. (P4) Each marking thread numbers its own markers in a ring of its own (15 of 4096; threads after the 15th share a 16th), no atomic shared by the recording threads; the report names a marker's ring and reads the markers around it in that ring |
RX_VK_HANG_DUMP=<file> or 0 |
The hang watch (Windows) is on in every run: once no frame was shown for RX_VK_HANG_SEC seconds (20) with the game's window in front, the top of every thread's stack goes into the log and the whole stacks into triforce_hang.txt in the game folder, once a stall and at most three times a run. <file>: that file instead, and every second counts whatever window is in front. 0: no watch (Triforce) The same report can be asked for at any time: put a file named triforce_hang.txt.now in the game folder (the report's name with .now); within a second the watch takes it away and writes every thread's stack, for a game that goes on showing frames and gets nowhere (a loading screen that never ends). |
RX_VK_NOOPT (set) |
Pipelines built without the driver's optimisations |
RX_VK_MESH_OPT=1 or =0 |
(Triforce) Task and mesh pipelines on AMD. Unset: built without the driver's optimizer on AMD's own drivers (it hung the GPU minutes into Kokiri on an RX 6600) and with it on RADV (without it, the foliage culling's task programs timed out the GPU's ring at the save load on a Steam Deck); the driver's part is made once more on RADV with mesh shaders. =1: with the optimizer everywhere. =0: without it on every AMD driver, RADV too, as before |
RX_VK_GPU_CLOCK=0, =peak, =standard |
(Triforce, Linux) The Steam Deck's GPU held at amdgpu's peak stable power state while the game runs (gpu/vk/vk_gpu_clock.cpp): the Deck's automatic clock dropped while the frame waited on the CPU or a readback, and the GPU work after it ran slow (Kokiri handheld on a Deck OLED: 11.1 to 16.2 fps at the same 15 W; up to 4 W more where the APU was under its cap, so shorter battery life). Unset: only on the Deck's APU, and only while power_dpm_force_performance_level is auto (a level set by hand is left alone). The render node VK_EXT_physical_device_drm names is opened and the state set on an amdgpu context of the renderer's own (no root); the kernel gives the level back at the process's end, a crash too. The log's vk: GPU clock: line says what was done (AMD only). =0: nothing opened; =peak (or =1), =standard: that state on any AMD GPU, whatever the level |
HOS_HALF_RATE_SHADING=1 |
(Triforce, Linux) Keeps RADV_FORCE_VRS_CONFIG_FILE, which Steam's Game Mode gives every game (its Half Rate Shading). By default it is dropped before Vulkan loads when it names a file that exists: while it does, RADV on RDNA 2 and newer puts a forced shading rate into every pipeline's key, whatever the file holds, so the pipelines prepared in Desktop Mode or by the builder all compiled again (over 25 minutes to the title on a Deck). The slider then does nothing for this game, little loss: RADV keeps fragment programs that read their position at full rate, and nearly all of this game's do. RADV_FORCE_VRS is left alone. The log's boot: line says what was done. Can be set in triforce_env.txt |
RX_VK_COMPUTE_PIN=all, lanes or shared |
(Triforce, the performance audit's PIPE-52, after Source A's and Source B's) Which compute programs' pipelines ask for subgroups of 32 lanes (gpu/vk/compute_pin.h, gpu/vk/vk_draw.cpp pin_compute). all, the default on every driver but Mesa's Intel one: every compute program, as before. lanes, the default on Mesa's Intel driver: only the programs that can tell how many lanes run beside them (a vote, a lane mask, the lane's index, a shuffle, FSWZADD, a matrix multiply, a barrier of Subgroup scope in the module, or shared memory in a workgroup of 32 invocations or fewer); the rest get the driver's choice, which Mesa's Intel compiler builds in a fraction of the time and memory (Source A, an Iris Xe: 0.8-1 GB over 23-25 s pinned, at most 300 MB unpinned). shared: as lanes, and any shared memory pins, whatever the workgroup. The log has vk: compute programs held to 32 lanes: ... where it is not all by default, and the pinned and free counts after the precompile. An unpinned program that did need 32 lanes computes wrongly: =all is the old pipelines. Not run on an Intel GPU here |
RX_VK_FALLBACK_PHI_LIMIT=<n> |
(Triforce, the performance audit's PIPE-56, after Source A's) On Mesa's RADV for GCN 1 to 4 GPUs (HD 7000 to RX 500: RADV without 16-bit storage input and output) and on Mesa's Intel driver only: a mesh-fallback program with a compute stage of more than <n> OpPhi instructions is not handed to the driver; it is left out as a program the driver refused is, with a log line (8 at most), and its draws are not drawn (gpu/vk/fallback_size_policy.h, gpu/vk/vk_draw.cpp fallback_compute_pipelines). Unset: 50,000 on GCN (Source A: RADV for GFX6-8 had not built a 79,947-phi stage after 45-90 s and was killed at 25 GB), 20,000 on Mesa's Intel driver. 0: no limit. No other driver has a limit, whatever is set. Not run on either driver here |
RX_VK_FALLBACK_CALL_LIMIT=<n> |
(Triforce, PIPE-56) The same for a stage's OpFunctionCall instructions. Unset: 200 on Mesa's Intel driver (Source A, an Iris Xe: a 251-call stage unfinished after 27 minutes at 14 GB), none on RADV for GCN. 0: no limit |
RX_VK_NO_SPILLING_RATE=1 |
(Triforce, the performance audit's PIPE-55, after Source A's; Linux build only) The Linux build sets shader_spilling_rate=2 in its environment before the Vulkan instance is made (gpu/vk/mesa_spilling.h, gpu/vk/vk_main.cpp create_instance), unless the player has set that variable. Only Mesa's Intel shader compiler reads it: a program whose registers do not fit is built in fewer, larger steps (Source A, an Iris Xe: one compute program not built after 20 minutes and 13 GB, 32 s and 1.7 GB at rate 2). =1 sets nothing, so the driver keeps its own rate. On Mesa's Intel driver the log has vk: Mesa's Intel compiler spills at rate .... The Windows build sets nothing: under Proton, add shader_spilling_rate=2 to the launch options. Not run on an Intel GPU here |
RX_VK_DRIVER_FAULTS=0 or 2 |
(Triforce, 11-22, the performance audit's PIPE-57, after Source A's; gpu/vk/driver_faults.h) On AMD's own Windows driver only (VK_DRIVER_ID_AMD_PROPRIETARY), unless 0: a program whose pipeline build faulted inside the driver is not asked of the driver again this run, and its key is appended to triforce_driver_faults.txt beside the executable (one line: vendor, driver version, program) by the fault's handler, before a fault during the start's shader work restarts the game, so the next start with that driver skips it instead of faulting again (vk: driver faults: N programs ... kept out of it; delete the file to try them again, another driver version ignores its lines). And one build of a program is inside the driver at a time: a second waits outside it, a probe of the caches is told a compile is required. 2: on every driver (the lab's); 0: nowhere. On other drivers nothing of it runs (gpu/vk/vk_draw.cpp fault_quarantine, build_graphics, guarded_graphics) |
RX_VK_PASS_BARRIER=game or full |
The barrier a draw pass starts with (gpu/vk/pass_barrier.h). game: a pass right after another, with nothing recorded between (no barrier of the game's, no copy, clear, uniform update or dispatch), waits for the earlier work in its fragment stages only, so its vertex, task and mesh work may overlap the earlier pass's fragments; a pass the replay itself split off for a hazard (a pass of its own in the log) and RX_VK_BARRIER_EVERY_DRAW's keep a full one. (Triforce, P4) "Nothing recorded between" is the command buffer's own count (RX_VK_BARRIER_CONTEXT), so beside the Replay helper threads too. full: a full barrier at every pass start, as before. Unset: game with NVIDIA's driver, full on every other card. The log's vk: pass barriers: line says which, and the frame statistics' pass starts ordered in their fragment stages only how many a frame |
RX_VK_CHUNK=<n> |
(Triforce, 11-22, the performance audit's SYNC-66, after Source B's; gpu/vk/barrier_rules.h part_draws) How many draws and dispatches a part of a long submission has in a serial replay: the GPU starts on the first part while the rest is recorded, and each split costs a queue submit, two full barriers and the part's bookkeeping (about 27 a frame at 120). Unset: the driver's default, 120 on every driver until the lab has measured one (Source B cuts at 128 where the GPU idles while the CPU records and at 4096 on desktop drivers); 0: whole submissions, never split; 120: today's size whatever a later default says. The size was read once into a static: now the RX_VK_LAB_AB knob chunk:<n> changes it in its phases while the variable is unset (RX_VK_LAB_AB=chunk:480,chunk:240 with RX_VK_PARALLEL=0). The log's first vk: a submission's parts: line says the size in force and the driver's default |
RX_VK_SPLIT_BARRIER=pass or full |
(Triforce) A long submission goes to the GPU in parts of 120 draws and dispatches (RX_VK_CHUNK); gpu/vk/barrier_rules.h. pass: a pass open at a part's split goes on in the next part, begun again with the same targets behind a barrier of its attachments' outputs alone and with what its draws sampled and wrote, so the GPU does not drain between two draws of one of the game's passes; where the part's end records anything (its uniform updates, its write-backs) or an event's write is held, the full barriers as before. A parallel replay's segments are not split into parts: each begins and ends with a full barrier, so nothing goes on across a segment's edge. full: a full barrier at each part's end and the next one's start, as before. Unset: full on every card ((Triforce, 11-22, SYNC-66) this row said pass with NVIDIA's driver; pass has been off unless set since 11-16, when the lab's Market showed no gain from it: barrier_rules.h split_in_pass). The log's vk: a submission's parts: lines say which and, every 3,600 splits, how many went on in their pass and how many of those parts had uploads (whose own full barriers order them after the part before all the same) |
RX_VK_GPU_WAITS=0 |
(Triforce, 11-22, the performance audit's SYNC-27; on by default; not yet run in the game) The host's calls that block on the GPU are made without being timed, as before. By default each is timed where it is wrapped (gpu/vk/vk_work.h, gpu/vk/gpu_wait_kinds.h) and summed by kind: vkWaitForFences and vkWaitSemaphores with a timeout above 0 (fences, timelines), vkQueueWaitIdle and vkDeviceWaitIdle (idle), vkGetQueryPoolResults with the wait bit (queries). Polls count nothing, a wait inside a wait counts once, and the low-latency sleep's wait is left out as pacing. After each 120-present line the log has vk: host waits for the GPU: ... ms a frame (fences, timelines, idle, queries; all threads), which counts what that line's "GPU-bound wait" (the recording slots' waits alone) does not, and the frame trace has gpu_waits_ms. The cost is two clock reads a blocking wait. The RX_VK_LAB_AB knob nogpuwaits turns the count off in its phases |
RX_VK_ORDER_WAKE=1 |
(Triforce, 11-22, the performance audit's SYNC-59; off unless set; not yet run in the game) A queue stopped at a wait for an event goes on when a submit finds the wait met. A signal of the CPU's (nvnEventSignal) wakes no one: the stop waits for the order thread's next Sleep(1), or a game thread's wait yields up to 3 ms and then forces it. With the switch (gpu/vk/vk_replay.cpp sync_watch, event_signal_queued) the order thread waits on an auto-reset event, 1 ms at most, which the signal sets while a queue is stopped: one SetEvent, no lock and no replay on the signalling thread. And a game thread's wait for stopped work that sees a signal pending lets the queues whose waits are met go on first, as sync_settle does; nothing is forced. The order line counts the wakes and those that let work on: under about one a second, leave it off. The RX_VK_LAB_AB knob orderwake turns it on in its phases |
RX_VK_RELEASE_QUEUE=1 |
(Triforce, 11-22, the performance audit's MEM-85, after Source B's idea; gpu/vk/release_queue.h; off unless set, not yet run in the game) Without the replay thread (RX_VK_ASYNC unset), a texture or program the game finalizes is let go by its own thread: held for the replaying thread only while a queue is stopped at a wait (PR 430), otherwise after sync_drain and the replay's lock, which a replay holds through whole submissions. With this on, every such release goes to a list the replaying thread applies at the start of the next submission's replay or present when no queue is stopped (after the stopped work otherwise, as PR 430's); a texture's release counts the game's writes from the write generation of its call, so writes after the call are still uploaded. The RX_VK_ASYNC job path is not changed. The RX_VK_LAB_AB knob relq turns it on in its phases. On in every run, a count: every 600 releases a vk: releases line when one of them waited 0.5 ms or more for the replay or its order (how many, the time in all, the longest) or went to the list. Not built: the entry's rel_wait_ms column in frames.csv |
RX_VK_UB_BATCH=1 or 2 |
(Triforce, 11-22, the performance audit's SYNC-21; off unless set; not yet run in the game) A recording's uniform updates are written into guest memory at its end between two full barriers, one vkCmdUpdateBuffer an update (about 80 a frame) and nothing between two updates of the same bytes. =1 (gpu/vk/ub_batch.h, gpu/vk/vk_replay.cpp flush_ub_batched): each update's bytes go into the recording's stream (256 bytes at least) and each run of updates into one buffer is one vkCmdCopyBuffer of many regions; a run ends where an update would write bytes the run already wrote, or where the destination buffer changes, and the next starts behind a full barrier, so overlapping updates reach memory in the stream's order. A piece that is not 4-byte aligned becomes a region too (it was a CPU write at record time); with the stream full a piece is written as before. =2: written as before, the overlaps counted (by guest address). Both log a line every 600 flushes: updates, runs ended by an overlap and by another buffer, copies and regions. Look at the counts first: a barrier at every run end costs GPU time if they are common. The RX_VK_LAB_AB knob ubbatch is =1 in its phases |
RX_VK_SPLIT_BEFORE_DRAW=0 or 1 |
(Triforce, the performance audit's REPLAY-14, after Source A's) A part of a long submission (and a helper thread's segment) ends only right before a plain draw that will draw (NOP_DRAW, _IDX, _INDIRECT; rendering on, no rasterizer discard), not after any draw or dispatch (gpu/vk/barrier_rules.h split_before_draw, cut_ok; gpu/vk/vk_replay.cpp). On by default on Intel's GPUs only: on an Arc B580 a command buffer that begins with mesh draws drew its later plain draws as exploded triangles (Source A: 40 shard frames of 1,121, then 0 of 1,101). =0 off, =1 on with any GPU. A run of mesh draws or dispatches is then not cut, so a part can be longer than RX_VK_CHUNK. Not run on an Intel GPU here |
RX_VK_SPLIT_UBFLUSH=0 or 1 |
(Triforce, REPLAY-14) Whether a part's end writes the submission's uniform updates so far into the game's memory (split_ub_flush). On by default, as before, except on Intel's GPUs without mirrors of the game's pools (integrated ones), where only the submission's last part writes them, as an unsplit submission does: written at each part's end they reach the memory later parts' other reads and the game's CPU see (Source A: white blocks in 1 run of 3 on a Meteor Lake iGPU, then 0 of 3). =0 off, =1 on with any GPU. The log's vk: a submission's parts: ended only right before a plain draw ... line says both |
RX_VK_EVENT_BARRIER=late or full |
(Triforce) An event signal in the game's command stream (gpu/vk/barrier_rules.h). late: nothing is recorded at the signal and its pass goes on (the word's buffer is bound there, as before); the event's word is written right after the next full barrier on its command buffer (the game's next barrier, a dispatch's or pass start's), so after all the work before the signal, and a recording's end writes what is still held behind a full barrier before its write-backs copy the words to the game's memory; a wait the replay finds met for an event whose write is held gets a full barrier first. The game sees the word at that barrier rather than at the signal. full: the pass ended, a full barrier and the write at each signal, as before. Unset: with the pass barriers' game mode (RX_VK_PASS_BARRIER: NVIDIA's driver). Not with the parallel replay. The vk: event signals: line says which |
RX_VK_TAIL_EARLY=1 or =0 |
(Triforce, on by default since options_version 6; over the Debug tab's Start next frame early row, tail_early=0 to turn it off; read at the start; after NX2navi's tail_early) The early tail (gpu/vk/tail_early.h, gpu/vk/vk_replay.cpp): the replay cuts a frame's recording at the gameplay upscale's dispatch (the game's network, or DLSS, DLAA, FSR in its place) and records the rest, the upscaler and the interface, as one command buffer; its event signals are held. At the recording's end a tail that wrote no binding (its inline uniform updates aside), bound no guest memory itself, ran no program of the game's that reaches guest memory through the page table or a texel buffer, and wrote no texture back has its event words written in its upload command buffer, after the scene's write-backs and ahead of its own commands: OoT's present poll then sees its frame's event while the GPU still runs the tail. Any other tail has the words written at its end, as before. Also with the parallel replay (its segments end at that dispatch) and with the lazy write-back. Not with RX_VK_BENCH or a frame dump. A vk: the early tail line at the start says on, and every 1200 tails how many went early and why the others did not. Not yet run in the game |
RX_VK_DISPATCH_BARRIER=game |
(Triforce) Off unless set, not yet run in the game: a dispatch right after another, nothing recorded between, records no full barrier of its own (not an indirect one, nor a program a stand-in may take over), as NX2navi's barrier_game does; the game's own barriers order its dispatches. Only the game shows whether that is always so (a one-frame band or flicker where it is not): a switch for the lab. A vk: RX_VK_DISPATCH_BARRIER=game: line every 20,000 dispatches it left without one. (wp14, P4) It no longer stands aside while the Replay helper threads record (most frames at the Market, so the lab's earlier run of it measured little): "nothing recorded between" is the command buffer's own count of its commands (gpu/vk/cmd_work.h, RX_VK_BARRIER_CONTEXT), a segment being a command buffer of its own |
RX_VK_BARRIER_CONTEXT=0 |
(Triforce, P4; after NX2navi's per-context barrier state) What the barrier rules ask, "was anything recorded into this command buffer since its last full barrier, its last pass's end, its last dispatch", is answered by each command buffer's own count of its commands (gpu/vk/cmd_work.h), where one count of every thread's commands served before (an atomic add on every command by every recording thread). So the rules hold while the Replay helper threads record: the left-out repeats of a full barrier, RX_VK_PASS_BARRIER's pass starts and RX_VK_DISPATCH_BARRIER. A command buffer's begin starts its state afresh; each segment begins and ends with a full barrier, so no rule relaxes across a segment's edge. RX_VK_SPLIT_BARRIER asks also whether anything went to the queue between two parts (every submit is counted). The rules' defaults are as they were. 0: the one count, and the rules standing aside while the helper threads record, as before. The vk: barrier state: line at the start says which; the frame statistics' full barriers recorded, ... left out and pass starts ordered in their fragment stages only show the difference |
RX_VK_BATCH_IDLE=1 |
(Triforce, 11-22, off by default; the performance audit's SYNC-09, after Source A's; gpu/vk/barrier_rules.h batch_idle) With held submits (RX_VK_BATCH, the row below: on by default with Mesa's RADV only), a submit that joins the held batch sends it at once when the GPU has finished every batch sent; while the GPU is busy, submits still group. A held batch otherwise waits for a wait, a present, the 2 ms poll or the cap of 32 with the GPU idle beside it. Source A has this on wherever batching is, and off where guest memory stayed host-pointer imports (each submit there pays amdgpu's page check); here it is off unless set on every driver until a Linux RADV machine has run it, and no guard for host-pointer imports is built. Nothing changes without held submits (NVIDIA, AMD's and Intel's Windows drivers). The 120-present vk: batched submits: line counts its flushes as idle |
RX_VK_BATCH=parts, 1 or 0 |
Held submits (gpu/vk/vk_replay.cpp batch_way). 1 (the default with Mesa's RADV): every submit held until something needs the GPU's results or the queue's order. (Triforce) parts, off unless set: only a whole submission's recordings are held, and only while the game's submit is being replayed; a part goes at once with those held before it, as do 4 held (RX_VK_BATCH_MAX), and the held go when the replay of the game's submit returns. Neither changes the command buffers or their order on the queue. 0: each submit at once (the default elsewhere). The vk: batched submits lines say which and how many command buffers went in each queue call |
RX_VK_PEND_HELD=0 |
(Triforce, on by default) A flush for a fence wait or a progress poll looks at a flag before the queue's lock (dev.present_mu) and returns when nothing is held (always, with batching off): it took the lock to find nothing, behind a present or a late page's fix waiting on the GPU. A held submit's recording is made known to the waiters only once it is held with the flag raised, so a waiter that finds it flushes it (before, it could flush nothing and wait for the held signal until the next poll, present or cap); a recordings' wait whose recording the recordings' timeline has passed returns without a flush. The batched submits' line counts the looks that found nothing held. =0: the lock every time and the registration first, as before; RX_VK_LAB_AB=nopendheld the same in its phases (tests/test_flush_nothing_held.py) |
RX_VK_IMPORT_HIGH=<percent> or 0, RX_VK_IMPORT_LOW=<percent> |
The idle imports' valve (gpu/vk/vk_memory.cpp imports_give_back): past HIGH percent (85) of the system heap's budget, the imported pools bound least lately, idle for 600 submissions and without a mirror, are given back down to LOW percent (75; 10 to 95). On by default where that budget is under 12 GB (on Windows only with the memory handling on); RX_VK_IMPORT_HIGH=85 turns it on at any budget, =0 off altogether. Setting either keeps the whole budget as the measure (no cap, below) |
RX_VK_IMPORT_CAP_MB=<n> or 0 |
(Triforce, the performance audit's MEM-22, after Source A's) What the valve above measures the heap against, where that is less than the budget (gpu/vk/import_budget.h). Unset: 4,500 MB with Mesa's RADV at a budget of 12 GB or more, where the valve was off and live imports piled up for the session (Source A, an RX 9070 XT with 32 GB: 221 live imports and 7.4 GB after two hours against 50-64 and 2.3-2.7 GB capped); no cap on any other driver or at a smaller budget. <n>: that cap on any driver and budget, which turns the valve on. 0: no cap, RADV's behaviour before. A pass against the cap gives back 1 GB at most. Not run on RADV here |
RX_VK_FOLIAGE_SHADOW_CULL=<layer>[f] |
(Triforce, after NX2navi's 754ded9) On from layer 1 unless set (off: as the game draws them): the draws of mesh programs into the sun's shadow cascades (depth only, square, wider than 768) from that layer of the cascades on (0 to 2; NX2navi's is 1) that cull neither face are drawn with their back faces culled (the front ones with f, as 1f): the foliage's double-sided cards draw half their fragments there (gpu/vk/foliage_shadow.h). Not quite the same picture: a lone card facing away from the sun casts no shadow in the middle and far cascades (where cards stand in pairs or clumps the others cover it; the near cascade is drawn as the game asks). The log says vk: RX_VK_FOLIAGE_SHADOW_CULL at the start and names the first draws it culled (vk: foliage shadow cull:) |
RX_VK_FOLIAGE_SHADOW_VRS=<layer> |
(Triforce, after NX2navi's 754ded9) On from layer 2 unless set (off: the extension not asked for, no pipeline changed): the same draws of native mesh programs, from that layer of the cascades on, shade one fragment per 2 x 2 pixels (VK_KHR_fragment_shading_rate, where the device has pipelineFragmentShadingRate and native mesh shaders; elsewhere nothing changes): the leaves' alpha test runs a quarter as often, depth still per texel. The rate is dynamic state only in the pipelines of native mesh programs with no colour target and a depth one (and in their two shader libraries, keyed apart), which the driver builds again once: on such a device the driver's part of the preparation makes those libraries too (and the RX_VK_LIB_CHECK sample asks for them), once more at the first start after the update, before the game (the other libraries come back from the cache), and the light precompile builds each depth-only pipeline of a native mesh program once more; their keys, the program cache and every other pipeline stay as they were. The log says vk: the far shadow cascades' foliage at 2 x 2: at the start and names the first draws (vk: foliage shadow 2 x 2:) |
RX_VK_FOG_CULL=1 |
(Triforce, after NX2navi's 0379b00) Off unless set: the volumetric fog's first compute pass skips, as the game does, the froxels behind a coarse depth table of the frame before and writes them as empty, which the fog's history smears into dark trails beside near objects (worst at the screen edges, in foggy places such as the Lost Woods and Kokiri Forest). By default those froxels are computed too: the comparison is made never true in that one module, found by its shape in the SPIR-V (gpu/vk/spv_fog.h: a block of five image writes, four of (0,0,0,1) and last 1/255, and the one branch to it an ordered greater-than decides). It is applied where the module is made (make_module), outside the translation stamp: the program cache's records stay as they were translated, so nothing is translated again, and only that one compute pipeline is new to the driver's caches. With the precompile keeping none (RX_VK_PRECOMPILE_KEEP, less RAM), its record of the compute programs built has the patch and the matcher's version in its key (gpu/vk/vk_draw.cpp kFogPatch times spv_fog::kMatcher, raised whenever the matcher finds modules it did not: a record written by the matcher before 11-17's, which patched none of Triforce's fog modules, is built again), so the first start with the patch, or with a new matcher, builds the listed compute programs once more before the game (every one but the fog's a cache hit, the fog's compiled into the play cache, mkw_vk_pipelines_play.bin, or the main one where there is none, and saved before the record says built) rather than compiling the fog's at its first dispatch; with RX_VK_FOG_CULL=1 that key is the one it was. A little more GPU time in the fog's pass. The log says vk: fog: module <crc>, the volumetric fog's first pass: and what was done (also for a near miss: the exit found but not its comparison) |
RX_VK_FIFO (set), RX_VK_IMMEDIATE (set) |
The swapchain's present mode for one run, over the Insert menu's VSync row: FIFO, as with vsync forced by a driver; immediate, where the surface lists it. Unset, the row decides (gpu/vk/present_mode.h): On is mailbox where the driver has it (immediate on Windows where it has none, FIFO elsewhere), Off immediate wherever the surface lists it |
RX_VK_SKIP_PROG=<prefix>,... |
Leaves out the draws of these programs (default 53509044401d78d2; - leaves out none) |
RX_VK_PIPE_SKIP=0, 1 or 2 |
Default/1: wait for shader translation; a pending pipeline can be skipped only for attachment-only draws whose targets hold an earlier frame. 0: wait for every pipeline too. 2: restore the old skip for untranslated draws with persistent targets; this can omit writes before the shader is known. Translated memory-writing draws still wait |
RX_VK_TRANSLATE_WAIT_MS=<ms> |
(Triforce, 11-22, the performance audit's PIPE-30, after Source A's; gpu/vk/translate_wait.h) Off by default: a draw whose program is still translating waits for it, as before. Set (1 to 100, digits only; 8 to try): a draw into targets that hold an earlier frame, of a program whose key's translated variants write no memory (noted at each new pipeline and at the precompile's loads), waits at most that many ms a frame in all, the translation hurried but not run on the draw's thread, then is left out; a spent budget leaves the next one out at once. A key never translated, one with a variant that writes memory, and a draw into new targets wait as before; RX_VK_PIPE_SKIP=0 and =2 keep their meaning. The log says how many waited and were left out (vk: programs still translating, so far: ...). More draws left out, mostly in load frames: for a lab to weigh (gpu/vk/vk_draw.cpp draw, translate_note) |
RX_VK_PIPE_DEPTH_BUDGET=1 |
(Triforce, 11-22, the performance audit's PIPE-29, after Source B's; gpu/vk/pipe_wait.h depth_budget, choose) Off by default on every driver, Intel's too (the entry would have it on for Intel's Windows driver: that waits for the owner's word). Set: a depth-tested draw into a pass drawn once whose shaders write no memory, outside a samples-passed count and not into targets kept from an earlier frame (the item icon capture's), waits for its pipeline from the frame's wait pool (RX_VK_PIPE_FRAME_WAIT_MS, 50 ms) and is then left out; that pipeline is then left out at once until it is built (the list emptied every 600 presents). The first 16 left out are named, and a line counts them (vk: depth-tested draws into passes drawn once, so far: ...). A render into a new depth target left out can stay missing until it is drawn again: the trade Source B made for an Arc B580's 11-13 s freezes (gpu/vk/vk_draw.cpp draw, pipe_depth_budget) |
RX_VK_PIPE_FRAME_WAIT_MS=<ms>, RX_VK_PIPE_ONESHOT_BUDGET=1, RX_VK_PIPE_SKIP_NEW=0 |
A draw whose pipeline is not ready (gpu/vk/pipe_wait.h, NX2navi's rules). A full-screen draw (at most 6 vertices over half the pass or more: a lighting, fog or tone mapping pass) into targets that hold an earlier frame is left out only where the hold of the last picture takes its frame (RX_VK_HOLD_PIPELINES); where it cannot (at its bound, resting after one, or off) the draw waits for its pipeline up to this many ms a frame in all (50, at most 500), then 40 ms more, and is left out after both; its job goes to the front of the workers' queue meanwhile. 0: left out, as before. RX_VK_PIPE_ONESHOT_BUDGET=1 (off; NX2navi has it on): draws into targets drawn once and draws whose shaders write memory wait from the same budget and are left out once it is spent, instead of waiting until their pipeline is made. RX_VK_PIPE_SKIP_NEW=0: a pass whose colour target is drawn for the first time is kept by its depth target alone, as before (by default its draws wait, as for any target drawn once: the game's item icon capture). The log's vk: pipelines not ready line counts them |
RX_VK_PIPE_FAST_WORKERS=0, RX_VK_PIPE_LINK_MS=<ms> |
A pipeline whose stage libraries were cold has those libraries built by a worker first and is linked from them, ready with that link, and its whole optimised build follows as a job of its own (gpu/vk/pipe_wait.h libs_first, NX2navi's pipe_fast_workers); a draw that waits for it runs the libraries and the link, not the whole build. 0: the whole build first and the cold libraries after it, as before. RX_VK_PIPE_LINK_MS=<ms> (0 by default, at most 100; NX2navi's 6): the links made on the draws' threads in a frame take at most this long; a new pipeline after that is linked by a worker, its draws left out or waited for meanwhile (needs the fast pipeline link and the first switch on) |
RX_VK_PRECOMPILE=0 or 1 |
The shader preparation before the title off or on (on in builds made with RX_RELEASE=1, as the builders' are) |
RX_VK_PREPARE_THREADS=<n> |
The threads the shaders are translated and their driver's part made on before the title, 1 to 64. Unset: every processor, a thread past half of them for each GB of RAM free at the start, and half in a process started above normal priority (the log's "the shaders' preparation runs on" line says how many) |
RX_VK_WARM_COMPUTES=listed or all |
(Triforce, 11-22; gpu/vk/warm_computes.h, tests/test_warm_computes.py) The compute pipelines the shader preparation's translation pass has the driver compile. all: every compute program's texture variants (about 9,700), as before. listed: only the programs play dispatched (triforce_computes.bin, about a tenth of them; the precompile builds the same ones), the others translated as before and compiled at their first dispatch; with no list yet (nothing played) every one. Unset: listed on Intel's GPUs (an Arc A750 spent 5175 s of a 5858 s pass on them, an RTX 4070 SUPER 170 s on the whole pass), all on the others. No stamp holds it |
RX_VK_FALLBACK_SHARED_RECORDS=0 |
(Triforce, 11-21, the performance audit's MEM-154) With the compute fallback for task and mesh shaders, each recording thread keeps buffer pairs: 64 MB of records, the same size for every program, and a payload sized by the task program. A payload that fits no pair now makes a pair that takes the newest pair's records and only a new payload; before, 64 MB more of records each time, kept for the session. The log's vk: mesh fallback: a buffer pair lines say made or shared. 0: its own records each time, as before (gpu/vk/vk_draw.cpp fallback_buffers_of) |
RX_VK_TASK_MESH_FALLBACK=0 or 1 |
Task + mesh draws through the compute fallback (1) or the driver's mesh shaders (0). By default the fallback is on for AMD's Windows driver for RDNA 2 (every RX 6000 card and that generation's integrated GPUs: the driver whose vk: vendor fixes line names the "AMD proprietary shader compiler"), where the native path timed out the driver on the RX 6700 XT and RX 6800 XT (issue 996) |
RX_VK_FALLBACK_LOADED=0 |
(Triforce, 11-22, the performance audit's PIPE-62, after Source A's) On the task and mesh fallback, the precompile is handed only the fallback programs whose records are still on the disk, as before. The default also hands it every fallback program already in memory that is ready and not failed (gpu/vk/vk_shader.cpp program_cache_load_some, in the part outside the translation stamp), so that their compute pipelines are built on the precompile's workers before the title: in a start that prepares, state_list_prepare has read the state lists' programs in before the precompile asks, and those got no pipelines until their first draw, which waited up to 50 ms on the recording thread and was left out until they were built. The log says how many: vk: N mesh fallback programs read in earlier in this start are made ready with the rest. Only GPUs on the fallback (no mesh shaders, RX 6000 and RDNA2 integrated GPUs on Windows, the menu's Compute row, RX_VK_TASK_MESH_FALLBACK=1); the preparing start's load grows by the compiles moved out of play |
RX_VK_MESH_AHEAD=0 |
(Triforce, on by default, after NX2navi's mesh_ahead; =0 as before) An indirect mesh draw's records are copied into a ring as {count, 1, 1} before it, outside the pass, so each one ended its pass and the next draw began it again (OoT's foliage, grass and leaves: about 16 a frame at the Market). Now the first indirect mesh draw of a run copies the records of the indirect mesh draws after it as well, in the same three barriers, and those stay in the pass: a run is the indirect mesh draws after it with only state, draws, counter reports and render conditions between (gpu/vk/vk_replay.cpp mesh_run_kind); a dispatch, a barrier, a copy, a clear, a uniform update, new targets or an event ends it, so no work of the game's between can write the records after they were copied. A draw takes only the entry copied for it (its op, records, count and stride); at most 32 draws and 1 MB of the ring a run (gpu/vk/mesh_ahead.h). A vk: indirect mesh draws line every 20,000 conversions says how many took their records from an earlier draw |
RX_VK_NO_PROGRAM_CACHE (set) |
Neither reads nor writes hookshot_programs.bin and the pipeline notes |
RX_VK_PROGRAM_CARRY=0 |
The program cache (triforce_programs.bin) is good for one build of the translator only, as before: any change to its files, a log line or a host option's number in gpu/vk/vk_api.h too, translates every program again, and the pipeline cache, the pipeline notes and the prepare's record go with it. By default the cache is carried over an update that changed nothing of what translates (gpu/vk/program_carry.h has the rule, tests/test_program_carry.py holds it): the translation stamp (nx2/build.py translation_stamp) is the translator's files without vk_api.h, without the parts of vk_shader.cpp and vk_bank.cpp marked as outside it, and without comments, blank lines and spaces at lines' ends. The build log's build: translation stamp line says whether it is the last release's (nx2/released_translation_stamp.json, which players' caches are for, and which tests/test_program_carry.py holds this source to) or which stamped files moved it against that release; a second line, in brackets, compares it with the previous build in the same folder (its record: translation_stamp.json in the build folder, written once the objects are compiled). Both are about the build's part of the stamp: the runtime adds its own settings to it (disk_stamp). The log's vk: program cache line at the start says whether the programs were kept, carried over an update of the translator (and from which build), or translated again (and how many the cache had); while they are translated again a line now and then counts them. Switching it either way translates every program once more |
RX_VK_PREPARE_RECHECK=0 |
(Triforce, 11-22, after Casual Gamer's #dev-fixes post) Both as before: a start whose record (triforce_prepared.bin) says the shaders are prepared takes its word, and the empty mark of a start that died in the driver's part without stage libraries (triforce_prepared.bin.warming) leaves that part out on any GPU and driver. By default (gpu/vk/prepare_again.h, vk_draw.cpp prepare_run): where the record says nothing to do, the program cache's head and size are read, and one made again since for another GPU or other settings (another stamp, or its head alone) holds none of the shaders: preparing again (logged), the stale record removed first; a cache carried over an update keeps the stamp and passes. And the mark holds what the part is made for (the GPU, the driver, the programs), as the libraries' journal does: another stamp's mark is another driver's, and the part goes on (tests/test_prepare_again.py) |
RX_VK_CACHE_SET=0 |
(Triforce) No earlier set of the shader caches is kept or put back (gpu/vk/cache_set.h has the rule, gpu/vk/vk_cache_set.cpp the files, tests/test_cache_set.py). By default, when the caches' stamp changes and the build of the translator did not (a setting of the translation: the menu's Robust buffers row, the mesh shaders row, the GPU, an RX_VK_ switch of the translation), the set there (the program cache and its index, the pipeline cache and the play file with their .for, the prepare's record with its .check, .warming and .warming.skip, the pipeline notes and what is kept beside them by the stamp) is renamed to <name>.<stamp>.<ext> when the disk has twice the set and 10 GB free, and triforce_cache_set.kept.txt lists it. One set is kept. A start whose stamp is the kept set's puts every piece of it back (a set with a piece missing is deleted), and the set it found is kept in its place; a start of another build deletes it. triforce_cache_set.txt names what the set there was made for, and the log's vk: shader caches: lines say which part of the stamp changed. A set put back while the player's triforce_pipeline_states.bin is not the one it was kept with leaves triforce_cache_set.states.txt, and the prepare before the title then goes through the state lists, so that what was met under the other set is built before the game. Files of a kept set's names that no record names (a start that ended in a swap) are deleted at the next start. RX_VK_CACHE_SET=0 also deletes a kept set; RX_VK_PCACHE_KEEP_OLD and RX_VK_NO_PROGRAM_CACHE leave it off too (a kept set of this build stays, another build's is deleted) |
RX_VK_GPL=1 or 0, RX_VK_GPL_KEEP_LINKS (set) |
The fast pipeline link (VK_EXT_graphics_pipeline_library; gpu/vk/gpl_rules.h), on by default since options_version 5: a new pipeline is linked from its program's two shader libraries where the driver has them compiled, and the optimised build replaces it. The Debug tab's Fast pipeline link row is the same without an environment to set (fast_pipeline_link=1); the switch goes over the row. With it the preparation has its driver's part ("Compiling shaders"), which now goes on after a start that died in it, leaving out the programs that start had in the driver's hands (triforce_prepared.bin.warming and .warming.skip), up to three starts in a row. RX_VK_GPL_KEEP_LINKS: the linked pipelines the optimised ones replaced are kept for the run, as before, instead of destroyed 600 presents and 10 s later. RX_VK_NO_WARM (set): no driver's part; RX_VK_GPL_SYNC (set): a cold library is compiled in the draw; RX_VK_GPL_NO_CACHE (set): the libraries are not kept in the pipeline cache |
RX_VK_LIB_CHECK=0 |
(Triforce, after NX2navi's e10ef60) On unless 0. At a start whose record says the driver's part is made for these shaders and this driver, a sample of 12 kept program variants has its two stage libraries made as that part makes them, asking the caches only where the device can (the answer a draw's link gets; without the flag, RX_VK_GPL_SYNC, their time against a second making, which comes from the cache), twice, before the game (gpu/vk/lib_check.h). When more than half are cold (mkw_vk_pipelines.bin lost or refused, or the libraries built otherwise now without kWarmRecipe counted up) the driver's part is made again at once, as after a driver update, with its journal and skip list; warm, nothing more happens (some 50 library lookups). triforce_prepared.bin.check records that it did: a start that finds them cold again right after leaves them to the draws, as before (each try holds a start for minutes; remove the file to try again). A making again whose cache could not be saved is recorded the same way. A cache file over its bound is not made again at all. The log's vk: stage libraries: line says what was found |
RX_VK_BUILT_CHECK=0, =2 |
(Triforce, 11-22, the performance audit's PIPE-21, after Source A's and Source B's; gpu/vk/built_check.h) On unless 0. A light precompile (RX_VK_PRECOMPILE_KEEP: none kept) records what it built for the caches in <notes>.built, and later starts left all of it to its first draw or dispatch on the record's stamp alone. Now, before the record is trusted, up to 24 of the recorded notes are asked of Triforce's own pipeline caches as a draw asks them (without compiling, where the device has pipelineCreationCacheControl; without it each is built twice and timed: a first build over 4 times the second and 3 ms more was compiled), and with the record's compute key up to 6 of the listed compute programs as a dispatch asks them. Under 16 answers nothing is said; half of them or more not there: the caches lost them, and everything noted and listed is built again before the title and recorded anew (vk: precompile's record: ...). Lost again right after that (<notes>.built.check): left to the draws, as before, with a hint about the driver's shader cache size. Also counted: play builds of recorded pipelines that took 40 ms or more and recorded compute programs a dispatch did not find (vk: precompile's record: in play so far, ..., at most every 10 s while it grows). 2: built again at every start (the lab's). 0: neither the check nor the counter, as before (gpu/vk/vk_draw.cpp built_check_cold, precompile_run, built_play_build) |
RX_VK_SPV_PACK=0 |
Every shader module kept for the whole run, as before. By default the SPIR-V of graphics and mesh programs is kept packed in memory (gpu/vk/spv_store.h, to about 0.37 of its size) and their shader modules, which the driver otherwise holds for the whole run, are made only for the time a pipeline is created with them, on the thread that builds it. Compute programs, the programs the preparation lets go and the programs a draw reads from the cache itself keep their modules. The log's vk: shader code packed lines say what it comes to and what it costs |
RX_VK_PCACHE_RAM=1 |
Off by default (in its one session on, v0.4.0-test9, it gave back nothing the working set showed). With it, once the PC has had under 1.5 GB of RAM available at two looks a second apart, the pipeline cache (when it is 256 MB or more) is destroyed once no pipeline creation is using it (gpu/vk/pcache_gate.h): the pipelines built after that go without it and it is not saved again that session, so mkw_vk_pipelines.bin keeps its last save. The log's vk: RAM short ...: the pipeline cache ... is let go line says when and what the working set did. Whatever this switch says, the cache's save in play waits while a copy of it would not fit in the RAM available with 2 GB to spare (the save at the game's close does not), and the builder of the predicted pipelines behind the game rests while under 3 GB (or a tenth of a PC of more than 30 GB) is available (gpu/vk/mem_parts.h) |
RX_VK_WRITERS_WAIT_MS=<ms> |
(Triforce) How long the game's close waits for the files the renderer is writing on threads of their own (gpu/vk/file_writers.h; 2000 by default, 0: no wait and nothing refused, as before). The close ends the process through ExitProcess, which stops every other thread where it is: the pipeline cache's save in play, the order file, a bug capture's or a debug picture, the hang report, the predicted pipelines' list, the frame log. At the close (HOS_OPT_EXITING) no such write begins any more and the ones under way are waited for; one still going at the bound is cut, and is one of the files written whole beside the old (.part / .tmp, then put in place: the prepared record triforce_prepared.bin and the .for files are now too), or a list whose reader takes whole records only. The log's vk: exit: the files being written ... were waited for line says how long, and what was cut |
RX_VK_OPTIONS_MERGE=0 |
(Triforce) The menu writes its own values over triforce_options.ini in place at every change, as before. By default (gpu/vk/ini_merge.h, vk_menu.cpp save) each line it writes is merged by its key with the file as it is then: a line changed outside the game while it runs (a text editor, a tool) and not changed in the game since the game read or wrote the file is written as the file has it, so a change made outside and one made in the menu within the same second both stay (a row changed on both sides is the game's); the game takes such a line at its next start. The file is written whole beside the old one and put in its place (in place only where another program holds it open so that it cannot be replaced). The log's menu: options: ... changed in triforce_options.ini outside the game line names such lines |
RX_VK_MEM_PARTS=0 |
No vk: memory, the parts line. By default every 600 presents it gives the working set, the game's own memory committed and in RAM (a sample of its pages), the rest of the working set in RAM by what it is (a sample too: the program's code, the driver's code, other code, mapped files and views, write-combined or uncached memory, the heaps and other private memory), the shader modules alive and the packed stages, the pipeline cache, the pipelines and stage libraries kept (how many a draw has had, how many were given back) and the allocator's blocks in system memory (gpu/vk/mem_parts.h), and what its walks and samples took. It is written on a thread of its own that nothing waits for; the guest window's walk is made again every eighth line |
HOS_MEM_ZERO_MARK=1 |
(Triforce, 11-22, the performance audit's MEM-13; off unless set; not yet run in the game) Freed guest pages that a Vulkan import holds are zeroed in place, not discarded (host/hos_mem.c discard_pages and FreeMemoryPages, host/hos_svc.c UnmapPhysicalMemory). The renderer does not see a bare memset, so its mirror, its captures and the write-back's shadow keep the freed bytes, and a later write-back could put them back over the zeros. With the switch the fill (host/hos.h hos_guest_fill) marks the pages written, after the memset. Off by default until it is measured: the marked zeros (up to 5.2 GB over a tour) are pages the captures and the mirror syncs then copy, which could hitch an arrival. To measure: two runs a side, the log's "capture ... copied (MB)" and "mirror syncs ... dirty pages", and the frames over 50 ms in each arrival's first 5 seconds |
RX_VK_SWAP_RESERVE_MB=<MB>, RX_VK_TEST_SWAP_MB=<n> |
(Linux; Triforce, 11-22, the performance audit's MEM-141, after Source A's; off unless set, not yet run on Linux) A memory pressure hold that counts the swap. The RAM rules look at MemAvailable alone, which a PC with swap keeps up by pushing the game's pages out (a 16 GB Steam Deck's swap filled while it said little). With the reserve set (Source A's is 2560), every 30 presents the PC is short when MemAvailable is under 1536 MB or MemAvailable and SwapFree together are under the reserve, and until both are 256 MB clear of their lines a hold is on: a capture buffer is kept as a spare only up to 32 MB of spares, the staging arenas the GPU is done with are freed as it begins and then after 5 s unused, malloc_trim is asked every 600 presents from 64 MB free, idle imports are given back (in all of one hold at most the bytes the PC was short at its worst, still only after 3,600 idle submissions), and an integrated GPU's texture budget is less by what the PC is short, never under 512 MB, coming back 256 MB a look. A PC without swap, or whose swap cannot be read, is never short by the sum. The log's vk: swap hold: on and off lines say when and what each gave. 0 or not set: no hold, as before; never on Windows. RX_VK_TEST_SWAP_MB=<n> plays that much swap free, as RX_VK_TEST_AVAIL_MB plays MemAvailable (gpu/vk/linux_pressure.h, gpu/vk/vk_memory.cpp swap_hold_step) |
HOS_MEM_CENSUS=<seconds> or 0 |
(Triforce) The guest memory census (host/guest_census.h), on by default every 5 seconds, on a thread of its own: a mem: census line with what the runtime handed out of the guest window by kind (the program and the system region, the heap, the address regions and the game's own pages in them, what lies outside them: the physical maps and first touches), the game's own count against the 9809 MB it is told it has, the pages the game let go that stay committed (zeroed under an import, or discarded with a freed region) and what the give-back gave back, the process's commit and working set, and the PC's commit and RAM; and a mem: census, the renderer line with the Vulkan back end's big holders (its imports, mirrors, VRAM in use, the allocator's blocks in system memory, the pipeline cache, the pipelines and stage libraries kept, the shader modules). A count of bits a 4 KB page, kept as each place commits, maps or lets go of guest pages. 0: no line (and, with the give-back off, nothing kept) |
HOS_MEM_GIVE_BACK=1 or 2 |
(Triforce) Off by default, not yet run in the game: the pages the game let go that stay committed because an import held them (FreeMemoryPages, UnmapPhysicalMemory) or because they were discarded with a freed address region are decommitted once nothing of the renderer imports them, from 4 GB up (below it pages are handed out without a commit), up to 256 MB a census pass, in runs of 16 MB at most; the renderer answers and runs the decommit with its import locks held (gpu/vk/vk_memory.cpp guest_release_unimported), so no import can lock them between. 1: every pass; 2: only while the PC is short (its commit past 85% of its limit, or under 1.5 GB of RAM available). The census line's given back says how much |
HOS_MEM_MAP_RESULT=0 |
(Triforce) MapPhysicalMemory answers success even where Windows refused the commit, as before. By default it answers Horizon's LimitReached (0x10801), which the SDK turns into its out-of-memory result, and the log says mem: MapPhysicalMemory ...: the commit failed |
RX_VK_PRECOMPILE_KEEP=1 or 0 |
The precompile keeps every pipeline it builds for the session (1), or keeps none of them: they are built for the caches and let go, and a draw that first needs one builds it from there (0). Unset or auto: kept where the RAM available at the precompile and what the game holds already (less what reading the pipeline cache added, except on AMD's driver: own_for_keep) come to 22 GB or more, on a PC of 20 GB or more (gpu/vk/mem_parts.h keep_all_pipelines); the log's vk: precompile: line says which and why. (Triforce, 11-22, after Casual Gamer's #dev-fixes post) Unset (not auto): on a discrete GPU in a PC of under 20 GB every pipeline is kept while the game is told its mapped pages are used (HOS_MEM_QUERY_USED, keep_all_small_pc): a 16 GB laptop, ~0.6 GB more private memory, frames of 1 s or more 15 and 11 in two tours -> 3 and 6. A card the driver allows under 6.5 GB still leaves them to their first draw first; integrated GPUs keep the RAM rule; auto: the RAM rule, as before |
RX_VK_TEX_PIPES_AHEAD=0 |
(Triforce, on by default; =0 as before) The texture converters' compute pipelines (the GPU ASTC decoder, the BC encoder, the unswizzle and the swizzle back: gpu/vk/vk_texture.cpp texture_compute_pipeline, texture_pipelines_warm) made through the pipeline cache kept across runs, and all four before the game: in the precompile, right after the cache is read, or at the start when the preparation was skipped at the build. Each was made without a cache inside the first upload that needed it, which with an empty driver cache (a first start, a new driver) waited for the compile, a vk: slow upload of 100-320 ms. The ASTC decoder and the BC encoder only where the GPU does not sample ASTC. The vk: texture converters ready in line says what it took |
RX_VK_PIPE_RELEASE=0, RX_VK_PIPE_RELEASE_EVERY=<presents> |
Every kept pipeline stays for the session, as before. By default, while the PC's RAM is short (under 1.5 GB available at two looks in a row), every 300 presents up to 512 of the kept pipelines no draw has had yet are given back to the driver (gpu/vk/pipe_release.h); a draw that needs one later has it built again by a worker. The log's vk: RAM short: ... kept pipelines no draw has had given back lines say how many and what the working set did |
RX_VK_PCACHE_CARRY=0 |
The pipeline cache's file carried over a stamp change (gpu/vk/pcache_carry.h): at an update's preparation (Setup's "Preparing shaders", HOOKSHOT_PREPARE_ONLY) a mkw_vk_pipelines.bin made for other shaders is read all the same when it is this device's and driver's, within its bound, and at most 1.25 times its base (the size of the last set built fresh, kept beside it in mkw_vk_pipelines.bin.base with the carries since): the pipelines of shaders the update did not change are hits instead of hours of compiling. The cap is over every carry since the base was built, not a quarter more each time, and a carried cache may never pass the file's bound either. The preparation looks at a carried cache's size every 10 s while it builds and at each save: past the cap (or the bound), nothing more is built into it, it is not written, mkw_vk_pipelines.bin.nocarry names the new stamp (a preparation begun again after a Cancel starts fresh), and the preparation builds the driver's part again into a fresh cache: the compute pipelines the carried run built, from the program cache, then the stage libraries, nothing translated again (from the driver's own cache for what it had just compiled), which gets a new base. A carried preparation that is stopped (a Cancel, a closed window) saves its cache under the new stamp with its history marked open in .base: the preparation begun again reads it as carried still, capped the same (or, when .nocarry names the stamp, not at all), until a carried preparation goes through to its end. The log says pipeline cache carried over a stamp change (N MB, base M MB). 0: a file for other shaders is never read, as before (the rule of 11-14). The play file keeps its own rule |
HOS_DRIVER_CACHE_ROOM=0 |
(Linux; Triforce, 11-22, the performance audit's PIPE-97, after Source A's and Source B's; not yet run on Linux) The game builds the pipelines its notes predict (about 41,400) into the driver's own shader cache on disk, and NVIDIA's and Mesa's caches hold 1 GiB unless told otherwise and trim themselves to it: part of a full preparation is dropped and compiled again in play. By default the game sets __GL_SHADER_DISK_CACHE_SIZE (NVIDIA) and MESA_SHADER_CACHE_MAX_SIZE (Mesa: RADV, the Steam Deck) to 10 GiB before Vulkan loads, for its own run and the builder's --prepare-shaders run; a size already in the environment stays, and the cache only grows by what is built. The log's boot: room in the drivers' shader caches: line gives both values. HOS_DRIVER_CACHE_ROOM=0, in the environment or triforce_env.txt: neither is set, as before. Nothing is done on Windows, where NVIDIA's driver takes its size from its control panel (host/hos_main.c driver_cache_room) |
HOS_DRIVER_CACHE_FOLDER=0 |
(Linux; Triforce, 11-22, the performance audit's PIPE-98, after Source A's; not yet run on Linux) NVIDIA's Linux driver keeps no shader cache at all when __GL_SHADER_DISK_CACHE_PATH names a folder that is not there: it neither makes it nor falls back to its own folder, and every prepared pipeline is compiled again at each start. By default the game makes the folder the variable names, with its parents, for the user alone, before Vulkan loads (the builder's --prepare-shaders run too); the value is never changed, nothing is made when the variable is not set, and a boot: __GL_SHADER_DISK_CACHE_PATH=<path> is not a folder and cannot be made one line says when it could not. HOS_DRIVER_CACHE_FOLDER=0, in the environment or triforce_env.txt: nothing is made, as before. The driver files its cache by the program's file name: the Linux binary stays triforce (tests/test_driver_cache_folder.py pins nx2/build.py's name), and __GL_SHADER_DISK_CACHE_APP_NAME is never set (host/hos_main.c driver_cache_folder) |
RX_VK_PCACHE_CARRY_PROJECT=0 |
The early drop of a carried pipeline cache (gpu/vk/pcache_carry.h). When the stage libraries are built into a cache carried over a stamp change, every 32nd program of the warm's order is built first, the others waiting for it, and the cache's growth over that sample, per program, times all the programs, is where it ends at this rate. With at least 1500 libraries in the sample, a projected growth of at least twice the room it had when they began (its cap, or the bound, less its size then) drops the carry at once, exactly as past its limit (not written, .nocarry, the driver's part built again into a fresh cache), a few minutes in rather than when it gets there: an update whose file was built by an older translator misses nearly every library and filled the cache for 34 minutes before it was let go. The sample is spread over the whole order, not its head: the notes' programs go first and the rest in the program cache's file order, and hits and misses come in stretches of it, so a head that misses while the rest hits would have been dropped for nothing. The notes' programs wait for the sample (a few minutes cold). The log says the pipeline cache carried over a stamp change would grow to about N MB at this rate. The compute pipelines' pass and the precompile keep the look past the limit alone. 0: dropped only once past its limit, and the warm in its own order, as before |
RX_VK_PCACHE_MAX_MB=<MB> |
The bound on the pipeline cache's file, mkw_vk_pipelines.bin (gpu/vk/pcache_bound.h): a file over it is not read (the cache starts empty and the next save writes a new one), and data over it is not written (the file keeps its last save). Unset: an eighth of the PC's RAM, 2048 MB at least and 8192 MB at most. 0: no bound, as before |
RX_VK_PCACHE_LIBS_ONLY=1 or 2 |
(Triforce, 11-22, the performance audit's PIPE-78, after Source A's and Source B's; gpu/vk/pcache_libs.h) Off unless set. 1: when a fresh pipeline cache file begins (none read for these shaders), on NVIDIA's own driver with 20 GB of RAM or less, 512 MB or more in the driver's own cache folder (GLCache) and the stage libraries kept in our cache, the file keeps the stage libraries and the compute pipelines alone: whole graphics pipelines are left to the driver's cache and there is no play file, so a file of ~650 MB instead of 1.1-1.6 GB is read and held. Recorded in <file>.lean for that file's life (a full file stays full until the next fresh one); not decided in a start that only prepares. vk: pipeline cache: libraries only (...). 2: lean at every fresh file whatever the PC (the lab's). Whole pipelines then load 3-4 times slower from the driver's shared, capped cache (gpu/vk/vk_draw.cpp pcache_libs_decide, build_graphics, pcache_play_open) |
RX_VK_PCACHE_CARRY_MB=<MB> |
(Triforce, 11-18) The carry of the pipeline cache's file over an update that changed the translation (gpu/vk/pcache_bound.h carried): a file for other shaders is read all the same when it is no larger than this (1536 MB unset), leaves room under the bound for as much again and the PC has 31 GB of RAM or more (Windows), so the driver finds what it compiled for the shaders that did not change (AMD's driver keeps no cache of its own for these). 0: never carried, the rule of 11-14 alone |
RX_VK_PCACHE_PLAY_FILE=0, RX_VK_PCACHE_FOLD_MB=<MB> |
The pipeline cache's play file (gpu/vk/pcache_play.h, NX2navi's play cache): once the preparation is done, what a run compiles goes into a second cache with a file of its own, mkw_vk_pipelines_play.bin beside the first (a creation asks the first cache without compiling, then the play cache), and a save writes that small file; mkw_vk_pipelines.bin is written only when the preparation built into it. Before, a save after a few new pipelines wrote the whole file again (2.6 GB at the owner's start after its precompile). At a start whose play file has reached RX_VK_PCACHE_FOLD_MB (64) it is folded into the first cache, that session builds into it as before, and its first save writes it and removes the play file. Needs pipelineCreationCacheControl. 0: no play file, as before |
RX_VK_PCACHE_OWN_PASSES=0 |
(Triforce, 11-22, the performance audit's PIPE-95, after Source A's) The back end's own compute passes (FSR 3.1's dozen and its HDR output pass, the anti-aliasing's, the texture converters') are made with a bare creation into the main pipeline cache, as before. The default makes them the way a dispatch's pipeline is made (gpu/vk/vk_draw.cpp shared_cache_compute, cached_compute; gpu/vk/pcache_play.h): the main cache asked without compiling, a miss compiled into the play cache, a driver fault caught (the pass is then not made). Bare, they grew the main cache by a little, whose file is written in play only after 64 MB of growth, so they waited for the exit's save of the whole main file (650 MB fresh, 2 to 3 GB with the stage libraries), and an exit that cut that write short had them compiled again at the next start, inside the first upscaled frame. Without a play cache (no pipelineCreationCacheControl, or RX_VK_PCACHE_PLAY_FILE=0) only the guard is new |
RX_VK_WARM_SAVE_MIN=<minutes> |
(Triforce) Checkpoint saves of the pipeline cache during the shader preparation's long builds (gpu/vk/warm_checkpoint.h, tests/test_warm_checkpoint.py): while the driver's part (the stage libraries, about two hours cold on an RX 7900 XT) and the precompile build, mkw_vk_pipelines.bin is saved every 10 minutes once at least 1000 were built since the last save, so that a restart, a crash, a power cut or a kill goes on from the last checkpoint (what it saved comes back as hits) instead of from nothing. Each goes through the preparation's own save: the file's bound, a carried session's cap with its history kept open as a stopped one's (RX_VK_PCACHE_CARRY), the file written whole with its .for and .base; it is left out while a copy of the cache would not fit in the RAM available with 2 GB to spare or the disk lacks its size and 1 GB (asked again a minute later), fetched with room for what is built meanwhile, written to the disk before it takes the old file's place, given up when the window is closed or Setup's Cancel is pressed (the stop's own save writes the cache), due only while the part moves (a stuck one goes silent), and it does not count the part as made (the next start still runs it). Beside the file, .own says it holds this part's pipelines alone, so that a part over the file's bound after a crash ends as a new file over the bound, not as an older build's file made again from nothing. The log says vk: the driver's part so far saved for a restart: N MB in X s. Not on Intel unless RX_VK_PCACHE_PLAY_SAVE=1 (its driver crashed fetching the cache while pipelines were built with it); RX_VK_PCACHE_PLAY_SAVE=0: on no card. 0: saved at the end alone, as before |
RX_VK_PRECOMPILE_SAVE_S=<seconds> |
(Triforce, 11-22, the performance audit's PIPE-23, after Source A's; gpu/vk/precompile_save.h) A precompile that keeps its pipelines and built for this many seconds or more (30 by default, at most a day) saves the pipeline cache before the title, and says what that wrote: vk: precompile: N s of building: the pipeline cache saved before the title (... KB in ... ms), or why nothing was. It was first saved in play (present 300, after 32 more builds; on Intel only at a clean close), so a crash, a kill or a power cut early in play cost the whole build again at the next start. The save is the play file's alone while there is a play cache (gpu/vk/pcache_play.h): the main file, 2 to 3 GB with the stage libraries, is not written before the title. Not when the game went on while workers still build, after a stop, or in a start that only prepares (those save by themselves); the precompile that keeps nothing saves before its record, as before. Also: a preparation without stage libraries counts the compute pipelines it builds into the main cache for that file's save, and saves the cache at its end before its record says the part is made (it ended unsaved). 0: none of this, as before (gpu/vk/vk_draw.cpp precompile_end_save, prepare_compute_pipeline, prepare_run, pipeline_cache_save) |
RX_VK_FETCH_BOUNDS=0 or 1, RX_VK_NAN_BITS=0 or 1, RX_VK_GATHER_OFFSET=0 or 1 |
The translation's vendor and driver workarounds (gpu/vk/vk_vendor.h) off or on for one run, whatever the GPU; the log's vk: vendor fixes line says which are on. By default: out-of-bounds texel fetches answered with 0 on every GPU but NVIDIA's; NaN tests on a value's bits on AMD's older Windows shader compiler (RX 5000 and RX 6000); gathers nudged by 1/512 of a texel on AMD's and Intel's drivers. They change the shaders' translation (one preparation of the shaders) |
RX_VK_NAN_SELECTS=0 |
(Triforce, after NX2navi's e38f42a, issue #156) Where the NaN tests are made on the bits (RX_VK_NAN_BITS: by default AMD's older Windows shader compiler, RX 5000 and RX 6000), a float select of a constant whose bits are a NaN (an integer mask the translation types as a float) is also made a select of the bits, so that compiler cannot fold it into stray black or white blocks (gpu/vk/spv_nan_select.h: 32-bit selects, and 16-bit ones in a module that has a 16-bit integer type). It is applied where a module is made (make_module), outside the translation stamp: no program is translated again, nothing changes on any other card, and on those cards only the modules that have such a select are new to the driver's caches. So that those are compiled before the game rather than at their first draw or dispatch, the driver's part of the preparation, the light precompile's record and the predicted pipelines' record have a stamp of their own there: the first start on those cards goes through them once more, everything but those modules coming back from the caches (the variants on the driver's part's skip list are carried over). RX_VK_NAN_SELECTS=0 leaves the selects as they are (the NaN tests on bits stay). The log says vk: NaN selects: module <crc>, <n> float select(s) of a NaN constant made select(s) of the bits for the first four modules and every 64th |
RX_VK_VB_RANGE=0, RX_VK_MESH_VB_REBIND=1 |
A draw's vertex streams (vk_draw.cpp draw). RX_VK_VB_RANGE=0: all 16 bound again whenever one changed, as before v0.6.0 (by default only the ones that changed, vertex_bind_range). RX_VK_MESH_VB_REBIND=1 (off by default: about 3% at the Market in the lab, and its tickets not reproduced): after a mesh pipeline's bind the next vertex draw binds all 16 streams again with their strides (by default they stay as they were bound, as before: a mesh pipeline has the strides static, and its bind leaves them undefined for the next pipeline that has them dynamic, as it does the topology; tests/test_draw_binds.py) |
RX_VK_MIRROR=0, RX_VK_MIRROR_MB=<MB> |
No VRAM mirrors of the game's memory pools (on for discrete cards); their budget (unset: by the card, gpu/vk/mirror_budget.h: a quarter of the video memory on a discrete card over 4.5 GB, at most 3 GB; an eighth on cards of 4.5 GB or less and on integrated GPUs up to 6.5 GB; the log's vk: VRAM mirrors' budget line. =768 is what a 6 GB card had before) |
RX_VK_MIRROR=0, RX_VK_MIRROR_MB=<MB> |
No VRAM mirrors of the game's memory pools (on for discrete cards); their budget. Unset, the budget goes by the card (gpu/vk/mirror_budget.h): a quarter, at most 3072 MB; an eighth on cards of 4.5 GB or less and on integrated GPUs up to 6.5 GB. Discrete cards between 4.5 and 6.5 GB had the eighth before 11-21: RX_VK_MIRROR_MB=768 is a 6 GB card's old size. (Triforce, 11-22, the performance audit's MEM-51) Without mirrors (RX_VK_MIRROR=0, Intel's integrated GPUs) the replay no longer notes what only a mirror's write-back reads (gpu/vk/vk_memory.cpp wb_notes_off: the report words of memory_cpu_owned, the written pages of shadow_written_to and guest_cpu_wrote): those lists grew to 65,536 words and 8 million pages, were dropped and grew again. No switch of its own: with mirrors on everything is noted as before |
RX_VK_DEMOTE_QUICK=0 |
A pool the CPU and the GPU both write is tried in guest memory (vk_memory.cpp demote_trials); by default a trial whose GPU time a frame is over 3 times its baseline and 5 ms more, after 3 frames or more, ends then, settling or measured, and is judged as a slower one is (mirrored again, measured again: gpu/vk/demote_watch.h). 0: every trial runs its 10 settling and its measured frames, as before (in the owner's logs, some twenty frames of 100 ms for a pool at 106 ms against 7.4) |
RX_VK_IMPORT_CHUNK_MB=<MB> |
The game's memory is imported in whole chunks of its address space, 16 MB each (0: by the game's own pools). (Triforce, 11-22, the performance audit's MEM-16, after Source A's) Unset, the chunk is 4 MB where the mirrors are on and whole on an NVIDIA card (NVIDIA before Turing by default, a card without sparse residency buffers, RX_VK_MIRROR_PIECES=0): a whole mirror copies all of its import into video memory, the padding too, and Source A measured about a quarter less mirror memory with 4 MB for about half again as many imports. With the mirrors in pieces, without mirrors, and on AMD's and Intel's cards it stays 16 MB (an import stalled the replay 20 to 75 ms on an AMD card). The log says vk: imports in chunks of N MB once. An imports-ahead file written at 16 MB is read as it is. 16: as before on every card |
RX_VK_IMPORT_AHEAD=1 or 0 |
On by default with NVIDIA's driver (=0 off). Off for test12 to test14: the GPU hung at the title in 6 of 12 lab runs; the cause, the game's freed pages decommitted under an import the background thread had not finished (bg_held), is closed and the lab's A/B with it was clean in 10 of 10 (gpu/vk/import_ahead.h). The ranges of the game's memory a run imported on a binding's own thread (8 to 17 ms each on an RTX 5090), whole as they were imported (their span over the game's pools included; the first version kept 16 MB chunks, which a binding across their ends imported again as one), are kept in triforce_imports_ahead.txt beside the game, at most 256, and the next runs import them on the background import thread as soon as the game's pools reach them, 4 at a look, at each change of the pool table and every 8 submissions (gpu/vk/import_ahead.h), each range once a session, and none while the PC's RAM is low (under 3 GB available, or a tenth of the RAM: the RAM's rule gives idle imports back then, and the two took turns on the same ranges in the owner's test9 session). A file of the first version's chunks is read as it is. Unset: off (it was on with NVIDIA's driver only, as RX_VK_ASYNC_IMPORT is); 1: on any card; 0: off. (Triforce) A race that fits the hang is closed since: the host decommitted the game's freed pages under an import the background thread had locked and not yet put in the pool table (vk_memory.cpp bg_held; RX_VK_BG_IMPORT_HOLD=0: not, as before, for the A/B); it stays off until a lab A/B with =1 hangs no more. The log's vk: imports ahead lines count them and name the ranges sent, vk: the game's pages ... are freed under a background import the frees that window met; the stall line's "pools imported where bound" is what is left |
RX_VK_IMPORT_TOUCH=0 |
Off: the pages of a range of the game's memory are not read before the driver imports it. On by default, on Windows, for the imports made on the background thread (gpu/vk/import_touch.h): the driver locks a range's pages inside vkAllocateMemory, faulting in the untouched ones, and a queue submit from another thread waits for it; the ranges imported ahead are up to 1 GB. Read first, outside the driver, the allocate of the 288 to 752 MB ranges went from 16 to 93 ms to 4 to 13 ms on an RTX 5090, and the longest queue submit beside an import in play from 71 to 93 ms to 10 to 12 ms. The log's vk: import lines give a slow import's parts: the first 12 of a session, and the first 48 of 64 MB or more. |
RX_VK_IMPORT_LEAVING=0 |
(Triforce, 11-22, after Casual Gamer's #dev-fixes post) The game's freed pages under an import already given back whose memory is not freed yet (an evicted pool, a retired pool's import given back) are discarded or decommitted, as before. By default they are zeroed in place, as under a live import (gpu/vk/vk_memory.cpp memory_guest_imported, imports_leaving_overlap): the driver keeps those pages locked until the GPU is past them, and a discard there lost the device (v0.4.0 on a 16 GB laptop: 2 tours of 5 without, 0 of 53 with). The log says freed under an import still being given back for the first 8 and every 64th (tests/test_import_leaving.py). |
RX_VK_KEEP_RETIRED=1 or 0 |
A retired pool's import (a pool merged into a larger one) kept for the session (1) or given back once the GPU is past it (0; gpu/vk/vk_memory.cpp retired_imports_give_back). Unset: given back on Linux and with NVIDIA's driver, kept on Windows with AMD's and Intel's (device losses right after they went back there, issues 17, 309, 571). (Triforce, 11-22, after Casual Gamer's #dev-fixes post) Unset, those kept are given back all the same past the import rule's high mark of the system heap's budget (RX_VK_IMPORT_HIGH, 85%) or for a minute after an import was refused for want of room (gpu/vk/mem_parts.h retired_pressed; the log says retired imports given back after all): on a Radeon 780M the retired imports filled that heap, and 24.9% of the draws were left out for want of their pools (0 with it; refused imports 16 -> 1). =1 keeps them always, as before. |
RX_VK_CAP_SPARE_MB=<MB> or 0 |
The submit-time capture's spare buffers, kept for the next captures (12 at most, gpu/vk/vk_memory.cpp cap_spare_max), held to that many MB; 0: up to 768 MB, as before. Unset: 32 MB on a card the driver allows 6.5 GB or less, and (Triforce, 11-22, after Casual Gamer's #dev-fixes post) on a PC of under 20 GB of RAM (gpu/vk/mem_parts.h spare_capped; the log says capture buffers: 32 MB of spares at most): on a 16 GB laptop the spares held ~0.45 GB that Windows paged out and in again, capped 10-18% fewer page-ins. Not on AMD's cards, where a capture buffer made anew costs about 100 ms: they keep their spares |
RX_VK_IMPORT_RAM=1 |
The imports' second trigger (gpu/vk/vk_memory.cpp imports_give_back): with the PC's RAM short (under 1.5 GB available) every import unbound for ~10 s of play is given back, up to 1 GB a pass. (Triforce, 11-22, after Casual Gamer's #dev-fixes post) Off unless set: a 16 GB PC has under 1.5 GB available nearly all the time, so it fired every ~20 s and the imports it gave back came straight back (690 to 1216 imports in a 13-minute tour). The system heap's trigger (RX_VK_IMPORT_HIGH) stays as it is. |
RX_VK_KEEP_RETIRED=wait, RX_VK_RETIRED_REFUSED=1 |
(Triforce, 11-22, the performance audit's MEM-21, after Source A's; gpu/vk/retired_give_back.h; off unless set, not yet run in the game) A pool remade larger is retired, and once the GPU is past it its import is pinned RAM nothing binds. Unset, as before: given back at once on Linux and with NVIDIA's driver on Windows, kept for the session with AMD's and Intel's on Windows (given back at once there, an Arc B390, an Ally X and an RX 6600 lost the device right after); RX_VK_KEEP_RETIRED=0 gives back at once and any other value keeps, as before. wait, on any driver: given back RX_VK_RETIRE_SECS (30) seconds after the pool retired, RX_VK_RETIRE_MIN_SECS (2) while the system heap is past 85% of its budget; with it the imports given back and not freed yet are left out of what the pressure give-back (RX_VK_IMPORT_HIGH) reads. RX_VK_RETIRED_REFUSED=1: also the retired pools whose mirror was refused (RX_VK_NO_MIRROR_POOLS, a pool over 1 GB, video memory refused), never given back before on any OS; on with wait unless =0. The vk: imports: line every 1200 mirror epochs says how many retired pools are still imported |
HOS_CRASH_THREADS=0 |
Off: a crash report has the faulting thread alone. On by default, on Windows (host/crash_threads.h): a crash or fatal error's report ends with one CRASH: beside it, thread ... line for every other thread, its host stack as module and offset, taken at the report's start on a helper thread; the threads running code come first, then the ones waiting in the system. For the crash while a save loads, which reads an object whose memory holds something else: the lines say what the other threads were doing. |
HOS_CRASH_TEST_S=<seconds> |
(the lab's) A host thread reads address 8 that long after the start: a crash report on purpose, to look at one from a run in the game (its other threads' lines above). Not for play. |
EDEN_NX2_GM_LEAN=1 |
Only the global-memory helpers a program's instructions call are put into its SPIR-V (gpu/vk/eden/shader_recompiler/backend/spirv/gm_lean.h). A stage that reads or writes through a pointer no storage buffer was tracked to carried every helper, six and for a storing stage eighteen, each with a search over every storage buffer in it. Off unless set: the SPIR-V is then what it was. An EDEN_ name: each setting has its own program cache. The translator's files are in the translation stamp, so a build with this code translates every program again once, whatever the switch says. |
RX_VK_UPLOAD_AGAIN_MS=<ms> |
A texture uploaded before whose memory the game wrote again, met by a draw after the frame's uploads took this long (16), is uploaded at the next frame instead; its last bytes are drawn meanwhile, at most 8 frames in a row (gpu/vk/upload_owed.h later). New textures are never left so (theirs is RX_VK_HOLD_MS's rule). 0: every one at once, as before. The log's "left for the next frame" lines and the stall line count them. RX_VK_UPLOAD_AGAIN_FRAMES=<n>: a texture's upload is left so at most that many frames in a row (2: its last bytes drawn a frame or two at most; 8: as before). With 16 ms nothing was ever left in the lab's runs (the frames with re-upload bursts took 9.8 ms of uploads); 3 spreads a burst over the frames after it, its textures a frame or two late meanwhile, which is why it is not the default |
RX_VK_UPLOAD_TORN=0 |
(Triforce, wp18-flash) A texture uploaded before, 1 MB or more, whose storage the CPU has rewritten since the copy its re-upload would read (a capture's copy of one of its whole pages, every 16th and the last, differs from guest memory at the draw's look) keeps its last bytes for that frame and is uploaded at the next frame with what that frame's capture took (gpu/vk/upload_torn.h): a copy taken while the game was still writing the texture was test29's white frames at the Market after a tour (BC6H bytes passing through, decoded to bright colours the bloom spread over the picture). At most one frame in a row, and not for a texture found so in the two presents before (one the CPU rewrites every frame is uploaded as before). Not a dispatch's upload. 0: uploaded at once, as before. The log's re-uploads of storage the CPU rewrote since its capture lines count them, those found and those left (with 0 too: the measure of how often a copy may have been taken mid-write) |
RX_VK_REUPLOAD_EARLY=0 |
The textures the CPU keeps rewriting (uploaded again from its writes twice or more within 120 presents, 1 MB or more, sampled in the frame or the one before, not drawn into by the GPU) are looked at once on the replay thread before a parallel replay's segments begin, after the dry pass, their uploads in the recording before the segments: not made by a segment under the recording lock, where the other recording threads queued behind them (lab S2 after a tour: 4 to 12 such uploads of 28 to 84 MB in ~13% of the frames, the descriptor time 24 ms over the threads against 3). 0: the segments' looks alone, as before. The log's textures the CPU keeps rewriting, looked at before line says how many and how long (gpu/vk/reupload_early.h) |
RX_VK_ZERO_HOLES=0 |
(Triforce, Linux, on by default; =0 as before) The all-zero check of a big texture's storage (32 MB or more: cleared on the GPU when every byte is 0; RX_VK_ZERO_UPLOAD=0 turns the check off) reads only what the guest memfd holds data for (lseek SEEK_DATA and SEEK_HOLE, gpu/vk/guest_holes.h), not its holes: a page the game never wrote reads as zero, but a read through the shared mapping made it RAM (the 288 MB shadow map at each Hyrule Field arrival, 200-300 ms on a Steam Deck). Where the window is not a memfd, or a seek fails, the whole storage is read. The is all zero and is not all zero lines say how many MB were read. =0: the whole storage always |
RX_VK_UPLOAD_SAME=0 |
(Triforce) A texture uploaded before whose storage the CPU wrote again is checked against the bytes its image holds (gpu/vk/upload_same.h): the units of its storage the writes reached (each level's and layer's GOB-block rows, as its upload reads them) whose bytes hash as at their last upload are not uploaded, and when that is all of them nothing is. The upload of the rest reads the copy the check hashed, so that what is kept is what the image got; any other upload and any GPU write forget it. Textures of 16 MB or less uploaded on the CPU (block-compressed, or under 8 MB), not sparse; one whose checks find nothing the same 4 times in a row is uploaded unchecked for its next 64 re-uploads. Lab S2 after some tours: the game rewrote a few big BC textures the Market samples with the bytes they had, 40 to 60 MB every 4 to 5 frames (the Market at 62-78 fps against 83-96, ~26 GB of uploads in its stay). 0: every re-upload made as before. The log's re-uploads checked against the bytes their images hold line says what it looked at, found the same and uploaded. RX_VK_UPLOAD_SAME_KEEP=0: the check hashes every byte it looks at; by default a page the submit-time capture keeps a copy of is hashed once and its hash kept with the copy until a capture copies other bytes into it (about half of those textures' pages passed through other bytes between two captures) |
RX_VK_UPLOAD_SAME_ASTC=0 |
(Triforce) ASTC textures decoded on the GPU (kept as RGBA8, BC3 or BC1; 2D only) are checked too, by RX_VK_UPLOAD_SAME's check: one unit a layer, its levels from the first one the image keeps, which is what the GPU decoder stages of a layer a write reached; the staging reads the copy the check hashed. Lab S2's Market after a tour: the game rewrote such textures with the bytes they had (1536 x 1536 ASTC 5x5 of 11 levels, 768 x 768 kept as BC3, 512 x 512), staged and decoded again unchecked, about 1.4 GB in 10 s (90 fps down to 72, the 1% low 57 to 33). 0: ASTC re-uploads made as before, every layer a write reached staged and decoded. The re-uploads checked line says what of it was ASTC; the re-uploads not checked line every 600 frames counts the re-uploads made without the check, by route and by why |
RX_VK_TWIN_SAME=0 |
(Triforce) The parallel replay's twin (a texture an earlier segment samples that a later segment of the same submission uploaded, uploaded again in the earlier segment's uploads so that its draws see the bytes as submitted) uploads only what that submission's uploads into the image asked for (gpu/vk/upload_same.h note_upload; the whole storage when one of them was whole or the image was made again), and where every unit it reads has a hash kept by RX_VK_UPLOAD_SAME's check, reads a copy of them hashed as copied: when the copy holds the bytes the hashes are of, the hashes are kept. Before, the twin uploaded the whole storage and, unchecked, forgot the hashes the later segment's checked upload had just kept, so the next rewrite of the same bytes was uploaded again, the twin with it, every few frames: lab S2's Market after a tour, about 97% of what was still uploaded unchecked in those loops, up to 6.9 GB in one stay. 0: the twin uploads the whole storage and forgets the hashes, as before. The log's the parallel replay's twins line every 600 frames counts them, the bytes uploaded against the whole, and how many kept the hashes |
RX_VK_UPLOAD_EARLIEST=0 |
(Triforce) A parallel replay's upload of a texture, made by the worker of a later segment of the submission while an earlier one is still being recorded, is recorded into the init command buffer of the earliest segment still being recorded (submitted before that segment's uploads and commands; gpu/vk/upload_earliest.h, vk_texture.cpp UploadRedirect). Every segment before it has ended its recording and no longer samples the texture, and every one from it on finds the upload at or before its place in the queue, so no earlier segment uploads the texture again (the twin, RX_VK_TWIN_SAME): it is uploaded once, the same bytes. Lab S2's heavy Market loops (round 48) uploaded 2.1 GB of twins in their last minutes, the big streamed or new textures each uploaded once by a later segment and again by an earlier one; those twins took the frames' upload budget (RX_VK_UPLOAD_NEW_MB, RX_VK_UPLOAD_NEW_MS), and the new textures after them were left for the next frame, the picture held. Only an upload staged from the CPU as it is recorded is moved: not one read on the GPU (the GPU unswizzle, from the pool) or decided from live memory (the all-zero clear), which in the earlier segment's init would run before a segment between writes that memory on the GPU. Not for a texture the GPU drew (its contents are the GPU's; the CPU's writes over it, RX_VK_CPU_OVER_GPU, keep their own path) or a sparse one: those keep the segment's own uploads, and the twin. The uploads' GPU time in an init command buffer is not in the segments' GPU time. 0: every upload in its segment's own uploads, the twin as before. The log's uploads recorded into an earlier segment's init command buffer line every 600 frames (with 0 too) counts them and the bytes, and how often and how long a segment's end waited for its init lock, each segment's own, held while such an upload (or a new image's first layout change) is recorded into its init (its submit waits as long) |
RX_VK_SHADOW_STAGE=0, RX_VK_CAP_UNCACHED=1 |
(on by default; the row is Triforce's, 11-22, with the performance audit's MEM-39) A capture buffer asks for cached host memory, but a driver can hand out write-combined memory, which the CPU reads at about 0.3 GB/s. Such a capture's texture pages are copied into a staging block in ordinary memory first, and to the buffer from there, and every CPU read of them uses the staging (gpu/vk/vk_memory.cpp capture_make, cap_page_bytes): the shadow's copies, and since MEM-39 the RX_VK_TEX_SAME compare of each copied texture page with its shadow copy, which still read the buffer. RX_VK_SHADOW_STAGE=0: no staging, every read from the capture buffer, as before. Where the buffers are cached (the 600-take shadow staging line counts them) nothing is staged and nothing changes; the first buffer that is not cached is logged with its memory type. Lab only: RX_VK_CAP_UNCACHED=1 asks for the capture buffers as memory written in order, which is uncached where the driver has such a type, to make the slow case on any PC, and the RX_VK_LAB_AB knob texsamemap reads the buffer in the compare in its phases |
RX_VK_SHADOW_KEEP=0 |
(Triforce) A texture page the submit-time capture takes with the bytes its shadow copy holds (the copy the uploads read, RX_VK_TEX_SAME's compare) keeps that copy as it is, not copied again, its kept hash with it (gpu/vk/shadow_prev.h). Lab S2's Market after some tours: about half of the ~400 texture pages a capture took, six captures a frame, held their copy's bytes. Only for a page the capture takes once; any other is copied as before, and the shadow holds what the capture holds either way. 0: every page copied, as before. The log's texture shadow (600 takes) line counts the pages compared, left, given back and copied |
RX_VK_SHADOW_PREV=0 |
(Triforce) A texture page the capture takes with other bytes keeps the copy it had, and that copy's hash, beside the new one (gpu/vk/shadow_prev.h Prev), and a capture that brings those bytes back gives it back, hash and all: no copy, and the re-upload check after it finds the hashes kept (lab S2's Market after some tours: the other half of those pages went back and forth between two versions, and a check hashed each again after every change, 0.2 to 0.3 ms a frame). A kept copy that does not come back within 8 changes of its page, or within 64 captures, goes; at most 64 MB are kept. 0: none kept, a changed page copied over as before. The texture shadow line says how many are kept and how many went |
RX_VK_SHADOW_VERS |
(Triforce) The copies a texture page keeps beside its own in the shadow (gpu/vk/shadow_prev.h Vers): RX_VK_SHADOW_PREV keeps one, and a page whose captures bring more than two versions (A, B, C, A every few frames) is copied again for every version but the one before the last. 2 to 4 keep that many, newest first, and a capture that brings any kept version's bytes takes that one back, the copy it had becoming the newest, so each version a page cycles through while it is still among the kept copies is copied once: 4 KB a version, under the same 64 MB cap. Unset or 1: one copy, as before. The texture shadow line counts the pages given a copy of their own, one before it, and two or more before |
RX_VK_SHADOW_CHECK=1 |
(Triforce) Each texture page RX_VK_SHADOW_KEEP or RX_VK_SHADOW_PREV left uncopied is compared with the capture's copy again after the capture is taken, and the hashes kept with the shadow's copies are hashed again: the texture shadow check line every 600 captures counts the copies that differ and the hashes that are not of their bytes, both of which must be 0. Slow: for the lab's checks. Unset or 0: not checked |
RX_VK_HOLD_MS=<ms> |
Hold the last picture (gpu/vk/present_hold.h, on by default): a new texture a draw samples after the frame's uploads took their budget (RX_VK_UPLOAD_NEW_MS, RX_VK_UPLOAD_NEW_MB) is uploaded at the next frame, the dummy drawn in its place, and that frame is not shown: the window gets the last complete picture again, the Insert menu, the counters and the notices drawn over it, until a frame is drawn with every texture complete. The game runs on underneath. No frame generation makes a frame from a held one, and the one shown after a hold starts its history anew (and the temporal upscalers theirs). <ms>: the hold's bound (250); at it the rest are uploaded at once and the next frame is shown whatever it holds, and no hold comes for 120 presents (twice as long after each hold at its bound that follows, up to 1920). 0: no hold, no new texture left for later: the one frame that takes them all, as before. The log's vk: hold: lines, the stall line and the 600-frame line count them |
RX_VK_HOLD_PIPELINES=0 |
A frame with draws or dispatches left out because their program, pipeline or compute pipeline was still being made is held as one with a texture still owed its bytes (RX_VK_HOLD_MS's hold, with its bound and its rests; NX2navi's frame hold, gpu/vk/pipe_wait.h): by default the window keeps the last complete picture instead of showing one that lacks a pass. 0: such frames are shown, as before |
RX_VK_UPLOAD_NEW_MS=<ms>, RX_VK_UPLOAD_NEW_MB=<MB> |
The new textures' budget a frame while the hold is on: once the frame's uploads took 12 ms or 64 MB, a new texture is left for the next frame (ASTC ones too; the frame's first upload always goes). 12 ms keeps an area change's frames near 16.7 ms with their draws and memory sync; 64 MB is what the GPU copies or decodes in a few milliseconds, so that no frame leaves it a backlog. 0: that half of the budget off |
RX_VK_UPLOAD_SPLIT_MB=<MB> |
A new layered ASTC texture whose texels are more than this (128) has its first upload in parts while the hold is on, the texture's layers over at most 6 frames (gpu/vk/layer_split.h): its draws sample the dummy and its frames are held until the last part is in; for a dispatch or at the hold's bound what is left goes at once. In the owner's test7 session one 1365 x 1365 x 90 texture kept as BC3 took one frame's upload command buffer 114.8 ms of GPU time. 0: whole, as before. The stall line counts the parts |
RX_VK_DUMMY_GEN=0 |
A frame that left textures for later makes every texture view a draw resolved stale (destroy_gen), as before. By default only the looks that resolved to the dummy for want of their texture are (texture_dummy_generation, vk_draw.cpp texture_view_of); the stall line counts the views resolved anew |
RX_VK_VIEW_KEEP=0 |
Any texture's end (an eviction, a dead render target let go, a texture made BC3 from BC1, the compaction moving one) makes every texture look of every recording thread stale, and each is resolved anew when next met (the slot, the cache, the view, under the parallel replay's lock), as before. By default a thread that finds the destroy generation moved keeps the looks of the textures whose views did not go: those are noted by their creation number before the generation moves (gpu/vk/view_keep.h, vk_draw.cpp texture_view_of); never a look of no texture or no view, nor a flat texture's 3D copy. More than 1024 gone since a thread's last pass: all resolved anew. The log's vk: texture looks kept lines count them, the stall line the views resolved anew. After NX2navi's tex_gen_undo |
RX_VK_DESC_KEEP=0 or check |
The per-binding reuse of a draw's descriptors (gpu/vk/desc_keep.h, on by default): a draw that builds its descriptors takes, for each sampled texture, user uniform buffer, stage's constants and read-only storage buffer, what the program's last draw on that thread resolved it to, while everything it was resolved from is the same: the texture's handle, its slot's registration, the samplers', no texture destroyed or made again, no texture left for later and the same submission; the buffer's address and size, no inline uniform update, no pool moved or mirror made, the same recording. 0: every descriptor resolved, as before (so also with RX_VK_NO_DESC_REUSE, RX_VK_SAMPLER_CACHE=0 and the descriptor diagnostics). check: every descriptor resolved too, and one that comes out otherwise than what was kept for the same inputs is counted and logged (vk: descriptor reuse check): the way to try the rules. The frame statistics' a frame's descriptors line says how many were resolved and taken, how many pushes were whole, of the changed bindings or of nothing, and how many sets were written, through a template, or bound again |
RX_VK_DESC_SIG=0 or check |
The whole-draw skip by the signature of a draw's descriptor inputs (gpu/vk/desc_sig.h, on by default with the per-binding reuse): a draw whose bindings moved, of the program whose descriptors its last draw pushed in that command buffer, first reads what each of them is resolved from (a texture's handle and its slot's version, a user uniform buffer's address and size, a read-only storage buffer's address and size words, a driver bank's stage generation) and the stamps the per-binding reuse gives each kind; when that equals the signature the pushed descriptors were built from, and their build kept every one, the build and the push are left out (a build would take each of them again and push nothing). Push programs only, of the kinds the per-binding reuse keeps: not those with storage buffers they write, tables, texel buffers or storage images, not the mesh fallback or RenoDX's. 0: built, as before. check: built too, and one that comes out otherwise than what is pushed is counted and logged (vk: descriptor signature check). The frame statistics' a frame's descriptor signatures line says how many draws read theirs and how many were kept whole |
RX_VK_DESC_COUNTS=0 |
(Triforce, 11-22, the performance audit's DESC-22, after Source A's; gpu/vk/desc_counts.h) build_descriptors walks the program's stages at every build to sum its buffers, images and texel views, as before. The default keeps the three sums packed on the program (Program::desc_n, 10 bits each, in the padding after ready so that sizeof(Program), which the shader caches' stamp holds, stays what it is): stored at the program's first build once it is translated, read at every later one. A program with more than 1023 of a kind walks at every build. A build that went by kept counts and had one of its three vectors move is made again, walked, and that program walks from then on (one log line). The lab's knob descwalk (RX_VK_LAB_AB) is this switch in its phases |
RX_VK_PROF_ALL=1 (the dispatch's pick clock) |
(Triforce, 11-22, the performance audit's DESC-30, after Source A's and Source B's) Every profiling scope timed, and with it the clock pair around each compute dispatch's program pick, as before. Unset, the pick's time for the stall line is the change of the thread's exactly timed nanoseconds across the pick (its slow path is timed by PROF_EXACT), so a pick the memo answers reads no clock. DESC-30 has no switch of its own, the results being the same: besides the pick, taau_key answers from its list parsed once (it wrote the key out and walked the list as text several times a dispatch), RX_VK_LOG_PUSH formats its key only when set, the first-pipeline clock is read only when there is one to make, and texture_frame fills RX_VK_LOG_BAKED's list only for that switch (read once) and finds its largest textures by a partial sort. The lab's knob diagold (RX_VK_LAB_AB) puts all of it back in its phases (gpu/vk/vk_draw.cpp dispatch, taau_key, dispatch_diag_old; gpu/vk/vk_texture.cpp texture_frame) |
RX_VK_LAB_AB=e_draw:<ns>, e_dispatch:<ns>, d_present_after:<us> |
(Triforce, 11-22, the performance audit's REPLAY-51, after Source B's; lab knobs of the in-run A/B, gpu/vk/lab_ab.h, nothing without the variable) The d_<site> knobs wait once a frame; e_draw and e_dispatch wait the knob's nanoseconds at every draw or dispatch, first in draw() and dispatch() so the profiles leave it out, on whichever thread records, and count each wait. The frame's change against the time spun says how much of that path is on the frame's critical path (200 ns at about 3,050 draws a frame is 0.6 ms of work). A phase's end logs vk: lab A/B: phase e_draw:<ns> over: with its waits and ms a second. d_present_after is d_present's control: the same wait just after the present's drain(0), where d_present is just before it. Pin RX_VK_PARALLEL with the e_ knobs (the log warns otherwise): Automatic moves draws between threads. Off: one relaxed load a draw. tests/test_lab_ab_each.py |
HOS_OOT_SHADOW_STEP=<n> |
(Triforce, 11-21, the performance audit's GAME-05) The game gives each nearby character or object a square depth shadow map sized by its size on screen, 384 to 1,920 a side, so while anything moves each frame asks for depth textures of sides not seen before. The one read of the side is rounded up to a multiple of <n> (a power of two up to 256; 64 when not set): 25 sizes, which come round again, so the render targets' pool serves them. A map gets at most 63 more texels a side; its projection does not change. 0 or 1: the game's own side, as before (host/oot_shadow_step.h, host/oot_shadow_step.c, nx2/oot_patches.py patch_shadow_step) |
HOS_SHADOW_BUCKET=<step> |
(Triforce, 11-21, the performance audit's TEX-85) The game sizes each character's shadow map (square, D32, one level) from the camera's distance every frame and places a frame's render targets first fit in its target heap, so a map a few pixels larger moved every target after it, and each moved one is a new image to the renderer. Such a map wider than 384 is answered the storage size and alignment of the next multiple of the step up (384: sides 768, 1152, 1536, 1920); the texture's own size and layout do not change, only the bytes the game sets aside, by 1.8 to 5.3 MB a map. 0: every map its own size, as before. Not set: 384, and 0 where the target heap is pinned (HOS_RT_POOL_MB, or a 5120-wide output's 900 MB). The log says the step and counts the stepped answers (host/shadow_slot.h, host/nvn_native.c shadow_slot_layout) |
HOS_OOT_TEX_COMPACT_MS=<n> |
(the lab's) The game's texture data compaction (its aglTextureDataMgr::Compaction thread moves a texture's data in the game's heap, a cycle of about 18 frames; idle in a fresh Market, at work at every ask after a tour, where each move is a texture at a new address for the renderer to capture and check): at most one cycle started every n ms. -1 (a test): none started. Unset or 0: as shipped. The cycles started are logged every 10 s either way ("oot: texture compaction in"). host/oot_tex_compact.c, tests/test_oot_tex_compact.py |
HOS_OOT_TEX_ASK_MS=<n> |
(Triforce) The game's texture data manager asks for a compaction round (above) at most once every n ms: its step, every frame, asks whenever no round is asked for and its flag says so, and each ask let through can start a round that moves a texture to a new address. Unset (or not a number): 1000. 0: every ask, as shipped. off: none. A round started always finishes; an ask held back is made again at the next step. The asks let through and held are logged every 10 s ("oot: texture compaction asks in"). host/oot_tex_compact.h, nx2/oot_patches.py patch_tex_ask, tests/test_oot_tex_compact.py |
RX_VK_TEX_WARM=1 |
Textures made and uploaded ahead, while the frames are light (gpu/vk/tex_warm.h; off unless set). A texture is made and uploaded where a draw first samples it, and the frame's budget for that (12 ms, 64 MB, the picture held) applies only to targets drawn in the frame before, so an area's first frame, whose targets are new, takes every texture of the area at once: 350 to 800 uploads of 250 to 390 MB, 100 to 180 ms, in the lab's tours. With the switch every registered slot is noted, and at the start of a game's submit that follows a light frame (under 400 draws and dispatches: a loading screen, a menu) the noted textures, 8 frames old at least, are made and uploaded, 6 ms a frame. Bytes the game writes afterwards are uploaded again by the write marks, as before. "vk: textures made ahead in light frames" counts them. tests/test_tex_warm.py |
RX_VK_TEX_WARM_LIST=1 or 2 |
(Triforce, 11-22, the performance audit's TEX-23, after Source A's; off unless set, and only with RX_VK_TEX_WARM=1) The textures made ahead by a list of what was drawn (gpu/vk/tex_warm.h). Every registered slot made ahead needs the 40% rule, and on an 8 GB card that rule stops the warming at once. With the switch, a BC or ASTC texture a draw uses within 90 s of the game making it is learnt: its shape and eight 64-byte samples of its bytes, at its storage's address. The list is kept beside the game as triforce_textures_drawn.bin (32,768 at most; saved every 300 presents when it changed; a file cut short or of another version is not read). At a light frame the ripe slots the list names are made while the textures and 256 MB more fit their budget and the render targets' pool is not being given back; 1: the others after them, by the 40% rule, once no noted slot is left ripe; 2: the listed alone. The look itself learns nothing. "vk: textures made ahead by the list" counts listed, unlisted, learnt and no-room. Unset or 0: every registered slot as above. Not measured: lab proof first (the entry's own default is 1). tests/test_tex_warm_list.py |
HOS_MEM_LIMIT=1 or <MB> |
(the lab's) The game's memory held to what it is told it has, as the console holds it. The game is told 9809 MB, but nothing was refused until the PC's own commit ran out, and it holds 11.7 GB by its own count in a fresh Market and 13.5 GB after a tour (the mem: census line), with its GPU heap within 15 MB of full and its texture compaction running every frame. 1: AllocateMemoryPages and MapPhysicalMemory are refused past the 9809 MB, and UsedMemorySize is the game's count; a number above 1: refused past that many MB. Unset or 0: as before. What the game does when refused is what the lab is to find out. host/hos_mem.c, tests/test_mem_limit.py Refused, the game asks again thousands of times, each ask a region taken and freed; a region of the game's own freed with none of its pages in it is no longer discarded (hos_region_discard_needed), and the regions it frees with pages in them are discarded with the thread's virtual core given up. Those two were the stutter when walking with the limit on: in a three-area lab run the game's own part of the frame was over 8 ms in 24% of the frames before and in 0.3% after (as without the limit), 63.8 fps to 100.0. =1 does not fit this build: the heap takes 6.9 GB of the 9.8 and an area's resources need 4.7 GB and more, so a save's load can starve and stay on its loading screen for good (the owner's, 2026-11-20, read with the hang watch's stacks: the game at 9,807 MB, its load threads idle). Use a size in MB: 12800 loaded and played four areas without reaching it. |
RX_VK_DESC_SET_KEEP=0, RX_VK_DESC_TEMPLATE=0 |
A program over the driver's push limit (32 descriptors on NVIDIA's, AMD's and Intel's drivers) has a set written for each draw that builds its descriptors. By default a set whose descriptors are all as those of the last one written for that layout in the recording is bound again instead, while no texture was destroyed or made again and no pool moved, and a set written is written through the program's descriptor update template (Vulkan 1.1). (Triforce, after NX2navi's desc_template) A program within the push limit has its descriptors pushed whole (in a new command buffer, or after another program at its bind point) through a push descriptor template of its own (vkCmdPushDescriptorSetWithTemplateKHR, one a program and bind point, from the same entries and packed array as a set's), not with the write structs the driver walks one by one; a push of the changed bindings only keeps its write structs. The frame statistics' a frame's descriptors line counts the pushes made through it. With RX_VK_RECORDER the packet copies the packed array (gpu/vk/vk_recorder.h). RX_VK_DESC_SET_KEEP=0: a new set each time; RX_VK_DESC_TEMPLATE=0: sets written and pushes made with the write structs; both as before |
RX_VK_CREATE_NEW_MS=<ms> |
While the hold is on, a sampled texture seen for the first time once the frame's makes took this long (8), or its uploads their budget, is not made yet (vk_texture.cpp create_later): the draw samples the dummy, the frame is held, the next frame makes it. The frame's first make always goes; never a dispatch's. 0: made at once, as before (a texture left for later was made all the same). The stall line counts the textures made, their time, those not made yet, and the images made |
RX_VK_UNSWIZZLE_MT_MB=<MB> |
A block-linear level unswizzled on the CPU is split over several threads (a thread for each 2 MB, 8 at most) from this size (4); 16: from 16 MB, as before |
RX_VK_PROGRAM_READAHEAD=<n> |
After a draw reads a program from the program cache itself, or takes one read ahead, workers read the next n programs (32) and keep them made for the draws that come to them, 512 at most (gpu/vk/program_readahead.h). 0: none, as before. The log's vk: programs from the cache lines and the stall line count them |
RX_VK_PROGRAM_READ_UNLOCKED=0 |
A draw that reads a program from the program cache itself, or waits for one the read-ahead's worker is reading, lets the shaders' lock go meanwhile, so that the replay's helper threads go on picking their own programs (they queued behind it: "the program picks waited 169 ms for the shaders' lock" at the Market's arrival); a second draw of that program waits for the first's result, and the record stays listed until it is read (gpu/vk/program_read_once.h). A program's release waits until no pick has the lock let go. 0: read and waited for under the lock, as before. The stall line counts the waits for another draw's read, and the picks' waits to take the lock again with their waits for it |
RX_VK_STAGE_CODE_CACHE=<MB> |
What a program pick made of a stage's bytes (the control section and the code area read from guest memory: its code key, the instructions lowered to Maxwell) is kept by those bytes, 64 MB at most, the least recently used going first: a program object met for the first time whose stages' bytes were met before (the game makes them again at loads) takes a copy instead of decoding them again under the shaders' lock (gpu/vk/stage_code_cache.h; an entry is taken only for the same bytes, byte for byte). The save's load-in frame said "the program picks read the stages' code 45.6 ms": a stage was some 60 us to read and decode, and is 3 us to find. 0: none, each stage decoded again for each program object, as before. The log's vk: the stages' code read for the program picks lines count them |
RX_VK_STAGE_CODE_LAZY=0 |
A program pick reads the stages of a program object it meets for the first time without lowering their code: their keys, NVN stages and headers (what finds the program) come from the control sections and code areas, and the code is lowered (and kept, RX_VK_STAGE_CODE_CACHE) only when the pick translates a variant. A program found in memory, read ahead or in the program cache was made from stages that lower (its key names them); one not found has its stages lowered before it is translated, and should one not lower, the pick starts again from those that do: the program it was before (gpu/vk/stage_code_cache.h). The save's load-in frame lowered every stage of each program object met, 48 of a stage's 60 us, for programs all prepared before the title. Not with RX_VK_REJECT_STAGES, RX_VK_REJECT_KEYS, RX_VK_OLD_LOWERING, RX_VK_DUMP_NATIVE or RX_VK_DUMP_FAILED, which act in the lowering. 0: each stage lowered as it is read, as before. The log's vk: the stages' code read for the program picks lines count the stages read without lowering and those lowered since |
RX_VK_STAGE_CODE_UNLOCKED=0 |
A program pick reads the stages of a program object it meets for the first time (guest memory, their keys, the stage code cache) with the shaders' lock let go, as a draw's own read of a program (gpu/vk/program_read_once.h: a program's release waits until no pick has the lock let go), so that the replay's helper threads go on picking their own programs meanwhile; two picks of one object at once each read it, and the first list put stands. 0: read under the lock, as before. The stall line's "the program picks read the stages' code" counts the read and the lock's taking again |
RX_VK_PROGRAM_ORDER=0 |
Each session writes the order its draws first needed their programs in (read from the program cache, or translated), the first 4096, into triforce_program_order.bin beside the cache now and then (this session's first, then those of the sessions before it has not met). The next session's read-ahead workers, from the first draw on (the title and the file select), read those programs in that order whenever no draw asks them for anything, the whole order, and keep them made apart from the shelf until a draw takes them (RX_VK_PROGRAM_ORDER_KEEP below; gpu/vk/program_order.h): the save's load-in frame read some 100 programs on the draws' threads before. Not with the RAM low. 0: neither read nor written, as before. The stall line says why the draws read what they still read themselves (named by no order, read ahead and let go before, not read ahead yet) and how many they took in this order; the log says once when the whole order has been gone through, and how many programs it keeps |
RX_VK_PROGRAM_ORDER_KEEP=0 |
A program read ahead in the last sessions' order stays until a draw takes it, whatever the draws meet meanwhile, and nothing in the order is passed by: the workers read all of it (4096 at most) while the title and the file select stand still, and a program a draw's ask read that the order names is kept with these, not on the shelf, which lets its oldest go. Only a RAM gone short lets them go (all of them). The pipelines' warm keeps its window: the first 512 kept and not taken are read with it, those beyond without, each warmed as the draws take warmed ones (the nearest first). Some 40 to 50 KB a program packed: the owner's order of 2411 programs some 100 to 120 MB, 4096 at most some 200 MB. The owner's test37 session (SDR, where the order's sessions were HDR Native) took another path through the order and its load-in frame read 115 programs itself, 64 of them read ahead and let go as behind where the draws were, 51 passed by. 0: the rules before: 512 at most, each until the draws are 256 places past it (where the draws are: the middle place of the last 16 programs they needed first), what lies behind not read |
RX_VK_PROGRAM_READAHEAD_NOTES=0 |
The read-ahead's next programs are those after it in the pipeline notes' order (the order earlier sessions first built their pipelines: an area's programs lie together), 4 workers, the compute programs too (in the order play first dispatched them, triforce_computes.bin), and a full shelf lets its oldest go; the program cache file's order only for a program neither names. 0: the file's order (since the shaders are prepared before the title, the preparation's), one worker, no compute programs, and nothing more read once 512 wait, as before (test16's file select load took 7 of some 600 programs read ahead that way) |
RX_VK_PIPELINE_WARM=0 or 1 |
Where the precompile keeps no pipelines (the RAM spared) and the fast pipeline link is on, the read-ahead's worker that has just read a program makes, before any draw can have it, the stage libraries of the pipelines the pipeline notes name for it (asked of the caches only: one the driver would have to compile is left to its draw) and links them; the draw takes the link made in place of linking its own, and the whole build follows as before (gpu/vk/pipe_warm.h). At most 32 notes a program variant, 512 links held for draws that have not come (the oldest let go beyond) and 1024 libraries no draw has had; nothing made while the RAM is low or short, and what is held goes back to the driver while it is short. 0: none, as before; 1: the libraries only. The log's vk: pipelines made behind the draws lines count them |
RX_VK_PIPELINE_WARM_FOLLOW=1 |
Off by default (test19: the lab's tour showed no gain). 1: the warm follows the draws: a program read within 64 places (in the notes' order) after one the draws consumed in the last 2 s has its libraries made and linked, one within 192 its libraries only, one farther (or once the draws stopped taking) nothing; and the libraries no draw has had are kept up to 2048, the oldest let go beyond (with the links made from it), so the bound never stops the warm (gpu/vk/pipe_warm.h, test18: 2266 links made, 276 taken, the libraries at their bound from the load on); it spends at most 250 ms of the workers' time a second (500 saved up), and never makes again a library it let go. Off: every program read is warmed whole and the libraries stop at 1024, as before |
RX_VK_COMPUTE_WARM=1 |
Off by default (test19: the lab's tour showed no gain). 1: where the precompile keeps no pipelines, the read-ahead's worker that has just read a compute program play dispatched (triforce_computes.bin) makes its compute pipeline, asked of the caches only, as its first dispatch would; the dispatch that takes the program has it. One a program while it waits on the read-ahead's shelf, destroyed when the shelf lets the program go and given back while the RAM is short; once a program variant a session. Off: each compute pipeline is made at its first dispatch, as before |
RX_VK_PIPELINE_ORDER=0 |
Each session writes the order its draws first needed their pipelines in (a new one, or one the precompile kept that no draw had), the first 4096, into triforce_pipeline_order.bin beside the pipeline notes now and then, from the presents on a thread of its own (this session's first, then those of the sessions before it has not met). Where the pipeline warm runs (RX_VK_PIPELINE_WARM), the next session finds each one's note before play and the warm makes, for a program variant the read-ahead has read, the pipelines that order names for it and no other (32 at most a variant; the notes' other pipelines are not made then, and the warm does not follow the draws): their stage libraries asked of the caches and their links, held for the draws by their place in the order, 1024 at most (beyond, the farthest ahead goes, and none is made farther), and 2048 libraries no draw has had at most. Where the draws are: the middle place of the last 16 pipelines they needed first; a link held 512 places behind it goes with the libraries only it held, and none is made there (gpu/vk/pipe_order.h): the save's load-in frame made 86 to 92 ms of pipelines on the draws' threads, the warm's links from the notes let go before the load came (lab round 37: 1964 made, 54 taken). The first session after this writes the file; the next one has it. 0: neither read nor written, the warm from the notes as before. The stall line counts the pipelines new to the draws, those linked ahead (of them in this order), and the links and stage libraries the draws made themselves; the log's vk: pipelines made ahead in the order lines the rest |
RX_VK_PIPE_AHEAD=<places> |
(Triforce, 11-22, the performance audit's PIPE-81, after Source B's: its first step; gpu/vk/pipe_ahead.h) A count, nothing built: with the last sessions' pipeline order in use (light mode), each pipeline the draws first need is counted by its place against where the draws are: within this many places ahead (1024 unset, at most 4096), further ahead, behind, not in the order, and those within the window that the warm had linked. A line every 600 presents while it grows (vk: pipelines first drawn, by their place in the order: ...) says whether a builder of whole pipelines just ahead of the draws would meet a third of them or more, the entry's rule for building it at all. 0: not counted (gpu/vk/vk_draw.cpp order_met) |
RX_VK_VRAM_MB=<MB> |
The texture cache's budget as a fixed size, whatever the card. Unset: on a card the driver allows more than 8.5 GB, no size (RX_VK_TEX_PRESSURE); on a smaller one 45% of what the driver allows; with RX_VK_TEX_PRESSURE=0 70% of it above 8.5 GB, at most 6 GB (the rule before) |
RX_VK_TEX_PRESSURE=0 or =<pct> |
(Triforce, after NX2navi's TEX_VRAM_PRESSURE) On a card the driver allows more than 8.5 GB, with VK_EXT_memory_budget, not an integrated GPU, without RX_VK_VRAM_MB and without a quality preset whose budget applies, the texture budget follows the live use instead of the fixed 6 GB: textures go once the driver's count, less the free space in the blocks they can take back, is past 80% of what the driver allows now, the least recently used first, each unused 2 s or more, 64 a pass, down to 2% under that line (gpu/vk/tex_pressure.h); the 90% and 97% rules and the compaction's lines stay. While the system's commit is low the fixed size comes back (RX_VK_TEX_COMMIT_FREE_MB). 0: the fixed size, as before; <pct>: that line (50 to 95). The log's vk: texture budget line at the start says which, and the vk: VRAM: line every 600 presents the budget (by live use: what the textures may hold before the line) and the line |
RX_VK_TEX_KEEP_TAKEN=0 |
(Triforce, after NX2navi's TEX_KEEP_TAKEN) While VRAM is short, a texture uploaded from memory that the game let go 30 presents ago goes first (RX_VK_LET_GO_PCT); one the game has taken back before waits 8 times the longest it stayed let go before a take-back, when that is longer (gpu/vk/tex_pressure.h): made again, the frame that wants it draws the dummy (NX2navi: Kakariko's haze gone every few seconds). The eviction by age still takes it. 0: the 30 presents alone, as before |
RX_VK_TEX_COME_BACK=0 |
(Triforce, after NX2navi's pause for drops that come back) Where the budget follows the live use: when in 240 presents 64 or more textures the line let go went and half or more of them were made again within 600, the line stands aside for 600 presents, doubled at each such period up to 7200; a period with fewer back ends the doubling (gpu/vk/tex_pressure.h ComeBack). The 90% and 97% rules and the compaction's lines still hold meanwhile. The log says when a pause begins. 0: no pause |
RX_VK_TEX_STEP=<n> |
The live textures one pass of texture_sweep over the budget lets go of at most (64 where the budget follows the live use; the render targets drawn over since do not count), the rest at the next look two presents on, not ten. Set, on any card, the fixed size's too; 0: no step, one cut as before |
RX_VK_TEX_COMMIT_FREE_MB=<MB> |
Where the budget follows the live use: while less of the system's commit than that is free (the default: the larger of 4 GB and a tenth of the limit, NX2navi's), the fixed size is the budget again (Windows charges a discrete card's memory to the commit, and an allocation that fails there ends the game). 0: never. Not on Linux |
RX_VK_TEX_COMMIT_RESERVE_MB=<MB> |
(Triforce, 11-22, the performance audit's OS-05, after Source A's; off unless set, not measured here) On any card, while less of the system's commit than that is free (the page files' room to grow counted in, below), the textures are held to what they hold less the shortfall, never under 1 GB, as the 97% rule takes its excess: the cache's passes give blocks back before an allocation is refused at Windows' commit limit (HOS_COMMIT_WAIT_MS waits such a refusal out). Source A's is 2560, on by default there; one vk: commit limit near line when it begins and ends and every 600 presents while it holds. Not set or 0: no cut, as before. Not on Linux (gpu/vk/commit_room.h, gpu/vk/vk_texture.cpp texture_frame) |
RX_VK_TEX_COMMIT_GROWTH=0 or =1 |
(Triforce, 11-22, OS-05) Whether the room the page files still have to grow (each one's largest size less its size now, a drive's page files capped together by its free space, asked of Windows at most once a second) counts as free commit, for the reserve above and for RX_VK_TEX_COMMIT_FREE_MB's fall-back alike: Source A's first rule, without it, retired textures for 90 minutes while a page file Windows manages could still grow. Read only while less is free than the higher of the two lines. Not set: counted where RX_VK_TEX_COMMIT_RESERVE_MB is set, else not (as before); 0: never; 1: also without the reserve (vk_texture.cpp commit_now, page_file_growth) |
RX_VK_SWEEP_ALL=1 |
Every texture of the cache ordered by its last use for every pass of vk_texture.cpp texture_sweep, as before. By default a pass under the budget (every 10 presents, and the dead render targets' passes between them) orders only the textures it can take: those the GPU drew and those the game let go; the others it passes over all the same. Over the budget every texture is ordered. The log's "passes for the dead render targets between the looks" line says what a pass costs |
RX_VK_TEX_RATE_HIGH=0 |
The texture eviction's waits (vk_texture.cpp texture_sweep: 60 presents unused over the budget, 30 after the game let a texture go, 600 or 3600 for one the GPU drew, the compaction's 600 and 1800) count presents above 60 a second, as before. By default they count their seconds at any rate up to 480 a second (gpu/vk/present_rate.h, after NX2navi's M19): at the Market's 94 a second "60 presents" were 0.64 s. Below 60 they count seconds unless RX_VK_TEX_RATE_LOW=0. The log says the first time a run goes above 68 a second |
RX_VK_TEX_DETAIL=full, reduced or low |
The texture detail for one run, over the Insert menu's Texture detail row: whole textures, or the large ones without their largest level, or without two (gpu/vk/tex_detail.h). Unset, the row decides, and its Automatic goes by what the driver allows: full from 10,240 MB, low under 6,144 MB, never full on an integrated GPU |
RX_VK_TEX_BC1_PARTS=0 |
(Triforce, 11-21, the performance audit's TEX-50) An ASTC block of two to four partitions with a colour endpoint mode each is refused unread by the opaque-texture scan, as before, so a texture with one stays BC3. The default reads those modes as the decoder does (their bits below the weights) and takes the block as opaque when every partition's mode has no alpha and is not HDR; the blocks the decoder takes for an error are still refused. The kept as BC1 log lines count the blocks read this way. And a first start, with no options file, now keeps opaque textures as BC1 as the row's default says: it started at off (gpu/vk/astc_opaque.h, vk_menu.cpp tex_bc1_at_start) |
RX_VK_TEX_BC1=0/1 |
Opaque ASTC textures kept as BC1 instead of BC3 for one run, or not, over the Debug tab's Opaque textures as BC1 row (on by default since options_version 5): a texture the renderer keeps as BC3 whose every block the GPU decoder writes opaque is encoded as BC1, half the video memory, the same texels (gpu/vk/tex_bc1.h, gpu/vk/astc_opaque.h). One whose memory later holds blocks with alpha, or that a copy on the GPU writes, becomes BC3 for good; the log counts both |
RX_VK_ASTC_BC_ALL=1 or 0 |
Large decoded ASTC textures are kept as BC3, a quarter of RGBA8: the coarse blocks (6 x 6 texels and up) from 2 MB as RGBA8 (RX_VK_ASTC_BC_MB), the finer ones (UI, characters) only from 64 MB. Where the driver allows under 8.5 GB the finer ones go from 2 MB too (gpu/vk/astc_bc_policy.h). (Triforce, 11-22, the performance audit's TEX-12, after Source A's) And on every integrated GPU, whatever it is allowed: its allowance is a share of the system's RAM (a 16 GB handheld reported 10,361 MB), so it kept those textures as RGBA8 in RAM the game needs too. The log says all large ASTC textures kept as BC3, with an integrated GPU there. 1: on any card; 0: the finer ones as RGBA8 on any card, which is an integrated GPU allowed 8.5 GB or more as it was before |
RX_VK_BC_SMALL_LAYERS=<n> |
(Triforce, 11-21, the performance audit's TEX-09) The layers one run of the ASTC-to-BC3 re-encode takes for a level of 1024 x 1024 or less, 1 to 8, through a small scratch of its own (1024 x 1024 x 8, 32 MB, and 4 MB more of output buffer). Unset: 8, and 1 on AMD's cards until the picture is checked there (one layer a run was for dark lines between Hyrule Field's ground tiles on an RX 6600). A terrain array of 90 layers and 11 levels was about 990 runs of a decode, an encode, a copy and three full barriers; its levels from the second down are now about 210. Each layer of a run is copied by a region of its own. No small scratch at reduced or low texture detail. 1: none, every run one layer, as before (gpu/vk/bc_scratch.h, vk_texture.cpp bc_small_layers, bc_encode_into) |
RX_VK_BC_LAYERS=<n>, RX_VK_BC_SCRATCH_FULL=1 |
The layers one run of the GPU's ASTC-to-BC3 re-encode decodes and encodes, 1 to 8 (1: with more, an array's layers past a run's first came out wrong in the smaller levels, dark lines between Hyrule Field's ground tiles). (Triforce, 11-21, the performance audit's TEX-10) The 2048 x 2048 scratch, its output buffer and the second scratch are made with that many layers, 20 MB a layer (36 with the second), not with 8 whatever a run used: 140 of 160 MB were held and never written. RX_VK_BC_SCRATCH_FULL=1: 8 layers, as before (gpu/vk/bc_scratch.h, vk_texture.cpp bc_scratch_layers) |
RX_VK_TARGET_POOL_MB=<MB>, RX_VK_POOL_IDLE=<presents>, RX_VK_TARGET_POOL_TRIM=0 |
(Triforce, 11-21, the performance audit's TEX-29) The render targets' pool gives a dead target's image to the next target of its shape. Its bound is a twelfth of what the driver allows, 256 to 768 MB (<MB> sets it; 0: no pool); it was a fixed 256, which starved at 2560 x 1440. It is trimmed oldest first, whatever the shape. A shape nothing has taken from the pool goes after 8 presents (RX_VK_POOL_IDLE), one that was taken before after 120. Above 90% of the allowance it holds half its bound, above 97% nothing, unless a floor of the targets' blocks is kept. RX_VK_TARGET_POOL_TRIM=0: emptied above 90%, as before; with RX_VK_TARGET_POOL_MB=256 RX_VK_POOL_IDLE=120 the pool as it was. The 600-present line vk: render target images has the reuse, the bound and the tier (gpu/vk/target_pool.h, vk_texture.cpp pool_trim) |
RX_VK_STAGING_BURST_S=<seconds> |
(Triforce, 11-22, the performance audit's TEX-28, after Source A's) The uploads stage their bytes in host-visible arenas of 64 MB, and each present gives the idle ones back beyond what is kept: 256 MB, 64 MB where the driver allows 6.5 GB or less (RX_VK_STAGING_KEEP_MB=<MB>), and any nothing staged into for 30 s (RX_VK_STAGING_IDLE_S=<n>, 0: kept). An arena is taken again only once the GPU is done with the submission that read it, so frames that stage in a row use two in turn, and with 64 MB kept the one that had its turn was freed at every second present of a load and made again the present after. An idle arena staged into in the last 2 seconds now stays while the arenas add up to 256 MB (gpu/vk/staging_keep.h), unless VRAM is over 90% of the allowance. Nothing changes where 256 MB are kept anyway. The log's vk: memory: line counts the arenas made so far and their time. 0: as before |
RX_VK_WROTE_REGIONS=0, =2 |
(Triforce, 11-21, the performance audit's TEX-02) Every sampled, uploaded texture is asked once an epoch whether the GPU wrote into its storage since its upload, which took a lock and walked the map of written ranges; nearly every answer is no. One bit a 2 MB region of GPU addresses, set where a GPU write ever reached, answers no without the lock when the storage touches no set region; a set bit asks the map as before. 0: the lock and the walk each time; 2: a check, both asked and compared, the count of disagreements (which must be 0) logged (gpu/vk/wrote_regions.h, vk_texture.cpp texture_gpu_wrote, gpu_wrote_into) |
RX_VK_PREDICT_BG_STREAM=0 |
(Triforce, 11-21, the performance audit's PIPE-83) The builder of the predicted pipelines behind the game (predict_background: the starts after a translator or driver update, resting while the game is in play) keeps its plan as record numbers and reads a pipeline's two notes from triforce_pipelines.bin when it builds it, each worker through its own handle; it held every note (~27 KB) and a full note of every predicted pipeline until it ended, about 1 GB. The same programs and pipelines are built. 0: all of them held, as before (gpu/vk/predict_stream.h, vk_draw.cpp predict_background) |
RX_VK_PREDICT_CHECK=0, =2 |
(Triforce, 11-22, the performance audit's PIPE-68, after Source B's and Source A's; gpu/vk/predict_check.h) On unless 0. The predicted pipelines are built once for the driver's own cache and a record says which programs are done; a driver can lose them all the same (NVIDIA's cache cap, a cleared cache folder, AMD's Windows driver keeping a third). At a start whose record says all are built, the builder's idle thread, after its delay and only while the frame shown is a light one, samples up to 12 of them spread over the plan: each built for the driver's cache alone and timed, then once more as the warm reference; cold is a first build over 4 times the second and 3 ms more, and the sample ends once its majority is decided. Cold: the record is removed, so they are all built again behind the game at light frames, and <notes>.predicted.check takes a strike for these shaders and this driver; cold again after that, the log says this driver does not keep them and no later start checks. Warm: the strike is forgotten. 2: checked at every start, a recorded stop too. Also counted: the builds in play of programs the plan predicts that took over 20 ms (vk: predicted pipelines: N builds in play of predicted programs took over 20 ms, at most every 10 s while it grows). 0: neither the check nor the counter, as before (gpu/vk/vk_draw.cpp predict_check_cold, predict_background, predicted_play_build) |
RX_VK_PREDICT_TYPES=1 or 0 |
(Triforce, 11-22, the performance audit's PIPE-44, after Source A's; gpu/vk/predict_types.h) Unset: each predicted pipeline is built once for its program, by its key as play keys it (two predicted layouts that differ only in what is dynamic, a stride, gave the same pipeline twice): the same pipelines, fewer builds. 1: that, and the plan drops a predicted vertex layout whose attributes definitely differ from the program's vertex inputs (an integer input against a float attribute, or the other signedness, read from the vertex module's SPIR-V; scaled formats count as integers): such a pipeline is invalid. Off by default because it changes which pipelines are built, and it applies to a plan made after it is set (a plan is made once for the shaders). 0: every predicted pipeline built, as before. The predicted lines say how many were left out as built already, how many programs the programs' file did not lend, the notes of variants it has no shaders for and the layouts that did not fit (gpu/vk/vk_predict.cpp predict_pipelines, gpu/vk/vk_draw.cpp predict_first) |
RX_VK_DRAWN_PAGE_MAP=0 |
(Triforce, 11-21, the performance audit's TEX-21) A texture in a virtual pool is checked through its mapping, 64 KB a page, and its page map was recorded at its first check: one the GPU drew first had none, so once the game finalized it the first check took its whole storage as mapped since and uploaded it from memory over what the GPU drew (HUD labels and render targets blank after an area change, up to 15 MB an upload). The map is recorded at the first draw that says who drew it, and the later check gives only the pages mapped anew or written by the CPU. Not for a write that gives no reason (a clear, the movie upscaler). The log counts them. 0: at the first check, as before (gpu/vk/drawn_page_map.h, vk_texture.cpp texture_written) |
RX_VK_DEAD_SUM=0, RX_VK_DEAD_POOL_NOW=0, RX_VK_DEAD_MIN_UNUSED=3 |
(Triforce, 11-21, the performance audit's TEX-30) The frame's transient render targets, drawn over from another start: the other targets' parts over one are added up, each byte once, so one covered at its head by one target and at its tail by another, each under an eighth, is let go too (it was kept for good); it is dead after 1 unused present, not 3; and its image goes to the render targets' pool in the pass that lets it go, once the GPU is done with it, not at the next present. RX_VK_DEAD_SUM=0: judged one by one; RX_VK_DEAD_POOL_NOW=0: pooled at the next present; RX_VK_DEAD_MIN_UNUSED=3: three presents: each as before (gpu/vk/target_overlap.h ShiftedOver, vk_texture.cpp texture_sweep) |
RX_VK_ASTC_REUSE=2 |
(Triforce, 11-21, the performance audit's TEX-14, its first step; off when not set) When the game comes back to an area it makes its textures again, mostly at other addresses, and the same ASTC blocks are decoded and encoded again while the image made of them the first time may still be in VRAM. With 2 a new ASTC texture's blocks are hashed at its first upload (128 bits), the textures the game finalizes that were uploaded from memory and never drawn into are listed, and each new texture with a listed one's blocks and shape is counted: the log's decoded ASTC used again line says how many MB of images a copy would have stood in for, and what the hashing cost. Every texture is decoded as before. The copy itself is not built: the walk it was measured on would have reused 0 to 11 MB, and the audit asks for 500 MB on a tour before it is (gpu/vk/astc_reuse.h, vk_texture.cpp reuse_upload) |
RX_VK_KEEP_OBSOLETE=1 |
(Triforce, 11-21, the performance audit's TEX-43) A texture the GPU drew in one frame is kept after the game finalizes it, for being made again over that storage and sampled undrawn (the terrain's tiles; RX_VK_KEEP_FINALIZED_MB). One of 32 KB or more, in no virtual pool, whose storage the CPU has written three quarters of since the release holds nothing that memory holds any more: the sweep lets it go whatever the budget says, where only a draw over it did, and the game's own writes kept each for good (about 200 render target images an hour in players' logs). The log counts them. 1: kept, as before (gpu/vk/finalized_obsolete.h, vk_texture.cpp texture_sweep) |
RX_VK_SLOT_RETIRE=<presents> |
(Triforce, 11-21, the performance audit's TEX-76) The game draws each character's shadow map at a fixed address, sized from the camera every frame, and each size is a texture of its own: the ones before it, drawn over, waited 120 presents unused before the sweep took them. A depth target of one level and layer whose start a newer target of the same format and another size was drawn over since its last use goes once unused for <presents> presents, 16 when not set; nothing is written back, and its image goes to the render targets' pool. The log counts them. 0: after the sweep's own wait, as before (gpu/vk/slot_retire.h, vk_texture.cpp texture_sweep) |
RX_VK_COUNT_BY_TEXELS=1 |
(Triforce, 11-22, the performance audit's TEX-86, after Source A's) A texture the GPU samples in the game's own compressed blocks (BC, and ASTC where the log says vk: ASTC sampled natively) is counted by its whole blocks (gpu/vk/tex_count.h): a level is its width and height rounded up to blocks, times the block's bytes and the layers. It was counted by texels: a byte a texel for BC (twice BC1's and BC4's size) and the 16 bytes of an ASTC block for every texel (16, 64 and 144 times the size at 4 x 4, 8 x 8 and 12 x 12), so the texture budget let textures go for memory nothing held, and the first size estimate left out the top levels of arrays that fit. The count is still lifted to what the allocator gave. Decoded ASTC (NVIDIA's and AMD's desktop drivers) and the renderer's own BC3 and BC1 are counted as before. The log says once which count is on. 1: by texels, as before |
RX_VK_EVICT_STALE_FLUSH=1 |
(Triforce, 11-22, the performance audit's TEX-R404, after Source A's) Over the budget, the eviction writes each chosen texture the GPU drew back into the game's memory before it goes. The game draws its HUD labels inside the storage of a 1920 x 1080 target it no longer uses; when that target went, its old texels landed over the labels, which were then uploaded from them as noise. A write-back is now left out when another image the GPU drew overlaps the texture's storage and was drawn in a later frame than the texture's own last drawing (gpu/vk/evict_reason.h; one drawn in the same frame keeps it); the texture goes all the same. The log names the first 20 (vk: texture #... goes without its write-back) and counts them on the written back into their memory before eviction line. Nothing changes while no pass writes anything back (a card under its budget). 1: every chosen texture is written back, as before |
RX_VK_COMPACT=1, RX_VK_COMPACT_PCT=<50..90>, RX_VK_COMPACT_MB=<MB> |
VRAM compaction (off by default): the textures that are not render targets in a pool of their own, moved out of sparsely used blocks a few a present so that the blocks go back to the driver, and the texture budget holding the driver's count at that share of what it allows (85); the free space that starts a run (512; 192 while the count is over 90%) |
RX_VK_EVICT_EXCESS=0 |
(Triforce, on by default; =0, or the lab's knob noexcess, as before) With the compaction on, what the 90% and 97% rules ask of the hold's pass is their excess (gpu/vk/vram_compact.h rule_target, gpu/vk/vk_texture.cpp texture_frame): their budget less 64 MB, where the pass went down to 7/8 of it. Those budgets are the textures less the excess, not sizes: 62 MB over the 90% line on an 8 GB card took about 400 MB of textures, all on screen again within the camera's turn, made again, and over the line again. Over the budget's size (the fixed one, or the live line's) the pass still goes down to 7/8 of that size; with both, the lower |
RX_VK_COMPACT=1, RX_VK_COMPACT_PCT=<50..90>, RX_VK_COMPACT_MB=<MB> |
VRAM compaction (off by default): the textures that are not render targets in a pool of their own, moved out of sparsely used blocks a few a present so that the blocks go back to the driver, and the texture budget holding the driver's count at that share of what it allows (85); the free space that starts a run (192 while the count is over 90%). RX_VK_COMPACT_MB unset: (Triforce, 11-22, the performance audit's TEX-38, after Source A's) a sixteenth of what the driver allows, 64 to 512 MB (vram_compact.h default_min_free): 512 on a card that allows 8 GB or more, as before; 327 on a 6 GB laptop that allows 5,233 MB; 512 before the first look. RX_VK_COMPACT_MB=512: 512 on every card, as before. tests/test_compact_start.py |
RX_VK_MEMORY_PRIORITY=1 or <targets>,<textures> |
(Triforce, 11-22, the performance audit's TEX-47, after Source A's; off when not set) When a card is short of video memory, Windows moves some of the game's device memory to system memory, read over the bus from then on, and picks what goes. With the switch and a driver that has VK_EXT_memory_priority, the game ranks its memory: the render targets' blocks 1.0 (kept first), the sampled textures' 0.25 (moved out first), everything else the driver's own 0.5 (gpu/vk/memory_priority.h); <targets>,<textures> sets the first two, each from 0 to 1. The textures then come from their own pool also where it is not compacted (RX_VK_COMPACT), and a sparse texture's chunks name the textures' rank. The log says vk: memory priorities on with the three numbers, or that the driver has no such extension. Source A measured it on an RTX 4090 with the video memory taken by other programs: with 1.3 GB moved out, a median GPU frame of 24 to 29 ms against 109 to 179; with room on the card, no difference. Not run on a small card, and a driver may ignore it: off by default, and without the switch the extension is not asked for. 0, off, no or a value that cannot be read: off |
RX_VK_SKIP_COMPRESSED_OVER_RT=1 |
A compressed (ASTC, BC, ETC2/EAC) texture made over storage render targets used is not uploaded, as before: bosses and new enemies all blue the first time |
RX_VK_NO_WRITEBACK (set) |
GPU writes to mirrored pools are not copied back to guest memory (an experiment, for A/B) |
RX_VK_MSYNC_PASS=0, =1 |
(Triforce, 11-21, the performance audit's MEM-48) A mirror sync's pages that come from a capture's buffer go to the pool's VRAM mirror by the write-back diff's compute pass, one dispatch a sync, where they were copy regions of a page or a few each (700 to 1,300 a frame, each read over PCIe after the one before). A run not in whole words, a GPU without subgroup votes in compute and a sync whose chunk table finds no room keep the copies; a mirror written twice in one upload command buffer, once by the pass, gets a full barrier between. On for NVIDIA when not set; 1: on every GPU; 0: copy regions, as before. The log's mirror syncs' pass (600 submits) line counts dispatches, chunks, fallbacks and barriers; RX_VK_LAB_AB=nomsyncpass is the in-run comparison (gpu/vk/msync_pass.h, vk_memory.cpp msync_pass_add, msync_pass_flush) |
RX_VK_WB_FORGET_SORT=1 |
(Triforce, 11-21, the performance audit's MEM-61) At the end of each part with write-backs the write-back diff clears, for every page written since, the bit that says its pool's shadow knows the page. The three lists of such pages (the game's writes, the collection's, the replay's) were sorted first, thousands of pages a part, only so that the pool found for one page serves the next; the bits and the counts do not depend on the order, and the lists hold ascending runs as they come. They are no longer sorted. The log's forgetting the written pages took line gives the time. 1: sorted, as before (vk_memory.cpp shadows_forget_written) |
RX_VK_WB_DIFF=0 |
Write-backs copy every byte again instead of only what changed against a VRAM shadow (the diff is on by default; v2.0.9 and v2.0.10 had it off, issue 1161) |
RX_VK_LAZY_WB=1, =2 or =0 |
The lazy write-back for one run, over the Debug tab's Lazy write-back row (lazy_write-back=1; on by default since options_version 5; docs/lazy-writeback.md, gpu/vk/wb_lazy_state.h): a whole page of what shaders write into a mirrored pool that the CPU leaves alone is no longer copied back at every submission; its page has no access, and whoever touches it (the game's code or the host's, by a fault; a host call that hands it to the kernel; the GPU through the import) has it copied down first. Windows only. On AMD's driver the row alone leaves it off, as NX2navi did after games ended in play there; =1 turns it on anyway. =2 is the self-check: every copy is still made, the pages are protected and paid as if not, and each payment compares what it would have copied with guest memory: a MISMATCH at guest line is a page it would have got wrong. The log says vk: lazy write-back on (or why off) at the start, and every 600 submits vk: lazy write-back (600 submits): the MB not copied, the pages owed, the pages paid by a fault, a host call, a GPU read, a mirror given up and a recording's submit, the payments and their time, and what failed |
RX_VK_LAZY_PAYERS=<1..4> |
(Triforce, 4 by default; =1 as before) How many of the lazy write-back's payments copy at once (gpu/vk/wb_lazy_payers.h, NX2navi's wb_lazy_unlocked). A payment's copy goes onto the queue after everything submitted so far and its thread waits for it (0.5 to 3 ms each in the owner's sessions, up to 21 ms at a load); with one at a time, a second thread that touched another owed page, or the replay giving a mirror up, waited for the first one's copy to come back before its own went onto the queue. Each payment holds a slot of its own (a command buffer and a fence); the pages of two payments are never the same ones (gpu/vk/wb_lazy_state.h), and each copy still goes onto the one queue after everything before it. The 600-submit line vk: lazy write-back (600 submits) ends with the payments that waited for a free slot and the most slots in use at once |
RX_VK_GEN_SEED=<n> |
The page write generations (gpu/vk/write_gen.h) start at n and not at 1 (decimal, or hex with 0x; 2^62 at most). They are 64 bits; the 32-bit ones of earlier builds ran out after days of play, and textures and mirrors then kept old contents. RX_VK_GEN_SEED=0xFFFF0000 takes a play test across 2^32 within seconds: the log says the write generations start at and, at the crossing, this run has made 4294967296 write generations, and nothing in the picture should change there |
RX_VK_UPSCALE_OFF=1 |
(Triforce) The upscaler Off for one run: the game's gameplay upscale networks are not dispatched, their input is stretched linearly into their output (gpu/vk/upscale_off.h). Softer than the networks below 100%; only while the game's own upscaler draws (DLSS and FSR take the dispatch first). Not set: as before, the networks run, and on cards that run them on software multiplies the first one is stood in for. The lab's upoff phases switch it within a run |
RX_VK_STUB_SAME_SIZE=0 |
(Triforce, 11-22, the performance audit's GPUWORK-21, after Source B's and Source A's; gpu/vk/stub_same_size.h) On unless 0. A gameplay upscale network that cannot run (left out or not translated: RX_VK_NO_F16, a card or driver that cannot build it) is stood in for by its input drawn into its output (gpu/vk/vk_draw.cpp upscale_stub) also where the two are one size: 9dc98871eb7fc101, the network of Render resolution 100%, was declined as "no larger than its input" and skipped whole, a black 3D under the HUD. Both gameplay networks now take the typed upscale first (it reads the scene's shared-exponent picture and undoes the network's square-root encoding; it was the 3/4 network's alone), then the blit, which warns of wrong colours for both, then nothing. The picture is the upscaler Off's: softer, none of the network's anti-aliasing. Only where the network cannot run. 0: the decline, and the 3/4 network alone in the typed upscale, as before. RX_VK_NO_UPSCALE_STUB=1 still turns the whole stub off; RX_VK_FORCE_UPSCALE_STUB=2 sends every network through it, for a look |
RX_VK_DLSS=0/1/2, RX_VK_DLSS_PRESET=<letter>, RX_VK_DLSS_LOG=1, RX_VK_REFLEX, RX_VK_REFLEX_LOG=1, RX_VK_ANTILAG=0/1 |
NVIDIA DLSS and Reflex, and AMD Anti-Lag 2, for one run (=- on Reflex or Anti-Lag 2: its extensions not even enabled): the readme's NVIDIA DLSS section. RX_VK_DLSS_TRACE=<frames> logs one frame's large draws every that many frames, RX_VK_DLSS_DEBUG=motion shows the motion vectors, =alternate the game's own upscale every other frame |
RX_VK_FSR4=0/1/2, RX_VK_FSR_DIR=<folder> |
AMD FSR 4 for one run (0 never, 1 FSR 4, 2 its Native AA), and another folder for AMD's DLLs (not from hookshot_env.txt): the readme's AMD FSR 4 section. RX_VK_FSR4=1/2 and RX_VK_DLSS=1/2 go over the Upscaler row, a saved FSR 3.1 too where the engine they ask for runs; RX_VK_FSR=1 goes over them (one upscaler at a time; =2: FSR 3.1 as its Native AA, the 3D at full size). The DLSS trace and debug switches above apply to FSR 4 too, on the frame chain they share |
RX_VK_FSR4_DRS=1, RX_VK_FSR4_AUTO_EXPOSURE=0 |
(Triforce) AMD FSR 4's context as before, for comparing (gpu/vk/vk_fsr4.cpp make_context, gpu/vk/temporal_rules.h plan_context): RX_VK_FSR4_DRS=1 one context with FSR's dynamic-resolution flag for every render size from the start, where a fixed Render resolution otherwise gets a context of its own size without it (and the game's dynamic resolution one with it once the size first changes); RX_VK_FSR4_AUTO_EXPOSURE=0 its HDR contexts (Upscale before bloom, or an RGBA16F picture with RenoDX's HDR Native) without FSR's auto exposure. A creation or evaluation of DLSS or FSR 4 that fails leaves the game's upscale for 2 s and is tried again; the fourth failure in a row turns that engine off (the Upscaler row then shows Game and says so) until the row is set again |
RX_VK_SHARPEN_3D=0, RX_VK_FSR3_BOOST=0, RX_VK_UPSCALE_LOD_BIAS=0/<negative> |
(Triforce) For comparing with before (gpu/vk/sharpen_rules.h): the Sharpness row sharpens the 3D before the HUD with DLSS, DLAA, FSR 3.1 and FSR 4 (FSR 3.1's own RCAS, FSR 4's own sharpening, FSR 3.1's RCAS pass over DLSS's picture) and then nothing at the window; RX_VK_SHARPEN_3D=0 the finished picture at the window for every upscaler, the HUD with it, as before. RX_VK_FSR3_BOOST=0 FSR 3.1's sharpness the row's alone, without the share towards the most below three quarters of the output's width. RX_VK_UPSCALE_LOD_BIAS=0 no texture LOD bias while DLSS or FSR scales the 3D with jitter (unset: log2(render / output) - 0.5 in quarters of a level, so -1.5 at Performance, -1 at Quality and -0.5 at the Native AAs, on the wrapping, mipmapped textures of the draws into the scene at the upscaler's render size (or, in the frame the dynamic resolution steps, at the size the scene's camera is drawn at), never the shadow maps, captures, other passes or dispatches; the log says vk: texture LOD bias at each change); a negative number, such as RX_VK_UPSCALE_LOD_BIAS=-1 or =-1.5, that bias (-3 at most) in the same draws and only while an upscaler with jitter runs, for trying other values (the log says it once at the start) |
RX_VK_FSR4_FG=0/1/4 |
AMD's frame generation, the Frame generation row's AMD FSR (gpu/vk/vk_fsr4.cpp fsr4fg): 0 never in this run (RX_VK_FSR4=0 too, which keeps AMD's library unloaded); 1, as without it, the newest frame generation AMD's library lists for the card, FSR 4's where listed (RX 9000), else FSR 3.1's (3.1.6 on RX 6000 and 7000), the row naming it ("AMD FSR (3.1.6)") and the log the version in use; 4 FSR 4's alone, as before (FG-1) |
TRIFORCE_MENU_AHEAD=0 |
(Triforce) What the options' rows ask of NVIDIA's and AMD's libraries (whether DLSS, FSR 4 and FSR 4's frame generation run here: NGX's start, AMD's loader) asked at the options' open on the presenting thread, as before, and not once on a thread of its own as soon as the game runs (gpu/vk/vk_menu.cpp menu_ahead; its log line says how long each took). For comparing: the first open waited about 2 s for them in test11 |
RX_VK_AA=<0..3>, RX_VK_AA_KEEP=1 |
The anti-aliasing for one run, over the Insert menu's Anti-aliasing row: 0 the game's own SMAA, 1 none, 2 FXAA, 3 SMAA at its Ultra preset in its place (gpu/vk/aa_rows.h, gpu/vk/vk_aa.cpp). Unset, the row decides; with DLSS, DLAA or FSR drawing from the tone mapped picture (Upscale before bloom off) the game's SMAA is left out (none: they want jittered frames no other anti-aliasing has been over), and before the bloom it runs as the game's; the switch goes over both, for an A/B (RX_VK_AA=0: the game's SMAA under the upscaler). The game's SMAA is three compute programs known by their keys (game build e0f3ccfa): with another choice in effect its composition is replaced and its edge and weight passes are left out, and RX_VK_AA_KEEP=1 keeps those two running. The log says vk: aa: when a composition is first replaced, why one was left to the game, and when none was found for a minute |
RX_VK_ASYNC=1 |
The replay on a thread of its own instead of the game's submitting thread (off by default). The game still presents only once the GPU has run its frame, so nothing is released early. (Triforce, gpu/vk/async_rules.h; not yet run in the game) With it on, each with a switch of its own to put it back: a signal of the CPU's takes its capture on the game's thread only when a submission handed over before it may still wait for that event, which the host tells at the submit (RX_VK_ASYNC_EVENT_NOTES=0: at every signal while the thread has work, as before; the vk: the replay thread: ... signals of the CPU's line counts both); the submit's capture shares its copies with the copy helpers and has them all made before the hand-over (RX_VK_ASYNC_CAPTURE_BEHIND=0: every copy on the game's thread); the game's submit keeps its virtual core for the hand-over (HOS_ASYNC_KEEP_CORE=0: given up and taken again); the game's present poll waits for the replay thread asleep and looks at its event between yields only once the GPU has the frame (HOS_PRESENT_POLL=0: the game's own sleeps); a present runs the jobs behind it until the frame's stopped work has gone on and then makes go only what was already stopped at the present before (RX_VK_PRESENT_DRAIN=1: every present forces every stopped queue past its wait, as before; =0: none does; RX_VK_PRESENT_WAIT_MS, 8: how long it runs the jobs behind); and the thread looks for its next job for 100 µs before it sleeps (RX_VK_ASYNC_SPIN_US=<0..1000>). Still open, and why it stays off: after a ten-area tour the player's character is drawn black for one frame, 0 to 3 times a minute at the Market (gpu/vk/async_rules.h has what the lab ruled out). Two diagnostics for it: RX_VK_LOG_READBACK_ZERO=1 logs each readback of GPU results that is all 0 where it was not at its readback before, and RX_VK_REGION_TRAP=1 (with RX_VK_PASS_TRACE=1 and the frame log) logs the passes of the last frames and writes their render conditions to region_cond_<n>.txt when the picture's bottom middle goes dark for a frame, eight times a run. RX_VK_ASYNC_FORCED=1: the thread as it was before 11-14, every catch-up forcing |
RX_VK_OCC_QUERY=0, RX_VK_OCC_QUERY_SKIP=<addr>[,...], RX_VK_OCC_COND=0, RX_VK_OCC_LOG_COND=1, RX_VK_OCC_GATE=0 |
(on by default since 11-17: +2.7 to +4.6% fps in every scene measured, 10-12% fewer draws, no flicker added; RX_VK_OCC_QUERY=0 turns it off) The game's samples-passed reports (which objects show; a count of 0 is not drawn) get their real counts: the replay still writes each report as it passes it with 4096 (RX_VK_OCC_FIXED, everything visible), and the draws from its reset are counted by Vulkan occlusion queries (precise where the card has them); once the GPU is done with the recording that holds them the count is written into the report's record over the 4096, as NX2navi writes it at completion. The done recordings are found with one look at the recordings' timeline (nothing waits) as a game's fence wait ends (the game reads its counts after it), at each recording's begin and each present, at the latest when the recording's slot comes round. The game's report records rotate (a ring: an address is another object's at its next report), so a count is written only while its report is still the newest at its address, and only when it is whole (every query available, no draw left out, reset and report in one recording, read back within 8 presents); otherwise the record keeps its 4096. The game also predicates draws and clears on these words (render conditions), decided as NX2navi decides them: a word whose newest report is a samples-passed one whose count is still to come is unknown and the condition renders; a word whose count was written (or for which none comes) is read from memory as before, where a written 0 skips the draws and clears it gates. A count goes in only over the value the replay left in the word (a compare-and-write: never over the game's CPU re-arming the record), and a record rewritten in the stream after its report (a small buffer clear, a report of another counter type) gets no count. A parallel replay's segments signal the recordings' timeline and are sealed as they are submitted, so their counts are written too. The count word is written as the replay writes a report (guest_cpu_write, and the word kept out of the mirrors' write-backs). With hostQueryReset (Vulkan 1.2) a recording's queries are reset on the CPU once read, only those it used. RX_VK_OCC_QUERY_SKIP: report addresses that keep the fixed answer (the log's occlusion query sites lines list the first 64 addresses with their counts). The log's occlusion queries line every 600 presents: the reports, how many were counted whole and why not, the counts written at completion (and of them 0), those not written and why (lost, superseded by a later report at the address, late, a render condition's), the mean latency in presents and how many were written after the next present, where the done recordings were found, and the render conditions on samples-passed words (rendered because a count was pending, rendered or skipped from a written count, from memory with no count to come, as before in the knob's off phases) with the draws and clears they skipped. RX_VK_OCC_COND=0: a condition on a samples-passed word always renders (the counts are still written), to tell the counts from the skips. RX_VK_OCC_LOG_COND=1: one such condition in 499 logged (300 lines), with both words, their sources (pending, written, memory) and the present. (11-22) RX_VK_OCC_GATE=0 turns off (on by default since its lab A/B: no fps lost at the Market): a count over a draw that a written count's condition left out (between the reset and its report) is the skip's 0, not the object's, and a condition on it renders; the count is still written for the game's CPU. Why: the game's CPU reads a count after its frame wait and draws a hidden object's proxy instead of the object, but most counts land after it has read the 4096, so it goes on drawing the object under the condition, the condition reads the skip's 0 and the object stays hidden (tickets 11-21: items and trees in the Forest Temple, black interiors; RX_VK_OCC_QUERY=0 showed them). The line's second half counts these counts (counted whole, written, of them 0), the conditions that read one and those the switch rendered, on or off. Cost with it on: a hidden object under such a condition is drawn every other frame instead of never. Lab: the knob occq in RX_VK_LAB_AB runs the queries the whole run and writes the counts of the reports made in its phases (gpu/vk/occ_answer.h, vk_replay.cpp "occlusion queries") |
RX_VK_OCC_DEPTH_ONLY=1 |
(Triforce, 11-22, the performance audit's GPUWORK-01, after Source A's; off unless set) Only the occlusion windows whose draws write no colour are counted. The game's occlusion tests draw depth only, but a query here opens at a window's first draw in the pass and stays open to the report or the pass's end, so it can enclose draws that write colour, and a query's end waits for the work it encloses. With the switch, a window's first draw that writes a colour target gives its count up: the open query ends before that draw, no query begins again until the next reset, and the report is incomplete, so its record keeps the 4096 placeholder and what it gates is drawn. Fewer objects are culled with it (Source A: 4% fewer for 0.25 ms of GPU time), never one missing; whether that pays here is for a measurement to say, which is why it is off. The lab's knob occdepth (RX_VK_LAB_AB) is the switch in its phases. Counted either way, in a third vk: occlusion queries line every 600 presents: the counting windows that met a colour draw, the colour draws recorded under an open query, the counts given up and the reports kept 4096 for it (gpu/vk/occ_answer.h Counter::colour_draw; gpu/vk/vk_replay.cpp occ_draw_colour; gpu/vk/vk_draw.cpp draw) |
RX_VK_OCC_LEAN=3 |
(Triforce, 11-22, the performance audit's DESC-82, after Source B's: its first step, the census; off unless set) The game's occlusion proxies write no colour, yet each runs its whole fragment shader and fills its fragment descriptors. With 3, each draw an open occlusion query counts that writes no colour is classed (gpu/vk/occ_lean.h): lean, or the first refusal of a pipeline without the fragment stage (no fragment stage, depth out, sample mask, demote, stores, image writes, atomics, global memory, alpha to coverage, alpha test), and its fragment descriptors added to its class; every 600 presents vk: occlusion proxies (RX_VK_OCC_LEAN=3 gives each class's draws a frame and descriptors a draw. Nothing else changes: no pipeline, key or descriptor. The entry's lean pipelines (1) and their check (2) are built only if the census finds more than one fragment descriptor a proxy to save; they are not built, and read as off. tests/test_occ_lean.py |
RX_VK_GATE_WAIT_MS=<1..100> |
(Triforce, off unless set, after NX2navi's gate_wait_ms, whose default is 10; not yet run in the game) A submission whose first command buffer begins (after state only) with a wait for an event the game signals from the CPU, unmet in the replay's order, waits at its submit for that signal, at most this long, before its capture and its replay (gpu/vk/gate_wait.h, gpu/vk/vk_replay.cpp gate_wait_signal): the capture then holds what the game wrote up to its signal, and the submission is replayed in the submit call on the submitting thread, instead of stopping at the wait and going on from the order thread (sync_watch) with a second capture once the signal came. The wait holds no lock and looks at the event's word in the game's memory. One that runs out goes as before; after 4 that ran out, once they are more than a tenth, it is off for the run (logged). A vk: RX_VK_GATE_WAIT_MS line every 600 waits gives their mean and how many ran out; the order line's captures at a CPU event's wait and made to go by presents say how often the old way was taken |
RX_VK_WAIT_HOLD_PAUSE_US=<us> |
(Triforce, 11-22, the performance audit's THREAD-11, after Source B's; off unless set, not measured here) A wait of the game's for a fence whose work is stopped at an event's wait holds up to RX_VK_WAIT_HOLD_US (3 ms) for another queue to let it on before it forces it, looking again and again: a flush, the timeline's value, the order lock to ask whether the stopped work is still needed, and a yield of the processor. With <us> (2 is Source B's; 1000 at most) a gap of PAUSEs that long stands between two looks instead of the yield, and the order lock is taken only when one of its sections has left since the waiter last asked, which is the only time its answer can change; the fence's own value is still read at every look, and the bound and the forced drain stay. Source B measured 59.2 to 59.9 fps and a 1% low of 40.0 to 42.1 with such a gap on a loop that runs far more often than this one (about 15 holds a second here). 0 or not set: as before. Either way the vk: queues ordered by their events report is followed by a vk: fence waits held for stopped work line: the holds, their looks, the time held, the takes of the order lock and how the holds ended (gpu/vk/wait_hold.h, gpu/vk/vk_replay.cpp wait) |
RX_VK_WAIT_HOLD_PAUSE_US=<us> |
(Triforce, 11-22, the performance audit's THREAD-11, after Source B's; off unless set, not measured here) A wait of the game's for a fence whose work is stopped at an event's wait holds up to RX_VK_WAIT_HOLD_US (3 ms) for another queue to let it on before it forces it, looking again and again: a flush, the timeline's value, the order lock to ask whether the stopped work is still needed, and a yield of the processor. With <us> (2 is Source B's; 1000 at most) a gap of PAUSEs that long stands between two looks instead of the yield, and the order lock is taken only when one of its sections has left since the waiter last asked, which is the only time its answer can change, or while a signal of the CPU's (nvnEventSignal without the replay thread) is queued and no section has acted on it yet; the fence's own value is still read at every look, and the bound and the forced drain stay. Source B measured 59.2 to 59.9 fps and a 1% low of 40.0 to 42.1 with such a gap on a loop that runs far more often than this one (about 15 holds a second here). 0 or not set: as before. Either way the vk: queues ordered by their events report is followed by a vk: fence waits held for stopped work line: the holds, their looks, the time held, the takes of the order lock and how the holds ended (gpu/vk/wait_hold.h, gpu/vk/vk_replay.cpp wait) |
RX_VK_INDEX_REBASE=0 |
(Triforce, 11-21, the performance audit's DESC-12) A direct indexed draw binds its index buffer at offset 0 and gives its offset as the draw's first index, so draws at different offsets of one buffer bind it once: bound at each draw's own offset, nearly every indexed draw called vkCmdBindIndexBuffer. Only where the offset is a whole number of indices; indirect indexed draws are as before. RX_VK_PROF_FINE=1 counts the index binds looked up and those made. 0: every draw binds at its own offset (gpu/vk/index_rebase.h, vk_draw.cpp draw, bind_index) |
RX_VK_RECORDER_OWN=0 |
(Triforce, 11-21, the performance audit's REPLAY-04) With the recorder thread, a recording slot's descriptor pools are reset, its extra pools destroyed and its grown streams given back in draw_begin_recording, after the recording's first packets, as before: each is a boundary the replay waits at until the recorder has run what came before. The default makes that reset in begin_recording right after the slot's command pools are reset, where the recorder has nothing held. The 120-present line a frame's recorder thread counts the replay's waits (gpu/vk/vk_draw.cpp draw_slot_reset, vk_replay.cpp begin_recording) |
RX_VK_DESC_POOL_GROW=0, RX_VK_DESC_POOL_DIV=<1..32>, RX_VK_STREAM_MB=<MB> |
(Triforce, 11-22, the performance audit's DESC-33, after Source A's; gpu/vk/desc_pool_grow.h) Each recording slot (48 at most) keeps a descriptor pool for the programs over the push limit, and the driver may keep host memory for all of it 48 times. A slot's pool is made at half size (4096 sets, 16384 uniform buffers and sampled images, and so on) and made whole (8192 sets) at the slot's first reset after a recording ran out of it; a recording that runs out gets a whole extra pool on the spot, as it always did. RX_VK_DESC_POOL_GROW=0: whole pools from the start, as before. RX_VK_DESC_POOL_DIV=<n> divides both sizes by n. RX_VK_STREAM_MB=<n> is the size of each slot's first upload stream (2 by default; a recording that needs more is moved to a bigger one, kept for the slot's next 120 recordings; 24 with RX_VK_STREAM_GROW_OFF=1, which skips draws instead). Every 3000 recordings the log's two "the recording streams" lines say the most one recording held of its stream, how many slots are still at half, how many were made whole, the extra pools made, and the most sets and descriptors of each type one recording took: what a smaller default is judged by (the stream's stays 2 MB until those numbers are read in play) (gpu/vk/vk_draw.cpp make_pool, slot_reset_locked, draw_begin_recording) |
RX_VK_CAP_SPARE_FIT=0, RX_VK_CAP_STEP_MB=<n> |
(Triforce, 11-22, the performance audit's MEM-33; the first on by default, the second off unless set; not yet run in the game) RX_VK_CAP_SPARE_FIT=0: a capture with no spare buffer makes its own with the spares' lock held, takes any spare that fits, and a spare made ahead is made once, as before. Without it (gpu/vk/cap_spare.h, gpu/vk/vk_memory.cpp cap_buf_get) the buffer is made with the lock let go, so the replay's take does not wait behind a submitting thread's allocation to give a buffer back; where spares are not capped at 32 MB a capture leaves alone a spare of 32 MB or more that is over twice its size class, for the load that wants it; the spare a capture of a class of 32 MB or more takes is made again on a worker; a spare is made ahead only if it fits what spares may hold together with the ones held and being made, and a buffer given back counts the ones being made; when the allocation fails, any spare that fits, then the exact size. RX_VK_CAP_STEP_MB=<n>: where spares are capped at 32 MB (a card of 6.5 GB or less), a capture over 16 and up to 32 MB gets a buffer in steps of n MB, not the whole 32 MB (Source A: 4; its worst frames were worse in two pairs, so off here). The 600-take line counts the buffers made on a submitting thread and their ms |
RX_VK_MIRROR_PIECE_IDLE=<submissions> |
(Triforce, 11-22, the performance audit's MEM-26, its first step only; off unless set; not yet run in the game) A mirror in pieces keeps a piece's memory until the whole mirror goes, also where no game pool is left in its import. Giving such pieces back is NOT ported (the unbind and the free must wait for the GPU and for the bind timeline). What it would find is counted (gpu/vk/piece_idle.h): every 1200 submissions, after the mirrors in pieces line, the MB of pieces no game pool covers; with this switch each binding given a mirror in pieces also notes the submission in its pieces, and the line says how many of those MB no binding reached for that many submissions (600 is the wait the release would use). Under about 100 MB at the end of a tour on a 6 GB card (RX_VK_TEST_CARD_MB=6144) the release is not worth porting |
RX_VK_RANGE_WALK=0 |
(Triforce, 11-22, the performance audit's MEM-42; on by default; not yet run in the game) The capture and collection loops (gpu/vk/vk_memory.cpp memory_collect_written, capture_make's staging and behind loops, take_capture's loops over the texture storage's ranges) ask of every page whether it lies in a sorted range list with a binary search, as before. Without it each loop has a cursor that only moves forward (gpu/vk/range_walk.h), one pass over the ranges for the loop; an address below the last one asked searches again, so any order gives the search's answers (tests/test_range_walk.py compares them). The RX_VK_LAB_AB knob norangewalk searches in its phases |
RX_VK_TABLE_STREAM=0 |
(Triforce, 11-22, the performance audit's SYNC-04; on by default; not yet run in the game) The guest page table's changes of a recording (the table the shaders' pointers go through, gpu/vk/vk_memory.cpp memory_table_flush) are flushed as before: a (page, value) pair for every page changed, all of them sorted, the last of each page kept: 16 bytes a page and a sort on the recording thread, a few ms when a pool of hundreds of MB is imported ahead or merged. Without it the changes are streamed (gpu/vk/table_stream.h): runs in page order and apart are appended one after the other, any other set is swept by page with the newest change owning each page, through one reused batch of 8,192 entries. The transfers are the same ones in the same order (tests/test_page_table_stream.py compares the two, entry for entry). A flush over 1 ms is logged with its pages, changes and transfers (the first 16) |
RX_VK_CAPTURE_BEHIND=0 |
(Triforce, on by default; =0 as before) The submit-time capture (gpu/vk/vk_memory.cpp capture_make) takes the write marks on the game's submitting thread and copies there only the pages read at once (the late pages and the texture storage); the rest of its copies, in parts of 32 pages, go to the capture's copy helpers while that thread replays the submission (gpu/vk/capture_behind.h). A read of a page as submitted copies its part itself when no helper has taken it yet, or waits for the helper; every part is done and flushed before a recording is submitted and before the thread goes back to the game. Only with the replay on the submitting thread (not RX_VK_ASYNC=1), with copy helpers (RX_VK_CAPTURE_THREADS, not RX_VK_LOW_SPEC), at least 128 pages behind and at most 512 ahead (a scene's load: copied whole as before). At the Market the old copy was ~0.25 ms of each submit's ~0.35 ms capture, six submits a frame. The 120-present line a frame's captures at the game's submits gives their time on the game's threads (the scan, the copies made there, and the copies behind made or waited for by the replay), the MB copied and behind, and who copied the parts; the stall line names the captures when they took 1 ms or more |
RX_VK_CAP_FREE_ASYNC=0 |
(Triforce, on by default; =0 as before) A retired capture buffer the spares cannot keep (past 12 buffers or 768 MB, 32 MB on a card of 6.5 GB or less) is destroyed on a thread of its own (gpu/vk/vk_memory.cpp cap_buf_free, destroy_buffer_later), not in the capture's take on the replay's thread with its locks held: freeing a 64-256 MB host-cached buffer makes the driver unmap and release every page, the retires part of a vk: slow capture take line. Only buffers the GPU is done with get there; the memory comes back a moment later. The 600-take line counts the buffers and MB handed over. With no thread to be had they are destroyed where they were retired |
RX_VK_PARALLEL=<0..8>, RX_VK_PARALLEL_AUTO=<2..8> |
The parallel replay: a frame's large command buffers recorded on that many threads, always, or wherever short trials as the game runs find it faster than the replay thread alone; RX_VK_PARALLEL=0: never. The Debug tab's Replay helper threads row is the second without an environment to set (replay_helper_threads= 1 to 7 for 2 to 8 threads); either switch goes over the row. The row's Automatic (8), which it is unless the options file says otherwise, is the count gpu/vk/replay_threads.h gives the PC: none with four cores or fewer or on AMD's driver for RDNA 1 and 2, 2 threads with five to seven cores, 3 with eight or more. The log says at the start what was chosen (replay helper threads:) and at each trial which way is in use (parallel replay, trial). Between trials the tuner's rule (gpu/vk/replay_threads.h rule) judges every 120 frames on the replay thread alone: where the replay is plainly the frame's limit (70% of the frame or more) and the helper threads would take at least 1 ms and a tenth of the frame off it, never counting below the GPU's time (the game waits for each frame's GPU work), they are turned on without a trial; where they cannot pay (no command buffer large enough to cut, the GPU's time about as long as the replay's, or the replay under 60% of the frame: the game's own threads are its limit) no trial is made while that holds; trials decide the rest, and a trial that takes the helpers back off holds the rule's "on" for 3,600 presents. The log says so (parallel replay, the rule) when its verdict changes. RX_VK_PARALLEL_RULE=0: trials only, as before. With DLSS or FSR on, for upscaling or frame generation, the dry pass tells their hooks in the draws in stream order, and each command buffer from the first draw or dispatch that takes what they noted (the upscale, or the engine's point before the bloom) on is recorded in order after the segments before it (gpu/vk/stream_order.h); RX_VK_PARALLEL_TEMPORAL=0: the replay thread records alone then, as before. The frame statistics' a frame's parallel replay: line says in how many frames the threads recorded, the command buffers in segments and alone (and why), and the time in them; the next one (its parts) where that time went: the setup before the threads begin, how soon each command buffer's first segment reached the GPU, the helper threads' wake-up, each command buffer's longest segment, the replay thread's wait, the submits, the recording lock's waits, and the segments' GPU time (the GPU time line counts the segments too; it left them out). After each trial's line a trial N's parts line gives its three parts' frame, replay thread's time, GPU time, the rest of the frame, full barriers and draws, and the helper threads' parts. That header lists what an audit of the parallel replay found and fixed, and what is left. RX_VK_NO_DRY_COPIES=1: the dry pass does not mark what copies and texture clears write, as before. The replay thread records the next segment to submit itself when no helper thread has begun it (it only waited before, on the core kept for it); RX_VK_PARALLEL_OWN=0: it waits for the helper threads, as before. RX_VK_PARALLEL_SEG=<32..>: the draws and dispatches a segment is cut for (160); RX_VK_PARALLEL_SEGS=<2..12>: the most segments a command buffer is cut into (6), without which a smaller RX_VK_PARALLEL_SEG cuts no finer once a command buffer has six segments' worth |
RX_VK_PARALLEL_BACKOFF=0 |
The tuner's trials as before: one every 1,800 presents after one that kept the way, each with 104 frames the other way. With the back-off (the default, gpu/vk/replay_threads.h Tuner) each trial that keeps the way, the other way longer than both of its own parts, puts the next one off twice as long (3,600, 7,200, then 14,400 presents at most; a margin of 10% or more counts twice), one too close to tell keeps the old interval (the first such one after a change of scene or way: 900 presents), and once the way has held so the other way is tried for 64 frames, not 104; a short trial that finds the other way shorter changes nothing itself, a full trial follows at once. The next trial comes early (900 presents after the last one at the soonest, never while the rule says no trial) when the scene clearly changes: two windows of 120 frames in a row whose draws moved by a quarter (200 at least) or whose replay or GPU time moved by 30% (1 ms at least) from the first window after the way was set, or a trial whose first and last parts did. In the lab's steady Market a trial came every ~2,090 presents, each ~100 frames 1.9 ms longer; the trial lines now end with when the next may come, and parallel replay, the scene changed says when one was brought forward |
RX_VK_TUNER_SETTLED=0 |
The tuner's rule judges every window and a trial the scene changed under decides, as before. With settled scenes only (the default, gpu/vk/replay_threads.h Tuner, after Kaefergeneral's #dev-fixes post: on his 5900X and RTX 3090 the rule turned the helper threads on in an area's load and the first trial after the arrival kept them, and Automatic was 6 to 10% slower than Off) the rule judges a window of 120 frames only if the one before it describes the same scene (its draws within a quarter, 200 at least, its replay and GPU times within 30%, 1 ms at least: the back-off's test), so a load's window and the first after it get no verdict and the rule's "on" comes a window after a scene settles; a trial whose first and last parts moved so changes nothing, either way, and the next comes 120 presents after a window like the one before it, not 900 or more later. The trial's line says so (the scene changed under it), and parallel replay, the scene settled when the next is set |
RX_VK_RECORDER=thread, =defer, =sync, =off |
(unset: thread on an NVIDIA GPU with 12 logical processors or more, and on an AMD GPU with 6 physical cores or more in the process's affinity but for AMD's Windows driver for RX 5000 and RX 6000 (gpu/vk/recorder_auto.h); else off. The log's vk: recorder thread on/off by default line says which rule applied; RX_VK_LAB_AB=norec makes the calls directly in its phases, to measure it) thread: the replay thread's vkCmd* calls packed with copies of their arguments into a ring and made by a recorder thread of their own, in order (gpu/vk/vk_recorder.h); the replay thread waits for it at every command buffer begin, end and reset, submit, wait, readback and destruction. Beside the Replay helper threads too (no longer refused with RX_VK_PARALLEL): a parallel replay's segments make their calls themselves, after the ring has been run (segments_begin), and the recorder is idle while they record. With it on, the frame statistics' a frame's recorder thread line says how many of the replay's calls it made a frame and in how long, and how long the replay thread waited for it; what it saves is the replay time line's commands with it against without it. defer and sync are its test steps (held and run on the same thread). RX_VK_RECORDER_RING_MB (8), RX_VK_RECORDER_SPIN_US, RX_VK_RECORDER_STATS=0, RX_VK_RECORDER_POISON=1, RX_VK_RECORDER_PIN (next, sibling or a mask) |
RX_VK_REPLAY_PRIO=0 or 1 |
(Triforce, on by default, after NX2navi's recorder_prio; =0 as before) A thread runs at the highest priority while it replays the game's frames (the submitting thread's replay and its capture, the present, the stopped work the order thread lets on: gpu/vk/vk_replay.cpp ReplayPin) and gets its own priority back after, so the game's code it runs between replays keeps the game's priority; the core kept for the replay is kept from the game's threads only, and the helper threads and the capture's copy helpers (above normal) outranked a replay at the game's priority there. A thread at that priority or above already is left alone. The replay thread of RX_VK_ASYNC=1 and the recorder thread of RX_VK_RECORDER=thread take the level for good. =1: above normal. The log's vk: a thread that replays runs at line says which (gpu/vk/replay_prio.h) |
RX_VK_REPLAY_PIN_SOFT=0, =2 |
(Triforce, 11-22, the performance audit's THREAD-09, after Source A's; Windows) A thread is pinned while it replays to the core the host keeps for the replay, and that core is kept from the game's threads, not from other programs': where another program's high-priority thread holds it, the pinned replay waits for it, ready to run (Source A, a 6+8-core hybrid processor with an overlay service at priority 15: 14 to 37 frames over 40 ms in a 40 s run, none with this). Not set: on a processor with cores of more than one kind the pin is soft: the thread may run on the reserved core and on the fastest-kind cores among its own processors, the reserved core's last logical processor is its ideal one, and the core it is on when the pin starts is left out so that it moves at once; its affinity and ideal processor come back after the replay. The replay thread of RX_VK_ASYNC=1 gets the same processors for good. A processor of one kind of core keeps the strict pin, and nothing changes there. 0: the reserved core alone everywhere, as before; 2: soft everywhere (the lab; the knob pinsoft of RX_VK_LAB_AB does it by phases). A thread of another program that wakes on the core every millisecond moves the replay again and again (Source A: 54.3 against 44.6 fps, one run each): 0 is for that. The log's vk: a replay's pin is line says which (gpu/vk/replay_pin.h, gpu/vk/vk_replay.cpp ReplayPin, replay_pin_soft) |
HOS_VCORES=0, HOS_CORES=<1..8>, HOS_RESERVE_CORE=0 |
No virtual cores; the cores the game sees (6); no core kept for the replay (one is, with 8 or more logical processors) |
HOS_VCORES=0, HOS_CORES=<1..8>, HOS_RESERVE_CORE=0, =1 |
No virtual cores; the cores the game sees (6); no core kept for the replay (one is, with 8 or more logical processors). (Triforce, 11-22, the performance audit's THREAD-49, after Source A's) On the cache die of a two-die X3D processor with SMT off none is kept unless HOS_RESERVE_CORE=1 asks for it or the replay has a thread of its own (RX_VK_ASYNC=1): the game then has all 8 of the die's cores (Source A, a 9950X3D with SMT off: 59.8-59.9 fps with none kept against 56.9-57.4 with one). The log's cpu: no core kept for the replay on the cache die line says so. With SMT on and on every other processor nothing changes (host/hos_x3d.h hos_x3d_keep_replay_core) |
HOS_AV1=mf, HOS_AV1_MISSING=1 |
(Triforce, 11-22, the performance audit's IO-32; Windows) The game's AV1 movies on Media Foundation first (Microsoft's AV1 Video Extension), as before, and on dav1d only where the PC has no such decoder. Without it dav1d goes first where the FFmpeg the build links has libdav1d, as on Linux, and Media Foundation where it has not or where libdav1d does not open (host/video_av1.h, host/nn_video.c dec_init_sized): Media Foundation's path decodes in software on every GPU (host/mf_av1.c takes the synchronous decoder). HOS_AV1=dav1d, the old way to ask for dav1d first, is the default now. HOS_AV1_MISSING=1: Media Foundation as if the extension were missing. Each movie logs one line at its Stop, Flush or its decoder's end: its pictures, the decoder, the mean and the worst time to decode a submission, and the pictures skipped to catch up (host/video_movie.h). The two decoders were not timed against each other in the game |
HOS_VIDEO_RGBA=1 |
(Triforce, 11-22, the performance audit's IO-36) Every planar 4:2:0 movie picture (libdav1d's) is converted to RGBA when it is decoded, as before: a swscale pass, an 8 MB allocation and an 8 MB row copy for a 1080p picture, on the movie thread. Without it such a picture is kept as NV12 alone, as Media Foundation's NV12 pictures already were, and its pool makes the RGBA only if the game reads RGBA, which this game's movie library does not; planar 4:2:0 with alpha is converted at once either way. The NV12 buffer is zeroed only for an odd size or a format that is not copied into it, and U and V are interleaved 16 pairs a step with SSE2 (host/video_nv12.h, host/nn_video.c queue_frame). The movie's line in the log (IO-32) has the time a picture took with either. Not timed in the game |
HOS_VIDEO_UNBOUNDED_CATCHUP=1, HOS_VIDEO_NO_CATCHUP=1 |
(Triforce, 11-22, the performance audit's THREAD-82) The movie decoder's acquire skips the pictures behind the movie's clock and decodes the next ones to skip them too. HOS_VIDEO_UNBOUNDED_CATCHUP=1: with no bound but a guard of 600 steps, as before: with a decoder slower than the movie (19.5 ms a picture against 16.7) each picture decoded to catch up puts the clock further ahead, so an acquire decoded up to about 300 pictures with its lock held, threw them away, and the next started further behind. Without it each decode that gives a picture is timed, about the last 8 kept as one number, and the acquire stops decoding ahead when that number is more than the gap between two pictures (from the pictures' own times) or once it has decoded for one gap, and shows the late picture it has (host/video_catchup.h, host/nn_video.c dec_acquire): such a movie falls behind its sound instead of stalling, and its line in the log says "slower than it plays". A decoder faster than the movie catches up as before, a few pictures an acquire. HOS_VIDEO_NO_CATCHUP=1: no picture skipped at all (the movie in slow motion under 60 fps). Not run in the game |
HOS_VIDEO_INPUT_LIMIT=<n> |
(Triforce, 11-22, the performance audit's IO-34) How many submissions the movie decoder holds, not decoded yet or decoded and not taken, before it refuses one: 16 when unset; 0: no limit, every submission taken, as before. The game submits a whole movie at once on the thread that also takes the pictures, so at a movie's start the pictures that came due while it submitted were skipped. With the limit a submission is refused at once with the console's result for a full decoder (0x1c266f) and the game submits it again later; the stream's last submission is never refused, and a decoder with no codec behind it refuses nothing. Each decoder has its own "ready for a submission" event, clear from a refusal until an acquire, a Stop or a Flush makes room (it was one event for all, always set); the movie's line in the log counts the refusals (host/video_input.h, host/nn_video.c dec_submit, input_room). If a movie ever hangs on a black screen, try =0 first. Not run in the game |
HOS_MOVIE_PACE=0 |
(Triforce, 11-22, the performance audit's PRESENT-30) The frame rate cap is kept while a movie plays, as before. Without it, at a cap of exactly 60 and with the Steady frame rate row off, the frames are paced by 240 while a movie player has updated in the last quarter second, and the game's own limiter and its time step follow as they do at a cap of 240 (host/movie_pace.h, host/nn_vi.c movie_pace_decide, pace_fps, realtime_step): the game's movie player takes one picture an update at most and its updates follow the frame loop, so at 60 every frame that came late was a picture the decoder skipped. Game time stays real time; the limiter is put back where it was when the movie is over, and the log has a line at the movie's start and one at its end. The cap itself (the Steady row, the vsync event, the hand-off to RivaTuner or Reflex) does not move. Movies use more CPU and power with it. Not run in the game |
A64_NO_VBYTES=1, A64_NO_VMOVES=1 |
(Triforce, 11-21, the performance audit's LIFT-02; read when the game is translated, and in the lift key) The translator writes TBL with a one-register table and EXT as loops of single bytes through the stack, a 128-bit vector load as two halves and DUP by element as a loop, each followed by a 16-byte read of the register that cannot be forwarded from those stores. nx2/fastvec.py rewrites each on the lifted text as one instruction's helper (PSHUFB; PALIGNR or two shifts; one 16-byte load; one broadcast), the same bytes in the same registers (tests/test_vbytes.py runs every shape both ways). A64_NO_VBYTES=1 keeps the translator's text for TBL and EXT, A64_NO_VMOVES=1 for the loads and DUP. A build with them needs a hot profile of its own (RX_PGO=gen) |
A64_DMB_LIGHT=1 |
(Triforce, 11-22, the performance audit's LIFT-47, after Source B's; read when the game is translated, and in the lift key; off by default) The translator writes every DMB and DSB as recomp_barrier(), an out-of-line full fence. x86-64 keeps load-load, load-store and store-store order in hardware, so with this set the eight DMBs that ask only for those (ISHLD, ISHST and the OSH, NSH and full-system forms) are lifted as A64_DMB_LDST() (nx2/insn.py dmb_light), which is nothing but a barrier for the compiler on x86-64 and the full fence on any other host (nx2/rtgen.py). A full DMB, every DSB, ISB and STLR's locked store keep theirs. Unset, empty or 0: the kit's text. tests/test_dmb_light.py runs every such word both ways, alone and between a store and a load. Not counted in this game's code and not measured in the game: how many of its barriers are of these kinds is not known, and what other threads see cannot be shown by a test on one thread. With it set the hot functions that hold such a DMB no longer match the shipped hot profile: such a build needs one of its own (RX_PGO=gen) |
HOS_FMA_FAST=0, A64_NO_FMA_SOFT=1 |
(Triforce, 11-22, the performance audit's LIFT-06, after Source A's; only in a build without FMA3, x86-64-v2: with FMA3 none of it is compiled) Without a hardware FMA every double-precision FMADD, and each single-precision one its binary64 fast path cannot prove, ran the translator's exact body, integer code of many words (about 180 ns a call and 13.7% of a core on an i7-3770, Source A's figures). nx2/fma_soft.py puts a short way out at the head of recomp_fpe_fma64 and recomp_fpe_fma32 for the plain case: default FPCR (FZ or not), three normal operands and a normal result, by an exact product and sum in binary64, rounded to odd, then rounded once, FPSR.IXC set when inexact; everything else goes on into the body. tests/test_fma_soft.py compares both bodies with it and without, value and every byte of the context. HOS_FMA_FAST=0 (read once when the game runs): the exact bodies only, as before. A64_NO_FMA_SOFT=1 (read when the game is translated, and in the lift key): the translator's runtime text as it was. Not measured in a game on a CPU without FMA3 |
A64_NO_FMA_STEPS=1 |
(Triforce, 11-22, the performance audit's LIFT-05, after Source A's; read when the game is translated, and in the lift key; only in a build with FMA3, x86-64-v3) The single-precision FRECPS and FRSQRTS steps (2 - ab and (3 - ab) / 2, the Newton-Raphson steps of a reciprocal and a reciprocal square root) were computed in binary64 on x86-64 (two widenings, a multiply, a subtraction, a narrowing) with a test for a binary32 midpoint, which went to the exact body. nx2/fma_steps.py gives their fast paths the guard the fused multiply-add's already had: with FMA3 one fused instruction, the step rounded once as on the console; the tests that decide whether the result is kept are unchanged (tests/test_fma_steps.py runs every form both ways and against the exact body). A64_NO_FMA_STEPS=1: the translator's text for the two steps. The compile define -DA64_FPX_NO_FMA32 returns all three (FMADD/FMLA and the two steps) to the binary64 form. Source A measured the steps alone at 23% to 29% fewer cycles; not measured in the game, and how often this game runs them is not counted |
A64_VECFP=1 |
(Triforce, 11-22, the performance audit's LIFT-03, after Source A's; read when the game is translated, and in the lift key; off by default) The translator's passes turn straight FADD, FSUB and FMUL .4S and the .4S by-element multiplies into one SSE op; other float forms stay a helper call a lane or exact integer code a lane. With this set nx2/vecfp.py lifts each of them as if (!a64_vfpx_q_<form>(c, ...)) { the C as before }: the helper does the op in SSE and writes the register only when the scalar fast paths' rules prove the result is the console's with no new FPSR bit. 1: every group; or a list of elem (FMUL, FMLA, FMLS .2S by element), vec (FMUL .2S; FMLA, FMLS and FDIV .2S and .4S; the multiply-adds need FMA3 and decline without it), minmax (FMAX, FMIN, FMAXNM, FMINNM: scalar S, .2S, .4S; kept unless a NaN or, under FZ, a subnormal is involved) and fcvt (FCVT S to D and D to S, FCVTL, FCVTL2, FCVTN). Unset, empty or 0: the translator's text. tests/test_vecfp.py runs 137 guest words three ways (with it, without it, exact). Source A measured +3.5% to +5.1% fps where the game's update bounds the frame, for 3.7% more compile time; not measured in this game, which is why it is off. A build with it needs a hot profile of its own (RX_PGO=gen) |
HOS_HEAP_COMMIT=1 |
(Triforce, 11-21, the performance audit's MEM-09) On Windows the game's heap (~6.9 GB asked for at its start) is left reserved and committed as it is touched, 64 KB at a first touch, by the handler that commits pages nothing handed out; committed whole, all of it counted against RAM plus the page file, touched or not. A fault another thread's commit answered is tried again, a commit refused at Windows' commit limit is tried again for 5 s, and a file read or write reads each page of its buffer once before the kernel's call, which faults nothing in. The log says heap: left reserved and counts the heap's first touches. 1: all of it committed at the start, as before; so it is in large pages (HOS_LARGE_PAGES) and on Linux (host/heap_commit.h, mkw_glue.c commit_on_touch, hos_mem.c SetMemoryHeapSize) |
RX_VK_DMABUF_NVIDIA=1, RX_VK_NO_DMABUF=1, RX_VK_DMABUF_PIECE_MB=<n> |
(Linux) Where the game's memory is a memfd, each pool of it is offered to the driver as a dma-buf made by udmabuf, larger pools as several of at most udmabuf's limit bound into one sparse buffer; the log's vk: guest memory as dma-bufs: line says yes or why not. RX_VK_NO_DMABUF=1: host-pointer imports only. RX_VK_DMABUF_PIECE_MB=<n>: pieces of at most n MB. (Triforce, 11-22, the performance audit's OS-08, after Source A's; not yet run on Linux) NVIDIA's proprietary driver refuses every such dma-buf and the pool ends as a host-pointer import anyway, after a refused import each (up to 198 ms for one during a load) and a kernel message at each start: with that driver none is offered, /dev/udmabuf is not opened, and the line says no (NVIDIA's driver refuses them: host pointers) (gpu/vk/dmabuf_gate.h). NVK and RADV keep their dma-bufs. RX_VK_DMABUF_NVIDIA=1: offered to NVIDIA's driver too, as before |
HOS_COMMIT_WAIT_MS=<ms> |
(Triforce, 11-22, the performance audit's OS-04, after Source A's and Source B's; 5000 unless set) How long a refusal at Windows' commit limit (RAM and the page file full, error 1455) is waited out, tried again every 50 ms: such a refusal often ends in moments, as a page file set to grow grows or commit is given back. The game's own commits waited so already (the row above); now the host's own tables do too (a failed allocation there ended the game at once: host/host_alloc.h, hos_xmalloc in host/mkw_glue.c), and the renderer's failed new, which was an uncaught std::bad_alloc: its new handler sleeps 50 ms and lets the allocation be tried again, up to this long a thread, but only while the system has less than 4 GiB of commit left (a new refused with more free is not the limit's and throws at once), and not for the few allocations that have their own answer to a refusal (gpu/vk/new_wait.h, gpu/vk/vk_main.cpp new_refused). The log has refused ... made after N ms for the first rescues. 0: no wait anywhere, a refusal fails at once; 60000 at most |
HOS_TEXELS_KEEP_CORE=1 |
(Triforce, 11-21, the performance audit's THREAD-20) nvnTextureReadTexels and nvnTextureWriteTexels reach the back end, which waits for all the GPU work submitted and then for the replay's lock; the game calls them from its loading threads at an area's arrival and at boot. The calling thread gives its virtual core up for that call, as it does around a readback, so the game threads allowed only on that core do not wait with it. A write kept for a renderer not started yet never waits and keeps the core. 1: kept, as before (host/rx_backend.c rx_nvn_read_texels, rx_nvn_write_texels) |
HOS_LOG_SYNC=1, HOS_LOG_BATCH_MS=<ms> |
The log's lines are written by a thread of their own, not by the thread that logs: a write that blocks (a console, a busy disk) holds no game thread. The writer waits a little after a line and writes the lines of that time in one write (HOS_LOG_BATCH_MS, 250 unless set, at most 2000; 0: the lines there are at each wake); a queue half full goes out at once, and every way out of the game writes the queue first. HOS_LOG_SYNC=1: each line written by the thread that logs it. (Triforce, 11-22, the performance audit's THREAD-56, after Source A's; not yet run on Linux) The writer is Linux's and the Steam Deck's too now: there every hos_log wrote stderr in the calling game thread, its virtual core held, so HOS_LOG_SYNC=1 is Linux as it was. And nvnCommandBufferEndRecording's two lines (the sweep's, the 50,000-recording line) are written after the recordings' lock is released, the virtual core given up, on every system (host/hos_thread.c log_queue, host/nvn_native.c) |
RX_VK_INVALIDATE_QUICK=1 |
(Triforce, 11-22, the performance audit's THREAD-25, after Source A's; off unless set. Source A has it on; here it waits for a run in the game, as a wrong answer skips the wait a readback of GPU results needs, the exposure flashes' kind of fault) The game invalidates each shape's 64-byte occlusion slot, per view, and the host gives the calling thread's virtual core up before every such call and queues for it again after, though nearly none has anything to wait for. With 1 the back end is asked first, with no lock and no wait: a range with nothing to invalidate, or one below 512 GB with no fast fence poll's order ticket still to wait for, no live texture's storage in it, no texture the GPU wrote ever listed there and no write-back ever made into its pages, is one invalidate returns from at once, so the call is left out and the core kept. The two "ever" answers are bits a page that are only set, before their tables change (gpu/vk/page_marks.h); a page written back once has the call made for good. Source A measured Hyrule Field at 50.5 to 51.4 fps and its 1% low up by two to four frames a second, its busiest worker keeping the core 31,444 times against 2,604. Every 10 s a vk: invalidates: line counts the calls left out and made. With RX_VK_LOG_INVALIDATE, RX_VK_LOG_READBACK or RX_VK_INVALIDATE_WAIT set every call is made; the lab's knob noinvq makes them all in its phases (gpu/vk/vk_replay.cpp invalidate_quick, host/rx_backend.c rx_nvn_invalidate) |
HOS_OPEN_KEEP_CORE=1 |
(Triforce, 11-21, the performance audit's IO-24) nn::fs::OpenFile gives its virtual core up only around the host's own open, as before. The default gives it up before the path is worked out too: that reaches the button prompts' builder, which builds a file at its first open (a quarter of a second and more) while the other openers wait for it, and none of them holds a core meanwhile. Every return takes the core back before it answers the game (host/nn_fs.c OpenFile, host/prompts.c hos_prompts_font_file) |
HOS_SHORT_SLEEP_TIMER=1, =0 |
(Triforce, 11-21, the performance audit's OS-31) How sleeps under a millisecond wait. Not set: with 6 or fewer logical processors in the process's mask (Windows, one processor group) the game's own short sleeps wait on the high-resolution timer, which wakes about 0.5 ms late, and the host's own yield until their time; with more, all yield, as before. The game's idle job workers sleep 20 us and look again about 7,600 times a second, and a yielding sleeper keeps a processor busy. 1 (any value but 0, off, no, false): every short sleep on the timer, as the switch did before; 0: every short sleep yields. (Triforce, 11-22, the performance audit's OS-32, after Source A's; not yet run on Linux) Off Windows the processors are not counted and, not set, every short sleep yields, as before; HOS_SHORT_SLEEP_TIMER=game puts the game's own short sleeps on the timer and leaves the host's yielding at any processor count, on any system: Source A's default off Windows (on Linux the timer wakes tens of microseconds late, not half a millisecond), which was never measured in the game by itself and is to be tried on a Steam Deck before SHORT_SLEEP_ELSEWHERE in host/short_sleep.h makes it what Linux does when the switch is not set. The log's sleep: line says which (host/short_sleep.h, host/hos_thread.c sleep_for) |
HOS_DISCARD_KEEP_CORE=0, =1 |
(Triforce, 11-22, the performance audit's OS-40, after Source A's; not set: as before, which is NOT Source A's default. It reverses a choice made here on purpose, changes when a game thread waits, and was not measured here) A discard of memory the game let go is milliseconds in the kernel for a region of some MB, and before it the lazy write-back's pages there are paid and pages a GPU import holds are zeroed; the game threads allowed only on the freeing thread's virtual core wait all the while. Not set: the core is given up for the discard's own kernel call, and only with the memory limit on (HOS_MEM_LIMIT), as before. 0: a freed region's thread gives its core up before the whole of the discard and takes it back once, after the region is unlisted and never under the regions' lock; the discard's own call gives it up without the limit too (FreeMemoryPages). Source A at its Market: core waits of 50 ms and more 287 to 19, the longest 177 to 45 ms, frames unchanged; the freeing thread once waited 124 ms for its core back, in a load. 1: the core kept through every discard, with the limit too. With 0 the log counts such frees and the longest take-back every 1,000 (host/hos_mem.c discard_core, hos_region_free, discard_pages) |
HOS_SHORT_SLEEP_TIMER=1, =0 |
(Triforce, 11-21, the performance audit's OS-31) How sleeps under a millisecond wait. Not set: with 6 or fewer logical processors in the process's mask (Windows, one processor group) the game's own short sleeps wait on the high-resolution timer, which wakes about 0.5 ms late, and the host's own yield until their time; with more, all yield, as before. The game's idle job workers sleep 20 us and look again about 7,600 times a second, and a yielding sleeper keeps a processor busy. 1 (any value but 0, off, no, false): every short sleep on the timer, as the switch did before; 0: every short sleep yields. The log's sleep: line says which (host/short_sleep.h, host/hos_thread.c sleep_for) |
HOS_SHORT_SLEEP_POLLERS=<n>, =auto |
(Triforce, 11-22, the performance audit's OS-33, after Source A's; off unless set: it changes how the game's threads wait and was not measured here) A cap on the game threads that yield through a sleep under a millisecond at once. Where those sleeps yield (more than 6 logical processors, HOS_SHORT_SLEEP_TIMER not set) every idle job worker keeps a processor busy; with the cap, a game thread that would be one more than <n> yielding waits on the high-resolution timer for that sleep instead, about 0.5 ms late. auto: a quarter of the process's logical processors (2 with 8, 4 with 16, 6 with 24), Source A's rule, whose provisional numbers are 2.7% less CPU a frame at the same frame rate with 16 processors, and 1.7% of the frame rate lost in a 24-thread run held to 2. The game's MainThread and Presentation Thread and the host's own sleeps are never counted and always yield. Not set, 0, off: no limit, as before. The start's sleep: at most line says the cap, and with HOS_SLEEP_LOG=1 a sleep: line every 5 s counts the sleeps that took the timer for it (host/short_sleep.h short_sleep_pollers, short_sleep_poll_enter, host/hos_thread.c sleep_for) |
HOS_OS_YIELD=0 |
(Triforce, 11-22, the performance audit's THREAD-41, after Source A's; off unless set: it changes how the game's threads wait and was not measured here) The game's YieldThread hands its virtual core to a waiting game thread of equal or better priority and then also gives the processor up (SwitchToThread, a call into the kernel, thousands of times a second from the game's job system). 0: only the virtual core's hand-over, the console's yield; Windows still takes the processor at the end of a time slice. Source A, the game held to 4 processors: half of its six executors' CPU time was inside that call, and without it the mean frame was 0.26 to 0.34 ms shorter; with 16 processors no difference. The risk is a thread yielding in a loop for one that waits on its processor, on PCs with 2 to 4 logical processors. Not set or 1: both, as before. With HOS_VCORES=0 the processor's yield stays whatever this says; SleepThread(0) and the short sleeps keep theirs (host/hos_thread.c os_yield, YieldThread) |
HOS_VCORE_SPIN_US=<us>, HOS_VCORE_SPIN_MAX=<n> |
(Triforce, on by default; HOS_VCORE_SPIN_US=0 as before) A game thread that waits for a virtual core it asked a holder to give up spins for it, up to 250 us, before it sleeps (host/hos_thread.c vc_spin, after NX2navi's core_take): the holder gives the core up at its next checkpoint, mostly within microseconds, and the waiter then runs without an OS wake. Who gets a core does not change, only how soon. At most HOS_VCORE_SPIN_MAX threads spin at once and the rest sleep at once: by default a quarter of the logical processors beyond 8, at most 4 (none with 8 or fewer, 1 with 12, 2 with 16). The vcores: line (every 5 s) counts the waits that ended in the spin and those that slept, the time spun, the spins left out for the cap, and how soon a granted core ran after a spin and after a sleep; the start's vcores: a waiter spins up to line says what is in effect. A yield with no thread waiting for a core takes no lock (NX2navi's yield fast path) |
HOS_VIDEO_ACQUIRE_TRIES=1, HOS_VIDEO_KEEP_CORE=1 |
(Triforce, on by default; each =1 as before) A movie's Acquire (host/nn_video.c dec_acquire) waits for a picture up to 100 ms by the clock, and not at all after a Stop or Flush with nothing submitted since: the old wait, 50 sleeps of 2 ms that each took 4-5 ms on Windows, ran out only after ~250 ms once a movie had stopped, a frame that long at every load from the title. It also decodes without the calling thread's virtual core, taken back only after the decoder's lock is let go, so other game threads run meanwhile. HOS_VIDEO_ACQUIRE_TRIES=1: the 50 sleeps; HOS_VIDEO_KEEP_CORE=1: the core held throughout |
HOS_VCORE_WIDE=1 |
(Triforce, 11-22, the performance audit's GAME-22, after Source B's; off unless set, never measured there or here) A game thread whose core mask names two or more cores takes any free virtual core, not only those. Source B's reason: the game's two main threads may run on two of three cores only, where per-core job workers of better priority preempt them while the other cores stand idle. A thread with a one-core mask, which guards the game's lock-free per-core data, or with no mask, stays where it was; no two threads ever run under one core number either way. The risk is the one HOS_VCORE_ANY=1 (every thread on any core, which crashed) has, for fewer threads: a thread that reads its core number, blocks and goes on under another. The log's vcores: ... asks for ideal core ... and core mask lines name every thread whose mask has two or more cores (all masks when the switch is set to anything): with no such line the switch changes nothing (host/hos_thread.c vc_allowed, core_mask_note) |
RX_VK_HELPER_SPIN_US=<us> |
(Triforce, on by default; =0 as before) The parallel replay's spins (gpu/vk/helper_spin.h, after NX2navi's replay workers): a helper thread with no segment to record spins up to 100 us for the next before it sleeps, and the replay thread spins as long for a segment a helper records before it sleeps for it. The frame statistics' its spins line, after the parallel replay's parts, says how often each ended in the spin or slept and the time spun |
HOS_X3D=0 |
(Windows) The game's threads and the replay's core are not kept on the die with the largest L3 cache. By default they are (the replay's core only where one is kept there: HOS_RESERVE_CORE), on a processor whose L3 caches differ in size and whose largest serves 8 or more cores (AMD's two-die X3D parts: a 7950X3D's or 9950X3D's 3D V-Cache die; host/hos_x3d.h), and the log's cpu: logical processors ... share the largest L3 cache line says so. On every other processor nothing changes and the log has no such line |
HOS_X3D=0 |
(Windows) The game's threads and the replay's core are not kept on the die with the largest L3 cache. By default they are, on a processor whose L3 caches differ in size and whose largest serves 8 or more cores (AMD's two-die X3D parts: a 7950X3D's or 9950X3D's 3D V-Cache die; host/hos_x3d.h), and the log's cpu: logical processors ... share the largest L3 cache line says so. On every other processor nothing changes and the log has no such line |
HOS_SIM_CPU=<cores>/<threads> |
(Triforce, 11-22, the performance audit's OS-49, after Source B's; a lab switch, off unless set; Windows) A PC with fewer cores, simulated: the process is held to <cores> of the PC's physical cores (the die with the largest L3 first, then the fastest class, then the last ones, so that the replay's kept core is among them; one core always stays out; host/hos_sim_cpu.h), set before any thread, and the renderer sizes its pools and thread counts by <threads> (gpu/vk/cpu_count.h: an affinity mask alone does not change hardware_concurrency). 6/12 and 4/8 play as those PCs' pools do; 6 alone is 6/6. The log says cpu: HOS_SIM_CPU= with the mask, or that it was not applied (then the variable is cleared and nothing changes). Not run in the game. tests/test_sim_cores.py |
RX_VK_SIM_GPU_SLOW=<factor> |
(Triforce, 11-22, the performance audit's OS-49, after Source B's; a lab switch, off unless set) A slower GPU, simulated (gpu/vk/sim_gpu.h): for each ms of work the recordings measure, (factor - 1) ms more, from over 1 to 10 (2.5 is read). A one-invocation compute loop (shaders/sim_gpu_burn.comp) ends the replay's own recordings between full barriers, inside the GPU time they are measured over, so the frame's GPU time and Resolution Auto see the slower card; a third timestamp a recording measures what the burn took and the difference is carried (owed time held between -50 and 100 ms, burns of 1 to 16 ms, the loop's time calibrated 0.8/0.2). A line every 10 s: work, added, the factor reached, dropped. It repeats the fast card's relative answer only: no bandwidth, driver or upscaler cost. Not run in the game. tests/test_sim_cores.py |
HOS_POWER_THROTTLING=1 |
(Windows) Windows' power throttling of a window not in front left as it is (for A/B runs). By default every run, the shader preparation's too, opts out of it at the start: full speed, not the efficiency speed (EcoQoS) Windows 11 gives such a process, and the 1 ms timer resolution kept, which Windows 11 may otherwise ignore for it (Windows 10: full speed only). The log's power: line says what Windows took |
HOS_HOST_ZSTD=0 or 2, HOS_HOST_ZSTD_AWAY=0/1/2 |
The game's files (.zs) are decoded by the host's zstd (third_party/zstd) instead of the game's own translated decoder: the host decodes what host/host_zstd.h takes (whole buffers, and the loading threads' streams with their content size and room for it), the game's code the rest, errors included. (Triforce, 11-21, the performance audit's IO-01) On when not set: the host is given the content's exact size to write into (libzstd may park literals in spare room past a block, where the game's decoder never writes), and check mode ran clean in the game. 0: the game's own decoder for everything, as before. 2: check, the game's code decodes everything and the host beside it, and the log's zstd check: ... MISMATCH and wrote past the end lines name every difference (its zstd: lines count what was compared). HOS_HOST_ZSTD_AWAY: which decodes give their virtual core up: 1 (not set) whole buffers with 128 KB of input or room, streams never; 0 none; 2 whole buffers and stream feeds from 64 KB, as it was. Game build e0f3ccfa only. The lift needs both of its calls (nx2/oot_patches.py patch_host_zstd): a build log that says the host's zstd decoder's calls were found at 1 of 2 places has one only, and the switch then covers only that function |
Building
A build reads and writes tens of gigabytes. When the game folder or the build files folder is on a hard drive,
make_game.py warns that an SSD is much faster and builds anyway (the builders ask before they start).
| Switch | What it does |
|---|---|
HOOKSHOT_JOBS=<n> (or --jobs) |
Compilers at once (default one per CPU thread, each started when the free memory holds it; HOOKSHOT_MEM_GATE=0 turns that check off) |
HOOKSHOT_LOW_PRIORITY=1 |
(Triforce, 11-22, the performance audit's OS-57) (Windows) The builders start the build tools (make_game.py and everything it runs) below normal priority, as every build was before. The default is normal priority: Source A reports, without a measurement, that below normal Windows kept the steps that are one process (the read, the lift) on a hybrid Intel CPU's efficiency cores while the performance cores idled, and a first build took over an hour. The compilers then compete with the desktop like any program (HOOKSHOT_JOBS bounds them). Read by Triforce Setup (setup/Setup.cs), the launcher's build (launcher/Logic/Build/BuildRunner.cs) and the two older builders (builder/HookshotBuilder/Runner.cs, builder/py/hookshot_builder/core.py build_priority); Linux sets no nice value either way. The shaders' preparation at a build keeps its workers below normal in the normal-class process (gpu/vk/vk_draw.cpp prepare_priority) |
HOOKSHOT_LIFT_JOBS=<n> |
Processes that write the lifted C. Forked on Linux and macOS: default the cores, at most 16, one per 2 GB of free memory. Spawned on Windows (nx2/emit_pool.py), where they also cut the big chunks and share the page marks: default half the processors, at most 8, one per GB of free memory. 1: one process, on every system; the C is the same whatever the count |
HOOKSHOT_KEEP_BUILD_FILES=1 |
Keeps the lifted C and the objects after a build, so that the next one compiles only what changed |
HOOKSHOT_LIFTED_C_REGEX=1 |
(Triforce, 11-22, the performance audit's IO-40) The lifted functions' definitions are found by the patterns' own finditer, tried at every line of the lifted C, as before. By default nx2/lifted_c.py's definitions and noted_starts jump from one "\nvoid f_" to the next and try the pattern only there, for build.py's memory estimate, chunks.py's costs and cuts and split_hot.py's pieces: the same matches (tests/test_lifted_c_scan.py), so the same files. lifted_c.py, chunks.py and split_hot.py are in the lift key: the first build with this change translates the game once more. The other half of the entry, translating while the package's romfs is still being extracted, is not here |
HOOKSHOT_KEEP_LIFT=0 |
(Triforce, 11-22, the performance audit's LIFT-27) The translated game is kept as little as before: its key (what decides whether a build translates the game again) hashes every A64_, OOT_ and RX_ variable and the folders' paths, and nx2/released_translation_stamp.json, and any failed build forgets it. By default the key takes of the environment only what shapes the C, the lifter's A64_ switches and RX_TARGET (tests/test_lift_key_env.py holds the lift's files to that), and leaves out the release's shader translation stamp, which build.py alone reads; and a build that failed in its compile, only in the program's own files (host/, the renderers) and in nothing the lift wrote, keeps the key once, so that the retry compiles the rest without translating the game again (a second such failure in a row forgets it, as a generated header cut short fails the program's own files too). The key changes once with this, and the two values of the switch have different keys. Not here yet: keeping the translated game after a player's finished build, which is the owner's decision (nx2/make_game.py lift_key, keep_lift_after_failure) |
HOOKSHOT_EARLY_COMPILE=0 |
(Windows) Not compiled beside the lift: libopus and the two renderers, which need no translated code. By default make_game.py starts build.py with RX_EARLY=1 for them while the game is translated (the lift's own processes take at most half the processors there), and the build proper finds their objects made |
HOOKSHOT_MEM_GIANT=1 or 0 |
Whether the memory gate counts a function of 1.2 MB or more by the square of its size (a chunk that is one 5 MB function takes 6.2 GB, not the 1.9 GB it is counted at otherwise). By default only on a PC with less than 14 GB free when the compile starts: with more, counting the giants in full halves the compilers running at once for no need |
HOOKSHOT_MEM_LOG=1 |
For each file compiled, @@mem <file> <peak MB> <counted MB> <seconds>: the most memory its compiler was seen holding, beside what the memory gate counted it at (mem_need in nx2/build.py). For fitting the gate after a change to the lift or the compiler |
HOOKSHOT_PROMPTS_FOLDER_KEY=0 |
(Triforce, 11-21, the performance audit's IO-43) A game built from romfs and exefs folders has its button prompts drawn at every build and update, as before. The default keeps them when nothing they are made from changed: with no unpack stamp to tell the dump by, the key is the content of the game's files the tool reads (the font, the textures, the layouts, the camera's pack, the size table, the dictionaries and every language's messages). Every game's key also holds host/prompts.c and the tools' release (nx2/make_game.py prompts_key, prompt_game_files) |
HOOKSHOT_PROMPTS_WIDEN_EACH=1 |
(Triforce, 11-22, the performance audit's IO-42) The button prompts' tool widens the "lines that stay" image (a 9 by 9 maximum, what a leader line pays to cross them) at every route, as before. By default the widened array is kept for the last image asked, and every route of one line is given the same image: 4 or 5 widenings a controller face where there were 35 or 37, each a filter over a 2-megapixel image (the five faces' lines on blank stand-in images: 21 s where they took 42). The lines drawn are the same (nx2/prompt_assets.py guide_widened) |
HOOKSHOT_DUMP_LINKS_LSTAT=1 |
(Triforce, 11-21, the performance audit's IO-41) A build from romfs and exefs folders checks them for links with an os.lstat for every entry, as before. The default reads each entry's kind and attributes from the folder's own listing (os.scandir), 1.3 to 1.5 s where the one-by-one check took 36 to 49 s over the game's 186,583 files, and stops the build at a folder it cannot list, which the walk passed over. The copy that follows makes each folder once and lets os.link say that a file is there already (nx2/make_game.py refuse_dump_links, link_or_copy) |
HOOKSHOT_NUP_IN_PLACE=0 |
(Triforce, 11-22, the performance audit's IO-51) A .nup package's unpack writes each file to <name>.part and renames it, and resolves the output folder and looks at every folder above the file for every file, as before. The default writes each file straight to its name (one os.lstat, then a create that fails if anything is there) and looks at each folder once: under a virus scanner on NTFS the temporary's create and rename and the repeated looks were most of a small file's cost over the game's 186,583 files. A file that is there whole is kept, one of another size is unlinked and written again, one whose write fails is deleted; the files written are the same (nx2/nup.py extract, Destination) |
HOOKSHOT_FINISH_COPY_ALL=1 |
(Triforce, 11-22, the performance audit's IO-45) The end of a build copies every file into the game folder as <name>.new and swaps it in, as before, and keeps no note. By default the finish notes in the game folder (.triforce_installed.json), for each file it installed, the SHA-1 of the source and the installed copy's size, modification time, file number and mode, and the next finish passes over a file whose source hashes the same and whose installed copy is still as noted, without reading it: image.bin and the prebuilt DLLs at an update that did not change them. The exe and the renderer are linked again at every build with the link's time in them, so they are still copied. A file not noted, changed by hand, on a file system without file numbers (FAT, exFAT), or under a note that does not read is copied; deleting the note copies everything (nx2/make_game.py INSTALLED_NOTE, installed_same) |
HOOKSHOT_LINK_REPRO=1 |
(Triforce, 11-22, the performance audit's IO-45) (Windows) The game's exe and the renderer are linked with /Brepro: lld writes a hash of the file where it otherwise writes the time of the link, so two links of the same objects are the same bytes, and the finish above passes an unchanged exe over instead of copying its 460 MB. Off unless set: it changes the bytes of every linked file once (nx2/build.py repro_link) |
HOOKSHOT_MINGW=<dir>, HOOKSHOT_MSVC=1 |
The llvm-mingw to build with; the Visual Studio route instead |
HOOKSHOT_WORK_LOCK=0 |
(Triforce, 11-22, the performance audit's IO-47) make_game.py takes no lock on its work folder, as before. By default it holds an OS lock on <work>/make_game.lock for as long as it runs (msvcrt.locking on Windows, flock elsewhere), taken after an earlier build left running is stopped and before the stale objects go: a second build on the same folder stops at once with the first one's process id instead of compiling the same objects again and racing on the staged game folder, which nothing prevented on Linux (two builders, a builder beside the launcher, --cli). The lock ends with its process, so a build that crashed never blocks the next; an error other than "held by another" is said and the build runs without the lock (nx2/make_game.py lock_work) |
HOOKSHOT_SINGLE_INSTANCE=0 |
(Triforce) Hookshot Builder takes no lock on its build tools, as before. By default a second builder for the same tools folder (builder/HookshotBuilder/Instance.cs, named after Tools.Root), its --cli included, waits up to 5 s for one that is ending, then says so and ends: two of them built into one work folder and stopped each other's build. Triforce Setup has its own lock (setup/Guard.cs Instance) |
TRIFORCE_LEGACY_PATHS=1 |
(Triforce) Triforce Setup keeps .NET Framework's legacy path checks, which refuse paths of 260 characters and more whatever its manifest says (an exe csc builds is taken as written for .NET 4.0). By default setup/Setup.cs Main sets the two switches 4.6.2 defaults to (Switch.System.IO.UseLegacyPathHandling, Switch.System.IO.BlockLongPaths) before any path is used, so that with Windows' own LongPathsEnabled on Setup reads and writes deep paths |
HOOKSHOT_SEGMENT_HEAP=0 |
(Triforce, Windows; on by default since 11-22: the lab's play A/B, 81.4 against 80.6 fps) The exe's manifest asks for Windows' segment heap (heapType SegmentHeap, Windows 10 2004 and newer) for the whole process, its DLLs and the graphics driver too, in place of the NT heap, whose lock AMD's driver's compile threads waited on through the shader preparation (nx2/win_manifest.py, tests/test_segment_heap.py). The heap is fixed when the process starts: a build with it and one without are the two arms. 0: the NT heap, as before. The log's the shaders' preparation runs on line names the process heap (segment or NT) |
RX_CPM=<dir>, WGPU_NATIVE=<dir> |
The CPM cache (Vulkan and SPIR-V headers, VMA, FFmpeg) and wgpu-native |
RX_TARGET=windows |
On Linux: the Windows game, with llvm-mingw's Linux build in HOOKSHOT_MINGW |
RX_RELEASE=1 |
A release build (make_game.py sets it): no console window, the shaders prepared before the title |
RX_VK_PGO=gen, =<file>, =0; RX_VK_PGO_FILE=<path> |
(Triforce, 11-21, the performance audit's LIFT-10) A play profile for the renderer's own code (gpu/vk/*.cpp; not the vendored recompiler, ImGui or zstd). gen: a build whose renderer counts its branches; run it with RX_VK_PGO_FILE=<path>, make <path>.reset once the scene to record is loaded and <path>.dump at its end, then llvm-profdata merge -o work\triforce_vk.profdata <path>. <file>: built with that profile (its contents are in the object keys, its path is not). Not set: make_game.py passes work\triforce_vk.profdata when the tools have one and the compiler can read it; 0: none. A profile from another version of the renderer is taken function by function, the changed ones built without it. Record it again for each release, and compare against RX_VK_PGO=0 before shipping one (nx2/build.py vk_pgo_flags, host/pgo_rt.c) |
RX_PGO=gen or RX_PGO=<file> |
The hot code counting its branches for a profile, or built with one (make_game.py passes the shipped profile) |
A64_HOT_STICKY=0 |
(Triforce, 11-22, the performance audit's LIFT-30, after Source A's; read when the game is translated, and in the lift key) nx2/split_hot.py deals the hot functions out afresh and gives every hot piece code_hot.c's whole preamble, as before. By default <work>\image\hot_pieces.txt keeps each hot function's piece: the next translation leaves the functions it knows where they were and puts a new one in the piece it shares the most calls with, else in the cheapest, unless that makes the costliest piece more than 1.15 times a fresh split's (then the split is the fresh one); and each piece keeps only the declarations of f_ and hos_ names it uses. An update that changes a few hot functions then compiles one or two hot pieces of about ten MB again, not up to eight. The functions' text is the same either way, and the hot profile goes by function name, so it fits both. The file is not in the lift key (tests/test_sticky_hot_pieces.py) |
RX_COLD_OPT=O2 or =<file>, RX_COLD_PART_MB=<n> |
(Triforce, 11-22, the performance audit's LIFT-17, after Source A's; opt-in) The hot pieces are compiled at -O2 with the play profile and every other lifted chunk at -O1. RX_COLD_OPT=O2: every other lifted chunk at -O2 too; =<file>: only the chunks the file lists, one file name a line (code_012.c). Unset, empty or O1: as before. Each -O2 chunk is compiled as parts of RX_COLD_PART_MB MB by the lift's own estimate (6 when unset; 0: no cut), cut only where a function begins and written under <build>/split with a key file a chunk, so a second build writes nothing (nx2/cold_parts.py, tests/test_chunk_parts.py): -O2's time grows with the square of a function's size. The lifted files themselves are not touched. Source A's figures: +4.4% and +5.5% fps where the game's update bounds the frame, for about twice the lifted compile's processor time (23 minutes against 5 without the cut); not built or measured with this game. The names begin with RX_, so setting them translates the game again once |
RX_MARCH=<level> |
The CPU level to build for (default this PC's: x86-64-v3, else x86-64-v2, else x86-64) |
RX_VK_ONLY=1 |
Only the Vulkan back end, with no lift |
OOT_WORK, OOT_DUMP, OOT_EXEFS, OOT_ROMFS |
The work folder and the dump's folders, over work/dump.txt |
HOS_MODS=<folder> |
The mods folder, in place of mods in the game folder: for the running game (RomFS mods, cheat files) and for a build (the code patches it applies) |
Mods: code patches and cheats
The game loads RomFS mods at its start (host/mods.c). The two kinds of mod that change what the game does go other
ways, because the game's code is C compiled ahead of time and cannot be patched while it runs.
The mods folder, for the game and for a build alike (host/mods.c find_mods, nx2/code_mods.py find_mods,
which must stay the same walk): a mod is a folder under mods that holds a romfs, exefs or cheats folder, at
most four levels down, and nothing below a mod is looked at. A folder whose name starts with - or _ is off, one
that starts with . is skipped. Mods are ordered by their path under mods, ASCII letters' case ignored, and the last
one wins. Triforce Setup's mod manager can switch a mod by renaming its folder and order mods by a prefix, and needs
no other file.
Code patches (<mod>/exefs/*.ips, *.pchtxt), nx2/code_mods.py:
make_game.pycallsbuild_steponce its copy of the game's code (<work>/exefs) is there and checked, after the copy the game folder keeps for updates (.triforce_exefs) is made and before the lift key is taken. The patches go into that copy, a module with a patch written again as a plain NSO, and the lift reads it:lift.py,chunks.pyand the rest of the translator know nothing of mods.- The lift key hashes the files of that copy, so the patched bytes are in it: a patch added, taken out, switched off
or edited translates the game again, a patch that changes no byte does not, and neither does a change to
code_mods.pyitself (LIFT_KEY_NOT). - A patch names its module by build id (the
.ipsfile's name, the.pchtxtfile's@nsobid-, trailing zeros left out or not) and may be for any module of the exefs. Offsets count the NSO's 0x100-byte header, as Atmosphere and the emulators read them;.pchtxtknows@flag offset_shift,@enabled,@disabled,@little-endian,@big-endianand@stop. Mods in order, a mod's files by name, the later write wins and the build says which file wrote over which. - A file is refused whole, with a line that says why: another build's, cut short, a value that cannot be read, a write into the header, past the image or between the segments. The last leaves out code caves, which the translator has not been tried on.
- The build writes
triforce_code_mods.txtinto the game folder when it is done: a line per patch file, tab separated,appliedorrefused, the file's FNV-1a 64 and size, its path under the mods folder, then the module and the bytes changed, or the reason. The next build (the game's update offer runs--update) reads the mods folder again, so the same patches are built in again, and says which of the record's are gone, changed or refused now. The game reads the record at its start (host/mod_code.h) and logs for each patch file whether it is built in or waits for a build, and which built-in patches are gone from the folder.
Cheats (<mod>/cheats/<first 16 digits of main's build id>.txt), host/mod_cheats.h and host/mod_cheats.c:
- Read at the start, run by an interpreter once a game frame, at the game's present and on its thread
(
hos_mod_cheats_frame). Nothing is compiled in, so a cheat file needs no build. NX2navi compiled in the cheats that write instructions; Triforce's translator has no switchable patches, so such a cheat (an opcode 0 into a module's.text) is refused and belongs in a code patch. - The opcodes it runs are listed at the top of
host/mod_cheats.h: 0 to A and C0 to C3 of Atmosphere's cheat machine. Any other is refused when the file is read, the whole cheat, by name. Registers are shared by one file's cheats within a frame and cleared between frames; a master code runs first. - Memory is the program image and the heap, each access checked (
mod_cheat_readable); the modules' code (hos_codein the generatedhos_image.c) is never written. Region 0 is the module main's base (hos_main_base), 1 and 2HOS_HEAP_BASE, 30x08000000, ashost/hos_svc.ctells the game. - Each cheat that is not a heading has a row on the System tab, 96 at most (
gpu/vk/mod_cheat_rows.h; option ids 130 to 133 ingpu/vk/vk_api.h). The rows are not in the options file:triforce_cheats.txtin the game folder has a line for each cheat that is on, its number (FNV-1a 32 of<mod>/<name>) and that text, and a cheat listed there is on at the start.
The options file
hookshot_options.ini, in the game folder, holds the Insert menu's rows as <key>=<number>: the row's name in lower
case with _ for spaces (frame_generation=2, invert_camera_x=1), except Output resolution, which is output_res.
gpu/vk/vk_menu.cpp writes the whole file at every change (save; (Triforce) merged by key with a change made outside the game meanwhile, and written whole: RX_VK_OPTIONS_MERGE above), with options_version=8,
microphone_device=<name> when a microphone is chosen by name, and the controls (pad_<button> and key_<button>:
the README's Controls). A value outside a row's range is clamped when it is read. Where the
number is not the obvious one:
| Key | Values |
|---|---|
gpu_device |
0 Auto, n the n-th card with Vulkan 1.3 as the row lists them |
frame_generation |
0 Off, 1 Auto, 2 to 8 the multiplier, 9 AMD FSR frame generation (the made frame by AMD's frame generation library, FSR 4's or FSR 3.1's by the card, with the picture without the HUD; paused with HDR Native or RenoDX's RGBA16F scene, where the renderer's own makes the frame as at 2x: gpu/vk/vk_fsr4.cpp fsr4fg; where that cannot run the value stays in the file and the row shows and runs 2x: gpu/vk/framegen_rows.h) |
dlss_frame_generation |
0 Off, 1 2x, 2 3x, 3 4x: NVIDIA DLSS frame generation, the Frame generation row's NVIDIA DLSS values (gpu/vk/merged_rows.h; read at the start, gpu/vk/vk_dlssg.cpp). The row sets frame_generation to 0 with it |
frame_rate_cap |
0 60, 1 90, 2 120, 3 144, 4 165, 5 240, 6 the monitor's refresh rate; -1 45, -2 40, -3 30 |
frame_pacing |
0 Off, 1 frames on an even line. With steady_frame_rate, the Frame pacing row (gpu/vk/merged_rows.h): Off is 0 and 0, Even 1 and 0, Steady (any rate) 1 and 1, Steady (refresh steps) 1 and 2 |
steady_frame_rate |
0 Off, 1 any rate (the cap, then 200, 180, 160, 144, 120, 110, 100, 90, 80, 72, 66, 60, 55, 50, 45, 40, 36, 30 under it), 2 whole divisions of the display's refresh rate under the cap, from 30 up (host/pace_steady.h) |
resolution |
0 Auto, 1 100%, 2 75%, 3 67%, 4 50%, 5 58%, 6 33% (with DLSS and FSR: 3 Quality, 5 Balanced, 4 Performance, 6 Ultra Performance; their Native (100%) is dlss 2, 5 or 6) |
output_res |
0 2048x1152, 1 2560x1440, 2 3840x2160, 3 1920x1080, 4 5120x1440, 5 5120x2880, 6 5120x2160, 7 1536x864 (the handheld profile; before options_version 8 it was handheld_profile=1, read as 7) |
ultrawide |
0 16:9, 1 16:10, 2 21:9, 3 32:9 (before options_version 6, 1 was the monitor's shape: read as the nearest of the four, gpu/vk/ultrawide_rows.h) |
hdr, renodx_hdr |
the HDR row (gpu/vk/merged_rows.h): hdr 0 Off, 1 Expanded, 2 Native (the game's own); renodx_hdr 1 with hdr 2 is Native + RenoDX |
nvidia_reflex, amd_anti-lag_2 |
the Low latency row by the card's maker: 0 Off, 1 On, 2 On + Boost (NVIDIA alone) |
hdr_paper_white, hdr_peak_brightness |
nits: 80 to 400, and 400 to 10,000 |
renodx_tonemapper |
0 Vanilla, 1 PsychoV35, 2 RenoDRT |
renodx_gamma_correction |
0 Off, 1 2.2, 2 BT.1886 (2.4) |
renodx_match_tone_slope |
0 Off, 1 On (as out of the box): PsychoV35's rows, with renodx_tone_slope and renodx_hue_clip |
renodx_tone_slope, renodx_highlight_saturation |
0 to 100, 50 unchanged: the first PsychoV35's, the second RenoDRT's |
renodx_blowout, renodx_flare |
0 to 100, 0 none: RenoDRT's |
renodx_hue_clip, renodx_hue_correction, renodx_color_grading |
percent, 0 to 100: 50, 100 and 100 out of the box; the first PsychoV35's, the others RenoDRT's |
dlss |
the Upscaler: 0 the game's own, 1 NVIDIA DLSS, 2 NVIDIA DLAA, 3 AMD FSR 3.1, 4 AMD FSR 4, 5 AMD FSR 4 Native AA, 6 AMD FSR 3.1 Native AA. The row names the engine; 2, 5 and 6 are its Native (100%) on the Render resolution row (gpu/vk/upscaler_rows.h) |
anti-aliasing |
0 the game's own SMAA, 1 Off, 2 FXAA, 3 SMAA Ultra |
texture_detail |
0 Automatic, 1 Full, 2 Reduced, 3 Low |
fps_counter |
0 Off, 1 On, 2 Full (NX2navi's full performance overlay in the counter's place: vk_menu.cpp draw_perf, the frame times and the figures per frame gpu/vk/perf_stats.h, the machine's numbers sampled twice a second on a thread of their own gpu/vk/perf_machine.cpp) |
opaque_textures_as_bc1 |
0 Off, 1 On |
sharpness, rumble_strength, motion_sensitivity_x, motion_sensitivity_y |
percent |
mouse_sensitivity |
hundredths: 100 is 1.00 |
left_stick_dead_zone, right_stick_dead_zone |
-1 Default (XInput's ~24%), 0 to 50 percent (before options_version 8 a stick_dead_zone of 1 to 5, 5, 10, 15, 20 or 30% for both sticks, is read into each stick's own where it had none) |
vibration_curve |
hundredths, 20 to 150: the power on the motors' rumble, 100 is 1.00 (none) |
walk_key |
0 Off, 1 Caps Lock, 2 Shift, 3 Ctrl, 4 Tab |
walk_scale |
hundredths, 20 to 90: 51 is 0.51 of the stick's travel |
robust_buffers |
0 Auto (on), 1 Off, 2 On |
game_speed |
0 Per frame, 1 Real time |
text_speed |
0 Normal, 1 2x, 2 4x, 3 Instant |
menu_sounds |
percent, 0 to 100: 80 unless set, 0 silent. The settings' own sounds, the game's interface sounds from its RomFS (host/menu_sound.c, gpu/vk/menu_sound_events.h; option ids 135 and 136), under master_volume |
microphone |
0 Off, 1 Default, 2 and up a microphone (the name in microphone_device decides which) |
mouse_camera |
0 As the stick, 1 Native |
layout_preset |
0 Nintendo, 1 Xbox / PC, 2 Swap Face, 3 Custom |
button_prompts |
0 Auto (the controller there at the start, XInput's without a name the Xbox's; none: the device used last in the run before, <user>/prompts_auto.txt, else the keyboard and mouse), 1 Switch, 2 Xbox, 3 PlayStation 4, 4 PlayStation 5, 5 Steam Deck, 6 Keyboard & mouse (host/prompts.c, nx2/prompt_keys.py) |
replay_helper_threads |
0 Off, 1 to 7 the parallel replay tried on 2 to 8 threads, 8 Automatic (the default; the Debug tab). A file that says 0 stays Off: delete the line, or choose Automatic on the Debug tab, for the default |
The Game language row is not in this file: its choice is the code line of language.txt in the game folder, which the
menu rewrites in place (gpu/vk/game_language.h: the code alone on that line, the rest of the file as it was, and only a
code the file itself names) and the host reads at the start (host/nn_applet.c). Nor are the Mod cheats rows: which
of a mod's cheats are on is the host's to keep, in triforce_cheats.txt (Mods: code patches and cheats above).
(Triforce) options_version=8 grouped the rows and merged those that chose one thing twice (gpu/vk/merged_rows.h; the
436f9ac-based builds wrote 7 for it, which v0.5.1 had already given to Frame pacing's default: its 7 still has the old rows'
lines, so a file before 8 is moved, and one of those builds' 7, without them, keeps what it has). A file
from before keeps its values; these lines are read once and not written again, their rows' jobs done otherwise:
quality_preset (the textures' and the mirrors' memory budgets are the card's own, from its video memory), upscaling
(the window's filter follows the sizes: gpu/vk/upscaler_rows.h auto_filter, AMD FSR 1 when the picture is enlarged, the
plain copy otherwise and always with HDR Native), reflex_frame_limit (off, the old default, until Reflex holding the cap
with DLSS frame generation has been played: RX_VK_REFLEX_LIMIT=1 for a run), handheld_profile (an output_res) and stick_dead_zone (each
stick's own).
The other rows are 0 Off and 1 On. Some are read at the start, before the menu exists, by the code that needs them:
output_res (host/nn_applet.c; 7 is the handheld profile), ultrawide (host/hos_main.c), frame_rate_cap
(host/nn_vi.c; the monitor's rate is the display's the window opens on, rounded, 30 to 240, and 60 when it cannot be read), robust_buffers
(gpu/vk/vk_main.cpp), texture_detail (gpu/vk/vk_texture.cpp, at the first texture) and the controls (host/nn_hid.c).
The renodx_ rows other than renodx_hdr are read at every frame (gpu/vk/vk_renodx.cpp fill_settings), and the
menu shows the rows of one tonemapper while it is the one chosen. RenoDX's mod for this game has Vanilla and PsychoV35;
RenoDRT and the gamma correction come from gpu/vk/shaders/renodx_glue, three files of Triforce's own that
scripts/renodx_shaders.py compiles together with RenoDX's scene shaders and its output encoder as the build fetched them
(nothing of RenoDX is in the repository or changed). RenoDRT calls RenoDX's library; the gamma correction is on the
finished picture, HUD included, and the tone mappers are given a peak with it taken out, so that the brightest light
still lands on the HDR peak brightness. A change to a glue file changes the stamp of renodx_spv.h, which the next build
then compiles again.
RivaTuner Statistics Server has no row: where it is installed and running it is the game's frame limiter, and an options
file that still has the test builds' rivatuner_limit= is read by nothing (the next save drops the line). A thread of
gpu/vk/rtss_limit.cpp looks twice a second: it puts the limit (gpu/vk/pace_rule.h pace_rtss_want: the cap in
effect, Monitor's rate and the caps under 60 included, times the frames shown for each of the game's with frame
generation 2x to 8x or AMD FSR 4) into RTSS's profile for the executable through RTSS's own hooks library
(RTSSHooks64.dll from RTSS's folder: FramerateLimit and FramerateLimitDenominator, nothing else, no other profile),
reads it back, and once RTSS is seen holding the game to it (gpu/vk/rtss_decide.h rtss_decide) the host's wait steps
aside (gpu/vk/vk_pace.cpp), the in-house frame generation's display thread leaves its own spacing of made frames to
RTSS, and Reflex is given no frame limit. A limit lower than the profile's waits 5 s before it is written, a higher one
1 s, so a multiplier that changes in play does not rewrite the profile each time. What the profile held is kept in
triforce_rtss_profile.txt in the game folder before the first change (one line per executable, the others' lines
kept, a file that does not read left alone) and goes back at the exit; the next start puts it back after a kill or a
crash, unless the player changed the profile since. The game's own wait holds the frames instead with frame generation
on Auto (its presents follow the screen's refresh, not the game, so no limit on them holds the game) and with DLSS frame
generation (Streamline presents on a pace of its own: HOS_RTSS_DLSSG=1 tries RTSS there), during movies (the profile
keeps the play limit), while no picture went out for 200 ms (a minimised window), while RTSS is not installed, not
running or has not hooked the game, and when the profile does not keep the limit (no administrator rights) or RTSS
refuses it, unless a limit the player set in RTSS, at or under the game's, holds the game (then RTSS holds movies too).
A hold needs a present since the frame start two frames back, so a window that stops showing gives the frames back
within two frames. RTSS's count past 1.05 times the limit three
periods running, 30 s hooked with the limit and no hold, or the game's frames coming sooner than the cap give the frames
back; RTSS is tried again a minute later (three times), and at once when RTSS starts again or another limit is wanted.
The game never starts RTSS, installs nothing and asks for no rights. vk: pace: lines in the log say which limiter is in
force and why; the Full overlay's Frame limit line names RivaTuner or NVIDIA Reflex after the rate when either holds the frames.
Layout
| Path | What |
|---|---|
docs/design.md |
why mkw-recomp's pipeline, the architecture, MKW's lessons as rules, stages, testing |
nx2/ |
the lift pipeline and its tests (mkw-recomp's, made game-neutral; kit.py has the paths), and make_game.py, which the builders run |
host/ |
the standalone Horizon runtime (TOTKPort's hos/ as adapted by mkw-recomp), with the native NVN2 layer nvn_native.c; host/posix has the Win32 calls on Linux |
gpu/vk/ |
the Vulkan back end (hookshot_vk.dll, hookshot_vk.so), with Eden's shader recompiler and sirit |
gpu/render/, gpu/third_party/ |
the WebGPU renderer the Windows exe falls back to when it was built with wgpu-native, its op stream (rx_nvn.h), suyu's decoders |
builder/ |
Hookshot Builder: the Windows app (.NET 8 WPF), its setup and MSI, and the Linux builder and launcher scripts |
setup/ |
Triforce Setup, the program players run (.NET Framework 4.8, WPF): Setup.cs installs, updates and runs make_game.py, Shell*.cs and Main.xaml are its window, Guard.cs is what keeps a run from damaging an install, Mods.cs the mods folder as the Mods page lists and changes it, Steam.cs and SteamArt.cs the Add to Steam shortcut and its pictures, Sound.cs the game's own decide and cancel sounds as Setup plays them (decoded in memory from the player's game folder: no sound is shipped; TRIFORCE_SOUND_LOG=<file> writes down, in a test run, the sounds that would have played) (CONTRIBUTING.md) |
scripts/ |
test runs, the profile and log readers, the save copier (oot_saves.py), release tooling, scripts/linux (dependencies, AppImage) |
tests/ |
the game-free checks, all run by tests/run_all.py |
third_party/ |
a64-kit (Hookshot's few changes marked (hookshot)), libopus, zbic (Atmosphere's zstd with ZBIC, for unpacking only), SDL2's licence, Dear ImGui and its Vulkan backend, zstd's decoder, the Libertinus fonts, SMAA's reference shader and lookup textures (the Anti-aliasing row's SMAA Ultra) |
License: GPL-3.0-or-later, as mkw-recomp: a64-kit's translator is suyu's (GPL-2.0-or-later) and Eden's code is GPL-3.0.