diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 555b41d5..eb22ae3b 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -8,14 +8,15 @@ body: - type: input id: version attributes: - label: Game version - description: As shown in the window title, for example 1.2.1. + label: Version + description: The title line of the settings menu (F1), for example "TotK Recomp 0.1.0, game 1.4.3". validations: required: true - type: input id: system attributes: label: GPU, driver and Windows version + description: Copy system info in the menu's Advanced tab puts them on the clipboard. validations: required: true - type: textarea @@ -28,4 +29,4 @@ body: id: log attributes: label: Log - description: Attach the log file from the run where it happened. + description: Attach logs\totk.log from the folder of totk.exe. After a crash, copy it before you start the game again. diff --git a/AGENTS.md b/AGENTS.md index 9306b608..ef92d714 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,7 +27,7 @@ This repository is public. Game data lives outside it and every derived file sta - Every lifter change passes the differential tests against Unicorn ([docs/building.md](docs/building.md), "Checks"). After changing `recomp/jumptables.py`, `tests\jumptables_check.py` reports 0 disagreements on 1.2.1 and 1.4.3. - `recomp/layout.py` alone decides module bases. - Graphics bugs: [docs/maxwell.md](docs/maxwell.md) lists the Maxwell behaviour the Vulkan path must match and the TotK bugs other ports fixed. -- Comments say what the code does and why. Cite code by file plus function and what it does; a line number may follow as a hint. +- Comments say what the code does and why, in words that stand on their own. Cite our code by file plus function (a line number may follow as a hint) and upstream code by project, file and function: `refs/` moves, so its line numbers rot. Commit hashes belong to the attribution of copied code. ## Writing diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3f160087..1b404f3e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,6 +32,8 @@ Use the issue form. Include the port version and game update from the title line - One topic per pull request. - Describe the problem, then what changed. - Say how you tested it: which version, which scene, how long. +- A change to the lifter (`recomp/`) or the CPU headers passes the differential tests in [docs/building.md](docs/building.md), "Checks". +- Commit messages are plain sentences, without `feat:` or other prefixes. - AI-assisted code is welcome. You are responsible for having read and run it. ## Code and docs diff --git a/README.md b/README.md index 2d21832c..8a32bca1 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ The Switch code is translated from ARM64 to C ahead of time and compiled into a ## Status -Early development. The game is playable on Windows, with visual bugs and crashes still expected. macOS, Linux and the Steam Deck are planned. +Early development. The game is playable on Windows; visual bugs and crashes are still expected. Linux and the Steam Deck are planned. Report problems as issues, following [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/docs/maxwell.md b/docs/maxwell.md index 093d6e60..c8fa4886 100644 --- a/docs/maxwell.md +++ b/docs/maxwell.md @@ -15,8 +15,10 @@ Source shorthands: . - **RYU-SH**: Ryujinx shader translator vendored at `refs/MacNativeGames/vendor/ryujinx/src/Ryujinx.Graphics.Shader/` (Ryujinx 1.3.2, MIT). Paths below are relative to it. -- **NXN**: `refs/nxnative/docs/agents/04-graphics.md` (MIT). -- **MNG**: `refs/MacNativeGames` (MIT). +- **NXN**: nxnative's graphics notes, `refs/nxnative/docs/agents/` (MIT). nxnative has rewritten them since; each + row states the behaviour and fix it took from them. +- **MNG**: `refs/MacNativeGames` @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (MIT); line numbers below are at that + commit. - **DK3D**: `refs/deko3d` @ `373bfd43d8b2d805fa2eb7d406dbb823032df958` (zlib, fincs), the homebrew Maxwell driver for Switch. Written against the hardware, not the NVN API: what it programs is what the GPU needs. Paths relative to `source/`. `.def` files give methods as word indices (`engine_3d.def`); byte offset = index x 4, so `0x5A1` = OGD `0x1684`. No conditional rendering, no @@ -31,50 +33,50 @@ Source shorthands: | # | Maxwell / NVN | Vulkan / AMD | Emulators / ports | Source | |---|---|---|---|---| -| 1.1 | **Colour target the fragment shader does not write keeps its old texel**, even with blending enabled. | Undefined value written/blended. | NXN: zero write mask and no blend for unwritten outputs (`reflection colors`). Already fixed here. | NXN:122; MNG `games/totk/tests/metal_semantics/probe.m:5` | -| 1.2 | **Unwritten vertex outputs read as (0, 0, 0, 1)** in the next stage, including the unwritten components of a partly written output (VS writes xyz, FS divides by w). | FS input with no VS output: interface mismatch, value undefined; an unwritten component of a written output is undefined (AMD: whatever the register holds, often 0). | Ryujinx initialises exactly the components the next stage reads, but only when stages are linked (`Translation/Translator.cs:212-227`, `NextInputAttributesComponents`); position starts (0,0,0,1) (`:259`). NXN Link's Awakening: sun shadow lookups divided by w = 0, scene dim, no shadows. Ours: missing outputs padded with (0, 0, 0, 1), unlinked outputs initialised by translator patch 0006 (section 7, check 2). | NXN:84, NXN:151 | -| 1.3 | **Clears honour the scissor and the clear's own channel / stencil write mask**, and may come between draws inside a pass. `SET_CLEAR_SURFACE_CONTROL` (0x10f8) has `RESPECT_STENCIL_MASK`, `USE_CLEAR_RECT`, `USE_SCISSOR0`, `USE_VIEWPORT_CLIP0`. | `vkCmdClearAttachments` takes a rect but **ignores the colour write mask**; load-op clears are whole-attachment. | NXN/MNG draw a triangle with the clear's mask (`clear_color_tri`, `clear_ds_tri`); TotK uses mid-pass, partial-mask and partial-scissor clears (NXN:174). yuzu: "red dot" was clears hitting the wrong RT index (YZ-2305, PR 10243). Hardware recipe (DK3D): `CLEAR_BUFFERS` (`0x674` = 0x19d0) carries the colour channel mask (bits 2-5), depth (0), stencil (1), target id (6-9) and layer (10-20) in one word; `ClearBufferFlags` (`0x43E` = 0x10f8) is set once to `StencilMask | Scissor` (`maxwell/gpu_3d_base.cpp:69`), so every clear is cut by scissor 0 and its stencil bits by the stencil front write mask register, and DK3D's colour clear does not program `ColorWriteMask` (`0x680`). A stencil clear writes `StencilFrontMask` (`0x4E7`) and `ClearStencil` (`0x368`) just before the clear and restores the shadowed state after (`gpu_3d_base.cpp:497-510`). Multisample raster is switched off around a colour clear (`:459, :465`). Arrays: an MME macro repeats the clear for every layer (`maxwell/clear_buffers.mme:5-22`). No pass concept: clears sit between draws. Ours: masked colour and stencil clears are **skipped** (check 3). | OGD 0x10f8; NXN:81, NXN:174; DK3D `maxwell/gpu_3d_base.cpp:444-512`, `engine_3d.def:305, 644` | -| 1.4 | **Conditional rendering** (`SET_RENDER_ENABLE_A..C` 0x1550-0x1558, NVN `SetRenderEnableConditional`) compares two 64-bit counters at `addr` and `addr+16` on the GPU, in command order. TotK wraps nearly every clear in it. A `TIMESTAMP` report writes 0 to the counter field. | `VK_EXT_conditional_rendering` tests one 32-bit word against zero. | NXN: honouring it fixed the black 3D scene (light-volume depth never cleared). deko3d has no conditional rendering at all (no `SET_RENDER_ENABLE` in `engine_3d.def`), so it cannot settle the compare rule. Ours: evaluated on the CPU at record time; a report from an unfinished submission counts as 0 (check 5). | OGD; NXN:173 | -| 1.5 | **Depth mode** is runtime state: `nvnDeviceSetDepthMode` near = -w (GL, NVN default) or 0. Register `SET_VIEWPORT_Z_CLIP` (0x0d7c) `NEGATIVE_W_TO_POSITIVE_W` / `ZERO_TO_POSITIVE_W`. | Vulkan clips z < 0 unless `VK_EXT_depth_clip_control` `negativeOneToOne`. | Ryujinx infers the mode from the viewport transform, falling back to the register (`GetDepthMode`, RYU-SU). NXN: wrong mode either clips everything (black window) or puts all depth in 0.5..1 (DOF blurs the screen). Ours: `negativeOneToOne` from NVN state. DK3D programs both halves: `SetDepthMode` (`0x35F` = 0xd7c) selects the pre-transform clip range, and the viewport transform maps z to [near, far] itself: scale z = `0.5 * (far - near)` and offset z = `0.5 * (near + far)` for -1..1, scale `far - near` and offset `near` for 0..1 (`maxwell/gpu_3d_base.cpp:143-147, 336-343`). Same maths as Vulkan `negativeOneToOne`. | OGD 0x0d7c; NXN:55-64, NXN:150; DK3D `maxwell/gpu_3d_base.cpp:136-147, 321-362` | +| 1.1 | **Colour target the fragment shader does not write keeps its old texel**, even with blending enabled. | Undefined value written/blended. | NXN: zero write mask and no blend for unwritten outputs (`reflection colors`). Already fixed here. | NXN; MNG `games/totk/tests/metal_semantics/probe.m:5` | +| 1.2 | **Unwritten vertex outputs read as (0, 0, 0, 1)** in the next stage, including the unwritten components of a partly written output (VS writes xyz, FS divides by w). | FS input with no VS output: interface mismatch, value undefined; an unwritten component of a written output is undefined (AMD: whatever the register holds, often 0). | Ryujinx initialises exactly the components the next stage reads, but only when stages are linked (`Translation/Translator.cs:212-227`, `NextInputAttributesComponents`); position starts (0,0,0,1) (`:259`). NXN Link's Awakening: sun shadow lookups divided by w = 0, scene dim, no shadows. Ours: missing outputs padded with (0, 0, 0, 1), unlinked outputs initialised by translator patch 0006 (section 7, check 2). | NXN | +| 1.3 | **Clears honour the scissor and the clear's own channel / stencil write mask**, and may come between draws inside a pass. `SET_CLEAR_SURFACE_CONTROL` (0x10f8) has `RESPECT_STENCIL_MASK`, `USE_CLEAR_RECT`, `USE_SCISSOR0`, `USE_VIEWPORT_CLIP0`. | `vkCmdClearAttachments` takes a rect but **ignores the colour write mask**; load-op clears are whole-attachment. | NXN/MNG draw a triangle with the clear's mask (`clear_color_tri`, `clear_ds_tri`); TotK uses mid-pass, partial-mask and partial-scissor clears (NXN). yuzu: "red dot" was clears hitting the wrong RT index (YZ-2305, PR 10243). Hardware recipe (DK3D): `CLEAR_BUFFERS` (`0x674` = 0x19d0) carries the colour channel mask (bits 2-5), depth (0), stencil (1), target id (6-9) and layer (10-20) in one word; `ClearBufferFlags` (`0x43E` = 0x10f8) is set once to `StencilMask | Scissor` (`maxwell/gpu_3d_base.cpp:69`), so every clear is cut by scissor 0 and its stencil bits by the stencil front write mask register, and DK3D's colour clear does not program `ColorWriteMask` (`0x680`). A stencil clear writes `StencilFrontMask` (`0x4E7`) and `ClearStencil` (`0x368`) just before the clear and restores the shadowed state after (`gpu_3d_base.cpp:497-510`). Multisample raster is switched off around a colour clear (`:459, :465`). Arrays: an MME macro repeats the clear for every layer (`maxwell/clear_buffers.mme:5-22`). No pass concept: clears sit between draws. Ours: masked colour and stencil clears are **skipped** (check 3). | OGD 0x10f8; NXN; DK3D `maxwell/gpu_3d_base.cpp:444-512`, `engine_3d.def:305, 644` | +| 1.4 | **Conditional rendering** (`SET_RENDER_ENABLE_A..C` 0x1550-0x1558, NVN `SetRenderEnableConditional`) compares two 64-bit counters at `addr` and `addr+16` on the GPU, in command order. TotK wraps nearly every clear in it. A `TIMESTAMP` report writes 0 to the counter field. | `VK_EXT_conditional_rendering` tests one 32-bit word against zero. | NXN: honouring it fixed the black 3D scene (light-volume depth never cleared). deko3d has no conditional rendering at all (no `SET_RENDER_ENABLE` in `engine_3d.def`), so it cannot settle the compare rule. Ours: evaluated on the CPU at record time; a report from an unfinished submission counts as 0 (check 5). | OGD; NXN | +| 1.5 | **Depth mode** is runtime state: `nvnDeviceSetDepthMode` near = -w (GL, NVN default) or 0. Register `SET_VIEWPORT_Z_CLIP` (0x0d7c) `NEGATIVE_W_TO_POSITIVE_W` / `ZERO_TO_POSITIVE_W`. | Vulkan clips z < 0 unless `VK_EXT_depth_clip_control` `negativeOneToOne`. | Ryujinx infers the mode from the viewport transform, falling back to the register (`GetDepthMode`, RYU-SU). NXN: wrong mode either clips everything (black window) or puts all depth in 0.5..1 (DOF blurs the screen). Ours: `negativeOneToOne` from NVN state. DK3D programs both halves: `SetDepthMode` (`0x35F` = 0xd7c) selects the pre-transform clip range, and the viewport transform maps z to [near, far] itself: scale z = `0.5 * (far - near)` and offset z = `0.5 * (near + far)` for -1..1, scale `far - near` and offset `near` for 0..1 (`maxwell/gpu_3d_base.cpp:143-147, 336-343`). Same maths as Vulkan `negativeOneToOne`. | OGD 0x0d7c; NXN-64, NXN; DK3D `maxwell/gpu_3d_base.cpp:136-147, 321-362` | | 1.6 | **Depth clamp / clip**: `SET_VIEWPORT_CLIP_CONTROL` (0x193c) has separate `PIXEL_MIN_Z`/`PIXEL_MAX_Z` CLIP or CLAMP and geometry-clip modes. | `depthClampEnable` also disables z clipping (unless `VK_EXT_depth_clip_enable`). RADV had a dynamic depth clamp driver bug causing TotK vertex explosions. | Ryujinx: clamp = `!(clip & DepthClampDisabled)` (RYU-SU `UpdateDepthClampState`). yuzu disabled dynamic depth clamp on affected RADV (YZ-2305, PR 10262). DK3D has one switch, `depthClampEnable`, and writes `VIEW_VOLUME_CLIP_CONTROL` (`0x64F` = 0x193c) with `0x101A` when on and `0x181D` when off (default at setup is `0x181D`); it labels the bits "todo: figure out what this actually does". Bits 3-4 (`DepthClampNear/Far`) are set in both values, bits 0-2 and 11 differ. There is no separate depth-clip toggle. The viewport near/far registers (`Viewport` array words 2-3) carry the clamp range and are swapped when far < near (`:349-350`). Vulkan clamp to [min, max] of the viewport depth matches. | OGD 0x193c; DK3D `maxwell/gpu_3d_state.cpp:42`, `gpu_3d_base.cpp:135-139, 349-350`, `engine_3d.def:621` | | 1.7 | **Depth formats**: D24S8 is native; D24 quantises to 2^-24 everywhere in 0..1. Polygon offset units are in D24 steps for D24 targets; `SET_DEPTH_BIAS_CONTROL` (0x1110) `DEPTH_FORMAT_DEPENDENT`. | RX 9070 has no D24S8 attachment; D32F has finer steps near 0 and a per-primitive exponent-based r. EQUAL / LEQUAL tests between a pre-pass and a later pass, and decal biases, behave differently. | yuzu rescales depth-bias units when D24 is emulated as D32F; Ryujinx passes `units / 2` (register is twice the API value) (RYU-SU `UpdateDepthBiasState`). MNG: D16 load-clear 0.5 → 32767 vs fragment 0.5 → 32768 made Ultrahand/Recall classification tiles visible. Ours: D24S8 → D32_SFLOAT_S8, bias not rescaled (check 4). DK3D writes `PolygonOffsetUnits` (`0x56F` = 0x15bc) as `constantFactor * 2.0f`, clamp to `0x61F`, factor to `0x55B` (`maxwell/gpu_3d_state.cpp:148-157`), confirming the x2 register. | OGD 0x1110, 0x15bc, 0x156c; MNG `docs/how-it-works.md:57-61`; DK3D `maxwell/gpu_3d_state.cpp:154` | -| 1.8 | **Position invariance**: identical position math gives identical depth across programs (pre-pass then EQUAL / LEQUAL). | Only for outputs declared `Invariant`. | Ryujinx decorates position `Invariant` (`CodeGen/Spirv/Declarations.cs:571`) and marks float ops `NoContraction` unless `QueryHostReducedPrecision` (`CodeGen/Spirv/Instructions.cs:2047`). NXN: Odyssey ground z-fought without it; LA's foliage drawn with depth EQUAL vanished when the pre-pass failed. Ours: translator default (all NoContraction). | NXN:85, NXN:147 | +| 1.8 | **Position invariance**: identical position math gives identical depth across programs (pre-pass then EQUAL / LEQUAL). | Only for outputs declared `Invariant`. | Ryujinx decorates position `Invariant` (`CodeGen/Spirv/Declarations.cs:571`) and marks float ops `NoContraction` unless `QueryHostReducedPrecision` (`CodeGen/Spirv/Instructions.cs:2047`). NXN: Odyssey ground z-fought without it; LA's foliage drawn with depth EQUAL vanished when the pre-pass failed. Ours: translator default (all NoContraction). | NXN | | 1.9 | **Sampling a texture that is also a bound render target**: Maxwell's texture cache is not coherent with ROP writes; NVN requires `nvnCommandBufferBarrier(INVALIDATE_TEXTURE)` between writing and sampling (methods `INVALIDATE_TEXTURE_DATA_CACHE` 0x1338, `..._NO_WFI` 0x1288). Reading a different level/layer, or read-only depth while testing, is fine. | Same image as attachment and sampled in one pass is a feedback loop: undefined unless `VK_EXT_attachment_feedback_loop_layout`; on AMD DCC/HTILE-compressed data is not readable by the sampler without decompression. | yuzu: pixelated Ultrahand glow fixed with barriers on attachment feedback loops (YZ-2305, PR 10402). BotW black textures on GCN worked around with `AMD_DEBUG=nohyperz` (HTILE off) (). Ours: an NVN barrier ends the pass and inserts a full memory barrier; no detection of a sampled texture that is a current attachment (check 10). DK3D barrier recipe (`maxwell/gpu_base.cpp:49-115`): the ordering part and the cache part are separate. Ordering: Tiles = `TiledCacheBarrier` (`0x3DF`), Fragments = `FragmentBarrier` (`0x378`), Primitives = `WaitForIdle` (`0x44`), Full = gpfifo `SetReference` + new gpfifo entry with `NoPrefetch`, so later command and indirect-parameter fetch happens after everything finished. Tiles and Fragments need an implicit WFI before a cache invalidate. Caches (each opt-in): texture data `InvalidateTextureDataCache` (`0x3DD`, WFI) or `..NoWfi` (`0x4A2`); shader `InvalidateShaderCaches` (`0x369`: instruction, global data, constant); descriptors `InvalidateTextureHeaderCacheNoWfi` (`0x50A`) + `InvalidateSamplerCacheNoWfi` (`0x509`); zcull `0x4B2`; L2 gpfifo `MemOpB` `L2FlushDirty` + `L2SysmemInvalidate`. The texture-cache invalidate is its own flag; ordering alone does not refresh it. Every queue flush ends with image + shader + descriptor + L2 invalidation "to ensure the visibility of CPU updates between flushes" (`:28-47`): CPU writes into textures and descriptors reach the GPU at the next submit boundary, not mid-submit (2.2). | OGD; DK3D `maxwell/gpu_base.cpp:28-115` | -| 1.10 | **Duplicate attachments**: the same texture bound at two colour slots with write mask 0 on one does not interfere (ROP writes only enabled channels). | Tile-based or compressed attachments may store the unwritten copy over the written one. | NXN BotW G-buffer (c1 = c2, c3 = c4): leaves the duplicate slot unattached (`rt_dup_slot`). | NXN:130 | +| 1.10 | **Duplicate attachments**: the same texture bound at two colour slots with write mask 0 on one does not interfere (ROP writes only enabled channels). | Tile-based or compressed attachments may store the unwritten copy over the written one. | NXN BotW G-buffer (c1 = c2, c3 = c4): leaves the duplicate slot unattached (`rt_dup_slot`). | NXN | | 1.11 | **Per-target write masks**: `RtColorMask[i]`, or entry 0 for all when `RtColorMaskShared`. `SET_SINGLE_CT_WRITE_CONTROL` (0x0f90). A colour target with format 0 is disabled. | Per-attachment `colorWriteMask`. | RYU-SU `UpdateRtColorMask`, `IsRtEnabled` ("Colors are disabled by writing 0 to the format"). | OGD 0x0f90 | -| 1.12 | **sRGB render target views**: NVN encodes on write when the view format is sRGB over a linear texture. Maxwell also has a global `SET_SRGB_WRITE` (0x15b8). | Format of the attachment view decides; needs `MUTABLE_FORMAT`. | NXN Mario: attaching the base texture stored linear values, picture darker. Ours: RT views take the view format (`view_format`). | OGD 0x15b8; NXN:69 | -| 1.13 | **Compressed and 3D targets**: agl's GPU BC4 encoder renders blocks through an `RGBA16UI` view, one plane of a 32×32×32 BC4 3D texture per pass. NVN renders a 3D texture slice by slice. | Needs `BLOCK_TEXEL_VIEW_COMPATIBLE` + `EXTENDED_USAGE`, `2D_ARRAY_COMPATIBLE`. | NXN shadow textures (`bcrt_attach`). yuzu: wrong block depth on 3D slices gave Gloom textures on terrain (YZ-2305, PR 10433). Already fixed here. | NXN:132, NXN:176 | -| 1.14 | **Draw with no render target** (fragment shader only writes an SSBO, 1×1 viewport) runs normally. | Needs an attachment-less pass with explicit render area. | NXN `bare_dims`: cave ambient light came back. Ours: area of viewport 0 (`vk_exec.c` `resolve_rt`). | NXN:177 | -| 1.15 | **Window origin**: NVN default lower-left (GL); TotK switches to upper-left. Y flip and scissor flip follow. | Vulkan upper-left; negative viewport height to flip. | Ryujinx flips scissor against screen height when Y-negate is on (RYU-SU `UpdateScissorState`). | NXN:145 | +| 1.12 | **sRGB render target views**: NVN encodes on write when the view format is sRGB over a linear texture. Maxwell also has a global `SET_SRGB_WRITE` (0x15b8). | Format of the attachment view decides; needs `MUTABLE_FORMAT`. | NXN Mario: attaching the base texture stored linear values, picture darker. Ours: RT views take the view format (`view_format`). | OGD 0x15b8; NXN | +| 1.13 | **Compressed and 3D targets**: agl's GPU BC4 encoder renders blocks through an `RGBA16UI` view, one plane of a 32×32×32 BC4 3D texture per pass. NVN renders a 3D texture slice by slice. | Needs `BLOCK_TEXEL_VIEW_COMPATIBLE` + `EXTENDED_USAGE`, `2D_ARRAY_COMPATIBLE`. | NXN shadow textures (`bcrt_attach`). yuzu: wrong block depth on 3D slices gave Gloom textures on terrain (YZ-2305, PR 10433). Already fixed here. | NXN | +| 1.14 | **Draw with no render target** (fragment shader only writes an SSBO, 1×1 viewport) runs normally. | Needs an attachment-less pass with explicit render area. | NXN `bare_dims`: cave ambient light came back. Ours: area of viewport 0 (`vk_exec.c` `resolve_rt`). | NXN | +| 1.15 | **Window origin**: NVN default lower-left (GL); TotK switches to upper-left. Y flip and scissor flip follow. | Vulkan upper-left; negative viewport height to flip. | Ryujinx flips scissor against screen height when Y-negate is on (RYU-SU `UpdateScissorState`). | NXN | | 1.16 | **Multiple viewports / scissors** (16), selected by `ViewportIndex` output. | Needs `multiViewport` and `shaderOutputViewportIndex`. | Ours: one viewport, one scissor; differing scissors logged (`nvn_api_cmd.c`). | OGD 0x192c | | 1.17 | **Fragment output saturation** per target: `SET_PS_SATURATE` (0x13a8) clamps output n to 0..1 or -1..1 in fixed function. NVN does not expose it (GLSLC emits `.SAT` in code). | None. | Not emulated by Ryujinx; listed so a clamp difference is not chased in the wrong place. | OGD 0x13a8 | -| 1.18 | **New memory reads as zero** (fresh pool pages); feedback effects never clear their state texture. | New image content undefined. | NXN `tex_zero_fill`. | NXN:80 | -| 1.19 | **MSAA**: `nvnCommandBufferDownsample` resolves; depth-stencil downsamples are copies the game does itself. | `vkCmdResolveImage` colour only; integer formats pick one sample. | NXN LA: stencil lost in the half-size depth copy, no AO. | NXN:148 | +| 1.18 | **New memory reads as zero** (fresh pool pages); feedback effects never clear their state texture. | New image content undefined. | NXN `tex_zero_fill`. | NXN | +| 1.19 | **MSAA**: `nvnCommandBufferDownsample` resolves; depth-stencil downsamples are copies the game does itself. | `vkCmdResolveImage` colour only; integer formats pick one sample. | NXN LA: stencil lost in the half-size depth copy, no AO. | NXN | ## 2. Textures and samplers | # | Maxwell / NVN | Vulkan / AMD | Emulators / ports | Source | |---|---|---|---|---| | 2.1 | **Automatic block height**: NVN truncates `height_in_blocks * 1.5 / 8` before picking the GOB power of two (deko3d rounds up). Wrong H reads padding: 160×160 BC3 warp pad half black. Allocation size is the same, so size checks do not catch it. Mip levels shrink the block height while the level fits in half of it. | Opaque optimal tiling. | MNG fixed (40 SDK-measured cases, `games/totk/tests/texture_auto_layout/probe.c`). Ours: truncating form already (`runtime/nvn_tex.c`, the block-height pick). DK3D reads: height in block rows (rounded up), x 1.5, then `(h + 7) / 8` rounded up, then the largest power of two <= that, capped at 16 GOBs (`dk_image.cpp:444-447`, `pickTileSize` `:13-20`); 3D uses `depth + depth / 2` directly as the GOB count (`:451-454`); video images are fixed at 2 GOBs (`:438`). Per level, the shift drops while `unit << (shift - 1) >= level dimension` with unit 8 rows / 1 slice (`adjustTileSize` `:23-37`, used at `:89-91`), width tile is always 0. Array layers are padded to the block shrunk to the full height / depth (`alignLayerSize` `:57-72`). Every one of these matches `nvn_tex.c` except the rounding. | MNG `docs/how-it-works.md:47-53`; DK3D `dk_image.cpp:13-37, 57-72, 80-103, 436-455` | -| 2.2 | **Textures filled by the CPU with no NVN flush** (TotK terrain: two 121-layer ASTC 8×8 arrays, 42 MB each; BC4 material textures read back with `ReadTexels` and copied into a 5120×5120 roughness atlas). The CPU and GPU share memory, so no flush is needed on the Switch. | Host images are copies; must detect CPU writes. | NXN write-protects texture pages (`tex_dirty_upload`); zero ASTC decodes magenta, zero BC black. yuzu: small CPU writes into GPU-used pages not invalidated gave slow rain/snow particles and teleport particle corruption (YZ-2306, PR 10942). Ours: `GetWriteWatch` generations (`vk_memory.c`, `mem_written_pages`). | NXN:174-175 | -| 2.3 | **Same storage, new texture object every frame** (transient targets, deferred handles). Same storage with a different descriptor reinterprets the same block-linear bytes. | Two `VkImage`s over one allocation with optimal tiling do not share a defined layout (AMD tiling and DCC metadata are per image); a new image starts `UNDEFINED`. | NXN shares host textures by `(pool, offset, description)`; MNG keeps a "live texture at address" redirect. yuzu: whole areas black for a frame on camera changes from texture-cache alias/overlap ordering (YZ-2305, PR 10418). Ours: GPU-only pool textures are `VkImage`s bound onto pool memory (check 7). | NXN:70; MNG `docs/how-it-works.md:67-71` | -| 2.4 | **Deferred texture handles** (`BindTexturesDeferred`): the GPU reads the handle from memory when the command runs; BotW records command blocks once and writes handles later. | n/a | NXN BotW: handles copied at record time were zero, 3D scene black. | NXN:129 | +| 2.2 | **Textures filled by the CPU with no NVN flush** (TotK terrain: two 121-layer ASTC 8×8 arrays, 42 MB each; BC4 material textures read back with `ReadTexels` and copied into a 5120×5120 roughness atlas). The CPU and GPU share memory, so no flush is needed on the Switch. | Host images are copies; must detect CPU writes. | NXN write-protects texture pages (`tex_dirty_upload`); zero ASTC decodes magenta, zero BC black. yuzu: small CPU writes into GPU-used pages not invalidated gave slow rain/snow particles and teleport particle corruption (YZ-2306, PR 10942). Ours: `GetWriteWatch` generations (`vk_memory.c`, `mem_written_pages`). | NXN-175 | +| 2.3 | **Same storage, new texture object every frame** (transient targets, deferred handles). Same storage with a different descriptor reinterprets the same block-linear bytes. | Two `VkImage`s over one allocation with optimal tiling do not share a defined layout (AMD tiling and DCC metadata are per image); a new image starts `UNDEFINED`. | NXN shares host textures by `(pool, offset, description)`; MNG keeps a "live texture at address" redirect. yuzu: whole areas black for a frame on camera changes from texture-cache alias/overlap ordering (YZ-2305, PR 10418). Ours: GPU-only pool textures are `VkImage`s bound onto pool memory (check 7). | NXN; MNG `docs/how-it-works.md:67-71` | +| 2.4 | **Deferred texture handles** (`BindTexturesDeferred`): the GPU reads the handle from memory when the command runs; BotW records command blocks once and writes handles later. | n/a | NXN BotW: handles copied at record time were zero, 3D scene black. | NXN | | 2.5 | **Border colours**: any RGBA (TSC words 4-7, plus sRGB border fields). TotK/BotW grass interaction map clamps to (0.5, 0.5, 0.5, 0.5), its "untouched" value. | Three fixed colours unless `VK_EXT_custom_border_color` (+ `customBorderColorWithoutFormat`); integer formats need `INT_CUSTOM`. | MNG emulates in the shader; with transparent black, grass away from the player lay flat and showed no cut (MNG issue #49). Ours: custom border when supported, else transparent black (check 11). | G80TEX; MNG `games/totk/third_party/d2r_gfx/gfx/nvn/nvn_mtl.m:5041-5045` | | 2.6 | **sRGB decode** is a TIC bit (`G80_TIC_2_SRGB_CONVERSION`) separate from the format; TSC has its own `SRGB_CONVERSION` (word 0 bit 13). NVN exposes sRGB as formats. | Format decides. | NVN-level translation by format is enough. | G80TEX:197, :377 | -| 2.7 | **Swizzles** per texture and per view (`TextureBuilderSetSwizzle`, `TextureViewSetSwizzle`); BotW layout captures rebuild a texture on the same storage with (1, 1, 1, R) or alpha 1. Default per-format mapping R8 → (R, 0, 0, 1). | `VkComponentMapping` on the view. | NXN: font atlas white boxes, HUD dark boxes without it. Ours: mapped (`vk_exec_draw.c` `get_view`). | NXN:68, NXN:140 | -| 2.8 | **Sample dimension comes from the instruction**: a non-array sample of an array texture reads layer 0; 1,512 BotW shaders sample a cube as a cube array. | View type must match the declared type. | NXN: 2D array bound as 2D gave one pale colour (washed-out scene); cubes created as 6-layer arrays with cube / cube-array views. Ours: views per resource type (`get_view`). | NXN:121, NXN:131 | +| 2.7 | **Swizzles** per texture and per view (`TextureBuilderSetSwizzle`, `TextureViewSetSwizzle`); BotW layout captures rebuild a texture on the same storage with (1, 1, 1, R) or alpha 1. Default per-format mapping R8 → (R, 0, 0, 1). | `VkComponentMapping` on the view. | NXN: font atlas white boxes, HUD dark boxes without it. Ours: mapped (`vk_exec_draw.c` `get_view`). | NXN | +| 2.8 | **Sample dimension comes from the instruction**: a non-array sample of an array texture reads layer 0; 1,512 BotW shaders sample a cube as a cube array. | View type must match the declared type. | NXN: 2D array bound as 2D gave one pale colour (washed-out scene); cubes created as 6-layer arrays with cube / cube-array views. Ours: views per resource type (`get_view`). | NXN | | 2.9 | **LOD**: TSC min/max LOD clamp, LOD bias, `TWO_D_NO_MIPMAP` texture type, a min filter without mips stays on the base level; TIC carries its own max anisotropy and aniso quality fields. | `minLod`/`maxLod`, `mipLodBias` limited by `maxSamplerLodBias`. | yuzu: anisotropy heuristics for mods forcing trilinear (YZ-2306, PR 10744). Ours: non-mip filter → `maxLod = minLod + 0.25`, bias clamped (`vk_texture.c` `make_sampler`). | G80TEX | | 2.10 | **Texture gather rounding**: Maxwell sub-texel precision differs from AMD/Intel; edge texels picked by TLD4 differ by one. | Implementation-defined `subTexelPrecisionBits`. | yuzu adds a sub-pixel offset to gathers on non-NVIDIA hosts: fixed BotW shadow artifacts at object edges ("shader_recompiler: Add subpixel offset for correct rounding at ImageGather", , title only). | — | | 2.11 | **Gather offsets**: `TLD4.PTP` takes four per-texel offsets, possibly from registers. | `ConstOffsets` must be constant. | Ours: `QueryHostSupportsNonConstantTextureOffset() => false` makes Ryujinx emulate register offsets (`tools/xlate/Program.cs`). | RYU-SH `Translation/Optimizations` (TexturePass) | | 2.12 | **Depth compare** (`TSC` depth compare + `TIC_4_DEPTH_TEXTURE`), min/max reduction filtering. | `compareEnable`; reduction mode needs `samplerFilterMinmax` and is not allowed with compare. | Ours: reduction dropped when compare is on (`vk_texture.c` `make_sampler`). | G80TEX | | 2.13 | **ASTC / BC**: native ASTC; zero ASTC block = error colour on hosts. | AMD and NVIDIA desktop GPUs lack ASTC: decode to RGBA8. yuzu offered ASTC recompression to BC1/BC3 for low VRAM (YZ-2305, PR 10398). | Ours: native upload where the device samples ASTC, else a compute-shader decode (`vk_astc.c`, `TOTK_ASTC`), CPU decode (`tex_astc.c`) as the fallback. | `runtime/vk_astc.c` | -| 2.14 | **Linear CPU-written textures** (`FLAGS_LINEAR`, small ramps, glyph caches): CPU writes visible to the GPU directly. | Must re-upload or use linear images over host memory. | NXN Mario: sky black without its 64×1 RGBA16F ramps. | NXN:75 | +| 2.14 | **Linear CPU-written textures** (`FLAGS_LINEAR`, small ramps, glyph caches): CPU writes visible to the GPU directly. | Must re-upload or use linear images over host memory. | NXN Mario: sky black without its 64×1 RGBA16F ramps. | NXN | ## 3. Shader math | # | Maxwell | Vulkan / AMD | Emulators / ports | Source | |---|---|---|---|---| -| 3.1 | **FMNMX and `.SAT` with NaN return the other operand / 0** (IEEE minNum). Games rely on this to stop NaN spreading (one NaN pixel blown up by bloom or temporal passes flickers or fills the screen). | `GLSL.std.450 FMin/FMax/FClamp`: result undefined when an operand is NaN (NMin/NMax are the NaN-dropping forms). AMD hardware min/max usually drops NaN; the compiler may still assume no NaN. | Ryujinx emits FMin/FMax/FClamp (`CodeGen/Spirv/Instructions.cs:336, 956, 972`; saturate = FClamp 0..1, `Instructions/InstEmitAluHelper.cs:419-423`). NXN translated shaders use `isnan` selects; MNG measured Metal min/max/saturate drop NaN (`probe.m:1-4`). | GLSL450; NXN:86 | +| 3.1 | **FMNMX and `.SAT` with NaN return the other operand / 0** (IEEE minNum). Games rely on this to stop NaN spreading (one NaN pixel blown up by bloom or temporal passes flickers or fills the screen). | `GLSL.std.450 FMin/FMax/FClamp`: result undefined when an operand is NaN (NMin/NMax are the NaN-dropping forms). AMD hardware min/max usually drops NaN; the compiler may still assume no NaN. | Ryujinx emits FMin/FMax/FClamp (`CodeGen/Spirv/Instructions.cs:336, 956, 972`; saturate = FClamp 0..1, `Instructions/InstEmitAluHelper.cs:419-423`). NXN translated shaders use `isnan` selects; MNG measured Metal min/max/saturate drop NaN (`probe.m:1-4`). | GLSL450; NXN | | 3.2 | **FMZ multiply mode** (`FMUL/FFMA/...` field `Fmz`, `.FMZ`): 0 × anything = 0, including Inf/NaN (DX9 rule). | IEEE: 0 × Inf = NaN. | Ryujinx decodes `Fmz` (`Decoders/InstDecoders.cs:306-309, 1901`) but no emitter reads it. Ours: same. Census needed (check 13). | RYU-SH | | 3.3 | **Denormals**: per-instruction `.FTZ`. | AMD flushes fp32 denormals by default; `VK_KHR_shader_float_controls` sets it per shader. | Ryujinx ignores `.FTZ`. Low risk. | RYU-SH (no `Ftz` use in `Instructions/`) | | 3.4 | **Warp size 32**: `SHFL`, `VOTE`, `S2R LANEID`, ballots are 32-bit. | AMD RDNA runs wave32 or wave64 per shader (the driver chooses; RADV fragment default wave64); `VK_EXT_subgroup_size_control` `requiredSubgroupSize = 32` fixes it. | Ryujinx adapts lane masks to `QueryHostSubgroupSize()` (default 32, `IGpuAccessor.cs:218`; `Instructions/InstEmitWarp.cs:72, 106`, `InstEmitMove.cs:175-185`). Ours: not overridden, no required size (check 6). | (`RADV_PERFTEST=pswave32`) | @@ -82,17 +84,17 @@ Source shorthands: | 3.6 | **Implicit-LOD sampling in divergent control flow** works on Maxwell (TEX unit uses quad neighbours). | Undefined in non-uniform control flow; AMD whole-quad mode usually works. | — | VKSPEC (derivatives) | | 3.7 | **Integer division** does not exist (compiled to `XMAD`/`IMAD` sequences); MUFU.RCP(0) = +Inf, LG2(0) = -Inf. | Same IEEE edge cases through `1/x`, `Log2`. | Low risk. | — | | 3.8 | **FP64** in some TotK cutscene shaders. | No FP64 on some hosts. | yuzu FP64 → FP32 (YZ-2306, PR 10693); ours: `softfloat64` job flag (`tools/xlate/Program.cs` `QueryHostSupportsShaderFloat64`). | — | -| 3.9 | **Integer vertex inputs read as raw bits** (bone indices `R8UI`). | Float-declared inputs convert integers. | NXN Mario: stretched characters; re-translated with `uint` inputs. Ours: attribute types passed to `QueryGraphicsState` (`Program.cs`). | NXN:76 | +| 3.9 | **Integer vertex inputs read as raw bits** (bone indices `R8UI`). | Float-declared inputs convert integers. | NXN Mario: stretched characters; re-translated with `uint` inputs. Ours: attribute types passed to `QueryGraphicsState` (`Program.cs`). | NXN | ## 4. Memory model | # | Maxwell / Tegra | Vulkan / AMD discrete | Emulators / ports | Source | |---|---|---|---|---| | 4.1 | **One memory**: the CPU reads GPU-written buffers and textures after a fence; the GPU sees CPU writes after `FlushMappedRange` or, in practice, immediately (TotK skips flushes). Block-linear layout is defined, so a buffer copy into texture storage is a texture upload. | Images live in VRAM with private tiling; buffer bytes copied into image memory are not texels. | yuzu PR 10942 (small CPU writes); MNG alias visibility barriers for copies through two buffers over one allocation. Ours: GPU-written ranges of CPU-visible pools marked at fence completion; GPU-only pools nothing (check 8). | MNG `docs/how-it-works.md:67-71` | -| 4.2 | **Counter reports** (`ReportCounter`, `SET_REPORT_SEMAPHORE_A..D` 0x1b00): `{counter, timestamp}`; TIMESTAMP puts 0 in the counter; SAMPLES_PASSED counts visible samples; ZCULL stats. | Occlusion queries are separate objects; results copied to a buffer. | NXN TotK: timestamp counter 0 matters for conditional clears. Ours: every report writes `{0, time}`; occlusion counts are always 0 (check 5). DK3D writes `SET_REPORT_SEMAPHORE_OFFSET` (`0x6C0` = 0x1b00) with payload `0` and `OPERATION=Counter`, `STRUCTURE_SIZE=FourWords` (`dk_variable.cpp:193-240`): TIMESTAMP = unit `Crop`, counter `Payload`, written when the ROP has retired every earlier draw; SAMPLES_PASSED = unit `Crop`, counter `0x15`; ZCULL stats = four one-word reports at +0, +4, +8, +12. TIMESTAMP_TOP is not a 3D report: a gpfifo `Semaphore` release of 16 bytes with `ReleaseWfiDisable`, written when the command processor reaches it, without waiting for earlier work (`:246-253`). So `TIMESTAMP - TIMESTAMP_TOP` around a span is its GPU duration. Layout: two 64-bit words, counter then timestamp (`Primer.md:578`). Each report is followed by a tiled-cache flush (`:256`). `ResetCounter` (`0x54C` = 0x1530) zeroes SAMPLES_PASSED; it is the reset for the timestamp types too (`:282-300`). Unit: `dkTimestampToNs(ts) = ts * 625 / 384`, i.e. **614.4 MHz** GPU ticks (1.63 ns), not the 19.2 MHz system tick (`include/deko3d.h:1367-1373`) (check 21). | OGD 0x1b00; NXN:173; DK3D `dk_variable.cpp:183-300`, `include/deko3d.h:1367` | +| 4.2 | **Counter reports** (`ReportCounter`, `SET_REPORT_SEMAPHORE_A..D` 0x1b00): `{counter, timestamp}`; TIMESTAMP puts 0 in the counter; SAMPLES_PASSED counts visible samples; ZCULL stats. | Occlusion queries are separate objects; results copied to a buffer. | NXN TotK: timestamp counter 0 matters for conditional clears. Ours: every report writes `{0, time}`; occlusion counts are always 0 (check 5). DK3D writes `SET_REPORT_SEMAPHORE_OFFSET` (`0x6C0` = 0x1b00) with payload `0` and `OPERATION=Counter`, `STRUCTURE_SIZE=FourWords` (`dk_variable.cpp:193-240`): TIMESTAMP = unit `Crop`, counter `Payload`, written when the ROP has retired every earlier draw; SAMPLES_PASSED = unit `Crop`, counter `0x15`; ZCULL stats = four one-word reports at +0, +4, +8, +12. TIMESTAMP_TOP is not a 3D report: a gpfifo `Semaphore` release of 16 bytes with `ReleaseWfiDisable`, written when the command processor reaches it, without waiting for earlier work (`:246-253`). So `TIMESTAMP - TIMESTAMP_TOP` around a span is its GPU duration. Layout: two 64-bit words, counter then timestamp (`Primer.md:578`). Each report is followed by a tiled-cache flush (`:256`). `ResetCounter` (`0x54C` = 0x1530) zeroes SAMPLES_PASSED; it is the reset for the timestamp types too (`:282-300`). Unit: `dkTimestampToNs(ts) = ts * 625 / 384`, i.e. **614.4 MHz** GPU ticks (1.63 ns), not the 19.2 MHz system tick (`include/deko3d.h:1367-1373`) (check 21). | OGD 0x1b00; NXN; DK3D `dk_variable.cpp:183-300`, `include/deko3d.h:1367` | | 4.3 | **Semaphores / events** written by the GPU in order; CPU polls them. | Writes on a completion thread after the fence. | Ours: `vk_completion_add`, submit order. | — | -| 4.4 | **Inline uniform updates** (`UpdateUniformBuffer`) happen in command order between draws; reading the buffer at record time gives the last value. | Must snapshot. | NXN: snapshotted at encode time; Mario's wave sim diverged when two writes reordered. | NXN:71, NXN:79, NXN:82 | -| 4.5 | **GPU-written index buffers** (8-bit indices written earlier in the same submission). | No `uint8` index type without `VK_EXT_index_type_uint8`; CPU widening reads stale bytes. | NXN widens on the GPU (`wide_run`). Ours: CPU widening at record time; device-local byte indices skipped (check 9). | NXN:175 | +| 4.4 | **Inline uniform updates** (`UpdateUniformBuffer`) happen in command order between draws; reading the buffer at record time gives the last value. | Must snapshot. | NXN: snapshotted at encode time; Mario's wave sim diverged when two writes reordered. | NXN | +| 4.5 | **GPU-written index buffers** (8-bit indices written earlier in the same submission). | No `uint8` index type without `VK_EXT_index_type_uint8`; CPU widening reads stale bytes. | NXN widens on the GPU (`wide_run`). Ours: CPU widening at record time; device-local byte indices skipped (check 9). | NXN | | 4.6 | **Compute shared memory**: 48 KiB per block on GM20B. | AMD 64 KiB. | Ours: `QueryComputeSharedMemorySize` from job (`Program.cs`). | OGD `clb1c0.h` | | 4.7 | **Virtual memory pools** map physical pool pages; the same bytes reachable at two GPU addresses. | Two `VkBuffer`s over one allocation need alias-aware barriers. | MNG `MTL4VisibilityOptionResourceAlias`. | MNG `docs/how-it-works.md:67-71` | | 4.8 | **Command list calls**: a `CallCommands` / `CallList` is not a GPU subroutine. DK3D `dkCmdBufCallList` stores a `Call` control entry (`dk_cmdbuf.cpp:327-338`); `dkQueueSubmitCommands` walks the entries on the CPU and recurses into the called list at submit (`dk_queue.cpp:287-296`), emitting gpfifo entries that point at the command words, which the GPU fetches later (prefetch can be switched off per entry, `:176`). So list structure is fixed at submit, command words are read when fetched. | n/a | Ours: `OP_CALL` is walked at replay, `CallCommands` inlines the recording at record time (`vk_exec.c` `walk`, `nvn_api_cmd.c` `inline_recording`). Equivalent for control flow; deferred bind handles are the data read late (2.4). | DK3D `dk_cmdbuf.cpp:327`, `dk_queue.cpp:280-298` | @@ -103,7 +105,7 @@ Source shorthands: |---|---|---|---|---| | 5.1 | **Provoking vertex: last** (GL convention, NVN default; `SET_PROVOKING_VERTEX` 0x1684, NVN 55 `SetProvokingVertexMode`). Flat-interpolated outputs (instance/particle ids, material indices, flat normals) come from the last vertex. | **First vertex** unless `VK_EXT_provoking_vertex` with `provokingVertexMode = LAST_VERTEX`. | Ours: last-vertex mode where `provokingVertexLast` is available (`vk_pipeline.c` `create_graphics`; check 1). DK3D: `ProvokingVertexLast` (`0x5A1`) is set to 1 at queue setup and per rasterizer state from `DkProvokingVertex` (`maxwell/gpu_3d_base.cpp:76`, `gpu_3d_state.cpp:67`); `DkRasterizerState` defaults to Last (`include/deko3d.h:823`). Confirms last as the hardware-side default. | OGD 0x1684; `runtime/nvn_ext.c`; DK3D `include/deko3d.h:794-823` | | 5.2 | **Primitive restart**: any index value, compared against the raw index for any index size; can apply to lists (`SET_DA_PRIMITIVE_RESTART_TOPOLOGY_CHANGE`) and to non-indexed draws (`..._VERTEX_ARRAY` 0x0de8). | Restart only at all-ones of the index type; lists need `primitiveTopologyListRestart`. | Ryujinx enables it for draw-arrays only on GL (RYU-SU comment). NXN: TotK terrain strips use 0xffff. Ours: non-all-ones restart not replayed, logged. DK3D: `PrimitiveRestartEnable` (`0x591` = 0x1644) + `PrimitiveRestartIndex` (`0x592` = 0x1648), index written only when enabled; any value; `PrimitiveRestartWithDrawArrays` (`0x37A` = 0x0de8) is forced 0 at setup (`maxwell/gpu_3d_ibo.cpp:21-30`, `gpu_3d_base.cpp:73`). Nothing on lists vs strips beyond that. | OGD 0x1644, 0x1648; DK3D `maxwell/gpu_3d_ibo.cpp:21-30` | -| 5.3 | **Point size**: `SET_POINT_SIZE` (0x1518) when the shader does not write it; GLSLC clamps a written size to a driver constant. | Point size must be written by the shader. | Ryujinx writes the `PointSize` from graphics state at VS start (`Translation/EmitterContext.cs:84-88`); ours reads the `SetPointSize` state from the support buffer (translator patch 0008). | NXN:41 | +| 5.3 | **Point size**: `SET_POINT_SIZE` (0x1518) when the shader does not write it; GLSLC clamps a written size to a driver constant. | Point size must be written by the shader. | Ryujinx writes the `PointSize` from graphics state at VS start (`Translation/EmitterContext.cs:84-88`); ours reads the `SetPointSize` state from the support buffer (translator patch 0008). | NXN | | 5.4 | **Line width**, smooth lines (`SET_LINE_WIDTH_FLOAT` 0x13b0, `SET_ANTI_ALIASED_LINE`). | `wideLines`, `VK_EXT_line_rasterization`. | Ours: 1 px, logged. | OGD | | 5.5 | **Polygon offset units** are twice the API value in the register; NVN API takes GL units. | `depthBiasConstantFactor` in format-dependent r. | Ryujinx `units / 2f` from the register (RYU-SU). Ours takes NVN API units (right) but D32F instead of D24 (1.7). DK3D `constantFactor * 2.0f` (1.7). | OGD 0x15bc, 0x187c; DK3D `maxwell/gpu_3d_state.cpp:154` | | 5.6 | **Dual-source blending**: SRC1 factors read the shader's second output. | Needs fragment output `Location 0, Index 1`. | Ryujinx declares `Index` only when `DualSourceBlendEnable` (`Translation/Translator.cs:196`, `CodeGen/Spirv/Declarations.cs:608-617`). Ours: SRC1 factors mapped (`vk_pipeline.c` `blend_factor`) but the translator is always given `false` (`Program.cs` `QueryGraphicsState`) (check 12). | — | @@ -118,11 +120,11 @@ Source shorthands: | Game | Symptom | Cause | Fix / link | |---|---|---|---| -| TotK | 3D scene black | conditional clears ignored | NXN:173 | -| TotK | cave magenta / black | CPU-filled ASTC/BC with no flush never uploaded | NXN:174 | -| TotK | stone blocks unlit by torches | roughness atlas built from `ReadTexels` of never-uploaded BC4 | NXN:175 | -| TotK | BC4 3D texture draws lost | compressed render target | NXN:176 | -| TotK | missing ambient light, bloom halo | draw with no render target skipped | NXN:177 | +| TotK | 3D scene black | conditional clears ignored | NXN | +| TotK | cave magenta / black | CPU-filled ASTC/BC with no flush never uploaded | NXN | +| TotK | stone blocks unlit by torches | roughness atlas built from `ReadTexels` of never-uploaded BC4 | NXN | +| TotK | BC4 3D texture draws lost | compressed render target | NXN | +| TotK | missing ambient light, bloom halo | draw with no render target skipped | NXN | | TotK | warp pad half black | block height rounding | MNG `docs/how-it-works.md:49-53` | | TotK | coloured squares with Ultrahand / Recall | D16 clear vs fragment rounding with depth EQUAL | MNG `docs/how-it-works.md:57-61` | | TotK/BotW | grass flat away from Link, no cut | custom border colour (0.5) | MNG `nvn_mtl.m:5041-5045` | @@ -140,9 +142,9 @@ Source shorthands: | TotK | "detective mode" Link on AMD | AMD EDS3 colour-blend driver regression | YZ-2306 PR 10946 | | BotW | shadow artifacts at object edges (AMD) | gather rounding | yuzu commit 780240e (2.10) | | BotW | black textures on GCN | HTILE (depth compression) | `AMD_DEBUG=nohyperz` wiki (1.9) | -| BotW | 3D scene black | deferred texture handles | NXN:129 | -| BotW | albedo scattered squares | duplicate colour attachments | NXN:130 | -| BotW | HUD dark boxes, black stamina wheel | capture texture swizzle rebuild | NXN:140 | +| BotW | 3D scene black | deferred texture handles | NXN | +| BotW | albedo scattered squares | duplicate colour attachments | NXN | +| BotW | HUD dark boxes, black stamina wheel | capture texture swizzle rebuild | NXN | ## 7. Checks for our runtime @@ -155,7 +157,7 @@ Grep-level look on 2026-10-22, statuses updated 2026-10-26; "saw" is what the gr FS inputs the VS lacks. Our translator never links stages, so Ryujinx's `InitializeVertexOutputs` would initialise no user output; translator patch 0006 initialises the unlinked outputs. **Fixed.** 3. **Masked clears.** `vk_exec.c` skips colour clears with a partial channel mask (`W_CLEAR_MASK`); `clear_ds` skips stencil - clears with a partial mask (`W_STENCIL_MASK`). TotK issues such clears (NXN:174). Check the log for + clears with a partial mask (`W_STENCIL_MASK`). TotK issues such clears (NXN). Check the log for `colour clear with channel mask` and `stencil clear with mask`. DK3D (1.3) confirms what the replay must do: colour clear = scissor 0 + channel mask, stencil clear = `value & mask` merged under the front write mask; so a draw with `colorWriteMask` / `stencilWriteMask` set to the clear mask is the exact equivalent. **Missing.** 4. **D24 → D32F.** `vk_formats.c` maps D24S8 to `D32_SFLOAT_S8_UINT`; `vk_exec_draw.c` `record_fixed` passes NVN units unscaled. Depth EQUAL passes and decal offsets can z-fight. Look at: per-pass depth-test op histogram, EQUAL passes diff --git a/totk.ini.example b/totk.ini.example index d182bea7..58cdfa0e 100644 --- a/totk.ini.example +++ b/totk.ini.example @@ -51,6 +51,9 @@ # lang = en-US # System mode reported to the game: docked or handheld. # operation_mode = docked +# Language of the settings menu and the overlay: en or ru. Default: the Windows display language, English if it is +# neither. +# menu_lang = en [audio] # none mixes without opening an audio device. @@ -71,6 +74,8 @@ # rumble_triggers = 0 # Mouse camera sensitivity (0 to 10; 0 = no mouse camera and no cursor capture). # mouse_sens = 1 +# Write the input of this run to a file that replays as a script (docs/controls.md, "Scripted input"). Default: off. +# input_record = input.txt # Remap buttons, one line per Switch button: bind_ = # comma separated pad: and key: entries, or none. A line replaces that button's defaults (pad and keyboard); # buttons without a line keep them. Invalid entries are logged and skipped. @@ -86,3 +91,7 @@ [files] # Folder with RomFS mod files that replace or add game files. Default: none. # romfs_mods = + +# The Advanced tab of the settings menu (F1) has more keys: scheduling, shaders and pipelines, textures and memory, +# render fixes, Vulkan and diagnostics. They are for troubleshooting; the menu shows each one with its default and +# writes it here when you change it.