has none: the survey that makes a provisional profile reads NSPs`, or the same line for a dump folder (issue #1265). A folder holding `exefs/` and `romfs/` directly, or only `updates/<version>/`, was not taken for a dump at all: the script asks for `prod.keys`, then stops with `no NSP with a readable title ID`. → [A NUP or a dump of a game with no profile stops before the survey](../reference/packing.md#a-nup-or-a-dump-of-a-game-with-no-profile-stops-before-the-survey) - the survey of a Switch 2 game says `SDK: ?` and `no SDK version string found`, and its provisional profile has `app_pool 0xCD500000`. → [A provisional profile of a Switch 2 game shows no SDK and a Switch 1 memory pool](../reference/packing.md#a-provisional-profile-of-a-switch-2-game-shows-no-sdk-and-a-switch-1-memory-pool) - the Mac host step fails in `host_msl.py` with `TypeError: __init__() got an unexpected keyword argument 'capture_output'`, although the launcher reports a recent bundled Python. → [The Mac host build starts an older Python than the pipeline](../reference/packing.md#the-mac-host-build-starts-an-older-python-than-the-pipeline) - the first extraction stops with `nx_extract exit code 131` and `.NET location: Not found`, even though `dotnet` is on `PATH`. The shader translator can fail the same way. → [Homebrew .NET is on PATH but apphosts cannot find the runtime](../reference/packing.md#homebrew-net-is-on-path-but-apphosts-cannot-find-the-runtime) - the extraction and captures succeed, then the shader step stops with `translation chain tools do not match the lock file: xlate_source: lock … / actual` and nothing after `actual`, which reads like a stale translator. → [The shader step stops with an empty `xlate_source`](../reference/packing.md#the-shader-step-stops-with-an-empty-xlate_source) - on an Intel Mac, the NSP script stops at its translator check with `[RED] the shader translator does not run (Unhandled exception. System.IO.FileLoadException: Could not load file or assembly '…/dmsh_xlate.dll'. The assembly architecture is not compatible with the current process architecture.)`, although the .NET 10 runtime for x86_64 is installed. → [An Intel Mac cannot load the bundled translator's dll](../reference/packing.md#an-intel-mac-cannot-load-the-bundled-translators-dll) - `vk_shaders.py` stops with `OSError: [Errno 7] Argument list too long: 'xcrun'` after the Metal compiles, in the `metallib` link. → [The Vulkan shader step fails with `Argument list too long: 'xcrun'`](../reference/packing.md#the-vulkan-shader-step-fails-with-argument-list-too-long-xcrun) - the shader split stops with `the split shader tables differ from game profile <id>'s`, on the game version the profile registers. → [The split shader tables differ from a game profile's](../reference/packing.md#the-split-shader-tables-differ-from-a-game-profiles) - packing succeeds, but `unzip -t` or Python's `ZipFile.testzip()` reports a bad CRC for a large deflated file. → [A streamed file changes size and the IPA fails its CRC check](../reference/packing.md#a-streamed-file-changes-size-and-the-ipa-fails-its-crc-check) - `devicectl` copying a large RomFS folder fails with POSIX error 24 (`EMFILE`) or spends most of its time on small files; deleting an old folder during iOS startup hits the launch watchdog. A push after changing extracted files can also keep sending old assets if an image is reused solely because it exists. → [RomFS folder transfers fail or leave stale game files](../reference/packing.md#romfs-folder-transfers-fail-or-leave-stale-game-files) - the first build after restarting the Mac spends minutes in `unpack` (`[1/5] unpack v131072: 5%, 1.2/~24.4 GB`) although the game, the packer and the image are as they were: 8 minutes for a 24.4 GB image from a NUP on a network share. → [A reboot packs a RomFS image again](../reference/packing.md#a-reboot-packs-a-romfs-image-again) - a direct `dmhost` run logs `fs mount rom: → <path> (read-only)` for a path that does not exist, then crashes in the game's code a fraction of a second after `nnMain` (Echoes of Wisdom: `CRASH sig=11 addr=0x88` 0.3 s in). The host now stops at the mount instead with `FATAL the game files <path> (rom:) are missing: neither a folder nor a RomFS image`. → [A stale `DM_ROMFS` path crashes the game soon after `nnMain`](../reference/packing.md#a-stale-dm_romfs-path-crashes-the-game-soon-after-nnmain) - a successful `--romfs separate --no-keep-extracted` build prints a push command pointing at deleted game files. On iOS, a complete image for another build can also prevent startup despite a valid `Documents/romfs` folder. → [Separate RomFS deployment loses its image or folder fallback](../reference/packing.md#separate-romfs-deployment-loses-its-image-or-folder-fallback) - a `--romfs separate` app whose image was copied into its Documents folder by hand (Finder, the Files app, a LiveContainer guest) logs `boot: game files not found (Documents/romfs.img, Documents/romfs or <App>/romfs)`, and a build with `romfs.id` shows "There is no game file image on this device.", though the complete image is there. Renaming it to `romfs.img` makes the game start. → [A hand-copied RomFS.img is not found on iOS](../reference/packing.md#a-hand-copied-romfsimg-is-not-found-on-ios) - reducing the iPhone transfer to one image still creates thousands of resource files on the Mac, and build scanners require the expanded folder. → [Building creates a full RomFS tree before packing its image](../reference/packing.md#building-creates-a-full-romfs-tree-before-packing-its-image) - a game's `<id>_build` folder is slow to count, copy or delete: Metroid Dread's held 160,331 files in 48,782 folders, 84,541 of them in the compile cache. → [A build folder holds hundreds of thousands of small files](../reference/packing.md#a-build-folder-holds-hundreds-of-thousands-of-small-files) - a build that runs the shader step writes the compile cache's files back and removes them again, on Skyward Sword HD 24,131 files and 10,150 folders each time, Tears of the Kingdom over 900,000 entries. Removing old entries took up to half an hour on an external drive. → [The compile cache was unpacked for each build](../reference/packing.md#the-compile-cache-was-unpacked-for-each-build) - a game's shader libraries are slow to copy or delete: Skyward Sword HD's `b-<chain>/` held 12,064 files for 2,470 shaders, a third of its build folder's files, and each `regress.py` chain build held another set. A tar would not do: the host reads these files at every run. → [Shader libraries take a file per shader variant](../reference/packing.md#shader-libraries-take-a-file-per-shader-variant) - a game's `<id>-work` folder is too slow to count: Tears of the Kingdom's held 8,893,028 files and 509 GB, and its count ran past ten minutes. → [A work folder holds millions of small files](../reference/packing.md#a-work-folder-holds-millions-of-small-files) - the NSP script stops at the shader split of a registered profile with `[RED] 13744 file(s) could not be read, their shaders are left out (first: AI/FileEntry/FileEntry.Product.100.byml.zs: CalledProcessError: Command ['zstd', '-d', '-c', '-q', '…/extract/v0/RomFS.img/AI/…'] returned non-zero exit status 1.)`. → [The zstd command given a path inside the image](../reference/packing.md#the-zstd-command-given-a-path-inside-the-image) - a game's DLC works only when packed inside its IPA, although its base RomFS can be deployed separately. After pushing a smaller DLC set, removed indices can remain reported as owned and mounted. → [DLC in Documents is ignored or removed DLC remains installed](../reference/packing.md#dlc-in-documents-is-ignored-or-removed-dlc-remains-installed) - the settings of a Mac app or IPA packed from a NUP or a dump folder have no Game language row, while `DM_LANG` in the environment changes the language. Reported on Donkey Kong Bananza (NX2Apple#619, #659; the reporters' packed files were not available). → [No Game language row in an app packed from a NUP or a dump](../reference/packing.md#no-game-language-row-in-an-app-packed-from-a-nup-or-a-dump) - starting a Mac app through a front end with unchanged settings enables the encode thread, and can disable Metal 4 pipelines and the pipeline archive; starting the same app from Finder keeps the host's defaults. → [A Mac front end's default settings change Metal execution paths](../reference/packing.md#a-mac-front-ends-default-settings-change-metal-execution-paths) - in a Mac app, the settings window stays on screen after **Play**, not responding (a spinning cursor over it), until the game ends. → [The Mac settings window stays on screen after Play](../reference/packing.md#the-mac-settings-window-stays-on-screen-after-play) - with the NSP folder on an exFAT or FAT drive, the build leaves out an update whose name has no `[v…]` tag (the folder seems to hold two), or a stage stops with `FileNotFoundError` on a `._<name>` path inside `<id>_build/` and the next run fails on the half-deleted folder. → [A game folder on an exFAT drive reads one update as two, or fails to remove a folder](../reference/packing.md#a-game-folder-on-an-exfat-drive-reads-one-update-as-two-or-fails-to-remove-a-folder) - with the build folder on an exFAT or FAT drive, the shader step compiles every library and then stops in `c1_guard.py` with `UnicodeDecodeError: 'utf-8' codec can't decode byte …` (dmsh_build.py: `[RED] c1_guard.py failed`), reading a `._<key>_b.metal`. → [The c1 guard stops on an AppleDouble file after the shader build](../reference/packing.md#the-c1-guard-stops-on-an-appledouble-file-after-the-shader-build) - with the build folder or the app on an exFAT or FAT drive, the Mac app step stops in `pack_app.py`. The first form it takes is `no input file at <build>/shader/cache/<chain>/._<key>_b.metallib`, or `no rewriter fixups for <build>/<version>/._main.patched.bin` when the modules come first. When the inputs get past it, the copies stop with `chflags` or `Permission denied`, and the signing step stops with `codesign failed (1): code object is not signed at all` and `In subcomponent: …/Contents/MacOS/._nxnative`, which reads like a broken launcher build. → [The Mac app step stops on AppleDouble files in its inputs, its copies and its signature](../reference/packing.md#the-mac-app-step-stops-on-appledouble-files-in-its-inputs-its-copies-and-its-signature) - with the app on a Mac OS Extended, exFAT or FAT drive, the first build into a folder works and the next one that changes anything stops in `pack_app.py` `replace_app` with `OSError: [Errno 45] Operation not supported: '<app>'`. The old app stays in place. → [A second Mac app build stops with `[Errno 45]` when it replaces the old app](../reference/packing.md#a-second-mac-app-build-stops-with-errno-45-when-it-replaces-the-old-app) - on an exFAT or FAT drive, shader splitting stops with `ValueError: not a version 2 shader code archive` or `[RED] /glslc_capture/._…: no GLSLC output`. → [External shader directories contain AppleDouble metadata](../reference/packing.md#external-shader-directories-contain-appledouble-metadata) - `decompress NSZ` stops immediately with `nsz: error: unrecognized arguments: --keys …`. → [NSZ decompression rejects `--keys`](../reference/packing.md#nsz-decompression-rejects---keys) - the NSP script or any module tool stops on `main`: `compressed with zstd (NSO flag bit 7), which this loader does not decode yet`; with the decoder but without its package, `ZBIC (zstd) segments need the zbic package (python3 -m pip install zbic)`. → [ZBIC-compressed NSO segments](../reference/packing.md#zbic-compressed-nso-segments) - `FATAL open <folder>/subsdk1.fixups.tsv` right after the host starts, or `build_ipa.sh` stops with `no rewritten module …/subsdk1`, for a version that has no such module. → [A version without one of the profile's modules stops the host at boot](../reference/packing.md#a-version-without-one-of-the-profiles-modules-stops-the-host-at-boot) - `[RED] no NSP with a readable title ID in <folder>`, although the keys open the package (the launcher's key check passes). Renaming the file to `Game [0100XXXXXXXXXXXX].nsp` makes the build go on. → [An NSP without a ticket or a title ID in its name stops with "no NSP with a readable title ID"](../reference/packing.md#an-nsp-without-a-ticket-or-a-title-id-in-its-name-stops-with-no-nsp-with-a-readable-title-id) - `[RED] no NSP with a readable title ID in <folder>` for a folder holding `Game [0100XXXXXXXXXXXX].NSP`, on any Mac volume; renaming it to `.nsp` makes the build go on. A dump folder beside `Game.NSP` is packed instead of the package, and `Game.NUP` is not found. A `Game.NSZ` stops with `nsz made no Game.nsp`. → [A game file whose extension is in capitals is not found](../reference/packing.md#a-game-file-whose-extension-is-in-capitals-is-not-found) - a game folder holding one merged package (`[Base + Update + DLC].nsp`, or a 1G+1U cartridge dump with no update NSP beside it) stops with `no base game NSP found`, or packs the base game alone (v0) without its update and DLC; when the base game's own build cannot be packed (Mario Kart 8 Deluxe 1.0.0's `main` is 32-bit), the build stops there. → [A merged NSP (base game, update and DLC in one file) packs as one title](../reference/packing.md#a-merged-nsp-base-game-update-and-dlc-in-one-file-packs-as-one-title) - a version a profile was not brought up on crashes at its first movie: `UNIMPL _ZN5movie9ExtractorC1ENS_13ContainerTypeE`, then `CRASH sig=11` (issue #1211). The derived profile's `modules` has only `main sdk`. → [A derived profile leaves out a module that moved to another slot](../reference/packing.md#a-derived-profile-leaves-out-a-module-that-moved-to-another-slot) - the NSP script stops at its rewrite stage with `FileNotFoundError: … extract/v0/ExeFS/subsdk1` while packing a version the profile was not brought up on; the extraction has every other module. → [A derived profile loads only the modules its version ships](../reference/packing.md#a-derived-profile-loads-only-the-modules-its-version-ships) - `nx_extract` stops with exit code 134 and `Unhandled exception. LibHac.Common.Keys.MissingKeyException: Unable to decrypt NCA section.` with `Key Name: key_area_key_application_<NN>` (or `titlekek_<NN>`), after any NSZ conversion, the build ID lookup or the survey. An NSZ converted with such keys is written anyway: `nsz -D` warns `master_key_<NN> missing … This will lead to corrupted output.` and exits 0. → [Keys older than the game stop the extraction with an unhandled MissingKeyException](../reference/packing.md#keys-older-than-the-game-stop-the-extraction-with-an-unhandled-missingkeyexception) - the extraction of a game whose base is an XCI that also carries its update (a "1G+1U" dump) stops with `[RED] nx_extract exit code -6`. `extract_v<version>.log` lists the update's build IDs even for the base game alone, then ends in an unhandled exception from the RomFS (`ResultFsNonRealDataVerificationFailed (2002-4604): Hash error!` from `RomFsFileSystem..ctor`, or `ArgumentException` / `InvalidOperationException` from the patch layers). → [A cartridge dump with its update on it extracts the update as the base game](../reference/packing.md#a-cartridge-dump-with-its-update-on-it-extracts-the-update-as-the-base-game) - an XCI with two applications (Super Mario Galaxy + Super Mario Galaxy 2 on one cartridge dump) always packs the first game; `build_ipa_from_nsp.py` never reaches the second. → [A cartridge dump that holds two games packs only the first](../reference/packing.md#a-cartridge-dump-that-holds-two-games-packs-only-the-first) - `nx_extract` stops with exit code 134 and `Unhandled exception. System.InvalidOperationException: The LinkedList is empty.` from `LibHac.Tools.FsSystem.CachedStorage.GetBlock`, with no `[RED] hash check failed` list, with or without `--allow-damaged`. → [Extraction of a damaged NSP ends in "The LinkedList is empty"](../reference/packing.md#extraction-of-a-damaged-nsp-ends-in-the-linkedlist-is-empty) - `[RED] the NSP is damaged: a filesystem's own tables fail the NCA's hash check`, exit code 3, right after the build IDs; before 2026-11-04, `[RED] nx_extract exit code -6` with an unhandled `ResultFsNonRealDataVerificationFailed (2002-4604)` under `RomfsHeader`. The ExeFS reads, and the build IDs and name are printed, since only the RomFS is hit. → [A damaged RomFS's own tables](../reference/packing.md#a-damaged-romfss-own-tables) - a build packed with `--allow-damaged` crashes or draws wrongly in game code, the same way on each run, at a place unrelated to the host's last work. The log gave no sign of damage; the build log's list (`logs/extract_<version>.log`) is the only record, and it is not part of a bug report's run log. → [A crash from a damaged NSP's file looks like a host bug](../reference/packing.md#a-crash-from-a-damaged-nsps-file-looks-like-a-host-bug) - the NSP script stops at the offline HTML pages (`logs/extract_html_<version>.log`) with `[RED] the NSP is damaged: <n> files fail the NCA's hash check` and a list under `/html-document/`, although the program extracted cleanly and the NSZ tool verified every NCA of the update. → [An update's offline HTML pages reported as a damaged NSP](../reference/packing.md#an-updates-offline-html-pages-reported-as-a-damaged-nsp) - for a game with no profile, the NSP script stops at `build ID lookup · main of the base game` with `[RED] nx_extract exit code -6`; `<title ID>_survey/logs/exefs.log` ends in `ResultFsNonRealDataVerificationFailed (2002-4604): Hash error!` from `PartitionFileSystemMetaCore.QueryMetaDataSize` under `Nca.OpenFileSystem`, although every NCA in both NSPs matches its content ID (the SHA-256 that names it) and the base game with its update extracts cleanly. → [The survey's build ID lookup stops on the base game alone with a hash error](../reference/packing.md#the-surveys-build-id-lookup-stops-on-the-base-game-alone-with-a-hash-error) ## Rewriter - `NameError: name 'CS_ARCH_ARM64' is not defined` at the start of `patch_nso.py`; now `[RED] Capstone 6.… is unsupported` from the NSP script or `patch_nso.py`. → [Capstone API version](../reference/rewriter.md#capstone-api-version) - an updated game loses a needed cut because its NSO build ID changed, although the relevant code still matches a verified version; the rewriter reports `[RED] function patch ... skipped` when that match cannot be established, and the NSP script ends with `[RED] main: no function patch carries the registered builds' fixes to this build` or `[RED] main: function patches not applied` (Super Smash Bros. Ultimate 13.0.1: a static-initialiser abort in `nninitStartup`, GitHub issue #375). → [Function-matched cuts for unregistered builds](../reference/rewriter.md#function-matched-cuts-for-unregistered-builds) - after a game update, the Cheats menu lists only `Cheats for build … (another version of the game)`, and nothing runs. Or a cheat file converted to the new build by hand writes into the wrong place: a table instead of a variable, or code that moved. → [Cheats carried across game updates](../reference/rewriter.md#cheats-carried-across-game-updates) - `jump table <addr>` assertion in `patch_nso.py`, in a Unity / IL2CPP `main`. → [Offset jump tables through x18 read at rewrite time](../reference/rewriter.md#offset-jump-tables-through-x18-read-at-rewrite-time) - `jump table <addr>` assertion in `patch_nso.py`, in a `subsdk`. → [Offset jump tables with the bounds check on another register](../reference/rewriter.md#offset-jump-tables-with-the-bounds-check-on-another-register) - `jump table <addr>` assertion where the index is a copy made before the check (`mov w0,w18`, then 41 instructions holding two other jump tables on `x0`, then `cmp w18,#4; b.hi; ldrsw x18,[x11,x0,lsl #2]; add x18,x18,x11; br x18`). → [Index copied before the bounds check](../reference/rewriter.md#index-copied-before-the-bounds-check) - `jump table <addr>` assertion in `patch_nso.py` on an offset table whose index is checked with a 64-bit compare (`cmp x22, #0x10; …; b.hi; adrp x18 + add x18; mov x0, x18; ldrsw x18, [x0, x22, lsl #2]; add x18, x18, x0; br x18`). → [64-bit bounds check of the index](../reference/rewriter.md#64-bit-bounds-check-of-the-index) - `jump table <addr>` assertion in `patch_nso.py` where the index is made with a 64-bit `and` by `0xffffffff` after the check (`cmp w8, #4; b.hi; and x18, x8, #0xffffffff; ldrsw x18, [x16, x18, lsl #2]; add x18, x18, x16; br x18`). → [Index zero-extended after a 32-bit bounds check](../reference/rewriter.md#index-zero-extended-after-a-32-bit-bounds-check) - `jump table <addr>` assertion in a Unity / IL2CPP `main` whose dispatch checks a fresh mask of another register than the one it indexes with. → [Index masked in the block that branches to the dispatch](../reference/rewriter.md#index-masked-in-the-block-that-branches-to-the-dispatch) - `jump table 6eea88` or `jump table 6eeac0` assertion in `patch_nso.py` on Return of the Obra Dinn 1.0.1. → [Zero-guarded complemented jump-table index](../reference/rewriter.md#zero-guarded-complemented-jump-table-index) - `jump table <addr>` assertion on an offset table whose base was set far back (`cmp w18,#5; b.hi; ldrsw x18,[x24,x18,lsl #2]; add x18,x18,x24; br x18`). → [Offset table base set far back in the function](../reference/rewriter.md#offset-table-base-set-far-back-in-the-function) - `jump table <addr>` assertion on an offset table whose base was set far back and moved through other registers (`ldrb w18,[x14]; sub w18,w18,#1; cmp w18,#6; b.hi; ldrsw x18,[x7,x18,lsl #2]; add x18,x18,x7; br x18`). → [Far table base passed through other registers](../reference/rewriter.md#far-table-base-passed-through-other-registers) - `jump table ae95f8` assertion in `patch_nso.py` while rewriting Blasphemous 1.0.8. → [Offset table base initialized after the dispatch](../reference/rewriter.md#offset-table-base-initialized-after-the-dispatch) - `jump table <addr>` assertion, entries relative to an `adr`. → [Offset tables relative to an adr](../reference/rewriter.md#offset-tables-relative-to-an-adr) - `AssertionError: jump table 30ee50c` while rewriting an ADR-relative dispatch with `cmp x9,#4`. → [ADR-relative jump tables with 64-bit bounds](../reference/rewriter.md#adr-relative-jump-tables-with-64-bit-bounds) - `AssertionError: jump table 3ce6c` while rewriting `main`, on an ADR-relative dispatch that the existing form describes: `ldrb w0, [x18, #5]; cmp w0, #5; b.hi; ldr s0, [sp, #8]; ldr s1, [x18, #0xc]; adr x18, #L; ldrsw x1, [x17, x0, lsl #2]; add x18, x18, x1; br x18`. → [Vector registers read as writes of the jump-table index](../reference/rewriter.md#vector-registers-read-as-writes-of-the-jump-table-index) - no failure seen on a game. The rewriter could read a jump table with the wrong size or base, so a case's target or landing pad would be missing or wrong. In the other direction, a halfword table whose base is in x30 got all 65,536 landing pads (`J` rows with 65536 in `main.sites.tsv`), which only makes the patch area larger. → [Overwritten jump-table indices and bases taken as unchanged](../reference/rewriter.md#overwritten-jump-table-indices-and-bases-taken-as-unchanged) - `jump table <addr>` assertion on a byte table indexed by x30 (`adr x18, #L; ldrb w30, [x14, x12]; add x18, x18, x30, lsl #2; br x18`). → [Byte tables indexed by x30 (capstone register names)](../reference/rewriter.md#byte-tables-indexed-by-x30-capstone-register-names) - `jump table <addr>` assertion on a byte table whose `add` is far from the `br` (`adr x18,#L; ldrb w0,[x17,x15]; add x18,x18,x0,lsl #2`, then 17 register moves before `br x18`). → [Byte tables whose add is far from the br](../reference/rewriter.md#byte-tables-whose-add-is-far-from-the-br) - `jump table <addr>` assertion in `patch_nso.py`, in a Unity / IL2CPP `main`, at a `blr x18`. → [Indirect calls through x18](../reference/rewriter.md#indirect-calls-through-x18) - `jump table <addr>` assertion on a `br x18` with no table in front of it. → [Indirect tail calls through x18 in IL2CPP thunks](../reference/rewriter.md#indirect-tail-calls-through-x18-in-il2cpp-thunks) - `AssertionError: jump table d29e68` while rewriting Moving Out 2 1.3.315. → [Unframed pointer tail calls followed by zero trap padding](../reference/rewriter.md#unframed-pointer-tail-calls-followed-by-zero-trap-padding) - `jump table 53e9c` while rewriting Warm Snow 2.1.4's Unity IL2CPP `main`, or `jump table 108bb70` on Ori and the Blind Forest: Definitive Edition. → [Loaded method-pointer tail call before an error block](../reference/rewriter.md#loaded-method-pointer-tail-call-before-an-error-block) - job system hangs; a queue claims thousands of tasks but every slot is empty. → [Exit stub order in exclusive windows](../reference/rewriter.md#exit-stub-order-in-exclusive-windows) - `branch into window <addr>` assertion. → [Out-of-line retry blocks of atomic updates](../reference/rewriter.md#out-of-line-retry-blocks-of-atomic-updates) - branches to an `ldxr … stxr` loop's head landed mid-window. → [A window never spans a second exclusive load](../reference/rewriter.md#a-window-never-spans-a-second-exclusive-load) - `AssertionError: 0x…` in `site_window` on an `adrp` inside an exclusive window (`ldaxr x9,[x9]; cmp x9,x25; b.ne out; adrp x10 + add x10` (the same address again, for the store); `mov x18,x26; stlxr w9,x8,[x10]`, then loads and `cbnz w9` back). → [adrp inside an exclusive window](../reference/rewriter.md#adrp-inside-an-exclusive-window) - `B()` assertion at a spin wait: a branch into the patch area beyond the ±128 MB a `b` reaches. → [Halfword jump table landing pads sized to the largest entry](../reference/rewriter.md#halfword-jump-table-landing-pads-sized-to-the-largest-entry) - `B()` range assertion in `patch_nso.py` (`site_plain`), only for one module. → [Patch area before the module base for a large bss](../reference/rewriter.md#patch-area-before-the-module-base-for-a-large-bss) - `frame step state page` assertion when a `FRAME_STEP` profile is added to a module with a large BSS. → [Frame-step state with a front patch area](../reference/rewriter.md#frame-step-state-with-a-front-patch-area) - `B()` range assertion, then `patch area of … bytes does not fit in the … before the base`. → [Patch area right before the base for a long text](../reference/rewriter.md#patch-area-right-before-the-base-for-a-long-text) - `main: patch area of 0x6b9d38 bytes does not fit in -0x39c0000 before the base; rewriting again with 0x6c0000`, then a `B()` range assertion in `site_window`: the gap before the base came out negative. → [Two patch areas for a text longer than a branch reaches](../reference/rewriter.md#two-patch-areas-for-a-text-longer-than-a-branch-reaches) - a `B()` range assertion in `site_plain` on the branch back to the site, in a module that takes two patch areas. → [Split point within the back area's reach](../reference/rewriter.md#split-point-within-the-back-areas-reach) - `observation gate neither at a function entry nor after a bl`; `observation gate neither at a function entry, after a bl nor before a call` on an epilogue. → [Observation gates on any relocatable instruction](../reference/rewriter.md#observation-gates-on-any-relocatable-instruction) - `jump table <addr>` assertion on an ordinary byte table near the start of the text (`adr x18; ldrb w0,[x17,x16]; add x18,x18,x0,lsl #2; br x18`). → [Code before the first unwind entry is one function](../reference/rewriter.md#code-before-the-first-unwind-entry-is-one-function) - the rewrite never finishes, the Mac swaps, the rewriter's footprint reaches 100 GB. → [Long functions analysed in pieces](../reference/rewriter.md#long-functions-analysed-in-pieces) - `KeyError` at `site_br` for a `br x18` that is an ordinary byte jump table. → [Disassembly goes on after undecodable words](../reference/rewriter.md#disassembly-goes-on-after-undecodable-words) - `RuntimeError: 788 ldr x18, #0xd1eb0` in `patch_nso.py`, or any rewrite site in data. → [Data blocks at the start of the text](../reference/rewriter.md#data-blocks-at-the-start-of-the-text) - `RuntimeError: 44 ldr x18, #0xfffffffffff40370` while rewriting an NRO. → [NRO metadata inside the text segment](../reference/rewriter.md#nro-metadata-inside-the-text-segment) - `jump table <addr>` assertion in `patch_nso.py`, in a Unity / IL2CPP `main`, at an `alloca` (`mov sp, x18`). → [Stack pointer writes through x18](../reference/rewriter.md#stack-pointer-writes-through-x18) - `CRASH sig=10 addr=0` on an `stp` relative to `sp`, with `sp` not a multiple of 16 (`main+0x2bbba4`, `sub sp, sp, #0xc0` then `stp d15, d14, [sp, #0x60]` with sp ending in `…9dc`). → [Stack arguments reserved with sub sp, sp, xN](../reference/rewriter.md#stack-arguments-reserved-with-sub-sp-sp-xn) - SIGILL / trap on a system register read. → [System register reads that macOS traps](../reference/rewriter.md#system-register-reads-that-macos-traps) - every pointer in `.data` / the GOT is a module offset, crashes everywhere. → [Packed relative relocations (DT_RELR)](../reference/rewriter.md#packed-relative-relocations-dt_relr) - `regress.py check` stops before gameplay with `CUTS of build ... in both ...`, naming a revision profile and its copied harness profile. → [Regression rewrites register copied profiles twice](../reference/rewriter.md#regression-rewrites-register-copied-profiles-twice) - packing spends most of the rewrite step on the x18 scan and the spin-wait search, using one core per module. Cancelling a parallel rewrite can leave its workers running; `DM_REWRITE_J=0` or a negative value can silently omit spin gates, and the NSP script can ignore an explicit worker limit. → [Parallel scans preserve rewrite output](../reference/rewriter.md#parallel-scans-preserve-rewrite-output) - a rewrite never ends, using no CPU: `patch_nso.py` waits in `wait4` and one forked worker of the same command in `sem_wait`, in `multiprocessing/queues.py` `get`, having run no job. It is rare and needs small jobs (about 1 in 6,000 pools of tiny jobs under load). Separately, a SIGTERM could be ignored until the rewrite ended, or leave workers behind. → [A pool's shutdown hangs on a worker that has just started](../reference/rewriter.md#a-pools-shutdown-hangs-on-a-worker-that-has-just-started) ## Memory and address space - on the Mac, a game crashes once its address regions pass the profile's alias region: at launch (Trails in the Sky 1st Chapter: `sig=11 addr=0x1` at `sdk+0x15576c`, after an 11.27 GB region at alias +1.00 GB) or a little later (Just Dance: a null allocation past 4.375 GB after about 40 s, then a crash at `main+0x639ab0`), though the build's address region check reports a larger reach. A provisional profile's red line `past the profile's … alias region, the iPhone layout` says the same. Tears of the Kingdom's long-session memory-shortage Blood Moon (`[game] MSF / R / Rf` after about 87 minutes at +2.25 of 2.38 GB, issue #639) may be this too: not confirmed by a long session, and a mark near the top alone is not exhaustion. → [The Mac's alias region is the Switch's 64 GB](../reference/memory.md#the-macs-alias-region-is-the-switchs-64-gb) - large resources silently skipped, later a null deref where the resource is used; also visible as `SetHeapSize` asking for much less than the pool. → [Partitioning the guest block between alias region, stacks and heap](../reference/memory.md#partitioning-the-guest-block-between-alias-region-stacks-and-heap) - an `nn::diag` abort with Result 0 under `nn::os::detail::ThreadManager::CreateThread` → `ThreadManagerImplByHorizon::MapAliasStack`, on some boots and not on others, with no `MapMemory refused` line. → [Thread stacks placed at random in the stack region](../reference/memory.md#thread-stacks-placed-at-random-in-the-stack-region) - `SetHeapSize OOM: req 0x600000 > cap 0`, followed by an SDK abort in `nninitStartup` on the first provisional boot. → [Provisional Unreal layout leaves no heap](../reference/memory.md#provisional-unreal-layout-leaves-no-heap) - `nnMain` returns right after `nv::InitializeGraphics`, with no error (Hyrule Warriors: Age of Calamity); `[mem] SetHeapSize … + modules … > app pool` (Monster Hunter Rise), `[mem] SetHeapSize … + modules 0x5c00000 > app pool` (Catherine: Full Body); `SetHeapSize` asks for almost the whole application pool and fails at boot (Metroid Dread: 0xc9400000, larger than the heap region); the memory pool for the game's 96 MB GPU heap has no storage (`MemoryPoolInitialize` red line), then a null read at `main+0x2eb954` (Catherine: Full Body); heap allocations fail late in a busy scene. → [Heap sized from the application pool less used memory](../reference/memory.md#heap-sized-from-the-application-pool-less-used-memory) - `SetHeapSize OOM: req 0xffffffffe0000000 > cap 0xd0000000`, followed by an abort when allocating the launcher NRO. → [Offline NRO copies are not additional guest memory](../reference/memory.md#offline-nro-copies-are-not-additional-guest-memory) - repeated `[RED] MapMemory refused (0xd401)` for a stack source inside a loaded NRO's writable data, then an abort in `MapAliasStack` / `CreateThread`. → [Thread stacks backed by active NRO data](../reference/memory.md#thread-stacks-backed-by-active-nro-data) - `SetHeapSize OOM: req 0x120000000 > cap 0xd0000000`, then `Break#1 reason=0` in `nninitStartup`, with a backtrace through `nn::os::SetMemoryHeapSize` (`sdk+0x967a4`). → [A heap request beyond the heap region returns ResultOutOfMemory](../reference/memory.md#a-heap-request-beyond-the-heap-region-returns-resultoutofmemory) - a provisional profile's heap check reports "the heap request did not fit; set mem_reserve", the build finishes, and the game still stops at its first run: `SetHeapSize OOM: req 0x18ce00000 > cap 0xb8000000`, then `CRASH sig=10` (SIGBUS) in `nninitStartup` on the heap it never got. → [The heap check grows the block around the profile's alias region](../reference/memory.md#the-heap-check-grows-the-block-around-the-profiles-alias-region) - the app quits at launch; the host log shows `SetHeapSize OOM: req 0xc5200000 > cap 0`. → [Unreal games without virtual address memory take a heap](../reference/memory.md#unreal-games-without-virtual-address-memory-take-a-heap) - `CRASH sig=11 addr=0 pc=sdk+0x4656c8` right after the window is created, with `x0 = 0` and the return address in `main` (`main+0x3508a90`): the faulting code is `ldr x0,[0xc5d000+0xc68]; ldr x8,[x0]; ldr x1,[x8,#0x68]; br x1`. → [`nv::GetGraphicsMemoryInfo` with no graphics device](../reference/memory.md#nvgetgraphicsmemoryinfo-with-no-graphics-device) - a null pointer in the game's resource code (`main+0x15a69b0`, null + 0x78, thread `BaseProcCreateAndDeleteThread`): a model's load returned null, its status 9, written hundreds of times by a loader thread. The `[mem]` lines end near the top of the alias region. → [An SDK 21 Switch 2 game with a 4.5 GB alias region](../reference/memory.md#an-sdk-21-switch-2-game-with-a-45-gb-alias-region) - `StandardAllocator::Initialize` aborts in `nninitStartup` (Fire Emblem Engage); `nn::diag` abort in `StandardAllocator::Initialize(void *, size_t, bool)` from `nninitStartup` (`sdk+0x2f98e4` ← `main+0x5b69e0`, Big Brain Academy: Brain vs. Brain). → [Virtual address memory follows the NPDM's system resource](../reference/memory.md#virtual-address-memory-follows-the-npdms-system-resource) - the first `AllocateAddressRegion` fails with 0x1803; `StandardAllocator::Initialize` aborts in `nninitStartup` (an `nn::diag` abort; the NSP script's heap check reports "the host stopped before nnMain"); the alias region fills in minutes; regions a game reserves later fail (Size-aligned regions exhaust the alias address space, The movie player's own StandardAllocator). → [The SDK's address-region node area](../reference/memory.md#the-sdks-address-region-node-area) - a null-based write minutes into play, at the pool size minus 0x20 (Engage: a write to `NULL + 0x1fffe0`, `addr=0x1fffe0` at `main+0x9a4664`); NULL index pointers written on several job threads at once (`main+0xdb0ad4`, `0xdaea58`, `0xdadb5c`), with 32-bit mesh indices turning up inside texture objects. → [Size-aligned regions exhaust the alias address space](../reference/memory.md#size-aligned-regions-exhaust-the-alias-address-space) - a cut engine region still does not fit; two large regions lose up to 1 GB each to alignment, depending on where `mmap` put the guest block (Absolum); the region comes 0.69 GB past the 1 GB node area, at the next 1 GB boundary (Paper Mario: The Thousand-Year Door). → [1 GB alignment of regions of 1 GB and more](../reference/memory.md#1-gb-alignment-of-regions-of-1-gb-and-more) - a write at NULL + 0x3fffe0 (a 4 MB pool − 0x20) at `main+0x48b770`, about six minutes into the prologue, with Unity's `ALLOC_CACHEOBJECTS_THREAD` allocator in x19; the `[mem]` high-water mark at +4.26 GB of the 4.375 GB alias region while 1.26 GB is mapped (Sea of Stars). → [Size-class alignment doubles Unity's regions](../reference/memory.md#size-class-alignment-doubles-unitys-regions) - nothing aborts at startup as with Unity 2022.3, but the provisional profile gave a 1 GB block and a 256 MB alias region while Unity maps 1.5 GB in the first room. → [Unity 6 takes its memory with no StandardAllocator and no heap](../reference/memory.md#unity-6-takes-its-memory-with-no-standardallocator-and-no-heap) - `nn::diag` abort from `StandardAllocator::Initialize` long after `nninitStartup`, right after the first Vulkan query pool (`sdk+0x12dad0` ← `main+0x62c52c`). → [The movie player's own StandardAllocator](../reference/memory.md#the-movie-players-own-standardallocator) - the `[mem]` high-water mark climbs close to the end of the alias region while far less is mapped (SUPER ROBOT WARS Y: +4.27 GB of 4.38 GB with 1.82 GB of live regions), and it looks like the address space is about to run out. → [An alias high-water mark near the top is not exhaustion](../reference/memory.md#an-alias-high-water-mark-near-the-top-is-not-exhaustion) - `StandardAllocator::Initialize` aborts in `nninitStartup` (Pokémon Legends: Z-A: `main+0x1b2e690`); `nn::diag` abort at `sdk+0x11ff34` (`StandardAllocator::Initialize`) in `nninitStartup`, SDK 15.3.2, called from `main+0x31370c` (Paper Mario: The Thousand-Year Door). → [StandardAllocators over 12 to 62 GB of address space](../reference/memory.md#standardallocators-over-12-to-62-gb-of-address-space) - a SIGSEGV writing just past a null base as a menu or board loads (`nn::bezel::CoreSystem::Allocate` returned null for a 46 MB request at `main+0x8d9a48`, Super Mario Party Jamboree 2.3.0), sometimes first `[RED] fs ReadFile into 0x0+0x400000 failed at +0 (EFAULT)`, a read into a null buffer from the same allocator; the alias region's `[mem]` lines show `StandardAllocator::Initialize(nullptr, 56.00 GB) … 2.06 GB of address space`. → [Bezel Engine's two memory setups](../reference/memory.md#bezel-engines-two-memory-setups) - a write to `0x20000ffff` in static initialization (`main+0x164990`), after `AllocateAddressRegion` returns `0x1803`; reducing the request to 3 GB still returns `0x1803` with the SDK's original large-region alignment. With only the outer ranges reduced, a later free crashes at `main+0x1668dc` after reading compressed file data as a slab-owner pointer. With all three ranges cut, a write to `0x78` at `main+0x2c534a8` (`lr=main+0x2c53484`) when the opening quest's overalls bush is shaken, or when a later save loads. With a pool too small for the area: `nn::diag` abort with `Result 0` and an empty message while a world loads, backtrace `sdk+0x16ba48 sdk+0x37d1b0 sdk+0x37c2f4 sdk+0x37c27c sdk+0x37a980 main+0x12300c main+0x164b40 main+0x164954 main+0x168e54` on Sparks of Hope 1.6.2225577 and SDK 13.3.5. → [Separate virtual ranges in Snowdrop's page allocator](../reference/memory.md#separate-virtual-ranges-in-snowdrops-page-allocator) - `nn::diag` abort at `sdk+0x12dad0` in `nninitStartup`, called from `main+0x756310` (1.1.1: `main+0x7562d0`). → [.NET NativeAOT malloc and the GC region range](../reference/memory.md#net-nativeaot-malloc-and-the-gc-region-range) - the game aborts in its static initialisers, before `nnMain`, when its own 62 GB address region fails (`main+0x37c9bd0`, `AllocateAddressRegion(&p, 0xf80000000)` at `main+0x37c9a5c`). → [A 62 GB page allocator behind `nu::VirtualAllocHook`](../reference/memory.md#a-62-gb-page-allocator-behind-nuvirtualallochook) - the game calls `exit(1)` in `nninitStartup` (Octopath Traveler 0: `main+0x12e74`); `nn::diag::Abort` from `main+0x352fbec` (Unreal's fatal error) after the first commit, `AllocateMemoryPages(0, 2 MB)` while the RHI starts (`main+0x353ff8c`, result 0xe03) (Pikmin 4); a crash in `NumberLineAllocator::Compaction` at boot (DRAGON QUEST XI S, region option 4224). → [Unreal's engine address region and its options](../reference/memory.md#unreals-engine-address-region-and-its-options) - a null read in the out-of-memory report at `main+0x1005824` when the engine region is smaller than the allocator's pools (Octopath Traveler 0). → [Unreal's FMallocBinned3 replaced by the host allocator](../reference/memory.md#unreals-fmallocbinned3-replaced-by-the-host-allocator) - Wwise crashes in `AK::MemoryMgr::Init` while reallocating or freeing a block, after Unreal switches to the host heap. Whether a boot crashes depends on where the heap puts the block, and the fault address can be a null read or garbage. → [Wwise loses the span header in a virtual block from Unreal's heap](../reference/memory.md#wwise-loses-the-span-header-in-a-virtual-block-from-unreals-heap) - an abort right at `nnMain`, under `nn::os::CreateThread` → `ThreadManagerImplByHorizon::MapAliasStack` → `StackGuardManager::MapAtRandomAddress`; with the log line, `[RED] MapMemory refused (0xd401): <stack region> <- <address outside the guest block>`. → [Thread stacks from the host's Unreal heap](../reference/memory.md#thread-stacks-from-the-hosts-unreal-heap) - `nn::diag` abort from `main+0x11bc`, no message, in the first battle, with about 1 GB mapped (FINAL FANTASY RESONANCE with DRAGON QUEST VII Reimagined's 2 GB region). → [Unreal 5.6's page allocator never gives address space back](../reference/memory.md#unreal-56s-page-allocator-never-gives-address-space-back) - write to `0x268` right after the title screen (`main+0x5d6708`, a constructor whose `this` is `0x200`). → [Ring heaps cut from a pool at 64 KB alignment](../reference/memory.md#ring-heaps-cut-from-a-pool-at-64-kb-alignment) - C++ exception aborts in `nn::ro::detail::GetExceptionInfo`. → [`svcQueryMemory` must report each module's real layout](../reference/memory.md#svcquerymemory-must-report-each-modules-real-layout) - `MapPhysicalMemory` faults on part of a page. → [`MapPhysicalMemory` in 16 KB host pages](../reference/memory.md#mapphysicalmemory-in-16-kb-host-pages) - the alias region's mapped total runs past the application pool in the first minute. → [Maps past the application pool fail as on Horizon](../reference/memory.md#maps-past-the-application-pool-fail-as-on-horizon) - after a large `UnmapPhysicalMemory` or heap shrink, RAM does not come back. `phys_footprint` may still fall, so it hides this: the `guest` class in `DM_MEMSTAT` shows the real figure. → [Unmapped guest memory stays resident](../reference/memory.md#unmapped-guest-memory-stays-resident) - a write through a null pointer at +0x1c0 during startup. → [`GetInfo(UserExceptionContextAddress)` returns a real buffer](../reference/memory.md#getinfouserexceptioncontextaddress-returns-a-real-buffer) - a null-pool buffer even with virtual pools working (Virtual memory pools mapped onto one physical pool). → [A null-pool buffer from a game heap that ran out](../reference/memory.md#a-null-pool-buffer-from-a-game-heap-that-ran-out) - a model load exhausts its resource heap: a null `operator new` at the world load, or `BufferInitialize: pool has no storage` followed by a null-pool crash. A display-list heap that runs out shows as `AddCommandMemory` with a null pool outside a recording, then host-lent segments growing until `FATAL NVN command memory` (Host-lent command memory segments). → [Model heaps sized by the host's command record sizes](../reference/memory.md#model-heaps-sized-by-the-hosts-command-record-sizes) - the frames stop at the first loading screen, a graphics worker at 100% CPU (17 s in, `UnityGfxDeviceWorker` running, the main thread waiting on a condition variable, no red line). → [Unity's GPU pool block allocation spins at size 0](../reference/memory.md#unitys-gpu-pool-block-allocation-spins-at-size-0) - SIGBUS inside a host hook (`snprintf` under `mount_ex` / `h_fs_MountSave`), then the process hangs (Super Mario 3D World + Bowser's Fury); SIGBUS inside Metal (`AGCDeserializedReply`, an AGX compiler block) at an address in the guest stack region (Breath of the Wild). → [Host calls on small guest stacks](../reference/memory.md#host-calls-on-small-guest-stacks) - the iPhone app is killed for memory; resident memory grows steadily (about 0.2 MB a frame) while the residency set and the texture counts stay flat. → [Deferred-release drain without an autorelease pool](../reference/memory.md#deferred-release-drain-without-an-autorelease-pool) - travelling produces a brief multi-GB footprint spike, then memory returns to its earlier level; periodic memory lines can miss the peak. Upload diagnostics show many swapped-out blocks still alive in one batch. → [Upload staging grows within one rendering submission](../reference/memory.md#upload-staging-grows-within-one-rendering-submission) - GPU memory grows with repeated `nvnTextureReadTexels` calls on a long-lived game thread, even after each readback completes. → [GPU readback without an autorelease pool](../reference/memory.md#gpu-readback-without-an-autorelease-pool) - process footprint and Metal allocation grow during stationary gameplay even after readback fences complete; the deferred-release queue and command allocator sizes remain bounded. → [Completion readbacks survive a guest waiter's pool](../reference/memory.md#completion-readbacks-survive-a-guest-waiters-pool) - `footprint` shows `Malloc Large` about the size of `pso_archive/` (the log's `pipeline archive …: N files, … MB`), resident or swapped for the whole run. `MallocStackLogging=1` with `malloc_history <pid> -allBySize` gives `newArchiveWithURL` → `MTL4ArchiveImpl::loadFromURL` → `LoaderGlobalState::loadFile` → `-[NSData initWithContentsOfFile:options:maxLength:error:]` → malloc. → [A pipeline archive on an external drive is read into memory](../reference/memory.md#a-pipeline-archive-on-an-external-drive-is-read-into-memory) - the periodic `residency set up to frame` line shows hundreds of allocations added and removed per 300 frames in a scene where nothing loads: Ocarina of Time, 1,500 (`pool_gpu` 900 of 180 KB, `mrbuf_get` 600 of 0.5 MB), and 650 commits. → [Pool tables and readback buffers made anew each frame](../reference/memory.md#pool-tables-and-readback-buffers-made-anew-each-frame) - with a profile that has `tex_dirty_upload`, a texture in a sparse pool that the game draws into or writes as an image logs `CPU-written texture ser=…` at its first use, and takes its content from its storage. `t_sparse_tiles` crashed at `and unmapped, not drawn: its heap tile goes back` when built with such a profile, and passed with one without the key. → [A texture in a sparse pool came out CPU-written at its first use](../reference/memory.md#a-texture-in-a-sparse-pool-came-out-cpu-written-at-its-first-use) - on an iPhone the app is ended by the system (a jetsam event: no crash report, no `[dm] CRASH` line) once its footprint reaches the limit: about 6 GB on a 12 GB iPhone with the increased memory limit (6,143 MiB measured in LiveContainer), 3.3 GB without it. The log stops mid-frame. → [iOS ends the app once the guest's touched pages reach its memory limit](../reference/memory.md#ios-ends-the-app-once-the-guests-touched-pages-reach-its-memory-limit) - a Switch 2 game goes past Metal's recommended working set while its first 3D scene loads: `Insufficient Memory` command buffer errors, then a hung Mac. Ocarina of Time on a 16 GB Mac: 12 GB and more wired, once a kernel panic in `IOGPUGroupMemory.cpp` at 14.7 GB wired. → [Memory pools nothing gave an address to stay out of the raw pool table](../reference/memory.md#memory-pools-nothing-gave-an-address-to-stay-out-of-the-raw-pool-table) - a game whose shaders read texture handles from memory wires far past the working set while a scene loads, with `Insufficient Memory` errors or a panic, and stutters when new textures stream in. With a limit on how many it makes, surfaces in shadow go near black instead. → [Shaders report which textures they read through a pool](../reference/memory.md#shaders-report-which-textures-they-read-through-a-pool) - the Mac grows unresponsive for hours, then panics, with the host still submitting work that fails. → [Repeated GPU out-of-memory failures end the game](../reference/memory.md#repeated-gpu-out-of-memory-failures-end-the-game) ## Threads - TSan reports `thread_main` writing `host_work` while `thr_runnable` reads it during a same-core yield (`t_notify_sched`, issue #411). → [Publishing a new thread's scheduler fields](../reference/threads.md#publishing-a-new-threads-scheduler-fields) - a parent returns from `StartThread` before a newly runnable higher-priority child pinned to its core finishes its work (deterministic regression, not attributed to a game failure). → [Starting a higher-priority thread on the caller's core](../reference/threads.md#starting-a-higher-priority-thread-on-the-callers-core) - a crash at the very start of a new thread, reading through a null pointer it took from its argument (`main+0x1dc0`, in a boot stub's last thread, about once in a dozen boots), with the starter still in its next few calls. → [A thread's arguments in slots its starter reuses after connecting to a service](../reference/threads.md#a-threads-arguments-in-slots-its-starter-reuses-after-connecting-to-a-service) - per-core job queues never drained. → [Core mask changes move the ideal core into the new mask](../reference/threads.md#core-mask-changes-move-the-ideal-core-into-the-new-mask) - crash indexing a per-core table with a huge offset (index −2). → [Ideal core −2 resolves to the process default core](../reference/threads.md#ideal-core-2-resolves-to-the-process-default-core) - the main thread waits forever on an event right after `nnMain` starts, with only three or four threads created; `DM_THR=1` shows no `CreateThread` for the thread it waits on. → [Free thread count (`svcGetInfo` type 24)](../reference/threads.md#free-thread-count-svcgetinfo-type-24) - in garbage-collected titles (Unity / IL2CPP), live objects freed, with their finalizers releasing native resources. → [Pausing threads and reading their context for garbage collectors](../reference/threads.md#pausing-threads-and-reading-their-context-for-garbage-collectors) - in a garbage-collected title whose collector stops threads cooperatively, live objects freed while their thread sleeps, and their memory reused: a crash in the collected runtime's code on a pointer made of another object's bytes (Streets of Rage 4: `CRASH sig=11` at `main+0x46a4`, BRUTE's `SyncBlock::GetSyncBlock`, on `0x5b005b00000002`, a string's length 2 and "[["), in about two boots of three, during the first seconds of loading. → [SVCs leave the stack below sp untouched](../reference/threads.md#svcs-leave-the-stack-below-sp-untouched) - crashes around movie changes in the game's own player threads, about one run in two: `SignalEvent` → `MultiWaitImpl::NotifyAndWakeupThread` on a null MultiWait at address 0x20; `WaitAny` walking freed holders; a worker reading a freed object at `main+0x225338`. The other way round, a handoff that waits too widely: a black screen at boot that never loads a texture (`packaged textures: first uploads 0`), or a load that never ends behind an animated loading screen, with the thread dump's `same-core handoffs N, total T ms` larger than the run itself. → [Same-core wake handoffs](../reference/threads.md#same-core-wake-handoffs) - the picture stops for good while sound goes on; the main thread spins in the game's own wait loop (a `sample` of the process shows it in guest code, no SVC), the other guest threads wait, and the job workers it waits for sit in `svc_thread` → `dm_yield_to_core_peers` → `nanosleep`. → [A same-core handoff holds only a waker pinned to that core](../reference/threads.md#a-same-core-handoff-holds-only-a-waker-pinned-to-that-core) - the picture stops and stays (sound goes on) at random places, about one run in two: every task worker waits on its own event, and the task a waiter waits for counts a subtask that is marked queued but is in no queue (the ring's head equals its tail). → [Lock-free queues published without barriers](../reference/threads.md#lock-free-queues-published-without-barriers) - the game freezes when a movie starts playing beside the game (a guide movie in a corner of the screen): the last frame stays, the process idles at a few percent of a core, and the thread dump shows a lower-priority job thread `running/not waiting` with its backtrace in the movie player (`ReleaseOutputBufferIndex`), the main thread waiting for it, and the movie's input thread `running/not waiting` too. A `sample` of the process shows the job thread in `md_pump` → `md_event` → `dm_yield_to_core_peers`, and the input thread in `h_movie_SendIn` → `md_pump` waiting for a pthread mutex. → [A host lock held across a same-core handoff](../reference/threads.md#a-host-lock-held-across-a-same-core-handoff) - several threads crash at once and the dumps interleave, then the process hangs instead of exiting. → [Simultaneous crashes of several threads](../reference/threads.md#simultaneous-crashes-of-several-threads) - `watchdog: sampling failed` and no thread stacks when `DM_WATCH_SAMPLE` contains an apostrophe, such as `/tmp/John's Mac/hang.txt`; shell syntax in the path can also run commands, and long paths are truncated. → [Watchdog sample output paths are literal arguments](../reference/threads.md#watchdog-sample-output-paths-are-literal-arguments) - none seen; found while investigating Fire Emblem Engage's demo crash, which it did not change (that was the address-space shortage, Size-aligned regions exhaust the alias address space). → [`SignalToAddress` type 2 with count ≤ 0](../reference/threads.md#signaltoaddress-type-2-with-count--0) - a 64-bit wait could return at once or block when it should not (not met in a game). → [`WaitForAddress` type 3: 64-bit wait if equal](../reference/threads.md#waitforaddress-type-3-64-bit-wait-if-equal) - boot stops before or soon after the first frame with the CPU at 0% and every guest thread waiting on a condition variable: the main thread in `nn::os::AcquireSemaphore` after posting a command to `UnityGfxDeviceWorker`, the worker in `AcquireSemaphore` too, one condition wait after it (`wait #` one higher); 3 of 5 Mac runs, at random points. → [Unity's stream buffer handshake loses a wake-up on Apple cores](../reference/threads.md#unitys-stream-buffer-handshake-loses-a-wake-up-on-apple-cores) - the picture stops and sound goes on, at a random frame (3,000 to 51,300, about 100 s at the quickest), with no `[RED]` line and the GPU idle and caught up. `main` is parked in `nn::os::WaitConditionVariable`, called from the park in Trinity's submit loop. The release flag is set, the state word is 1, the mutex is free, and no `SignalProcessWideKey` was ever issued for that key. → [Trinity's rendezvous loses its release on Apple cores](../reference/threads.md#trinitys-rendezvous-loses-its-release-on-apple-cores) - a game that runs on the Switch crashes on the Mac 10 to 60 s into a scene, at a different place each run, with garbage in a list the game just built (Breath of the Wild 1.6.0: `h_nvnBufferGetAddress` called with a row's metadata word as the buffer pointer, `main+0x14ef6e0`; also faults in `main+0x12970dc`, `+0x13615f4`, `+0x1445d48`, `+0x1472470`). A trace of the draw-list builders shows two threads inside the same view at once, running the same job descriptor. → [Lock acquire without acquire ordering runs a queue item twice](../reference/threads.md#lock-acquire-without-acquire-ordering-runs-a-queue-item-twice) - a PhysX worker crashes in a task's `removeReference` with a null task manager, right as the game switches to 30 fps (`pc=main+0x10ccf28`, `lr=main+0x13c236c`); on the iPhone and in 2 of 5 Mac runs, in every Mac run with 12 busy loops loading the CPU. → [Late PhysX task destructor after the unlock](../reference/threads.md#late-physx-task-destructor-after-the-unlock) - `game called nn::diag abort: Result 0, call site sdk+0x153c34` during `main`'s static initialisers, `bt: sdk+0x153c34 sdk+0x137eb4 sdk+0x13dc50 sdk+0x13fa90 sdk+0xa4d64 main+0x134 run_module_inits+0xa8 guest_main+0x15c main+0xfc start+0x1a20`, and no game code on the stack at all. → [The thread ID at ThreadLocalRegion+0x110 (SDK 22)](../reference/threads.md#the-thread-id-at-threadlocalregion0x110-sdk-22) - a 30 Hz game thread runs at 27 Hz, and whatever it paces comes out slow (cutscenes at 36 ms per frame instead of 33.3; gameplay was fine at 60). → [Timer slack in guest sleeps (`sleep_precise`)](../reference/threads.md#timer-slack-in-guest-sleeps-sleep_precise) - a guest thread keeps a core at 100% with billions of `SleepThread` calls. → [Sleeps under 20 µs take the yield path](../reference/threads.md#sleeps-under-20-µs-take-the-yield-path) - a thread polls at full speed although the power line's yields (if any) show no back-off sleeps; a `sample` of the host shows it in `svc_thread` → `block` → `pthread_cond_wait` with timeouts of nanoseconds, between plain `cthread_yield`s. → [Short timed waits are polls](../reference/threads.md#short-timed-waits-are-polls) - a loading screen sits for a minute with the CPU nearly idle; one thread yields thousands of times a second, every yield a back-off sleep (the power line's top yielder, with as many back-off sleeps). → [Yields that make progress return at once (`thr_yield`)](../reference/threads.md#yields-that-make-progress-return-at-once-thr_yield) - one guest thread keeps a host core at 100% with about a billion yields a minute (`SVC 0xb` in `DM_HLECOUNT`), none of them a back-off sleep, while the game itself plays normally. → [A wait at two yields is not progress](../reference/threads.md#a-wait-at-two-yields-is-not-progress) - a host helper thread aborts when signalling a destroyed `SystemEvent`; repeated `vi::GetDisplayVsyncEvent` calls double the event's tick rate. Rapid replacement can abort with `too many vsync events`, or a retired vsync worker can signal another service's event at reused storage. → [Service-event producers follow the binding lifetime](../reference/threads.md#service-event-producers-follow-the-binding-lifetime) - the main thread waits forever on a job's done event at boot while every worker sleeps, two of them on one event (`main+0x1426c` waiting on `Job::m_doneEvent`); 4 of 6 Mac runs. → [One auto-clear event shared by a pool's workers](../reference/threads.md#one-auto-clear-event-shared-by-a-pools-workers) - abort in `os::WaitSystemEvent` under `oe::PopNotificationMessage` (The Legend of Zelda: Link's Awakening); one guest thread at about 1000 ms/s on the iPhone only, the phone hot, CPU energy 5–7 W (Monster Hunter Rise's `MessageSuperviseThread`, priority 32, in the `[nvn] threads` lines). → [The oe notification event and its queue](../reference/threads.md#the-oe-notification-event-and-its-queue) - Paper Mario: The Thousand-Year Door 1.0.1 stays black before its first frame. The main thread stops at `main+0x32796c`, after starting `SYS_Notification`; the priority-28 notifier is in `oe::PopNotificationMessage`, while the priority-44 main thread waits for its same-core wake handoff. → [Native HLE waits release the guest core](../reference/threads.md#native-hle-waits-release-the-guest-core) - every save slot shows NO DATA and `Play Time 0 mins`, right after "Save was successful" and with a save imported from elsewhere, though the files are there and a commit is logged. Reopening the save screen reads no save file (`DM_FS=1`). The terms of service come back at every boot, since the system data save is refused too. → [File system calls are service requests](../reference/threads.md#file-system-calls-are-service-requests) ## Services and SDK calls - `sm::Initialize` aborts right after `ConnectToNamedPort` (SVC 0x1F) and `SendSyncRequest` (0x21); abort inside `nn::sm::Initialize`, the log showing `SVC 0x1f` (ConnectToNamedPort, port name `sm:`) and `SVC 0x21` answered by placeholders, then an `nn::diag` abort; abort with no message at start-up in a service call the host has no hook for (`Break` from `sdk+…` with an `nn::diag` backtrace). → [SDK calls that open a system service through sm](../reference/services.md#sdk-calls-that-open-a-system-service-through-sm) - a game update aborts at boot where the base game ran. → [A game update imports SDK calls the base game did not](../reference/services.md#a-game-update-imports-sdk-calls-the-base-game-did-not) - abort in `sm::Initialize` under `sf::hipc::InitializeHipcServiceResolution`, right after the first frames (from `main+0x5b8198`). → [Game-linked HIPC clients of system services](../reference/services.md#game-linked-hipc-clients-of-system-services) - a call the host hooks under its newer name reaches the SDK's own code on an older game. → [Older SDK names for the same calls](../reference/services.md#older-sdk-names-for-the-same-calls) - abort in `sm::Initialize` under `nn::friends::GetBlockedUserList` after the opening movie. → [SDK 4's `friends::GetBlockedUserList` without a `Uid`](../reference/services.md#sdk-4s-friendsgetblockeduserlist-without-a-uid) - the first loading screen never ends; `DM_FS=1` shows `save:/system` "not found" and no `fs mount save`. → [SDK 6's `account::OpenPreselectedUser` returns a Result](../reference/services.md#sdk-6s-accountopenpreselecteduser-returns-a-result) - the host crashes in `h_fs_OpenDirectory` when its folder-backed directory handle allocation fails. → [Directory handle allocation failure](../reference/services.md#directory-handle-allocation-failure) - IL2CPP "Could not open …/global-metadata.dat" (then a crash in its logger). → [The SDK's own `fs::IsMounted` reads an empty mount table](../reference/services.md#the-sdks-own-fsismounted-reads-an-empty-mount-table) - `game called nn::diag abort: Result 0x7802` (`MountNameAlreadyExists`) when a game mounts a RAM disk under a name it has just unmounted. → [A mount in the SDK's own table stays until the SDK releases it](../reference/services.md#a-mount-in-the-sdks-own-table-stays-until-the-sdk-releases-it) - a 10-byte read of the wrong RomFS file, then a null pointer at boot; files named `rom:\StartupUI.pak` are not found. → [File handles with low bits set, and backslash paths](../reference/services.md#file-handles-with-low-bits-set-and-backslash-paths) - after a rebuild, a game shows every file of its file select as new, while its save folder holds names that start with a backslash (`\savedata0.bin`, `\screenshot0.bin`). → [Saves named before backslash paths](../reference/services.md#saves-named-before-backslash-paths) - a fault inside `sdk` at boot, right after the save data is mounted: `ldr w8, [x0, #0x24]` with `x0` holding a host file handle (SD GUNDAM G GENERATION CROSS RAYS: `sdk+0x62a78`, `x0 = 0x4000000000000390`), while `GetFileSize` on the same handle answered just before. → [An unhooked `fs::ReadFile` overload falls through to the SDK's own](../reference/services.md#an-unhooked-fsreadfile-overload-falls-through-to-the-sdks-own) - Addressables never start (no `StreamingAssets/aa/settings.json` in the `DM_FS=1` output at all), then a null asset crash (`main+0x31100ec`). → [C library path checks ask the file system's limits](../reference/services.md#c-library-path-checks-ask-the-file-systems-limits) - an Atk task aborts in a `switch` default (`UnexpectedDefaultImpl`, then `AbortImpl`) while a stream sound loads. → [Paths with `.` and `..` components](../reference/services.md#paths-with--and--components) - a long black screen at boot with nothing in the log (Engage: about 17 s on the Mac, 32 s on an iPhone); sampling the process (`sample <pid> 3`) shows `getxattr` under `path_component` at the top of stack. → [RomFS lookups on large directories](../reference/services.md#romfs-lookups-on-large-directories) - `[RED] fs ReadFile into … failed at +0 (EFAULT): VM region … protection 1`, now and then. → [ReadFile into write-protected texture pool pages](../reference/services.md#readfile-into-write-protected-texture-pool-pages) - `fs … not found` lines with `DM_FS=1`. → [File-not-found noise from optional paths](../reference/services.md#file-not-found-noise-from-optional-paths) - a missing `fs::DeleteDirectory`; undefined `nn::fs::` / `nn::account::` imports with no hook, found from the import list (Listing a game's unhooked imports before they are met) before they were met. → [Directory, file data cache and save-thumbnail calls](../reference/services.md#directory-file-data-cache-and-save-thumbnail-calls) - the SDK's own code opened fsp-srv and aborted, leaving the save writes uncommitted. → [`fs::Commit` with a list of mounts](../reference/services.md#fscommit-with-a-list-of-mounts) - a failed write in one independent save can make another save's next `Commit` fail and discard its successful changes; the damaged save may then commit its truncated working file. → [Save-write failures stay with their backing transaction](../reference/services.md#save-write-failures-stay-with-their-backing-transaction) - `[RED] save transaction: cloning the work directory failed (…, errno=45)` when the save folder (`DM_SAVE`) is on an external drive, then a read-only save mount and every save write failing (South Park: `profile.sys`); now the line reads `the save folder's filesystem cannot clone directories (save transactions need APFS …)`. → [A save folder that cannot clone directories](../reference/services.md#a-save-folder-that-cannot-clone-directories) - SIGSEGV at address 0 in `nn::fs::GetSaveDataSizeMax`, about 13 minutes into a new game. → [Save data size queries](../reference/services.md#save-data-size-queries) - each aborted in `sm::Initialize` or read a null applet proxy, one per boot. → [Cache storage and other titles' save data](../reference/services.md#cache-storage-and-other-titles-save-data) - the island lives in device save data, which the host did not mount. → [Device save data on the account save's directory](../reference/services.md#device-save-data-on-the-account-saves-directory) - every boot asks to pick a Mii again (`DM_FS=1`: `UserSave:/userdata.dat` not found although the host save has it). → [Device and account save data as two saves](../reference/services.md#device-and-account-save-data-as-two-saves) - abort in `fs::detail::GetFileSystemProxyServiceObject` under `fs::QueryMountSystemDataCacheSize` (`main+0x8f23bc`). → [System data stand-in for the MiiModel archive](../reference/services.md#system-data-stand-in-for-the-miimodel-archive) - a failed write of `<DM_SAVE>.sync.tmp` leaks its stream, and the diagnostic can report a cleanup error instead of the write error. → [Save-sync metadata errors close the temporary file](../reference/services.md#save-sync-metadata-errors-close-the-temporary-file) - DLC the player owns is not unlocked. → [Add-on content from `DM_AOC_DIR`](../reference/services.md#add-on-content-from-dm_aoc_dir) - some owned DLC is missing, and `aoc: reporting` stops at 64 add-on contents. → [Owned add-on content lists beyond 64 entries](../reference/services.md#owned-add-on-content-lists-beyond-64-entries) - SIGSEGV in `crypto::detail::CbcModeAes128Helper::DecryptBlocks` with a null destination (`main+0x8737e8`, right after `aoc:` is mounted). → [Add-on content mount cache sized as RomFS working memory](../reference/services.md#add-on-content-mount-cache-sized-as-romfs-working-memory) - SIGBUS in `__vfprintf` under `aoc_load`, from `h_aoc_Count` (a store to `0x…67ff0`, right below a page of the guest thread's stack). → [Add-on content queries on a small guest stack](../reference/services.md#add-on-content-queries-on-a-small-guest-stack) - clang reports a negative shift in `fill` or `vib_targets` (`hle_hid.c`). → [Controller disconnect between style and player lookup](../reference/services.md#controller-disconnect-between-style-and-player-lookup) - connecting a Steam Controller clears another controller's held input or rumble and makes it press a button to rejoin; a composite controller can appear as two players or lose native fallback after a partial exclusive open. → [Steam Controller hotplug interrupts other players](../reference/services.md#steam-controller-hotplug-interrupts-other-players) - `DM_RUMBLE_MIN` silences quiet effects on native controllers but has no effect on the Steam Controller's direct HID output. → [Steam Controller bypasses the rumble cutoff](../reference/services.md#steam-controller-bypasses-the-rumble-cutoff) - six-axis values reach the game but gyro aiming does nothing, or stops after using a stick. → [Steam Controller stick drift suppresses gyro aiming](../reference/services.md#steam-controller-stick-drift-suppresses-gyro-aiming) - buttons and menus work, the sticks do nothing in play (Super Mario Odyssey: its first hint, "Look Around", waited forever); an `nn::diag` abort with Result 0x2aca in the first frames of `nnMain` (Hollow Knight: Silksong, Unity 6000.0.50f1: `bt: sdk+0x514580 main+0x1296c64 …`). → [History reads fill every requested entry](../reference/services.md#history-reads-fill-every-requested-entry) - the game never reads the controller (the title's "Press L+R" never sees a press; no `GetNpadState` call at all). → [Npad style set update event](../reference/services.md#npad-style-set-update-event) - motion moves never happen; shaking does nothing (Super Mario Odyssey: cap throws by shaking). → [Six-axis sensors](../reference/services.md#six-axis-sensors) - motion controls do nothing with a controller that has a gyroscope (Breath of the Wild: aiming with its Motion Controls option on); the six-axis sensor always lies flat. → [Live controller motion](../reference/services.md#live-controller-motion) - a non-finite accelerometer or gyro sample corrupts the six-axis fields; later valid samples do not restore the previous fusion state. → [Non-finite motion samples](../reference/services.md#non-finite-motion-samples) - on iPhone Duo's inner display the phone's gyro is turned a quarter turn: tilting up and down moves the pointer left and right, and the other way round (GitHub issue #569); the outer display is right. → [The phone's motion in the picture's frame](../reference/services.md#the-phones-motion-in-the-pictures-frame) - a Pro Controller's buttons work on the Mac, but its gyro pointer never moves; `GCMotion` callbacks arrive with acceleration and rotation all zero. → [Switch Pro Controller advertises motion but sends zeroes](../reference/services.md#switch-pro-controller-advertises-motion-but-sends-zeroes) - six-axis handles use byte 0 = 0 for a FullKey controller, which the SDK reserves for no style; Handheld exposes two sensors instead of its combined sensor. → [Six-axis handle encoding](../reference/services.md#six-axis-handle-encoding) - a button mapped to Shake does nothing on a secondary controller, including the first physical controller with `DM_KBD_PLAYER=own`, even though its normal buttons work in a one-player game. → [Mapped Shake on secondary controllers](../reference/services.md#mapped-shake-on-secondary-controllers) - SDK 20 calls that reach a service; `nfp`'s `AttachActivateEvent` / `AttachDeactivateEvent` crashed in the SDK at `sdk+0x3f2a78`. → [SDK 20 six-axis sensor and amiibo (`nfp`) calls](../reference/services.md#sdk-20-six-axis-sensor-and-amiibo-nfp-calls) - `[RED] sf: the game connects to service nfp:user itself`, then `game called nn::diag abort: Result 0xe15` under the game's own initialization (`main+0x115deb0`). → [`nfp`'s extended application area](../reference/services.md#nfps-extended-application-area) - selecting amiibo initializes `nfp`, then the game connects to the unserved `nfc:user` service and aborts in `nn::nfc::Initialize`. → [NFC initialization beside the amiibo library](../reference/services.md#nfc-initialization-beside-the-amiibo-library) - `game called nn::diag abort: Result 0, call site sdk+0x13ce58` in the middle of play, from `nn::os::TryWaitSystemEvent` on an event that was never set up (backtrace `main+0x1fb9920` in Tears of the Kingdom 1.4.3). → [The amiibo library's state before Initialize](../reference/services.md#the-amiibo-librarys-state-before-initialize) - abort in `nn::sm::Initialize` under `nn::hid::VibrationNode::Update`. → [Vibration values flushed by the SDK's vibration graph](../reference/services.md#vibration-values-flushed-by-the-sdks-vibration-graph) - with rumble on, `[RED] sf: the game connects to service hid itself`, then `CRASH sig=11 addr=0` in `hid::detail::IsVibrationDeviceMounted` (`sdk+0x24254c` in SDK 7), under `hid::IsVibrationDeviceMounted`. With rumble off in the host's settings the game never asks. → [Whether a vibration device is mounted](../reference/services.md#whether-a-vibration-device-is-mounted) - `DM_RUMBLE_LOG=1` shows the game's startup handle request answered with none, then every vibration value sent to handle 0 and reaching no output for the whole session, although a controller with haptics (a DualSense on the Mac) is connected. A game that rumbles would stay silent. → [Vibration handles before a controller is reported](../reference/services.md#vibration-handles-before-a-controller-is-reported) - a controller (an Xbox Wireless Controller, a GameSir Super Nova, a GameSir Cyclone) never vibrates in a game on the Mac or the iPhone, though iOS Settings' Identify buzzes it; the log repeats `[RED] haptics: controller left handle create player: Couldn’t communicate with a helper application. (NSCocoaErrorDomain 4097)`. The engine itself starts. → [Controller haptic engines without advanced players](../reference/services.md#controller-haptic-engines-without-advanced-players) - on the Mac, a DualShock 4 or a controller that presents itself as one (a GameSir Cyclone over Bluetooth: HID vendor `054C`, product `05C4`, `productCategory` "DualShock 4") does not rumble; Core Haptics failed on every locality with NSCocoaErrorDomain 4097 (issue #363, also in a minimal Swift app), while the same controller rumbles in an SDL-based emulator. → [DualShock 4 rumble through its effects report](../reference/services.md#dualshock-4-rumble-through-its-effects-report) - with two controllers that present themselves as DualShock 4s on the Mac, the one turned on first rumbles normally and the one turned on later is barely felt. The first logs `rumble through the DualShock 4 effects report`; the later one logs `haptics: player 2 controller …, localities …`, then `has no advanced players (NSCocoaErrorDomain 4097): plain players` and `plays both motors on one engine (Handles)`. → [A DualShock 4 that connects after the first stays on Core Haptics](../reference/services.md#a-dualshock-4-that-connects-after-the-first-stays-on-core-haptics) - with a controller connected (a DualShock 4 here), `DM_KEYS` and `DM_CTL` presses are logged (`DM_KEYS: … press …`) but the game does not react to them, or only now and then; without the controller the same script works. → [Scripted presses on a path of their own](../reference/services.md#scripted-presses-on-a-path-of-their-own) - taps in handheld mode do nothing, though the game reads the touch screen (the title's PRESS ANY BUTTON, the menus' cards). → [Touch gestures recognized from the touch points](../reference/services.md#touch-gestures-recognized-from-the-touch-points) - on the Mac, the mouse pointer stays over the game picture while playing with a controller or the keyboard, in a window and in fullscreen (issue #675). → [Mac pointer stays over the game](../reference/services.md#mac-pointer-stays-over-the-game) - the Mac dims or turns off its display and can reach the lock screen while the player is using a controller, in a window or in fullscreen. → [Mac display sleep during controller play](../reference/services.md#mac-display-sleep-during-controller-play) - the first boot aborted in `hid::GetMouseState` (the SDK's mouse resource was never initialized). → [Mouse, keyboard and key code maps](../reference/services.md#mouse-keyboard-and-key-code-maps) - the first boot crashed in `hid::detail::SetPalmaBoostMode`, a null read at `sdk+0x238eb0` (the hid service never opened). → [Poké Ball Plus (Palma)](../reference/services.md#poké-ball-plus-palma) - undefined `irsensor` imports found from the import list (Listing a game's unhooked imports before they are met). → [IR camera reported unconnected](../reference/services.md#ir-camera-reported-unconnected) - null read in `sdk` under `nn::applet::CreateLibraryApplet` (Engage: title menu → DLC → `nn::ec::ShowShopAddOnContentList`); `Show…` overloads found in the imports before they were met. → [System applets opened by `Show…` calls](../reference/services.md#system-applets-opened-by-show-calls) - entering 2P stops the game on its 2P screen: the same frame repeats, the music plays, no controller does anything, until the window loses and regains focus (Mario Kart 8 Deluxe, every launch). With one controller, once that was fixed: the 2P character select ignores input while the log shows the controller applet opened again every few frames. → [Library applets take the application's focus](../reference/services.md#library-applets-take-the-applications-focus) - the sound stutters and the input box lags while the player types a name (Octopath Traveler 0 on an iPhone: one 4.7 s frame, 5,035 wakeups a second instead of about 1,800, and no audio underruns). → [The software keyboard blocks only its caller](../reference/services.md#the-software-keyboard-blocks-only-its-caller) - null read in `applet::CreateLibraryApplet` under `swkbd::InlineKeyboard::Initialize` (3D World, entering the save select after the character select). → [The inline keyboard as a resident library applet](../reference/services.md#the-inline-keyboard-as-a-resident-library-applet) - texture creation returns null right after the inline keyboard's `Initialize`, then a null read at `main+0x7713044`. → [Inline keyboard window size, setters and callbacks](../reference/services.md#inline-keyboard-window-size-setters-and-callbacks) - the hunter's name box stays empty, then stays open with the name in it (Monster Hunter Rise, character creation). → [Inline keyboard text callbacks and `Calc` states](../reference/services.md#inline-keyboard-text-callbacks-and-calc-states) - the name typed in the Mac input box is dropped and the game asks again; the log has `oe focus state → 2` and `→ 1` between `inline keyboard Appear` and `→ OK` (Monster Hunter Rise, character creation). → [The Mac input box keeps the game's focus](../reference/services.md#the-mac-input-box-keeps-the-games-focus) - `CRASH sig=10` at a heap address, called from `main+0x6bca160` right after the name was entered (Monster Hunter Rise); crash in `lmem::AllocateFromExpHeap` under `ngc::ProfanityFilter::MaskProfanityWordsInText` right after the character name is entered (DARK SOULS: REMASTERED); filter methods among the undefined imports with no hook, found from the import list before they were met (The Great Ace Attorney Chronicles). → [`nn::ngc::ProfanityFilter` vtable and by-name overloads](../reference/services.md#nnngcprofanityfilter-vtable-and-by-name-overloads) - `[RED] sf: the game connects to service ngct:u itself, which the host does not serve`, then `Break#1 reason=0 Result=0xe15` from the SDK when the player name is entered after a race (Cruis'n Blast). → [`nn::ngc` China-region profanity check and mask](../reference/services.md#nnngc-china-region-profanity-check-and-mask) - SIGSEGV in `vi::CreateLayer(Layer**, Display*, int, int)` (`sdk+0x3f9bc4`, from SDL3's Switch video driver at `main+0x239304`). → [`vi::CreateLayer` with the layer's size](../reference/services.md#vicreatelayer-with-the-layers-size) - SIGSEGV at `sdk+0x44ea94` reading address 0, in `vi::CreateLayer`, right after `am::GetSelfController()`; the caller is the game's window setup (`main+0x978cb6c`). → [`vi::CreateLayer` with `LayerCreationSettings` (SDK 22)](../reference/services.md#vicreatelayer-with-layercreationsettings-sdk-22) - SIGSEGV in `vi::SetLayerCrop` or `vi::OpenDisplay` when opening a display by name. → [vi layer and display calls without vi service objects](../reference/services.md#vi-layer-and-display-calls-without-vi-service-objects) - `CRASH sig=11 addr=0 pc=0` with the link register just after a call to a `vi::SetLayerNextHdr…` or `vi::ClearLayerNextHdr…` function. → [Layer HDR metadata](../reference/services.md#layer-hdr-metadata) - SIGSEGV in `android::Surface::getQueuedFrameNumber` under `nn::vi::GetLatestFrameNumber`. → [Layer frame numbers](../reference/services.md#layer-frame-numbers) - SIGSEGV in `vi::GetDefaultDisplayPanelIdentifier` (`main+0xa9a4`, before the window). → [Default display panel identifier](../reference/services.md#default-display-panel-identifier) - the first boot crashed in `oe::DisableAlbumImageTakenNotification`: a null read at `sdk+0x338070`, the first call in `nnMain` (`main+0x6b188c`); enabling those notifications also gives a null read at `sdk+0x33b0f0` (Xenoblade Chronicles 3); other `oe` calls that reach am, found in the imports before they were met. → [oe calls answered without an applet proxy](../reference/services.md#oe-calls-answered-without-an-applet-proxy) - a null read at `sdk+0x36ec60` in `oe::EnableAlbumImageTakenNotification`, called from `nnMain` (`main+0x286268`). → [oe calls answered without an applet proxy](../reference/services.md#oe-calls-answered-without-an-applet-proxy) - abort in `nn::sm::Initialize` under `nn::oe::FinishStartupLogo`, right after the first frames. → [The startup logo](../reference/services.md#the-startup-logo) - null read in `oe::InitializeCopyrightFrameBuffer`, right after the window setup. → [Copyright frame buffer overlay](../reference/services.md#copyright-frame-buffer-overlay) - SDK 20 calls that reach a service, each one boot; SDK 20's `OpenAudioRenderer` aborts on an ARUID of 0. → [Applet resource user ID, launch parameters and VR mode](../reference/services.md#applet-resource-user-id-launch-parameters-and-vr-mode) - a null read in `sdk+0x35258` (apm's session) in `oe::IsCpuOverclockEnabled`, the first call in `nnMain`; null read at `sdk+0x362b8` (`apm::SetCpuOverclockEnabled`) in the first calls of `nnMain` (`main+0x2e1e4c`). → [CPU overclock calls without an apm session](../reference/services.md#cpu-overclock-calls-without-an-apm-session) - the game freezes after switching apps and back, picture still, sound on; the main loop waits in its pause handshake (`main+0x5d10d4` / `main+0x5cea68`). Mac repro `DM_OE_SCRIPT=bg=1@20,bg=0@25`. → [Focus handling mode decides whether focus changes are notified](../reference/services.md#focus-handling-mode-decides-whether-focus-changes-are-notified) - abort in `sm::Initialize` under `capsrv::InitializeForApplication` (`album::Initialize`); calls that reach the album service, found in the imports before they were met. → [Album calls fail with no album](../reference/services.md#album-calls-fail-with-no-album) - a null read at `sdk+0x336ccc` in `pdm::QueryApplicationPlayStatistics` (Pokémon Sword, the second boot); undefined `nn::account::` / `nn::friends::` imports with no hook, found from the import list (Listing a game's unhooked imports before they are met) before they were met. → [Account, friends, play data and Nintendo Account calls](../reference/services.md#account-friends-play-data-and-nintendo-account-calls) - the game ends right after `nnMain`, with a crash in its own cleanup on an object it had not created yet (DRAGON QUEST BUILDERS 2: `CRASH sig=11 addr=0x60db0` at `main+0x2676c8`, x0 = 0, the callers `main+0x85210` and `main+0x7fabf8`). No red line. → [Creating an ssl context needs no network](../reference/services.md#creating-an-ssl-context-needs-no-network) - `abort` under `grpc_init` at startup, with no red line: `game called nn::diag abort: Result 0, call site sdk+0xb8fe8`, backtrace `sdk+0xba138 sdk+0x7bd670 sdk+0x777f30 main+0x21f0c80`, just after `fs mount _npln:` (Ocarina of Time). → [`EventFd` needs no network](../reference/services.md#eventfd-needs-no-network) - `Break#1 reason=0 Result=0` right after the first save is created, then exit 42; the stack has `nn::diag::detail::OnAssertionFailure` under `nn::image::JpegDecoder::Decode` (`sdk+0x394e4`), called from the game (Burnout Paradise Remastered, SDK 9.3). → [The local user's profile image](../reference/services.md#the-local-users-profile-image) - `[RED] sf: the game connects to service mii:e … mii:u itself`, then an abort. → [Mii database answered by the host](../reference/services.md#mii-database-answered-by-the-host) - the abort with no message (`SVC 0x15` / `0x1f` / `0x21` placeholders, then `Break` with `sm::Finalize` under `ShopServiceAccessServer::Proxy::Initialize`) from `ec::InitializeForShopServiceAccessors`, called from Unreal's `FOnlineSubsystemSwitch::Init` at the start of `nnMain`. → [Shop service accessors](../reference/services.md#shop-service-accessors) - a purchase watcher crashes in `nn::ec::InitializePurchasedEvent` after account selection, before it can wait for a notification. → [Offline purchased-item notifications](../reference/services.md#offline-purchased-item-notifications) - abort in `nn::sm::Initialize` under `nn::pctl::IsFreeCommunicationAvailable` (Engage, entering its first battle map). → [Parental controls and free communication](../reference/services.md#parental-controls-and-free-communication) - play report calls met entering the save select (3D World); undefined `nn::ldn::` / `nn::socket::` imports with no hook, found from the import list before they were met (Big Brain Academy). → [Network interface, LDN, socket and play report calls](../reference/services.md#network-interface-ldn-socket-and-play-report-calls) - `[RED] sf: the game connects to service bsd:u itself, which the host does not serve` (and bsd:s, bsd:a) at the game's first socket call, then the game's own abort: Star Fox's `vsocket.nintendo.cpp:148` logs `socket: 4` and stops. With only the connection cut, the game's HTTP thread aborted a few seconds in: its event loop's `poll` returned -1 with errno 14 (EFAULT), and the loop tolerates only EINTR (`main+0xbe2efc4`). → [SDK 21 socket initialization and overloads](../reference/services.md#sdk-21-socket-initialization-and-overloads) - `[RED] sf: the game connects to service bt itself, which the host does not serve`, then `game called nn::diag abort` at `sdk+0x16ba48` and exit 134, a second after the audio renderer starts. With `bt` and `btm:u` served as zeroed host sessions the abort moves to `nn::btm::user::InitializeBtmUserInterface` (`sdk+0xb8eb4`), before either session gets a request. → [Bluetooth LE at boot](../reference/services.md#bluetooth-le-at-boot) - the boot sits at a black loading screen for good, CPU nearly idle, every thread waiting, about 1 boot in 6 (3 in 4 with four Mac hosts at once); the title movie is never opened, and the save files are never probed. → [Network requests stay on hold before they settle](../reference/services.md#network-requests-stay-on-hold-before-they-settle) - one thread at 100% CPU from boot, with one SVC in 99 s (`NexusRevolution Socket`, `main+0x92c7c4`, the game's network thread). → [Socket `Poll` and `Select` with nothing to wait on](../reference/services.md#socket-poll-and-select-with-nothing-to-wait-on) - the first comparison in `nnMain` aborted in `sm`. → [Language codes](../reference/services.md#language-codes) - `DM_LANG=zh-Hans` or `zh-Hant` reaches the game unchanged, but its startup menu falls back to Japanese; the older `zh-CN` or `zh-TW` spelling selects Chinese. → [Chinese language aliases in settings comparisons](../reference/services.md#chinese-language-aliases-in-settings-comparisons) - abort in `sm::Initialize` under `nn::settings::GetAvailableLanguageCodes` (early in `nnMain`, `main+0x327888`); abort in `sm::Initialize` under `nn::settings::GetAvailableLanguageCodeCount()` (`main+0x117590`). → [Available language codes and their count](../reference/services.md#available-language-codes-and-their-count) - the font engine runs on garbage; crash after the shared fonts load, looking up the "?" glyph (`main+0x6c73c0`, a font cache lookup returning null), with SDK 10's `ScalableFontEngine::LoadFont` failing with error 403 and `SetFont` with 301 on both stand-in fonts; or Japanese, Korean or Chinese text draws nothing in a Unity game while Latin text is fine (Patrick's Parabox's language menu showed three blank lines). → [Shared font address: BFTTF header or bare TTF](../reference/services.md#shared-font-address-bfttf-header-or-bare-ttf) - abort in `nn::sm::Initialize` under `nn::pl::sharedresource::GetPlatformSharedResourceManager` (first thing in `nnMain`). → [Shared fonts requested all at once](../reference/services.md#shared-fonts-requested-all-at-once) - `[RED] oe::ExecuteProgram(<n>, <k> bytes of parameters: …)`; before this entry, a crash right after that line (`sig=4` on a trap, or the next function running). A program started on its own quits at boot: it expects the launch parameter its launcher passes. → [Multi-program applications: `oe::ExecuteProgram`](../reference/services.md#multi-program-applications-oeexecuteprogram) - a null read in `applet::StartLibraryAppletImmediately` under `web::OfflineWebSession::Start` at boot; a game's pause menu, an offline page, never shows, or the game waits for a message from it. → [Offline HTML pages in a web view](../reference/services.md#offline-html-pages-in-a-web-view) - a crash in the font engine at boot with the null glyph, from a code point no message uses (`main+0x62d20` on 1.0.0, `main+0x63780` on 1.1.4); `?` in text for an icon the stand-in does not draw. → [Every undrawn extension code point is a ring](../reference/services.md#every-undrawn-extension-code-point-is-a-ring) - `nn::jit::Initialize` crashes reaching for the jit service (`sdk+0x2e5414`). → [`nn::jit` taken over by the host](../reference/services.md#nnjit-taken-over-by-the-host) - `[RED] jit::GenerateCode command <n>: request <key> … is not in the image …: capture it on the Mac (DM_JIT_CAPTURE) and rebuild the image`, then the game crashes there (the iPhone, or the Mac with `DM_JIT_SERVE`). → [`nn::jit` served from an image on iOS](../reference/services.md#nnjit-served-from-an-image-on-ios) - controller-button icons in text show as `?`. → [Nintendo-extension glyphs for button icons](../reference/services.md#nintendo-extension-glyphs-for-button-icons) - on a phone, `GetSharedFontLoadState` would report "not loaded". → [Shared fonts on iOS](../reference/services.md#shared-fonts-on-ios) - a crash after the shared fonts load, looking up the "?" glyph (`nro0+0xaef8a8`, a null pointer from nn::font's texture cache), with `ScalableFontEngine::LoadFont` returning 201 on one engine and 0 on another, and `SetFont` 301. → [A shared font larger than the game's font engine memory](../reference/services.md#a-shared-font-larger-than-the-games-font-engine-memory) - SDK calls that reach the time service, each aborting in `sm::Initialize` (or found in the imports before they were met). → [Steady clock, clock snapshots and user clocks](../reference/services.md#steady-clock-clock-snapshots-and-user-clocks) - a call the host answers reads as failed when it succeeded, or reads leftover register bits. Super Smash Bros. Ultimate refills the Spirit Board at every visit, since the elapsed time between two snapshots never reads as known. → [Hooks whose return type did not match the SDK](../reference/services.md#hooks-whose-return-type-did-not-match-the-sdk) - `std::terminate` (`Break` from `sdk+0x5bfa48`) at the first real-time read (right after the first-boot dialog, `main+0x3f3f68` → `system_clock::now()`). → [`clock_gettime(CLOCK_REALTIME)` through the time source pointer](../reference/services.md#clock_gettimeclock_realtime-through-the-time-source-pointer) - after switching apps and back, one guest thread at 100% in a tight loop (`main+0x9abd0`, `x10 = 0`); the game freezes, picture still, sound on. Mac repro `DM_OE_SCRIPT=bg=1@20,bg=0@25`. → [Guest clock reads wait while the app is in the background](../reference/services.md#guest-clock-reads-wait-while-the-app-is-in-the-background) - abort in `sm::Initialize` under `nn::crypto::GenerateCryptographicallyRandomBytes` (Unicorn Overlord: `std::random_device` → the `sdk`'s own `getentropy` → `InitializeCsrng`; Z-A: the first call in `nnMain`, `main+0x1734b4`). → [Cryptographically random bytes](../reference/services.md#cryptographically-random-bytes) - `libc++abi: terminating due to uncaught exception of type std::__1::system_error` (the arguments came out as rubbish, the format named the failure) once the game's own code ran, with `sdk+0x5f2e60` (`std::terminate`) and `sdk+0x66ad2c`/`sdk+0x66acc8` (`get_terminate`/`terminate`) in the backtrace. → [`clock_gettime` is `nn::time`'s steady clock (SDK 22)](../reference/services.md#clock_gettime-is-nntimes-steady-clock-sdk-22) - relocation repeatedly scans all HLE and forced-takeover entries, and named-stub reuse becomes quadratic as more imports are missing. → [Host symbol indexes avoid repeated name scans](../reference/services.md#host-symbol-indexes-avoid-repeated-name-scans) - a library's `free` rejects a pointer (`CentralHeap::Free` → `NotNMallocPtrError`). → [Global symbol resolution in load order](../reference/services.md#global-symbol-resolution-in-load-order) - a weakly imported function the game calls although nothing defines it: an `UNIMPL` line, then an abort. → [Undefined weak imports bind to 0](../reference/services.md#undefined-weak-imports-bind-to-0) - crash in `nn::ro::InitializeWithPortName`. → [`nn::ro` and its port](../reference/services.md#nnro-and-its-port) - the frame loop runs, but the game waits for code it loads itself (`ro::RegisterModuleInfo` / `ro::GetBufferSize` red lines; `main` imports 1,045 `lua2cpp::create_agent_*` functions, global, that no ExeFS module defines, bound to stubs at start). → [Loading NROs with `ro::LoadModule`](../reference/services.md#loading-nros-with-roloadmodule) - `FATAL .../nro.tsv: more NROs than module slots (MAX_MOD 128)` before `nnMain` (GitHub issue #372); after increasing the capacity, startup eagerly copies several GB of inactive NRO data and bss. → [NRO tables sized from the manifest and snapshots taken on demand](../reference/services.md#nro-tables-sized-from-the-manifest-and-snapshots-taken-on-demand) - `[EOS] Failed to create platform` (the game plays offline); `refused …: an online SDK (Epic Online Services), not loaded`; `refused an NRR that registers only online SDKs (1 hashes)`. → [Online SDKs in NROs are never loaded](../reference/services.md#online-sdks-in-nros-are-never-loaded) - `main` imports EGL (SDL3's GL support) and `vkGetInstanceProcAddr` (its Vulkan support), but the game renders with NVN (`FNA3D_Driver_NVN.cpp`). → [GPU driver modules that are never loaded](../reference/services.md#gpu-driver-modules-that-are-never-loaded) - `UNIMPL _ZN5movie12SetAllocatorEPFPvmmS0_EPFvS0_S0_EPFS0_S0_mS0_ES0_`, `UNIMPL glslcInitialize`, then `UNIMPL _ZN5movie9ExtractorC1ENS_13ContainerTypeE` and a crash reading address 0x18 in an NRO (`pc=nro18+0x97f4`) as the first movie starts. → [Modules only the NROs import from](../reference/services.md#modules-only-the-nros-import-from) - `[RED] ro::LookupModuleSymbol BuiltDebug: not defined in that module` once at boot; nothing goes wrong after it. → [`ro::LookupModuleSymbol` for a name the module does not define](../reference/services.md#rolookupmodulesymbol-for-a-name-the-module-does-not-define) - harmless on the build it was written for, silent memory corruption on any other. → [Code inherited from another title at fixed addresses](../reference/services.md#code-inherited-from-another-title-at-fixed-addresses) - an abort connecting to `pl:u` at boot; a failed `nn::audio` call at boot. → [Built-in fonts and the audio device notification of SDK 21](../reference/services.md#built-in-fonts-and-the-audio-device-notification-of-sdk-21) - an abort in `nn::hid` at boot, in a Switch 2 game that sets up the Joy-Con's mouse mode. → [The Joy-Con mouse pointer](../reference/services.md#the-joy-con-mouse-pointer) - a crash at boot in `nn::vi` under `nn::streamplay::CreateIndividualDisplays`. → [GameShare guest displays](../reference/services.md#gameshare-guest-displays) - `[RED] sf: the game connects to service chat:u itself, which the host does not serve`, then `game called nn::diag abort: Result 0xe15` under `nn::chat::Initialize`. → [GameChat at boot](../reference/services.md#gamechat-at-boot) - `CRASH sig=11 addr=0 pc=sdk+0x6be4d4` in `nn::chat::GetChattingUid()`, from the game's title screen code. → [GameChat queries from the title screen (SDK 21)](../reference/services.md#gamechat-queries-from-the-title-screen-sdk-21) - `nn::diag abort` in `gs::sdk::CheckGraphicsSystemInitialized`, or a failed `camera::sdk::CreateCameraContext` (0x3af3), at boot. → [The camera through the graphics system](../reference/services.md#the-camera-through-the-graphics-system) - with the camera session answering 0xdc4 to every command, Star Fox logs `This platform does not support the camera function.` (its `vwebcam.switch2.cpp:997`) and dereferences a null on the way out (`main+0xba54e4c`); with 0x7c4 to every command its module aborts in `Initialize` (subsdk3+0x1ef4) or `Finalize` (subsdk3+0x200c). → [The camera commands of SDK 21's own camera module](../reference/services.md#the-camera-commands-of-sdk-21s-own-camera-module) - a null read at boot in `nn::oe::IsLanguageSelectionLimited`, right after the game asks for its language. → [Whether the language selection is limited](../reference/services.md#whether-the-language-selection-is-limited) - a null read at boot in `nn::os::SdkMutexType` under `nn::gs::sdk::SetGraphicsFrameLengthMode`, called from `nn::oe::SetGraphicsTargetFrameRate`. → [The target frame rate (graphics frame length)](../reference/services.md#the-target-frame-rate-graphics-frame-length) - a Switch 2 game presents at 720p, with its upscaler at the matching low size. → [The display's largest buffer](../reference/services.md#the-displays-largest-buffer) - `registered NROs not found` from `nro_collect.py` in a game whose RomFS has an NRR, or `[RED] ro::LoadModule: no rewritten NRO with SHA-256 …`. `main` is small (about 600 KB of code) beside a data segment of random-looking bytes. → [A game that decodes its code at run time](../reference/services.md#a-game-that-decodes-its-code-at-run-time) - a crash in `ro::RegisterModuleInfo`, or an NRR that seems to register millions of hashes: the words at +0x340 and +0x344 are random. → [NRR version 1](../reference/services.md#nrr-version-1) ## Movies - abort in NVIDIA's video path (`NvRmChannelOpen` → `NvOsDrvOpen`). → [The SDK's hardware decoder opens nvdrv](../reference/movies.md#the-sdks-hardware-decoder-opens-nvdrv) - constructing a movie decoder aborts with `FATAL movie: missing SDK symbol _ZNK5movie6Buffer4DataEv`. → [SDK 1 movie buffer getters](../reference/movies.md#sdk-1-movie-buffer-getters) - the game waits forever at a movie (Engage's 94 s opening `S01F.webm`; frames keep presenting, nothing happens). → [`movie::Decoder` taken over as a MediaCodec-style protocol](../reference/movies.md#moviedecoder-taken-over-as-a-mediacodec-style-protocol) - a movie in grey with vertical bands of colour, its luma sharp; or a read far outside guest memory at `main+0x344f74` on the first movie picture (CRI Sofdec2's NV12 → RGB conversion). → [Output format keys (`md_format`)](../reference/movies.md#output-format-keys-md_format) - a movie decodes and its sound plays, but the picture is black: `DM_MOVIE_TRACE=1` shows pictures coming out, the pass dump shows the two planes uploaded and one quad drawn, and the uniform block of the conversion shader (`DM_NVN_CBDUMP`) is all zeros. → [`nv12-colorspace` picks the game's YUV matrix](../reference/movies.md#nv12-colorspace-picks-the-games-yuv-matrix) - a call through a null pointer in the host's `movie::Decoder::Configure` right after `nnMain` starts the logos. → [SDK 4's `movie::Decoder` constructor without a priority](../reference/movies.md#sdk-4s-moviedecoder-constructor-without-a-priority) - a call through a null pointer in the host's `movie::Decoder::Configure` (`pc=0 lr=h_movie_Configure+…`) when the first movie starts; with only the constructor taken over, `[RED] movie: decoder type 1 output 3 mode 1 not supported by the host`. → [SDK 3's `movie::Decoder` constructor takes a type and a format only](../reference/movies.md#sdk-3s-moviedecoder-constructor-takes-a-type-and-a-format-only) - `CRASH sig=11 addr=0 pc=0` with `lr=h_movie_Configure+…`, as the first movie starts. → [The base-object constructors of `movie::Decoder`](../reference/movies.md#the-base-object-constructors-of-moviedecoder) - the first deferred signal crashed in `InternalCriticalSectionImplByHorizon::Enter` (DRAGON QUEST XI S). → [Client events read through the registered pointer](../reference/movies.md#client-events-read-through-the-registered-pointer) - a crash reading address 0 at `main+0xab4e18` right after `[movie] Stop` and `decoder … destroyed`, at the first skip of the intro movie or the first menu change (Mario Strikers: Battle League; `MoviePlayerWorker` in the thread dump). → [Video decoded off the caller's thread](../reference/movies.md#video-decoded-off-the-callers-thread) - the process dies when an activity starts, 2 runs in 5, with no `CRASH` line: the run ends with exit 137 (SIGKILL), and `~/Library/Logs/DiagnosticReports/dmhost-*.ips` has `EXC_BREAKPOINT` in `_os_unfair_lock_corruption_abort` ← `pthread_mutex_destroy` ← `md_free` (the movie decoder's destructor). → [Input indices returned by a flush while a client holds them](../reference/movies.md#input-indices-returned-by-a-flush-while-a-client-holds-them) - when the prologue movie was skipped, 2.25 GB were mapped within seconds, past the application pool, and the game crashed in its allocator (DRAGON QUEST XI S). → [End of stream is the last input until `Flush` or `Stop`](../reference/movies.md#end-of-stream-is-the-last-input-until-flush-or-stop) - decoding the end-of-stream packet gave VideoToolbox −12909 and AudioToolbox −50. → [End-of-stream packets with no data, and deleted decoders](../reference/movies.md#end-of-stream-packets-with-no-data-and-deleted-decoders) - the game never leaves a movie that has played to its end; the last picture stays on screen. → [H.264 drain at the end of a stream goes on with released slots](../reference/movies.md#h264-drain-at-the-end-of-a-stream-goes-on-with-released-slots) - a looping tutorial loses B-frame presentation order after the first loop, without a `Flush` or end-of-stream packet. → [H.264 loops retain presentation order when timestamps restart](../reference/movies.md#h264-loops-retain-presentation-order-when-timestamps-restart) - an anime or story movie ends on a black screen; the pause menu still works and skipping lets the game continue. → [No picture carries the end-of-stream flag](../reference/movies.md#no-picture-carries-the-end-of-stream-flag) - the opening movie never starts, in about half the boots (DRAGON QUEST XI S: a black screen and no sound from boot on). → [Audio decoders keep more outputs than a pre-decoding player fills](../reference/movies.md#audio-decoders-keep-more-outputs-than-a-pre-decoding-player-fills) - a movie stays black after its first picture, the sound never starts, and the game keeps presenting frames. → [Audio output slots for players that hold every output](../reference/movies.md#audio-output-slots-for-players-that-hold-every-output) - a movie shows as a black screen with the loading icon, one picture every few seconds, while its sound decoder keeps up. → [Video output slots: how far the extractor gets ahead](../reference/movies.md#video-output-slots-how-far-the-extractor-gets-ahead) - a crash in the game's heap free (`sead::ExpHeap`) on a movie thread, a second into the first movie, at the same address every boot (`pc=main+0x42f980`, a free-list unlink through a link of 0x3f, `addr=0x47`). → [AAC decoders offer at most 32 outputs](../reference/movies.md#aac-decoders-offer-at-most-32-outputs) - the movie then froze on its first second, its sound decoder full and the game taking no more audio. → [AAC output buffer size is one frame](../reference/movies.md#aac-output-buffer-size-is-one-frame) - `FATAL movie: missing SDK symbol _ZNK5movie6Buffer10GetNvnSyncEv` at the first frame of the native-texture movie (H.264 into the game's RGBA texture, as in Monster Hunter Rise). → [SDK 4's `movie::Buffer` has no sync object](../reference/movies.md#sdk-4s-moviebuffer-has-no-sync-object) - a native-texture movie shows as a strip of small grey copies at the top of the screen. → [Parameter sets in `Configure` made the H.264 decoder without RGBA](../reference/movies.md#parameter-sets-in-configure-made-the-h264-decoder-without-rgba) - looping movie previews flash black at the end of every loop. → [Last picture kept across a flush and at end of stream](../reference/movies.md#last-picture-kept-across-a-flush-and-at-end-of-stream) - a native-texture movie freezes on its 16th picture while the game keeps running; `DM_MOVIE_TRACE=1` shows 16 `AcquireOutputBufferIndex` / `GetOutputBuffer` pairs and no `ReleaseOutputBufferIndex`. → [`GetOutputBuffer` returns the output index in native-texture mode](../reference/movies.md#getoutputbuffer-returns-the-output-index-in-native-texture-mode) - a native-texture movie jumps ahead for one picture and returns: every 17 pictures, each exactly 16 ahead (one cycle of the video output slots), the picture before it never shown. Text burnt into the movie shows the line being typed half a second later for one frame. → [A native-texture movie shows a picture 16 frames ahead, then goes back](../reference/movies.md#a-native-texture-movie-shows-a-picture-16-frames-ahead-then-goes-back) - `[RED] movie: client texture format 0x9a is not RGBA8 / RGBX8 (sRGB included), writing in RGBA byte order`; a native-texture movie plays in the wrong colours, warm lamps blue. → [A BGRA8 client texture gets its movie with red and blue swapped](../reference/movies.md#a-bgra8-client-texture-gets-its-movie-with-red-and-blue-swapped) - the game crashed on a null right after the failed open. → [`movie::Extractor` runs natively](../reference/movies.md#movieextractor-runs-natively) - VP8 WebM movies play black; `movie::Decoder` is created with decoder type 2. → [VP8 uses the same libvpx worker and output paths](../reference/movies.md#vp8-uses-the-same-libvpx-worker-and-output-paths) - a movie with a Vorbis track starts clean, then crackles and stutters. The log has no underrun and no red line, and with `DM_AUDIO_DUMP` the game's mix has exact zeros in whole 512-sample blocks (mostly one or two at a time, 11 to 21 ms). → [Vorbis output lengths at a window change](../reference/movies.md#vorbis-output-lengths-at-a-window-change) - a movie with a Vorbis track plays its first seconds with sound; after the game flushes and restarts it (a seek, a loop, or the app losing and regaining focus) the picture goes on but the sound does not come back, for the rest of the movie. The log shows `[movie] Flush`, `Flush`, `Start`, `Start` and no more `GetOutputBuffer … → PCM` lines. With `DM_AUDIO_DUMP`, the game's mix is real audio up to the flush and exact zeros from then on, so the AudioUnit is not at fault (0 underruns). → [Vorbis sound stops for good after a Flush](../reference/movies.md#vorbis-sound-stops-for-good-after-a-flush) - a Switch 2 game crashes when a movie starts: `nn::codec::video::Initialize` faults in the SDK (Donkey Kong Bananza: `sdk+0x2de99c`, after its first punch, when the guide movie starts), and before that `nv::InitCheck` aborts (`hle_nv.c`). Later, when a second movie starts: `game called nn::diag abort: Result 0` in `nn::os::ClearSystemEvent` or `TryWaitSystemEvent` on the decoder's event. → [`nn::codec` video decoders taken over](../reference/movies.md#nncodec-video-decoders-taken-over) - a movie stays black with the game waiting behind it, the decoder made and no `first picture` line (`Submit…InputBuffer` never called). Or `[RED] nn::codec VP9: Corrupt frame detected`, then `Keyframe / intra-only frame required`, each time about 6 s into a movie or after skipping in one. → [The submission-ready event counted as packets](../reference/movies.md#the-submission-ready-event-counted-as-packets) - a crash in `nn::codec::video::InitializeAv1DecoderByTransferMemory` when a movie starts. → [AV1 movies through SDK 22's decoder](../reference/movies.md#av1-movies-through-sdk-22s-decoder) - an abort in `nn::codec` (the SDK's own decoder client, which opens a service the host does not have) when a movie starts in a game built with SDK 19 for the Switch 2. → [SDK 19's decoder forms](../reference/movies.md#sdk-19s-decoder-forms) ## Audio - abort with Result 0x499 in `audio::GetAudioRendererWorkBufferSize`. → [SDK 8's longer `AudioRendererParameter`](../reference/audio.md#sdk-8s-longer-audiorendererparameter) - the game is silent; only the game's updates render (catch-up frames that nothing plays). The log has `audren: OpenAudioRenderer (no event)` and no `render thread started`. → [A renderer opened without an event](../reference/audio.md#a-renderer-opened-without-an-event) - `[RED] audren: a second renderer (the host drives only one)` with different parameters from the first open; later, `catch-up renders so far` in the thousands (7,625 in 6 minutes), about 10% of the first renderer's frames. → [A game with more than one renderer](../reference/audio.md#a-game-with-more-than-one-renderer) - with two renderers open, one plays single 5 ms frames between silences and its sound effects are missing, while the other has an occasional all-zero 5 ms block; no underrun and no `[RED]` line, and the AudioOut `appended` and `released` counts stay balanced. Cross-correlating the outputs finds one renderer's waveform on the other. → [Two renderers overwriting each other's queued blocks](../reference/audio.md#two-renderers-overwriting-each-others-queued-blocks) - `audren: OpenAudioRenderer` logged twice right after the first open, with the same work buffer and "original device 1 mode 1", and a second render thread (until 2026-11-04 the second log line was `[RED] audren: a second renderer`, which now means more than one renderer). → [The SDK's open with an event calls the open without one (`t_in_open`)](../reference/audio.md#the-sdks-open-with-an-event-calls-the-open-without-one-t_in_open) - the frame loop stops for good as a level loads while audio keeps rendering. The main thread waits in `os::WaitSystemEvent` under `CAudioMemoryPool::Shutdown`, and a sound thread of higher priority waits on the same condition variable. → [The renderer event as the service gives it: a kernel event](../reference/audio.md#the-renderer-event-as-the-service-gives-it-a-kernel-event) - the game exits with 42 on its first rendered audio frame: `Break#1 reason=0` in `os::SignalSystemEvent`, called from the public `ExecuteAudioRendererRendering` on the host's render thread (`render_main`). → [The renderer event belongs to the renderer, not the game](../reference/audio.md#the-renderer-event-belongs-to-the-renderer-not-the-game) - none of its own; command generation races the game's `Update` on SDKs whose lock is not at SDK 16's offset. → [The renderer's update lock (`update_lock`)](../reference/audio.md#the-renderers-update-lock-update_lock) - `FATAL audren: missing SDK symbol _ZN2nn2os12SdkMutexType4LockEv` right after the renderer's render thread starts. → [No `SdkMutexType` in SDK 3](../reference/audio.md#no-sdkmutextype-in-sdk-3) - the sound is choppy: about two of every three 5 ms blocks are silent (a `DM_AUDIO_DUMP`), with no underruns. The log's `catch-up renders so far` grows by one for each rendered frame (2000 of every 2000), and every update logs `no frame rendered before update N`. → [Where the `AudioRenderSystem` sits in `AudioRendererImpl`](../reference/audio.md#where-the-audiorendersystem-sits-in-audiorendererimpl) - `CommandListProcessor::Process` crashes now and then (SIGSEGV under `render_main`, once at 60 s and once at 134 s in the shrine); every `RequestUpdate` renders a catch-up frame. → [The render thread's route through the public `ExecuteAudioRendererRendering` (SDK 20)](../reference/audio.md#the-render-threads-route-through-the-public-executeaudiorendererrendering-sdk-20) - SIGSEGV at address 0x18 in `UpsamplerManager::Allocate` on the render thread. → [A renderer below 48 kHz with no upsampler on the CPU](../reference/audio.md#a-renderer-below-48-khz-with-no-upsampler-on-the-cpu) - the main thread spins at start-up in a resource wait (a `YieldThread` loop, no crash), right after `OpenAudioRenderer`. → [A sound engine's heap too small for its renderer and players](../reference/audio.md#a-sound-engines-heap-too-small-for-its-renderer-and-players) - no sound after boot; `audren: no DeviceSink (ID 0x13) in the command list` and a malformed-command error persist even when later command lists are valid. → [Incomplete startup lists must not select the command layout](../reference/audio.md#incomplete-startup-lists-must-not-select-the-command-layout) - ASan reports a stack-buffer-overflow in `capture` while logging the first full command histogram; a malformed list can also consume sink discovery or return PCM before its invalid tail is checked. → [Malformed later command lists and bounded histogram logging](../reference/audio.md#malformed-later-command-lists-and-bounded-histogram-logging) - the CPU processor drops the final mix. → [The final mix is taken from the DeviceSink's mix buffers](../reference/audio.md#the-final-mix-is-taken-from-the-devicesinks-mix-buffers) - no sound: `[RED] audren: no DeviceSink (ID 0x10) in the command list, 0 commands of 0x148 bytes`. → [SDK 4: DeviceSink is command 0xf of 0x130 bytes](../reference/audio.md#sdk-4-devicesink-is-command-0xf-of-0x130-bytes) - no sound; red `audren: command 1 in the command list is malformed (magic 0 size 0)`. → [SDK 6: the DSP command header layout](../reference/audio.md#sdk-6-the-dsp-command-header-layout) - no sound: `[RED] audren: no DeviceSink (ID 0x13) in the command list, 0 commands of 0x148 bytes` and `[RED] audren: command 2 in the command list is malformed (offset 0x3e, …)`, with `first-frame commands 13, by command ID: 0×2`. → [SDK 5: a startup list that walks in two layouts, and a 0x138-byte DeviceSink](../reference/audio.md#sdk-5-a-startup-list-that-walks-in-two-layouts-and-a-0x138-byte-devicesink) - UBSan reports a misaligned `uint32_t` load in `cmd_ok` while `t_audren_layout` probes SDK 4/6 lists (issue #409). → [Unaligned command headers during layout probing](../reference/audio.md#unaligned-command-headers-during-layout-probing) - no music and no sound effects, only the movies' sound (the log repeats `audren: first-frame commands …` every frame and never prints `DeviceSink inputs`). → [SDK 8: command IDs numbered differently](../reference/audio.md#sdk-8-command-ids-numbered-differently) - `CRASH sig=11 addr=0x20` at `nn::audio::server::AddressInfo::GetReference` (`sdk+0x249874`) on the render thread, under `CommandGenerator::GenerateDataSourceCommand` and `render_once`, minutes into a movie. The `AddressInfo` the crash register points at is all zeros, though the function had just read a non-null memory pool pointer from it. Or `[RED] audren: no update lock read off AudioRenderSystem::Update or UpdateImpl`, on an SDK whose code the scan does not recognize. → [The update lock read off `UpdateImpl`](../reference/audio.md#the-update-lock-read-off-updateimpl) - no sound; red `audren: command 0 in the command list is malformed (first word 0x181901 size 0)`. → [SDK 21 DSP command header without a magic](../reference/audio.md#sdk-21-dsp-command-header-without-a-magic) - RealtimeSanitizer reports stdio locking in `au_render` at its 2,000-callback diagnostic boundary. A busy log writer can block that callback even when its PCM queue is full. → [Periodic diagnostics outside the AudioUnit callback](../reference/audio.md#periodic-diagnostics-outside-the-audiounit-callback) - PCM is consumed correctly and its buffer reaches the released queue, but the guest release event never arrives. The notifier is asleep with `notify_pending=1` and `notify_armed=0`. → [AudioOut release notification can sleep with pending work](../reference/audio.md#audioout-release-notification-can-sleep-with-pending-work) - FMOD waits for buffer release after stopping an AudioOut, hanging the game during a scene transition. → [Stopping an AudioOut releases its pending buffers](../reference/audio.md#stopping-an-audioout-releases-its-pending-buffers) - crackling on iOS only. → [RemoteIO's default I/O buffer duration](../reference/audio.md#remoteios-default-io-buffer-duration) - clicks and dropouts on the Mac, heard as clipping; the log's `audio #N device callbacks` lines show hundreds of underruns per 2000 callbacks. Closing an output can also log `[RED] audio device buffer: ... (status 560947818)` (`!obj`). → [The Mac's default I/O buffer](../reference/audio.md#the-macs-default-io-buffer) - a game is silent on an iPhone whose ring / silent switch is set to silent, though the volume is up; a game or video app plays through the switch. → [The ring / silent switch muted the game on iOS](../reference/audio.md#the-ring--silent-switch-muted-the-game-on-ios) - sound stays silent after Siri, an alarm, a call or another app's audio; a game whose audio thread waits for its buffers back (Wwise's poll-only output, FMOD) then waits forever. → [Interruptions that stop RemoteIO callbacks](../reference/audio.md#interruptions-that-stop-remoteio-callbacks) - a game stops advancing while the Mac's selected output refuses to play. A process sample shows `AudioOutputUnitStart` waiting in the HAL, with the game's audio renderer waiting for a released PCM buffer. → [A blocked audio device start freezes the game](../reference/audio.md#a-blocked-audio-device-start-freezes-the-game) - TSan reports `au_create` writing `a->au` while `au_watchdog` reads it under `g_aos_lock` when a second real output opens (issue #410). → [AudioUnit construction before output publication](../reference/audio.md#audiounit-construction-before-output-publication) - combined numbers mislead: one fully fed output plus one fed by nobody look like "every other callback underruns, 2.0 blocks queued". → [Several outputs at once (`audio #N`)](../reference/audio.md#several-outputs-at-once-audio-n) - a null read at `sdk+0x1f2314` as the first movie starts (the title menu's background, right after the first press), in `nn::audio::SetAudioOutVolume`, called from `main+0x1c4fbc`. → [AudioOut volume kept per output](../reference/audio.md#audioout-volume-kept-per-output) - a null read in `audio::GetAudioOutBufferCount` on Wwise's sink wakeup thread (`sdk+0x1e7ed0`, from `main+0x30faae8`). → [AudioOut buffer count from the host queue](../reference/audio.md#audioout-buffer-count-from-the-host-queue) - an abort in `sm::Initialize` under `audio::GetAudioDeviceOutputVolume` (the game thread, `main+0xee8edc`). → [Audio device output volume and names](../reference/audio.md#audio-device-output-volume-and-names) - an `nn::diag` abort with Result 0xe15 on an audio thread at start, in `audio::CreateUserClientSessionByHipc` under `audio::AcquireAudioOutputDeviceNotification`, after the line `sf: the game connects to service aud:u itself`. → [The output device notification under its SDK 21 and 22 name](../reference/audio.md#the-output-device-notification-under-its-sdk-21-and-22-name) - SDL3's audio driver lists the input devices (AudioIn) when its audio starts. `[RED] sf: the game connects to service audren:u itself`, then `nn::diag abort: Result 0xe15` under `audio::AcquireAudioDeviceNotificationForInput` (`sdk+0x5633c`). → [No audio input devices](../reference/audio.md#no-audio-input-devices) - `[RED] sf: the game connects to service auddmg:u itself, which the host does not serve`, then `game called nn::diag abort: Result 0xa99` at `sdk+0x1f61ac` under `audio::ListVirtualInputDevices`. → [No virtual audio input devices (SDK 22)](../reference/audio.md#no-virtual-audio-input-devices-sdk-22) - `game called nn::diag abort: Result 0xe15, call site sdk+0x1f8704`, i.e. inside `nn::audio::CreateAudioOutManagerByHipc+0xb4`, before any audio device opened. → [`OpenAudioOut` without a release event (SDK 22)](../reference/audio.md#openaudioout-without-a-release-event-sdk-22) - `[RED] sf: the game connects to service auddmg:u itself, which the host does not serve`, then `game called nn::diag abort: Result 0xa99` under `nn::audio::GetDefaultVirtualOutputDevice` (`sdk+0x221520`, `audio::detail::GetVirtualOutputDeviceProperties`). → [SDK 21's OutputStream on a virtual output device](../reference/audio.md#sdk-21s-outputstream-on-a-virtual-output-device) - an abort in `sm::Initialize` under the hardware Opus decoder's C interface; for the multi-stream one, under `nn::codec::GetHardwareOpusMultiStreamDecoderWorkBufferSize(int, int, int, int, int)` (at `nnMain`, CRI's Opus streams). An abort in `sf::hipc::InitializeHipcServiceResolution` under `codec::GetHardwareOpusDecoderWorkBufferSize(int, int)` (`main+0x31f8e8`, early in `nnMain`). A game that builds `HardwareOpusMultiStreamDecoder` with the imported constructor and then calls it through its vtable. → [Hardware Opus decoders built on the SDK's software decoders](../reference/audio.md#hardware-opus-decoders-built-on-the-sdks-software-decoders) - `game called nn::diag abort: Result 0xe15` under `nn::codec::GetHardwareOpusDecoderManagerWorkBufferSize` (`sdk+0x323180`), the game's sound setup. → [SDK 21's hardware Opus decoder manager](../reference/audio.md#sdk-21s-hardware-opus-decoder-manager) - `CRASH sig=11 addr=0` in `h_codec_HwOpusFini`, the first time the game finalizes a decoder. → [One key for the two forms of the Opus decoder](../reference/audio.md#one-key-for-the-two-forms-of-the-opus-decoder) - the light limiter crashed on a null state pointer (`ApplyLightLimiterEffect`, `sdk+0x228494`). → [At least one rendered frame between two updates](../reference/audio.md#at-least-one-rendered-frame-between-two-updates) - the sound runs about 50 times faster than the output; the loop runs 11,000 updates a second on one core. → [A sound driver that never waits on the renderer event](../reference/audio.md#a-sound-driver-that-never-waits-on-the-renderer-event) ## Frame rate - clang reports division by zero in `fstep_tick` (`hle_nvn.c`). → [Frame cap checked and used from the same sample](../reference/frame-rate.md#frame-cap-checked-and-used-from-the-same-sample) - a 30 fps game to run at 60; after the floor was lowered, slow motion on a GPU-bound device (GitHub issue #9). → [sead's dynamic present interval, `ksys::VFR` and the host's frame step](../reference/frame-rate.md#seads-dynamic-present-interval-ksysvfr-and-the-hosts-frame-step) - `scripts/regress.py` reports a hang (`no frame after … s`, a state dump with every game thread waiting) in some runs of Tears of the Kingdom, baseline and candidate alike; the log's last focus line before it is `oe focus state → 2`, with no `→ 1` after it. → [A regress run stops when another app takes the key window](../reference/frame-rate.md#a-regress-run-stops-when-another-app-takes-the-key-window) - otherwise stationary gameplay benchmarks show roughly 125–135 ms frame spikes at their verification screenshots; adaptive-cap results vary between runs. → [Benchmark captures perturb the measured frame pacing](../reference/frame-rate.md#benchmark-captures-perturb-the-measured-frame-pacing) - on an iPhone, a game with the frame step at 60 fps drops a frame in most windows after a few minutes, and its GPU time per frame roughly doubles to triples (17-26 ms for the same scenes). → [A thermally serious iPhone holds 30 fps](../reference/frame-rate.md#a-thermally-serious-iphone-holds-30-fps) - in a game the host steps at 60 fps (`FRAME_STEP`), a prerendered movie plays at twice its speed, its sound falls behind, and the frame counter shows 60 during it. The log has `[movie]` lines with pictures 33 ms apart (`time 0 / 33000 / 67000 µs`) and no `frame step cap 60 → 30` at the movie. → [Movies hold 30 fps under the frame step](../reference/frame-rate.md#movies-hold-30-fps-under-the-frame-step) - after a 30 fps cap ends (a prerendered movie, the thermal cap), a GPU-bound game stays at 30 fps in a scene that held 60 before the cap; the log shows `frame step cap 30 → 60 fps` and a few frames later `frame step: hold 1 → 2 vsyncs at present … (3 late frames; …)`, with no probe after it. → [The frame step after a 30 fps cap ends](../reference/frame-rate.md#the-frame-step-after-a-30-fps-cap-ends) - on a Mac, a GPU-bound game at 60 fps falls to 30 or 20 fps when the scene gets heavier and stays there until a menu or a lighter scene, while the GPU clock sits at its floor (338–400 MHz on an M5 Pro) and the GPU is powered 60–75% of the time; the log shows probes back to hold 1 that fail after about 33 frames (`frame step: hold 2 → 1 vsyncs … (probe, GPU 1.67× its time at hold 1)` then `the probe failed`), and the host's profiler (`@gpu_mhz`) shows the clock rising during each probe and falling back after it. → [A probe's grace lasts while its frames keep getting cheaper](../reference/frame-rate.md#a-probes-grace-lasts-while-its-frames-keep-getting-cheaper) - a game whose profile has a frame step (`FRAME_STEP` in its `patches.py`) runs at double speed when packed from another update; the log has no `frame step in whole vsyncs` line, and the frame counter shows 60. → [A derived profile drops the frame step its build lacks](../reference/frame-rate.md#a-derived-profile-drops-the-frame-step-its-build-lacks) - a fixed-step game runs at double speed (or slow motion at 30) after `DM_FPS_TARGET` is set, in `Documents/env.txt` or the launcher, on a build its profile's frame step stubs and limiter rows do not know. → [A present cap applies only with a frame step or an engine limit the host writes](../reference/frame-rate.md#a-present-cap-applies-only-with-a-frame-step-or-an-engine-limit-the-host-writes) - selecting 30 FPS changes the engine's interval field, but the screen and frame loop still run near 60 FPS. → [Engine-native frame caps also govern presentation](../reference/frame-rate.md#engine-native-frame-caps-also-govern-presentation) - the game always renders at full resolution, or turning off dynamic resolution still allows the native controller to lower it. → [Resolution policy is independent of the frame-rate cap](../reference/frame-rate.md#resolution-policy-is-independent-of-the-frame-rate-cap) - slow motion when the GPU is the bottleneck: a game's interval controller that times the GPU never steps up (GitHub issue #9). → [GPU timestamps per submission segment](../reference/frame-rate.md#gpu-timestamps-per-submission-segment) - GPU time reads 32 times too small when a game converts raw NVN counter timestamps itself. → [Raw NVN timestamp units](../reference/frame-rate.md#raw-nvn-timestamp-units) - a Switch 2 game holds 20 or 30 fps on the Mac although its frame work fits in one vsync: its frame-rate controller raises the present interval (`the game sets present interval 1 → 3` in the log) and never steps back down. → [The Switch 2's system tick is 31.25 MHz](../reference/frame-rate.md#the-switch-2s-system-tick-is-3125-mhz) - menus reach 60 fps with `present_interval display`, but entering gameplay returns to 30 fps despite spare GPU time. → [Unity's integer target frame rate](../reference/frame-rate.md#unitys-integer-target-frame-rate) - the game presents at interval 1, yet every frame takes exactly 33.3 ms of "frame work"; after only the limiter was raised, everything ran twice as fast on the iPhone. → [A render-thread limiter with a constant and a fixed time step](../reference/frame-rate.md#a-render-thread-limiter-with-a-constant-and-a-fixed-time-step) - 55 fps with every frame 18.2 ms, the main thread asleep most of the time; every 11th frame stays on screen two vsyncs. → [A frame-end wait polled in 2 ms sleeps](../reference/frame-rate.md#a-frame-end-wait-polled-in-2-ms-sleeps) - a Switch 2 game runs its title and menus at 60 fps and its gameplay at 30, asking for present interval 2, with the GPU mostly idle. → [A target frame rate the game steps by](../reference/frame-rate.md#a-target-frame-rate-the-game-steps-by) - with a game's target frame rate written to 120 and a 120 Hz display link, the game holds 120 where frames fit, but a scene whose frames take 14 ms runs in slow motion at 72 fps, and on a 60 Hz screen the whole game runs at half speed. → [120 fps follows the frame step](../reference/frame-rate.md#120-fps-follows-the-frame-step) - an Unreal Engine game holds 30 fps with spare CPU and GPU time and asks for present interval 2; `present_interval display` alone does not help, as the engine's game thread sleeps out its own frame limit. → [Unreal's frame limit and present interval, found by name](../reference/frame-rate.md#unreals-frame-limit-and-present-interval-found-by-name) - a Frostbite game holds 30 fps with spare CPU and GPU time. Raising only the frame limit and the present interval gives 60 frames a second with the game at half speed (the match clock at 3.6 game seconds a second instead of 7.5). → [Frostbite's simulation rate, found by name](../reference/frame-rate.md#frostbites-simulation-rate-found-by-name) - the app is active and the game keeps running, but the picture freezes while display-link callbacks stop; the log repeatedly drops queued frames. → [Present thread rescues a silent display link](../reference/frame-rate.md#present-thread-rescues-a-silent-display-link) - `[longframe]` lines of 40–180 ms with no new pipelines, a short submit and normal GPU time, which read like CPU hitches in the game: single frames of 60–100 ms, or bursts of 5–12 frames, one of 140–180 ms and the rest about 40 ms. → [Long frames a test run makes itself](../reference/frame-rate.md#long-frames-a-test-run-makes-itself) - with the display link driving presents, a presented frame comes out black when three presents are on the GPU at once, or two after a dropped frame; on an M6 the same reuse also logs `[RED] display command buffer error` with `kIOGPUCommandBufferCallbackErrorPageFault`. → [A present command allocator is reused only after its own present completes](../reference/frame-rate.md#a-present-command-allocator-is-reused-only-after-its-own-present-completes) - "sometimes the speed increases when jumping" (Mario 1.2.1 on the iPhone): in `display` mode interval-2 frames were shown for 16.7 ms and the game visibly jumped ahead. "When pressing B, Link's move pace is speeding up" (Breath of the Wild on the iPhone); `old frames dropped by merging`. → [Frames of a dynamic present interval held on screen and at the acquire](../reference/frame-rate.md#frames-of-a-dynamic-present-interval-held-on-screen-and-at-the-acquire) - Donkey Kong Bananza ran its heavy areas at 15 fps where its GPU took about 46 ms a frame: the frames came every 66.7 ms, and the presentation thread spent 85% of its time in `nvnWindowAcquireTexture` waiting for display-link ticks. → [Odd present intervals on the 30 Hz display link](../reference/frame-rate.md#odd-present-intervals-on-the-30-hz-display-link) - with `present_interval display`, `DM_PRESENT_HZ=120` and `DM_PRESENT_LINK=2` (a 120 Hz display link) a game stays at 60 fps although its frame takes 8 ms; the display link logs about two ticks per present. With a requested 90 Hz, truncating the tick conversion instead allows 120 fps (reproduced through the real acquire with simulated link ticks). → [One frame per tick of a 120 Hz display link](../reference/frame-rate.md#one-frame-per-tick-of-a-120-hz-display-link) - frames miss the screen while the GPU stays at its lowest clock (444 MHz on an M2 Max); more work (a higher render scale) only makes the frames slower. → [Present snapshots: the game's swapchain texture free at once](../reference/frame-rate.md#present-snapshots-the-games-swapchain-texture-free-at-once) - none seen in a game. When the presented texture changes size or format while snapshots are on, a display command buffer still queued could sample the ring slot's old texture outside the residency set, which faults the queue (`kIOGPUCommandBufferCallbackErrorPageFault`, then every later command buffer ignored), as in A present snapshot's copy needs the same residency commit. → [A replaced snapshot ring texture stays resident until the slot's next use](../reference/frame-rate.md#a-replaced-snapshot-ring-texture-stays-resident-until-the-slots-next-use) - a steady game whose frame-rate counter wanders between 50 and 60 on the iPhone only; the `display link up to tick` lines show about as many empty ticks as frames dropped by merging: frames arrive two in one tick and none in the next. → [Vulkan acquire and vsync event follow the display link](../reference/frame-rate.md#vulkan-acquire-and-vsync-event-follow-the-display-link) - a `regress.py` run of an NVN game stays at 20 fps from the start (`frame N not reached`, a NEW-FAIL) in some runs only: `frame step: hold 1 → 2` and `2 → 3 vsyncs` in the first 15 presents, then `display link recovered: stalled 1017 ms` about once a second to the end, and no trial back to a shorter hold. → [A game window another process starts opens behind other windows](../reference/frame-rate.md#a-game-window-another-process-starts-opens-behind-other-windows) - asked for 60 Hz, the system fires the display link on every third refresh of a 165 Hz screen, 55 Hz, so games paced by it ran at 55 fps (27.5 at 30). → [Virtual 60 Hz ticks on screens that are not a multiple of 60](../reference/frame-rate.md#virtual-60-hz-ticks-on-screens-that-are-not-a-multiple-of-60) - virtual ticks keep the average, but a frame still stays up two or three refreshes in turn (13.9 / 20.8 ms at 144 Hz), and Apple's HUD showed the frame interval jumping between them. → [Fullscreen switches the screen to a rate the frame rate divides](../reference/frame-rate.md#fullscreen-switches-the-screen-to-a-rate-the-frame-rate-divides) - a Mac game in fullscreen holds 60 fps for 45 s to 3 minutes, then the same work takes about twice the GPU time (Tears of the Kingdom 10.5 → 19.7 ms) and the frame step falls to 30 fps. `powermetrics` shows the GPU at its lowest clock (338 MHz on an M4 Pro) while it is 72–98% busy, with thermal pressure nominal. Probes back to 60 fail, because the clock does not rise within a probe. `gamepolicyd` logs `Game mode enabled` and `Set DPS to 2`. → [macOS Game Mode holds the GPU at its lowest clock](../reference/frame-rate.md#macos-game-mode-holds-the-gpu-at-its-lowest-clock) - a Mac game started with `DM_FULLSCREEN=1` from an app that is itself in fullscreen (the launcher's console mode) came up as a window. → [A game opened from a fullscreen app stays a window](../reference/frame-rate.md#a-game-opened-from-a-fullscreen-app-stays-a-window) - the mouse pointer stayed on the picture of a Mac game, in a window and in fullscreen, until it was moved to a screen corner. → [The pointer stays on a Mac game](../reference/frame-rate.md#the-pointer-stays-on-a-mac-game) - on a ProMotion built-in screen, only in fullscreen, the frame step went 1 → 2 → 3 vsyncs on frames costing 0.1–0.6 vsyncs (`3 late frames; cost 0.32 vsyncs`) and the game presented 15 frames a second; a window, or the screen set to a fixed 60 Hz, did not do it. The `DM_NVN_TSV` rows show presents shown one 120 Hz refresh late (`@pres_at_ms` − `@link_target_ms` = 8.3 ms) with a skipped tick after each (`@link_gap_ms` 33 ms), and `@link_lead_ms` about 16 ms against about 50 ms in a window. → [Frame latency 2 for the display link in fullscreen](../reference/frame-rate.md#frame-latency-2-for-the-display-link-in-fullscreen) - on a MacBook Air M2's fixed 60 Hz built-in display, the reporter measured about 50 ms from the game's present call to on-screen presentation with the display link, at both requested frame latencies 1 and 2, versus 29 ms with `DM_PRESENT_LINK=0`. After loading, all three runs held 60 fps with 0.3% of on-screen intervals outside 16.7 ± 2 ms and no frame-step changes. → [Fixed-rate display-link delay remains at latency 1](../reference/frame-rate.md#fixed-rate-display-link-delay-remains-at-latency-1) - autorelease work takes a measurable share of replay time, with temporary arena-buffer ownership traffic a few times per draw. → [Arena buffer ownership on allocation](../reference/frame-rate.md#arena-buffer-ownership-on-allocation) - a game runs at about 10 fps with little GPU work: the submit thread waits for a command allocator (`mtl_sub_begin` → `mtl_wait_at`), the GPU sits idle between encoders for hundreds of ms (`DM_NVN_GPUPROF`), the Metal 4 `SubmissionQueue` thread spends nearly all its time in `iokit_user_client_trap` (almost all system time), and the `memory up to frame` line shows a residency set of 10,000 objects or more. → [Dedicated c1 constants as slices of a bank](../reference/frame-rate.md#dedicated-c1-constants-as-slices-of-a-bank) - the submit thread waits on the texture / sampler registry lock while a lower-priority registration thread is preempted holding it. → [Registry lock priority inheritance](../reference/frame-rate.md#registry-lock-priority-inheritance) - in a replay profile, `_platform_memcmp` is most of the time spent in serial lookups (`tex_mtl` through `g_by_serial`). → [Hash-table lookups of 8-byte keys](../reference/frame-rate.md#hash-table-lookups-of-8-byte-keys) - the GPU sits idle each frame while the host translates the submission (a game that does not submit frame N+1 until frame N's GPU work is done). → [Submissions handed to the GPU in segments](../reference/frame-rate.md#submissions-handed-to-the-gpu-in-segments) - one frame in 50 or so takes 25-40 ms in a scene where the frame normally fits, with the host on time: `@sync_ms` is high, `@sub_wall_ms` is not, and the frame before has a GPU span (`@gpu_end_ms - @gpu_beg_ms`) of 25-40 ms while the summed `@gpu_ms` has not moved. Runs fall into two states, and on the same code one can have 5 long frames and the next 60. A bad run also shows 186 % CPU against 133 %, and the previous frame still running when the next starts (p50 4 ms, p90 10 ms, against about 0 in a good run). → [The GPU idles with the next command buffer already committed](../reference/frame-rate.md#the-gpu-idles-with-the-next-command-buffer-already-committed) - the submit thread's CPU samples half in `__CFBasicHashFindBucket_Linear` under `CFSetContainsValue` (from `tex_mtl_` and `tex_by_id`), a few hundred thousand to over a million instructions of translation per draw, the submission growing with the game's CPU-written textures. → [The set of CPU-written textures hashed by serial](../reference/frame-rate.md#the-set-of-cpu-written-textures-hashed-by-serial) - several milliseconds of CPU translation and geometry preparation separate one frame's GPU end from the next frame's GPU start, even though the frame already contains complete geometry passes. → [Geometry boundaries submit prepared work early](../reference/frame-rate.md#geometry-boundaries-submit-prepared-work-early) - CPU submission spikes during texture updates, with the residency log showing tens of MB of new private staging allocations per frame. → [Reusing upload staging after a slot completes](../reference/frame-rate.md#reusing-upload-staging-after-a-slot-completes) - periodically rewritten textures cause CPU submission spikes even with no new staging allocations or shader compilation; a small cube-array image produces thousands of deswizzle dispatches and buffer-to-texture copies. → [Small array texture uploads without per-face staging](../reference/frame-rate.md#small-array-texture-uploads-without-per-face-staging) - the submit thread's CPU samples dominated by `mtl_addr` / `mtl_gpu_addr` (vertex buffers in `draw`, uniform buffers in `encode_args`). → [Address to memory pool lookups by binary search](../reference/frame-rate.md#address-to-memory-pool-lookups-by-binary-search) - gameplay has low CPU clocks, large render submission wall time compared with thread CPU time, and default QoS (`0x15`) on the main guest thread while workers report user-interactive (`0x21`). → [Main guest thread keeps inherited default QoS](../reference/frame-rate.md#main-guest-thread-keeps-inherited-default-qos) - stalls of 30–60 ms about once a second, at 30 fps and at 60 (99th percentile 63–127 ms); the main thread waits 20–34 ms for the render thread once a second. → [Time-constraint computation declared below the thread's peaks](../reference/frame-rate.md#time-constraint-computation-declared-below-the-threads-peaks) - a movie or full-screen compute pass far slower than the same work should be, nearly all of it GPU time: `GPU p50` near the frame time with `submit+present` under 1 ms. `[RED] raw global memory: a write log ran out of slots` on older chains. With `DM_NVN_GPUPROF` a relaxed timestamp can put the time before the compute encoder's reported start, so the encoder itself looks short and the gap before it is what is long. → [A shader that writes a whole frame through raw global memory](../reference/frame-rate.md#a-shader-that-writes-a-whole-frame-through-raw-global-memory) - a game with dynamic resolution stays at its full size while the GPU runs far over budget: `GPU p50` above the frame time target, frame times locked to 2 vsyncs, and the same pass sizes frame after frame in `DM_NVN_GPUPROF`. → [Dynamic resolution that never moves, and draw passes that wait for each other](../reference/frame-rate.md#dynamic-resolution-that-never-moves-and-draw-passes-that-wait-for-each-other) - many passes a frame on the same attachments, with the residency set line showing `passes ended to land them for a read` in the thousands and `refused …: earlier submission running` matching it. Ocarina of Time: 10,463 per 300 frames, each ending the pass over a uniform block no GPU write touched. → [A full table of running GPU writes ends passes for nothing](../reference/frame-rate.md#a-full-table-of-running-gpu-writes-ends-passes-for-nothing) - a game that reads textures through a pool (Shaders report which textures they read through a pool) renders far below its maximum dynamic resolution: Ocarina of Time's main pass at 763x429 with the GPU at 17 ms a frame. → [A host's own store in a fragment shader moves its depth test](../reference/frame-rate.md#a-hosts-own-store-in-a-fragment-shader-moves-its-depth-test) ## NVN objects - heap corruption; a stack smash where a function returned to `0x100000000`; a crash in SHA-256 on the code address 0x16300. → [Host records must fit the game's SDK object sizes](../reference/nvn-objects.md#host-records-must-fit-the-games-sdk-object-sizes) - out-of-range vertices, NaN, a black band and flicker; seen on the iPhone, while Mac runs of the same scene looked clean. → [Inlined SDK code writes into `NVNcommandBuffer` +0x10](../reference/nvn-objects.md#inlined-sdk-code-writes-into-nvncommandbuffer-0x10) - a running game with sound draws a black screen; every uniform buffer returns the same initialized address, with its allocation offset reported as its size. → [Guest ring allocators write `NVNbuffer` offset and size directly](../reference/nvn-objects.md#guest-ring-allocators-write-nvnbuffer-offset-and-size-directly) - sprites broke apart in some runs only, depending on the allocation order; buffers overlapped. → [Sizes the hardware never reports as 0 (ZCull save area)](../reference/nvn-objects.md#sizes-the-hardware-never-reports-as-0-zcull-save-area) - a null write as soon as the main thread starts recording a command buffer (13 Sentinels: a constructor at `main+0x2fa9a0` runs on `this = 0` when the prologue enters its first battle). → [Heaps cut from a pool at alignment relative to its GPU address](../reference/nvn-objects.md#heaps-cut-from-a-pool-at-alignment-relative-to-its-gpu-address) - `[RED] memory pool … created at retry N`. → [`newBufferWithBytesNoCopy` retried under memory pressure](../reference/nvn-objects.md#newbufferwithbytesnocopy-retried-under-memory-pressure) - a buffer is created with a null pool right after a scene change. → [Virtual memory pools mapped onto one physical pool](../reference/nvn-objects.md#virtual-memory-pools-mapped-onto-one-physical-pool) - `[RED] MapVirtual: non-contiguous mapping (true sparse) not implemented`. → [Sparse virtual pools built from separate physical pools](../reference/nvn-objects.md#sparse-virtual-pools-built-from-separate-physical-pools) - `[RED] MapVirtual: non-contiguous mapping (true sparse) not implemented`, on small virtual pools; streamed textures black or missing (OCTOPATH TRAVELER's village ground and plants). → [Virtual pools of one texture each, mapped before and after the texture](../reference/nvn-objects.md#virtual-pools-of-one-texture-each-mapped-before-and-after-the-texture) - `[RED] NVN unimplemented function called: nvnTextureBuilderGetSparseTileLayout`, then an out-of-memory abort in Unreal's allocator (`Failed to allocate 1879113728 bytes from Standard Allocator`, on `DM_DBG=1`). → [The sparse tile layout of a texture](../reference/nvn-objects.md#the-sparse-tile-layout-of-a-texture) - `CRASH sig=10` in `memmove` from `pkg_upload` → `nvn_deswizzle`, at an address 32 GB into a sparse virtual pool; textures with unaliased tails came out magenta. → [Textures read through a 4 KB page table of a sparse pool](../reference/nvn-objects.md#textures-read-through-a-4-kb-page-table-of-a-sparse-pool) - `kIOGPUCommandBufferCallbackErrorOutOfMemory` on every command buffer from the first frames, no frame presented, "GPU allocated" near the Mac's memory; `large texture … in a sparse virtual pool` lines name textures of gigabytes. → [Large sparse textures as Metal placement sparse textures](../reference/nvn-objects.md#large-sparse-textures-as-metal-placement-sparse-textures) - the placement heaps (`sparse tiles: placement heap N`) keep growing through a session, to several times the memory the game maps behind its sparse textures. On a 16 GB M1 Pro, Mario Kart World's race reached 11 heaps (2.75 GB) within three minutes, wired memory 8.7 GB, and the system swapped: frames went from 25 to 50 ms. A GPU write through one place of a page is also not seen at another. → [Physical pages mapped at several places of a placement sparse texture](../reference/nvn-objects.md#physical-pages-mapped-at-several-places-of-a-placement-sparse-texture) - frames of 100 ms and more every few frames on a Mac short of memory, with no failing command buffer; a Metal System Trace shows the driver wiring and unwiring all the time (3.2 s of a 6 s trace on the game below), and the `restop` line of `DM_CTL` shows gigabytes of shared buffers. → [Large pools wrapped in chunks](../reference/nvn-objects.md#large-pools-wrapped-in-chunks) - GPU memory grows with every scene change (Engage's idle title demo reached 5.4 GB of GPU memory and 3.6 GB resident in 850 s). → [Finalized pools kept alive by residency and the sharing table](../reference/nvn-objects.md#finalized-pools-kept-alive-by-residency-and-the-sharing-table) - the memory line's `freed but alive` count only grows, while no host table holds those buffers; "GPU allocated" is far above resident memory (Ghost Trick: Phantom Detective, 125 to 146 buffers and 6.6 to 8.7 GB of GPU allocations against 2.2 GB resident). → [Finalized pool buffers kept by a guest thread's autorelease pool](../reference/nvn-objects.md#finalized-pool-buffers-kept-by-a-guest-threads-autorelease-pool) - GPU and resident memory keep growing during texture streaming while pool, residency and serial-object counts stay nearly flat, with no freed pool buffers alive. → [Finalized textures kept by registered descriptor views](../reference/nvn-objects.md#finalized-textures-kept-by-registered-descriptor-views) - the submit thread spends milliseconds a frame in `pool_gpu` → `tex_by_id` → `tex_mtl` / `tex_get` (a `sample` of the process), and the `[nvn-mtl] pool for handles traced to no slot … built in X ms` line shows a rebuild of the texture pool table every frame at about 2 ms. Fire Emblem Fortune's Weave's battle map: 1.9 ms a build, three builds a frame, about 14 % of the main thread. → [Texture ID views revalidated only for the serials that changed](../reference/nvn-objects.md#texture-id-views-revalidated-only-for-the-serials-that-changed) - the serial table grows by about 10 entries a frame (276,000 after 25,000 frames). → [Dead texture serials kept in a ghost table](../reference/nvn-objects.md#dead-texture-serials-kept-in-a-ghost-table) - `nvn_replay` aborts on a game's capture with `-[NvProg width]: unrecognized selector` (from `rt_dims`) or `-[NvProg mipmapLevelCount]`: a render target resolves to a program. → [A replay's own objects take serials above a capture's](../reference/nvn-objects.md#a-replays-own-objects-take-serials-above-a-captures) - `DM_NVN_CAPTURE` reports `a record names … (0 bytes), outside every pool … texture registry entry …` for some texture IDs, with addresses that look like data; one capture stopped with `a sparse virtual pool (step 1 does not capture page tables): the capture is incomplete`, another with `straddles a region`. → [A captured texture ID whose memory pool was finalized](../reference/nvn-objects.md#a-captured-texture-id-whose-memory-pool-was-finalized) - `CRASH sig=11 … pc=nvn_sparse_protect+0x40`, an address that looks like data, `x8` 8 below it, after a long session; the backtrace `tex_by_id` ← `tex_mtl` ← `pkg_upload`. The pool need not be sparse. → [A texture read after its memory pool object was freed](../reference/nvn-objects.md#a-texture-read-after-its-memory-pool-object-was-freed) - `regress.py capture` stops with `frame N was not captured within … s` although the game reached the frame before it; a capture takes 5 to 20 minutes where an earlier one of the same frame took 2 to 3, and a sample of the host shows the submitting thread in `lzfseEncodeBase` under `nvn_cap_submit`. → [A frame capture runs under the standard thread policy](../reference/nvn-objects.md#a-frame-capture-runs-under-the-standard-thread-policy) - `nvn_replay` stops with `program #N (a key …) stage S: the translated shader's bindings or inputs differ from the ones the records were captured against`, and `regress.py replay` reports every game's capture as one the candidate cannot replay, while the shaders' reflection (`<key>_b.json`) is the same in both chains apart from the chain field. → [A capture refused after a change to the reflection structs](../reference/nvn-objects.md#a-capture-refused-after-a-change-to-the-reflection-structs) - `[RED] NVN unimplemented function called: nvnCommandBufferGetControlMemoryFree` (or `…GetControlMemorySize`) once, after the game gives a command buffer control memory. → [Control memory capacity queries](../reference/nvn-objects.md#control-memory-capacity-queries) - `FATAL NVN command memory: the game's pool is empty…`. → [Host-lent command memory segments](../reference/nvn-objects.md#host-lent-command-memory-segments) - frames stop after about 15 s; a game thread spins in its command-memory callback (a ring allocator at `main+0x9cc120` waiting for fences that have all signalled). → [What `GetCommandMemoryUsed` counts](../reference/nvn-objects.md#what-getcommandmemoryused-counts) - `CRASH sig=10` in `mtl_exec` after minutes of play, the fault address equal to `x19` and shaped like `0x1000000003`. → [Prerecorded lists in slots of their measured size](../reference/nvn-objects.md#prerecorded-lists-in-slots-of-their-measured-size) - the title showed one stretched 64×64 icon over the 3D scene, a new game a white screen; post-process passes with stale texture handles; `[RED] bind record … overwritten after recording`. → [Recorded commands patched in place by the game (`OP_BIND_TEX1`)](../reference/nvn-objects.md#recorded-commands-patched-in-place-by-the-game-op_bind_tex1) - choosing X-2 after the collection launcher crashes in `keys_hash`, reading control address `0x8000000000`; the program object now contains command-buffer data. → [Bindings belong to each queue](../reference/nvn-objects.md#bindings-belong-to-each-queue) - about 23 s after launch, when the title screen hands over to the opening demo, a crash in `keys_hash` (`prog_key` ← `prog_get` ← `bind_stages` ← `prog_resolve` ← `mtl_queue_activate`), reading a control address made of float data; the program object now holds other data. → [Finalized programs leave every queue's bindings](../reference/nvn-objects.md#finalized-programs-leave-every-queues-bindings) - `nvnCommandBufferFenceSync` unimplemented, every `SyncWait` timed out at once. → [Fence syncs recorded in command buffers](../reference/nvn-objects.md#fence-syncs-recorded-in-command-buffers) - `FATAL submit re-entered` in the first frames. → [Submissions from two queues on two threads](../reference/nvn-objects.md#submissions-from-two-queues-on-two-threads) - going to the background (iOS `sceneDidEnterBackground`, minimizing the Mac window) while the "Preparing shaders" or "Preparing pipelines" screen is up blocks the main thread until the step ends: minutes on a first start, long enough for iOS to end the app. The log's `[nvn] graphics suspended` line comes only after the `pipeline prepare:` line. → [Going to the background during the prepare step](../reference/nvn-objects.md#going-to-the-background-during-the-prepare-step) - frames stop, no crash, the main thread sits in `nvnSyncWait(sync, -1)`, and the watchdog's wait-state line shows the main fence one short (`main fence submitted N / completed N-1`). → [A GPU command buffer that never completes](../reference/nvn-objects.md#a-gpu-command-buffer-that-never-completes) - the frame's blocking SyncWait on its newest fence wakes about 0.26–0.29 ms after the GPU end (M2 Max; the wait ledger, `DM_NVN_WAITS=1`), on the critical path of every frame. → [The game's SyncWait wakes on the GPU's own signal of its fence](../reference/nvn-objects.md#the-games-syncwait-wakes-on-the-gpus-own-signal-of-its-fence) - loading screens many times slower on the iPhone than on the Mac (Three Houses' first loading screen 78 s on the iPhone, 5 s on the Mac). → [`nvnQueueFinish` waits for the GPU, not the display](../reference/nvn-objects.md#nvnqueuefinish-waits-for-the-gpu-not-the-display) - CPU texture uploads spend time recalculating block-linear addresses and calling variable-length `memcpy` for every 16-byte segment. → [CPU deswizzle copies use slice and row offsets](../reference/nvn-objects.md#cpu-deswizzle-copies-use-slice-and-row-offsets) - a Switch 2 game's textures from its files keep their shapes but break up along every edge: misplaced 4×4 blocks (16-byte pieces) in a regular weave, invisible in flat areas. Normal maps make lit surfaces look woven; opacity masks punch holes. → [The Switch 2's order inside a GOB](../reference/nvn-objects.md#the-switch-2s-order-inside-a-gob) - driver comparisons report the wrong block dimensions for packaged 2D / 3D textures, or too little storage for linear block-compressed textures (64x64 BC1 with stride 128: 2048 bytes instead of 8192). → [Packaged texture block dimensions and linear storage rows](../reference/nvn-objects.md#packaged-texture-block-dimensions-and-linear-storage-rows) - huge stretched terrain walls and ceilings, flickering, while characters and the HUD are right: `WriteTexels` into a texture overwrote the mesh data stored right after it. → [Minimal texture layouts](../reference/nvn-objects.md#minimal-texture-layouts) - menus and dialogue boxes draw but contain no text, while images and pictogram digits are fine; the sky is black (CPU-written linear colour ramps). → [Linear textures in CPU-visible pools](../reference/nvn-objects.md#linear-textures-in-cpu-visible-pools) - a trap during graphics initialization in `SetupSurfaceInfoMemoryInside`, asserting `ctx.memorySize <= localmemsetupinfo.memorySize`. → [Linear render-target storage without the LINEAR flag](../reference/nvn-objects.md#linear-render-target-storage-without-the-linear-flag) - on an iPhone only, a scene's backgrounds are solid magenta and magenta frames flash, while the Mac is right. The log has `[RED] linear texture offset … / row pitch 32 not aligned to 64 bytes; created as a private texture (CPU writes invisible)`, then `[RED] deswizzle failed format 0x25 target 1`. → [Linear textures a device cannot view on their pool's buffer](../reference/nvn-objects.md#linear-textures-a-device-cannot-view-on-their-pools-buffer) - video frames, or a game's built-in default textures, are all zero. → [Textures written with `nvnTextureWriteTexels`](../reference/nvn-objects.md#textures-written-with-nvntexturewritetexels) - after a few minutes of play the main thread spends whole frames in `WriteTexels` (Metroid Dread's frames stopped at about 175 s). → [`WriteTexels` regions written in place by block-linear address](../reference/nvn-objects.md#writetexels-regions-written-in-place-by-block-linear-address) - black screen with every geometry right (`DM_NVN_HILITE` shows each sprite and glyph in place); the uniform buffer right (a `CBDUMP`), so every texture read 0. → [A pool's storage at creation is its textures' content](../reference/nvn-objects.md#a-pools-storage-at-creation-is-its-textures-content) - a game draws its UI and text but every image is black; `packaged textures: first uploads 0` while `TextureInitialize` counts the textures the game created (SD GUNDAM G GENERATION CROSS RAYS: 74, of which the 10 BC3 ones hold data and none is uploaded). After the fill works, one overlay still comes up with its text over nothing: the panel's background is missing and the text of the next block sits on top of it. → [`COMPRESSIBLE` in a pool the CPU writes is only a hint](../reference/nvn-objects.md#compressible-in-a-pool-the-cpu-writes-is-only-a-hint) - a texture the game filled with `memcpy` and flushed reads as zeros (BotW's sky brownish grey, the distant haze brown). → [First-use fill of storage the game flushed](../reference/nvn-objects.md#first-use-fill-of-storage-the-game-flushed) - magenta (ASTC's error colour) where UI images belong: a title logo and menu panels, while the 3D scene and the text draw; `DM_NVN_ZBLOCK=1` reports nothing (the textures are not uploaded on the CPU at all); `DM_NVN_TEXINFO=WxH` shows storage holding data at first use (`non-zero …`) in a pool with flags 0x22 (`CPU_UNCACHED | GPU_CACHED`). → [Storage of a CPU-uncached pool at first use](../reference/nvn-objects.md#storage-of-a-cpu-uncached-pool-at-first-use) - a picture that should change with a selection is black, or shows the previous item's picture while the item's name and description are right. `DM_NVN_TEXINFO=WxH` shows `swizzled=0` at first use with storage holding data, no packaged layout, in a `CPU_CACHED` or `CPU_UNCACHED` pool, and `DM_NVN_DIRTYCHECK=1` reports no missed write. → [Block-compressed storage the CPU wrote before first use](../reference/nvn-objects.md#block-compressed-storage-the-cpu-wrote-before-first-use) - a movie plays black (Age of Calamity: its intro movie under the "+ Skip" prompt). → [Mapped-range flushes taken as uploads (`tex_flush_upload`)](../reference/nvn-objects.md#mapped-range-flushes-taken-as-uploads-tex_flush_upload) - open-world ground is one flat colour on a flat plane with blocky seams, or water and sand are missing, while course meshes, rocks and the kart look right. `DM_NVN_TEXINFO=WxH` shows uncompressed textures with `swizzled=0`, no packaged layout and storage holding data in a `CPU_CACHED` pool. → [Uncompressed storage the CPU wrote, in a pool the GPU has not written](../reference/nvn-objects.md#uncompressed-storage-the-cpu-wrote-in-a-pool-the-gpu-has-not-written) - magenta surfaces (Metal decodes an all-zero ASTC block as the error colour (1, 0, 1)); a zero BC block decodes black, which looks like missing light; black screen while the UI (or a dialog box) draws in the right places under `HILITE` or in the pass dump; `packaged textures: first uploads 0`. → [CPU writes with no flush, caught by page protection (`tex_dirty_upload`)](../reference/nvn-objects.md#cpu-writes-with-no-flush-caught-by-page-protection-tex_dirty_upload) - a texture the game builds from CPU-filled textures read back with `nvnTextureReadTexels` comes out zero. → [`ReadTexels` from guest memory and textures written after first use](../reference/nvn-objects.md#readtexels-from-guest-memory-and-textures-written-after-first-use) - `[RED] upload batches belong to the submit thread only: up_begin called on thread '…'`, then an abort, with `pkg_upload` ← `tex_mtl` ← `mtl_read_texels` on the stack; or `CRASH sig=10` in `nvn_deswizzle` ← `mtl_read_texels`, at an address in a sparse virtual pool's reserved range. → [`ReadTexels` on a texture of a sparse pool](../reference/nvn-objects.md#readtexels-on-a-texture-of-a-sparse-pool) - a streamed texture's small mip levels hold another texture or zeros while its large levels are right (`texraw <serial>.<level>`), so surfaces sampled with a mip bias or at a distance show bright speckles, dark blotches and sharp detail where the Switch shows soft texture (Yoshi's felt), from the moment finer levels stream in (the opening going dark). → [GPU copies into textures uploaded from their storage](../reference/nvn-objects.md#gpu-copies-into-textures-uploaded-from-their-storage) - what the GPU drew into a texture is lost later: a texture re-created from the same memory, or one the game moved with `memcpy`, comes out zero; on the Switch it holds the drawing. Tears of the Kingdom: the grass of a meadow is drawn with no length and the ground under it goes dark, a few seconds after loading, tile by tile around Link. → [Render passes into textures uploaded from their storage](../reference/nvn-objects.md#render-passes-into-textures-uploaded-from-their-storage) - the `[nvn] residency set up to frame …` line shows hundreds of additions from `mirror_readback`'s line in `nvn_mtl.m` every 300 frames, and as many removals, with the residency commits' time up. Tears of the Kingdom: about 1,500 every 300 frames on an iPhone 17 (1.4.2, seedds/nxnative#931), about 370 on a Mac. → [Readback buffers kept for reuse](../reference/nvn-objects.md#readback-buffers-kept-for-reuse) - textures that should hold CPU-written data come out magenta (ASTC's error colour) or black. → [Sampled textures in a sparse pool uploaded through the page table](../reference/nvn-objects.md#sampled-textures-in-a-sparse-pool-uploaded-through-the-page-table) - the submit thread spends most of its time in `nvn_dirty_since` under `nvn_sparse_since`, called from `tex_mtl` (render-target and texture lookups of textures in a sparse pool). → [A sparse texture's CPU-write check at every lookup](../reference/nvn-objects.md#a-sparse-textures-cpu-write-check-at-every-lookup) - some textures are re-uploaded every frame (several MB per frame). → [Dirty-page ranges of pools that share a host page](../reference/nvn-objects.md#dirty-page-ranges-of-pools-that-share-a-host-page) - packaged textures re-uploaded at every use with unchanged content; upload staging and frame times rising. → [Writes beside a packaged texture in a shared host page](../reference/nvn-objects.md#writes-beside-a-packaged-texture-in-a-shared-host-page) - about one run in four stalled early (around the opening movie or the title), with no log output, not even the time-limit report. → [Dirty-page tracker race and early stalls](../reference/nvn-objects.md#dirty-page-tracker-race-and-early-stalls) - a CPU-written texture stays stale after later writes; letters can be missing from a glyph cache. → [Dirty-page writes missed during upload](../reference/nvn-objects.md#dirty-page-writes-missed-during-upload) - a host system call writing into storage after its NVN pool was finalized fails with `EFAULT`; a direct write can fault after the tracker stopped owning the page. → [A retired pool remains read-only](../reference/nvn-objects.md#a-retired-pool-remains-read-only) - `[RED] NVN unimplemented function called: nvnSamplerBuilderSetBorderColorui` during renderer initialization. → [Integer sampler border colours](../reference/nvn-objects.md#integer-sampler-border-colours) - `[RED] sampler ID 4096 not registered` (or another ID past the sampler pool), once, from the first frames on. → [Bound handles are the driver's 32-bit words](../reference/nvn-objects.md#bound-handles-are-the-drivers-32-bit-words) - device / subsystem setup returns quietly and the next stage never starts. → [Version and capability checks that fail quietly](../reference/nvn-objects.md#version-and-capability-checks-that-fail-quietly) - a null-pointer crash early in `nnMain`, right after NVN setup should have happened (Super Mario 3D World + Bowser's Fury, `main+0x759e08`: the device singleton `main+0x1a28ea0` is still null). → [The device's API version](../reference/nvn-objects.md#the-devices-api-version) - null read at `main+0xb8462c` right after the first two textures, called from `main+0x670eb0` (Bayonetta 3), or cleanup crashes at `main+0x9c0d1c` after shader initialization fails (ASTRAL CHAIN). → [Newest GPU code version reported by the driver](../reference/nvn-objects.md#newest-gpu-code-version-reported-by-the-driver) - none seen: a Switch 2 game asking `nvnDeviceGetInteger` got the Tegra X1's values (measured on a Switch 1), and items past 0x5F answered 0 with a red line. → [The Switch 2's device values](../reference/nvn-objects.md#the-switch-2s-device-values) - a jump to pc=0 right after the NVN bootstrap loader (`lr=main+0x37fe930`, `[RED] NVN address lookup of an unknown name: nvnSetExternalDebuggerEnabledNVX`). → [Extensions fetched by name and called unchecked](../reference/nvn-objects.md#extensions-fetched-by-name-and-called-unchecked) - SIGBUS in `AGCDeserializedReply`, address in the guest stack region. → [NVN entry points on the big host stack](../reference/nvn-objects.md#nvn-entry-points-on-the-big-host-stack) - red `NVN unimplemented function called` lines for `nvnColorStateGetBlendEnable`, `nvnBlendStateGetBlendFunc`, `nvnPolygonStateGetCullFace`, `nvnDepthStencilStateGetDepthTestEnable`, `nvnBufferBuilderGetSize`, `nvnTextureBuilderGetWidth`, …. → [State read back through NVN getters](../reference/nvn-objects.md#state-read-back-through-nvn-getters) - an abort in device setup when `nvnTexturePoolGetSize` / `nvnSamplerPoolGetSize` returned 0. → [Pool size getters, texture address and command memory size](../reference/nvn-objects.md#pool-size-getters-texture-address-and-command-memory-size) - `[RED] NVN unimplemented function called: nvnTextureBuilderGetMemoryOffset`, then `nvnTextureBuilderGetRawStorageClass`. → [Builder storage getters](../reference/nvn-objects.md#builder-storage-getters) - `[nvn-mtl] FATAL buffer copy address is in no memory pool src=0x70d08a8b00 dst=0 n=0x29a00` as a match loads: a recorded `CopyBufferToBuffer` whose destination is 0. → [`Map` of a pool without CPU access returns NULL](../reference/nvn-objects.md#map-of-a-pool-without-cpu-access-returns-null) - red stub lines for NVN calls. → [NVN calls that were red stubs](../reference/nvn-objects.md#nvn-calls-that-were-red-stubs) - `nvnWindowGetPresentInterval`, `nvnCommandBufferSetCopyImageStride` missing. → [SDK 8 window and copy-stride entry points](../reference/nvn-objects.md#sdk-8-window-and-copy-stride-entry-points) - `[RED] texture bound to an image slot lacks the shader-write usage`, and compute image writes go to a dummy texture. → [Image bindings supply shader-write intent](../reference/nvn-objects.md#image-bindings-supply-shader-write-intent) - `[RED] NVN unimplemented function called` for each. → [`nvnTextureBuilderGetViewOffset`, `nvnTextureViewCompare`, `nvnBlendStateSetAdvancedNormalizedDst`](../reference/nvn-objects.md#nvntexturebuildergetviewoffset-nvntextureviewcompare-nvnblendstatesetadvancednormalizeddst) - a pool walk makes gigabytes of textures from far fewer images: Ocarina of Time's 32,768 IDs name 3,607 storages, and one texture per ID came to 2 GB. → [Texture IDs of one storage share one packaged texture](../reference/nvn-objects.md#texture-ids-of-one-storage-share-one-packaged-texture) - thousands of first uploads a frame in a scene whose textures do not change: Ocarina of Time, about 15,000 a frame. → [Finalizing a copy of a texture object](../reference/nvn-objects.md#finalizing-a-copy-of-a-texture-object) ## Rendering - clang reports null dereferences in `nvnWindowInitialize` and `clear_tex`; clearing a null texture crashes with `DM_NVN_PASSDUMP=1`. → [Null textures in diagnostic logs](../reference/rendering.md#null-textures-in-diagnostic-logs) - Metal aborts on a texture descriptor with an absurd size (`height (1869367126) greater than … 16384`). → [Texture objects copied into command records](../reference/rendering.md#texture-objects-copied-into-command-records) - a decoded movie stays black even though its YUV textures contain the picture; disabling its depth test makes it visible. → [New textures start as zero](../reference/rendering.md#new-textures-start-as-zero) - glyphs render as white boxes (the font atlas is `(1, 1, 1, R)`). → [Texture swizzle through swizzled Metal views](../reference/rendering.md#texture-swizzle-through-swizzled-metal-views) - RGB565, RGB5A1 or RGB5 textures sample with red and blue exchanged: smeared, banded rock, the shapes right and the colours wrong; or what the GPU cleared, drew or copied into such a texture reads back to the game, or samples, with red and blue exchanged. → [RGB565-family textures in Metal's channel order](../reference/rendering.md#rgb565-family-textures-in-metals-channel-order) - outdoor battle ground and lower foliage are nearly black while the characters and the UI stay lit: a baked shadowmask takes the sunlight away. RGBA4 textures sample with their four channels reversed. → [RGBA4 textures in Metal's channel order](../reference/rendering.md#rgba4-textures-in-metals-channel-order) - dark boxes and cream cloud rectangles behind HUD prompts, a black stamina wheel and a black System menu background (layout captures). → [`nvnTextureCompare` compares the channel mapping](../reference/rendering.md#nvntexturecompare-compares-the-channel-mapping) - Metal validation aborts in `tex_by_id` with `MTLPixelFormatDepth32Float` not compatible with `MTLPixelFormatR32Float`. → [Sampling a depth attachment through a red texture view](../reference/rendering.md#sampling-a-depth-attachment-through-a-red-texture-view) - `newTextureViewWithPixelFormat` takes a large share of the replay thread (45% in Age of Calamity) when a game registers textures into a ring of IDs before every bind. → [Texture views cached by texture and view parameters](../reference/rendering.md#texture-views-cached-by-texture-and-view-parameters) - daylight scenes washed out to white (every read of a texture returned one fixed value); `texture type mismatch` red lines, among them `declares slot … as Metal type 6, texture ID … is type 5` (a cube in a cube array slot). → [Compatible views for a mismatched declared texture type](../reference/rendering.md#compatible-views-for-a-mismatched-declared-texture-type) - with `MTL_SHADER_VALIDATION=1`, `Invalid Metal usage: Texture is not resident` for a texture allocated in `tex_fit`; without validation those reads are undefined. → [Compatible views made from the texture under a view](../reference/rendering.md#compatible-views-made-from-the-texture-under-a-view) - a type mismatch when a Metal 1D texture is bound to a shader's `texture2d` argument. → [1D textures as one-row 2D textures](../reference/rendering.md#1d-textures-as-one-row-2d-textures) - shaders that sample a cube texture as `texturecube_array` get a type mismatch. → [Cube textures held as 6-layer 2D arrays](../reference/rendering.md#cube-textures-held-as-6-layer-2d-arrays) - an abort in `MTLTextureDescriptor` validation, `arrayLength (510) … greater than the max allowed size (341)`, when the prologue movie ends. → [Cube map arrays count layer-faces](../reference/rendering.md#cube-map-arrays-count-layer-faces) - an abort in Metal's validation: `newSliceRange.length(1) must be a multiple of (6)`. → [Cube views count their layers in cubes](../reference/rendering.md#cube-views-count-their-layers-in-cubes) - `texture type mismatch … declares slot 10 as Metal type 5, texture … is type 3` (undefined reads); the later `[RED] texture type mismatch: shader declares a cube, texture is 2D` could also report an unused conditional input as an error. → [A 2D texture in a cube slot binds the zero cube](../reference/rendering.md#a-2d-texture-in-a-cube-slot-binds-the-zero-cube) - `[RED] texture type mismatch: shader … declares slot … as Metal type 7, texture ID … is type 2 … bound as is` (or type 3, a 2D array); the reads are undefined. → [A 2D texture in a 3D slot binds the zero 3D texture](../reference/rendering.md#a-2d-texture-in-a-3d-slot-binds-the-zero-3d-texture) - `[RED] texture type mismatch: shader … declares slot … as Metal type 2, texture ID … is type 4 (NVN target 5, …); bound as is`, for a shader whose MSL declares the slot `texture2d_ms`. → [Multisample texture slots](../reference/rendering.md#multisample-texture-slots) - translucent UI (frosted text bands, button guides, dialog headers) yellow and white. → [Integer views for images a shader declares uint or int](../reference/rendering.md#integer-views-for-images-a-shader-declares-uint-or-int) - flat-coloured objects with no texture detail in an otherwise correct scene: the UVs and colours a vertex factory fetches from buffers read 0. Then `texture buffers bound as 2D rows … N times, about N made` in the log, a Metal texture for nearly every bind. → [Buffer textures behind handles in uniform buffers, and rows of finalized descriptors](../reference/rendering.md#buffer-textures-behind-handles-in-uniform-buffers-and-rows-of-finalized-descriptors) - `texture type mismatch: shader declares 2, texture is 9`; the slot read 0. → [Buffer textures read by 1D integer fetches (row wrap)](../reference/rendering.md#buffer-textures-read-by-1d-integer-fetches-row-wrap) - none of its own seen here. Pull request #984 reports GPU hangs from huge light counts on its build of the same game. → [Integer buffer textures read through float slots](../reference/rendering.md#integer-buffer-textures-read-through-float-slots) - none visible on an M6, where at most 0.23 % of pixels differ between paired runs. GitHub issue #783 reports wrong light offsets on an M2. → [Integer textures read through float slots](../reference/rendering.md#integer-textures-read-through-float-slots) - particle effects drawn at the wrong scale or place, or flickering, where the particle data is a buffer texture at a pool offset that is not a multiple of 16; log line `buffer texture at pool offset …, below Metal's 16-byte alignment`. → [Buffer textures at offsets below 16 bytes](../reference/rendering.md#buffer-textures-at-offsets-below-16-bytes) - lighting that alternates between lit and unlit from one frame to the next on an iPhone, the same scene steady on a Mac; log lines `texture buffer (texture ID …, … at pool offset …) has no 2D-row form for a wrapped 1D fetch: the slot reads 0` and `texture type mismatch: … a buffer texture: the slot reads 0 (dummy)`. → [Buffer texture rows at a pool offset the device will not view](../reference/rendering.md#buffer-texture-rows-at-a-pool-offset-the-device-will-not-view) - torn digits and a background in blue steps (Rhythm Heaven Groove's latency calibration). → [Automatic block height truncates](../reference/rendering.md#automatic-block-height-truncates) - magenta (the ASTC error colour) on streamed textures in a sparse pool; `DM_NVN_ZBLOCK` finds such textures (all-zero blocks). → [Sparse textures laid out in 64 KB tiles](../reference/rendering.md#sparse-textures-laid-out-in-64-kb-tiles) - a CPU-filled texture shuffled into a patchwork of rectangles (OCTOPATH TRAVELER's world map on the traveler selection). → [Sparse textures take the block height of their 64 KB tile](../reference/rendering.md#sparse-textures-take-the-block-height-of-their-64-kb-tile) - none visible on an M6 on the Frigate Orpheon's deck. Laid out 1 GOB high, the mapped tiles of a streamed 3D texture fall in scattered places, so lookups read zero in the holes; GitHub issue #783 reports a black gunship hull in the opening on an M2. → [Sparse 3D textures take the standard 3D tile](../reference/rendering.md#sparse-3d-textures-take-the-standard-3d-tile) - crashes that move between runs (30–70% of boots, in the first minute): in the allocator, on bogus pointers, in unrelated threads. Unreal's purgatory proxy (05-debugging) finds freed 64 KB-aligned blocks modified; with the parked blocks read-only, the faulting store is a `memcpy` of texture mip data from the texture streamer into the buffer `RHILockTexture2D` returned. → [Sparse textures of 8- and 16-byte blocks: blocks at most 8 GOBs high](../reference/rendering.md#sparse-textures-of-8--and-16-byte-blocks-blocks-at-most-8-gobs-high) - a small CPU-filled sparse texture shows part of its image beside fragments, cut off at the bottom (Yoshi's Crafted World's loading icon: the left half of a chalk drawing and two stray strokes). → [Sparse textures smaller than a tile keep the automatic block height](../reference/rendering.md#sparse-textures-smaller-than-a-tile-keep-the-automatic-block-height) - streamed textures read 0 (magenta on Monster Hunter Rise's title screen's clothes). → [Sparse textures bound from their first mapped level](../reference/rendering.md#sparse-textures-bound-from-their-first-mapped-level) - textures a mip level sharper or blurrier than on the Switch where the game biases its sampler; in the Vulkan layer, a red line `sampler LOD bias … not implemented`. → [Sampler LOD bias](../reference/rendering.md#sampler-lod-bias) - whatever a game keeps in a texture that it samples past its edge with clamp-to-border reads the wrong value there: grass flattened along Link's path in Tears of the Kingdom, its bend map filled with "bent" wherever the window scrolled. → [Border colours Metal has no sampler state for](../reference/rendering.md#border-colours-metal-has-no-sampler-state-for) - the process ends at once (the window vanishes), with `-[MTLTextureDescriptorInternal validateWithDevice:]` failing an assertion such as `requests 9 mipmap levels, but the dimensions (1, 1, 1) can only support 1`, or `sampleCount must be > 1 for multisample textures`. → [Texture fields Metal refuses](../reference/rendering.md#texture-fields-metal-refuses) - in an Unreal Engine game, textures and lighting turn blurry and muddy about a second after an area loads and stay that way, whatever the frame rate, render scale or upscaling; no red line. → [Unreal's texture streaming pool](../reference/rendering.md#unreals-texture-streaming-pool) - ≈13 MB/frame leak. → [Transient render targets shared by storage](../reference/rendering.md#transient-render-targets-shared-by-storage) - a model has correct geometry, base colour and normals but appears as a black silhouette; deferred lighting's material-ID depth texture stays zero. → [IMAGE usage does not split texture storage](../reference/rendering.md#image-usage-does-not-split-texture-storage) - GPU memory grows with every image shown; the memory line's `shared textures` count keeps rising. → [Shared-storage entries taken over by a new texture](../reference/rendering.md#shared-storage-entries-taken-over-by-a-new-texture) - GPU memory grows as resolution changes or rooms load, although almost every retained texture still has a live NVN descriptor; reclaiming unused sharing-table entries cannot recover it. → [Live resolution variants share physical image storage](../reference/rendering.md#live-resolution-variants-share-physical-image-storage) - the whole picture came out darker and more saturated on the Mac and the iPhone: comparing with a Switch screenshot, every channel at every level equalled the Switch value decoded from sRGB once more (0.55 → 0.26, 0.75 → 0.52). → [Render-target views that change the format](../reference/rendering.md#render-target-views-that-change-the-format) - a movie (or another picture the game converts each frame) does not show: the screen keeps the last 3D frame while the decoder delivers every picture. A pass dump shows a pass writing one serial and the composite sampling another serial of the same size, the two Metal formats `RGBA8Unorm` (70) and `RGBA8Unorm_sRGB` (71). → [Textures of an sRGB / linear pair over the same storage](../reference/rendering.md#textures-of-an-srgb--linear-pair-over-the-same-storage) - a clear of, or a format-converting copy into, a texture made without render-target use is declined. → [Render-target use added on demand](../reference/rendering.md#render-target-use-added-on-demand) - `CRASH sig=11 addr=0x794` in `-[AGXG16GFamilyRenderContext_mtlnext drawIndexedPrimitives:…]+0x50`, called from `draw_`, right after the log line `texture upgraded to allow format views` (Metal API validation reports nothing first). → [A texture upgrade while a draw binds its arguments ends the pass](../reference/rendering.md#a-texture-upgrade-while-a-draw-binds-its-arguments-ends-the-pass) - `render target is a compressed-format texture …`; the pass's draws did nothing (the attachment was left out), or the pipeline-descriptor validation aborts the process. → [Compressed textures as render targets through an uncompressed shadow](../reference/rendering.md#compressed-textures-as-render-targets-through-an-uncompressed-shadow) - on an iPhone before the A17 Pro, the game runs until its first BC texture, then `failed assertion 'Texture Descriptor Validation' … MTLTextureDescriptor has invalid pixelFormat (134).` (or another number from 130 to 153, Metal's BC formats; 134 is `BC3_RGBA`) and `CRASH sig=6`, the backtrace through `tex_mtl`, `tex_by_id` and `encode_args`. → [GPUs without BC textures are refused at start](../reference/rendering.md#gpus-without-bc-textures-are-refused-at-start) - the boot aborts in Metal's pipeline validation: `MTLPixelFormatDepth16Unorm is not color renderable`. → [A depth texture drawn through a colour view](../reference/rendering.md#a-depth-texture-drawn-through-a-colour-view) - a G-buffer target holds only scattered squares (a different order for each 32×32 tile). → [The same texture attached at two colour slots](../reference/rendering.md#the-same-texture-attached-at-two-colour-slots) - `no render target could get an MTLTexture` (the pass skipped). → [Passes with no render target](../reference/rendering.md#passes-with-no-render-target) - a black world: everything rendered through a 3D LUT built by layered draws comes out black (every plane went to plane 0); `DM_NVN_PASSDUMP` shows no `L` line. → [Layered passes for vertex shaders that write the layer](../reference/rendering.md#layered-passes-for-vertex-shaders-that-write-the-layer) - a frame-time spike every few frames (the Metal HUD's frame-time line jumps by several ms at a regular interval) while the scene stands still; `DM_NVN_GPUPROF` over consecutive frames shows the slow frame with about 130 more render passes, each one draw into a 64x64 to 8x8 face of a cube or array level, and the next pass starting late. → [Passes into other layers of one texture level run as one layered pass](../reference/rendering.md#passes-into-other-layers-of-one-texture-level-run-as-one-layered-pass) - a GPU-bound frame with many passes on the same targets, one after the other, each preceded by a compute encoder of one dispatch (`DM_NVN_GPUPROF`: `compute / copy after pass … dispatches 1` between render passes of the same size); about 4 ms of GPU idle a frame inside command buffers in Metal System Trace. → [Compute dispatches between the draws of a pass run ahead of it](../reference/rendering.md#compute-dispatches-between-the-draws-of-a-pass-run-ahead-of-it) - a scene drawn only in a small square in the top-left corner of a black screen; speckled and blocky patches; a full-screen overlay showing one tile; the texture dump right after the scene pass shows the picture only in the corner, and `DM_NVN_HILITE` on the scene's shaders lights only the corner. → [Clears of attachments larger than the render pass](../reference/rendering.md#clears-of-attachments-larger-than-the-render-pass) - a point light (a lantern, a lighter) lights only one side of the room with straight, sharp edges, and everything else around it is dark as if in shadow; a dump of the shadow cube (DM_CTL `texraw`, every face) shows face 0 drawn and faces 1-5 all zero; more generally, layers above the first of an array, cube or 3D target keep their old or zero content after a clear. → [Clears of layered render targets in a pass that is not layered](../reference/rendering.md#clears-of-layered-render-targets-in-a-pass-that-is-not-layered) - `texture clear case not implemented … mask 0x1`. → [A channel mask that covers every channel is a whole clear](../reference/rendering.md#a-channel-mask-that-covers-every-channel-is-a-whole-clear) - `texture clear case not implemented … mask 0x8` while entering a rendered scene. → [Texture clears with partial channel masks or regions](../reference/rendering.md#texture-clears-with-partial-channel-masks-or-regions) - red lines for unimplemented mid-pass, partial-mask and partial-scissor clears (the clears were dropped); `depth-stencil clear with a scissor or partial stencil mask, cleared whole` (logged once). → [Clears inside a pass, with a partial mask or a partial scissor](../reference/rendering.md#clears-inside-a-pass-with-a-partial-mask-or-a-partial-scissor) - a pass loads a whole depth/stencil target every frame only to clear it: Donkey Kong Bananza clears a 2880x1620 Depth32F-S8 target with stencil mask `0x1`, before any pass is open, and loads 22.8 MB a frame for it. → [A depth clear over the whole target with a partial stencil mask](../reference/rendering.md#a-depth-clear-over-the-whole-target-with-a-partial-stencil-mask) - a tile grid in Ultrahand and Recall highlights; an `EQUAL` depth test rejects fragments writing the same depth as a cleared Depth16 target. → [Depth16 load-clears match fragment writes](../reference/rendering.md#depth16-load-clears-match-fragment-writes) - solid magenta blocks, exactly (255, 0, 255), hard-edged and aligned to the 16-pixel grid (16×16, sometimes two stacked): Super Mario 3D World and Super Mario Odyssey showed them only on the iPhone; Captain Toad and Origami King on a Mac, Apple M6, Captain Toad in about half the frames of the opening course, moving with the falling leaves. On an RG11B10F target (no alpha) the blocks are pure black or neon green, (0, 252, 0), and flicker, sometimes only part of a tile: Super Mario Bros. Wonder on an Apple M6 and an M1, most visible on the speech bubbles of dialogue; or non-finite pixels that bloom spreads into green blobs (NieR:Automata on the Mac). A rendered cutscene alternates brightness every game frame, with blocky bands of light and shadow switching on and off: each lighting-zone bit flips every frame (Xenoblade Chronicles 3, a read-only image load). → [Same-pass feedback read through a snapshot](../reference/rendering.md#same-pass-feedback-read-through-a-snapshot) - a scene full of deferred decals runs far below its target where the same scene with `DM_NVN_FB_SNAP=0` holds it, and the log's `same-pass feedback sampling: snapshot #…` count climbs by hundreds a frame. Tears of the Kingdom's first shrine on an iPad Pro 11 (M5): GPU p50 58.8 ms, about 15 fps, about 284 snapshots a frame (seedds/nxnative#737); Breath of the Wild on the Great Plateau, camera toward the Temple of Time, on an iPad Pro 13 (M4): 60 → about 42 fps, about 45 one-draw passes more a frame on the 1920×1080 G-buffer. Splatoon Raiders in inked stages on a MacBook Air (M2): GPU p50 22–26 ms against 11–14 ms in the hub, a one-draw pass and a whole-map snapshot of its 6400×6400 ink map (80 MB) for each ink stamp (seedds/nxnative#1063). The `[nvn] same-pass feedback up to frame …` line (every 300 frames) gives the snapshots, reuses and tile reads per frame. → [Same-pass feedback read from the tile](../reference/rendering.md#same-pass-feedback-read-from-the-tile) - the `[nvn] residency set up to frame …` line (every 300 frames) shows hundreds to thousands of additions from `fb_snap`'s line in `nvn_mtl.m`, gigabytes of them, and as many removals, with the residency commits' time and the submit thread's kernel time up. Tears of the Kingdom on an iPhone 17 (1.4.2, seedds/nxnative#931): 1,500-1,600 additions of 2.4 MB textures every 300 frames, residency commits 250-600 ms every 300 frames against about 25 in an older build, kernel time on the submit thread 1-2 ms a frame against 0.2. → [Snapshot textures taken by format and size](../reference/rendering.md#snapshot-textures-taken-by-format-and-size) - a scene with many bindless decals runs well below its target with the GPU busy, and a pass dump (`DM_NVN_PASSDUMP`) shows long runs of one-draw passes on the same targets, each loading and storing every attachment. Fire Emblem Fortune's Weave's battle maps: 31 consecutive one-draw passes on four 1024×576 targets a frame, 126.5 passes and about 1.4 GB of attachment loads and stores a frame. → [Bindless shaders taken as depth readers](../reference/rendering.md#bindless-shaders-taken-as-depth-readers) - a game that reads textures through a pool runs slower than its draws explain, with passes of one draw each on the same targets. A pass dump (`DM_NVN_PASSDUMP`) shows `SetRenderTargets` going on in the open pass and the pass ending anyway. Ocarina of Time in Kokiri Forest: two frames of four had 219 passes, 127 of them on the 128x128 reflection probe's cube faces, and frame times of 15, 15, 18, 18.5 ms in a cycle. → [Pool shaders taken as depth readers](../reference/rendering.md#pool-shaders-taken-as-depth-readers) - NaN texels in the upper levels of a texture the game fills level by level (each level drawn from the one above), and from there NaN wherever the texture is read: black speckles in whole 2×2 quads, white blotches once bloom spreads them, and a dark frame from the eye adaptation. → [Mip-chain pass sampling the level it renders](../reference/rendering.md#mip-chain-pass-sampling-the-level-it-renders) - bloom wide and hard around bright edges: neon letters swell into fat, filled shapes. With `DM_NVN_FB_SNAP=0` they are thin again, but the white blotches of the entry above come back. → [Upsample pass reading the level above the one it renders](../reference/rendering.md#upsample-pass-reading-the-level-above-the-one-it-renders) - text a game renders into textures for the title and the menus comes out upside down, while the scene looks right. → [Lower-left window origin](../reference/rendering.md#lower-left-window-origin) - geometry appears inside out and almost black; a fullscreen indirect-lighting triangle is entirely culled even though its vertex data and polygon state match the game. → [Queue initialization captures the raster origin](../reference/rendering.md#queue-initialization-captures-the-raster-origin) - a pink window with every command buffer ignored while headless runs look right: the first presents fail on the display command buffer with `kIOGPUCommandBufferCallbackErrorPageFault`, and after a few of those macOS ignores every submission of the process ("Ignored (for causing prior/excessive GPU errors)"). → [The residency set committed before a present](../reference/rendering.md#the-residency-set-committed-before-a-present) - `kIOGPUCommandBufferCallbackErrorPageFault` or `kIOGPUCommandBufferCallbackErrorHang` on a command buffer, and nothing says which draw or dispatch caused it; `DM_RES_CHECK=1` reports no `missing residency`. → [Naming the shaders of a GPU fault](../reference/rendering.md#naming-the-shaders-of-a-gpu-fault) - with present snapshots on (`DM_PRESENT_SNAP`, the iOS launcher's **Frame buffering**), a frozen, corrupted picture from the first presents; the first error is already `kIOGPUCommandBufferCallbackErrorSubmissionsIgnored` ("Ignored (for causing prior/excessive GPU errors)") on the display command buffer, then on every upload, segment and submission command buffer, and `[RED] present snapshots: the previous copy into a ring slot did not finish within 2 s`. With snapshots off the same game runs. → [A present snapshot's copy needs the same residency commit](../reference/rendering.md#a-present-snapshots-copy-needs-the-same-residency-commit) - an abort at the first present: `[RED] upload batches belong to the submit thread only: up_begin called on thread 'nvn-present-link'`, with `pkg_upload`, `tex_mtl` and `present_now` in the backtrace. → [A CPU-written window texture resolved where the present is queued](../reference/rendering.md#a-cpu-written-window-texture-resolved-where-the-present-is-queued) - a game that renders below the screen's resolution looks soft on a phone, in a large Mac window or on a 4K screen. → [The present upscales through MetalFX](../reference/rendering.md#the-present-upscales-through-metalfx) - in handheld mode the picture fills only two thirds of the screen's width and height, in the bottom-left corner (the top-left with the upper-left origin), the rest black. → [The NVN present crops by the vi layer crop](../reference/rendering.md#the-nvn-present-crops-by-the-vi-layer-crop) - a scene turns narrow, with black bars at its sides, while the swapchain or window textures keep their size; circles come out as tall ovals. The log has `vi::SetLayerCrop 0,0 1200x960` and `present upscaling: ... 1200x960 → 1800x1440` in a 2560x1440 window. → [A crop only picks texels; the picture has the layer's shape](../reference/rendering.md#a-crop-only-picks-texels-the-picture-has-the-layers-shape) - one-draw passes on one target, hundreds of times a frame, with the same attachments each time (a `DM_NVN_GPUPROF` frame: `load` and `store` of the whole target in every line); a low frame rate that follows the target's size. → [Setting the same targets again continues the pass](../reference/rendering.md#setting-the-same-targets-again-continues-the-pass) - a pass on a very large target costs about the same however little it draws; `DM_NVN_GPUPROF` shows time proportional to the target's area. → [A render area for passes on very large targets](../reference/rendering.md#a-render-area-for-passes-on-very-large-targets) - `[RED] NVN unimplemented function called: nvnCommandBufferShadingRateImagePalette`, or `nvnCommandBufferBindShadingRateImage` or `nvnCommandBufferSetShadingRatePaletteMode`, every frame. → [Variable rate shading ignored](../reference/rendering.md#variable-rate-shading-ignored) - angle-dependent character smearing, or vertex-only pipeline failures with `invalid depth/stencil pipeline formats 16843012/260`, although the pass began with valid `260/260` formats. → [Ten attachment records for eight colors and depth-stencil](../reference/rendering.md#ten-attachment-records-for-eight-colors-and-depth-stencil) - Metal aborts at pipeline creation: `depthAttachmentPixelFormat (MTLPixelFormatInvalid) and stencilAttachmentPixelFormat (MTLPixelFormatDepth32Float_Stencil8) must match`. → [Combined depth-stencil formats stay paired in passes and pipeline keys](../reference/rendering.md#combined-depth-stencil-formats-stay-paired-in-passes-and-pipeline-keys) - undefined values blended into attachments the fragment shader leaves alone. → [No writes to colour outputs the shader does not write](../reference/rendering.md#no-writes-to-colour-outputs-the-shader-does-not-write) - foliage, hair and fences drawn as solid quads (the parts the texture leaves transparent filled with its colour or black), dissolve effects solid instead of breaking up; once per run `SetAlphaRef …: the host has no alpha test`. → [The alpha test through a library of its own](../reference/rendering.md#the-alpha-test-through-a-library-of-its-own) - data a game builds in a target by combining draws comes out wrong; in Xenoblade Chronicles 2 indoor lighting has hard-edged dark boxes (world-space boxes in perspective, darker with the time of day) and lighter translucent rectangles elsewhere; in Skyward Sword HD a brown cast covers the distance and near objects turn into dark silhouettes, coming and going with the camera. A pass dump shows `lo=7` (or any value other than 3) on the `D` lines of the draws that write the target. → [Logic operations through a library of its own](../reference/rendering.md#logic-operations-through-a-library-of-its-own) - `nvnBlendStateSetAdvancedMode 8` (SRC_OVER) logged and blended with the state's own functions. → [Advanced blend modes as Porter-Duff factors](../reference/rendering.md#advanced-blend-modes-as-porter-duff-factors) - striped lighting: black and white bands that follow depth on every lit surface, as if every pixel were in or out of shadow at random. → [Stencil-mode texture views read through `X32_Stencil8`](../reference/rendering.md#stencil-mode-texture-views-read-through-x32_stencil8) - a character drawn as a dithered silhouette inside a dithered square (DRAGON QUEST VII Reimagined's hero). → [Stencil-mode textures from the texture builder](../reference/rendering.md#stencil-mode-textures-from-the-texture-builder) - `[nvn] SetConservativeRasterEnable on: ignored by host for now`, followed by `[RED] NVN unimplemented function called: nvnCommandBufferSetConservativeRasterDilate`. → [Conservative rasterization remains unimplemented](../reference/rendering.md#conservative-rasterization-remains-unimplemented) - characters (skinned models) invisible or stretched into streaks while the level renders; `vertex attribute format … does not match shader input type …` for a remaining mismatch. → [Integer vertex inputs](../reference/rendering.md#integer-vertex-inputs) - red lines 89 and 96 (`vconv_bind`, the CPU conversion every draw); about a quarter of Age of Calamity's replay thread in battle. → [Shadow vertex inputs](../reference/rendering.md#shadow-vertex-inputs) - an unsigned iOS build reports `[RED] pulling library ... not usable (no library)` and its draws wait for pipelines even with the profile's `pso_mtl4 on`, or packaging with `IOS_PULL=1` fails with `SKIPS[@]: unbound variable`. → [Pulling vertex inputs](../reference/rendering.md#pulling-vertex-inputs) - a fullscreen post-process draw writes no color, then a later blur composite darkens scenery while the character remains visible. → [Float32 vertex padding through integer inputs](../reference/rendering.md#float32-vertex-padding-through-integer-inputs) - `Vertex attribute m_36(5) of type uint4 cannot be read using MTLAttributeFormatHalf2` (draws dropped: black silhouettes); UVs collapse onto one texel (flat tan characters); vertices far out of view (negative 16-bit values widened with zeros). → [CPU conversion of vertex attributes the input type cannot take](../reference/rendering.md#cpu-conversion-of-vertex-attributes-the-input-type-cannot-take) - `[RED] BindVertexAttribState n=17`, tens of thousands of times, and a scene that draws wrong or not at all: the bind was refused, so the draws kept the previous layout. → [More than 16 vertex attributes](../reference/rendering.md#more-than-16-vertex-attributes) - `vertex attribute format … not mapped` (printed once). → [Vertex formats Metal lacks](../reference/rendering.md#vertex-formats-metal-lacks) - `[RED] BindVertexBuffers first=16 n=1` … `first=31`, thousands of times a run and no visible fault. → [Null vertex buffers bound past stream 15](../reference/rendering.md#null-vertex-buffers-bound-past-stream-15) - the assertion `buffer index (31) must be < 31`. → [Vertex streams 14 and 15 at Metal slots 14 and 15](../reference/rendering.md#vertex-streams-14-and-15-at-metal-slots-14-and-15) - Scaleform fills come out as solid white or light grey sheets over the whole screen, hard-edged triangles and bands, and the menu text is missing (a language list or a title screen that is all white behind its button prompt). → [Vertex streams at addresses that are not 4-byte aligned](../reference/rendering.md#vertex-streams-at-addresses-that-are-not-4-byte-aligned) - hard-edged translucent slabs and triangles over the scene that move with the camera, where a full-screen pass blends an effect in (Super Mario Odyssey: white wedges through the Cascade Kingdom's waterfall mist, one edge through the centre of the screen). → [Vertex fetches past a stream's bound size](../reference/rendering.md#vertex-fetches-past-a-streams-bound-size) - scenes and characters black, only foliage, light shafts and the HUD drawn; pass dumps full of `Z … draw skipped: no program bound`. → [Programs bound per stage](../reference/rendering.md#programs-bound-per-stage) - `[RED] failed to create render pipeline (vertex 790573a52b9c5053_b fragment f39fb42850f50ecd_b): Fragment input(s) user(locn0),user(locn1) … not written by vertex shader`, once on entering the first investigation; `texture type mismatch: shader declares a cube, texture is 2D` (a pixel shader run with another pair's bindings). → [Composite program taken again after a replay state restore](../reference/rendering.md#composite-program-taken-again-after-a-replay-state-restore) - `no program bound before the draw`, `program has no vertex shader` (a draw after a dispatch is dropped); `the dispatched program has no compute shader` (a dispatch after a graphics bind). → [Compute programs bound apart from graphics programs](../reference/rendering.md#compute-programs-bound-apart-from-graphics-programs) - a red line: the 8-bit index buffer had GPU-side writes in the submission (indices read stale). → [8-bit indices widened on the GPU after a write in the same submission](../reference/rendering.md#8-bit-indices-widened-on-the-gpu-after-a-write-in-the-same-submission) - indirect draws whose record the GPU writes earlier in the frame cannot be read on the CPU at replay; GPU-driven effects drawn as indirect quads, which Metal has no primitive for. → [Indirect draws and dispatches read by the GPU](../reference/rendering.md#indirect-draws-and-dispatches-read-by-the-gpu) - an empty G-buffer pass (the title screen showed only the UI); later, the submitting thread waiting for the GPU before each such draw (36–54 fps in Kamura Village on an iPhone). MIO also reported missing level geometry with maxima of 4,594 and 8,192 draws. → [Indirect-count multi-draws](../reference/rendering.md#indirect-count-multi-draws) - a hitch of a second or more as a level opens: a few frames of 330–540 ms whose submission takes 2–3 times its CPU time, and the wait ledger (`DM_NVN_WAITS=1`) shows thousands of indirect-count multi-draw waits for those frames only. → [CPU reads after a drain wait only for later writes](../reference/rendering.md#cpu-reads-after-a-drain-wait-only-for-later-writes) - a black screen while the frame loop runs at full rate, with `[RED] NVN unimplemented function called: nvnCommandBufferDrawTexture`; once drawn, the picture alternates frame by frame between the right image and another texture's (a solid colour, a still image). → [`nvnCommandBufferDrawTexture`](../reference/rendering.md#nvncommandbufferdrawtexture) - the HUD and sky render but the battle's characters and terrain are absent; the replay logs `draw skipped: rasterizer discard` between model draws. → [Rasterizer discard preserves vertex storage writes](../reference/rendering.md#rasterizer-discard-preserves-vertex-storage-writes) - exploding meshes and displaced model parts after vertex-only work; native post-vertex captures can contain valid positions for some meshes while other palettes are incorrect. → [Primitive barriers order vertex storage writes](../reference/rendering.md#primitive-barriers-order-vertex-storage-writes) - a character's mesh stretched for one frame into a long wedge or sheet that reaches another character, and other characters missing in that frame; intermittent (about one frame in a hundred near a group of characters). A pass dump shows `barrier bits 0x1 (render pass open)` before vertex-only draws (`fs=-`, `discard=1`) that bind a storage buffer `rw` which the draws before them read `ro`. → [Ordering barriers before a draw that writes](../reference/rendering.md#ordering-barriers-before-a-draw-that-writes) - characters collapsed into one thin spike (vertex streams read from feedback buffers that were never written); a character covered by a solid box while it moves (its fur shells pulled toward lagged positions that were never written); a pass dump shows draws with a vertex shader and no fragment shader (`fs=-`) before the draws that read them, and `Y tf begin … written 0/0/0/0` with no `T … tf capture` line. → [Transform feedback captured by a vertex entry point](../reference/rendering.md#transform-feedback-captured-by-a-vertex-entry-point) - a scene drawn with a geometry shader per mesh runs at 5 to 15 fps on the Mac, with the submitting thread or the GPU taking most of the frame. → [Geometry-shader draws encoded a run at a time](../reference/rendering.md#geometry-shader-draws-encoded-a-run-at-a-time) - `SIGSEGV` in `-[AGXG18GFamilyComputeContext_mtlnext performEndEncoding]` (from `rp_begin_ex_`, or in its `dealloc` on the encoding thread); Metal validation (`MTL_DEBUG_LAYER=1 MTL_DEBUG_LAYER_ERROR_MODE=nslog`) names it: "Command buffer already has an open command encoder". → [Helper encoders end the open copy encoder first](../reference/rendering.md#helper-encoders-end-the-open-copy-encoder-first) - the whole picture upside down (Absolum's title logo and "Press Any Button" mirrored top to bottom); a red-reporting stub for `nvnCommandBufferSetViewportSwizzles`. → [Viewport swizzles applied as a flipped viewport](../reference/rendering.md#viewport-swizzles-applied-as-a-flipped-viewport) - on an Unreal Engine game with a full GPU, moving sprites flicker black for a frame: cut straight across, or a whole silhouette in the sprite's outline. It follows GPU time against the frame budget, and goes away at 30 fps or with GPU time to spare. The black is already in the scene colour the base pass writes. → [Black shapes on sprites when Unreal's GPU work runs late](../reference/rendering.md#black-shapes-on-sprites-when-unreals-gpu-work-runs-late) - a `sample` of the submit thread shows `ubo_read` calling `-[MTLBuffer contents]` with `objc_retainAutorelease` at every handle read, and `objc_autoreleasePoolPop` at commit draining those buffers. Fire Emblem Fortune's Weave: about 4 % of the submit thread in the reads and as much again in the drain. → [Bindless handles read from guest memory directly](../reference/rendering.md#bindless-handles-read-from-guest-memory-directly) - `[RED] texture→texture copy case not implemented: 1920x1080x1→1920x1080x1 flags 0 format 260→252 3D 0→0`. → [Depth plane copies between depth formats](../reference/rendering.md#depth-plane-copies-between-depth-formats) - `FATAL deferred encoding: DmRecEnc has no stand-in for -copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:` with Metal encoding on its own thread (`DM_NVN_ENC_THREAD=1`, the default on iOS), at the first depth plane copy. → [Depth plane copies on the encode thread](../reference/rendering.md#depth-plane-copies-on-the-encode-thread) - a scene opens near white and fades to its normal colours over several seconds, at each scene change, while the settled picture is right. → [Pending clears land before a compute dispatch](../reference/rendering.md#pending-clears-land-before-a-compute-dispatch) - a regular lattice of dots over the ground, and the light wrong: three of four layers of an interleaved ambient occlusion array stay empty, while the draws and their bindings look right. → [`[[primitive_id]]` in a specialized Metal 4 pipeline](../reference/rendering.md#primitive_id-in-a-specialized-metal-4-pipeline) - with Metal 4 pipelines on (`DM_PSO_MTL4=1`), the iOS app crashes before its first frame, right after `pipeline prewarm list … lines`: `CRASH sig=11 pc=objc_release+0x10`, `bt: objc_autoreleasePoolPop warm_task __warm_prepare_block_invoke`, on several prepare workers at once. The Mac runs the same pipelines. → [A specialization descriptor iOS 26.0 returns autoreleased](../reference/rendering.md#a-specialization-descriptor-ios-260-returns-autoreleased) - a Switch 2 game calls `nvnCommandBufferEvaluateDlss` and its builder functions, which the host did not have. → [NVN2's DLSS on MetalFX](../reference/rendering.md#nvn2s-dlss-on-metalfx) - `[RED] NVN unimplemented function called: nvnDlssNetworkResize (x0=… x1=0x300 x2=0x1b0)` at the title. → [The DLSS network resized](../reference/rendering.md#the-dlss-network-resized) - a Switch 2 game's frame in its heavy scenes is dominated by one compute dispatch between the render-resolution passes and the output-resolution ones: Donkey Kong Bananza's upscaler takes 3.5-5 ms of a 24 ms GPU frame on an M1 in handheld mode (960x540 → 1920x1080, `DM_NVN_GPUPROF`), and the game cannot reach its 60 fps interval there. → [A game's own upscaler drawn by MetalFX](../reference/rendering.md#a-games-own-upscaler-drawn-by-metalfx) - with `DM_UPSCALER=metalfx`, a game's picture is washed out wherever it upscales: lifted shadows and low contrast, the scene only, with the UI drawn after it correct; with `DM_UPSCALER=game`, or at a size the game does not upscale, it is right. → [An upscaler's colour read from its code](../reference/rendering.md#an-upscalers-colour-read-from-its-code) - tall blue / textured panels that flickered frame to frame: the fountain's vertex shader pushed the water surface to the top of the screen. → [Metal 4 does not order operations inside one encoder](../reference/rendering.md#metal-4-does-not-order-operations-inside-one-encoder) - a buffer copy, inline update or fill completes, but a following copy through another Metal buffer over the same allocation reads stale bytes. → [Buffer copies through aliased Metal addresses](../reference/rendering.md#buffer-copies-through-aliased-metal-addresses) - many render passes with one draw each and high submit time: Metroid Dread's cutscene frames had about 180 passes with one draw each (about 5 ms of submit time per frame on the Mac). → [Inline uniform updates inside a render pass](../reference/rendering.md#inline-uniform-updates-inside-a-render-pass) - hundreds of render passes a frame and heavy attachment traffic when a game updates a small part of a large uniform block before each draw group. → [Partial-cover uniform shadows keep passes open](../reference/rendering.md#partial-cover-uniform-shadows-keep-passes-open) - a scene runs at 20–27 fps where similar ones hold 60, with the GPU time about three times its usual (draw counts unchanged). The `residency set` line shows `passes ended to land them for a read` in the tens of thousands, every one `refused … other GPU writes`, and about three times the usual `load-all store-all passes`. A burst of 1,200 such refusals at each world load is the short form. → [A storage buffer bound with size 0 counted as a write anywhere](../reference/rendering.md#a-storage-buffer-bound-with-size-0-counted-as-a-write-anywhere) - the `residency set` line shows `passes ended to land them for a read` in the tens of thousands, every one `refused … earlier submission running`. The slower the GPU, the more passes, and each pass makes it slower: a scene stays at a very low frame rate once it falls in. → [Inline updates of a running submission refused uniform shadows](../reference/rendering.md#inline-updates-of-a-running-submission-refused-uniform-shadows) - `stage 0 cb5 has no uniform buffer bound` (or another stage and slot, such as `stage 0 cb0`), once per run. → [An unbound uniform slot reads the zero bank](../reference/rendering.md#an-unbound-uniform-slot-reads-the-zero-bank) - GPU time per frame doubles with many small dispatches (Age of Calamity: GPU 9 → 18 ms a frame on the Mac; the iPhone's 15 → 51 ms, 17 fps). → [Compute dispatches share the copy encoder](../reference/rendering.md#compute-dispatches-share-the-copy-encoder) - dialog boxes with holes the size of their text, and white specks where text faded. → [Fragment-ordering barriers between draws that write images](../reference/rendering.md#fragment-ordering-barriers-between-draws-that-write-images) - a texture copied from a staging buffer shows another texture's blocks (Catherine: Full Body's cutscene subtitle band a hard-edged dark box with a magenta stroke through it). → [A segment committed after a buffer → texture copy](../reference/rendering.md#a-segment-committed-after-a-buffer--texture-copy) - a scaled texture copy skipped with a red line (Metal blits cannot scale); format-changing, depth-stencil and mirrored copies. → [Copies a blit cannot do, drawn](../reference/rendering.md#copies-a-blit-cannot-do-drawn) - `[RED] Downsample case not implemented: 320x176 1 samples format 70 → 80x48`; a missing bloom. → [`Downsample` of a single-sample texture](../reference/rendering.md#downsample-of-a-single-sample-texture) - no ambient occlusion (Mac); on a device the result depends on whatever that memory holds. → [Depth-stencil copies carry the stencil](../reference/rendering.md#depth-stencil-copies-carry-the-stencil) - `DM_NVN_GPUPROF=every:1` prints no per-frame reports and fills its timestamp heap across frames. → [Periodic GPU profiles close at frame boundaries](../reference/rendering.md#periodic-gpu-profiles-close-at-frame-boundaries) - with `DM_NVN_GPUPROF`, the host aborts minutes in on `-[AGXG16XFamilyComputeContext_mtlnext writeTimestampWithGranularity:afterStage:intoHeap:atIndex:]: unrecognized selector`, `up_flush` on the stack; or a profiled render pass with a wrong GPU time. → [GPU profiles stamp only the encoder they began](../reference/rendering.md#gpu-profiles-stamp-only-the-encoder-they-began) - the 3D scene black (targets cleared again before they are read); `[RED] SetRenderEnableConditional: the host draws anyway`; with a game that skips clears under render conditions, scenes black behind the HUD (Mario vs. Donkey Kong's levels, 1.0.1). → [Conditional rendering evaluated at replay](../reference/rendering.md#conditional-rendering-evaluated-at-replay) - with `render_cond`, a 3D scene black or missing behind the HUD, only in scenes with many occlusion queries; a pass dump shows conditions reading `values 1 / 0` on a record a report of the same submission has just written, and clear-only passes on targets just drawn to. Scenes with fewer queries are fine. → [Report tables that dropped entries](../reference/rendering.md#report-tables-that-dropped-entries) - `[RED] visibility slots exhausted`. → [Query slots running out inside a pass](../reference/rendering.md#query-slots-running-out-inside-a-pass) - no SPIR-V file in the RomFS; SPIRV-Cross refuses a module with "Struct member does not have ArrayStride set". → [Vulkan shaders generated at run time](../reference/rendering.md#vulkan-shaders-generated-at-run-time) - a crash in `bind_res` reading a freed view's texture (Super Mario Galaxy 2 on an iPhone, element 1 of the 8-texture array, when the ship took off after the first galaxy; GitHub issue 68). → [Descriptors hold the Metal objects they were written with](../reference/rendering.md#descriptors-hold-the-metal-objects-they-were-written-with) - Metal refuses a pipeline with "Fragment shader does not write to render target color(0), index(1) that is required for blending"; the Metal 4 specialization path can instead abort after `MTLCompilerService` crashes in `AGCLLVMStatelessFragmentObject::buildBlendFactor`. → [An unwritten secondary blend source](../reference/rendering.md#an-unwritten-secondary-blend-source) - the host aborts on Metal's compiler queue (`findOrCreateComputeFastClearPipeline`, `[AGX] Failed assertion "error == MTLCompilerErrorNoError"`) seconds into the game, with or without the pipeline prebuild, while `MTLCompilerService` crash reports show `EXC_BAD_ACCESS` in `llvm::ExtractElementInst` under `AGCLLVMStatelessFragmentObject::buildBlendFactor` (`AGCLLVMStatelessPSODynamicLibrary::compile`). → [A written secondary blend source (NVN dual-source blending)](../reference/rendering.md#a-written-secondary-blend-source-nvn-dual-source-blending) - adding a pixel shader to the profile's `dual_want.tsv` leaves the build reporting cache hits, the reflection without `entry_d`, and the host logging `[RED] shader ... has no dual-source entry point`. → [A shader added to `dual_want.tsv` keeps its cached build](../reference/rendering.md#a-shader-added-to-dual_wanttsv-keeps-its-cached-build) - Metal refuses the pipeline: "Fragment shader does not write to render target color(0), index(1)". → [Dual-source blending from output location 1](../reference/rendering.md#dual-source-blending-from-output-location-1) - Metal's validation aborts on a buffer layout no mapped attribute uses. → [Scaled and three-component vertex formats](../reference/rendering.md#scaled-and-three-component-vertex-formats) - menus 1.5x too big in handheld mode (the file-creation dialog cut off at the right edge). → [Viewport and scissor persist across render passes](../reference/rendering.md#viewport-and-scissor-persist-across-render-passes) - `draw outside a render pass`; the rest of the pass was dropped. → [Copies inside a render pass](../reference/rendering.md#copies-inside-a-render-pass) - an assert (a stripped trap, `main+0x4d26e0`) when the surface does not list `preTransform` INHERIT. → [Swapchain pre-transform and layer crop](../reference/rendering.md#swapchain-pre-transform-and-layer-crop) - a pipeline with no Metal pipeline state, and its draws missing. → [Specialization constants](../reference/rendering.md#specialization-constants) - a crash in `set_free` from `vkFreeDescriptorSets` as a game leaves. → [What a game tears down that it should not](../reference/rendering.md#what-a-game-tears-down-that-it-should-not) - `[RED] occlusion query outside a render pass or past the buffer`; a query's result stays 0. → [Occlusion queries that span render encoders](../reference/rendering.md#occlusion-queries-that-span-render-encoders) - a call to address 0 at boot. → [`VK_EXT_debug_report`](../reference/rendering.md#vk_ext_debug_report) - GX points and lines drawn as one-pixel points and lines. → [Not translated in the Vulkan layer: geometry shaders](../reference/rendering.md#not-translated-in-the-vulkan-layer-geometry-shaders) - `UNIMPL eglGetDisplay`, then `Break` right after `nv::InitializeGraphics` and `vi::OpenDefaultDisplay` (`main+0x5ed9d0`). → [Games that render with desktop OpenGL through EGL](../reference/rendering.md#games-that-render-with-desktop-opengl-through-egl) - the app closes with no message of its own, `[dm] CRASH sig=11 addr=0 pc=0` and a guest return address inside `main` (Well Dweller: `lr=main+0x3409a78`, the same address every time); `DM_GL_STUBS=1` then names the call: `[RED] glFlush called: not implemented, returns 0`. → [`glFlush` hands the frame so far to the GPU](../reference/rendering.md#glflush-hands-the-frame-so-far-to-the-gpu) - `UNIMPL glCreateShader` returns 0, followed by `UNIMPL glShaderSource`, `glCompileShader`, `glGetShaderiv` and `glGetShaderInfoLog`; the game crashes in `sdk` with a null shader handle even though EGL initialized. → [Direct GL imports use the same implementations as the loader](../reference/rendering.md#direct-gl-imports-use-the-same-implementations-as-the-loader) - the NSP script's provisional profile said Vulkan, and the capture boot crashed in the GL layer. → [Telling a GL game from an NVN or Vulkan one](../reference/rendering.md#telling-a-gl-game-from-an-nvn-or-vulkan-one) - the game draws thousands of vertices per frame and the window shows text only; a sprite scene is black while its text layer is perfect. → [Draws from client memory](../reference/rendering.md#draws-from-client-memory) - the NSP script took the game for an OpenGL one (`main imports EGL and names glShaderSource`), the GL shader capture found no shader, and the capture boot stopped with `[nvn-mtl] FATAL cannot read the shader map` from `h_nvnQueueSubmitCommands` called in an NRO (`nro8+0xc10d0`). → [NVN in NROs under an SDL main that names GL](../reference/rendering.md#nvn-in-nros-under-an-sdl-main-that-names-gl) - the NSP script took the game for an OpenGL one (`main imports EGL and names glShaderSource`) and translated 2 GL shaders; the game boots with sound and answers input, but the window stays black, and the log has `[nvn-mtl] [RED] shader … is not in the shader map` for every shader it makes, with no EGL call at all. → [NVN and its own GLSLC under a main that also links EGL](../reference/rendering.md#nvn-and-its-own-glslc-under-a-main-that-also-links-egl) - a jump to address 0 right after `glGetFloatv(0xb12)` (`lr=main+0x2d58c4`). → [Which GL functions a game calls](../reference/rendering.md#which-gl-functions-a-game-calls) - in a capture run every program links with no uniforms; the game's first `Shader:send` raises a Lua error and, on the Switch, its error handler quits (Any Lua error quits a LÖVE game). → [GL shaders put together at run time and captured](../reference/rendering.md#gl-shaders-put-together-at-run-time-and-captured) - an image-only fragment draw's writes disappear from the subresource also bound as its color attachment when the pass ends; other image layers retain their writes. → [Image stores into an attachment of their own pass](../reference/rendering.md#image-stores-into-an-attachment-of-their-own-pass) - read-only depth/stencil attachments are written back after every pass, and the periodic unwritten-store savings counter remains zero with the default configuration. → [Unwritten attachment stores without lookahead](../reference/rendering.md#unwritten-attachment-stores-without-lookahead) - portrait gameplay overlaps the touch controls, touch coordinates land outside the game picture, or a TV's picture renders at 4K again after a layout pass. → [iOS layouts: portrait, a half-folded Duo, iPad windows](../reference/rendering.md#ios-layouts-portrait-a-half-folded-duo-ipad-windows) - with *Picture shape* at 1.43:1 (`DM_SCREEN_ASPECT`) the game renders 1920x1344, but on an iPhone Duo in Fit (the default) the picture comes out smaller than the 16:9 one, with black bars on all four sides; it fills the screen only in Fill. On the Mac a click lands off the point under the pointer (it was mapped on a 16:9 rectangle of the window). → [The picture laid out in the shape the game presents](../reference/rendering.md#the-picture-laid-out-in-the-shape-the-game-presents) ## Shaders - the split finds no shaders, and the RomFS is one huge file with a short name (`42`) whose bytes look random past a table at its start (magic `CRA.`). → [One scrambled archive indexed by the NRO](../reference/shaders.md#one-scrambled-archive-indexed-by-the-nro) - the split finds only a small part of a game's shaders, with no `[RED]` line, and its RomFS holds files that start `NARC` (`.narc`, `.nptl`, `.ntex` on Mario Tennis Aces). → [Packed shader banks in loose NARC files](../reference/shaders.md#packed-shader-banks-in-loose-narc-files) - the split finds no shaders in `main` or RomFS, while reporting control sections in `main` with no code area. The game has `.sp4` resources and loose `.nvnbin` files rather than BNSH archives or whole GLSLC outputs. → [Sumo Ninty_NX shaders and MuxFDMR streams](../reference/shaders.md#sumo-ninty_nx-shaders-and-muxfdmr-streams) - the shader split finds no game programs despite loose `.fx.phyre` effects and multi-GB `.vbf` archives. → [Phyre NVN effects in Virtuos VBF archives](../reference/shaders.md#phyre-nvn-effects-in-virtuos-vbf-archives) - the shader split stops on one archive with a Python traceback (an `IndexError` or `struct.error` naming no file), or a reader's `[RED]` line about a format it does not know, and nothing is written; the NSP script loses the build at the split. → [A file no reader reads](../reference/shaders.md#a-file-no-reader-reads) - a black screen after the loading text; the split prints `[RED] /init.dict: the index (… header 04 04 03 00 …) is not in the layout of Luigi's Mansion 3's archives` for 878 of 879 archives and keeps only the 40 shaders of `main`, and the run prints `[RED] shader … is not in the shader map` for the programs the game draws with. → [Next Level Games archives of revision 4](../reference/shaders.md#next-level-games-archives-of-revision-4) - the split leaves out archives whose members do not overlap: `[RED] <file>/<member>.szs/#7: the archive members add up to more than 16 times the file (members that overlap)`, then `[RED] <n> file(s) could not be read`, and a registered profile's build stops there. → [A Yaz0 member that expands is not overlap](../reference/shaders.md#a-yaz0-member-that-expands-is-not-overlap) - `shader_split.py` finds 0 shaders in a RomFS of zstd files named `.zst`. → [Zstd files recognised by their magic](../reference/shaders.md#zstd-files-recognised-by-their-magic) - the game asks for shaders the map does not have (`[RED] shader ... is not in the shader map`, hundreds of lines), and the split finds far fewer shaders than the game uses (121 against 27,288 on Kirby and the Forgotten Land). → [HAL's `.cmp` containers: a size-prefixed frame](../reference/shaders.md#hals-cmp-containers-a-size-prefixed-frame) - the split finds almost no shaders and reports `[RED] /Archive/<name>.bea: entry 0 @0x4854535341 is not an ASST entry (its shaders are left out)` for every archive (`… file(s) could not be read`); the "offset" is the bytes `ASSTH`. → [Bezel Engine 2.9 archives keep their entries inline](../reference/shaders.md#bezel-engine-29-archives-keep-their-entries-inline) - a provisional split finds only a fraction of the shaders (3,126 of Pokémon Sword's 41,516). → [BNSH entries of GFPAK archives](../reference/shaders.md#bnsh-entries-of-gfpak-archives) - the split counts hundreds of files as unreadable (678 on Pokémon Legends: Arceus), each with `[RED] <file>.gfpak: entry 0 has compression 3 (Oodle), which this reader does not decode`, and leaves their shaders out. → [Oodle entries of GFPAK archives](../reference/shaders.md#oodle-entries-of-gfpak-archives) - the split found no shader in the game (0 shaders). → [GLSLC outputs holding several stages](../reference/shaders.md#glslc-outputs-holding-several-stages) - an NVN game's split finds none of its shipped shaders, and the ones it compiles at run time were not captured: the game's renderer is in NROs that call `glslcCompile`, and its whole RomFS is one zip. → [GLSLC outputs in a zip archive, and those NROs compile at run time](../reference/shaders.md#glslc-outputs-in-a-zip-archive-and-those-nros-compile-at-run-time) - a Switch 2 game whose split finds no shader: the RomFS holds `Asset/assets_a000.dat` (magic `PDAT`, 16.6 GB) and `Asset/assets.cat` (magic `PARC`, a table of 64-bit ID hashes), and the first boot stops on `cannot read the shader map`. → [PMAP records in phx's PDAT archives](../reference/shaders.md#pmap-records-in-phxs-pdat-archives) - a Switch 2 game's RomFS is one `data.zip` that does not start with a zip's local header, zipfile reads a member of it only to stop on `Bad CRC-32`, and the split finds no shader: every member is listed as stored, yet most are smaller on disk than their file size. → [LZ4-chained zip members behind a VZIP preamble, and shader binaries of one stage](../reference/shaders.md#lz4-chained-zip-members-behind-a-vzip-preamble-and-shader-binaries-of-one-stage) - an NVN game's split finds a few dozen shaders (`main`'s and a loose file's) and the screen stays black but for the loading indicator, with `[RED] shader … is not in the shader map` and `program has no vertex shader`; the RomFS holds `.BNDL` files that start with `bnd2`. → [GLSLC outputs in Criterion's Bundle 2 resources](../reference/shaders.md#glslc-outputs-in-criterions-bundle-2-resources) - 24 shaders before the control-length fix, 1,355 after. → [SPKG packages in KTGL LINKDATA](../reference/shaders.md#spkg-packages-in-ktgl-linkdata) - the split finds almost none of a KTGL Switch 2 game's shaders: the G2S containers in its RDB entries yield nothing, and its programs name no packaged shader. → [KTGL on NVN2: Switch 2 GLSLC outputs and LD_ / LI_ LINKDATA](../reference/shaders.md#ktgl-on-nvn2-switch-2-glslc-outputs-and-ld_--li_-linkdata) - the NSP script stops at `the shader split found no shaders in main or the RomFS` on a game whose `main` imports `glslcCompile` and whose RomFS is one or two `.pak` files. → [GLSLC outputs in base64 in Heaps' shader cache](../reference/shaders.md#glslc-outputs-in-base64-in-heaps-shader-cache) - only movies render, while the 3D scene reports missing shaders and programs without a vertex stage; the shader split finds loose programs but misses those in `Shaders/Shaders.arc.gz`. → [Gzip-wrapped shader archives](../reference/shaders.md#gzip-wrapped-shader-archives) - the NSP script stops at its GLSLC capture with `captured only 0 run-time shaders`, after the game ran the whole capture normally, on a game whose `main` imports `glslcCompile`, with a `.vert` or `.frag` file in its RomFS. → [Encrypted `.vert` and `.frag` files are no run-time GLSL](../reference/shaders.md#encrypted-vert-and-frag-files-are-no-run-time-glsl) - every frame black, the title screen included, while the game runs at full rate and draws (about 19,000 NVN calls a frame), with `[RED] shader … is not in the shader map` (26 keys in the first minute) and `program has no vertex shader`; the dumped shaders (`DM_NVN_SHDUMP`) match no file byte for byte, and some differ from a split shader only in the control section's compile information (+0x7d0), which is a sign of another GLSLC compile of the same source, not of a shared section. → [Gust's chunked zlib `.gz` files](../reference/shaders.md#gusts-chunked-zlib-gz-files) - the split finds no shaders in a RomFS made of `.sdfdata`, `.sdftoc` and `.sdfver` files. → [Shader records in Snowdrop SDF data slices](../reference/shaders.md#shader-records-in-snowdrop-sdf-data-slices) - the survey finds no shader container in a RomFS of `.toc` and `.cas` files (`Data/NX`, `Patch/NX`, `Data/layout.toc`, `Data/initfs_NX`); the split reads every file loosely and finds nothing. → [CompiledBytecode resources in Frostbite superbundles](../reference/shaders.md#compiledbytecode-resources-in-frostbite-superbundles) - `[RED] ... PKZ version 0x10000: only 0x20000 is known` stops the shader split. → [PKZ version 1 archives](../reference/shaders.md#pkz-version-1-archives) - the split finds zero shaders and refuses the shader build, although the CPK's DAT archives contain the objects passed to NVN at boot. → [Size-delimited PlatinumGames shader objects](../reference/shaders.md#size-delimited-platinumgames-shader-objects) - archive or loose asset shaders are absent from the map; only boot shaders in `main` are found, sometimes reported as raw controls with no identified code area. → [Monolith ARH1, XBC1 and HCPS/SLCT shader containers](../reference/shaders.md#monolith-arh1-xbc1-and-hcpsslct-shader-containers) - the split finds no shaders, although `main` contains NVN control sections; it reports that no data record or code-address pair identifies their code areas. → [Needle shader containers in main and GFD archives](../reference/shaders.md#needle-shader-containers-in-main-and-gfd-archives) - shaders the game draws are missing from the map (`DM_NVN_SHDUMP`), in no RomFS file and no module, stored or LZ4, and not compiled at run time. → [Shaders in a zlib stream in main (YEBIS .tfxo)](../reference/shaders.md#shaders-in-a-zlib-stream-in-main-yebis-tfxo) - two `[RED] shader … is not in the shader map` lines and `program has no vertex shader` as the opening movie starts; every movie drew white. → [Loose control sections and code areas in main (Bink 2)](../reference/shaders.md#loose-control-sections-and-code-areas-in-main-bink-2) - the provisional split finds only `main`'s 294 GLSLC outputs; the 3D scene and the title logo are magenta, with `[RED] shader … is not in the shader map` lines. → [SNVN program records in Retro Studios' RFRM forms](../reference/shaders.md#snvn-program-records-in-retro-studios-rfrm-forms) - the NSP script's split stops with `[RED] 24 file(s) could not be read`, each `an XNB effect without an MGFX version 8 effect of NVN shaders`. → [MGFX version 5 effects (MonoGame 3.0)](../reference/shaders.md#mgfx-version-5-effects-monogame-30) - `[RED] 1 file(s) could not be read, their shaders are left out (first: Data/resources.assets: error: unpack_from requires a buffer of at least 96 bytes for unpacking 96 bytes at offset 0 (actual buffer size is 0))` from the shader split, and the game's built-in shaders in that file missing at run time. → [Unity compute kernels with no code](../reference/shaders.md#unity-compute-kernels-with-no-code) - `failed to create render pipeline` with a fragment `user(locn1)` input missing from the vertex output, while the split found all shaders but almost no vertex / pixel pairs. → [Legacy Unity stages lose their pass partners](../reference/shaders.md#legacy-unity-stages-lose-their-pass-partners) - the split stopped with `no bundle has a Shader type tree of the same hash to borrow`. → [Unity Shader layouts written out for players without bundles](../reference/shaders.md#unity-shader-layouts-written-out-for-players-without-bundles) - the 3D battle scene was black behind a correct UI, with `[RED] shader 854a8afc9d07f88d is not in the shader map` and `the dispatched program has no compute shader`. → [Unity ComputeShader objects](../reference/shaders.md#unity-computeshader-objects) - black, jagged holes in the ground of a map (whole tiles of the terrain mesh missing while others draw), with about 25 distinct `[RED] shader … is not in the shader map` keys and `program has no vertex shader`, on a Unity game whose `Shader` objects all split cleanly. → [GLSLC outputs in a Unity TextAsset](../reference/shaders.md#glslc-outputs-in-a-unity-textasset) - `[RED] the shader split found no shaders in main or the RomFS`, the split's log ending in `shaders: 0`, and no `UE shader decode` step, on a game whose container holds shader libraries and whose pak names `GlobalShaderCache-`: from 2026-11-04 until issue #1277 was fixed, such a pak counted as inline. → [Unreal Engine 5.6 IoStore shader libraries](../reference/shaders.md#unreal-engine-56-iostore-shader-libraries) - `ValueError: …/Glow-Switch_0_P.utoc: shader group 0 has no chunk` from `uepak.py io_archive` while the NSP script decodes the shaders (`decode_ue_shaders`, after `[4/8] UE shader decode`). → [IoStore patch containers keep their shader groups in the base container](../reference/shaders.md#iostore-patch-containers-keep-their-shader-groups-in-the-base-container) - `[RED] …/Nicola-Switch_0_P.pak: the index is encrypted and no window of main decrypts it` from the NSP script before `[5/8] UE shader decode` (the message now reads `no key in main (a 32-byte window or two 16-byte literals its code stores together) decrypts it`). → [An Unreal pak key split into two 16-byte literals](../reference/shaders.md#an-unreal-pak-key-split-into-two-16-byte-literals) - `the RomFS has Unreal paks, but none … holds a shader code archive`, then `the shader split found no shaders in main or the RomFS`. → [Unreal Engine 4.27 shaders inline in cooked packages (LZ4)](../reference/shaders.md#unreal-engine-427-shaders-inline-in-cooked-packages-lz4) - `the RomFS has Unreal paks, but none … holds a shader code archive` from the NSP script, on a game with a `.pak` beside a `.utoc` and `.ucas`. → [Unreal Engine 4.27 shaders inline in IoStore export bundles](../reference/shaders.md#unreal-engine-427-shaders-inline-in-iostore-export-bundles) - the shader split reports `the game's decoder in the Mac host failed on a 8 → 30650 byte stream`, the host's output says `asked to decode Legacy compressor; not supported!`, and a run of the NSP script stops with `file(s) could not be read` (a provisional profile goes on without those shaders). → [An entry of a package's export list read as an Oodle shader table](../reference/shaders.md#an-entry-of-a-packages-export-list-read-as-an-oodle-shader-table) - `shaders: 0` from the split, with no red line, on a game whose pak holds `Engine/GlobalShaderCache-SP_GLSL_SAGE.bin` (`Sage` is the engine's name for the platform). → [Unreal Engine 5.4 shaders for the Switch 2](../reference/shaders.md#unreal-engine-54-shaders-for-the-switch-2) - `[RED] the shader split found no shaders in main or the RomFS`; the survey counts the game's Unreal paks, but no `UE shader decode` step runs and the split reads none of them. → [Unreal Engine 4.22 to 4.25 paks (version 8)](../reference/shaders.md#unreal-engine-422-to-425-paks-version-8) - `the shader split found no shaders in main or the RomFS`; the survey lists the RomFS as cooked packages (`.xxx`) and `.usm` movies only. → [Unreal Engine 3 shader caches (Oodle packages)](../reference/shaders.md#unreal-engine-3-shader-caches-oodle-packages) - `[RED] shader <key> is not in the shader map` for shaders whose code is in a `.bfsha` the split reads, `[RED] NVN unimplemented function called: nvnCommandBufferDrawMeshTasksIndirect`, and grass and ferns missing. → [Task and mesh shaders in BNSH, and indirect mesh draws](../reference/shaders.md#task-and-mesh-shaders-in-bnsh-and-indirect-mesh-draws) - a Switch 2 game's picture is far too bright and warm wherever the view opens out: lifted blacks, yellow skin, a pale veil. The build log has `Invalid reduction type: F32FtzRn`, easy to miss among thousands of lines. → [Float atomics in storage memory](../reference/shaders.md#float-atomics-in-storage-memory) - dotted horizontal rows in blocks of the picture, in smooth and blurred areas, from a Switch 2 game's upscaler: the frame before it is clean and the frame after it is not. The same input gives a different picture each run. Bright scenes show more of them. → [textureGatherOffsets and a loop over its offsets](../reference/shaders.md#texturegatheroffsets-and-a-loop-over-its-offsets) - `Ampere instruction 243 at 0x… is not implemented`, or `ISBERD mode b8 in a task or mesh shader`, in the build. → [F2IP](../reference/shaders.md#f2ip) - when an AV1 movie starts, `[RED] shader <key> is not in the shader map` for 11 compute shaders and `[RED] the dispatched program has no compute shader (or it is not mapped)`. → [`nn::ndve`'s movie enhancement file](../reference/shaders.md#nnndves-movie-enhancement-file) - `draw skipped: no render pipeline (vertex - fragment -)` in a game's final passes; shaders "not in the shader map", all from `agl_ndsr.pck`. → [The NDSR pack's record start](../reference/shaders.md#the-ndsr-packs-record-start) - shaders reported missing at random, and their dumped control sections are garbage (Unity). → [Program keys computed inside `nvnProgramSetShaders`](../reference/shaders.md#program-keys-computed-inside-nvnprogramsetshaders) - `[RED] shader … is not in the shader map` for shaders whose control section and code area are both in the game files, but in different records: dumped (`DM_NVN_SHDUMP`), the control section is one record's and the code area another's. → [Control sections shared among shaders that differ only in their compile information](../reference/shaders.md#control-sections-shared-among-shaders-that-differ-only-in-their-compile-information) - 12 compute shaders (particles, post effects) translated into an endless loop that hung the GPU at the first gameplay scene; SPIRV-Cross failed on 7 shaders instead of 2 (SPIRV-Cross parse failures). → [Exact program start for the decoder](../reference/shaders.md#exact-program-start-for-the-decoder) - GLSLC outputs fail the reader's check and are dropped (44 of DARK SOULS: REMASTERED's `main`'s 72 outputs and most of its archives' pixel shaders). → [GLSLC outputs read through their section headers](../reference/shaders.md#glslc-outputs-read-through-their-section-headers) - `shader_split.py` finds no stage for vertex shaders and stops at the first captured output (`no GLSLC output`). Translated, every post pass and the window draw one texel's colour (a black screen with sound); every varying at (0, 0, 0, 1). → [VertexA and VertexB parts merged into one vertex shader](../reference/shaders.md#vertexa-and-vertexb-parts-merged-into-one-vertex-shader) - a shader build accepts tools that differ from `dmsh_chain.lock`; after an override build, returning to the tested Metal compiler can still restore the override's libraries. → [Tested tools and compiler-specific shader caches](../reference/shaders.md#tested-tools-and-compiler-specific-shader-caches) - after an Xcode update the build stops with `[RED] this Mac's Metal compiler is not the one the shaders were tested with (dm/gfx/tools/dmsh_chain.lock): metal_macosx Apple metal version 32023.922 …`; `xcodebuild -downloadComponent MetalToolchain`, as the message said, downloads the same untested compiler again. → [Metal compiler of a newer Xcode](../reference/shaders.md#metal-compiler-of-a-newer-xcode) - `regress.py` waits for other jobs to end while the only reported jobs are sleeping `MSBuild.dll /nodemode:1 /nodeReuse:true` workers using 0% CPU. → [Idle MSBuild workers block regression measurements](../reference/shaders.md#idle-msbuild-workers-block-regression-measurements) - SPIRV-Cross can't parse the SPIR-V (`nullptr` exception). → [SPIRV-Cross parse failures](../reference/shaders.md#spirv-cross-parse-failures) - `Fragment input(s) user(locnN) mismatching vertex shader output type(s) or not written by vertex shader` and the draw is skipped; the host reports `[RED] failed to create render pipeline (vertex … fragment …)`. Offline packing fails with `pso_offline: metal-tt failed` for the same reason. → [Pixel shader inputs the vertex shader does not write](../reference/shaders.md#pixel-shader-inputs-the-vertex-shader-does-not-write) - outdoors dim and nothing casts a sun shadow (every shadow-map lookup fails). → [Unwritten components of a written output start as (0, 0, 0, 1)](../reference/shaders.md#unwritten-components-of-a-written-output-start-as-0-0-0-1) - rows of dark dots along contour lines of alpha-tested surfaces drawn after a depth pre-pass (Tears of the Kingdom: the stone lattice in front of the Great Sky Island start, as reported by MacNativeGames ae8f4f4; not reproduced here). → [Early fragment tests from the control section](../reference/shaders.md#early-fragment-tests-from-the-control-section) - a simulation or filter that reads neighbouring texels misbehaves though every constant is right. In the translated MSL a variable is declared with no value and read at once (`int _139; int _141 = _139;`), used as a coordinate. On Ocarina of Time: grass whose blades shift at 10 Hz, with a 6-frame cycle in the depth buffer and a wind velocity texture of strong stripes. → [Dead-code removal dropped a coordinate of a multi-output instruction](../reference/shaders.md#dead-code-removal-dropped-a-coordinate-of-a-multi-output-instruction) - the ground kept stale 32×32 blocks where the G-buffer draw failed the depth test: blocks of a stale image where a depth pre-pass and a later pass with other vertex shaders meet (Odyssey: 32×32 blocks on every fourth frame). → [Position invariance across shaders](../reference/shaders.md#position-invariance-across-shaders) - making a pipeline archive prints `Max Unstruct ID 758 in function agc.main in shader 13941 exceeds supported limit`, and one pipeline takes many minutes, in `metal-tt` offline or in the host's prebuild on the device (`Preparing pipelines` holding one count for minutes). The line is a note, not an error: `metal-tt` goes on, exits 0 and writes that pipeline into the archive. → [Front end at -O1: Apple's control-flow lowering](../reference/shaders.md#front-end-at--o1-apples-control-flow-lowering) - the half of Mario facing the camera's left was white (GitHub issue 72, on an iPhone). → [min, max and clamp with a NaN operand](../reference/shaders.md#min-max-and-clamp-with-a-nan-operand) - a pipeline red line for a float output meeting an integer attachment (the red line prints the row to add); a BC encoder's pipeline fails. → [Integer fragment outputs declared by hand](../reference/shaders.md#integer-fragment-outputs-declared-by-hand) - `failed to create render pipeline … output of type float4 is not compatible with a MTLPixelFormatR32Uint color attachment` (or `MTLPixelFormatRGBA16Uint`); every draw into the target skipped. → [Integer entry points for integer colour outputs](../reference/shaders.md#integer-entry-points-for-integer-colour-outputs) - a deferred scene with part of its materials unlit or black: grass, ground and trees dark while wood and characters look right, whole areas of a map black. There may be no red line. A texture dump shows an integer G-buffer target (`fmt=73`, RGBA8Uint) holding only zeros, and the lighting pass reads it. Since this entry, `[RED] shader … writes colour target …, an integer format, as a float`. → [Integer outputs told from float bits](../reference/shaders.md#integer-outputs-told-from-float-bits) - `failed to create render pipeline … Cannot convert attribute …`; draws missing (a pipeline that fails to build). → [Integer-typed vertex inputs fed normalized formats](../reference/shaders.md#integer-typed-vertex-inputs-fed-normalized-formats) - outdoors the whole screen blurred (depth of field out of focus everywhere). → [Depth mode near = 0 needs the per-mode entry points](../reference/shaders.md#depth-mode-near--0-needs-the-per-mode-entry-points) - `SPIRV-Cross threw an exception: Subgroup builtins are not available in this type of function`. → [Subgroup operations rewritten for a one-lane subgroup](../reference/shaders.md#subgroup-operations-rewritten-for-a-one-lane-subgroup) - the tone mapper read an empty LUT and the screen came out a flat blue. → [Geometry shaders that only pick the layer](../reference/shaders.md#geometry-shaders-that-only-pick-the-layer) - `[RED] NVN unimplemented function called: nvnCommandBufferDrawMeshTasks`, and a build that fails with `Ampere instruction 927 ... is not implemented` in shaders the map calls vertex or domain; what they draw is missing. → [NVN2 task and mesh shaders](../reference/shaders.md#nvn2-task-and-mesh-shaders) - large flat panels in front of the sky, the clouds behind them blinking at times, in some places and not others. In a `DM_NVN_PASSDUMP_ALL` dump every task and mesh shader's storage buffer shows as `st3` / `st4 sbufp reg6` or `reg7` `dummy addr=0 size=0`, though the game binds buffers for those stages. → [Task and mesh draws reading the dummy buffer](../reference/shaders.md#task-and-mesh-draws-reading-the-dummy-buffer) - a geometry shader fails to compile with `unknown main0_out`: SPIRV-Cross writes `unknown main0_out main0()` for the geometry stage, and the shader does not build. → [Geometry shaders with no Metal stage](../reference/shaders.md#geometry-shaders-with-no-metal-stage) - the models a passthrough geometry shader draws are missing: its own draw (a depth prepass) shows nothing, and so do the draws that test against that depth for equality. Before the shader loaded at all, the same models showed as black silhouettes. → [Passthrough geometry shaders](../reference/shaders.md#passthrough-geometry-shaders) - `[geometry failed] missing geometry topology buffer` in the build, then `[RED] shader … (geometry) failed to load` and those draws skipped. → [The topology table passed to a helper function](../reference/shaders.md#the-topology-table-passed-to-a-helper-function) - the host's memory watchdog closes the game (at 28.3 GB on Kirby Air Riders, whose Switch 2 has 9 GB), with the Metal heap full of frame arena blocks of 36 or 72 MB; it comes on quickly in a scene full of ribbons. → [A captured draw's vertex IDs far apart](../reference/shaders.md#a-captured-draws-vertex-ids-far-apart) - geometry reader compilation fails with undeclared `gl_BuiltIn_5253` and a scalar `.elements` access. Compiling only the compute kernel also leaves native passthrough geometry without emitted vertices. → [Geometry passthrough and viewport masks in compute](../reference/shaders.md#geometry-passthrough-and-viewport-masks-in-compute) - sorting repeated mesh indices consumes much of the render thread's CPU time. → [Geometry capture indices deduplicated with a bounded bitset](../reference/shaders.md#geometry-capture-indices-deduplicated-with-a-bounded-bitset) - later geometry uses stale shader-written data or appears in the earlier draw's position when draws are combined into a geometry run. → [Geometry runs retain external buffer dependencies](../reference/shaders.md#geometry-runs-retain-external-buffer-dependencies) - the CPU spends substantial replay time checking dependencies among geometry jobs that share many read-only buffers. → [Geometry dependency checks skip read-only pairs](../reference/shaders.md#geometry-dependency-checks-skip-read-only-pairs) - a game whose frames are mostly geometry-shader draws stays GPU-bound by attachment traffic: a `DM_NVN_GPUPROF` frame shows hundreds of two-draw render passes (each geometry draw, then the reopened pass of its raster) and gigabytes of attachment loads and stores, and no `geometry hoist` line ever appears in the log. → [An empty vertex stream kept every geometry draw out of a run](../reference/shaders.md#an-empty-vertex-stream-kept-every-geometry-draw-out-of-a-run) - geometry-heavy rendering spends substantial GPU time compacting the geometry shader's emitted indices. → [Parallel geometry index compaction](../reference/shaders.md#parallel-geometry-index-compaction) - the geometry kernel compiles, but its `_bgv.metal` vertex reader fails with `use of undeclared identifier 'gl_BuiltIn_5253'` and `member reference base type 'int' is not a structure or union`. → [Geometry reader viewport masks](../reference/shaders.md#geometry-reader-viewport-masks) - a passthrough geometry kernel writes beyond its vertex and raw-index scratch regions, and compaction reads the wrong groups; corruption can reach the following primitive-map buffers without a red diagnostic. → [Passthrough geometry output bounds follow input topology](../reference/shaders.md#passthrough-geometry-output-bounds-follow-input-topology) - a geometry kernel compiles and runs its storage-buffer side effects, but contains no `geometry_vb_output` binding and fills its index stream with restart markers; its following raster pass draws no geometry. → [Passthrough geometry kernels lose raster vertices](../reference/shaders.md#passthrough-geometry-kernels-lose-raster-vertices) - geometry-heavy frames have a large submission wall/CPU gap despite short GPU execution; stack samples spend most of the main thread in `geo_draw` → `mdi_wait` → shared-event wait, with index sorting another substantial cost. → [Geometry capture waits for every indexed draw](../reference/shaders.md#geometry-capture-waits-for-every-indexed-draw) - geometry-heavy frames remain GPU-bound after CPU readback waits are removed; encoder timestamps attribute most compaction time to the offset scan rather than the geometry shader or index writes. → [Geometry compaction serial prefix scan](../reference/shaders.md#geometry-compaction-serial-prefix-scan) - `[RED] geometry draw needs 261 MiB of scratch, above the 256 MiB bound` (or `exceeds the capture or invocation bound`); the draw is skipped. → [Geometry draws above the capture scratch bound](../reference/shaders.md#geometry-draws-above-the-capture-scratch-bound) - a geometry shader that reads `PrimitiveID` repeats its visibility decisions or storage addresses after a large draw is split into compute dispatches. → [Split geometry primitive IDs](../reference/shaders.md#split-geometry-primitive-ids) - a large geometry draw crashes in `geo_split` / `memcpy` while reading indices, sometimes preceded by `geometry draw exceeds the capture or invocation bound` for an unexpectedly small child draw. → [Recursive geometry splits retain their original draw range](../reference/shaders.md#recursive-geometry-splits-retain-their-original-draw-range) - geometry draws with transform feedback report `geometry draw cannot capture this pipeline` and write no feedback records after the geometry-job integration. → [Geometry jobs preserve transform-feedback replay](../reference/shaders.md#geometry-jobs-preserve-transform-feedback-replay) - geometry-heavy frames are GPU-bound on the emulation itself. A `DM_NVN_GPUPROF` frame shows, for every geometry draw, a capture pass (`0x0 0c`), a compute encoder and a one-draw reopening of the game's pass, with most of the frame's GPU time in the first two. → [Passthrough geometry shaders drawn by the vertex shader](../reference/shaders.md#passthrough-geometry-shaders-drawn-by-the-vertex-shader) - a pale blue wash over every 3D scene with atmosphere; the HUD is clean, and the albedo and normal targets are right. A 3D table (`texraw`) has data in plane 0 only, and the pass that fills it has no `L … layered pass` line and draws with `gs=-`. → [A passthrough geometry shader that writes the layer](../reference/shaders.md#a-passthrough-geometry-shader-that-writes-the-layer) - a passthrough geometry shader that uses `PrimitiveID` makes different visibility decisions or storage writes after the first 32 triangles when composed into a mesh shader. → [Mesh geometry primitive IDs restart per group](../reference/shaders.md#mesh-geometry-primitive-ids-restart-per-group) - after a pair is added to `geo_mesh.tsv`, `[RED] geometry mesh pipeline: ... Total mesh size (37248) exceeds the maximum mesh size allowed (32768)`, and the frames that draw the pair get much slower than on the compute path (Donkey Kong Bananza: translation from about 10 to 22–31 ms a frame). → [Mesh geometry groups sized to the vertex output](../reference/shaders.md#mesh-geometry-groups-sized-to-the-vertex-output) - a depth prepass of many small geometry-shader draws, drawn as mesh draws, leaves the GPU nearly idle: the per-pass profile (`DM_NVN_GPUPROF`) shows an idle gap before the pass that grows with its draw count (about 2.3 µs a draw), and the GPU counters show vertex-only time at about 4 % occupancy. → [Mesh geometry draws gathered into one dispatch](../reference/shaders.md#mesh-geometry-draws-gathered-into-one-dispatch) - `primitive type 14 not implemented`; patch draws skipped. → [Tessellation stages are not drawn](../reference/shaders.md#tessellation-stages-are-not-drawn) - a Switch 2 game's shaders do not translate (the translator reads Maxwell: 64-bit instructions behind scheduling words, a 0x50-byte SPH), or, rewritten as Maxwell code, UI text draws as solid boxes or not at all. → [Ampere shader code (Switch 2)](../reference/shaders.md#ampere-shader-code-switch-2) - a lit pass far slower on an M1 than the M4 Pro's figures suggest, the time spread over every material that loops over the scene's lights; dropping one material's draws (`DM_NVN_UB`) saved only its share. → [Storage words read one by one](../reference/shaders.md#storage-words-read-one-by-one) - `reflection conversion failed: B binding cp_i_cb3_0_ has no resolved slot number` at load, then `the dispatched program has no compute shader`; in the build, `SUATOM handle in bank 3` or `SURED handle in bank 3`, and bindings of an unrecognized kind for a typed buffer. Compute passes are skipped. → [Images and buffer textures with their handle in a uniform buffer](../reference/shaders.md#images-and-buffer-textures-with-their-handle-in-a-uniform-buffer) - a scene lit black with correct geometry. In `DM_NVN_PASSDUMP`, the lighting shader's bindings show `tex … tid=0 dummy` where the G-buffer should be, and a sampler bound where a texture is expected. → [Texture and sampler words in either order](../reference/shaders.md#texture-and-sampler-words-in-either-order) - objects from a compute-built list flicker: each is in one of two states, on and off irregularly and independently of the others, while the draws are the same frame to frame and the camera is still. Whole groups may vanish or appear in one frame and stay that way until the list's next rebuild. Shots of consecutive frames show the change per frame jumping between two levels. → [A store only a dispatch's first invocation makes](../reference/shaders.md#a-store-only-a-dispatchs-first-invocation-makes) - `metal` runs for hours on a shader of about 100 MB of MSL, mostly indentation, stuck in LICM (`hoistRegion` → `ScalarEvolution::forgetValue`), then the GPU compiler's connection breaks; even `-O0` and finished libraries crash it. Hundreds of forced one-pass loops nest around the program. → [Goto elimination forcing loops around a whole program](../reference/shaders.md#goto-elimination-forcing-loops-around-a-whole-program) - `BRX with no target`, or code about 20 % larger than it should be. → [Ampere jump tables read past their end](../reference/shaders.md#ampere-jump-tables-read-past-their-end) - `Ampere instruction 308` refused; a neural upscaler's programs missing, so the frame never reaches the window (a black 3D scene). → [MUFU.F16](../reference/shaders.md#mufuf16) - a compute shader's results in shared memory land in the wrong elements, or only part of its memory is cleared. An exposure histogram came back with its bins at about four times their index, the scene several stops too dark. → [Scaled shared memory addresses](../reference/shaders.md#scaled-shared-memory-addresses) - `[RED] failed to create compute pipeline: Threadgroup memory size (49152) exceeds the maximum threadgroup memory allowed (32768)`, thousands a run; the dispatch is skipped. → [Compute shared memory past 32 KB](../reference/shaders.md#compute-shared-memory-past-32-kb) - `[RED] shader <key>_b reflection conversion failed: fetch call 0: frag_pos uniform reference out of range`; the shader does not load and its draws are skipped. → [Uniform references past the first kilobyte](../reference/shaders.md#uniform-references-past-the-first-kilobyte) - the GPU hangs (`kIOGPUCommandBufferCallbackErrorHang`) from the first 3D scene on, or frames of about 88 ms, in a shader with a half-float loop. → [HADD2 and HMUL2 with an immediate](../reference/shaders.md#hadd2-and-hmul2-with-an-immediate) - wrong shading where a shader needs a cross product or a 2D rotation of half pairs; on Eden-NS2, which first read the mode as a plain negation of the high lane, sun and cloud shadows were lost. → [HFMA2 .H0_NH1](../reference/shaders.md#hfma2-h0_nh1) - none in the log: everything drawn with an engine's scene data lands on the first instance's transform, or at nothing. In the MSL, a bounds-checked read has a constant index (`vp_s2._m0[0]`) just after a comparison of the register it should use. → [A guarded load whose destination is its address](../reference/shaders.md#a-guarded-load-whose-destination-is-its-address) - the scene goes white with a yellow fringe: a few objects hold the largest value their target can, and bloom spreads it over the picture. Clamping a shader's terms one by one finds a value that is a register's stale contents. Or characters lit from an environment cube turn bright white in certain places only, and the cube's mean is far above its value elsewhere. → [A deferred write under a false guard](../reference/shaders.md#a-deferred-write-under-a-false-guard) - `Ampere instruction f63` (or `f6c`, `364`, `367`) `is not implemented`, or `SURED form 0310e000`, in the build. → [Ampere forms with a handle in a register, and SURED's other operations](../reference/shaders.md#ampere-forms-with-a-handle-in-a-register-and-sureds-other-operations) - `Ampere instruction 21b at … is not implemented` (`…0405721b`) or `Ampere instruction 925 at 0x0 is not implemented` (`040e0200000e4000 …7925`) in the build. → [Ampere BMSK and the read of a covered pixel](../reference/shaders.md#ampere-bmsk-and-the-read-of-a-covered-pixel) - no wrong picture seen so far. In the MSL, a shader with a 0x886 vote has `if (false)` and `false ? a : b` where a uniform predicate guards a value or a branch, and a lane guard on the same number reads `simd_all` or `simd_any` of its own predicate. → [VOTEU writes the uniform predicate](../reference/shaders.md#voteu-writes-the-uniform-predicate) - `[RED] <key>: the translator deleted N bindless accesses` in the build (Losses a shader build reports; `Failed to find handle source for bindless access` in its reflection's notes), for a shader with TXD through a uniform register (0xf6c). The MSL has no gradient sample, and what it read comes back 0. → [TXD through a uniform register kept no handle](../reference/shaders.md#txd-through-a-uniform-register-kept-no-handle) - `Failed to find handle source for bindless access` in the build's translator notes, for a read whose handle is two words of the game's own uniform buffer, and what it read comes back 0. Or nothing in the log: the read binds `fp_t_cb3_<word>` or `fp_t_cb2_<word>`, a texture word with no sampler word, so its sampler is `samp_tex`'s guess, where the shader's other reads of that word bind both. → [Handles built under a guard the read's guard cannot be tied to](../reference/shaders.md#handles-built-under-a-guard-the-reads-guard-cannot-be-tied-to) - `no member named 'gl_PointSize' in 'main0l_out'` and `does not compile` in the build, which still exits 0, then `[RED] <key>: its library builds only without its layer entry points` (Losses a shader build reports). A slice-writing geometry shader on it logs `has no layer entry points`. → [Layer entry points with the point size passed by reference](../reference/shaders.md#layer-entry-points-with-the-point-size-passed-by-reference) - in the build's log, `[RED] <key>: the translator deleted N bindless accesses (<type> N): their results read 0` or `[RED] <key>: its library builds only without its layer, integer output, dual source entry points`, and `[RED] lost without failing: …` with the counts per kind (the NSP script repeats that one line). In `regress.py`, `NEW-FAIL: N shaders with more … than in the baseline`. → [Losses a shader build reports](../reference/shaders.md#losses-a-shader-build-reports) - `Ampere instruction 80d ... (000fc80003fe0000c43211110000780d) is not implemented` for every vertex shader of the game, so nothing draws. → [A guard band cull in every vertex shader (0x80d)](../reference/shaders.md#a-guard-band-cull-in-every-vertex-shader-0x80d) - `Ampere instruction <op> at 0x… is not implemented`, `F2FP.MERGE_C` or `F2I from a float that is not 32-bit` in the shader build; those shaders are left out and their draws and dispatches skipped. → [Ampere instructions new in Pokémon Pokopia](../reference/shaders.md#ampere-instructions-new-in-pokémon-pokopia) - single bright dots at thin far geometry (railings, track edges), changing frame to frame as the camera moves, already in the lit picture before anti-aliasing. Most of them come from another cause (below). → [Comparisons with .FTZ](../reference/shaders.md#comparisons-with-ftz) - `Ampere instruction f55 at 0x… (000fe20000000000000000001a0f7f55) is not implemented` in the shader build; those shaders are left out. → [Barrier moves around warp shuffles](../reference/shaders.md#barrier-moves-around-warp-shuffles) - `Ampere b82 at 0x…: LDC with a bindless bank or an address mode (…00008a00…7b82)` in the shader build; those shaders are left out. → [LDC with the bank in its address register (`.IS`)](../reference/shaders.md#ldc-with-the-bank-in-its-address-register-is) - 64-bit arithmetic in a shader gives wild results: the 64-bit division behind an exposure average returned 893011 for 218, so the exposure stayed at the end of its range. With only the pair fixed it still gave 2 for 340 / 1. → [IMAD.HI adds a register pair, and IMAD.X its carry](../reference/shaders.md#imadhi-adds-a-register-pair-and-imadx-its-carry) - a scene lit by many small lights comes out too dark, with its clustered light lists empty for most clusters. → [NVN2 compute reads its workgroup counts at c0 + 4](../reference/shaders.md#nvn2-compute-reads-its-workgroup-counts-at-c0--4) - `Ampere instruction 361` (or `f60`, `370`, `38d` and others) refused, or hundreds of `Failed to find handle source for bindless access of type "textureCube"` when the handle was taken from the wrong register: units drawn white, the rest of the scene right. → [Texture handles of SDK 22's Ampere code](../reference/shaders.md#texture-handles-of-sdk-22s-ampere-code) - `reflection conversion failed: B binding cp_t_cb196610_10280074Smplr has no resolved slot number` at load, then `the dispatched program has no compute shader`; the shader's image has no slot either (`cp_i_tcb_AA_`). → [NVN2 compute's separate handles in c[0]](../reference/shaders.md#nvn2-computes-separate-handles-in-c0) - `reflection conversion failed: B binding fp_t_cb2_170 has no resolved slot number` at load (the draw is skipped), the build summary counting the binding under *slot was not decoded*; or, once the read's other inputs are known, `Failed to find handle source for bindless access of type "texture2D"` and the read answers 0. `DMSH_BINDLESS_TRACE=1` on a `dmsh_xlate` job prints what a refused handle is made of. → [A handle pair ORed sampler word first](../reference/shaders.md#a-handle-pair-ored-sampler-word-first) - a Switch 2 game's frame rate swings between 60 and 30 fps (Donkey Kong Bananza's own controller, `main+0x204a18`, drops to 30 after two frames of 20 ms from their start to the GPU's end, and comes back after six), and the GPU profile (`DM_NVN_GPUPROF`) shows one compute dispatch of 2-6.5 ms a frame: agl's upscaler network (`agl_ndsr.pck`, shader `7629d857a0a93833`). → [Ampere HMMA through simdgroup_matrix](../reference/shaders.md#ampere-hmma-through-simdgroup_matrix) - a vertex or compute shader reads zeros from NVN's driver segment `c0`. → [Driver-segment reads outside fragment shaders](../reference/shaders.md#driver-segment-reads-outside-fragment-shaders) - flickering hard-edged white tiles (tiled lighting with every tile row getting row 0's or other rows' lights). → [Compute `c0`: dispatch size and uniform buffer table](../reference/shaders.md#compute-c0-dispatch-size-and-uniform-buffer-table) - `[RED] shader ... reflection conversion failed: B binding gp_s0 has no resolved slot number`; a geometry shader reading driver segment `c0` reports that its storage-buffer table base was never measured. → [Geometry-stage storage buffer table](../reference/shaders.md#geometry-stage-storage-buffer-table) - a storage buffer the shader stores to or uses atomically has `rw: false` in its generated reflection; replay does not record its GPU writes for dependent buffer reads. → [Storage-buffer write flag in translation metadata](../reference/shaders.md#storage-buffer-write-flag-in-translation-metadata) - point sprites of size 0 (Odyssey's Cap Kingdom fog never parted around Mario). → [Graphics `c0 + 0x610`: the largest point size](../reference/shaders.md#graphics-c0--0x610-the-largest-point-size) - occlusion queries that always return 0 samples (Z-A: characters' legs folded back from the hips once they walked); every instanced draw's transform taken for instance 0. → [Graphics `c0 + 0x644`: the draw's base instance](../reference/shaders.md#graphics-c0--0x644-the-draws-base-instance) - flat grey or background-coloured triangles with straight edges across part of the scene, changing shape from frame to frame while the camera stands still; dropping the colour pass's fragment shaders in groups (`DM_NVN_SKIP_FS`) did not remove them, as the instances are misplaced in the depth pre-pass too, whose depth the colour pass tests for equality. → [The base instance of indirect draws comes from Metal](../reference/shaders.md#the-base-instance-of-indirect-draws-comes-from-metal) - `[RED] shader … reflection conversion failed: reads driver-bank locations at run time that the replay layer cannot fill: c0 dynamic index c0+0x630`, and that shader's draws are missing; the build notes `Shader instruction Pixld is not implemented` for pixel shaders; `[RED] NVN unimplemented function called: nvnProgramSetSampleShading`. → [Pixel `c0 + 0x620`: the sample index and GLSLC's sample position table](../reference/shaders.md#pixel-c0--0x620-the-sample-index-and-glslcs-sample-position-table) - a menu's labels drawn as plain bars, other menus empty except for the cursor (one pool's textures overwritten by another's); a black screen when IDs past a fixed table read as empty slots. → [Texture and sampler pools with overlapping IDs](../reference/shaders.md#texture-and-sampler-pools-with-overlapping-ids) - red lines from the list of command buffers that bound a non-first pool (6,734 in one DARK SOULS: REMASTERED run). → [Bases of bound handles kept in the command buffer](../reference/shaders.md#bases-of-bound-handles-kept-in-the-command-buffer) - distant walls and floors smeared sideways (DARK SOULS: REMASTERED): tiling textures took a clamp-to-edge sampler and repeated their edge column. → [Handles from uniform buffers take the bound pools' bases](../reference/shaders.md#handles-from-uniform-buffers-take-the-bound-pools-bases) - the 3D scene black, only particles and the HUD drawn; pass dump `B` lines all `tid=0 dummy`. → [Deferred texture binds read at execution](../reference/shaders.md#deferred-texture-binds-read-at-execution) - bindless handles read from a uniform buffer name the wrong texture when the game writes them earlier in the same submission. → [Handles in uniform buffers written earlier in the same submission](../reference/shaders.md#handles-in-uniform-buffers-written-earlier-in-the-same-submission) - a storage buffer reported with `cb_slot` 3, which had no NVN slot. → [Storage buffer addresses in the game's own uniform buffer](../reference/shaders.md#storage-buffer-addresses-in-the-games-own-uniform-buffer) - whatever a shader writes through a pointer it read from memory never happens. The build summary counted `Failed to find storage buffer for global memory operation "Store"`, and the shader's MSL had a store function with an empty body. In Donkey Kong Bananza the tunnel's walls and floor were black and only the loose rocks drew. → [Global memory at an address loaded from memory](../reference/shaders.md#global-memory-at-an-address-loaded-from-memory) - `no resolved slot number`, the shader does not load; the translation has a 32-entry texture-pool array (`fp_t2d_cb0_40000000`, handle type Direct). → [Bindless handles through a loop phi](../reference/shaders.md#bindless-handles-through-a-loop-phi) - none in the log: texture reads come back 0. Particle meshes collapse to a point (their scale reads 0), so effects are missing or show as dark patches. The translator's own message (`Failed to find handle source for bindless access of type "textureBuffer"`) used to be dropped, because `dmsh_xlate`'s accessor had no `Log`; its messages now go into the shader's notes, marked `translator: `, and the build summary counts them apart from unanswered queries. → [Bindless reads whose handle phi also carries other values](../reference/shaders.md#bindless-reads-whose-handle-phi-also-carries-other-values) - the shaders' bindless arrays have no slot and used not to load; the translator falls back to a 32-entry array such as `array<texture_buffer<float>, 32> vp_tb_cb0_40000000`. → [Texture slots picked at run time](../reference/shaders.md#texture-slots-picked-at-run-time) - Ryujinx's fallback arrays (`fp_t2d_cb0_40000000`) in pixel shaders whose handle comes from the game's own uniform buffers; the shaders do not load and their draws are skipped. → [A texture chosen at run time between two uniform-buffer handles](../reference/shaders.md#a-texture-chosen-at-run-time-between-two-uniform-buffer-handles) - `[RED] shader … reflection conversion failed: a texture handle the translator could not trace to one slot (profile key tex_dyn_slots off)`, then `failed to load`, and the draws are skipped: in Mario Party Superstars every character and NPC in a lit scene is a flat grey silhouette (the depth pre-pass draws, the colour pass does not), and the opening scene's pipe is grey. → [Texture handles from game memory index the pools](../reference/shaders.md#texture-handles-from-game-memory-index-the-pools) - the host stops at the shader's first load: `unexpected argument buffer layout: encodedLength=640 maxAid=48`. → [An array of handles in a uniform buffer](../reference/shaders.md#an-array-of-handles-in-a-uniform-buffer) - characters and other moving objects have almost no ambient light: lit only from where the sun reaches, black underneath, while the scenery around them is right. Nothing is red. On Kirby Air Riders a dark red Kirby on a bright course, where the game's own tutorial movie shows him bright pink. → [A table of handles longer than the array](../reference/shaders.md#a-table-of-handles-longer-than-the-array) - `reflection conversion failed: B binding fp_t2ds_cb196614_10570000 has no resolved slot number`, then `failed to load`; those draws are skipped, and the scene is dark or black where it is lit by them. → [An array of uniform-buffer handles with its sampler word in c2](../reference/shaders.md#an-array-of-uniform-buffer-handles-with-its-sampler-word-in-c2) - characters shaded black; a shader indexes a table of cube maps, and every element it reads clamps to the array's last one, which holds no handle. → [A table of handles past the array's length](../reference/shaders.md#a-table-of-handles-past-the-arrays-length) - `shaders with a binding whose slot was not decoded 588`; shadow cascades read through `array<texture2d_array<float>, 32> fp_t2das_cb2_0`. → [An array of handles from the driver table c2](../reference/shaders.md#an-array-of-handles-from-the-driver-table-c2) - `[RED] shader … reflection conversion failed: B binding fp_t2d_cb196610_10570000 has no resolved slot number`, then, with that resolved, `… reads driver-bank locations at run time that the replay layer cannot fill: c2 dynamic index`; the shader does not load and its draws are skipped. → [Arrays of c2 handles cover the whole table, with a separate sampler word](../reference/shaders.md#arrays-of-c2-handles-cover-the-whole-table-with-a-separate-sampler-word) - characters and props glowing white, about 10⁴ too bright, in DRAGON QUEST VII Reimagined's opening cutscene only, while walls and gameplay look right. → [A texture slot that shares its c2 word with an image slot](../reference/shaders.md#a-texture-slot-that-shares-its-c2-word-with-an-image-slot) - `[RED] texture type mismatch: shader … declares slot 128 as Metal type 2, texture ID … is type 7 (NVN target 2, …); bound as is`, for a shader whose MSL has a `texture3d` and a `texture2d` on the same register and only calls `get_width` / `get_height` on the `texture2d`. → [A size query on a 3D texture gets a 2D slot](../reference/shaders.md#a-size-query-on-a-3d-texture-gets-a-2d-slot) - `[RED] shader … reflection conversion failed: 66 bindings, over the limit 64`, then `failed to load`, and the draws with it are dropped (a black map). → [More than 64 bindings in one shader](../reference/shaders.md#more-than-64-bindings-in-one-shader) - the host stops at a shader's first load: `FATAL shader … has an unexpected argument buffer layout: encodedLength=88 maxAid=8` (crash in `c1_store` / `pull_load`), with a storage buffer or image missing from its reflection json. → [Argument buffer members with attributes after their id](../reference/shaders.md#argument-buffer-members-with-attributes-after-their-id) - the replay put a texture resource ID where the shader wanted an address; with the old 64 KB dummy buffer, pointers in the game's objects and in the host's program objects got their upper 4 bytes replaced and the game or the replay crashed, or `kIOGPUCommandBufferCallbackErrorPageFault`, after which macOS ignores the process's command buffers (GitHub issue #101). Later, `[RED] image atomics on a block-linear texture … not followed, the atomics go to a scratch buffer`, and compute shaders with atomics on a 3D image did not build (`array subscript is not an integer`). → [Image atomics](../reference/shaders.md#image-atomics) - `image atomics: unsupported or overflowing IMG extent` at the first dispatch, despite a valid four-byte counter buffer. → [Buffer image reflection keeps its texture type](../reference/shaders.md#buffer-image-reflection-keeps-its-texture-type) - `[RED] image atomics on a texture Metal cannot run them on`, and whatever the shader computes through them is lost: its writes go to a sink. → [Image atomics on a 32-bit colour texture](../reference/shaders.md#image-atomics-on-a-32-bit-colour-texture) - Metal shader validation reports invalid image-atomic stores even with an image-sized scratch buffer; without validation, GPU page faults can freeze rendering. → [Bounds of image atomics](../reference/shaders.md#bounds-of-image-atomics) - the NSP script stops with `captured only 0 run-time shaders` although the game reaches its frame loop with precompiled shaders. → [A GLSL language preamble is not a complete shader](../reference/shaders.md#a-glsl-language-preamble-is-not-a-complete-shader) - shaders missing from the map that no game file holds. → [Built-in shaders compiled with the game's own GLSLC](../reference/shaders.md#built-in-shaders-compiled-with-the-games-own-glslc) - the NSP script stops with `captured only 0 run-time shaders` while the capture run reaches the game's frame loop and runs to the end of its 30 s. → [A run-time compile that waits for a button press](../reference/shaders.md#a-run-time-compile-that-waits-for-a-button-press) - The Mac capture boot submits shader programs but writes no GLSLC capture files. → [Offline coverage after an empty GLSLC capture](../reference/shaders.md#offline-coverage-after-an-empty-glslc-capture) - a null read at `main+0x3316dc` in `nnMain`, right after the window setup (the program object's interface pointers at +0xd0 / +0xd8 both null). → [GLSLC GPU code version against the driver's range](../reference/shaders.md#glslc-gpu-code-version-against-the-drivers-range) - `gl_shaders.py` failed on the captured sources: `ES shaders for SPIR-V require version 310 or higher`. → [GLSL ES 1.00 sources without a `#version` line](../reference/shaders.md#glsl-es-100-sources-without-a-version-line) - `uniform LightEnv { … };` failed with `uniform u_LightEnv: type LightEnv (structs are not implemented)`, so every program that used one was missing from the library. → [Struct uniforms become member rows](../reference/shaders.md#struct-uniforms-become-member-rows) - the pipeline prebuild stops at the same line on every start (`pipeline prebuild: 7000 of 20740 pairs, 1987 built, 5013 already archived, 0 left to the draws, 0 failed`), behind *Preparing pipelines* or, with `DM_PSO_PREPARE=0`, as a black screen while the sound plays on; the NSP script's `[7/7] Pipeline prebuild` does not end (`dmhost` at 0% CPU, `MTLCompilerService` at 100%), and `MTLCompilerService` crash reports (`EXC_CRASH`, `llvm::report_bad_alloc_error`) come every 6 to 10 minutes. The bases built since the last file are never written, so the next start builds them again and stops at the same pair. → [A compile that does not return stalls every flush and draw](../reference/shaders.md#a-compile-that-does-not-return-stalls-every-flush-and-draw) - a self-contained Mac app (`--platform mac-app`) logs `pipeline prebuild: no .../Resources/dm/shader_pairs.tsv, nothing to build` although every shader library is there; it draws no hybrid stand-ins, and each pipeline seen for the first time compiles on the submit thread (frames of 100–550 ms). → [Shader-pair tables in a Mac app](../reference/shaders.md#shader-pair-tables-in-a-mac-app) - `pipeline archive bundled with the app: none for this GPU (...)`: the device builds the bases itself although the app carries an offline archive. → [Offline pipeline archive missing for the device GPU](../reference/shaders.md#offline-pipeline-archive-missing-for-the-device-gpu) - a truncated `.mtl4a` reaches `MTL4ArchiveImpl::loadFromURL`; the bundle reports coverage with `0 of 0 probed bases found`; rebuilt shader libraries reuse an archive of their old binaries; or packing fails with `pso_offline: no base to build` when every eligible pair has function constants, or when the profile's `shader_pairs.tsv` holds only its header (`--platform mac-app`, GitHub issue #338). → [Offline pipeline archive reuse and fallback](../reference/shaders.md#offline-pipeline-archive-reuse-and-fallback) - an unchanged NSP spends minutes in `shader split` after a shader-chain update, on both Mac and iOS builds, although the extracted package is identical. → [Shader extraction reruns after translation-only updates](../reference/shaders.md#shader-extraction-reruns-after-translation-only-updates) - rebuilding an unchanged NSP after a shader-chain update runs `metal-tt` for minutes even when all referenced Metal libraries and pipeline settings remain identical. → [Offline pipeline archive rebuilt after a chain-only update](../reference/shaders.md#offline-pipeline-archive-rebuilt-after-a-chain-only-update) - the host logs `pipeline archive bundled with the app: made for ... this run needs ...`, naming different depths, and pipeline bases compile during play despite a successful archive build. There need not be a `[RED]` line. → [Offline pipeline archive and profile depth disagree](../reference/shaders.md#offline-pipeline-archive-and-profile-depth-disagree) - `pipeline archive bundled with the app: this system cannot open …/applegpu_<gpu>.mtl4a (deployment target for architecture … found in archive … is not compatible with current OS …): the bases are built on the device`. On macOS 26.6 with Xcode 27.1, `t_pso_bundle` failed 10 checks, from `bundle: opened` on, and a Mac app packed there compiled every base on its first start, as without the archive. → [Offline pipeline archive made for another major version](../reference/shaders.md#offline-pipeline-archive-made-for-another-major-version) - `pso_offline.py` holds about 1.8 GB while `metal-tt` builds an archive of 140,036 bases, and the system's memory view shows the build far larger than that (180.5 GB) before `metal-tt` fails or is stopped. → [Python memory during offline pipeline archive preparation](../reference/shaders.md#python-memory-during-offline-pipeline-archive-preparation) - the offline archive stops with only `applegpu-nt command failed`, sometimes after `Max Unstruct ID` lines (a note, not the failure); the macOS kernel log reports `no paging space action` and kills `air-nt` as the largest compressed process. → [Bounded groups for the offline pipeline compiler](../reference/shaders.md#bounded-groups-for-the-offline-pipeline-compiler) - `--platform mac-app` or the iPhone build stops at its pipeline archive stage, after every earlier stage has finished: `[RED] pso_offline: metal-tt failed for applegpu_<gpu> (exit 1)`, then `pso_offline.py exit code 1`. → [A failed pipeline archive stops the whole build](../reference/shaders.md#a-failed-pipeline-archive-stops-the-whole-build) - `[RED] pso_offline: metal-tt failed for applegpu_<gpu> (exit 1)` with only `applegpu-nt command failed` in `metal-tt.<arch>.log`. → [Offline pipeline archive on a full disk](../reference/shaders.md#offline-pipeline-archive-on-a-full-disk) - `[RED] pipeline prewarm: seed list does not exist: …/pso_manifest.tsv` at every start, no `pipeline prewarm list …/pso_user.tsv` line, and the same compile stalls every session in places already visited, while `pso_user.tsv` keeps growing; the pipeline archive gains files every start and is never compacted (Donkey Kong Bananza: 88 files, 7 s to open them). → [The device's prewarm list unread without a seed list](../reference/shaders.md#the-devices-prewarm-list-unread-without-a-seed-list) - the first frame that draws with new programs loads their shader libraries on the submit thread (`[longframe] ... shader libraries N, X ms`): tens of milliseconds with the files cached, seconds when the drive is slow. → [Shader libraries loaded when the program is made](../reference/shaders.md#shader-libraries-loaded-when-the-program-is-made) - at boot, `CRASH sig=5 … pc=_dispatch_once_wait.cold.1` right after the `pipeline bases so far` line, with `bt: pso_prebuild __shmap_load_block_invoke … mtl_prog_prefetch h_nvnProgramSetShaders`. → [The prepare step inside the shader map's once](../reference/shaders.md#the-prepare-step-inside-the-shader-maps-once) - the user cache folder (`getconf DARWIN_USER_CACHE_DIR`, then `com.apple.gpuarchiver/`) fills with `gpuarchiver-*` folders of 0.3–5 MB each, one per pipeline archive flush (456 folders, 2.5 GB after two days). Later folders are larger, up to about 127 MB (an M4 Pro, 2026-10-29: 19 GB in 423 folders after a day of Mac runs and regression checks); why they grew is **open**. A later compile can fail with `cannot open '…/gpuarchiver-…/PersistentState': No such file or directory`. → [Metal's build folders left by pipeline archive flushes](../reference/shaders.md#metals-build-folders-left-by-pipeline-archive-flushes) - a previously working game exits with 139 on every start after pipeline preparation; `dispatch_retain(NULL)` is called by `-[_MTLBinaryArchive materializeAirNTFromOnlineForSlice:entryList:]` under `airntSerializeToURL` and `arch_flush` (issue #342). → [A compaction flush that crashes, then crashes every start](../reference/shaders.md#a-compaction-flush-that-crashes-then-crashes-every-start) - identical render pipelines compile repeatedly under different keys, lengthening startup prewarm and adding pipeline misses during play. → [Pipeline keys omit unused colour state](../reference/shaders.md#pipeline-keys-omit-unused-colour-state) - a vertex shader whose pairs changed was restored unpadded from `cas/`. → [Shader cache key covering the pairs](../reference/shaders.md#shader-cache-key-covering-the-pairs) - an edit to a shader build helper reaches no library: `shader cache: hit` for every shader, and the old MSL is filed under the new chain version. An edit to `dmsh_meshstage.py` did not change the chain version either. → [Shader cache key missing helper modules](../reference/shaders.md#shader-cache-key-missing-helper-modules) - a full build reports successful shaders, but `metal-tt` rejects its pipeline archive with fragment inputs not written by the vertex shader. Fifteen cached vertices lacked default outputs in DRAGON QUEST I & II. → [Partial vertex builds missing paired pixel sources](../reference/shaders.md#partial-vertex-builds-missing-paired-pixel-sources) - a repeated iOS-only shader build crashes with `FileNotFoundError` for `<key>_b.json` in the Mac output directory; requesting only Mac libraries with `IOSOUT` set still compiles iOS side libraries. → [Target selection keeps the shader analysis files in the cache](../reference/shaders.md#target-selection-keeps-the-shader-analysis-files-in-the-cache) - after `scripts/build_ipa_from_nsp.py <NSP folder> --platform mac`, a plain (iOS) run of the script on the same folder succeeds, but the Mac run command the first build printed then logs hundreds of `[RED] failed to load shader <key>_b: cannot open …/shader/cache/b-<chain>/<key>_b.metallib` lines, until `--platform mac` is run again. → [An iOS build after a Mac-only build kept no Mac libraries](../reference/shaders.md#an-ios-build-after-a-mac-only-build-kept-no-mac-libraries) - the build folder of a game (`<id>_build/shader/`) gains about 2 GB for Breath of the Wild with every upstream update that changes the shader chain: after two updates `shader/cache` held `b-157e1b96c8da` (2.1 GB) and `b-a78f966a7b38` (2.3 GB) besides the current one, and the next build added a third. → [Old shader library folders grew a game's build folder with each chain change](../reference/shaders.md#old-shader-library-folders-grew-a-games-build-folder-with-each-chain-change) - `<id>_build/shader/cache/cas/shader/` holds several entries for each shader, and grows by a full set with every upstream update that changes the shader chain. Tears of the Kingdom (seedds/nxnative#1033): 172,014 entries after six builds for 28,669 shaders, 11.85 GB of `.metal` and `.json` that no build read; the test Mac's copy held 934,955, of which the prune (dry run) found 906,286 unused: 70.2 GB of sources and reflection, scanned in 18 minutes on an external SSD. → [Old per-shader cache entries grew a game's build folder with each chain change](../reference/shaders.md#old-per-shader-cache-entries-grew-a-games-build-folder-with-each-chain-change) - the NSP script's Mac or iOS shader step for a game with very large shader packages runs at one or two shaders a second whatever `J` is. Its Python process sits at one full core, mostly system time, while few `metal` compiles run. Pokémon Pokopia (4.4 GB of packages, 131,426 shaders): players reported ETAs of 20 to 200 hours (seedds/nxnative#1036). → [A shader build that keeps its packages in memory runs one worker at a time](../reference/shaders.md#a-shader-build-that-keeps-its-packages-in-memory-runs-one-worker-at-a-time) - the Mac or iOS shader step of a game with a large map still takes many hours with every worker busy, and a `metal -c` of a translated shader takes about 0.7 s of CPU, nearly all in the front end. Optimising adds about 0.1 s, and an empty shader takes 0.025 s. Pokémon Pokopia's 131,426 shaders: about 9 hours on an M4 Pro (seedds/nxnative#1036). → [Each Metal compile instantiates Metal's texture classes again](../reference/shaders.md#each-metal-compile-instantiates-metals-texture-classes-again) - the shader step of a game with large translated sources has fewer Metal compiles running than `J` asks for, and `dmsh_build.py`'s own process stays busy on one core between them. Pokémon Pokopia's sources average 220 KB, and the builder spent about 0.12 s of Python on each shader, all but its system calls under the GIL, which alone would have come to about 4.2 hours of its full build. → [Rewrites that try every character of a large source](../reference/shaders.md#rewrites-that-try-every-character-of-a-large-source) - two builds of the same shaders give different `_bl` or `_bf` libraries for some keys, of the same size, 46 bytes apart, while their MSL is the same. A byte comparison of two library folders reports them, and `regress.py` can report them as changed variants. → [A library that depends on its source's file name](../reference/shaders.md#a-library-that-depends-on-its-sources-file-name) - the Mac or iOS shader step of a game with many pixel shaders spends most of its Metal compiles on libraries that few draws load: Pokémon Pokopia's whole map took 366,805 compiles, about 57% of them for `_ba` and `_bl`, and its runs opened none of the 5,775 of each. → [One compile for a pixel shader's side entry points](../reference/shaders.md#one-compile-for-a-pixel-shaders-side-entry-points) - startup tasks can prepare the same shader more than once, even though only one object enters the warm dictionary. A measured Tears of the Kingdom startup avoided 320 duplicate preparations; this is not a steady-frame-rate claim. → [Concurrent warm tasks prepare each shader once](../reference/shaders.md#concurrent-warm-tasks-prepare-each-shader-once) - the Mac's pipeline prebuild (`DM_PSO_PREBUILD=tool`, the NSP script's `pso_prebuild.log`) runs on far fewer workers than the Mac has: `1 workers` on an M6, where Metroid Prime Remastered's 20,233 pairs took 1,725 s and Link's Awakening's 17,742 took 667 s, and 4 on an M5 Pro, where Donkey Kong Bananza's 21,225 took 6.5 to 7.5 minutes. → [A prebuild pool sized from the Super cores](../reference/shaders.md#a-prebuild-pool-sized-from-the-super-cores) - `fragmentFunction main0 cannot be used to build a pipeline state` (a Metal validation assertion). → [Function constants specialized at load](../reference/shaders.md#function-constants-specialized-at-load) - with Metal 4 pipelines on (the Mac; on iOS `pso_mtl4 on` or `DM_PSO_MTL4=1`), Apple's performance HUD says `Compiled 2 shaders. Total compilation time is 102.70ms. Consider adopting MTL4Compiler for more fine grained compilations` during play, when a shader with function constants loads. → [Functions with function constants specialized by the pipeline, not the library](../reference/shaders.md#functions-with-function-constants-specialized-by-the-pipeline-not-the-library) - a pipeline for a vertex shader that writes `render_target_array_index` cannot be built. → [Layer-writing vertex shaders get the triangle class](../reference/shaders.md#layer-writing-vertex-shaders-get-the-triangle-class) - the picture bright green and white from some scene on, in runs with pipelines compiled on demand (prewarm lists off or short) and in none with `DM_NVN_PREDICT=0`. → [The precompile look-ahead restores the scissor](../reference/shaders.md#the-precompile-look-ahead-restores-the-scissor) - a GPU frame capture (`DM_GPU_CAPTURE`, or Xcode with `MTL_CAPTURE_ENABLED=1`) fails with `Capturing Render pipeline specialization is not supported`, or the capture layer crashes on the pipeline archive; a capture of the `MTLDevice` is refused. → [GPU frame captures need pipelines built through the device](../reference/shaders.md#gpu-frame-captures-need-pipelines-built-through-the-device) - the first boot sat on the loading clock for about a minute, the CPU idle, with every file read done after 12 s. → [A cold Metal cache looks like a long load](../reference/shaders.md#a-cold-metal-cache-looks-like-a-long-load) - hundreds of geometry raster passes in combat, despite support for batching consecutive geometry draws. → [Geometry runs across occlusion query boundaries](../reference/shaders.md#geometry-runs-across-occlusion-query-boundaries) - geometry preparation dominates rendering CPU even after geometry passes have been batched; primitive assembly and capture-index deduplication repeat for unchanged meshes. → [Prepared geometry indices reused after byte comparison](../reference/shaders.md#prepared-geometry-indices-reused-after-byte-comparison) - geometry vertex-capture passes consume substantial GPU time before geometry compute or depth rasterization. → [Geometry capture initializes only missing words](../reference/shaders.md#geometry-capture-initializes-only-missing-words) - Apple's performance HUD (`DM_METAL_HUD=1`) says `Compiled 2 shaders. Total compilation time is 102.70ms. Consider adopting MTL4Compiler for more fine grained compilations` during play, with a dip in the frame-rate graph at that moment, for example when a new room first issues a scissored clear. → [The host's own shaders compiled from source at run time](../reference/shaders.md#the-hosts-own-shaders-compiled-from-source-at-run-time) ## Game state - "stuck" at a screen with one draw per frame. → [Most draws are in command buffers replayed later](../reference/game-state.md#most-draws-are-in-command-buffers-replayed-later) - menus ignore A. → [Buttons mapped by position: B confirms](../reference/game-state.md#buttons-mapped-by-position-b-confirms) - a crash in `main+0x339c00` a second or two into the title, in love-nx's video module teardown (`love::video::theora::Video` → `~Worker`; its thread released the worker that the closing module deletes too). → [Any Lua error quits a LÖVE game](../reference/game-state.md#any-lua-error-quits-a-löve-game) - the TV latency calibration ("press A when you hear the fourth beat") ignores A. → [TV latency calibration's late, beat-timed listening window](../reference/game-state.md#tv-latency-calibrations-late-beat-timed-listening-window) - in a scripted run, a screen goes back by itself right after a confirm; the log shows `swkbd: … → no window, treated as cancel`. → [The software keyboard in scripted runs (`DM_KBD`)](../reference/game-state.md#the-software-keyboard-in-scripted-runs-dm_kbd) - a player join screen that ignores A (a character select with four "L + R to join" slots after the title). → [Player join screens (`hid::StartLrAssignmentMode`)](../reference/game-state.md#player-join-screens-hidstartlrassignmentmode)

# Symptom index One line per symptom in the [subsystem references](../reference/): what you see (an assertion, a `[RED]` line, an abort or crash site, a visible result) and the entry that explains it. Search this page for the text in your log first (`grep -i` the function name, the `[RED]` text or the address form), then read the entry and the game notes it names. Generated by `dm/tools/docs_symptoms.py` from the entries' Symptom bullets: change the entry, then run it. ## Packing - package identification stops with `ValueError: subsection not found` in `pfs0_names`, or LibHac reports `ResultFsPathNotFound` opening the last file of an NSP. → [PFS0 file-name table missing its final NUL](../reference/packing.md#pfs0-file-name-table-missing-its-final-nul) - `no base game, only update packages: pack the base game and its update into one NUP`, even when the update carries the complete game's files (issue #1195). → [A NUP with complete standalone updates stops at "no base game"](../reference/packing.md#a-nup-with-complete-standalone-updates-stops-at-no-base-game) - `[RED] a NUP packs only a game with a profile, and has none: the survey that makes a provisional profile reads NSPs`, or the same line for a dump folder (issue #1265). A folder holding `exefs/` and `romfs/` directly, or only `updates/<version>/`, was not taken for a dump at all: the script asks for `prod.keys`, then stops with `no NSP with a readable title ID`. → [A NUP or a dump of a game with no profile stops before the survey](../reference/packing.md#a-nup-or-a-dump-of-a-game-with-no-profile-stops-before-the-survey) - the survey of a Switch 2 game says `SDK: ?` and `no SDK version string found`, and its provisional profile has `app_pool 0xCD500000`. → [A provisional profile of a Switch 2 game shows no SDK and a Switch 1 memory pool](../reference/packing.md#a-provisional-profile-of-a-switch-2-game-shows-no-sdk-and-a-switch-1-memory-pool) - the Mac host step fails in `host_msl.py` with `TypeError: __init__() got an unexpected keyword argument 'capture_output'`, although the launcher reports a recent bundled Python. → [The Mac host build starts an older Python than the pipeline](../reference/packing.md#the-mac-host-build-starts-an-older-python-than-the-pipeline) - the first extraction stops with `nx_extract exit code 131` and `.NET location: Not found`, even though `dotnet` is on `PATH`. The shader translator can fail the same way. → [Homebrew .NET is on PATH but apphosts cannot find the runtime](../reference/packing.md#homebrew-net-is-on-path-but-apphosts-cannot-find-the-runtime) - the extraction and captures succeed, then the shader step stops with `translation chain tools do not match the lock file: xlate_source: lock … / actual` and nothing after `actual`, which reads like a stale translator. → [The shader step stops with an empty `xlate_source`](../reference/packing.md#the-shader-step-stops-with-an-empty-xlate_source) - on an Intel Mac, the NSP script stops at its translator check with `[RED] the shader translator does not run (Unhandled exception. System.IO.FileLoadException: Could not load file or assembly '…/dmsh_xlate.dll'. The assembly architecture is not compatible with the current process architecture.)`, although the .NET 10 runtime for x86_64 is installed. → [An Intel Mac cannot load the bundled translator's dll](../reference/packing.md#an-intel-mac-cannot-load-the-bundled-translators-dll) - `vk_shaders.py` stops with `OSError: [Errno 7] Argument list too long: 'xcrun'` after the Metal compiles, in the `metallib` link. → [The Vulkan shader step fails with `Argument list too long: 'xcrun'`](../reference/packing.md#the-vulkan-shader-step-fails-with-argument-list-too-long-xcrun) - the shader split stops with `the split shader tables differ from game profile <id>'s`, on the game version the profile registers. → [The split shader tables differ from a game profile's](../reference/packing.md#the-split-shader-tables-differ-from-a-game-profiles) - packing succeeds, but `unzip -t` or Python's `ZipFile.testzip()` reports a bad CRC for a large deflated file. → [A streamed file changes size and the IPA fails its CRC check](../reference/packing.md#a-streamed-file-changes-size-and-the-ipa-fails-its-crc-check) - `devicectl` copying a large RomFS folder fails with POSIX error 24 (`EMFILE`) or spends most of its time on small files; deleting an old folder during iOS startup hits the launch watchdog. A push after changing extracted files can also keep sending old assets if an image is reused solely because it exists. → [RomFS folder transfers fail or leave stale game files](../reference/packing.md#romfs-folder-transfers-fail-or-leave-stale-game-files) - the first build after restarting the Mac spends minutes in `unpack` (`[1/5] unpack v131072: 5%, 1.2/~24.4 GB`) although the game, the packer and the image are as they were: 8 minutes for a 24.4 GB image from a NUP on a network share. → [A reboot packs a RomFS image again](../reference/packing.md#a-reboot-packs-a-romfs-image-again) - a direct `dmhost` run logs `fs mount rom: → <path> (read-only)` for a path that does not exist, then crashes in the game's code a fraction of a second after `nnMain` (Echoes of Wisdom: `CRASH sig=11 addr=0x88` 0.3 s in). The host now stops at the mount instead with `FATAL the game files <path> (rom:) are missing: neither a folder nor a RomFS image`. → [A stale `DM_ROMFS` path crashes the game soon after `nnMain`](../reference/packing.md#a-stale-dm_romfs-path-crashes-the-game-soon-after-nnmain) - a successful `--romfs separate --no-keep-extracted` build prints a push command pointing at deleted game files. On iOS, a complete image for another build can also prevent startup despite a valid `Documents/romfs` folder. → [Separate RomFS deployment loses its image or folder fallback](../reference/packing.md#separate-romfs-deployment-loses-its-image-or-folder-fallback) - a `--romfs separate` app whose image was copied into its Documents folder by hand (Finder, the Files app, a LiveContainer guest) logs `boot: game files not found (Documents/romfs.img, Documents/romfs or <App>/romfs)`, and a build with `romfs.id` shows "There is no game file image on this device.", though the complete image is there. Renaming it to `romfs.img` makes the game start. → [A hand-copied RomFS.img is not found on iOS](../reference/packing.md#a-hand-copied-romfsimg-is-not-found-on-ios) - reducing the iPhone transfer to one image still creates thousands of resource files on the Mac, and build scanners require the expanded folder. → [Building creates a full RomFS tree before packing its image](../reference/packing.md#building-creates-a-full-romfs-tree-before-packing-its-image) - a game's `<id>_build` folder is slow to count, copy or delete: Metroid Dread's held 160,331 files in 48,782 folders, 84,541 of them in the compile cache. → [A build folder holds hundreds of thousands of small files](../reference/packing.md#a-build-folder-holds-hundreds-of-thousands-of-small-files) - a build that runs the shader step writes the compile cache's files back and removes them again, on Skyward Sword HD 24,131 files and 10,150 folders each time, Tears of the Kingdom over 900,000 entries. Removing old entries took up to half an hour on an external drive. → [The compile cache was unpacked for each build](../reference/packing.md#the-compile-cache-was-unpacked-for-each-build) - a game's shader libraries are slow to copy or delete: Skyward Sword HD's `b-<chain>/` held 12,064 files for 2,470 shaders, a third of its build folder's files, and each `regress.py` chain build held another set. A tar would not do: the host reads these files at every run. → [Shader libraries take a file per shader variant](../reference/packing.md#shader-libraries-take-a-file-per-shader-variant) - a game's `<id>-work` folder is too slow to count: Tears of the Kingdom's held 8,893,028 files and 509 GB, and its count ran past ten minutes. → [A work folder holds millions of small files](../reference/packing.md#a-work-folder-holds-millions-of-small-files) - the NSP script stops at the shader split of a registered profile with `[RED] 13744 file(s) could not be read, their shaders are left out (first: AI/FileEntry/FileEntry.Product.100.byml.zs: CalledProcessError: Command ['zstd', '-d', '-c', '-q', '…/extract/v0/RomFS.img/AI/…'] returned non-zero exit status 1.)`. → [The zstd command given a path inside the image](../reference/packing.md#the-zstd-command-given-a-path-inside-the-image) - a game's DLC works only when packed inside its IPA, although its base RomFS can be deployed separately. After pushing a smaller DLC set, removed indices can remain reported as owned and mounted. → [DLC in Documents is ignored or removed DLC remains installed](../reference/packing.md#dlc-in-documents-is-ignored-or-removed-dlc-remains-installed) - the settings of a Mac app or IPA packed from a NUP or a dump folder have no Game language row, while `DM_LANG` in the environment changes the language. Reported on Donkey Kong Bananza (NX2Apple#619, #659; the reporters' packed files were not available). → [No Game language row in an app packed from a NUP or a dump](../reference/packing.md#no-game-language-row-in-an-app-packed-from-a-nup-or-a-dump) - starting a Mac app through a front end with unchanged settings enables the encode thread, and can disable Metal 4 pipelines and the pipeline archive; starting the same app from Finder keeps the host's defaults. → [A Mac front end's default settings change Metal execution paths](../reference/packing.md#a-mac-front-ends-default-settings-change-metal-execution-paths) - in a Mac app, the settings window stays on screen after **Play**, not responding (a spinning cursor over it), until the game ends. → [The Mac settings window stays on screen after Play](../reference/packing.md#the-mac-settings-window-stays-on-screen-after-play) - with the NSP folder on an exFAT or FAT drive, the build leaves out an update whose name has no `[v…]` tag (the folder seems to hold two), or a stage stops with `FileNotFoundError` on a `._<name>` path inside `<id>_build/` and the next run fails on the half-deleted folder. → [A game folder on an exFAT drive reads one update as two, or fails to remove a folder](../reference/packing.md#a-game-folder-on-an-exfat-drive-reads-one-update-as-two-or-fails-to-remove-a-folder) - with the build folder on an exFAT or FAT drive, the shader step compiles every library and then stops in `c1_guard.py` with `UnicodeDecodeError: 'utf-8' codec can't decode byte …` (dmsh_build.py: `[RED] c1_guard.py failed`), reading a `._<key>_b.metal`. → [The c1 guard stops on an AppleDouble file after the shader build](../reference/packing.md#the-c1-guard-stops-on-an-appledouble-file-after-the-shader-build) - with the build folder or the app on an exFAT or FAT drive, the Mac app step stops in `pack_app.py`. The first form it takes is `no input file at <build>/shader/cache/<chain>/._<key>_b.metallib`, or `no rewriter fixups for <build>/<version>/._main.patched.bin` when the modules come first. When the inputs get past it, the copies stop with `chflags` or `Permission denied`, and the signing step stops with `codesign failed (1): code object is not signed at all` and `In subcomponent: …/Contents/MacOS/._nxnative`, which reads like a broken launcher build. → [The Mac app step stops on AppleDouble files in its inputs, its copies and its signature](../reference/packing.md#the-mac-app-step-stops-on-appledouble-files-in-its-inputs-its-copies-and-its-signature) - with the app on a Mac OS Extended, exFAT or FAT drive, the first build into a folder works and the next one that changes anything stops in `pack_app.py` `replace_app` with `OSError: [Errno 45] Operation not supported: '<app>'`. The old app stays in place. → [A second Mac app build stops with `[Errno 45]` when it replaces the old app](../reference/packing.md#a-second-mac-app-build-stops-with-errno-45-when-it-replaces-the-old-app) - on an exFAT or FAT drive, shader splitting stops with `ValueError: not a version 2 shader code archive` or `[RED] /glslc_capture/._…: no GLSLC output`. → [External shader directories contain AppleDouble metadata](../reference/packing.md#external-shader-directories-contain-appledouble-metadata) - `decompress NSZ` stops immediately with `nsz: error: unrecognized arguments: --keys …`. → [NSZ decompression rejects `--keys`](../reference/packing.md#nsz-decompression-rejects---keys) - the NSP script or any module tool stops on `main`: `compressed with zstd (NSO flag bit 7), which this loader does not decode yet`; with the decoder but without its package, `ZBIC (zstd) segments need the zbic package (python3 -m pip install zbic)`. → [ZBIC-compressed NSO segments](../reference/packing.md#zbic-compressed-nso-segments) - `FATAL open <folder>/subsdk1.fixups.tsv` right after the host starts, or `build_ipa.sh` stops with `no rewritten module …/subsdk1`, for a version that has no such module. → [A version without one of the profile's modules stops the host at boot](../reference/packing.md#a-version-without-one-of-the-profiles-modules-stops-the-host-at-boot) - `[RED] no NSP with a readable title ID in <folder>`, although the keys open the package (the launcher's key check passes). Renaming the file to `Game [0100XXXXXXXXXXXX].nsp` makes the build go on. → [An NSP without a ticket or a title ID in its name stops with "no NSP with a readable title ID"](../reference/packing.md#an-nsp-without-a-ticket-or-a-title-id-in-its-name-stops-with-no-nsp-with-a-readable-title-id) - `[RED] no NSP with a readable title ID in <folder>` for a folder holding `Game [0100XXXXXXXXXXXX].NSP`, on any Mac volume; renaming it to `.nsp` makes the build go on. A dump folder beside `Game.NSP` is packed instead of the package, and `Game.NUP` is not found. A `Game.NSZ` stops with `nsz made no Game.nsp`. → [A game file whose extension is in capitals is not found](../reference/packing.md#a-game-file-whose-extension-is-in-capitals-is-not-found) - a game folder holding one merged package (`[Base + Update + DLC].nsp`, or a 1G+1U cartridge dump with no update NSP beside it) stops with `no base game NSP found`, or packs the base game alone (v0) without its update and DLC; when the base game's own build cannot be packed (Mario Kart 8 Deluxe 1.0.0's `main` is 32-bit), the build stops there. → [A merged NSP (base game, update and DLC in one file) packs as one title](../reference/packing.md#a-merged-nsp-base-game-update-and-dlc-in-one-file-packs-as-one-title) - a version a profile was not brought up on crashes at its first movie: `UNIMPL _ZN5movie9ExtractorC1ENS_13ContainerTypeE`, then `CRASH sig=11` (issue #1211). The derived profile's `modules` has only `main sdk`. → [A derived profile leaves out a module that moved to another slot](../reference/packing.md#a-derived-profile-leaves-out-a-module-that-moved-to-another-slot) - the NSP script stops at its rewrite stage with `FileNotFoundError: … extract/v0/ExeFS/subsdk1` while packing a version the profile was not brought up on; the extraction has every other module. → [A derived profile loads only the modules its version ships](../reference/packing.md#a-derived-profile-loads-only-the-modules-its-version-ships) - `nx_extract` stops with exit code 134 and `Unhandled exception. LibHac.Common.Keys.MissingKeyException: Unable to decrypt NCA section.` with `Key Name: key_area_key_application_<NN>` (or `titlekek_<NN>`), after any NSZ conversion, the build ID lookup or the survey. An NSZ converted with such keys is written anyway: `nsz -D` warns `master_key_<NN> missing … This will lead to corrupted output.` and exits 0. → [Keys older than the game stop the extraction with an unhandled MissingKeyException](../reference/packing.md#keys-older-than-the-game-stop-the-extraction-with-an-unhandled-missingkeyexception) - the extraction of a game whose base is an XCI that also carries its update (a "1G+1U" dump) stops with `[RED] nx_extract exit code -6`. `extract_v<version>.log` lists the update's build IDs even for the base game alone, then ends in an unhandled exception from the RomFS (`ResultFsNonRealDataVerificationFailed (2002-4604): Hash error!` from `RomFsFileSystem..ctor`, or `ArgumentException` / `InvalidOperationException` from the patch layers). → [A cartridge dump with its update on it extracts the update as the base game](../reference/packing.md#a-cartridge-dump-with-its-update-on-it-extracts-the-update-as-the-base-game) - an XCI with two applications (Super Mario Galaxy + Super Mario Galaxy 2 on one cartridge dump) always packs the first game; `build_ipa_from_nsp.py` never reaches the second. → [A cartridge dump that holds two games packs only the first](../reference/packing.md#a-cartridge-dump-that-holds-two-games-packs-only-the-first) - `nx_extract` stops with exit code 134 and `Unhandled exception. System.InvalidOperationException: The LinkedList is empty.` from `LibHac.Tools.FsSystem.CachedStorage.GetBlock`, with no `[RED] hash check failed` list, with or without `--allow-damaged`. → [Extraction of a damaged NSP ends in "The LinkedList is empty"](../reference/packing.md#extraction-of-a-damaged-nsp-ends-in-the-linkedlist-is-empty) - `[RED] the NSP is damaged: a filesystem's own tables fail the NCA's hash check`, exit code 3, right after the build IDs; before 2026-11-04, `[RED] nx_extract exit code -6` with an unhandled `ResultFsNonRealDataVerificationFailed (2002-4604)` under `RomfsHeader`. The ExeFS reads, and the build IDs and name are printed, since only the RomFS is hit. → [A damaged RomFS's own tables](../reference/packing.md#a-damaged-romfss-own-tables) - a build packed with `--allow-damaged` crashes or draws wrongly in game code, the same way on each run, at a place unrelated to the host's last work. The log gave no sign of damage; the build log's list (`logs/extract_<version>.log`) is the only record, and it is not part of a bug report's run log. → [A crash from a damaged NSP's file looks like a host bug](../reference/packing.md#a-crash-from-a-damaged-nsps-file-looks-like-a-host-bug) - the NSP script stops at the offline HTML pages (`logs/extract_html_<version>.log`) with `[RED] the NSP is damaged: <n> files fail the NCA's hash check` and a list under `/html-document/`, although the program extracted cleanly and the NSZ tool verified every NCA of the update. → [An update's offline HTML pages reported as a damaged NSP](../reference/packing.md#an-updates-offline-html-pages-reported-as-a-damaged-nsp) - for a game with no profile, the NSP script stops at `build ID lookup · main of the base game` with `[RED] nx_extract exit code -6`; `<title ID>_survey/logs/exefs.log` ends in `ResultFsNonRealDataVerificationFailed (2002-4604): Hash error!` from `PartitionFileSystemMetaCore.QueryMetaDataSize` under `Nca.OpenFileSystem`, although every NCA in both NSPs matches its content ID (the SHA-256 that names it) and the base game with its update extracts cleanly. → [The survey's build ID lookup stops on the base game alone with a hash error](../reference/packing.md#the-surveys-build-id-lookup-stops-on-the-base-game-alone-with-a-hash-error) ## Rewriter - `NameError: name 'CS_ARCH_ARM64' is not defined` at the start of `patch_nso.py`; now `[RED] Capstone 6.… is unsupported` from the NSP script or `patch_nso.py`. → [Capstone API version](../reference/rewriter.md#capstone-api-version) - an updated game loses a needed cut because its NSO build ID changed, although the relevant code still matches a verified version; the rewriter reports `[RED] function patch ... skipped` when that match cannot be established, and the NSP script ends with `[RED] main: no function patch carries the registered builds' fixes to this build` or `[RED] main: function patches not applied` (Super Smash Bros. Ultimate 13.0.1: a static-initialiser abort in `nninitStartup`, GitHub issue #375). → [Function-matched cuts for unregistered builds](../reference/rewriter.md#function-matched-cuts-for-unregistered-builds) - after a game update, the Cheats menu lists only `Cheats for build … (another version of the game)`, and nothing runs. Or a cheat file converted to the new build by hand writes into the wrong place: a table instead of a variable, or code that moved. → [Cheats carried across game updates](../reference/rewriter.md#cheats-carried-across-game-updates) - `jump table <addr>` assertion in `patch_nso.py`, in a Unity / IL2CPP `main`. → [Offset jump tables through x18 read at rewrite time](../reference/rewriter.md#offset-jump-tables-through-x18-read-at-rewrite-time) - `jump table <addr>` assertion in `patch_nso.py`, in a `subsdk`. → [Offset jump tables with the bounds check on another register](../reference/rewriter.md#offset-jump-tables-with-the-bounds-check-on-another-register) - `jump table <addr>` assertion where the index is a copy made before the check (`mov w0,w18`, then 41 instructions holding two other jump tables on `x0`, then `cmp w18,#4; b.hi; ldrsw x18,[x11,x0,lsl #2]; add x18,x18,x11; br x18`). → [Index copied before the bounds check](../reference/rewriter.md#index-copied-before-the-bounds-check) - `jump table <addr>` assertion in `patch_nso.py` on an offset table whose index is checked with a 64-bit compare (`cmp x22, #0x10; …; b.hi; adrp x18 + add x18; mov x0, x18; ldrsw x18, [x0, x22, lsl #2]; add x18, x18, x0; br x18`). → [64-bit bounds check of the index](../reference/rewriter.md#64-bit-bounds-check-of-the-index) - `jump table <addr>` assertion in `patch_nso.py` where the index is made with a 64-bit `and` by `0xffffffff` after the check (`cmp w8, #4; b.hi; and x18, x8, #0xffffffff; ldrsw x18, [x16, x18, lsl #2]; add x18, x18, x16; br x18`). → [Index zero-extended after a 32-bit bounds check](../reference/rewriter.md#index-zero-extended-after-a-32-bit-bounds-check) - `jump table <addr>` assertion in a Unity / IL2CPP `main` whose dispatch checks a fresh mask of another register than the one it indexes with. → [Index masked in the block that branches to the dispatch](../reference/rewriter.md#index-masked-in-the-block-that-branches-to-the-dispatch) - `jump table 6eea88` or `jump table 6eeac0` assertion in `patch_nso.py` on Return of the Obra Dinn 1.0.1. → [Zero-guarded complemented jump-table index](../reference/rewriter.md#zero-guarded-complemented-jump-table-index) - `jump table <addr>` assertion on an offset table whose base was set far back (`cmp w18,#5; b.hi; ldrsw x18,[x24,x18,lsl #2]; add x18,x18,x24; br x18`). → [Offset table base set far back in the function](../reference/rewriter.md#offset-table-base-set-far-back-in-the-function) - `jump table <addr>` assertion on an offset table whose base was set far back and moved through other registers (`ldrb w18,[x14]; sub w18,w18,#1; cmp w18,#6; b.hi; ldrsw x18,[x7,x18,lsl #2]; add x18,x18,x7; br x18`). → [Far table base passed through other registers](../reference/rewriter.md#far-table-base-passed-through-other-registers) - `jump table ae95f8` assertion in `patch_nso.py` while rewriting Blasphemous 1.0.8. → [Offset table base initialized after the dispatch](../reference/rewriter.md#offset-table-base-initialized-after-the-dispatch) - `jump table <addr>` assertion, entries relative to an `adr`. → [Offset tables relative to an adr](../reference/rewriter.md#offset-tables-relative-to-an-adr) - `AssertionError: jump table 30ee50c` while rewriting an ADR-relative dispatch with `cmp x9,#4`. → [ADR-relative jump tables with 64-bit bounds](../reference/rewriter.md#adr-relative-jump-tables-with-64-bit-bounds) - `AssertionError: jump table 3ce6c` while rewriting `main`, on an ADR-relative dispatch that the existing form describes: `ldrb w0, [x18, #5]; cmp w0, #5; b.hi; ldr s0, [sp, #8]; ldr s1, [x18, #0xc]; adr x18, #L; ldrsw x1, [x17, x0, lsl #2]; add x18, x18, x1; br x18`. → [Vector registers read as writes of the jump-table index](../reference/rewriter.md#vector-registers-read-as-writes-of-the-jump-table-index) - no failure seen on a game. The rewriter could read a jump table with the wrong size or base, so a case's target or landing pad would be missing or wrong. In the other direction, a halfword table whose base is in x30 got all 65,536 landing pads (`J` rows with 65536 in `main.sites.tsv`), which only makes the patch area larger. → [Overwritten jump-table indices and bases taken as unchanged](../reference/rewriter.md#overwritten-jump-table-indices-and-bases-taken-as-unchanged) - `jump table <addr>` assertion on a byte table indexed by x30 (`adr x18, #L; ldrb w30, [x14, x12]; add x18, x18, x30, lsl #2; br x18`). → [Byte tables indexed by x30 (capstone register names)](../reference/rewriter.md#byte-tables-indexed-by-x30-capstone-register-names) - `jump table <addr>` assertion on a byte table whose `add` is far from the `br` (`adr x18,#L; ldrb w0,[x17,x15]; add x18,x18,x0,lsl #2`, then 17 register moves before `br x18`). → [Byte tables whose add is far from the br](../reference/rewriter.md#byte-tables-whose-add-is-far-from-the-br) - `jump table <addr>` assertion in `patch_nso.py`, in a Unity / IL2CPP `main`, at a `blr x18`. → [Indirect calls through x18](../reference/rewriter.md#indirect-calls-through-x18) - `jump table <addr>` assertion on a `br x18` with no table in front of it. → [Indirect tail calls through x18 in IL2CPP thunks](../reference/rewriter.md#indirect-tail-calls-through-x18-in-il2cpp-thunks) - `AssertionError: jump table d29e68` while rewriting Moving Out 2 1.3.315. → [Unframed pointer tail calls followed by zero trap padding](../reference/rewriter.md#unframed-pointer-tail-calls-followed-by-zero-trap-padding) - `jump table 53e9c` while rewriting Warm Snow 2.1.4's Unity IL2CPP `main`, or `jump table 108bb70` on Ori and the Blind Forest: Definitive Edition. → [Loaded method-pointer tail call before an error block](../reference/rewriter.md#loaded-method-pointer-tail-call-before-an-error-block) - job system hangs; a queue claims thousands of tasks but every slot is empty. → [Exit stub order in exclusive windows](../reference/rewriter.md#exit-stub-order-in-exclusive-windows) - `branch into window <addr>` assertion. → [Out-of-line retry blocks of atomic updates](../reference/rewriter.md#out-of-line-retry-blocks-of-atomic-updates) - branches to an `ldxr … stxr` loop's head landed mid-window. → [A window never spans a second exclusive load](../reference/rewriter.md#a-window-never-spans-a-second-exclusive-load) - `AssertionError: 0x…` in `site_window` on an `adrp` inside an exclusive window (`ldaxr x9,[x9]; cmp x9,x25; b.ne out; adrp x10 + add x10` (the same address again, for the store); `mov x18,x26; stlxr w9,x8,[x10]`, then loads and `cbnz w9` back). → [adrp inside an exclusive window](../reference/rewriter.md#adrp-inside-an-exclusive-window) - `B()` assertion at a spin wait: a branch into the patch area beyond the ±128 MB a `b` reaches. → [Halfword jump table landing pads sized to the largest entry](../reference/rewriter.md#halfword-jump-table-landing-pads-sized-to-the-largest-entry) - `B()` range assertion in `patch_nso.py` (`site_plain`), only for one module. → [Patch area before the module base for a large bss](../reference/rewriter.md#patch-area-before-the-module-base-for-a-large-bss) - `frame step state page` assertion when a `FRAME_STEP` profile is added to a module with a large BSS. → [Frame-step state with a front patch area](../reference/rewriter.md#frame-step-state-with-a-front-patch-area) - `B()` range assertion, then `patch area of … bytes does not fit in the … before the base`. → [Patch area right before the base for a long text](../reference/rewriter.md#patch-area-right-before-the-base-for-a-long-text) - `main: patch area of 0x6b9d38 bytes does not fit in -0x39c0000 before the base; rewriting again with 0x6c0000`, then a `B()` range assertion in `site_window`: the gap before the base came out negative. → [Two patch areas for a text longer than a branch reaches](../reference/rewriter.md#two-patch-areas-for-a-text-longer-than-a-branch-reaches) - a `B()` range assertion in `site_plain` on the branch back to the site, in a module that takes two patch areas. → [Split point within the back area's reach](../reference/rewriter.md#split-point-within-the-back-areas-reach) - `observation gate neither at a function entry nor after a bl`; `observation gate neither at a function entry, after a bl nor before a call` on an epilogue. → [Observation gates on any relocatable instruction](../reference/rewriter.md#observation-gates-on-any-relocatable-instruction) - `jump table <addr>` assertion on an ordinary byte table near the start of the text (`adr x18; ldrb w0,[x17,x16]; add x18,x18,x0,lsl #2; br x18`). → [Code before the first unwind entry is one function](../reference/rewriter.md#code-before-the-first-unwind-entry-is-one-function) - the rewrite never finishes, the Mac swaps, the rewriter's footprint reaches 100 GB. → [Long functions analysed in pieces](../reference/rewriter.md#long-functions-analysed-in-pieces) - `KeyError` at `site_br` for a `br x18` that is an ordinary byte jump table. → [Disassembly goes on after undecodable words](../reference/rewriter.md#disassembly-goes-on-after-undecodable-words) - `RuntimeError: 788 ldr x18, #0xd1eb0` in `patch_nso.py`, or any rewrite site in data. → [Data blocks at the start of the text](../reference/rewriter.md#data-blocks-at-the-start-of-the-text) - `RuntimeError: 44 ldr x18, #0xfffffffffff40370` while rewriting an NRO. → [NRO metadata inside the text segment](../reference/rewriter.md#nro-metadata-inside-the-text-segment) - `jump table <addr>` assertion in `patch_nso.py`, in a Unity / IL2CPP `main`, at an `alloca` (`mov sp, x18`). → [Stack pointer writes through x18](../reference/rewriter.md#stack-pointer-writes-through-x18) - `CRASH sig=10 addr=0` on an `stp` relative to `sp`, with `sp` not a multiple of 16 (`main+0x2bbba4`, `sub sp, sp, #0xc0` then `stp d15, d14, [sp, #0x60]` with sp ending in `…9dc`). → [Stack arguments reserved with sub sp, sp, xN](../reference/rewriter.md#stack-arguments-reserved-with-sub-sp-sp-xn) - SIGILL / trap on a system register read. → [System register reads that macOS traps](../reference/rewriter.md#system-register-reads-that-macos-traps) - every pointer in `.data` / the GOT is a module offset, crashes everywhere. → [Packed relative relocations (DT_RELR)](../reference/rewriter.md#packed-relative-relocations-dt_relr) - `regress.py check` stops before gameplay with `CUTS of build ... in both ...`, naming a revision profile and its copied harness profile. → [Regression rewrites register copied profiles twice](../reference/rewriter.md#regression-rewrites-register-copied-profiles-twice) - packing spends most of the rewrite step on the x18 scan and the spin-wait search, using one core per module. Cancelling a parallel rewrite can leave its workers running; `DM_REWRITE_J=0` or a negative value can silently omit spin gates, and the NSP script can ignore an explicit worker limit. → [Parallel scans preserve rewrite output](../reference/rewriter.md#parallel-scans-preserve-rewrite-output) - a rewrite never ends, using no CPU: `patch_nso.py` waits in `wait4` and one forked worker of the same command in `sem_wait`, in `multiprocessing/queues.py` `get`, having run no job. It is rare and needs small jobs (about 1 in 6,000 pools of tiny jobs under load). Separately, a SIGTERM could be ignored until the rewrite ended, or leave workers behind. → [A pool's shutdown hangs on a worker that has just started](../reference/rewriter.md#a-pools-shutdown-hangs-on-a-worker-that-has-just-started) ## Memory and address space - on the Mac, a game crashes once its address regions pass the profile's alias region: at launch (Trails in the Sky 1st Chapter: `sig=11 addr=0x1` at `sdk+0x15576c`, after an 11.27 GB region at alias +1.00 GB) or a little later (Just Dance: a null allocation past 4.375 GB after about 40 s, then a crash at `main+0x639ab0`), though the build's address region check reports a larger reach. A provisional profile's red line `past the profile's … alias region, the iPhone layout` says the same. Tears of the Kingdom's long-session memory-shortage Blood Moon (`[game] MSF / R / Rf` after about 87 minutes at +2.25 of 2.38 GB, issue #639) may be this too: not confirmed by a long session, and a mark near the top alone is not exhaustion. → [The Mac's alias region is the Switch's 64 GB](../reference/memory.md#the-macs-alias-region-is-the-switchs-64-gb) - large resources silently skipped, later a null deref where the resource is used; also visible as `SetHeapSize` asking for much less than the pool. → [Partitioning the guest block between alias region, stacks and heap](../reference/memory.md#partitioning-the-guest-block-between-alias-region-stacks-and-heap) - an `nn::diag` abort with Result 0 under `nn::os::detail::ThreadManager::CreateThread` → `ThreadManagerImplByHorizon::MapAliasStack`, on some boots and not on others, with no `MapMemory refused` line. → [Thread stacks placed at random in the stack region](../reference/memory.md#thread-stacks-placed-at-random-in-the-stack-region) - `SetHeapSize OOM: req 0x600000 > cap 0`, followed by an SDK abort in `nninitStartup` on the first provisional boot. → [Provisional Unreal layout leaves no heap](../reference/memory.md#provisional-unreal-layout-leaves-no-heap) - `nnMain` returns right after `nv::InitializeGraphics`, with no error (Hyrule Warriors: Age of Calamity); `[mem] SetHeapSize … + modules … > app pool` (Monster Hunter Rise), `[mem] SetHeapSize … + modules 0x5c00000 > app pool` (Catherine: Full Body); `SetHeapSize` asks for almost the whole application pool and fails at boot (Metroid Dread: 0xc9400000, larger than the heap region); the memory pool for the game's 96 MB GPU heap has no storage (`MemoryPoolInitialize` red line), then a null read at `main+0x2eb954` (Catherine: Full Body); heap allocations fail late in a busy scene. → [Heap sized from the application pool less used memory](../reference/memory.md#heap-sized-from-the-application-pool-less-used-memory) - `SetHeapSize OOM: req 0xffffffffe0000000 > cap 0xd0000000`, followed by an abort when allocating the launcher NRO. → [Offline NRO copies are not additional guest memory](../reference/memory.md#offline-nro-copies-are-not-additional-guest-memory) - repeated `[RED] MapMemory refused (0xd401)` for a stack source inside a loaded NRO's writable data, then an abort in `MapAliasStack` / `CreateThread`. → [Thread stacks backed by active NRO data](../reference/memory.md#thread-stacks-backed-by-active-nro-data) - `SetHeapSize OOM: req 0x120000000 > cap 0xd0000000`, then `Break#1 reason=0` in `nninitStartup`, with a backtrace through `nn::os::SetMemoryHeapSize` (`sdk+0x967a4`). → [A heap request beyond the heap region returns ResultOutOfMemory](../reference/memory.md#a-heap-request-beyond-the-heap-region-returns-resultoutofmemory) - a provisional profile's heap check reports "the heap request did not fit; set mem_reserve", the build finishes, and the game still stops at its first run: `SetHeapSize OOM: req 0x18ce00000 > cap 0xb8000000`, then `CRASH sig=10` (SIGBUS) in `nninitStartup` on the heap it never got. → [The heap check grows the block around the profile's alias region](../reference/memory.md#the-heap-check-grows-the-block-around-the-profiles-alias-region) - the app quits at launch; the host log shows `SetHeapSize OOM: req 0xc5200000 > cap 0`. → [Unreal games without virtual address memory take a heap](../reference/memory.md#unreal-games-without-virtual-address-memory-take-a-heap) - `CRASH sig=11 addr=0 pc=sdk+0x4656c8` right after the window is created, with `x0 = 0` and the return address in `main` (`main+0x3508a90`): the faulting code is `ldr x0,[0xc5d000+0xc68]; ldr x8,[x0]; ldr x1,[x8,#0x68]; br x1`. → [`nv::GetGraphicsMemoryInfo` with no graphics device](../reference/memory.md#nvgetgraphicsmemoryinfo-with-no-graphics-device) - a null pointer in the game's resource code (`main+0x15a69b0`, null + 0x78, thread `BaseProcCreateAndDeleteThread`): a model's load returned null, its status 9, written hundreds of times by a loader thread. The `[mem]` lines end near the top of the alias region. → [An SDK 21 Switch 2 game with a 4.5 GB alias region](../reference/memory.md#an-sdk-21-switch-2-game-with-a-45-gb-alias-region) - `StandardAllocator::Initialize` aborts in `nninitStartup` (Fire Emblem Engage); `nn::diag` abort in `StandardAllocator::Initialize(void *, size_t, bool)` from `nninitStartup` (`sdk+0x2f98e4` ← `main+0x5b69e0`, Big Brain Academy: Brain vs. Brain). → [Virtual address memory follows the NPDM's system resource](../reference/memory.md#virtual-address-memory-follows-the-npdms-system-resource) - the first `AllocateAddressRegion` fails with 0x1803; `StandardAllocator::Initialize` aborts in `nninitStartup` (an `nn::diag` abort; the NSP script's heap check reports "the host stopped before nnMain"); the alias region fills in minutes; regions a game reserves later fail (Size-aligned regions exhaust the alias address space, The movie player's own StandardAllocator). → [The SDK's address-region node area](../reference/memory.md#the-sdks-address-region-node-area) - a null-based write minutes into play, at the pool size minus 0x20 (Engage: a write to `NULL + 0x1fffe0`, `addr=0x1fffe0` at `main+0x9a4664`); NULL index pointers written on several job threads at once (`main+0xdb0ad4`, `0xdaea58`, `0xdadb5c`), with 32-bit mesh indices turning up inside texture objects. → [Size-aligned regions exhaust the alias address space](../reference/memory.md#size-aligned-regions-exhaust-the-alias-address-space) - a cut engine region still does not fit; two large regions lose up to 1 GB each to alignment, depending on where `mmap` put the guest block (Absolum); the region comes 0.69 GB past the 1 GB node area, at the next 1 GB boundary (Paper Mario: The Thousand-Year Door). → [1 GB alignment of regions of 1 GB and more](../reference/memory.md#1-gb-alignment-of-regions-of-1-gb-and-more) - a write at NULL + 0x3fffe0 (a 4 MB pool − 0x20) at `main+0x48b770`, about six minutes into the prologue, with Unity's `ALLOC_CACHEOBJECTS_THREAD` allocator in x19; the `[mem]` high-water mark at +4.26 GB of the 4.375 GB alias region while 1.26 GB is mapped (Sea of Stars). → [Size-class alignment doubles Unity's regions](../reference/memory.md#size-class-alignment-doubles-unitys-regions) - nothing aborts at startup as with Unity 2022.3, but the provisional profile gave a 1 GB block and a 256 MB alias region while Unity maps 1.5 GB in the first room. → [Unity 6 takes its memory with no StandardAllocator and no heap](../reference/memory.md#unity-6-takes-its-memory-with-no-standardallocator-and-no-heap) - `nn::diag` abort from `StandardAllocator::Initialize` long after `nninitStartup`, right after the first Vulkan query pool (`sdk+0x12dad0` ← `main+0x62c52c`). → [The movie player's own StandardAllocator](../reference/memory.md#the-movie-players-own-standardallocator) - the `[mem]` high-water mark climbs close to the end of the alias region while far less is mapped (SUPER ROBOT WARS Y: +4.27 GB of 4.38 GB with 1.82 GB of live regions), and it looks like the address space is about to run out. → [An alias high-water mark near the top is not exhaustion](../reference/memory.md#an-alias-high-water-mark-near-the-top-is-not-exhaustion) - `StandardAllocator::Initialize` aborts in `nninitStartup` (Pokémon Legends: Z-A: `main+0x1b2e690`); `nn::diag` abort at `sdk+0x11ff34` (`StandardAllocator::Initialize`) in `nninitStartup`, SDK 15.3.2, called from `main+0x31370c` (Paper Mario: The Thousand-Year Door). → [StandardAllocators over 12 to 62 GB of address space](../reference/memory.md#standardallocators-over-12-to-62-gb-of-address-space) - a SIGSEGV writing just past a null base as a menu or board loads (`nn::bezel::CoreSystem::Allocate` returned null for a 46 MB request at `main+0x8d9a48`, Super Mario Party Jamboree 2.3.0), sometimes first `[RED] fs ReadFile into 0x0+0x400000 failed at +0 (EFAULT)`, a read into a null buffer from the same allocator; the alias region's `[mem]` lines show `StandardAllocator::Initialize(nullptr, 56.00 GB) … 2.06 GB of address space`. → [Bezel Engine's two memory setups](../reference/memory.md#bezel-engines-two-memory-setups) - a write to `0x20000ffff` in static initialization (`main+0x164990`), after `AllocateAddressRegion` returns `0x1803`; reducing the request to 3 GB still returns `0x1803` with the SDK's original large-region alignment. With only the outer ranges reduced, a later free crashes at `main+0x1668dc` after reading compressed file data as a slab-owner pointer. With all three ranges cut, a write to `0x78` at `main+0x2c534a8` (`lr=main+0x2c53484`) when the opening quest's overalls bush is shaken, or when a later save loads. With a pool too small for the area: `nn::diag` abort with `Result 0` and an empty message while a world loads, backtrace `sdk+0x16ba48 sdk+0x37d1b0 sdk+0x37c2f4 sdk+0x37c27c sdk+0x37a980 main+0x12300c main+0x164b40 main+0x164954 main+0x168e54` on Sparks of Hope 1.6.2225577 and SDK 13.3.5. → [Separate virtual ranges in Snowdrop's page allocator](../reference/memory.md#separate-virtual-ranges-in-snowdrops-page-allocator) - `nn::diag` abort at `sdk+0x12dad0` in `nninitStartup`, called from `main+0x756310` (1.1.1: `main+0x7562d0`). → [.NET NativeAOT malloc and the GC region range](../reference/memory.md#net-nativeaot-malloc-and-the-gc-region-range) - the game aborts in its static initialisers, before `nnMain`, when its own 62 GB address region fails (`main+0x37c9bd0`, `AllocateAddressRegion(&p, 0xf80000000)` at `main+0x37c9a5c`). → [A 62 GB page allocator behind `nu::VirtualAllocHook`](../reference/memory.md#a-62-gb-page-allocator-behind-nuvirtualallochook) - the game calls `exit(1)` in `nninitStartup` (Octopath Traveler 0: `main+0x12e74`); `nn::diag::Abort` from `main+0x352fbec` (Unreal's fatal error) after the first commit, `AllocateMemoryPages(0, 2 MB)` while the RHI starts (`main+0x353ff8c`, result 0xe03) (Pikmin 4); a crash in `NumberLineAllocator::Compaction` at boot (DRAGON QUEST XI S, region option 4224). → [Unreal's engine address region and its options](../reference/memory.md#unreals-engine-address-region-and-its-options) - a null read in the out-of-memory report at `main+0x1005824` when the engine region is smaller than the allocator's pools (Octopath Traveler 0). → [Unreal's FMallocBinned3 replaced by the host allocator](../reference/memory.md#unreals-fmallocbinned3-replaced-by-the-host-allocator) - Wwise crashes in `AK::MemoryMgr::Init` while reallocating or freeing a block, after Unreal switches to the host heap. Whether a boot crashes depends on where the heap puts the block, and the fault address can be a null read or garbage. → [Wwise loses the span header in a virtual block from Unreal's heap](../reference/memory.md#wwise-loses-the-span-header-in-a-virtual-block-from-unreals-heap) - an abort right at `nnMain`, under `nn::os::CreateThread` → `ThreadManagerImplByHorizon::MapAliasStack` → `StackGuardManager::MapAtRandomAddress`; with the log line, `[RED] MapMemory refused (0xd401): <stack region> <- <address outside the guest block>`. → [Thread stacks from the host's Unreal heap](../reference/memory.md#thread-stacks-from-the-hosts-unreal-heap) - `nn::diag` abort from `main+0x11bc`, no message, in the first battle, with about 1 GB mapped (FINAL FANTASY RESONANCE with DRAGON QUEST VII Reimagined's 2 GB region). → [Unreal 5.6's page allocator never gives address space back](../reference/memory.md#unreal-56s-page-allocator-never-gives-address-space-back) - write to `0x268` right after the title screen (`main+0x5d6708`, a constructor whose `this` is `0x200`). → [Ring heaps cut from a pool at 64 KB alignment](../reference/memory.md#ring-heaps-cut-from-a-pool-at-64-kb-alignment) - C++ exception aborts in `nn::ro::detail::GetExceptionInfo`. → [`svcQueryMemory` must report each module's real layout](../reference/memory.md#svcquerymemory-must-report-each-modules-real-layout) - `MapPhysicalMemory` faults on part of a page. → [`MapPhysicalMemory` in 16 KB host pages](../reference/memory.md#mapphysicalmemory-in-16-kb-host-pages) - the alias region's mapped total runs past the application pool in the first minute. → [Maps past the application pool fail as on Horizon](../reference/memory.md#maps-past-the-application-pool-fail-as-on-horizon) - after a large `UnmapPhysicalMemory` or heap shrink, RAM does not come back. `phys_footprint` may still fall, so it hides this: the `guest` class in `DM_MEMSTAT` shows the real figure. → [Unmapped guest memory stays resident](../reference/memory.md#unmapped-guest-memory-stays-resident) - a write through a null pointer at +0x1c0 during startup. → [`GetInfo(UserExceptionContextAddress)` returns a real buffer](../reference/memory.md#getinfouserexceptioncontextaddress-returns-a-real-buffer) - a null-pool buffer even with virtual pools working (Virtual memory pools mapped onto one physical pool). → [A null-pool buffer from a game heap that ran out](../reference/memory.md#a-null-pool-buffer-from-a-game-heap-that-ran-out) - a model load exhausts its resource heap: a null `operator new` at the world load, or `BufferInitialize: pool has no storage` followed by a null-pool crash. A display-list heap that runs out shows as `AddCommandMemory` with a null pool outside a recording, then host-lent segments growing until `FATAL NVN command memory` (Host-lent command memory segments). → [Model heaps sized by the host's command record sizes](../reference/memory.md#model-heaps-sized-by-the-hosts-command-record-sizes) - the frames stop at the first loading screen, a graphics worker at 100% CPU (17 s in, `UnityGfxDeviceWorker` running, the main thread waiting on a condition variable, no red line). → [Unity's GPU pool block allocation spins at size 0](../reference/memory.md#unitys-gpu-pool-block-allocation-spins-at-size-0) - SIGBUS inside a host hook (`snprintf` under `mount_ex` / `h_fs_MountSave`), then the process hangs (Super Mario 3D World + Bowser's Fury); SIGBUS inside Metal (`AGCDeserializedReply`, an AGX compiler block) at an address in the guest stack region (Breath of the Wild). → [Host calls on small guest stacks](../reference/memory.md#host-calls-on-small-guest-stacks) - the iPhone app is killed for memory; resident memory grows steadily (about 0.2 MB a frame) while the residency set and the texture counts stay flat. → [Deferred-release drain without an autorelease pool](../reference/memory.md#deferred-release-drain-without-an-autorelease-pool) - travelling produces a brief multi-GB footprint spike, then memory returns to its earlier level; periodic memory lines can miss the peak. Upload diagnostics show many swapped-out blocks still alive in one batch. → [Upload staging grows within one rendering submission](../reference/memory.md#upload-staging-grows-within-one-rendering-submission) - GPU memory grows with repeated `nvnTextureReadTexels` calls on a long-lived game thread, even after each readback completes. → [GPU readback without an autorelease pool](../reference/memory.md#gpu-readback-without-an-autorelease-pool) - process footprint and Metal allocation grow during stationary gameplay even after readback fences complete; the deferred-release queue and command allocator sizes remain bounded. → [Completion readbacks survive a guest waiter's pool](../reference/memory.md#completion-readbacks-survive-a-guest-waiters-pool) - `footprint` shows `Malloc Large` about the size of `pso_archive/` (the log's `pipeline archive …: N files, … MB`), resident or swapped for the whole run. `MallocStackLogging=1` with `malloc_history <pid> -allBySize` gives `newArchiveWithURL` → `MTL4ArchiveImpl::loadFromURL` → `LoaderGlobalState::loadFile` → `-[NSData initWithContentsOfFile:options:maxLength:error:]` → malloc. → [A pipeline archive on an external drive is read into memory](../reference/memory.md#a-pipeline-archive-on-an-external-drive-is-read-into-memory) - the periodic `residency set up to frame` line shows hundreds of allocations added and removed per 300 frames in a scene where nothing loads: Ocarina of Time, 1,500 (`pool_gpu` 900 of 180 KB, `mrbuf_get` 600 of 0.5 MB), and 650 commits. → [Pool tables and readback buffers made anew each frame](../reference/memory.md#pool-tables-and-readback-buffers-made-anew-each-frame) - with a profile that has `tex_dirty_upload`, a texture in a sparse pool that the game draws into or writes as an image logs `CPU-written texture ser=…` at its first use, and takes its content from its storage. `t_sparse_tiles` crashed at `and unmapped, not drawn: its heap tile goes back` when built with such a profile, and passed with one without the key. → [A texture in a sparse pool came out CPU-written at its first use](../reference/memory.md#a-texture-in-a-sparse-pool-came-out-cpu-written-at-its-first-use) - on an iPhone the app is ended by the system (a jetsam event: no crash report, no `[dm] CRASH` line) once its footprint reaches the limit: about 6 GB on a 12 GB iPhone with the increased memory limit (6,143 MiB measured in LiveContainer), 3.3 GB without it. The log stops mid-frame. → [iOS ends the app once the guest's touched pages reach its memory limit](../reference/memory.md#ios-ends-the-app-once-the-guests-touched-pages-reach-its-memory-limit) - a Switch 2 game goes past Metal's recommended working set while its first 3D scene loads: `Insufficient Memory` command buffer errors, then a hung Mac. Ocarina of Time on a 16 GB Mac: 12 GB and more wired, once a kernel panic in `IOGPUGroupMemory.cpp` at 14.7 GB wired. → [Memory pools nothing gave an address to stay out of the raw pool table](../reference/memory.md#memory-pools-nothing-gave-an-address-to-stay-out-of-the-raw-pool-table) - a game whose shaders read texture handles from memory wires far past the working set while a scene loads, with `Insufficient Memory` errors or a panic, and stutters when new textures stream in. With a limit on how many it makes, surfaces in shadow go near black instead. → [Shaders report which textures they read through a pool](../reference/memory.md#shaders-report-which-textures-they-read-through-a-pool) - the Mac grows unresponsive for hours, then panics, with the host still submitting work that fails. → [Repeated GPU out-of-memory failures end the game](../reference/memory.md#repeated-gpu-out-of-memory-failures-end-the-game) ## Threads - TSan reports `thread_main` writing `host_work` while `thr_runnable` reads it during a same-core yield (`t_notify_sched`, issue #411). → [Publishing a new thread's scheduler fields](../reference/threads.md#publishing-a-new-threads-scheduler-fields) - a parent returns from `StartThread` before a newly runnable higher-priority child pinned to its core finishes its work (deterministic regression, not attributed to a game failure). → [Starting a higher-priority thread on the caller's core](../reference/threads.md#starting-a-higher-priority-thread-on-the-callers-core) - a crash at the very start of a new thread, reading through a null pointer it took from its argument (`main+0x1dc0`, in a boot stub's last thread, about once in a dozen boots), with the starter still in its next few calls. → [A thread's arguments in slots its starter reuses after connecting to a service](../reference/threads.md#a-threads-arguments-in-slots-its-starter-reuses-after-connecting-to-a-service) - per-core job queues never drained. → [Core mask changes move the ideal core into the new mask](../reference/threads.md#core-mask-changes-move-the-ideal-core-into-the-new-mask) - crash indexing a per-core table with a huge offset (index −2). → [Ideal core −2 resolves to the process default core](../reference/threads.md#ideal-core-2-resolves-to-the-process-default-core) - the main thread waits forever on an event right after `nnMain` starts, with only three or four threads created; `DM_THR=1` shows no `CreateThread` for the thread it waits on. → [Free thread count (`svcGetInfo` type 24)](../reference/threads.md#free-thread-count-svcgetinfo-type-24) - in garbage-collected titles (Unity / IL2CPP), live objects freed, with their finalizers releasing native resources. → [Pausing threads and reading their context for garbage collectors](../reference/threads.md#pausing-threads-and-reading-their-context-for-garbage-collectors) - in a garbage-collected title whose collector stops threads cooperatively, live objects freed while their thread sleeps, and their memory reused: a crash in the collected runtime's code on a pointer made of another object's bytes (Streets of Rage 4: `CRASH sig=11` at `main+0x46a4`, BRUTE's `SyncBlock::GetSyncBlock`, on `0x5b005b00000002`, a string's length 2 and "[["), in about two boots of three, during the first seconds of loading. → [SVCs leave the stack below sp untouched](../reference/threads.md#svcs-leave-the-stack-below-sp-untouched) - crashes around movie changes in the game's own player threads, about one run in two: `SignalEvent` → `MultiWaitImpl::NotifyAndWakeupThread` on a null MultiWait at address 0x20; `WaitAny` walking freed holders; a worker reading a freed object at `main+0x225338`. The other way round, a handoff that waits too widely: a black screen at boot that never loads a texture (`packaged textures: first uploads 0`), or a load that never ends behind an animated loading screen, with the thread dump's `same-core handoffs N, total T ms` larger than the run itself. → [Same-core wake handoffs](../reference/threads.md#same-core-wake-handoffs) - the picture stops for good while sound goes on; the main thread spins in the game's own wait loop (a `sample` of the process shows it in guest code, no SVC), the other guest threads wait, and the job workers it waits for sit in `svc_thread` → `dm_yield_to_core_peers` → `nanosleep`. → [A same-core handoff holds only a waker pinned to that core](../reference/threads.md#a-same-core-handoff-holds-only-a-waker-pinned-to-that-core) - the picture stops and stays (sound goes on) at random places, about one run in two: every task worker waits on its own event, and the task a waiter waits for counts a subtask that is marked queued but is in no queue (the ring's head equals its tail). → [Lock-free queues published without barriers](../reference/threads.md#lock-free-queues-published-without-barriers) - the game freezes when a movie starts playing beside the game (a guide movie in a corner of the screen): the last frame stays, the process idles at a few percent of a core, and the thread dump shows a lower-priority job thread `running/not waiting` with its backtrace in the movie player (`ReleaseOutputBufferIndex`), the main thread waiting for it, and the movie's input thread `running/not waiting` too. A `sample` of the process shows the job thread in `md_pump` → `md_event` → `dm_yield_to_core_peers`, and the input thread in `h_movie_SendIn` → `md_pump` waiting for a pthread mutex. → [A host lock held across a same-core handoff](../reference/threads.md#a-host-lock-held-across-a-same-core-handoff) - several threads crash at once and the dumps interleave, then the process hangs instead of exiting. → [Simultaneous crashes of several threads](../reference/threads.md#simultaneous-crashes-of-several-threads) - `watchdog: sampling failed` and no thread stacks when `DM_WATCH_SAMPLE` contains an apostrophe, such as `/tmp/John's Mac/hang.txt`; shell syntax in the path can also run commands, and long paths are truncated. → [Watchdog sample output paths are literal arguments](../reference/threads.md#watchdog-sample-output-paths-are-literal-arguments) - none seen; found while investigating Fire Emblem Engage's demo crash, which it did not change (that was the address-space shortage, Size-aligned regions exhaust the alias address space). → [`SignalToAddress` type 2 with count ≤ 0](../reference/threads.md#signaltoaddress-type-2-with-count--0) - a 64-bit wait could return at once or block when it should not (not met in a game). → [`WaitForAddress` type 3: 64-bit wait if equal](../reference/threads.md#waitforaddress-type-3-64-bit-wait-if-equal) - boot stops before or soon after the first frame with the CPU at 0% and every guest thread waiting on a condition variable: the main thread in `nn::os::AcquireSemaphore` after posting a command to `UnityGfxDeviceWorker`, the worker in `AcquireSemaphore` too, one condition wait after it (`wait #` one higher); 3 of 5 Mac runs, at random points. → [Unity's stream buffer handshake loses a wake-up on Apple cores](../reference/threads.md#unitys-stream-buffer-handshake-loses-a-wake-up-on-apple-cores) - the picture stops and sound goes on, at a random frame (3,000 to 51,300, about 100 s at the quickest), with no `[RED]` line and the GPU idle and caught up. `main` is parked in `nn::os::WaitConditionVariable`, called from the park in Trinity's submit loop. The release flag is set, the state word is 1, the mutex is free, and no `SignalProcessWideKey` was ever issued for that key. → [Trinity's rendezvous loses its release on Apple cores](../reference/threads.md#trinitys-rendezvous-loses-its-release-on-apple-cores) - a game that runs on the Switch crashes on the Mac 10 to 60 s into a scene, at a different place each run, with garbage in a list the game just built (Breath of the Wild 1.6.0: `h_nvnBufferGetAddress` called with a row's metadata word as the buffer pointer, `main+0x14ef6e0`; also faults in `main+0x12970dc`, `+0x13615f4`, `+0x1445d48`, `+0x1472470`). A trace of the draw-list builders shows two threads inside the same view at once, running the same job descriptor. → [Lock acquire without acquire ordering runs a queue item twice](../reference/threads.md#lock-acquire-without-acquire-ordering-runs-a-queue-item-twice) - a PhysX worker crashes in a task's `removeReference` with a null task manager, right as the game switches to 30 fps (`pc=main+0x10ccf28`, `lr=main+0x13c236c`); on the iPhone and in 2 of 5 Mac runs, in every Mac run with 12 busy loops loading the CPU. → [Late PhysX task destructor after the unlock](../reference/threads.md#late-physx-task-destructor-after-the-unlock) - `game called nn::diag abort: Result 0, call site sdk+0x153c34` during `main`'s static initialisers, `bt: sdk+0x153c34 sdk+0x137eb4 sdk+0x13dc50 sdk+0x13fa90 sdk+0xa4d64 main+0x134 run_module_inits+0xa8 guest_main+0x15c main+0xfc start+0x1a20`, and no game code on the stack at all. → [The thread ID at ThreadLocalRegion+0x110 (SDK 22)](../reference/threads.md#the-thread-id-at-threadlocalregion0x110-sdk-22) - a 30 Hz game thread runs at 27 Hz, and whatever it paces comes out slow (cutscenes at 36 ms per frame instead of 33.3; gameplay was fine at 60). → [Timer slack in guest sleeps (`sleep_precise`)](../reference/threads.md#timer-slack-in-guest-sleeps-sleep_precise) - a guest thread keeps a core at 100% with billions of `SleepThread` calls. → [Sleeps under 20 µs take the yield path](../reference/threads.md#sleeps-under-20-µs-take-the-yield-path) - a thread polls at full speed although the power line's yields (if any) show no back-off sleeps; a `sample` of the host shows it in `svc_thread` → `block` → `pthread_cond_wait` with timeouts of nanoseconds, between plain `cthread_yield`s. → [Short timed waits are polls](../reference/threads.md#short-timed-waits-are-polls) - a loading screen sits for a minute with the CPU nearly idle; one thread yields thousands of times a second, every yield a back-off sleep (the power line's top yielder, with as many back-off sleeps). → [Yields that make progress return at once (`thr_yield`)](../reference/threads.md#yields-that-make-progress-return-at-once-thr_yield) - one guest thread keeps a host core at 100% with about a billion yields a minute (`SVC 0xb` in `DM_HLECOUNT`), none of them a back-off sleep, while the game itself plays normally. → [A wait at two yields is not progress](../reference/threads.md#a-wait-at-two-yields-is-not-progress) - a host helper thread aborts when signalling a destroyed `SystemEvent`; repeated `vi::GetDisplayVsyncEvent` calls double the event's tick rate. Rapid replacement can abort with `too many vsync events`, or a retired vsync worker can signal another service's event at reused storage. → [Service-event producers follow the binding lifetime](../reference/threads.md#service-event-producers-follow-the-binding-lifetime) - the main thread waits forever on a job's done event at boot while every worker sleeps, two of them on one event (`main+0x1426c` waiting on `Job::m_doneEvent`); 4 of 6 Mac runs. → [One auto-clear event shared by a pool's workers](../reference/threads.md#one-auto-clear-event-shared-by-a-pools-workers) - abort in `os::WaitSystemEvent` under `oe::PopNotificationMessage` (The Legend of Zelda: Link's Awakening); one guest thread at about 1000 ms/s on the iPhone only, the phone hot, CPU energy 5–7 W (Monster Hunter Rise's `MessageSuperviseThread`, priority 32, in the `[nvn] threads` lines). → [The oe notification event and its queue](../reference/threads.md#the-oe-notification-event-and-its-queue) - Paper Mario: The Thousand-Year Door 1.0.1 stays black before its first frame. The main thread stops at `main+0x32796c`, after starting `SYS_Notification`; the priority-28 notifier is in `oe::PopNotificationMessage`, while the priority-44 main thread waits for its same-core wake handoff. → [Native HLE waits release the guest core](../reference/threads.md#native-hle-waits-release-the-guest-core) - every save slot shows NO DATA and `Play Time 0 mins`, right after "Save was successful" and with a save imported from elsewhere, though the files are there and a commit is logged. Reopening the save screen reads no save file (`DM_FS=1`). The terms of service come back at every boot, since the system data save is refused too. → [File system calls are service requests](../reference/threads.md#file-system-calls-are-service-requests) ## Services and SDK calls - `sm::Initialize` aborts right after `ConnectToNamedPort` (SVC 0x1F) and `SendSyncRequest` (0x21); abort inside `nn::sm::Initialize`, the log showing `SVC 0x1f` (ConnectToNamedPort, port name `sm:`) and `SVC 0x21` answered by placeholders, then an `nn::diag` abort; abort with no message at start-up in a service call the host has no hook for (`Break` from `sdk+…` with an `nn::diag` backtrace). → [SDK calls that open a system service through sm](../reference/services.md#sdk-calls-that-open-a-system-service-through-sm) - a game update aborts at boot where the base game ran. → [A game update imports SDK calls the base game did not](../reference/services.md#a-game-update-imports-sdk-calls-the-base-game-did-not) - abort in `sm::Initialize` under `sf::hipc::InitializeHipcServiceResolution`, right after the first frames (from `main+0x5b8198`). → [Game-linked HIPC clients of system services](../reference/services.md#game-linked-hipc-clients-of-system-services) - a call the host hooks under its newer name reaches the SDK's own code on an older game. → [Older SDK names for the same calls](../reference/services.md#older-sdk-names-for-the-same-calls) - abort in `sm::Initialize` under `nn::friends::GetBlockedUserList` after the opening movie. → [SDK 4's `friends::GetBlockedUserList` without a `Uid`](../reference/services.md#sdk-4s-friendsgetblockeduserlist-without-a-uid) - the first loading screen never ends; `DM_FS=1` shows `save:/system` "not found" and no `fs mount save`. → [SDK 6's `account::OpenPreselectedUser` returns a Result](../reference/services.md#sdk-6s-accountopenpreselecteduser-returns-a-result) - the host crashes in `h_fs_OpenDirectory` when its folder-backed directory handle allocation fails. → [Directory handle allocation failure](../reference/services.md#directory-handle-allocation-failure) - IL2CPP "Could not open …/global-metadata.dat" (then a crash in its logger). → [The SDK's own `fs::IsMounted` reads an empty mount table](../reference/services.md#the-sdks-own-fsismounted-reads-an-empty-mount-table) - `game called nn::diag abort: Result 0x7802` (`MountNameAlreadyExists`) when a game mounts a RAM disk under a name it has just unmounted. → [A mount in the SDK's own table stays until the SDK releases it](../reference/services.md#a-mount-in-the-sdks-own-table-stays-until-the-sdk-releases-it) - a 10-byte read of the wrong RomFS file, then a null pointer at boot; files named `rom:\StartupUI.pak` are not found. → [File handles with low bits set, and backslash paths](../reference/services.md#file-handles-with-low-bits-set-and-backslash-paths) - after a rebuild, a game shows every file of its file select as new, while its save folder holds names that start with a backslash (`\savedata0.bin`, `\screenshot0.bin`). → [Saves named before backslash paths](../reference/services.md#saves-named-before-backslash-paths) - a fault inside `sdk` at boot, right after the save data is mounted: `ldr w8, [x0, #0x24]` with `x0` holding a host file handle (SD GUNDAM G GENERATION CROSS RAYS: `sdk+0x62a78`, `x0 = 0x4000000000000390`), while `GetFileSize` on the same handle answered just before. → [An unhooked `fs::ReadFile` overload falls through to the SDK's own](../reference/services.md#an-unhooked-fsreadfile-overload-falls-through-to-the-sdks-own) - Addressables never start (no `StreamingAssets/aa/settings.json` in the `DM_FS=1` output at all), then a null asset crash (`main+0x31100ec`). → [C library path checks ask the file system's limits](../reference/services.md#c-library-path-checks-ask-the-file-systems-limits) - an Atk task aborts in a `switch` default (`UnexpectedDefaultImpl`, then `AbortImpl`) while a stream sound loads. → [Paths with `.` and `..` components](../reference/services.md#paths-with--and--components) - a long black screen at boot with nothing in the log (Engage: about 17 s on the Mac, 32 s on an iPhone); sampling the process (`sample <pid> 3`) shows `getxattr` under `path_component` at the top of stack. → [RomFS lookups on large directories](../reference/services.md#romfs-lookups-on-large-directories) - `[RED] fs ReadFile into … failed at +0 (EFAULT): VM region … protection 1`, now and then. → [ReadFile into write-protected texture pool pages](../reference/services.md#readfile-into-write-protected-texture-pool-pages) - `fs … not found` lines with `DM_FS=1`. → [File-not-found noise from optional paths](../reference/services.md#file-not-found-noise-from-optional-paths) - a missing `fs::DeleteDirectory`; undefined `nn::fs::` / `nn::account::` imports with no hook, found from the import list (Listing a game's unhooked imports before they are met) before they were met. → [Directory, file data cache and save-thumbnail calls](../reference/services.md#directory-file-data-cache-and-save-thumbnail-calls) - the SDK's own code opened fsp-srv and aborted, leaving the save writes uncommitted. → [`fs::Commit` with a list of mounts](../reference/services.md#fscommit-with-a-list-of-mounts) - a failed write in one independent save can make another save's next `Commit` fail and discard its successful changes; the damaged save may then commit its truncated working file. → [Save-write failures stay with their backing transaction](../reference/services.md#save-write-failures-stay-with-their-backing-transaction) - `[RED] save transaction: cloning the work directory failed (…, errno=45)` when the save folder (`DM_SAVE`) is on an external drive, then a read-only save mount and every save write failing (South Park: `profile.sys`); now the line reads `the save folder's filesystem cannot clone directories (save transactions need APFS …)`. → [A save folder that cannot clone directories](../reference/services.md#a-save-folder-that-cannot-clone-directories) - SIGSEGV at address 0 in `nn::fs::GetSaveDataSizeMax`, about 13 minutes into a new game. → [Save data size queries](../reference/services.md#save-data-size-queries) - each aborted in `sm::Initialize` or read a null applet proxy, one per boot. → [Cache storage and other titles' save data](../reference/services.md#cache-storage-and-other-titles-save-data) - the island lives in device save data, which the host did not mount. → [Device save data on the account save's directory](../reference/services.md#device-save-data-on-the-account-saves-directory) - every boot asks to pick a Mii again (`DM_FS=1`: `UserSave:/userdata.dat` not found although the host save has it). → [Device and account save data as two saves](../reference/services.md#device-and-account-save-data-as-two-saves) - abort in `fs::detail::GetFileSystemProxyServiceObject` under `fs::QueryMountSystemDataCacheSize` (`main+0x8f23bc`). → [System data stand-in for the MiiModel archive](../reference/services.md#system-data-stand-in-for-the-miimodel-archive) - a failed write of `<DM_SAVE>.sync.tmp` leaks its stream, and the diagnostic can report a cleanup error instead of the write error. → [Save-sync metadata errors close the temporary file](../reference/services.md#save-sync-metadata-errors-close-the-temporary-file) - DLC the player owns is not unlocked. → [Add-on content from `DM_AOC_DIR`](../reference/services.md#add-on-content-from-dm_aoc_dir) - some owned DLC is missing, and `aoc: reporting` stops at 64 add-on contents. → [Owned add-on content lists beyond 64 entries](../reference/services.md#owned-add-on-content-lists-beyond-64-entries) - SIGSEGV in `crypto::detail::CbcModeAes128Helper::DecryptBlocks` with a null destination (`main+0x8737e8`, right after `aoc:` is mounted). → [Add-on content mount cache sized as RomFS working memory](../reference/services.md#add-on-content-mount-cache-sized-as-romfs-working-memory) - SIGBUS in `__vfprintf` under `aoc_load`, from `h_aoc_Count` (a store to `0x…67ff0`, right below a page of the guest thread's stack). → [Add-on content queries on a small guest stack](../reference/services.md#add-on-content-queries-on-a-small-guest-stack) - clang reports a negative shift in `fill` or `vib_targets` (`hle_hid.c`). → [Controller disconnect between style and player lookup](../reference/services.md#controller-disconnect-between-style-and-player-lookup) - connecting a Steam Controller clears another controller's held input or rumble and makes it press a button to rejoin; a composite controller can appear as two players or lose native fallback after a partial exclusive open. → [Steam Controller hotplug interrupts other players](../reference/services.md#steam-controller-hotplug-interrupts-other-players) - `DM_RUMBLE_MIN` silences quiet effects on native controllers but has no effect on the Steam Controller's direct HID output. → [Steam Controller bypasses the rumble cutoff](../reference/services.md#steam-controller-bypasses-the-rumble-cutoff) - six-axis values reach the game but gyro aiming does nothing, or stops after using a stick. → [Steam Controller stick drift suppresses gyro aiming](../reference/services.md#steam-controller-stick-drift-suppresses-gyro-aiming) - buttons and menus work, the sticks do nothing in play (Super Mario Odyssey: its first hint, "Look Around", waited forever); an `nn::diag` abort with Result 0x2aca in the first frames of `nnMain` (Hollow Knight: Silksong, Unity 6000.0.50f1: `bt: sdk+0x514580 main+0x1296c64 …`). → [History reads fill every requested entry](../reference/services.md#history-reads-fill-every-requested-entry) - the game never reads the controller (the title's "Press L+R" never sees a press; no `GetNpadState` call at all). → [Npad style set update event](../reference/services.md#npad-style-set-update-event) - motion moves never happen; shaking does nothing (Super Mario Odyssey: cap throws by shaking). → [Six-axis sensors](../reference/services.md#six-axis-sensors) - motion controls do nothing with a controller that has a gyroscope (Breath of the Wild: aiming with its Motion Controls option on); the six-axis sensor always lies flat. → [Live controller motion](../reference/services.md#live-controller-motion) - a non-finite accelerometer or gyro sample corrupts the six-axis fields; later valid samples do not restore the previous fusion state. → [Non-finite motion samples](../reference/services.md#non-finite-motion-samples) - on iPhone Duo's inner display the phone's gyro is turned a quarter turn: tilting up and down moves the pointer left and right, and the other way round (GitHub issue #569); the outer display is right. → [The phone's motion in the picture's frame](../reference/services.md#the-phones-motion-in-the-pictures-frame) - a Pro Controller's buttons work on the Mac, but its gyro pointer never moves; `GCMotion` callbacks arrive with acceleration and rotation all zero. → [Switch Pro Controller advertises motion but sends zeroes](../reference/services.md#switch-pro-controller-advertises-motion-but-sends-zeroes) - six-axis handles use byte 0 = 0 for a FullKey controller, which the SDK reserves for no style; Handheld exposes two sensors instead of its combined sensor. → [Six-axis handle encoding](../reference/services.md#six-axis-handle-encoding) - a button mapped to Shake does nothing on a secondary controller, including the first physical controller with `DM_KBD_PLAYER=own`, even though its normal buttons work in a one-player game. → [Mapped Shake on secondary controllers](../reference/services.md#mapped-shake-on-secondary-controllers) - SDK 20 calls that reach a service; `nfp`'s `AttachActivateEvent` / `AttachDeactivateEvent` crashed in the SDK at `sdk+0x3f2a78`. → [SDK 20 six-axis sensor and amiibo (`nfp`) calls](../reference/services.md#sdk-20-six-axis-sensor-and-amiibo-nfp-calls) - `[RED] sf: the game connects to service nfp:user itself`, then `game called nn::diag abort: Result 0xe15` under the game's own initialization (`main+0x115deb0`). → [`nfp`'s extended application area](../reference/services.md#nfps-extended-application-area) - selecting amiibo initializes `nfp`, then the game connects to the unserved `nfc:user` service and aborts in `nn::nfc::Initialize`. → [NFC initialization beside the amiibo library](../reference/services.md#nfc-initialization-beside-the-amiibo-library) - `game called nn::diag abort: Result 0, call site sdk+0x13ce58` in the middle of play, from `nn::os::TryWaitSystemEvent` on an event that was never set up (backtrace `main+0x1fb9920` in Tears of the Kingdom 1.4.3). → [The amiibo library's state before Initialize](../reference/services.md#the-amiibo-librarys-state-before-initialize) - abort in `nn::sm::Initialize` under `nn::hid::VibrationNode::Update`. → [Vibration values flushed by the SDK's vibration graph](../reference/services.md#vibration-values-flushed-by-the-sdks-vibration-graph) - with rumble on, `[RED] sf: the game connects to service hid itself`, then `CRASH sig=11 addr=0` in `hid::detail::IsVibrationDeviceMounted` (`sdk+0x24254c` in SDK 7), under `hid::IsVibrationDeviceMounted`. With rumble off in the host's settings the game never asks. → [Whether a vibration device is mounted](../reference/services.md#whether-a-vibration-device-is-mounted) - `DM_RUMBLE_LOG=1` shows the game's startup handle request answered with none, then every vibration value sent to handle 0 and reaching no output for the whole session, although a controller with haptics (a DualSense on the Mac) is connected. A game that rumbles would stay silent. → [Vibration handles before a controller is reported](../reference/services.md#vibration-handles-before-a-controller-is-reported) - a controller (an Xbox Wireless Controller, a GameSir Super Nova, a GameSir Cyclone) never vibrates in a game on the Mac or the iPhone, though iOS Settings' Identify buzzes it; the log repeats `[RED] haptics: controller left handle create player: Couldn’t communicate with a helper application. (NSCocoaErrorDomain 4097)`. The engine itself starts. → [Controller haptic engines without advanced players](../reference/services.md#controller-haptic-engines-without-advanced-players) - on the Mac, a DualShock 4 or a controller that presents itself as one (a GameSir Cyclone over Bluetooth: HID vendor `054C`, product `05C4`, `productCategory` "DualShock 4") does not rumble; Core Haptics failed on every locality with NSCocoaErrorDomain 4097 (issue #363, also in a minimal Swift app), while the same controller rumbles in an SDL-based emulator. → [DualShock 4 rumble through its effects report](../reference/services.md#dualshock-4-rumble-through-its-effects-report) - with two controllers that present themselves as DualShock 4s on the Mac, the one turned on first rumbles normally and the one turned on later is barely felt. The first logs `rumble through the DualShock 4 effects report`; the later one logs `haptics: player 2 controller …, localities …`, then `has no advanced players (NSCocoaErrorDomain 4097): plain players` and `plays both motors on one engine (Handles)`. → [A DualShock 4 that connects after the first stays on Core Haptics](../reference/services.md#a-dualshock-4-that-connects-after-the-first-stays-on-core-haptics) - with a controller connected (a DualShock 4 here), `DM_KEYS` and `DM_CTL` presses are logged (`DM_KEYS: … press …`) but the game does not react to them, or only now and then; without the controller the same script works. → [Scripted presses on a path of their own](../reference/services.md#scripted-presses-on-a-path-of-their-own) - taps in handheld mode do nothing, though the game reads the touch screen (the title's PRESS ANY BUTTON, the menus' cards). → [Touch gestures recognized from the touch points](../reference/services.md#touch-gestures-recognized-from-the-touch-points) - on the Mac, the mouse pointer stays over the game picture while playing with a controller or the keyboard, in a window and in fullscreen (issue #675). → [Mac pointer stays over the game](../reference/services.md#mac-pointer-stays-over-the-game) - the Mac dims or turns off its display and can reach the lock screen while the player is using a controller, in a window or in fullscreen. → [Mac display sleep during controller play](../reference/services.md#mac-display-sleep-during-controller-play) - the first boot aborted in `hid::GetMouseState` (the SDK's mouse resource was never initialized). → [Mouse, keyboard and key code maps](../reference/services.md#mouse-keyboard-and-key-code-maps) - the first boot crashed in `hid::detail::SetPalmaBoostMode`, a null read at `sdk+0x238eb0` (the hid service never opened). → [Poké Ball Plus (Palma)](../reference/services.md#poké-ball-plus-palma) - undefined `irsensor` imports found from the import list (Listing a game's unhooked imports before they are met). → [IR camera reported unconnected](../reference/services.md#ir-camera-reported-unconnected) - null read in `sdk` under `nn::applet::CreateLibraryApplet` (Engage: title menu → DLC → `nn::ec::ShowShopAddOnContentList`); `Show…` overloads found in the imports before they were met. → [System applets opened by `Show…` calls](../reference/services.md#system-applets-opened-by-show-calls) - entering 2P stops the game on its 2P screen: the same frame repeats, the music plays, no controller does anything, until the window loses and regains focus (Mario Kart 8 Deluxe, every launch). With one controller, once that was fixed: the 2P character select ignores input while the log shows the controller applet opened again every few frames. → [Library applets take the application's focus](../reference/services.md#library-applets-take-the-applications-focus) - the sound stutters and the input box lags while the player types a name (Octopath Traveler 0 on an iPhone: one 4.7 s frame, 5,035 wakeups a second instead of about 1,800, and no audio underruns). → [The software keyboard blocks only its caller](../reference/services.md#the-software-keyboard-blocks-only-its-caller) - null read in `applet::CreateLibraryApplet` under `swkbd::InlineKeyboard::Initialize` (3D World, entering the save select after the character select). → [The inline keyboard as a resident library applet](../reference/services.md#the-inline-keyboard-as-a-resident-library-applet) - texture creation returns null right after the inline keyboard's `Initialize`, then a null read at `main+0x7713044`. → [Inline keyboard window size, setters and callbacks](../reference/services.md#inline-keyboard-window-size-setters-and-callbacks) - the hunter's name box stays empty, then stays open with the name in it (Monster Hunter Rise, character creation). → [Inline keyboard text callbacks and `Calc` states](../reference/services.md#inline-keyboard-text-callbacks-and-calc-states) - the name typed in the Mac input box is dropped and the game asks again; the log has `oe focus state → 2` and `→ 1` between `inline keyboard Appear` and `→ OK` (Monster Hunter Rise, character creation). → [The Mac input box keeps the game's focus](../reference/services.md#the-mac-input-box-keeps-the-games-focus) - `CRASH sig=10` at a heap address, called from `main+0x6bca160` right after the name was entered (Monster Hunter Rise); crash in `lmem::AllocateFromExpHeap` under `ngc::ProfanityFilter::MaskProfanityWordsInText` right after the character name is entered (DARK SOULS: REMASTERED); filter methods among the undefined imports with no hook, found from the import list before they were met (The Great Ace Attorney Chronicles). → [`nn::ngc::ProfanityFilter` vtable and by-name overloads](../reference/services.md#nnngcprofanityfilter-vtable-and-by-name-overloads) - `[RED] sf: the game connects to service ngct:u itself, which the host does not serve`, then `Break#1 reason=0 Result=0xe15` from the SDK when the player name is entered after a race (Cruis'n Blast). → [`nn::ngc` China-region profanity check and mask](../reference/services.md#nnngc-china-region-profanity-check-and-mask) - SIGSEGV in `vi::CreateLayer(Layer**, Display*, int, int)` (`sdk+0x3f9bc4`, from SDL3's Switch video driver at `main+0x239304`). → [`vi::CreateLayer` with the layer's size](../reference/services.md#vicreatelayer-with-the-layers-size) - SIGSEGV at `sdk+0x44ea94` reading address 0, in `vi::CreateLayer`, right after `am::GetSelfController()`; the caller is the game's window setup (`main+0x978cb6c`). → [`vi::CreateLayer` with `LayerCreationSettings` (SDK 22)](../reference/services.md#vicreatelayer-with-layercreationsettings-sdk-22) - SIGSEGV in `vi::SetLayerCrop` or `vi::OpenDisplay` when opening a display by name. → [vi layer and display calls without vi service objects](../reference/services.md#vi-layer-and-display-calls-without-vi-service-objects) - `CRASH sig=11 addr=0 pc=0` with the link register just after a call to a `vi::SetLayerNextHdr…` or `vi::ClearLayerNextHdr…` function. → [Layer HDR metadata](../reference/services.md#layer-hdr-metadata) - SIGSEGV in `android::Surface::getQueuedFrameNumber` under `nn::vi::GetLatestFrameNumber`. → [Layer frame numbers](../reference/services.md#layer-frame-numbers) - SIGSEGV in `vi::GetDefaultDisplayPanelIdentifier` (`main+0xa9a4`, before the window). → [Default display panel identifier](../reference/services.md#default-display-panel-identifier) - the first boot crashed in `oe::DisableAlbumImageTakenNotification`: a null read at `sdk+0x338070`, the first call in `nnMain` (`main+0x6b188c`); enabling those notifications also gives a null read at `sdk+0x33b0f0` (Xenoblade Chronicles 3); other `oe` calls that reach am, found in the imports before they were met. → [oe calls answered without an applet proxy](../reference/services.md#oe-calls-answered-without-an-applet-proxy) - a null read at `sdk+0x36ec60` in `oe::EnableAlbumImageTakenNotification`, called from `nnMain` (`main+0x286268`). → [oe calls answered without an applet proxy](../reference/services.md#oe-calls-answered-without-an-applet-proxy) - abort in `nn::sm::Initialize` under `nn::oe::FinishStartupLogo`, right after the first frames. → [The startup logo](../reference/services.md#the-startup-logo) - null read in `oe::InitializeCopyrightFrameBuffer`, right after the window setup. → [Copyright frame buffer overlay](../reference/services.md#copyright-frame-buffer-overlay) - SDK 20 calls that reach a service, each one boot; SDK 20's `OpenAudioRenderer` aborts on an ARUID of 0. → [Applet resource user ID, launch parameters and VR mode](../reference/services.md#applet-resource-user-id-launch-parameters-and-vr-mode) - a null read in `sdk+0x35258` (apm's session) in `oe::IsCpuOverclockEnabled`, the first call in `nnMain`; null read at `sdk+0x362b8` (`apm::SetCpuOverclockEnabled`) in the first calls of `nnMain` (`main+0x2e1e4c`). → [CPU overclock calls without an apm session](../reference/services.md#cpu-overclock-calls-without-an-apm-session) - the game freezes after switching apps and back, picture still, sound on; the main loop waits in its pause handshake (`main+0x5d10d4` / `main+0x5cea68`). Mac repro `DM_OE_SCRIPT=bg=1@20,bg=0@25`. → [Focus handling mode decides whether focus changes are notified](../reference/services.md#focus-handling-mode-decides-whether-focus-changes-are-notified) - abort in `sm::Initialize` under `capsrv::InitializeForApplication` (`album::Initialize`); calls that reach the album service, found in the imports before they were met. → [Album calls fail with no album](../reference/services.md#album-calls-fail-with-no-album) - a null read at `sdk+0x336ccc` in `pdm::QueryApplicationPlayStatistics` (Pokémon Sword, the second boot); undefined `nn::account::` / `nn::friends::` imports with no hook, found from the import list (Listing a game's unhooked imports before they are met) before they were met. → [Account, friends, play data and Nintendo Account calls](../reference/services.md#account-friends-play-data-and-nintendo-account-calls) - the game ends right after `nnMain`, with a crash in its own cleanup on an object it had not created yet (DRAGON QUEST BUILDERS 2: `CRASH sig=11 addr=0x60db0` at `main+0x2676c8`, x0 = 0, the callers `main+0x85210` and `main+0x7fabf8`). No red line. → [Creating an ssl context needs no network](../reference/services.md#creating-an-ssl-context-needs-no-network) - `abort` under `grpc_init` at startup, with no red line: `game called nn::diag abort: Result 0, call site sdk+0xb8fe8`, backtrace `sdk+0xba138 sdk+0x7bd670 sdk+0x777f30 main+0x21f0c80`, just after `fs mount _npln:` (Ocarina of Time). → [`EventFd` needs no network](../reference/services.md#eventfd-needs-no-network) - `Break#1 reason=0 Result=0` right after the first save is created, then exit 42; the stack has `nn::diag::detail::OnAssertionFailure` under `nn::image::JpegDecoder::Decode` (`sdk+0x394e4`), called from the game (Burnout Paradise Remastered, SDK 9.3). → [The local user's profile image](../reference/services.md#the-local-users-profile-image) - `[RED] sf: the game connects to service mii:e … mii:u itself`, then an abort. → [Mii database answered by the host](../reference/services.md#mii-database-answered-by-the-host) - the abort with no message (`SVC 0x15` / `0x1f` / `0x21` placeholders, then `Break` with `sm::Finalize` under `ShopServiceAccessServer::Proxy::Initialize`) from `ec::InitializeForShopServiceAccessors`, called from Unreal's `FOnlineSubsystemSwitch::Init` at the start of `nnMain`. → [Shop service accessors](../reference/services.md#shop-service-accessors) - a purchase watcher crashes in `nn::ec::InitializePurchasedEvent` after account selection, before it can wait for a notification. → [Offline purchased-item notifications](../reference/services.md#offline-purchased-item-notifications) - abort in `nn::sm::Initialize` under `nn::pctl::IsFreeCommunicationAvailable` (Engage, entering its first battle map). → [Parental controls and free communication](../reference/services.md#parental-controls-and-free-communication) - play report calls met entering the save select (3D World); undefined `nn::ldn::` / `nn::socket::` imports with no hook, found from the import list before they were met (Big Brain Academy). → [Network interface, LDN, socket and play report calls](../reference/services.md#network-interface-ldn-socket-and-play-report-calls) - `[RED] sf: the game connects to service bsd:u itself, which the host does not serve` (and bsd:s, bsd:a) at the game's first socket call, then the game's own abort: Star Fox's `vsocket.nintendo.cpp:148` logs `socket: 4` and stops. With only the connection cut, the game's HTTP thread aborted a few seconds in: its event loop's `poll` returned -1 with errno 14 (EFAULT), and the loop tolerates only EINTR (`main+0xbe2efc4`). → [SDK 21 socket initialization and overloads](../reference/services.md#sdk-21-socket-initialization-and-overloads) - `[RED] sf: the game connects to service bt itself, which the host does not serve`, then `game called nn::diag abort` at `sdk+0x16ba48` and exit 134, a second after the audio renderer starts. With `bt` and `btm:u` served as zeroed host sessions the abort moves to `nn::btm::user::InitializeBtmUserInterface` (`sdk+0xb8eb4`), before either session gets a request. → [Bluetooth LE at boot](../reference/services.md#bluetooth-le-at-boot) - the boot sits at a black loading screen for good, CPU nearly idle, every thread waiting, about 1 boot in 6 (3 in 4 with four Mac hosts at once); the title movie is never opened, and the save files are never probed. → [Network requests stay on hold before they settle](../reference/services.md#network-requests-stay-on-hold-before-they-settle) - one thread at 100% CPU from boot, with one SVC in 99 s (`NexusRevolution Socket`, `main+0x92c7c4`, the game's network thread). → [Socket `Poll` and `Select` with nothing to wait on](../reference/services.md#socket-poll-and-select-with-nothing-to-wait-on) - the first comparison in `nnMain` aborted in `sm`. → [Language codes](../reference/services.md#language-codes) - `DM_LANG=zh-Hans` or `zh-Hant` reaches the game unchanged, but its startup menu falls back to Japanese; the older `zh-CN` or `zh-TW` spelling selects Chinese. → [Chinese language aliases in settings comparisons](../reference/services.md#chinese-language-aliases-in-settings-comparisons) - abort in `sm::Initialize` under `nn::settings::GetAvailableLanguageCodes` (early in `nnMain`, `main+0x327888`); abort in `sm::Initialize` under `nn::settings::GetAvailableLanguageCodeCount()` (`main+0x117590`). → [Available language codes and their count](../reference/services.md#available-language-codes-and-their-count) - the font engine runs on garbage; crash after the shared fonts load, looking up the "?" glyph (`main+0x6c73c0`, a font cache lookup returning null), with SDK 10's `ScalableFontEngine::LoadFont` failing with error 403 and `SetFont` with 301 on both stand-in fonts; or Japanese, Korean or Chinese text draws nothing in a Unity game while Latin text is fine (Patrick's Parabox's language menu showed three blank lines). → [Shared font address: BFTTF header or bare TTF](../reference/services.md#shared-font-address-bfttf-header-or-bare-ttf) - abort in `nn::sm::Initialize` under `nn::pl::sharedresource::GetPlatformSharedResourceManager` (first thing in `nnMain`). → [Shared fonts requested all at once](../reference/services.md#shared-fonts-requested-all-at-once) - `[RED] oe::ExecuteProgram(<n>, <k> bytes of parameters: …)`; before this entry, a crash right after that line (`sig=4` on a trap, or the next function running). A program started on its own quits at boot: it expects the launch parameter its launcher passes. → [Multi-program applications: `oe::ExecuteProgram`](../reference/services.md#multi-program-applications-oeexecuteprogram) - a null read in `applet::StartLibraryAppletImmediately` under `web::OfflineWebSession::Start` at boot; a game's pause menu, an offline page, never shows, or the game waits for a message from it. → [Offline HTML pages in a web view](../reference/services.md#offline-html-pages-in-a-web-view) - a crash in the font engine at boot with the null glyph, from a code point no message uses (`main+0x62d20` on 1.0.0, `main+0x63780` on 1.1.4); `?` in text for an icon the stand-in does not draw. → [Every undrawn extension code point is a ring](../reference/services.md#every-undrawn-extension-code-point-is-a-ring) - `nn::jit::Initialize` crashes reaching for the jit service (`sdk+0x2e5414`). → [`nn::jit` taken over by the host](../reference/services.md#nnjit-taken-over-by-the-host) - `[RED] jit::GenerateCode command <n>: request <key> … is not in the image …: capture it on the Mac (DM_JIT_CAPTURE) and rebuild the image`, then the game crashes there (the iPhone, or the Mac with `DM_JIT_SERVE`). → [`nn::jit` served from an image on iOS](../reference/services.md#nnjit-served-from-an-image-on-ios) - controller-button icons in text show as `?`. → [Nintendo-extension glyphs for button icons](../reference/services.md#nintendo-extension-glyphs-for-button-icons) - on a phone, `GetSharedFontLoadState` would report "not loaded". → [Shared fonts on iOS](../reference/services.md#shared-fonts-on-ios) - a crash after the shared fonts load, looking up the "?" glyph (`nro0+0xaef8a8`, a null pointer from nn::font's texture cache), with `ScalableFontEngine::LoadFont` returning 201 on one engine and 0 on another, and `SetFont` 301. → [A shared font larger than the game's font engine memory](../reference/services.md#a-shared-font-larger-than-the-games-font-engine-memory) - SDK calls that reach the time service, each aborting in `sm::Initialize` (or found in the imports before they were met). → [Steady clock, clock snapshots and user clocks](../reference/services.md#steady-clock-clock-snapshots-and-user-clocks) - a call the host answers reads as failed when it succeeded, or reads leftover register bits. Super Smash Bros. Ultimate refills the Spirit Board at every visit, since the elapsed time between two snapshots never reads as known. → [Hooks whose return type did not match the SDK](../reference/services.md#hooks-whose-return-type-did-not-match-the-sdk) - `std::terminate` (`Break` from `sdk+0x5bfa48`) at the first real-time read (right after the first-boot dialog, `main+0x3f3f68` → `system_clock::now()`). → [`clock_gettime(CLOCK_REALTIME)` through the time source pointer](../reference/services.md#clock_gettimeclock_realtime-through-the-time-source-pointer) - after switching apps and back, one guest thread at 100% in a tight loop (`main+0x9abd0`, `x10 = 0`); the game freezes, picture still, sound on. Mac repro `DM_OE_SCRIPT=bg=1@20,bg=0@25`. → [Guest clock reads wait while the app is in the background](../reference/services.md#guest-clock-reads-wait-while-the-app-is-in-the-background) - abort in `sm::Initialize` under `nn::crypto::GenerateCryptographicallyRandomBytes` (Unicorn Overlord: `std::random_device` → the `sdk`'s own `getentropy` → `InitializeCsrng`; Z-A: the first call in `nnMain`, `main+0x1734b4`). → [Cryptographically random bytes](../reference/services.md#cryptographically-random-bytes) - `libc++abi: terminating due to uncaught exception of type std::__1::system_error` (the arguments came out as rubbish, the format named the failure) once the game's own code ran, with `sdk+0x5f2e60` (`std::terminate`) and `sdk+0x66ad2c`/`sdk+0x66acc8` (`get_terminate`/`terminate`) in the backtrace. → [`clock_gettime` is `nn::time`'s steady clock (SDK 22)](../reference/services.md#clock_gettime-is-nntimes-steady-clock-sdk-22) - relocation repeatedly scans all HLE and forced-takeover entries, and named-stub reuse becomes quadratic as more imports are missing. → [Host symbol indexes avoid repeated name scans](../reference/services.md#host-symbol-indexes-avoid-repeated-name-scans) - a library's `free` rejects a pointer (`CentralHeap::Free` → `NotNMallocPtrError`). → [Global symbol resolution in load order](../reference/services.md#global-symbol-resolution-in-load-order) - a weakly imported function the game calls although nothing defines it: an `UNIMPL` line, then an abort. → [Undefined weak imports bind to 0](../reference/services.md#undefined-weak-imports-bind-to-0) - crash in `nn::ro::InitializeWithPortName`. → [`nn::ro` and its port](../reference/services.md#nnro-and-its-port) - the frame loop runs, but the game waits for code it loads itself (`ro::RegisterModuleInfo` / `ro::GetBufferSize` red lines; `main` imports 1,045 `lua2cpp::create_agent_*` functions, global, that no ExeFS module defines, bound to stubs at start). → [Loading NROs with `ro::LoadModule`](../reference/services.md#loading-nros-with-roloadmodule) - `FATAL .../nro.tsv: more NROs than module slots (MAX_MOD 128)` before `nnMain` (GitHub issue #372); after increasing the capacity, startup eagerly copies several GB of inactive NRO data and bss. → [NRO tables sized from the manifest and snapshots taken on demand](../reference/services.md#nro-tables-sized-from-the-manifest-and-snapshots-taken-on-demand) - `[EOS] Failed to create platform` (the game plays offline); `refused …: an online SDK (Epic Online Services), not loaded`; `refused an NRR that registers only online SDKs (1 hashes)`. → [Online SDKs in NROs are never loaded](../reference/services.md#online-sdks-in-nros-are-never-loaded) - `main` imports EGL (SDL3's GL support) and `vkGetInstanceProcAddr` (its Vulkan support), but the game renders with NVN (`FNA3D_Driver_NVN.cpp`). → [GPU driver modules that are never loaded](../reference/services.md#gpu-driver-modules-that-are-never-loaded) - `UNIMPL _ZN5movie12SetAllocatorEPFPvmmS0_EPFvS0_S0_EPFS0_S0_mS0_ES0_`, `UNIMPL glslcInitialize`, then `UNIMPL _ZN5movie9ExtractorC1ENS_13ContainerTypeE` and a crash reading address 0x18 in an NRO (`pc=nro18+0x97f4`) as the first movie starts. → [Modules only the NROs import from](../reference/services.md#modules-only-the-nros-import-from) - `[RED] ro::LookupModuleSymbol BuiltDebug: not defined in that module` once at boot; nothing goes wrong after it. → [`ro::LookupModuleSymbol` for a name the module does not define](../reference/services.md#rolookupmodulesymbol-for-a-name-the-module-does-not-define) - harmless on the build it was written for, silent memory corruption on any other. → [Code inherited from another title at fixed addresses](../reference/services.md#code-inherited-from-another-title-at-fixed-addresses) - an abort connecting to `pl:u` at boot; a failed `nn::audio` call at boot. → [Built-in fonts and the audio device notification of SDK 21](../reference/services.md#built-in-fonts-and-the-audio-device-notification-of-sdk-21) - an abort in `nn::hid` at boot, in a Switch 2 game that sets up the Joy-Con's mouse mode. → [The Joy-Con mouse pointer](../reference/services.md#the-joy-con-mouse-pointer) - a crash at boot in `nn::vi` under `nn::streamplay::CreateIndividualDisplays`. → [GameShare guest displays](../reference/services.md#gameshare-guest-displays) - `[RED] sf: the game connects to service chat:u itself, which the host does not serve`, then `game called nn::diag abort: Result 0xe15` under `nn::chat::Initialize`. → [GameChat at boot](../reference/services.md#gamechat-at-boot) - `CRASH sig=11 addr=0 pc=sdk+0x6be4d4` in `nn::chat::GetChattingUid()`, from the game's title screen code. → [GameChat queries from the title screen (SDK 21)](../reference/services.md#gamechat-queries-from-the-title-screen-sdk-21) - `nn::diag abort` in `gs::sdk::CheckGraphicsSystemInitialized`, or a failed `camera::sdk::CreateCameraContext` (0x3af3), at boot. → [The camera through the graphics system](../reference/services.md#the-camera-through-the-graphics-system) - with the camera session answering 0xdc4 to every command, Star Fox logs `This platform does not support the camera function.` (its `vwebcam.switch2.cpp:997`) and dereferences a null on the way out (`main+0xba54e4c`); with 0x7c4 to every command its module aborts in `Initialize` (subsdk3+0x1ef4) or `Finalize` (subsdk3+0x200c). → [The camera commands of SDK 21's own camera module](../reference/services.md#the-camera-commands-of-sdk-21s-own-camera-module) - a null read at boot in `nn::oe::IsLanguageSelectionLimited`, right after the game asks for its language. → [Whether the language selection is limited](../reference/services.md#whether-the-language-selection-is-limited) - a null read at boot in `nn::os::SdkMutexType` under `nn::gs::sdk::SetGraphicsFrameLengthMode`, called from `nn::oe::SetGraphicsTargetFrameRate`. → [The target frame rate (graphics frame length)](../reference/services.md#the-target-frame-rate-graphics-frame-length) - a Switch 2 game presents at 720p, with its upscaler at the matching low size. → [The display's largest buffer](../reference/services.md#the-displays-largest-buffer) - `registered NROs not found` from `nro_collect.py` in a game whose RomFS has an NRR, or `[RED] ro::LoadModule: no rewritten NRO with SHA-256 …`. `main` is small (about 600 KB of code) beside a data segment of random-looking bytes. → [A game that decodes its code at run time](../reference/services.md#a-game-that-decodes-its-code-at-run-time) - a crash in `ro::RegisterModuleInfo`, or an NRR that seems to register millions of hashes: the words at +0x340 and +0x344 are random. → [NRR version 1](../reference/services.md#nrr-version-1) ## Movies - abort in NVIDIA's video path (`NvRmChannelOpen` → `NvOsDrvOpen`). → [The SDK's hardware decoder opens nvdrv](../reference/movies.md#the-sdks-hardware-decoder-opens-nvdrv) - constructing a movie decoder aborts with `FATAL movie: missing SDK symbol _ZNK5movie6Buffer4DataEv`. → [SDK 1 movie buffer getters](../reference/movies.md#sdk-1-movie-buffer-getters) - the game waits forever at a movie (Engage's 94 s opening `S01F.webm`; frames keep presenting, nothing happens). → [`movie::Decoder` taken over as a MediaCodec-style protocol](../reference/movies.md#moviedecoder-taken-over-as-a-mediacodec-style-protocol) - a movie in grey with vertical bands of colour, its luma sharp; or a read far outside guest memory at `main+0x344f74` on the first movie picture (CRI Sofdec2's NV12 → RGB conversion). → [Output format keys (`md_format`)](../reference/movies.md#output-format-keys-md_format) - a movie decodes and its sound plays, but the picture is black: `DM_MOVIE_TRACE=1` shows pictures coming out, the pass dump shows the two planes uploaded and one quad drawn, and the uniform block of the conversion shader (`DM_NVN_CBDUMP`) is all zeros. → [`nv12-colorspace` picks the game's YUV matrix](../reference/movies.md#nv12-colorspace-picks-the-games-yuv-matrix) - a call through a null pointer in the host's `movie::Decoder::Configure` right after `nnMain` starts the logos. → [SDK 4's `movie::Decoder` constructor without a priority](../reference/movies.md#sdk-4s-moviedecoder-constructor-without-a-priority) - a call through a null pointer in the host's `movie::Decoder::Configure` (`pc=0 lr=h_movie_Configure+…`) when the first movie starts; with only the constructor taken over, `[RED] movie: decoder type 1 output 3 mode 1 not supported by the host`. → [SDK 3's `movie::Decoder` constructor takes a type and a format only](../reference/movies.md#sdk-3s-moviedecoder-constructor-takes-a-type-and-a-format-only) - `CRASH sig=11 addr=0 pc=0` with `lr=h_movie_Configure+…`, as the first movie starts. → [The base-object constructors of `movie::Decoder`](../reference/movies.md#the-base-object-constructors-of-moviedecoder) - the first deferred signal crashed in `InternalCriticalSectionImplByHorizon::Enter` (DRAGON QUEST XI S). → [Client events read through the registered pointer](../reference/movies.md#client-events-read-through-the-registered-pointer) - a crash reading address 0 at `main+0xab4e18` right after `[movie] Stop` and `decoder … destroyed`, at the first skip of the intro movie or the first menu change (Mario Strikers: Battle League; `MoviePlayerWorker` in the thread dump). → [Video decoded off the caller's thread](../reference/movies.md#video-decoded-off-the-callers-thread) - the process dies when an activity starts, 2 runs in 5, with no `CRASH` line: the run ends with exit 137 (SIGKILL), and `~/Library/Logs/DiagnosticReports/dmhost-*.ips` has `EXC_BREAKPOINT` in `_os_unfair_lock_corruption_abort` ← `pthread_mutex_destroy` ← `md_free` (the movie decoder's destructor). → [Input indices returned by a flush while a client holds them](../reference/movies.md#input-indices-returned-by-a-flush-while-a-client-holds-them) - when the prologue movie was skipped, 2.25 GB were mapped within seconds, past the application pool, and the game crashed in its allocator (DRAGON QUEST XI S). → [End of stream is the last input until `Flush` or `Stop`](../reference/movies.md#end-of-stream-is-the-last-input-until-flush-or-stop) - decoding the end-of-stream packet gave VideoToolbox −12909 and AudioToolbox −50. → [End-of-stream packets with no data, and deleted decoders](../reference/movies.md#end-of-stream-packets-with-no-data-and-deleted-decoders) - the game never leaves a movie that has played to its end; the last picture stays on screen. → [H.264 drain at the end of a stream goes on with released slots](../reference/movies.md#h264-drain-at-the-end-of-a-stream-goes-on-with-released-slots) - a looping tutorial loses B-frame presentation order after the first loop, without a `Flush` or end-of-stream packet. → [H.264 loops retain presentation order when timestamps restart](../reference/movies.md#h264-loops-retain-presentation-order-when-timestamps-restart) - an anime or story movie ends on a black screen; the pause menu still works and skipping lets the game continue. → [No picture carries the end-of-stream flag](../reference/movies.md#no-picture-carries-the-end-of-stream-flag) - the opening movie never starts, in about half the boots (DRAGON QUEST XI S: a black screen and no sound from boot on). → [Audio decoders keep more outputs than a pre-decoding player fills](../reference/movies.md#audio-decoders-keep-more-outputs-than-a-pre-decoding-player-fills) - a movie stays black after its first picture, the sound never starts, and the game keeps presenting frames. → [Audio output slots for players that hold every output](../reference/movies.md#audio-output-slots-for-players-that-hold-every-output) - a movie shows as a black screen with the loading icon, one picture every few seconds, while its sound decoder keeps up. → [Video output slots: how far the extractor gets ahead](../reference/movies.md#video-output-slots-how-far-the-extractor-gets-ahead) - a crash in the game's heap free (`sead::ExpHeap`) on a movie thread, a second into the first movie, at the same address every boot (`pc=main+0x42f980`, a free-list unlink through a link of 0x3f, `addr=0x47`). → [AAC decoders offer at most 32 outputs](../reference/movies.md#aac-decoders-offer-at-most-32-outputs) - the movie then froze on its first second, its sound decoder full and the game taking no more audio. → [AAC output buffer size is one frame](../reference/movies.md#aac-output-buffer-size-is-one-frame) - `FATAL movie: missing SDK symbol _ZNK5movie6Buffer10GetNvnSyncEv` at the first frame of the native-texture movie (H.264 into the game's RGBA texture, as in Monster Hunter Rise). → [SDK 4's `movie::Buffer` has no sync object](../reference/movies.md#sdk-4s-moviebuffer-has-no-sync-object) - a native-texture movie shows as a strip of small grey copies at the top of the screen. → [Parameter sets in `Configure` made the H.264 decoder without RGBA](../reference/movies.md#parameter-sets-in-configure-made-the-h264-decoder-without-rgba) - looping movie previews flash black at the end of every loop. → [Last picture kept across a flush and at end of stream](../reference/movies.md#last-picture-kept-across-a-flush-and-at-end-of-stream) - a native-texture movie freezes on its 16th picture while the game keeps running; `DM_MOVIE_TRACE=1` shows 16 `AcquireOutputBufferIndex` / `GetOutputBuffer` pairs and no `ReleaseOutputBufferIndex`. → [`GetOutputBuffer` returns the output index in native-texture mode](../reference/movies.md#getoutputbuffer-returns-the-output-index-in-native-texture-mode) - a native-texture movie jumps ahead for one picture and returns: every 17 pictures, each exactly 16 ahead (one cycle of the video output slots), the picture before it never shown. Text burnt into the movie shows the line being typed half a second later for one frame. → [A native-texture movie shows a picture 16 frames ahead, then goes back](../reference/movies.md#a-native-texture-movie-shows-a-picture-16-frames-ahead-then-goes-back) - `[RED] movie: client texture format 0x9a is not RGBA8 / RGBX8 (sRGB included), writing in RGBA byte order`; a native-texture movie plays in the wrong colours, warm lamps blue. → [A BGRA8 client texture gets its movie with red and blue swapped](../reference/movies.md#a-bgra8-client-texture-gets-its-movie-with-red-and-blue-swapped) - the game crashed on a null right after the failed open. → [`movie::Extractor` runs natively](../reference/movies.md#movieextractor-runs-natively) - VP8 WebM movies play black; `movie::Decoder` is created with decoder type 2. → [VP8 uses the same libvpx worker and output paths](../reference/movies.md#vp8-uses-the-same-libvpx-worker-and-output-paths) - a movie with a Vorbis track starts clean, then crackles and stutters. The log has no underrun and no red line, and with `DM_AUDIO_DUMP` the game's mix has exact zeros in whole 512-sample blocks (mostly one or two at a time, 11 to 21 ms). → [Vorbis output lengths at a window change](../reference/movies.md#vorbis-output-lengths-at-a-window-change) - a movie with a Vorbis track plays its first seconds with sound; after the game flushes and restarts it (a seek, a loop, or the app losing and regaining focus) the picture goes on but the sound does not come back, for the rest of the movie. The log shows `[movie] Flush`, `Flush`, `Start`, `Start` and no more `GetOutputBuffer … → PCM` lines. With `DM_AUDIO_DUMP`, the game's mix is real audio up to the flush and exact zeros from then on, so the AudioUnit is not at fault (0 underruns). → [Vorbis sound stops for good after a Flush](../reference/movies.md#vorbis-sound-stops-for-good-after-a-flush) - a Switch 2 game crashes when a movie starts: `nn::codec::video::Initialize` faults in the SDK (Donkey Kong Bananza: `sdk+0x2de99c`, after its first punch, when the guide movie starts), and before that `nv::InitCheck` aborts (`hle_nv.c`). Later, when a second movie starts: `game called nn::diag abort: Result 0` in `nn::os::ClearSystemEvent` or `TryWaitSystemEvent` on the decoder's event. → [`nn::codec` video decoders taken over](../reference/movies.md#nncodec-video-decoders-taken-over) - a movie stays black with the game waiting behind it, the decoder made and no `first picture` line (`Submit…InputBuffer` never called). Or `[RED] nn::codec VP9: Corrupt frame detected`, then `Keyframe / intra-only frame required`, each time about 6 s into a movie or after skipping in one. → [The submission-ready event counted as packets](../reference/movies.md#the-submission-ready-event-counted-as-packets) - a crash in `nn::codec::video::InitializeAv1DecoderByTransferMemory` when a movie starts. → [AV1 movies through SDK 22's decoder](../reference/movies.md#av1-movies-through-sdk-22s-decoder) - an abort in `nn::codec` (the SDK's own decoder client, which opens a service the host does not have) when a movie starts in a game built with SDK 19 for the Switch 2. → [SDK 19's decoder forms](../reference/movies.md#sdk-19s-decoder-forms) ## Audio - abort with Result 0x499 in `audio::GetAudioRendererWorkBufferSize`. → [SDK 8's longer `AudioRendererParameter`](../reference/audio.md#sdk-8s-longer-audiorendererparameter) - the game is silent; only the game's updates render (catch-up frames that nothing plays). The log has `audren: OpenAudioRenderer (no event)` and no `render thread started`. → [A renderer opened without an event](../reference/audio.md#a-renderer-opened-without-an-event) - `[RED] audren: a second renderer (the host drives only one)` with different parameters from the first open; later, `catch-up renders so far` in the thousands (7,625 in 6 minutes), about 10% of the first renderer's frames. → [A game with more than one renderer](../reference/audio.md#a-game-with-more-than-one-renderer) - with two renderers open, one plays single 5 ms frames between silences and its sound effects are missing, while the other has an occasional all-zero 5 ms block; no underrun and no `[RED]` line, and the AudioOut `appended` and `released` counts stay balanced. Cross-correlating the outputs finds one renderer's waveform on the other. → [Two renderers overwriting each other's queued blocks](../reference/audio.md#two-renderers-overwriting-each-others-queued-blocks) - `audren: OpenAudioRenderer` logged twice right after the first open, with the same work buffer and "original device 1 mode 1", and a second render thread (until 2026-11-04 the second log line was `[RED] audren: a second renderer`, which now means more than one renderer). → [The SDK's open with an event calls the open without one (`t_in_open`)](../reference/audio.md#the-sdks-open-with-an-event-calls-the-open-without-one-t_in_open) - the frame loop stops for good as a level loads while audio keeps rendering. The main thread waits in `os::WaitSystemEvent` under `CAudioMemoryPool::Shutdown`, and a sound thread of higher priority waits on the same condition variable. → [The renderer event as the service gives it: a kernel event](../reference/audio.md#the-renderer-event-as-the-service-gives-it-a-kernel-event) - the game exits with 42 on its first rendered audio frame: `Break#1 reason=0` in `os::SignalSystemEvent`, called from the public `ExecuteAudioRendererRendering` on the host's render thread (`render_main`). → [The renderer event belongs to the renderer, not the game](../reference/audio.md#the-renderer-event-belongs-to-the-renderer-not-the-game) - none of its own; command generation races the game's `Update` on SDKs whose lock is not at SDK 16's offset. → [The renderer's update lock (`update_lock`)](../reference/audio.md#the-renderers-update-lock-update_lock) - `FATAL audren: missing SDK symbol _ZN2nn2os12SdkMutexType4LockEv` right after the renderer's render thread starts. → [No `SdkMutexType` in SDK 3](../reference/audio.md#no-sdkmutextype-in-sdk-3) - the sound is choppy: about two of every three 5 ms blocks are silent (a `DM_AUDIO_DUMP`), with no underruns. The log's `catch-up renders so far` grows by one for each rendered frame (2000 of every 2000), and every update logs `no frame rendered before update N`. → [Where the `AudioRenderSystem` sits in `AudioRendererImpl`](../reference/audio.md#where-the-audiorendersystem-sits-in-audiorendererimpl) - `CommandListProcessor::Process` crashes now and then (SIGSEGV under `render_main`, once at 60 s and once at 134 s in the shrine); every `RequestUpdate` renders a catch-up frame. → [The render thread's route through the public `ExecuteAudioRendererRendering` (SDK 20)](../reference/audio.md#the-render-threads-route-through-the-public-executeaudiorendererrendering-sdk-20) - SIGSEGV at address 0x18 in `UpsamplerManager::Allocate` on the render thread. → [A renderer below 48 kHz with no upsampler on the CPU](../reference/audio.md#a-renderer-below-48-khz-with-no-upsampler-on-the-cpu) - the main thread spins at start-up in a resource wait (a `YieldThread` loop, no crash), right after `OpenAudioRenderer`. → [A sound engine's heap too small for its renderer and players](../reference/audio.md#a-sound-engines-heap-too-small-for-its-renderer-and-players) - no sound after boot; `audren: no DeviceSink (ID 0x13) in the command list` and a malformed-command error persist even when later command lists are valid. → [Incomplete startup lists must not select the command layout](../reference/audio.md#incomplete-startup-lists-must-not-select-the-command-layout) - ASan reports a stack-buffer-overflow in `capture` while logging the first full command histogram; a malformed list can also consume sink discovery or return PCM before its invalid tail is checked. → [Malformed later command lists and bounded histogram logging](../reference/audio.md#malformed-later-command-lists-and-bounded-histogram-logging) - the CPU processor drops the final mix. → [The final mix is taken from the DeviceSink's mix buffers](../reference/audio.md#the-final-mix-is-taken-from-the-devicesinks-mix-buffers) - no sound: `[RED] audren: no DeviceSink (ID 0x10) in the command list, 0 commands of 0x148 bytes`. → [SDK 4: DeviceSink is command 0xf of 0x130 bytes](../reference/audio.md#sdk-4-devicesink-is-command-0xf-of-0x130-bytes) - no sound; red `audren: command 1 in the command list is malformed (magic 0 size 0)`. → [SDK 6: the DSP command header layout](../reference/audio.md#sdk-6-the-dsp-command-header-layout) - no sound: `[RED] audren: no DeviceSink (ID 0x13) in the command list, 0 commands of 0x148 bytes` and `[RED] audren: command 2 in the command list is malformed (offset 0x3e, …)`, with `first-frame commands 13, by command ID: 0×2`. → [SDK 5: a startup list that walks in two layouts, and a 0x138-byte DeviceSink](../reference/audio.md#sdk-5-a-startup-list-that-walks-in-two-layouts-and-a-0x138-byte-devicesink) - UBSan reports a misaligned `uint32_t` load in `cmd_ok` while `t_audren_layout` probes SDK 4/6 lists (issue #409). → [Unaligned command headers during layout probing](../reference/audio.md#unaligned-command-headers-during-layout-probing) - no music and no sound effects, only the movies' sound (the log repeats `audren: first-frame commands …` every frame and never prints `DeviceSink inputs`). → [SDK 8: command IDs numbered differently](../reference/audio.md#sdk-8-command-ids-numbered-differently) - `CRASH sig=11 addr=0x20` at `nn::audio::server::AddressInfo::GetReference` (`sdk+0x249874`) on the render thread, under `CommandGenerator::GenerateDataSourceCommand` and `render_once`, minutes into a movie. The `AddressInfo` the crash register points at is all zeros, though the function had just read a non-null memory pool pointer from it. Or `[RED] audren: no update lock read off AudioRenderSystem::Update or UpdateImpl`, on an SDK whose code the scan does not recognize. → [The update lock read off `UpdateImpl`](../reference/audio.md#the-update-lock-read-off-updateimpl) - no sound; red `audren: command 0 in the command list is malformed (first word 0x181901 size 0)`. → [SDK 21 DSP command header without a magic](../reference/audio.md#sdk-21-dsp-command-header-without-a-magic) - RealtimeSanitizer reports stdio locking in `au_render` at its 2,000-callback diagnostic boundary. A busy log writer can block that callback even when its PCM queue is full. → [Periodic diagnostics outside the AudioUnit callback](../reference/audio.md#periodic-diagnostics-outside-the-audiounit-callback) - PCM is consumed correctly and its buffer reaches the released queue, but the guest release event never arrives. The notifier is asleep with `notify_pending=1` and `notify_armed=0`. → [AudioOut release notification can sleep with pending work](../reference/audio.md#audioout-release-notification-can-sleep-with-pending-work) - FMOD waits for buffer release after stopping an AudioOut, hanging the game during a scene transition. → [Stopping an AudioOut releases its pending buffers](../reference/audio.md#stopping-an-audioout-releases-its-pending-buffers) - crackling on iOS only. → [RemoteIO's default I/O buffer duration](../reference/audio.md#remoteios-default-io-buffer-duration) - clicks and dropouts on the Mac, heard as clipping; the log's `audio #N device callbacks` lines show hundreds of underruns per 2000 callbacks. Closing an output can also log `[RED] audio device buffer: ... (status 560947818)` (`!obj`). → [The Mac's default I/O buffer](../reference/audio.md#the-macs-default-io-buffer) - a game is silent on an iPhone whose ring / silent switch is set to silent, though the volume is up; a game or video app plays through the switch. → [The ring / silent switch muted the game on iOS](../reference/audio.md#the-ring--silent-switch-muted-the-game-on-ios) - sound stays silent after Siri, an alarm, a call or another app's audio; a game whose audio thread waits for its buffers back (Wwise's poll-only output, FMOD) then waits forever. → [Interruptions that stop RemoteIO callbacks](../reference/audio.md#interruptions-that-stop-remoteio-callbacks) - a game stops advancing while the Mac's selected output refuses to play. A process sample shows `AudioOutputUnitStart` waiting in the HAL, with the game's audio renderer waiting for a released PCM buffer. → [A blocked audio device start freezes the game](../reference/audio.md#a-blocked-audio-device-start-freezes-the-game) - TSan reports `au_create` writing `a->au` while `au_watchdog` reads it under `g_aos_lock` when a second real output opens (issue #410). → [AudioUnit construction before output publication](../reference/audio.md#audiounit-construction-before-output-publication) - combined numbers mislead: one fully fed output plus one fed by nobody look like "every other callback underruns, 2.0 blocks queued". → [Several outputs at once (`audio #N`)](../reference/audio.md#several-outputs-at-once-audio-n) - a null read at `sdk+0x1f2314` as the first movie starts (the title menu's background, right after the first press), in `nn::audio::SetAudioOutVolume`, called from `main+0x1c4fbc`. → [AudioOut volume kept per output](../reference/audio.md#audioout-volume-kept-per-output) - a null read in `audio::GetAudioOutBufferCount` on Wwise's sink wakeup thread (`sdk+0x1e7ed0`, from `main+0x30faae8`). → [AudioOut buffer count from the host queue](../reference/audio.md#audioout-buffer-count-from-the-host-queue) - an abort in `sm::Initialize` under `audio::GetAudioDeviceOutputVolume` (the game thread, `main+0xee8edc`). → [Audio device output volume and names](../reference/audio.md#audio-device-output-volume-and-names) - an `nn::diag` abort with Result 0xe15 on an audio thread at start, in `audio::CreateUserClientSessionByHipc` under `audio::AcquireAudioOutputDeviceNotification`, after the line `sf: the game connects to service aud:u itself`. → [The output device notification under its SDK 21 and 22 name](../reference/audio.md#the-output-device-notification-under-its-sdk-21-and-22-name) - SDL3's audio driver lists the input devices (AudioIn) when its audio starts. `[RED] sf: the game connects to service audren:u itself`, then `nn::diag abort: Result 0xe15` under `audio::AcquireAudioDeviceNotificationForInput` (`sdk+0x5633c`). → [No audio input devices](../reference/audio.md#no-audio-input-devices) - `[RED] sf: the game connects to service auddmg:u itself, which the host does not serve`, then `game called nn::diag abort: Result 0xa99` at `sdk+0x1f61ac` under `audio::ListVirtualInputDevices`. → [No virtual audio input devices (SDK 22)](../reference/audio.md#no-virtual-audio-input-devices-sdk-22) - `game called nn::diag abort: Result 0xe15, call site sdk+0x1f8704`, i.e. inside `nn::audio::CreateAudioOutManagerByHipc+0xb4`, before any audio device opened. → [`OpenAudioOut` without a release event (SDK 22)](../reference/audio.md#openaudioout-without-a-release-event-sdk-22) - `[RED] sf: the game connects to service auddmg:u itself, which the host does not serve`, then `game called nn::diag abort: Result 0xa99` under `nn::audio::GetDefaultVirtualOutputDevice` (`sdk+0x221520`, `audio::detail::GetVirtualOutputDeviceProperties`). → [SDK 21's OutputStream on a virtual output device](../reference/audio.md#sdk-21s-outputstream-on-a-virtual-output-device) - an abort in `sm::Initialize` under the hardware Opus decoder's C interface; for the multi-stream one, under `nn::codec::GetHardwareOpusMultiStreamDecoderWorkBufferSize(int, int, int, int, int)` (at `nnMain`, CRI's Opus streams). An abort in `sf::hipc::InitializeHipcServiceResolution` under `codec::GetHardwareOpusDecoderWorkBufferSize(int, int)` (`main+0x31f8e8`, early in `nnMain`). A game that builds `HardwareOpusMultiStreamDecoder` with the imported constructor and then calls it through its vtable. → [Hardware Opus decoders built on the SDK's software decoders](../reference/audio.md#hardware-opus-decoders-built-on-the-sdks-software-decoders) - `game called nn::diag abort: Result 0xe15` under `nn::codec::GetHardwareOpusDecoderManagerWorkBufferSize` (`sdk+0x323180`), the game's sound setup. → [SDK 21's hardware Opus decoder manager](../reference/audio.md#sdk-21s-hardware-opus-decoder-manager) - `CRASH sig=11 addr=0` in `h_codec_HwOpusFini`, the first time the game finalizes a decoder. → [One key for the two forms of the Opus decoder](../reference/audio.md#one-key-for-the-two-forms-of-the-opus-decoder) - the light limiter crashed on a null state pointer (`ApplyLightLimiterEffect`, `sdk+0x228494`). → [At least one rendered frame between two updates](../reference/audio.md#at-least-one-rendered-frame-between-two-updates) - the sound runs about 50 times faster than the output; the loop runs 11,000 updates a second on one core. → [A sound driver that never waits on the renderer event](../reference/audio.md#a-sound-driver-that-never-waits-on-the-renderer-event) ## Frame rate - clang reports division by zero in `fstep_tick` (`hle_nvn.c`). → [Frame cap checked and used from the same sample](../reference/frame-rate.md#frame-cap-checked-and-used-from-the-same-sample) - a 30 fps game to run at 60; after the floor was lowered, slow motion on a GPU-bound device (GitHub issue #9). → [sead's dynamic present interval, `ksys::VFR` and the host's frame step](../reference/frame-rate.md#seads-dynamic-present-interval-ksysvfr-and-the-hosts-frame-step) - `scripts/regress.py` reports a hang (`no frame after … s`, a state dump with every game thread waiting) in some runs of Tears of the Kingdom, baseline and candidate alike; the log's last focus line before it is `oe focus state → 2`, with no `→ 1` after it. → [A regress run stops when another app takes the key window](../reference/frame-rate.md#a-regress-run-stops-when-another-app-takes-the-key-window) - otherwise stationary gameplay benchmarks show roughly 125–135 ms frame spikes at their verification screenshots; adaptive-cap results vary between runs. → [Benchmark captures perturb the measured frame pacing](../reference/frame-rate.md#benchmark-captures-perturb-the-measured-frame-pacing) - on an iPhone, a game with the frame step at 60 fps drops a frame in most windows after a few minutes, and its GPU time per frame roughly doubles to triples (17-26 ms for the same scenes). → [A thermally serious iPhone holds 30 fps](../reference/frame-rate.md#a-thermally-serious-iphone-holds-30-fps) - in a game the host steps at 60 fps (`FRAME_STEP`), a prerendered movie plays at twice its speed, its sound falls behind, and the frame counter shows 60 during it. The log has `[movie]` lines with pictures 33 ms apart (`time 0 / 33000 / 67000 µs`) and no `frame step cap 60 → 30` at the movie. → [Movies hold 30 fps under the frame step](../reference/frame-rate.md#movies-hold-30-fps-under-the-frame-step) - after a 30 fps cap ends (a prerendered movie, the thermal cap), a GPU-bound game stays at 30 fps in a scene that held 60 before the cap; the log shows `frame step cap 30 → 60 fps` and a few frames later `frame step: hold 1 → 2 vsyncs at present … (3 late frames; …)`, with no probe after it. → [The frame step after a 30 fps cap ends](../reference/frame-rate.md#the-frame-step-after-a-30-fps-cap-ends) - on a Mac, a GPU-bound game at 60 fps falls to 30 or 20 fps when the scene gets heavier and stays there until a menu or a lighter scene, while the GPU clock sits at its floor (338–400 MHz on an M5 Pro) and the GPU is powered 60–75% of the time; the log shows probes back to hold 1 that fail after about 33 frames (`frame step: hold 2 → 1 vsyncs … (probe, GPU 1.67× its time at hold 1)` then `the probe failed`), and the host's profiler (`@gpu_mhz`) shows the clock rising during each probe and falling back after it. → [A probe's grace lasts while its frames keep getting cheaper](../reference/frame-rate.md#a-probes-grace-lasts-while-its-frames-keep-getting-cheaper) - a game whose profile has a frame step (`FRAME_STEP` in its `patches.py`) runs at double speed when packed from another update; the log has no `frame step in whole vsyncs` line, and the frame counter shows 60. → [A derived profile drops the frame step its build lacks](../reference/frame-rate.md#a-derived-profile-drops-the-frame-step-its-build-lacks) - a fixed-step game runs at double speed (or slow motion at 30) after `DM_FPS_TARGET` is set, in `Documents/env.txt` or the launcher, on a build its profile's frame step stubs and limiter rows do not know. → [A present cap applies only with a frame step or an engine limit the host writes](../reference/frame-rate.md#a-present-cap-applies-only-with-a-frame-step-or-an-engine-limit-the-host-writes) - selecting 30 FPS changes the engine's interval field, but the screen and frame loop still run near 60 FPS. → [Engine-native frame caps also govern presentation](../reference/frame-rate.md#engine-native-frame-caps-also-govern-presentation) - the game always renders at full resolution, or turning off dynamic resolution still allows the native controller to lower it. → [Resolution policy is independent of the frame-rate cap](../reference/frame-rate.md#resolution-policy-is-independent-of-the-frame-rate-cap) - slow motion when the GPU is the bottleneck: a game's interval controller that times the GPU never steps up (GitHub issue #9). → [GPU timestamps per submission segment](../reference/frame-rate.md#gpu-timestamps-per-submission-segment) - GPU time reads 32 times too small when a game converts raw NVN counter timestamps itself. → [Raw NVN timestamp units](../reference/frame-rate.md#raw-nvn-timestamp-units) - a Switch 2 game holds 20 or 30 fps on the Mac although its frame work fits in one vsync: its frame-rate controller raises the present interval (`the game sets present interval 1 → 3` in the log) and never steps back down. → [The Switch 2's system tick is 31.25 MHz](../reference/frame-rate.md#the-switch-2s-system-tick-is-3125-mhz) - menus reach 60 fps with `present_interval display`, but entering gameplay returns to 30 fps despite spare GPU time. → [Unity's integer target frame rate](../reference/frame-rate.md#unitys-integer-target-frame-rate) - the game presents at interval 1, yet every frame takes exactly 33.3 ms of "frame work"; after only the limiter was raised, everything ran twice as fast on the iPhone. → [A render-thread limiter with a constant and a fixed time step](../reference/frame-rate.md#a-render-thread-limiter-with-a-constant-and-a-fixed-time-step) - 55 fps with every frame 18.2 ms, the main thread asleep most of the time; every 11th frame stays on screen two vsyncs. → [A frame-end wait polled in 2 ms sleeps](../reference/frame-rate.md#a-frame-end-wait-polled-in-2-ms-sleeps) - a Switch 2 game runs its title and menus at 60 fps and its gameplay at 30, asking for present interval 2, with the GPU mostly idle. → [A target frame rate the game steps by](../reference/frame-rate.md#a-target-frame-rate-the-game-steps-by) - with a game's target frame rate written to 120 and a 120 Hz display link, the game holds 120 where frames fit, but a scene whose frames take 14 ms runs in slow motion at 72 fps, and on a 60 Hz screen the whole game runs at half speed. → [120 fps follows the frame step](../reference/frame-rate.md#120-fps-follows-the-frame-step) - an Unreal Engine game holds 30 fps with spare CPU and GPU time and asks for present interval 2; `present_interval display` alone does not help, as the engine's game thread sleeps out its own frame limit. → [Unreal's frame limit and present interval, found by name](../reference/frame-rate.md#unreals-frame-limit-and-present-interval-found-by-name) - a Frostbite game holds 30 fps with spare CPU and GPU time. Raising only the frame limit and the present interval gives 60 frames a second with the game at half speed (the match clock at 3.6 game seconds a second instead of 7.5). → [Frostbite's simulation rate, found by name](../reference/frame-rate.md#frostbites-simulation-rate-found-by-name) - the app is active and the game keeps running, but the picture freezes while display-link callbacks stop; the log repeatedly drops queued frames. → [Present thread rescues a silent display link](../reference/frame-rate.md#present-thread-rescues-a-silent-display-link) - `[longframe]` lines of 40–180 ms with no new pipelines, a short submit and normal GPU time, which read like CPU hitches in the game: single frames of 60–100 ms, or bursts of 5–12 frames, one of 140–180 ms and the rest about 40 ms. → [Long frames a test run makes itself](../reference/frame-rate.md#long-frames-a-test-run-makes-itself) - with the display link driving presents, a presented frame comes out black when three presents are on the GPU at once, or two after a dropped frame; on an M6 the same reuse also logs `[RED] display command buffer error` with `kIOGPUCommandBufferCallbackErrorPageFault`. → [A present command allocator is reused only after its own present completes](../reference/frame-rate.md#a-present-command-allocator-is-reused-only-after-its-own-present-completes) - "sometimes the speed increases when jumping" (Mario 1.2.1 on the iPhone): in `display` mode interval-2 frames were shown for 16.7 ms and the game visibly jumped ahead. "When pressing B, Link's move pace is speeding up" (Breath of the Wild on the iPhone); `old frames dropped by merging`. → [Frames of a dynamic present interval held on screen and at the acquire](../reference/frame-rate.md#frames-of-a-dynamic-present-interval-held-on-screen-and-at-the-acquire) - Donkey Kong Bananza ran its heavy areas at 15 fps where its GPU took about 46 ms a frame: the frames came every 66.7 ms, and the presentation thread spent 85% of its time in `nvnWindowAcquireTexture` waiting for display-link ticks. → [Odd present intervals on the 30 Hz display link](../reference/frame-rate.md#odd-present-intervals-on-the-30-hz-display-link) - with `present_interval display`, `DM_PRESENT_HZ=120` and `DM_PRESENT_LINK=2` (a 120 Hz display link) a game stays at 60 fps although its frame takes 8 ms; the display link logs about two ticks per present. With a requested 90 Hz, truncating the tick conversion instead allows 120 fps (reproduced through the real acquire with simulated link ticks). → [One frame per tick of a 120 Hz display link](../reference/frame-rate.md#one-frame-per-tick-of-a-120-hz-display-link) - frames miss the screen while the GPU stays at its lowest clock (444 MHz on an M2 Max); more work (a higher render scale) only makes the frames slower. → [Present snapshots: the game's swapchain texture free at once](../reference/frame-rate.md#present-snapshots-the-games-swapchain-texture-free-at-once) - none seen in a game. When the presented texture changes size or format while snapshots are on, a display command buffer still queued could sample the ring slot's old texture outside the residency set, which faults the queue (`kIOGPUCommandBufferCallbackErrorPageFault`, then every later command buffer ignored), as in A present snapshot's copy needs the same residency commit. → [A replaced snapshot ring texture stays resident until the slot's next use](../reference/frame-rate.md#a-replaced-snapshot-ring-texture-stays-resident-until-the-slots-next-use) - a steady game whose frame-rate counter wanders between 50 and 60 on the iPhone only; the `display link up to tick` lines show about as many empty ticks as frames dropped by merging: frames arrive two in one tick and none in the next. → [Vulkan acquire and vsync event follow the display link](../reference/frame-rate.md#vulkan-acquire-and-vsync-event-follow-the-display-link) - a `regress.py` run of an NVN game stays at 20 fps from the start (`frame N not reached`, a NEW-FAIL) in some runs only: `frame step: hold 1 → 2` and `2 → 3 vsyncs` in the first 15 presents, then `display link recovered: stalled 1017 ms` about once a second to the end, and no trial back to a shorter hold. → [A game window another process starts opens behind other windows](../reference/frame-rate.md#a-game-window-another-process-starts-opens-behind-other-windows) - asked for 60 Hz, the system fires the display link on every third refresh of a 165 Hz screen, 55 Hz, so games paced by it ran at 55 fps (27.5 at 30). → [Virtual 60 Hz ticks on screens that are not a multiple of 60](../reference/frame-rate.md#virtual-60-hz-ticks-on-screens-that-are-not-a-multiple-of-60) - virtual ticks keep the average, but a frame still stays up two or three refreshes in turn (13.9 / 20.8 ms at 144 Hz), and Apple's HUD showed the frame interval jumping between them. → [Fullscreen switches the screen to a rate the frame rate divides](../reference/frame-rate.md#fullscreen-switches-the-screen-to-a-rate-the-frame-rate-divides) - a Mac game in fullscreen holds 60 fps for 45 s to 3 minutes, then the same work takes about twice the GPU time (Tears of the Kingdom 10.5 → 19.7 ms) and the frame step falls to 30 fps. `powermetrics` shows the GPU at its lowest clock (338 MHz on an M4 Pro) while it is 72–98% busy, with thermal pressure nominal. Probes back to 60 fail, because the clock does not rise within a probe. `gamepolicyd` logs `Game mode enabled` and `Set DPS to 2`. → [macOS Game Mode holds the GPU at its lowest clock](../reference/frame-rate.md#macos-game-mode-holds-the-gpu-at-its-lowest-clock) - a Mac game started with `DM_FULLSCREEN=1` from an app that is itself in fullscreen (the launcher's console mode) came up as a window. → [A game opened from a fullscreen app stays a window](../reference/frame-rate.md#a-game-opened-from-a-fullscreen-app-stays-a-window) - the mouse pointer stayed on the picture of a Mac game, in a window and in fullscreen, until it was moved to a screen corner. → [The pointer stays on a Mac game](../reference/frame-rate.md#the-pointer-stays-on-a-mac-game) - on a ProMotion built-in screen, only in fullscreen, the frame step went 1 → 2 → 3 vsyncs on frames costing 0.1–0.6 vsyncs (`3 late frames; cost 0.32 vsyncs`) and the game presented 15 frames a second; a window, or the screen set to a fixed 60 Hz, did not do it. The `DM_NVN_TSV` rows show presents shown one 120 Hz refresh late (`@pres_at_ms` − `@link_target_ms` = 8.3 ms) with a skipped tick after each (`@link_gap_ms` 33 ms), and `@link_lead_ms` about 16 ms against about 50 ms in a window. → [Frame latency 2 for the display link in fullscreen](../reference/frame-rate.md#frame-latency-2-for-the-display-link-in-fullscreen) - on a MacBook Air M2's fixed 60 Hz built-in display, the reporter measured about 50 ms from the game's present call to on-screen presentation with the display link, at both requested frame latencies 1 and 2, versus 29 ms with `DM_PRESENT_LINK=0`. After loading, all three runs held 60 fps with 0.3% of on-screen intervals outside 16.7 ± 2 ms and no frame-step changes. → [Fixed-rate display-link delay remains at latency 1](../reference/frame-rate.md#fixed-rate-display-link-delay-remains-at-latency-1) - autorelease work takes a measurable share of replay time, with temporary arena-buffer ownership traffic a few times per draw. → [Arena buffer ownership on allocation](../reference/frame-rate.md#arena-buffer-ownership-on-allocation) - a game runs at about 10 fps with little GPU work: the submit thread waits for a command allocator (`mtl_sub_begin` → `mtl_wait_at`), the GPU sits idle between encoders for hundreds of ms (`DM_NVN_GPUPROF`), the Metal 4 `SubmissionQueue` thread spends nearly all its time in `iokit_user_client_trap` (almost all system time), and the `memory up to frame` line shows a residency set of 10,000 objects or more. → [Dedicated c1 constants as slices of a bank](../reference/frame-rate.md#dedicated-c1-constants-as-slices-of-a-bank) - the submit thread waits on the texture / sampler registry lock while a lower-priority registration thread is preempted holding it. → [Registry lock priority inheritance](../reference/frame-rate.md#registry-lock-priority-inheritance) - in a replay profile, `_platform_memcmp` is most of the time spent in serial lookups (`tex_mtl` through `g_by_serial`). → [Hash-table lookups of 8-byte keys](../reference/frame-rate.md#hash-table-lookups-of-8-byte-keys) - the GPU sits idle each frame while the host translates the submission (a game that does not submit frame N+1 until frame N's GPU work is done). → [Submissions handed to the GPU in segments](../reference/frame-rate.md#submissions-handed-to-the-gpu-in-segments) - one frame in 50 or so takes 25-40 ms in a scene where the frame normally fits, with the host on time: `@sync_ms` is high, `@sub_wall_ms` is not, and the frame before has a GPU span (`@gpu_end_ms - @gpu_beg_ms`) of 25-40 ms while the summed `@gpu_ms` has not moved. Runs fall into two states, and on the same code one can have 5 long frames and the next 60. A bad run also shows 186 % CPU against 133 %, and the previous frame still running when the next starts (p50 4 ms, p90 10 ms, against about 0 in a good run). → [The GPU idles with the next command buffer already committed](../reference/frame-rate.md#the-gpu-idles-with-the-next-command-buffer-already-committed) - the submit thread's CPU samples half in `__CFBasicHashFindBucket_Linear` under `CFSetContainsValue` (from `tex_mtl_` and `tex_by_id`), a few hundred thousand to over a million instructions of translation per draw, the submission growing with the game's CPU-written textures. → [The set of CPU-written textures hashed by serial](../reference/frame-rate.md#the-set-of-cpu-written-textures-hashed-by-serial) - several milliseconds of CPU translation and geometry preparation separate one frame's GPU end from the next frame's GPU start, even though the frame already contains complete geometry passes. → [Geometry boundaries submit prepared work early](../reference/frame-rate.md#geometry-boundaries-submit-prepared-work-early) - CPU submission spikes during texture updates, with the residency log showing tens of MB of new private staging allocations per frame. → [Reusing upload staging after a slot completes](../reference/frame-rate.md#reusing-upload-staging-after-a-slot-completes) - periodically rewritten textures cause CPU submission spikes even with no new staging allocations or shader compilation; a small cube-array image produces thousands of deswizzle dispatches and buffer-to-texture copies. → [Small array texture uploads without per-face staging](../reference/frame-rate.md#small-array-texture-uploads-without-per-face-staging) - the submit thread's CPU samples dominated by `mtl_addr` / `mtl_gpu_addr` (vertex buffers in `draw`, uniform buffers in `encode_args`). → [Address to memory pool lookups by binary search](../reference/frame-rate.md#address-to-memory-pool-lookups-by-binary-search) - gameplay has low CPU clocks, large render submission wall time compared with thread CPU time, and default QoS (`0x15`) on the main guest thread while workers report user-interactive (`0x21`). → [Main guest thread keeps inherited default QoS](../reference/frame-rate.md#main-guest-thread-keeps-inherited-default-qos) - stalls of 30–60 ms about once a second, at 30 fps and at 60 (99th percentile 63–127 ms); the main thread waits 20–34 ms for the render thread once a second. → [Time-constraint computation declared below the thread's peaks](../reference/frame-rate.md#time-constraint-computation-declared-below-the-threads-peaks) - a movie or full-screen compute pass far slower than the same work should be, nearly all of it GPU time: `GPU p50` near the frame time with `submit+present` under 1 ms. `[RED] raw global memory: a write log ran out of slots` on older chains. With `DM_NVN_GPUPROF` a relaxed timestamp can put the time before the compute encoder's reported start, so the encoder itself looks short and the gap before it is what is long. → [A shader that writes a whole frame through raw global memory](../reference/frame-rate.md#a-shader-that-writes-a-whole-frame-through-raw-global-memory) - a game with dynamic resolution stays at its full size while the GPU runs far over budget: `GPU p50` above the frame time target, frame times locked to 2 vsyncs, and the same pass sizes frame after frame in `DM_NVN_GPUPROF`. → [Dynamic resolution that never moves, and draw passes that wait for each other](../reference/frame-rate.md#dynamic-resolution-that-never-moves-and-draw-passes-that-wait-for-each-other) - many passes a frame on the same attachments, with the residency set line showing `passes ended to land them for a read` in the thousands and `refused …: earlier submission running` matching it. Ocarina of Time: 10,463 per 300 frames, each ending the pass over a uniform block no GPU write touched. → [A full table of running GPU writes ends passes for nothing](../reference/frame-rate.md#a-full-table-of-running-gpu-writes-ends-passes-for-nothing) - a game that reads textures through a pool (Shaders report which textures they read through a pool) renders far below its maximum dynamic resolution: Ocarina of Time's main pass at 763x429 with the GPU at 17 ms a frame. → [A host's own store in a fragment shader moves its depth test](../reference/frame-rate.md#a-hosts-own-store-in-a-fragment-shader-moves-its-depth-test) ## NVN objects - heap corruption; a stack smash where a function returned to `0x100000000`; a crash in SHA-256 on the code address 0x16300. → [Host records must fit the game's SDK object sizes](../reference/nvn-objects.md#host-records-must-fit-the-games-sdk-object-sizes) - out-of-range vertices, NaN, a black band and flicker; seen on the iPhone, while Mac runs of the same scene looked clean. → [Inlined SDK code writes into `NVNcommandBuffer` +0x10](../reference/nvn-objects.md#inlined-sdk-code-writes-into-nvncommandbuffer-0x10) - a running game with sound draws a black screen; every uniform buffer returns the same initialized address, with its allocation offset reported as its size. → [Guest ring allocators write `NVNbuffer` offset and size directly](../reference/nvn-objects.md#guest-ring-allocators-write-nvnbuffer-offset-and-size-directly) - sprites broke apart in some runs only, depending on the allocation order; buffers overlapped. → [Sizes the hardware never reports as 0 (ZCull save area)](../reference/nvn-objects.md#sizes-the-hardware-never-reports-as-0-zcull-save-area) - a null write as soon as the main thread starts recording a command buffer (13 Sentinels: a constructor at `main+0x2fa9a0` runs on `this = 0` when the prologue enters its first battle). → [Heaps cut from a pool at alignment relative to its GPU address](../reference/nvn-objects.md#heaps-cut-from-a-pool-at-alignment-relative-to-its-gpu-address) - `[RED] memory pool … created at retry N`. → [`newBufferWithBytesNoCopy` retried under memory pressure](../reference/nvn-objects.md#newbufferwithbytesnocopy-retried-under-memory-pressure) - a buffer is created with a null pool right after a scene change. → [Virtual memory pools mapped onto one physical pool](../reference/nvn-objects.md#virtual-memory-pools-mapped-onto-one-physical-pool) - `[RED] MapVirtual: non-contiguous mapping (true sparse) not implemented`. → [Sparse virtual pools built from separate physical pools](../reference/nvn-objects.md#sparse-virtual-pools-built-from-separate-physical-pools) - `[RED] MapVirtual: non-contiguous mapping (true sparse) not implemented`, on small virtual pools; streamed textures black or missing (OCTOPATH TRAVELER's village ground and plants). → [Virtual pools of one texture each, mapped before and after the texture](../reference/nvn-objects.md#virtual-pools-of-one-texture-each-mapped-before-and-after-the-texture) - `[RED] NVN unimplemented function called: nvnTextureBuilderGetSparseTileLayout`, then an out-of-memory abort in Unreal's allocator (`Failed to allocate 1879113728 bytes from Standard Allocator`, on `DM_DBG=1`). → [The sparse tile layout of a texture](../reference/nvn-objects.md#the-sparse-tile-layout-of-a-texture) - `CRASH sig=10` in `memmove` from `pkg_upload` → `nvn_deswizzle`, at an address 32 GB into a sparse virtual pool; textures with unaliased tails came out magenta. → [Textures read through a 4 KB page table of a sparse pool](../reference/nvn-objects.md#textures-read-through-a-4-kb-page-table-of-a-sparse-pool) - `kIOGPUCommandBufferCallbackErrorOutOfMemory` on every command buffer from the first frames, no frame presented, "GPU allocated" near the Mac's memory; `large texture … in a sparse virtual pool` lines name textures of gigabytes. → [Large sparse textures as Metal placement sparse textures](../reference/nvn-objects.md#large-sparse-textures-as-metal-placement-sparse-textures) - the placement heaps (`sparse tiles: placement heap N`) keep growing through a session, to several times the memory the game maps behind its sparse textures. On a 16 GB M1 Pro, Mario Kart World's race reached 11 heaps (2.75 GB) within three minutes, wired memory 8.7 GB, and the system swapped: frames went from 25 to 50 ms. A GPU write through one place of a page is also not seen at another. → [Physical pages mapped at several places of a placement sparse texture](../reference/nvn-objects.md#physical-pages-mapped-at-several-places-of-a-placement-sparse-texture) - frames of 100 ms and more every few frames on a Mac short of memory, with no failing command buffer; a Metal System Trace shows the driver wiring and unwiring all the time (3.2 s of a 6 s trace on the game below), and the `restop` line of `DM_CTL` shows gigabytes of shared buffers. → [Large pools wrapped in chunks](../reference/nvn-objects.md#large-pools-wrapped-in-chunks) - GPU memory grows with every scene change (Engage's idle title demo reached 5.4 GB of GPU memory and 3.6 GB resident in 850 s). → [Finalized pools kept alive by residency and the sharing table](../reference/nvn-objects.md#finalized-pools-kept-alive-by-residency-and-the-sharing-table) - the memory line's `freed but alive` count only grows, while no host table holds those buffers; "GPU allocated" is far above resident memory (Ghost Trick: Phantom Detective, 125 to 146 buffers and 6.6 to 8.7 GB of GPU allocations against 2.2 GB resident). → [Finalized pool buffers kept by a guest thread's autorelease pool](../reference/nvn-objects.md#finalized-pool-buffers-kept-by-a-guest-threads-autorelease-pool) - GPU and resident memory keep growing during texture streaming while pool, residency and serial-object counts stay nearly flat, with no freed pool buffers alive. → [Finalized textures kept by registered descriptor views](../reference/nvn-objects.md#finalized-textures-kept-by-registered-descriptor-views) - the submit thread spends milliseconds a frame in `pool_gpu` → `tex_by_id` → `tex_mtl` / `tex_get` (a `sample` of the process), and the `[nvn-mtl] pool for handles traced to no slot … built in X ms` line shows a rebuild of the texture pool table every frame at about 2 ms. Fire Emblem Fortune's Weave's battle map: 1.9 ms a build, three builds a frame, about 14 % of the main thread. → [Texture ID views revalidated only for the serials that changed](../reference/nvn-objects.md#texture-id-views-revalidated-only-for-the-serials-that-changed) - the serial table grows by about 10 entries a frame (276,000 after 25,000 frames). → [Dead texture serials kept in a ghost table](../reference/nvn-objects.md#dead-texture-serials-kept-in-a-ghost-table) - `nvn_replay` aborts on a game's capture with `-[NvProg width]: unrecognized selector` (from `rt_dims`) or `-[NvProg mipmapLevelCount]`: a render target resolves to a program. → [A replay's own objects take serials above a capture's](../reference/nvn-objects.md#a-replays-own-objects-take-serials-above-a-captures) - `DM_NVN_CAPTURE` reports `a record names … (0 bytes), outside every pool … texture registry entry …` for some texture IDs, with addresses that look like data; one capture stopped with `a sparse virtual pool (step 1 does not capture page tables): the capture is incomplete`, another with `straddles a region`. → [A captured texture ID whose memory pool was finalized](../reference/nvn-objects.md#a-captured-texture-id-whose-memory-pool-was-finalized) - `CRASH sig=11 … pc=nvn_sparse_protect+0x40`, an address that looks like data, `x8` 8 below it, after a long session; the backtrace `tex_by_id` ← `tex_mtl` ← `pkg_upload`. The pool need not be sparse. → [A texture read after its memory pool object was freed](../reference/nvn-objects.md#a-texture-read-after-its-memory-pool-object-was-freed) - `regress.py capture` stops with `frame N was not captured within … s` although the game reached the frame before it; a capture takes 5 to 20 minutes where an earlier one of the same frame took 2 to 3, and a sample of the host shows the submitting thread in `lzfseEncodeBase` under `nvn_cap_submit`. → [A frame capture runs under the standard thread policy](../reference/nvn-objects.md#a-frame-capture-runs-under-the-standard-thread-policy) - `nvn_replay` stops with `program #N (a key …) stage S: the translated shader's bindings or inputs differ from the ones the records were captured against`, and `regress.py replay` reports every game's capture as one the candidate cannot replay, while the shaders' reflection (`<key>_b.json`) is the same in both chains apart from the chain field. → [A capture refused after a change to the reflection structs](../reference/nvn-objects.md#a-capture-refused-after-a-change-to-the-reflection-structs) - `[RED] NVN unimplemented function called: nvnCommandBufferGetControlMemoryFree` (or `…GetControlMemorySize`) once, after the game gives a command buffer control memory. → [Control memory capacity queries](../reference/nvn-objects.md#control-memory-capacity-queries) - `FATAL NVN command memory: the game's pool is empty…`. → [Host-lent command memory segments](../reference/nvn-objects.md#host-lent-command-memory-segments) - frames stop after about 15 s; a game thread spins in its command-memory callback (a ring allocator at `main+0x9cc120` waiting for fences that have all signalled). → [What `GetCommandMemoryUsed` counts](../reference/nvn-objects.md#what-getcommandmemoryused-counts) - `CRASH sig=10` in `mtl_exec` after minutes of play, the fault address equal to `x19` and shaped like `0x1000000003`. → [Prerecorded lists in slots of their measured size](../reference/nvn-objects.md#prerecorded-lists-in-slots-of-their-measured-size) - the title showed one stretched 64×64 icon over the 3D scene, a new game a white screen; post-process passes with stale texture handles; `[RED] bind record … overwritten after recording`. → [Recorded commands patched in place by the game (`OP_BIND_TEX1`)](../reference/nvn-objects.md#recorded-commands-patched-in-place-by-the-game-op_bind_tex1) - choosing X-2 after the collection launcher crashes in `keys_hash`, reading control address `0x8000000000`; the program object now contains command-buffer data. → [Bindings belong to each queue](../reference/nvn-objects.md#bindings-belong-to-each-queue) - about 23 s after launch, when the title screen hands over to the opening demo, a crash in `keys_hash` (`prog_key` ← `prog_get` ← `bind_stages` ← `prog_resolve` ← `mtl_queue_activate`), reading a control address made of float data; the program object now holds other data. → [Finalized programs leave every queue's bindings](../reference/nvn-objects.md#finalized-programs-leave-every-queues-bindings) - `nvnCommandBufferFenceSync` unimplemented, every `SyncWait` timed out at once. → [Fence syncs recorded in command buffers](../reference/nvn-objects.md#fence-syncs-recorded-in-command-buffers) - `FATAL submit re-entered` in the first frames. → [Submissions from two queues on two threads](../reference/nvn-objects.md#submissions-from-two-queues-on-two-threads) - going to the background (iOS `sceneDidEnterBackground`, minimizing the Mac window) while the "Preparing shaders" or "Preparing pipelines" screen is up blocks the main thread until the step ends: minutes on a first start, long enough for iOS to end the app. The log's `[nvn] graphics suspended` line comes only after the `pipeline prepare:` line. → [Going to the background during the prepare step](../reference/nvn-objects.md#going-to-the-background-during-the-prepare-step) - frames stop, no crash, the main thread sits in `nvnSyncWait(sync, -1)`, and the watchdog's wait-state line shows the main fence one short (`main fence submitted N / completed N-1`). → [A GPU command buffer that never completes](../reference/nvn-objects.md#a-gpu-command-buffer-that-never-completes) - the frame's blocking SyncWait on its newest fence wakes about 0.26–0.29 ms after the GPU end (M2 Max; the wait ledger, `DM_NVN_WAITS=1`), on the critical path of every frame. → [The game's SyncWait wakes on the GPU's own signal of its fence](../reference/nvn-objects.md#the-games-syncwait-wakes-on-the-gpus-own-signal-of-its-fence) - loading screens many times slower on the iPhone than on the Mac (Three Houses' first loading screen 78 s on the iPhone, 5 s on the Mac). → [`nvnQueueFinish` waits for the GPU, not the display](../reference/nvn-objects.md#nvnqueuefinish-waits-for-the-gpu-not-the-display) - CPU texture uploads spend time recalculating block-linear addresses and calling variable-length `memcpy` for every 16-byte segment. → [CPU deswizzle copies use slice and row offsets](../reference/nvn-objects.md#cpu-deswizzle-copies-use-slice-and-row-offsets) - a Switch 2 game's textures from its files keep their shapes but break up along every edge: misplaced 4×4 blocks (16-byte pieces) in a regular weave, invisible in flat areas. Normal maps make lit surfaces look woven; opacity masks punch holes. → [The Switch 2's order inside a GOB](../reference/nvn-objects.md#the-switch-2s-order-inside-a-gob) - driver comparisons report the wrong block dimensions for packaged 2D / 3D textures, or too little storage for linear block-compressed textures (64x64 BC1 with stride 128: 2048 bytes instead of 8192). → [Packaged texture block dimensions and linear storage rows](../reference/nvn-objects.md#packaged-texture-block-dimensions-and-linear-storage-rows) - huge stretched terrain walls and ceilings, flickering, while characters and the HUD are right: `WriteTexels` into a texture overwrote the mesh data stored right after it. → [Minimal texture layouts](../reference/nvn-objects.md#minimal-texture-layouts) - menus and dialogue boxes draw but contain no text, while images and pictogram digits are fine; the sky is black (CPU-written linear colour ramps). → [Linear textures in CPU-visible pools](../reference/nvn-objects.md#linear-textures-in-cpu-visible-pools) - a trap during graphics initialization in `SetupSurfaceInfoMemoryInside`, asserting `ctx.memorySize <= localmemsetupinfo.memorySize`. → [Linear render-target storage without the LINEAR flag](../reference/nvn-objects.md#linear-render-target-storage-without-the-linear-flag) - on an iPhone only, a scene's backgrounds are solid magenta and magenta frames flash, while the Mac is right. The log has `[RED] linear texture offset … / row pitch 32 not aligned to 64 bytes; created as a private texture (CPU writes invisible)`, then `[RED] deswizzle failed format 0x25 target 1`. → [Linear textures a device cannot view on their pool's buffer](../reference/nvn-objects.md#linear-textures-a-device-cannot-view-on-their-pools-buffer) - video frames, or a game's built-in default textures, are all zero. → [Textures written with `nvnTextureWriteTexels`](../reference/nvn-objects.md#textures-written-with-nvntexturewritetexels) - after a few minutes of play the main thread spends whole frames in `WriteTexels` (Metroid Dread's frames stopped at about 175 s). → [`WriteTexels` regions written in place by block-linear address](../reference/nvn-objects.md#writetexels-regions-written-in-place-by-block-linear-address) - black screen with every geometry right (`DM_NVN_HILITE` shows each sprite and glyph in place); the uniform buffer right (a `CBDUMP`), so every texture read 0. → [A pool's storage at creation is its textures' content](../reference/nvn-objects.md#a-pools-storage-at-creation-is-its-textures-content) - a game draws its UI and text but every image is black; `packaged textures: first uploads 0` while `TextureInitialize` counts the textures the game created (SD GUNDAM G GENERATION CROSS RAYS: 74, of which the 10 BC3 ones hold data and none is uploaded). After the fill works, one overlay still comes up with its text over nothing: the panel's background is missing and the text of the next block sits on top of it. → [`COMPRESSIBLE` in a pool the CPU writes is only a hint](../reference/nvn-objects.md#compressible-in-a-pool-the-cpu-writes-is-only-a-hint) - a texture the game filled with `memcpy` and flushed reads as zeros (BotW's sky brownish grey, the distant haze brown). → [First-use fill of storage the game flushed](../reference/nvn-objects.md#first-use-fill-of-storage-the-game-flushed) - magenta (ASTC's error colour) where UI images belong: a title logo and menu panels, while the 3D scene and the text draw; `DM_NVN_ZBLOCK=1` reports nothing (the textures are not uploaded on the CPU at all); `DM_NVN_TEXINFO=WxH` shows storage holding data at first use (`non-zero …`) in a pool with flags 0x22 (`CPU_UNCACHED | GPU_CACHED`). → [Storage of a CPU-uncached pool at first use](../reference/nvn-objects.md#storage-of-a-cpu-uncached-pool-at-first-use) - a picture that should change with a selection is black, or shows the previous item's picture while the item's name and description are right. `DM_NVN_TEXINFO=WxH` shows `swizzled=0` at first use with storage holding data, no packaged layout, in a `CPU_CACHED` or `CPU_UNCACHED` pool, and `DM_NVN_DIRTYCHECK=1` reports no missed write. → [Block-compressed storage the CPU wrote before first use](../reference/nvn-objects.md#block-compressed-storage-the-cpu-wrote-before-first-use) - a movie plays black (Age of Calamity: its intro movie under the "+ Skip" prompt). → [Mapped-range flushes taken as uploads (`tex_flush_upload`)](../reference/nvn-objects.md#mapped-range-flushes-taken-as-uploads-tex_flush_upload) - open-world ground is one flat colour on a flat plane with blocky seams, or water and sand are missing, while course meshes, rocks and the kart look right. `DM_NVN_TEXINFO=WxH` shows uncompressed textures with `swizzled=0`, no packaged layout and storage holding data in a `CPU_CACHED` pool. → [Uncompressed storage the CPU wrote, in a pool the GPU has not written](../reference/nvn-objects.md#uncompressed-storage-the-cpu-wrote-in-a-pool-the-gpu-has-not-written) - magenta surfaces (Metal decodes an all-zero ASTC block as the error colour (1, 0, 1)); a zero BC block decodes black, which looks like missing light; black screen while the UI (or a dialog box) draws in the right places under `HILITE` or in the pass dump; `packaged textures: first uploads 0`. → [CPU writes with no flush, caught by page protection (`tex_dirty_upload`)](../reference/nvn-objects.md#cpu-writes-with-no-flush-caught-by-page-protection-tex_dirty_upload) - a texture the game builds from CPU-filled textures read back with `nvnTextureReadTexels` comes out zero. → [`ReadTexels` from guest memory and textures written after first use](../reference/nvn-objects.md#readtexels-from-guest-memory-and-textures-written-after-first-use) - `[RED] upload batches belong to the submit thread only: up_begin called on thread '…'`, then an abort, with `pkg_upload` ← `tex_mtl` ← `mtl_read_texels` on the stack; or `CRASH sig=10` in `nvn_deswizzle` ← `mtl_read_texels`, at an address in a sparse virtual pool's reserved range. → [`ReadTexels` on a texture of a sparse pool](../reference/nvn-objects.md#readtexels-on-a-texture-of-a-sparse-pool) - a streamed texture's small mip levels hold another texture or zeros while its large levels are right (`texraw <serial>.<level>`), so surfaces sampled with a mip bias or at a distance show bright speckles, dark blotches and sharp detail where the Switch shows soft texture (Yoshi's felt), from the moment finer levels stream in (the opening going dark). → [GPU copies into textures uploaded from their storage](../reference/nvn-objects.md#gpu-copies-into-textures-uploaded-from-their-storage) - what the GPU drew into a texture is lost later: a texture re-created from the same memory, or one the game moved with `memcpy`, comes out zero; on the Switch it holds the drawing. Tears of the Kingdom: the grass of a meadow is drawn with no length and the ground under it goes dark, a few seconds after loading, tile by tile around Link. → [Render passes into textures uploaded from their storage](../reference/nvn-objects.md#render-passes-into-textures-uploaded-from-their-storage) - the `[nvn] residency set up to frame …` line shows hundreds of additions from `mirror_readback`'s line in `nvn_mtl.m` every 300 frames, and as many removals, with the residency commits' time up. Tears of the Kingdom: about 1,500 every 300 frames on an iPhone 17 (1.4.2, seedds/nxnative#931), about 370 on a Mac. → [Readback buffers kept for reuse](../reference/nvn-objects.md#readback-buffers-kept-for-reuse) - textures that should hold CPU-written data come out magenta (ASTC's error colour) or black. → [Sampled textures in a sparse pool uploaded through the page table](../reference/nvn-objects.md#sampled-textures-in-a-sparse-pool-uploaded-through-the-page-table) - the submit thread spends most of its time in `nvn_dirty_since` under `nvn_sparse_since`, called from `tex_mtl` (render-target and texture lookups of textures in a sparse pool). → [A sparse texture's CPU-write check at every lookup](../reference/nvn-objects.md#a-sparse-textures-cpu-write-check-at-every-lookup) - some textures are re-uploaded every frame (several MB per frame). → [Dirty-page ranges of pools that share a host page](../reference/nvn-objects.md#dirty-page-ranges-of-pools-that-share-a-host-page) - packaged textures re-uploaded at every use with unchanged content; upload staging and frame times rising. → [Writes beside a packaged texture in a shared host page](../reference/nvn-objects.md#writes-beside-a-packaged-texture-in-a-shared-host-page) - about one run in four stalled early (around the opening movie or the title), with no log output, not even the time-limit report. → [Dirty-page tracker race and early stalls](../reference/nvn-objects.md#dirty-page-tracker-race-and-early-stalls) - a CPU-written texture stays stale after later writes; letters can be missing from a glyph cache. → [Dirty-page writes missed during upload](../reference/nvn-objects.md#dirty-page-writes-missed-during-upload) - a host system call writing into storage after its NVN pool was finalized fails with `EFAULT`; a direct write can fault after the tracker stopped owning the page. → [A retired pool remains read-only](../reference/nvn-objects.md#a-retired-pool-remains-read-only) - `[RED] NVN unimplemented function called: nvnSamplerBuilderSetBorderColorui` during renderer initialization. → [Integer sampler border colours](../reference/nvn-objects.md#integer-sampler-border-colours) - `[RED] sampler ID 4096 not registered` (or another ID past the sampler pool), once, from the first frames on. → [Bound handles are the driver's 32-bit words](../reference/nvn-objects.md#bound-handles-are-the-drivers-32-bit-words) - device / subsystem setup returns quietly and the next stage never starts. → [Version and capability checks that fail quietly](../reference/nvn-objects.md#version-and-capability-checks-that-fail-quietly) - a null-pointer crash early in `nnMain`, right after NVN setup should have happened (Super Mario 3D World + Bowser's Fury, `main+0x759e08`: the device singleton `main+0x1a28ea0` is still null). → [The device's API version](../reference/nvn-objects.md#the-devices-api-version) - null read at `main+0xb8462c` right after the first two textures, called from `main+0x670eb0` (Bayonetta 3), or cleanup crashes at `main+0x9c0d1c` after shader initialization fails (ASTRAL CHAIN). → [Newest GPU code version reported by the driver](../reference/nvn-objects.md#newest-gpu-code-version-reported-by-the-driver) - none seen: a Switch 2 game asking `nvnDeviceGetInteger` got the Tegra X1's values (measured on a Switch 1), and items past 0x5F answered 0 with a red line. → [The Switch 2's device values](../reference/nvn-objects.md#the-switch-2s-device-values) - a jump to pc=0 right after the NVN bootstrap loader (`lr=main+0x37fe930`, `[RED] NVN address lookup of an unknown name: nvnSetExternalDebuggerEnabledNVX`). → [Extensions fetched by name and called unchecked](../reference/nvn-objects.md#extensions-fetched-by-name-and-called-unchecked) - SIGBUS in `AGCDeserializedReply`, address in the guest stack region. → [NVN entry points on the big host stack](../reference/nvn-objects.md#nvn-entry-points-on-the-big-host-stack) - red `NVN unimplemented function called` lines for `nvnColorStateGetBlendEnable`, `nvnBlendStateGetBlendFunc`, `nvnPolygonStateGetCullFace`, `nvnDepthStencilStateGetDepthTestEnable`, `nvnBufferBuilderGetSize`, `nvnTextureBuilderGetWidth`, …. → [State read back through NVN getters](../reference/nvn-objects.md#state-read-back-through-nvn-getters) - an abort in device setup when `nvnTexturePoolGetSize` / `nvnSamplerPoolGetSize` returned 0. → [Pool size getters, texture address and command memory size](../reference/nvn-objects.md#pool-size-getters-texture-address-and-command-memory-size) - `[RED] NVN unimplemented function called: nvnTextureBuilderGetMemoryOffset`, then `nvnTextureBuilderGetRawStorageClass`. → [Builder storage getters](../reference/nvn-objects.md#builder-storage-getters) - `[nvn-mtl] FATAL buffer copy address is in no memory pool src=0x70d08a8b00 dst=0 n=0x29a00` as a match loads: a recorded `CopyBufferToBuffer` whose destination is 0. → [`Map` of a pool without CPU access returns NULL](../reference/nvn-objects.md#map-of-a-pool-without-cpu-access-returns-null) - red stub lines for NVN calls. → [NVN calls that were red stubs](../reference/nvn-objects.md#nvn-calls-that-were-red-stubs) - `nvnWindowGetPresentInterval`, `nvnCommandBufferSetCopyImageStride` missing. → [SDK 8 window and copy-stride entry points](../reference/nvn-objects.md#sdk-8-window-and-copy-stride-entry-points) - `[RED] texture bound to an image slot lacks the shader-write usage`, and compute image writes go to a dummy texture. → [Image bindings supply shader-write intent](../reference/nvn-objects.md#image-bindings-supply-shader-write-intent) - `[RED] NVN unimplemented function called` for each. → [`nvnTextureBuilderGetViewOffset`, `nvnTextureViewCompare`, `nvnBlendStateSetAdvancedNormalizedDst`](../reference/nvn-objects.md#nvntexturebuildergetviewoffset-nvntextureviewcompare-nvnblendstatesetadvancednormalizeddst) - a pool walk makes gigabytes of textures from far fewer images: Ocarina of Time's 32,768 IDs name 3,607 storages, and one texture per ID came to 2 GB. → [Texture IDs of one storage share one packaged texture](../reference/nvn-objects.md#texture-ids-of-one-storage-share-one-packaged-texture) - thousands of first uploads a frame in a scene whose textures do not change: Ocarina of Time, about 15,000 a frame. → [Finalizing a copy of a texture object](../reference/nvn-objects.md#finalizing-a-copy-of-a-texture-object) ## Rendering - clang reports null dereferences in `nvnWindowInitialize` and `clear_tex`; clearing a null texture crashes with `DM_NVN_PASSDUMP=1`. → [Null textures in diagnostic logs](../reference/rendering.md#null-textures-in-diagnostic-logs) - Metal aborts on a texture descriptor with an absurd size (`height (1869367126) greater than … 16384`). → [Texture objects copied into command records](../reference/rendering.md#texture-objects-copied-into-command-records) - a decoded movie stays black even though its YUV textures contain the picture; disabling its depth test makes it visible. → [New textures start as zero](../reference/rendering.md#new-textures-start-as-zero) - glyphs render as white boxes (the font atlas is `(1, 1, 1, R)`). → [Texture swizzle through swizzled Metal views](../reference/rendering.md#texture-swizzle-through-swizzled-metal-views) - RGB565, RGB5A1 or RGB5 textures sample with red and blue exchanged: smeared, banded rock, the shapes right and the colours wrong; or what the GPU cleared, drew or copied into such a texture reads back to the game, or samples, with red and blue exchanged. → [RGB565-family textures in Metal's channel order](../reference/rendering.md#rgb565-family-textures-in-metals-channel-order) - outdoor battle ground and lower foliage are nearly black while the characters and the UI stay lit: a baked shadowmask takes the sunlight away. RGBA4 textures sample with their four channels reversed. → [RGBA4 textures in Metal's channel order](../reference/rendering.md#rgba4-textures-in-metals-channel-order) - dark boxes and cream cloud rectangles behind HUD prompts, a black stamina wheel and a black System menu background (layout captures). → [`nvnTextureCompare` compares the channel mapping](../reference/rendering.md#nvntexturecompare-compares-the-channel-mapping) - Metal validation aborts in `tex_by_id` with `MTLPixelFormatDepth32Float` not compatible with `MTLPixelFormatR32Float`. → [Sampling a depth attachment through a red texture view](../reference/rendering.md#sampling-a-depth-attachment-through-a-red-texture-view) - `newTextureViewWithPixelFormat` takes a large share of the replay thread (45% in Age of Calamity) when a game registers textures into a ring of IDs before every bind. → [Texture views cached by texture and view parameters](../reference/rendering.md#texture-views-cached-by-texture-and-view-parameters) - daylight scenes washed out to white (every read of a texture returned one fixed value); `texture type mismatch` red lines, among them `declares slot … as Metal type 6, texture ID … is type 5` (a cube in a cube array slot). → [Compatible views for a mismatched declared texture type](../reference/rendering.md#compatible-views-for-a-mismatched-declared-texture-type) - with `MTL_SHADER_VALIDATION=1`, `Invalid Metal usage: Texture is not resident` for a texture allocated in `tex_fit`; without validation those reads are undefined. → [Compatible views made from the texture under a view](../reference/rendering.md#compatible-views-made-from-the-texture-under-a-view) - a type mismatch when a Metal 1D texture is bound to a shader's `texture2d` argument. → [1D textures as one-row 2D textures](../reference/rendering.md#1d-textures-as-one-row-2d-textures) - shaders that sample a cube texture as `texturecube_array` get a type mismatch. → [Cube textures held as 6-layer 2D arrays](../reference/rendering.md#cube-textures-held-as-6-layer-2d-arrays) - an abort in `MTLTextureDescriptor` validation, `arrayLength (510) … greater than the max allowed size (341)`, when the prologue movie ends. → [Cube map arrays count layer-faces](../reference/rendering.md#cube-map-arrays-count-layer-faces) - an abort in Metal's validation: `newSliceRange.length(1) must be a multiple of (6)`. → [Cube views count their layers in cubes](../reference/rendering.md#cube-views-count-their-layers-in-cubes) - `texture type mismatch … declares slot 10 as Metal type 5, texture … is type 3` (undefined reads); the later `[RED] texture type mismatch: shader declares a cube, texture is 2D` could also report an unused conditional input as an error. → [A 2D texture in a cube slot binds the zero cube](../reference/rendering.md#a-2d-texture-in-a-cube-slot-binds-the-zero-cube) - `[RED] texture type mismatch: shader … declares slot … as Metal type 7, texture ID … is type 2 … bound as is` (or type 3, a 2D array); the reads are undefined. → [A 2D texture in a 3D slot binds the zero 3D texture](../reference/rendering.md#a-2d-texture-in-a-3d-slot-binds-the-zero-3d-texture) - `[RED] texture type mismatch: shader … declares slot … as Metal type 2, texture ID … is type 4 (NVN target 5, …); bound as is`, for a shader whose MSL declares the slot `texture2d_ms`. → [Multisample texture slots](../reference/rendering.md#multisample-texture-slots) - translucent UI (frosted text bands, button guides, dialog headers) yellow and white. → [Integer views for images a shader declares uint or int](../reference/rendering.md#integer-views-for-images-a-shader-declares-uint-or-int) - flat-coloured objects with no texture detail in an otherwise correct scene: the UVs and colours a vertex factory fetches from buffers read 0. Then `texture buffers bound as 2D rows … N times, about N made` in the log, a Metal texture for nearly every bind. → [Buffer textures behind handles in uniform buffers, and rows of finalized descriptors](../reference/rendering.md#buffer-textures-behind-handles-in-uniform-buffers-and-rows-of-finalized-descriptors) - `texture type mismatch: shader declares 2, texture is 9`; the slot read 0. → [Buffer textures read by 1D integer fetches (row wrap)](../reference/rendering.md#buffer-textures-read-by-1d-integer-fetches-row-wrap) - none of its own seen here. Pull request #984 reports GPU hangs from huge light counts on its build of the same game. → [Integer buffer textures read through float slots](../reference/rendering.md#integer-buffer-textures-read-through-float-slots) - none visible on an M6, where at most 0.23 % of pixels differ between paired runs. GitHub issue #783 reports wrong light offsets on an M2. → [Integer textures read through float slots](../reference/rendering.md#integer-textures-read-through-float-slots) - particle effects drawn at the wrong scale or place, or flickering, where the particle data is a buffer texture at a pool offset that is not a multiple of 16; log line `buffer texture at pool offset …, below Metal's 16-byte alignment`. → [Buffer textures at offsets below 16 bytes](../reference/rendering.md#buffer-textures-at-offsets-below-16-bytes) - lighting that alternates between lit and unlit from one frame to the next on an iPhone, the same scene steady on a Mac; log lines `texture buffer (texture ID …, … at pool offset …) has no 2D-row form for a wrapped 1D fetch: the slot reads 0` and `texture type mismatch: … a buffer texture: the slot reads 0 (dummy)`. → [Buffer texture rows at a pool offset the device will not view](../reference/rendering.md#buffer-texture-rows-at-a-pool-offset-the-device-will-not-view) - torn digits and a background in blue steps (Rhythm Heaven Groove's latency calibration). → [Automatic block height truncates](../reference/rendering.md#automatic-block-height-truncates) - magenta (the ASTC error colour) on streamed textures in a sparse pool; `DM_NVN_ZBLOCK` finds such textures (all-zero blocks). → [Sparse textures laid out in 64 KB tiles](../reference/rendering.md#sparse-textures-laid-out-in-64-kb-tiles) - a CPU-filled texture shuffled into a patchwork of rectangles (OCTOPATH TRAVELER's world map on the traveler selection). → [Sparse textures take the block height of their 64 KB tile](../reference/rendering.md#sparse-textures-take-the-block-height-of-their-64-kb-tile) - none visible on an M6 on the Frigate Orpheon's deck. Laid out 1 GOB high, the mapped tiles of a streamed 3D texture fall in scattered places, so lookups read zero in the holes; GitHub issue #783 reports a black gunship hull in the opening on an M2. → [Sparse 3D textures take the standard 3D tile](../reference/rendering.md#sparse-3d-textures-take-the-standard-3d-tile) - crashes that move between runs (30–70% of boots, in the first minute): in the allocator, on bogus pointers, in unrelated threads. Unreal's purgatory proxy (05-debugging) finds freed 64 KB-aligned blocks modified; with the parked blocks read-only, the faulting store is a `memcpy` of texture mip data from the texture streamer into the buffer `RHILockTexture2D` returned. → [Sparse textures of 8- and 16-byte blocks: blocks at most 8 GOBs high](../reference/rendering.md#sparse-textures-of-8--and-16-byte-blocks-blocks-at-most-8-gobs-high) - a small CPU-filled sparse texture shows part of its image beside fragments, cut off at the bottom (Yoshi's Crafted World's loading icon: the left half of a chalk drawing and two stray strokes). → [Sparse textures smaller than a tile keep the automatic block height](../reference/rendering.md#sparse-textures-smaller-than-a-tile-keep-the-automatic-block-height) - streamed textures read 0 (magenta on Monster Hunter Rise's title screen's clothes). → [Sparse textures bound from their first mapped level](../reference/rendering.md#sparse-textures-bound-from-their-first-mapped-level) - textures a mip level sharper or blurrier than on the Switch where the game biases its sampler; in the Vulkan layer, a red line `sampler LOD bias … not implemented`. → [Sampler LOD bias](../reference/rendering.md#sampler-lod-bias) - whatever a game keeps in a texture that it samples past its edge with clamp-to-border reads the wrong value there: grass flattened along Link's path in Tears of the Kingdom, its bend map filled with "bent" wherever the window scrolled. → [Border colours Metal has no sampler state for](../reference/rendering.md#border-colours-metal-has-no-sampler-state-for) - the process ends at once (the window vanishes), with `-[MTLTextureDescriptorInternal validateWithDevice:]` failing an assertion such as `requests 9 mipmap levels, but the dimensions (1, 1, 1) can only support 1`, or `sampleCount must be > 1 for multisample textures`. → [Texture fields Metal refuses](../reference/rendering.md#texture-fields-metal-refuses) - in an Unreal Engine game, textures and lighting turn blurry and muddy about a second after an area loads and stay that way, whatever the frame rate, render scale or upscaling; no red line. → [Unreal's texture streaming pool](../reference/rendering.md#unreals-texture-streaming-pool) - ≈13 MB/frame leak. → [Transient render targets shared by storage](../reference/rendering.md#transient-render-targets-shared-by-storage) - a model has correct geometry, base colour and normals but appears as a black silhouette; deferred lighting's material-ID depth texture stays zero. → [IMAGE usage does not split texture storage](../reference/rendering.md#image-usage-does-not-split-texture-storage) - GPU memory grows with every image shown; the memory line's `shared textures` count keeps rising. → [Shared-storage entries taken over by a new texture](../reference/rendering.md#shared-storage-entries-taken-over-by-a-new-texture) - GPU memory grows as resolution changes or rooms load, although almost every retained texture still has a live NVN descriptor; reclaiming unused sharing-table entries cannot recover it. → [Live resolution variants share physical image storage](../reference/rendering.md#live-resolution-variants-share-physical-image-storage) - the whole picture came out darker and more saturated on the Mac and the iPhone: comparing with a Switch screenshot, every channel at every level equalled the Switch value decoded from sRGB once more (0.55 → 0.26, 0.75 → 0.52). → [Render-target views that change the format](../reference/rendering.md#render-target-views-that-change-the-format) - a movie (or another picture the game converts each frame) does not show: the screen keeps the last 3D frame while the decoder delivers every picture. A pass dump shows a pass writing one serial and the composite sampling another serial of the same size, the two Metal formats `RGBA8Unorm` (70) and `RGBA8Unorm_sRGB` (71). → [Textures of an sRGB / linear pair over the same storage](../reference/rendering.md#textures-of-an-srgb--linear-pair-over-the-same-storage) - a clear of, or a format-converting copy into, a texture made without render-target use is declined. → [Render-target use added on demand](../reference/rendering.md#render-target-use-added-on-demand) - `CRASH sig=11 addr=0x794` in `-[AGXG16GFamilyRenderContext_mtlnext drawIndexedPrimitives:…]+0x50`, called from `draw_`, right after the log line `texture upgraded to allow format views` (Metal API validation reports nothing first). → [A texture upgrade while a draw binds its arguments ends the pass](../reference/rendering.md#a-texture-upgrade-while-a-draw-binds-its-arguments-ends-the-pass) - `render target is a compressed-format texture …`; the pass's draws did nothing (the attachment was left out), or the pipeline-descriptor validation aborts the process. → [Compressed textures as render targets through an uncompressed shadow](../reference/rendering.md#compressed-textures-as-render-targets-through-an-uncompressed-shadow) - on an iPhone before the A17 Pro, the game runs until its first BC texture, then `failed assertion 'Texture Descriptor Validation' … MTLTextureDescriptor has invalid pixelFormat (134).` (or another number from 130 to 153, Metal's BC formats; 134 is `BC3_RGBA`) and `CRASH sig=6`, the backtrace through `tex_mtl`, `tex_by_id` and `encode_args`. → [GPUs without BC textures are refused at start](../reference/rendering.md#gpus-without-bc-textures-are-refused-at-start) - the boot aborts in Metal's pipeline validation: `MTLPixelFormatDepth16Unorm is not color renderable`. → [A depth texture drawn through a colour view](../reference/rendering.md#a-depth-texture-drawn-through-a-colour-view) - a G-buffer target holds only scattered squares (a different order for each 32×32 tile). → [The same texture attached at two colour slots](../reference/rendering.md#the-same-texture-attached-at-two-colour-slots) - `no render target could get an MTLTexture` (the pass skipped). → [Passes with no render target](../reference/rendering.md#passes-with-no-render-target) - a black world: everything rendered through a 3D LUT built by layered draws comes out black (every plane went to plane 0); `DM_NVN_PASSDUMP` shows no `L` line. → [Layered passes for vertex shaders that write the layer](../reference/rendering.md#layered-passes-for-vertex-shaders-that-write-the-layer) - a frame-time spike every few frames (the Metal HUD's frame-time line jumps by several ms at a regular interval) while the scene stands still; `DM_NVN_GPUPROF` over consecutive frames shows the slow frame with about 130 more render passes, each one draw into a 64x64 to 8x8 face of a cube or array level, and the next pass starting late. → [Passes into other layers of one texture level run as one layered pass](../reference/rendering.md#passes-into-other-layers-of-one-texture-level-run-as-one-layered-pass) - a GPU-bound frame with many passes on the same targets, one after the other, each preceded by a compute encoder of one dispatch (`DM_NVN_GPUPROF`: `compute / copy after pass … dispatches 1` between render passes of the same size); about 4 ms of GPU idle a frame inside command buffers in Metal System Trace. → [Compute dispatches between the draws of a pass run ahead of it](../reference/rendering.md#compute-dispatches-between-the-draws-of-a-pass-run-ahead-of-it) - a scene drawn only in a small square in the top-left corner of a black screen; speckled and blocky patches; a full-screen overlay showing one tile; the texture dump right after the scene pass shows the picture only in the corner, and `DM_NVN_HILITE` on the scene's shaders lights only the corner. → [Clears of attachments larger than the render pass](../reference/rendering.md#clears-of-attachments-larger-than-the-render-pass) - a point light (a lantern, a lighter) lights only one side of the room with straight, sharp edges, and everything else around it is dark as if in shadow; a dump of the shadow cube (DM_CTL `texraw`, every face) shows face 0 drawn and faces 1-5 all zero; more generally, layers above the first of an array, cube or 3D target keep their old or zero content after a clear. → [Clears of layered render targets in a pass that is not layered](../reference/rendering.md#clears-of-layered-render-targets-in-a-pass-that-is-not-layered) - `texture clear case not implemented … mask 0x1`. → [A channel mask that covers every channel is a whole clear](../reference/rendering.md#a-channel-mask-that-covers-every-channel-is-a-whole-clear) - `texture clear case not implemented … mask 0x8` while entering a rendered scene. → [Texture clears with partial channel masks or regions](../reference/rendering.md#texture-clears-with-partial-channel-masks-or-regions) - red lines for unimplemented mid-pass, partial-mask and partial-scissor clears (the clears were dropped); `depth-stencil clear with a scissor or partial stencil mask, cleared whole` (logged once). → [Clears inside a pass, with a partial mask or a partial scissor](../reference/rendering.md#clears-inside-a-pass-with-a-partial-mask-or-a-partial-scissor) - a pass loads a whole depth/stencil target every frame only to clear it: Donkey Kong Bananza clears a 2880x1620 Depth32F-S8 target with stencil mask `0x1`, before any pass is open, and loads 22.8 MB a frame for it. → [A depth clear over the whole target with a partial stencil mask](../reference/rendering.md#a-depth-clear-over-the-whole-target-with-a-partial-stencil-mask) - a tile grid in Ultrahand and Recall highlights; an `EQUAL` depth test rejects fragments writing the same depth as a cleared Depth16 target. → [Depth16 load-clears match fragment writes](../reference/rendering.md#depth16-load-clears-match-fragment-writes) - solid magenta blocks, exactly (255, 0, 255), hard-edged and aligned to the 16-pixel grid (16×16, sometimes two stacked): Super Mario 3D World and Super Mario Odyssey showed them only on the iPhone; Captain Toad and Origami King on a Mac, Apple M6, Captain Toad in about half the frames of the opening course, moving with the falling leaves. On an RG11B10F target (no alpha) the blocks are pure black or neon green, (0, 252, 0), and flicker, sometimes only part of a tile: Super Mario Bros. Wonder on an Apple M6 and an M1, most visible on the speech bubbles of dialogue; or non-finite pixels that bloom spreads into green blobs (NieR:Automata on the Mac). A rendered cutscene alternates brightness every game frame, with blocky bands of light and shadow switching on and off: each lighting-zone bit flips every frame (Xenoblade Chronicles 3, a read-only image load). → [Same-pass feedback read through a snapshot](../reference/rendering.md#same-pass-feedback-read-through-a-snapshot) - a scene full of deferred decals runs far below its target where the same scene with `DM_NVN_FB_SNAP=0` holds it, and the log's `same-pass feedback sampling: snapshot #…` count climbs by hundreds a frame. Tears of the Kingdom's first shrine on an iPad Pro 11 (M5): GPU p50 58.8 ms, about 15 fps, about 284 snapshots a frame (seedds/nxnative#737); Breath of the Wild on the Great Plateau, camera toward the Temple of Time, on an iPad Pro 13 (M4): 60 → about 42 fps, about 45 one-draw passes more a frame on the 1920×1080 G-buffer. Splatoon Raiders in inked stages on a MacBook Air (M2): GPU p50 22–26 ms against 11–14 ms in the hub, a one-draw pass and a whole-map snapshot of its 6400×6400 ink map (80 MB) for each ink stamp (seedds/nxnative#1063). The `[nvn] same-pass feedback up to frame …` line (every 300 frames) gives the snapshots, reuses and tile reads per frame. → [Same-pass feedback read from the tile](../reference/rendering.md#same-pass-feedback-read-from-the-tile) - the `[nvn] residency set up to frame …` line (every 300 frames) shows hundreds to thousands of additions from `fb_snap`'s line in `nvn_mtl.m`, gigabytes of them, and as many removals, with the residency commits' time and the submit thread's kernel time up. Tears of the Kingdom on an iPhone 17 (1.4.2, seedds/nxnative#931): 1,500-1,600 additions of 2.4 MB textures every 300 frames, residency commits 250-600 ms every 300 frames against about 25 in an older build, kernel time on the submit thread 1-2 ms a frame against 0.2. → [Snapshot textures taken by format and size](../reference/rendering.md#snapshot-textures-taken-by-format-and-size) - a scene with many bindless decals runs well below its target with the GPU busy, and a pass dump (`DM_NVN_PASSDUMP`) shows long runs of one-draw passes on the same targets, each loading and storing every attachment. Fire Emblem Fortune's Weave's battle maps: 31 consecutive one-draw passes on four 1024×576 targets a frame, 126.5 passes and about 1.4 GB of attachment loads and stores a frame. → [Bindless shaders taken as depth readers](../reference/rendering.md#bindless-shaders-taken-as-depth-readers) - a game that reads textures through a pool runs slower than its draws explain, with passes of one draw each on the same targets. A pass dump (`DM_NVN_PASSDUMP`) shows `SetRenderTargets` going on in the open pass and the pass ending anyway. Ocarina of Time in Kokiri Forest: two frames of four had 219 passes, 127 of them on the 128x128 reflection probe's cube faces, and frame times of 15, 15, 18, 18.5 ms in a cycle. → [Pool shaders taken as depth readers](../reference/rendering.md#pool-shaders-taken-as-depth-readers) - NaN texels in the upper levels of a texture the game fills level by level (each level drawn from the one above), and from there NaN wherever the texture is read: black speckles in whole 2×2 quads, white blotches once bloom spreads them, and a dark frame from the eye adaptation. → [Mip-chain pass sampling the level it renders](../reference/rendering.md#mip-chain-pass-sampling-the-level-it-renders) - bloom wide and hard around bright edges: neon letters swell into fat, filled shapes. With `DM_NVN_FB_SNAP=0` they are thin again, but the white blotches of the entry above come back. → [Upsample pass reading the level above the one it renders](../reference/rendering.md#upsample-pass-reading-the-level-above-the-one-it-renders) - text a game renders into textures for the title and the menus comes out upside down, while the scene looks right. → [Lower-left window origin](../reference/rendering.md#lower-left-window-origin) - geometry appears inside out and almost black; a fullscreen indirect-lighting triangle is entirely culled even though its vertex data and polygon state match the game. → [Queue initialization captures the raster origin](../reference/rendering.md#queue-initialization-captures-the-raster-origin) - a pink window with every command buffer ignored while headless runs look right: the first presents fail on the display command buffer with `kIOGPUCommandBufferCallbackErrorPageFault`, and after a few of those macOS ignores every submission of the process ("Ignored (for causing prior/excessive GPU errors)"). → [The residency set committed before a present](../reference/rendering.md#the-residency-set-committed-before-a-present) - `kIOGPUCommandBufferCallbackErrorPageFault` or `kIOGPUCommandBufferCallbackErrorHang` on a command buffer, and nothing says which draw or dispatch caused it; `DM_RES_CHECK=1` reports no `missing residency`. → [Naming the shaders of a GPU fault](../reference/rendering.md#naming-the-shaders-of-a-gpu-fault) - with present snapshots on (`DM_PRESENT_SNAP`, the iOS launcher's **Frame buffering**), a frozen, corrupted picture from the first presents; the first error is already `kIOGPUCommandBufferCallbackErrorSubmissionsIgnored` ("Ignored (for causing prior/excessive GPU errors)") on the display command buffer, then on every upload, segment and submission command buffer, and `[RED] present snapshots: the previous copy into a ring slot did not finish within 2 s`. With snapshots off the same game runs. → [A present snapshot's copy needs the same residency commit](../reference/rendering.md#a-present-snapshots-copy-needs-the-same-residency-commit) - an abort at the first present: `[RED] upload batches belong to the submit thread only: up_begin called on thread 'nvn-present-link'`, with `pkg_upload`, `tex_mtl` and `present_now` in the backtrace. → [A CPU-written window texture resolved where the present is queued](../reference/rendering.md#a-cpu-written-window-texture-resolved-where-the-present-is-queued) - a game that renders below the screen's resolution looks soft on a phone, in a large Mac window or on a 4K screen. → [The present upscales through MetalFX](../reference/rendering.md#the-present-upscales-through-metalfx) - in handheld mode the picture fills only two thirds of the screen's width and height, in the bottom-left corner (the top-left with the upper-left origin), the rest black. → [The NVN present crops by the vi layer crop](../reference/rendering.md#the-nvn-present-crops-by-the-vi-layer-crop) - a scene turns narrow, with black bars at its sides, while the swapchain or window textures keep their size; circles come out as tall ovals. The log has `vi::SetLayerCrop 0,0 1200x960` and `present upscaling: ... 1200x960 → 1800x1440` in a 2560x1440 window. → [A crop only picks texels; the picture has the layer's shape](../reference/rendering.md#a-crop-only-picks-texels-the-picture-has-the-layers-shape) - one-draw passes on one target, hundreds of times a frame, with the same attachments each time (a `DM_NVN_GPUPROF` frame: `load` and `store` of the whole target in every line); a low frame rate that follows the target's size. → [Setting the same targets again continues the pass](../reference/rendering.md#setting-the-same-targets-again-continues-the-pass) - a pass on a very large target costs about the same however little it draws; `DM_NVN_GPUPROF` shows time proportional to the target's area. → [A render area for passes on very large targets](../reference/rendering.md#a-render-area-for-passes-on-very-large-targets) - `[RED] NVN unimplemented function called: nvnCommandBufferShadingRateImagePalette`, or `nvnCommandBufferBindShadingRateImage` or `nvnCommandBufferSetShadingRatePaletteMode`, every frame. → [Variable rate shading ignored](../reference/rendering.md#variable-rate-shading-ignored) - angle-dependent character smearing, or vertex-only pipeline failures with `invalid depth/stencil pipeline formats 16843012/260`, although the pass began with valid `260/260` formats. → [Ten attachment records for eight colors and depth-stencil](../reference/rendering.md#ten-attachment-records-for-eight-colors-and-depth-stencil) - Metal aborts at pipeline creation: `depthAttachmentPixelFormat (MTLPixelFormatInvalid) and stencilAttachmentPixelFormat (MTLPixelFormatDepth32Float_Stencil8) must match`. → [Combined depth-stencil formats stay paired in passes and pipeline keys](../reference/rendering.md#combined-depth-stencil-formats-stay-paired-in-passes-and-pipeline-keys) - undefined values blended into attachments the fragment shader leaves alone. → [No writes to colour outputs the shader does not write](../reference/rendering.md#no-writes-to-colour-outputs-the-shader-does-not-write) - foliage, hair and fences drawn as solid quads (the parts the texture leaves transparent filled with its colour or black), dissolve effects solid instead of breaking up; once per run `SetAlphaRef …: the host has no alpha test`. → [The alpha test through a library of its own](../reference/rendering.md#the-alpha-test-through-a-library-of-its-own) - data a game builds in a target by combining draws comes out wrong; in Xenoblade Chronicles 2 indoor lighting has hard-edged dark boxes (world-space boxes in perspective, darker with the time of day) and lighter translucent rectangles elsewhere; in Skyward Sword HD a brown cast covers the distance and near objects turn into dark silhouettes, coming and going with the camera. A pass dump shows `lo=7` (or any value other than 3) on the `D` lines of the draws that write the target. → [Logic operations through a library of its own](../reference/rendering.md#logic-operations-through-a-library-of-its-own) - `nvnBlendStateSetAdvancedMode 8` (SRC_OVER) logged and blended with the state's own functions. → [Advanced blend modes as Porter-Duff factors](../reference/rendering.md#advanced-blend-modes-as-porter-duff-factors) - striped lighting: black and white bands that follow depth on every lit surface, as if every pixel were in or out of shadow at random. → [Stencil-mode texture views read through `X32_Stencil8`](../reference/rendering.md#stencil-mode-texture-views-read-through-x32_stencil8) - a character drawn as a dithered silhouette inside a dithered square (DRAGON QUEST VII Reimagined's hero). → [Stencil-mode textures from the texture builder](../reference/rendering.md#stencil-mode-textures-from-the-texture-builder) - `[nvn] SetConservativeRasterEnable on: ignored by host for now`, followed by `[RED] NVN unimplemented function called: nvnCommandBufferSetConservativeRasterDilate`. → [Conservative rasterization remains unimplemented](../reference/rendering.md#conservative-rasterization-remains-unimplemented) - characters (skinned models) invisible or stretched into streaks while the level renders; `vertex attribute format … does not match shader input type …` for a remaining mismatch. → [Integer vertex inputs](../reference/rendering.md#integer-vertex-inputs) - red lines 89 and 96 (`vconv_bind`, the CPU conversion every draw); about a quarter of Age of Calamity's replay thread in battle. → [Shadow vertex inputs](../reference/rendering.md#shadow-vertex-inputs) - an unsigned iOS build reports `[RED] pulling library ... not usable (no library)` and its draws wait for pipelines even with the profile's `pso_mtl4 on`, or packaging with `IOS_PULL=1` fails with `SKIPS[@]: unbound variable`. → [Pulling vertex inputs](../reference/rendering.md#pulling-vertex-inputs) - a fullscreen post-process draw writes no color, then a later blur composite darkens scenery while the character remains visible. → [Float32 vertex padding through integer inputs](../reference/rendering.md#float32-vertex-padding-through-integer-inputs) - `Vertex attribute m_36(5) of type uint4 cannot be read using MTLAttributeFormatHalf2` (draws dropped: black silhouettes); UVs collapse onto one texel (flat tan characters); vertices far out of view (negative 16-bit values widened with zeros). → [CPU conversion of vertex attributes the input type cannot take](../reference/rendering.md#cpu-conversion-of-vertex-attributes-the-input-type-cannot-take) - `[RED] BindVertexAttribState n=17`, tens of thousands of times, and a scene that draws wrong or not at all: the bind was refused, so the draws kept the previous layout. → [More than 16 vertex attributes](../reference/rendering.md#more-than-16-vertex-attributes) - `vertex attribute format … not mapped` (printed once). → [Vertex formats Metal lacks](../reference/rendering.md#vertex-formats-metal-lacks) - `[RED] BindVertexBuffers first=16 n=1` … `first=31`, thousands of times a run and no visible fault. → [Null vertex buffers bound past stream 15](../reference/rendering.md#null-vertex-buffers-bound-past-stream-15) - the assertion `buffer index (31) must be < 31`. → [Vertex streams 14 and 15 at Metal slots 14 and 15](../reference/rendering.md#vertex-streams-14-and-15-at-metal-slots-14-and-15) - Scaleform fills come out as solid white or light grey sheets over the whole screen, hard-edged triangles and bands, and the menu text is missing (a language list or a title screen that is all white behind its button prompt). → [Vertex streams at addresses that are not 4-byte aligned](../reference/rendering.md#vertex-streams-at-addresses-that-are-not-4-byte-aligned) - hard-edged translucent slabs and triangles over the scene that move with the camera, where a full-screen pass blends an effect in (Super Mario Odyssey: white wedges through the Cascade Kingdom's waterfall mist, one edge through the centre of the screen). → [Vertex fetches past a stream's bound size](../reference/rendering.md#vertex-fetches-past-a-streams-bound-size) - scenes and characters black, only foliage, light shafts and the HUD drawn; pass dumps full of `Z … draw skipped: no program bound`. → [Programs bound per stage](../reference/rendering.md#programs-bound-per-stage) - `[RED] failed to create render pipeline (vertex 790573a52b9c5053_b fragment f39fb42850f50ecd_b): Fragment input(s) user(locn0),user(locn1) … not written by vertex shader`, once on entering the first investigation; `texture type mismatch: shader declares a cube, texture is 2D` (a pixel shader run with another pair's bindings). → [Composite program taken again after a replay state restore](../reference/rendering.md#composite-program-taken-again-after-a-replay-state-restore) - `no program bound before the draw`, `program has no vertex shader` (a draw after a dispatch is dropped); `the dispatched program has no compute shader` (a dispatch after a graphics bind). → [Compute programs bound apart from graphics programs](../reference/rendering.md#compute-programs-bound-apart-from-graphics-programs) - a red line: the 8-bit index buffer had GPU-side writes in the submission (indices read stale). → [8-bit indices widened on the GPU after a write in the same submission](../reference/rendering.md#8-bit-indices-widened-on-the-gpu-after-a-write-in-the-same-submission) - indirect draws whose record the GPU writes earlier in the frame cannot be read on the CPU at replay; GPU-driven effects drawn as indirect quads, which Metal has no primitive for. → [Indirect draws and dispatches read by the GPU](../reference/rendering.md#indirect-draws-and-dispatches-read-by-the-gpu) - an empty G-buffer pass (the title screen showed only the UI); later, the submitting thread waiting for the GPU before each such draw (36–54 fps in Kamura Village on an iPhone). MIO also reported missing level geometry with maxima of 4,594 and 8,192 draws. → [Indirect-count multi-draws](../reference/rendering.md#indirect-count-multi-draws) - a hitch of a second or more as a level opens: a few frames of 330–540 ms whose submission takes 2–3 times its CPU time, and the wait ledger (`DM_NVN_WAITS=1`) shows thousands of indirect-count multi-draw waits for those frames only. → [CPU reads after a drain wait only for later writes](../reference/rendering.md#cpu-reads-after-a-drain-wait-only-for-later-writes) - a black screen while the frame loop runs at full rate, with `[RED] NVN unimplemented function called: nvnCommandBufferDrawTexture`; once drawn, the picture alternates frame by frame between the right image and another texture's (a solid colour, a still image). → [`nvnCommandBufferDrawTexture`](../reference/rendering.md#nvncommandbufferdrawtexture) - the HUD and sky render but the battle's characters and terrain are absent; the replay logs `draw skipped: rasterizer discard` between model draws. → [Rasterizer discard preserves vertex storage writes](../reference/rendering.md#rasterizer-discard-preserves-vertex-storage-writes) - exploding meshes and displaced model parts after vertex-only work; native post-vertex captures can contain valid positions for some meshes while other palettes are incorrect. → [Primitive barriers order vertex storage writes](../reference/rendering.md#primitive-barriers-order-vertex-storage-writes) - a character's mesh stretched for one frame into a long wedge or sheet that reaches another character, and other characters missing in that frame; intermittent (about one frame in a hundred near a group of characters). A pass dump shows `barrier bits 0x1 (render pass open)` before vertex-only draws (`fs=-`, `discard=1`) that bind a storage buffer `rw` which the draws before them read `ro`. → [Ordering barriers before a draw that writes](../reference/rendering.md#ordering-barriers-before-a-draw-that-writes) - characters collapsed into one thin spike (vertex streams read from feedback buffers that were never written); a character covered by a solid box while it moves (its fur shells pulled toward lagged positions that were never written); a pass dump shows draws with a vertex shader and no fragment shader (`fs=-`) before the draws that read them, and `Y tf begin … written 0/0/0/0` with no `T … tf capture` line. → [Transform feedback captured by a vertex entry point](../reference/rendering.md#transform-feedback-captured-by-a-vertex-entry-point) - a scene drawn with a geometry shader per mesh runs at 5 to 15 fps on the Mac, with the submitting thread or the GPU taking most of the frame. → [Geometry-shader draws encoded a run at a time](../reference/rendering.md#geometry-shader-draws-encoded-a-run-at-a-time) - `SIGSEGV` in `-[AGXG18GFamilyComputeContext_mtlnext performEndEncoding]` (from `rp_begin_ex_`, or in its `dealloc` on the encoding thread); Metal validation (`MTL_DEBUG_LAYER=1 MTL_DEBUG_LAYER_ERROR_MODE=nslog`) names it: "Command buffer already has an open command encoder". → [Helper encoders end the open copy encoder first](../reference/rendering.md#helper-encoders-end-the-open-copy-encoder-first) - the whole picture upside down (Absolum's title logo and "Press Any Button" mirrored top to bottom); a red-reporting stub for `nvnCommandBufferSetViewportSwizzles`. → [Viewport swizzles applied as a flipped viewport](../reference/rendering.md#viewport-swizzles-applied-as-a-flipped-viewport) - on an Unreal Engine game with a full GPU, moving sprites flicker black for a frame: cut straight across, or a whole silhouette in the sprite's outline. It follows GPU time against the frame budget, and goes away at 30 fps or with GPU time to spare. The black is already in the scene colour the base pass writes. → [Black shapes on sprites when Unreal's GPU work runs late](../reference/rendering.md#black-shapes-on-sprites-when-unreals-gpu-work-runs-late) - a `sample` of the submit thread shows `ubo_read` calling `-[MTLBuffer contents]` with `objc_retainAutorelease` at every handle read, and `objc_autoreleasePoolPop` at commit draining those buffers. Fire Emblem Fortune's Weave: about 4 % of the submit thread in the reads and as much again in the drain. → [Bindless handles read from guest memory directly](../reference/rendering.md#bindless-handles-read-from-guest-memory-directly) - `[RED] texture→texture copy case not implemented: 1920x1080x1→1920x1080x1 flags 0 format 260→252 3D 0→0`. → [Depth plane copies between depth formats](../reference/rendering.md#depth-plane-copies-between-depth-formats) - `FATAL deferred encoding: DmRecEnc has no stand-in for -copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:` with Metal encoding on its own thread (`DM_NVN_ENC_THREAD=1`, the default on iOS), at the first depth plane copy. → [Depth plane copies on the encode thread](../reference/rendering.md#depth-plane-copies-on-the-encode-thread) - a scene opens near white and fades to its normal colours over several seconds, at each scene change, while the settled picture is right. → [Pending clears land before a compute dispatch](../reference/rendering.md#pending-clears-land-before-a-compute-dispatch) - a regular lattice of dots over the ground, and the light wrong: three of four layers of an interleaved ambient occlusion array stay empty, while the draws and their bindings look right. → [`[[primitive_id]]` in a specialized Metal 4 pipeline](../reference/rendering.md#primitive_id-in-a-specialized-metal-4-pipeline) - with Metal 4 pipelines on (`DM_PSO_MTL4=1`), the iOS app crashes before its first frame, right after `pipeline prewarm list … lines`: `CRASH sig=11 pc=objc_release+0x10`, `bt: objc_autoreleasePoolPop warm_task __warm_prepare_block_invoke`, on several prepare workers at once. The Mac runs the same pipelines. → [A specialization descriptor iOS 26.0 returns autoreleased](../reference/rendering.md#a-specialization-descriptor-ios-260-returns-autoreleased) - a Switch 2 game calls `nvnCommandBufferEvaluateDlss` and its builder functions, which the host did not have. → [NVN2's DLSS on MetalFX](../reference/rendering.md#nvn2s-dlss-on-metalfx) - `[RED] NVN unimplemented function called: nvnDlssNetworkResize (x0=… x1=0x300 x2=0x1b0)` at the title. → [The DLSS network resized](../reference/rendering.md#the-dlss-network-resized) - a Switch 2 game's frame in its heavy scenes is dominated by one compute dispatch between the render-resolution passes and the output-resolution ones: Donkey Kong Bananza's upscaler takes 3.5-5 ms of a 24 ms GPU frame on an M1 in handheld mode (960x540 → 1920x1080, `DM_NVN_GPUPROF`), and the game cannot reach its 60 fps interval there. → [A game's own upscaler drawn by MetalFX](../reference/rendering.md#a-games-own-upscaler-drawn-by-metalfx) - with `DM_UPSCALER=metalfx`, a game's picture is washed out wherever it upscales: lifted shadows and low contrast, the scene only, with the UI drawn after it correct; with `DM_UPSCALER=game`, or at a size the game does not upscale, it is right. → [An upscaler's colour read from its code](../reference/rendering.md#an-upscalers-colour-read-from-its-code) - tall blue / textured panels that flickered frame to frame: the fountain's vertex shader pushed the water surface to the top of the screen. → [Metal 4 does not order operations inside one encoder](../reference/rendering.md#metal-4-does-not-order-operations-inside-one-encoder) - a buffer copy, inline update or fill completes, but a following copy through another Metal buffer over the same allocation reads stale bytes. → [Buffer copies through aliased Metal addresses](../reference/rendering.md#buffer-copies-through-aliased-metal-addresses) - many render passes with one draw each and high submit time: Metroid Dread's cutscene frames had about 180 passes with one draw each (about 5 ms of submit time per frame on the Mac). → [Inline uniform updates inside a render pass](../reference/rendering.md#inline-uniform-updates-inside-a-render-pass) - hundreds of render passes a frame and heavy attachment traffic when a game updates a small part of a large uniform block before each draw group. → [Partial-cover uniform shadows keep passes open](../reference/rendering.md#partial-cover-uniform-shadows-keep-passes-open) - a scene runs at 20–27 fps where similar ones hold 60, with the GPU time about three times its usual (draw counts unchanged). The `residency set` line shows `passes ended to land them for a read` in the tens of thousands, every one `refused … other GPU writes`, and about three times the usual `load-all store-all passes`. A burst of 1,200 such refusals at each world load is the short form. → [A storage buffer bound with size 0 counted as a write anywhere](../reference/rendering.md#a-storage-buffer-bound-with-size-0-counted-as-a-write-anywhere) - the `residency set` line shows `passes ended to land them for a read` in the tens of thousands, every one `refused … earlier submission running`. The slower the GPU, the more passes, and each pass makes it slower: a scene stays at a very low frame rate once it falls in. → [Inline updates of a running submission refused uniform shadows](../reference/rendering.md#inline-updates-of-a-running-submission-refused-uniform-shadows) - `stage 0 cb5 has no uniform buffer bound` (or another stage and slot, such as `stage 0 cb0`), once per run. → [An unbound uniform slot reads the zero bank](../reference/rendering.md#an-unbound-uniform-slot-reads-the-zero-bank) - GPU time per frame doubles with many small dispatches (Age of Calamity: GPU 9 → 18 ms a frame on the Mac; the iPhone's 15 → 51 ms, 17 fps). → [Compute dispatches share the copy encoder](../reference/rendering.md#compute-dispatches-share-the-copy-encoder) - dialog boxes with holes the size of their text, and white specks where text faded. → [Fragment-ordering barriers between draws that write images](../reference/rendering.md#fragment-ordering-barriers-between-draws-that-write-images) - a texture copied from a staging buffer shows another texture's blocks (Catherine: Full Body's cutscene subtitle band a hard-edged dark box with a magenta stroke through it). → [A segment committed after a buffer → texture copy](../reference/rendering.md#a-segment-committed-after-a-buffer--texture-copy) - a scaled texture copy skipped with a red line (Metal blits cannot scale); format-changing, depth-stencil and mirrored copies. → [Copies a blit cannot do, drawn](../reference/rendering.md#copies-a-blit-cannot-do-drawn) - `[RED] Downsample case not implemented: 320x176 1 samples format 70 → 80x48`; a missing bloom. → [`Downsample` of a single-sample texture](../reference/rendering.md#downsample-of-a-single-sample-texture) - no ambient occlusion (Mac); on a device the result depends on whatever that memory holds. → [Depth-stencil copies carry the stencil](../reference/rendering.md#depth-stencil-copies-carry-the-stencil) - `DM_NVN_GPUPROF=every:1` prints no per-frame reports and fills its timestamp heap across frames. → [Periodic GPU profiles close at frame boundaries](../reference/rendering.md#periodic-gpu-profiles-close-at-frame-boundaries) - with `DM_NVN_GPUPROF`, the host aborts minutes in on `-[AGXG16XFamilyComputeContext_mtlnext writeTimestampWithGranularity:afterStage:intoHeap:atIndex:]: unrecognized selector`, `up_flush` on the stack; or a profiled render pass with a wrong GPU time. → [GPU profiles stamp only the encoder they began](../reference/rendering.md#gpu-profiles-stamp-only-the-encoder-they-began) - the 3D scene black (targets cleared again before they are read); `[RED] SetRenderEnableConditional: the host draws anyway`; with a game that skips clears under render conditions, scenes black behind the HUD (Mario vs. Donkey Kong's levels, 1.0.1). → [Conditional rendering evaluated at replay](../reference/rendering.md#conditional-rendering-evaluated-at-replay) - with `render_cond`, a 3D scene black or missing behind the HUD, only in scenes with many occlusion queries; a pass dump shows conditions reading `values 1 / 0` on a record a report of the same submission has just written, and clear-only passes on targets just drawn to. Scenes with fewer queries are fine. → [Report tables that dropped entries](../reference/rendering.md#report-tables-that-dropped-entries) - `[RED] visibility slots exhausted`. → [Query slots running out inside a pass](../reference/rendering.md#query-slots-running-out-inside-a-pass) - no SPIR-V file in the RomFS; SPIRV-Cross refuses a module with "Struct member does not have ArrayStride set". → [Vulkan shaders generated at run time](../reference/rendering.md#vulkan-shaders-generated-at-run-time) - a crash in `bind_res` reading a freed view's texture (Super Mario Galaxy 2 on an iPhone, element 1 of the 8-texture array, when the ship took off after the first galaxy; GitHub issue 68). → [Descriptors hold the Metal objects they were written with](../reference/rendering.md#descriptors-hold-the-metal-objects-they-were-written-with) - Metal refuses a pipeline with "Fragment shader does not write to render target color(0), index(1) that is required for blending"; the Metal 4 specialization path can instead abort after `MTLCompilerService` crashes in `AGCLLVMStatelessFragmentObject::buildBlendFactor`. → [An unwritten secondary blend source](../reference/rendering.md#an-unwritten-secondary-blend-source) - the host aborts on Metal's compiler queue (`findOrCreateComputeFastClearPipeline`, `[AGX] Failed assertion "error == MTLCompilerErrorNoError"`) seconds into the game, with or without the pipeline prebuild, while `MTLCompilerService` crash reports show `EXC_BAD_ACCESS` in `llvm::ExtractElementInst` under `AGCLLVMStatelessFragmentObject::buildBlendFactor` (`AGCLLVMStatelessPSODynamicLibrary::compile`). → [A written secondary blend source (NVN dual-source blending)](../reference/rendering.md#a-written-secondary-blend-source-nvn-dual-source-blending) - adding a pixel shader to the profile's `dual_want.tsv` leaves the build reporting cache hits, the reflection without `entry_d`, and the host logging `[RED] shader ... has no dual-source entry point`. → [A shader added to `dual_want.tsv` keeps its cached build](../reference/rendering.md#a-shader-added-to-dual_wanttsv-keeps-its-cached-build) - Metal refuses the pipeline: "Fragment shader does not write to render target color(0), index(1)". → [Dual-source blending from output location 1](../reference/rendering.md#dual-source-blending-from-output-location-1) - Metal's validation aborts on a buffer layout no mapped attribute uses. → [Scaled and three-component vertex formats](../reference/rendering.md#scaled-and-three-component-vertex-formats) - menus 1.5x too big in handheld mode (the file-creation dialog cut off at the right edge). → [Viewport and scissor persist across render passes](../reference/rendering.md#viewport-and-scissor-persist-across-render-passes) - `draw outside a render pass`; the rest of the pass was dropped. → [Copies inside a render pass](../reference/rendering.md#copies-inside-a-render-pass) - an assert (a stripped trap, `main+0x4d26e0`) when the surface does not list `preTransform` INHERIT. → [Swapchain pre-transform and layer crop](../reference/rendering.md#swapchain-pre-transform-and-layer-crop) - a pipeline with no Metal pipeline state, and its draws missing. → [Specialization constants](../reference/rendering.md#specialization-constants) - a crash in `set_free` from `vkFreeDescriptorSets` as a game leaves. → [What a game tears down that it should not](../reference/rendering.md#what-a-game-tears-down-that-it-should-not) - `[RED] occlusion query outside a render pass or past the buffer`; a query's result stays 0. → [Occlusion queries that span render encoders](../reference/rendering.md#occlusion-queries-that-span-render-encoders) - a call to address 0 at boot. → [`VK_EXT_debug_report`](../reference/rendering.md#vk_ext_debug_report) - GX points and lines drawn as one-pixel points and lines. → [Not translated in the Vulkan layer: geometry shaders](../reference/rendering.md#not-translated-in-the-vulkan-layer-geometry-shaders) - `UNIMPL eglGetDisplay`, then `Break` right after `nv::InitializeGraphics` and `vi::OpenDefaultDisplay` (`main+0x5ed9d0`). → [Games that render with desktop OpenGL through EGL](../reference/rendering.md#games-that-render-with-desktop-opengl-through-egl) - the app closes with no message of its own, `[dm] CRASH sig=11 addr=0 pc=0` and a guest return address inside `main` (Well Dweller: `lr=main+0x3409a78`, the same address every time); `DM_GL_STUBS=1` then names the call: `[RED] glFlush called: not implemented, returns 0`. → [`glFlush` hands the frame so far to the GPU](../reference/rendering.md#glflush-hands-the-frame-so-far-to-the-gpu) - `UNIMPL glCreateShader` returns 0, followed by `UNIMPL glShaderSource`, `glCompileShader`, `glGetShaderiv` and `glGetShaderInfoLog`; the game crashes in `sdk` with a null shader handle even though EGL initialized. → [Direct GL imports use the same implementations as the loader](../reference/rendering.md#direct-gl-imports-use-the-same-implementations-as-the-loader) - the NSP script's provisional profile said Vulkan, and the capture boot crashed in the GL layer. → [Telling a GL game from an NVN or Vulkan one](../reference/rendering.md#telling-a-gl-game-from-an-nvn-or-vulkan-one) - the game draws thousands of vertices per frame and the window shows text only; a sprite scene is black while its text layer is perfect. → [Draws from client memory](../reference/rendering.md#draws-from-client-memory) - the NSP script took the game for an OpenGL one (`main imports EGL and names glShaderSource`), the GL shader capture found no shader, and the capture boot stopped with `[nvn-mtl] FATAL cannot read the shader map` from `h_nvnQueueSubmitCommands` called in an NRO (`nro8+0xc10d0`). → [NVN in NROs under an SDL main that names GL](../reference/rendering.md#nvn-in-nros-under-an-sdl-main-that-names-gl) - the NSP script took the game for an OpenGL one (`main imports EGL and names glShaderSource`) and translated 2 GL shaders; the game boots with sound and answers input, but the window stays black, and the log has `[nvn-mtl] [RED] shader … is not in the shader map` for every shader it makes, with no EGL call at all. → [NVN and its own GLSLC under a main that also links EGL](../reference/rendering.md#nvn-and-its-own-glslc-under-a-main-that-also-links-egl) - a jump to address 0 right after `glGetFloatv(0xb12)` (`lr=main+0x2d58c4`). → [Which GL functions a game calls](../reference/rendering.md#which-gl-functions-a-game-calls) - in a capture run every program links with no uniforms; the game's first `Shader:send` raises a Lua error and, on the Switch, its error handler quits (Any Lua error quits a LÖVE game). → [GL shaders put together at run time and captured](../reference/rendering.md#gl-shaders-put-together-at-run-time-and-captured) - an image-only fragment draw's writes disappear from the subresource also bound as its color attachment when the pass ends; other image layers retain their writes. → [Image stores into an attachment of their own pass](../reference/rendering.md#image-stores-into-an-attachment-of-their-own-pass) - read-only depth/stencil attachments are written back after every pass, and the periodic unwritten-store savings counter remains zero with the default configuration. → [Unwritten attachment stores without lookahead](../reference/rendering.md#unwritten-attachment-stores-without-lookahead) - portrait gameplay overlaps the touch controls, touch coordinates land outside the game picture, or a TV's picture renders at 4K again after a layout pass. → [iOS layouts: portrait, a half-folded Duo, iPad windows](../reference/rendering.md#ios-layouts-portrait-a-half-folded-duo-ipad-windows) - with *Picture shape* at 1.43:1 (`DM_SCREEN_ASPECT`) the game renders 1920x1344, but on an iPhone Duo in Fit (the default) the picture comes out smaller than the 16:9 one, with black bars on all four sides; it fills the screen only in Fill. On the Mac a click lands off the point under the pointer (it was mapped on a 16:9 rectangle of the window). → [The picture laid out in the shape the game presents](../reference/rendering.md#the-picture-laid-out-in-the-shape-the-game-presents) ## Shaders - the split finds no shaders, and the RomFS is one huge file with a short name (`42`) whose bytes look random past a table at its start (magic `CRA.`). → [One scrambled archive indexed by the NRO](../reference/shaders.md#one-scrambled-archive-indexed-by-the-nro) - the split finds only a small part of a game's shaders, with no `[RED]` line, and its RomFS holds files that start `NARC` (`.narc`, `.nptl`, `.ntex` on Mario Tennis Aces). → [Packed shader banks in loose NARC files](../reference/shaders.md#packed-shader-banks-in-loose-narc-files) - the split finds no shaders in `main` or RomFS, while reporting control sections in `main` with no code area. The game has `.sp4` resources and loose `.nvnbin` files rather than BNSH archives or whole GLSLC outputs. → [Sumo Ninty_NX shaders and MuxFDMR streams](../reference/shaders.md#sumo-ninty_nx-shaders-and-muxfdmr-streams) - the shader split finds no game programs despite loose `.fx.phyre` effects and multi-GB `.vbf` archives. → [Phyre NVN effects in Virtuos VBF archives](../reference/shaders.md#phyre-nvn-effects-in-virtuos-vbf-archives) - the shader split stops on one archive with a Python traceback (an `IndexError` or `struct.error` naming no file), or a reader's `[RED]` line about a format it does not know, and nothing is written; the NSP script loses the build at the split. → [A file no reader reads](../reference/shaders.md#a-file-no-reader-reads) - a black screen after the loading text; the split prints `[RED] /init.dict: the index (… header 04 04 03 00 …) is not in the layout of Luigi's Mansion 3's archives` for 878 of 879 archives and keeps only the 40 shaders of `main`, and the run prints `[RED] shader … is not in the shader map` for the programs the game draws with. → [Next Level Games archives of revision 4](../reference/shaders.md#next-level-games-archives-of-revision-4) - the split leaves out archives whose members do not overlap: `[RED] <file>/<member>.szs/#7: the archive members add up to more than 16 times the file (members that overlap)`, then `[RED] <n> file(s) could not be read`, and a registered profile's build stops there. → [A Yaz0 member that expands is not overlap](../reference/shaders.md#a-yaz0-member-that-expands-is-not-overlap) - `shader_split.py` finds 0 shaders in a RomFS of zstd files named `.zst`. → [Zstd files recognised by their magic](../reference/shaders.md#zstd-files-recognised-by-their-magic) - the game asks for shaders the map does not have (`[RED] shader ... is not in the shader map`, hundreds of lines), and the split finds far fewer shaders than the game uses (121 against 27,288 on Kirby and the Forgotten Land). → [HAL's `.cmp` containers: a size-prefixed frame](../reference/shaders.md#hals-cmp-containers-a-size-prefixed-frame) - the split finds almost no shaders and reports `[RED] /Archive/<name>.bea: entry 0 @0x4854535341 is not an ASST entry (its shaders are left out)` for every archive (`… file(s) could not be read`); the "offset" is the bytes `ASSTH`. → [Bezel Engine 2.9 archives keep their entries inline](../reference/shaders.md#bezel-engine-29-archives-keep-their-entries-inline) - a provisional split finds only a fraction of the shaders (3,126 of Pokémon Sword's 41,516). → [BNSH entries of GFPAK archives](../reference/shaders.md#bnsh-entries-of-gfpak-archives) - the split counts hundreds of files as unreadable (678 on Pokémon Legends: Arceus), each with `[RED] <file>.gfpak: entry 0 has compression 3 (Oodle), which this reader does not decode`, and leaves their shaders out. → [Oodle entries of GFPAK archives](../reference/shaders.md#oodle-entries-of-gfpak-archives) - the split found no shader in the game (0 shaders). → [GLSLC outputs holding several stages](../reference/shaders.md#glslc-outputs-holding-several-stages) - an NVN game's split finds none of its shipped shaders, and the ones it compiles at run time were not captured: the game's renderer is in NROs that call `glslcCompile`, and its whole RomFS is one zip. → [GLSLC outputs in a zip archive, and those NROs compile at run time](../reference/shaders.md#glslc-outputs-in-a-zip-archive-and-those-nros-compile-at-run-time) - a Switch 2 game whose split finds no shader: the RomFS holds `Asset/assets_a000.dat` (magic `PDAT`, 16.6 GB) and `Asset/assets.cat` (magic `PARC`, a table of 64-bit ID hashes), and the first boot stops on `cannot read the shader map`. → [PMAP records in phx's PDAT archives](../reference/shaders.md#pmap-records-in-phxs-pdat-archives) - a Switch 2 game's RomFS is one `data.zip` that does not start with a zip's local header, zipfile reads a member of it only to stop on `Bad CRC-32`, and the split finds no shader: every member is listed as stored, yet most are smaller on disk than their file size. → [LZ4-chained zip members behind a VZIP preamble, and shader binaries of one stage](../reference/shaders.md#lz4-chained-zip-members-behind-a-vzip-preamble-and-shader-binaries-of-one-stage) - an NVN game's split finds a few dozen shaders (`main`'s and a loose file's) and the screen stays black but for the loading indicator, with `[RED] shader … is not in the shader map` and `program has no vertex shader`; the RomFS holds `.BNDL` files that start with `bnd2`. → [GLSLC outputs in Criterion's Bundle 2 resources](../reference/shaders.md#glslc-outputs-in-criterions-bundle-2-resources) - 24 shaders before the control-length fix, 1,355 after. → [SPKG packages in KTGL LINKDATA](../reference/shaders.md#spkg-packages-in-ktgl-linkdata) - the split finds almost none of a KTGL Switch 2 game's shaders: the G2S containers in its RDB entries yield nothing, and its programs name no packaged shader. → [KTGL on NVN2: Switch 2 GLSLC outputs and LD_ / LI_ LINKDATA](../reference/shaders.md#ktgl-on-nvn2-switch-2-glslc-outputs-and-ld_--li_-linkdata) - the NSP script stops at `the shader split found no shaders in main or the RomFS` on a game whose `main` imports `glslcCompile` and whose RomFS is one or two `.pak` files. → [GLSLC outputs in base64 in Heaps' shader cache](../reference/shaders.md#glslc-outputs-in-base64-in-heaps-shader-cache) - only movies render, while the 3D scene reports missing shaders and programs without a vertex stage; the shader split finds loose programs but misses those in `Shaders/Shaders.arc.gz`. → [Gzip-wrapped shader archives](../reference/shaders.md#gzip-wrapped-shader-archives) - the NSP script stops at its GLSLC capture with `captured only 0 run-time shaders`, after the game ran the whole capture normally, on a game whose `main` imports `glslcCompile`, with a `.vert` or `.frag` file in its RomFS. → [Encrypted `.vert` and `.frag` files are no run-time GLSL](../reference/shaders.md#encrypted-vert-and-frag-files-are-no-run-time-glsl) - every frame black, the title screen included, while the game runs at full rate and draws (about 19,000 NVN calls a frame), with `[RED] shader … is not in the shader map` (26 keys in the first minute) and `program has no vertex shader`; the dumped shaders (`DM_NVN_SHDUMP`) match no file byte for byte, and some differ from a split shader only in the control section's compile information (+0x7d0), which is a sign of another GLSLC compile of the same source, not of a shared section. → [Gust's chunked zlib `.gz` files](../reference/shaders.md#gusts-chunked-zlib-gz-files) - the split finds no shaders in a RomFS made of `.sdfdata`, `.sdftoc` and `.sdfver` files. → [Shader records in Snowdrop SDF data slices](../reference/shaders.md#shader-records-in-snowdrop-sdf-data-slices) - the survey finds no shader container in a RomFS of `.toc` and `.cas` files (`Data/NX`, `Patch/NX`, `Data/layout.toc`, `Data/initfs_NX`); the split reads every file loosely and finds nothing. → [CompiledBytecode resources in Frostbite superbundles](../reference/shaders.md#compiledbytecode-resources-in-frostbite-superbundles) - `[RED] ... PKZ version 0x10000: only 0x20000 is known` stops the shader split. → [PKZ version 1 archives](../reference/shaders.md#pkz-version-1-archives) - the split finds zero shaders and refuses the shader build, although the CPK's DAT archives contain the objects passed to NVN at boot. → [Size-delimited PlatinumGames shader objects](../reference/shaders.md#size-delimited-platinumgames-shader-objects) - archive or loose asset shaders are absent from the map; only boot shaders in `main` are found, sometimes reported as raw controls with no identified code area. → [Monolith ARH1, XBC1 and HCPS/SLCT shader containers](../reference/shaders.md#monolith-arh1-xbc1-and-hcpsslct-shader-containers) - the split finds no shaders, although `main` contains NVN control sections; it reports that no data record or code-address pair identifies their code areas. → [Needle shader containers in main and GFD archives](../reference/shaders.md#needle-shader-containers-in-main-and-gfd-archives) - shaders the game draws are missing from the map (`DM_NVN_SHDUMP`), in no RomFS file and no module, stored or LZ4, and not compiled at run time. → [Shaders in a zlib stream in main (YEBIS .tfxo)](../reference/shaders.md#shaders-in-a-zlib-stream-in-main-yebis-tfxo) - two `[RED] shader … is not in the shader map` lines and `program has no vertex shader` as the opening movie starts; every movie drew white. → [Loose control sections and code areas in main (Bink 2)](../reference/shaders.md#loose-control-sections-and-code-areas-in-main-bink-2) - the provisional split finds only `main`'s 294 GLSLC outputs; the 3D scene and the title logo are magenta, with `[RED] shader … is not in the shader map` lines. → [SNVN program records in Retro Studios' RFRM forms](../reference/shaders.md#snvn-program-records-in-retro-studios-rfrm-forms) - the NSP script's split stops with `[RED] 24 file(s) could not be read`, each `an XNB effect without an MGFX version 8 effect of NVN shaders`. → [MGFX version 5 effects (MonoGame 3.0)](../reference/shaders.md#mgfx-version-5-effects-monogame-30) - `[RED] 1 file(s) could not be read, their shaders are left out (first: Data/resources.assets: error: unpack_from requires a buffer of at least 96 bytes for unpacking 96 bytes at offset 0 (actual buffer size is 0))` from the shader split, and the game's built-in shaders in that file missing at run time. → [Unity compute kernels with no code](../reference/shaders.md#unity-compute-kernels-with-no-code) - `failed to create render pipeline` with a fragment `user(locn1)` input missing from the vertex output, while the split found all shaders but almost no vertex / pixel pairs. → [Legacy Unity stages lose their pass partners](../reference/shaders.md#legacy-unity-stages-lose-their-pass-partners) - the split stopped with `no bundle has a Shader type tree of the same hash to borrow`. → [Unity Shader layouts written out for players without bundles](../reference/shaders.md#unity-shader-layouts-written-out-for-players-without-bundles) - the 3D battle scene was black behind a correct UI, with `[RED] shader 854a8afc9d07f88d is not in the shader map` and `the dispatched program has no compute shader`. → [Unity ComputeShader objects](../reference/shaders.md#unity-computeshader-objects) - black, jagged holes in the ground of a map (whole tiles of the terrain mesh missing while others draw), with about 25 distinct `[RED] shader … is not in the shader map` keys and `program has no vertex shader`, on a Unity game whose `Shader` objects all split cleanly. → [GLSLC outputs in a Unity TextAsset](../reference/shaders.md#glslc-outputs-in-a-unity-textasset) - `[RED] the shader split found no shaders in main or the RomFS`, the split's log ending in `shaders: 0`, and no `UE shader decode` step, on a game whose container holds shader libraries and whose pak names `GlobalShaderCache-`: from 2026-11-04 until issue #1277 was fixed, such a pak counted as inline. → [Unreal Engine 5.6 IoStore shader libraries](../reference/shaders.md#unreal-engine-56-iostore-shader-libraries) - `ValueError: …/Glow-Switch_0_P.utoc: shader group 0 has no chunk` from `uepak.py io_archive` while the NSP script decodes the shaders (`decode_ue_shaders`, after `[4/8] UE shader decode`). → [IoStore patch containers keep their shader groups in the base container](../reference/shaders.md#iostore-patch-containers-keep-their-shader-groups-in-the-base-container) - `[RED] …/Nicola-Switch_0_P.pak: the index is encrypted and no window of main decrypts it` from the NSP script before `[5/8] UE shader decode` (the message now reads `no key in main (a 32-byte window or two 16-byte literals its code stores together) decrypts it`). → [An Unreal pak key split into two 16-byte literals](../reference/shaders.md#an-unreal-pak-key-split-into-two-16-byte-literals) - `the RomFS has Unreal paks, but none … holds a shader code archive`, then `the shader split found no shaders in main or the RomFS`. → [Unreal Engine 4.27 shaders inline in cooked packages (LZ4)](../reference/shaders.md#unreal-engine-427-shaders-inline-in-cooked-packages-lz4) - `the RomFS has Unreal paks, but none … holds a shader code archive` from the NSP script, on a game with a `.pak` beside a `.utoc` and `.ucas`. → [Unreal Engine 4.27 shaders inline in IoStore export bundles](../reference/shaders.md#unreal-engine-427-shaders-inline-in-iostore-export-bundles) - the shader split reports `the game's decoder in the Mac host failed on a 8 → 30650 byte stream`, the host's output says `asked to decode Legacy compressor; not supported!`, and a run of the NSP script stops with `file(s) could not be read` (a provisional profile goes on without those shaders). → [An entry of a package's export list read as an Oodle shader table](../reference/shaders.md#an-entry-of-a-packages-export-list-read-as-an-oodle-shader-table) - `shaders: 0` from the split, with no red line, on a game whose pak holds `Engine/GlobalShaderCache-SP_GLSL_SAGE.bin` (`Sage` is the engine's name for the platform). → [Unreal Engine 5.4 shaders for the Switch 2](../reference/shaders.md#unreal-engine-54-shaders-for-the-switch-2) - `[RED] the shader split found no shaders in main or the RomFS`; the survey counts the game's Unreal paks, but no `UE shader decode` step runs and the split reads none of them. → [Unreal Engine 4.22 to 4.25 paks (version 8)](../reference/shaders.md#unreal-engine-422-to-425-paks-version-8) - `the shader split found no shaders in main or the RomFS`; the survey lists the RomFS as cooked packages (`.xxx`) and `.usm` movies only. → [Unreal Engine 3 shader caches (Oodle packages)](../reference/shaders.md#unreal-engine-3-shader-caches-oodle-packages) - `[RED] shader <key> is not in the shader map` for shaders whose code is in a `.bfsha` the split reads, `[RED] NVN unimplemented function called: nvnCommandBufferDrawMeshTasksIndirect`, and grass and ferns missing. → [Task and mesh shaders in BNSH, and indirect mesh draws](../reference/shaders.md#task-and-mesh-shaders-in-bnsh-and-indirect-mesh-draws) - a Switch 2 game's picture is far too bright and warm wherever the view opens out: lifted blacks, yellow skin, a pale veil. The build log has `Invalid reduction type: F32FtzRn`, easy to miss among thousands of lines. → [Float atomics in storage memory](../reference/shaders.md#float-atomics-in-storage-memory) - dotted horizontal rows in blocks of the picture, in smooth and blurred areas, from a Switch 2 game's upscaler: the frame before it is clean and the frame after it is not. The same input gives a different picture each run. Bright scenes show more of them. → [textureGatherOffsets and a loop over its offsets](../reference/shaders.md#texturegatheroffsets-and-a-loop-over-its-offsets) - `Ampere instruction 243 at 0x… is not implemented`, or `ISBERD mode b8 in a task or mesh shader`, in the build. → [F2IP](../reference/shaders.md#f2ip) - when an AV1 movie starts, `[RED] shader <key> is not in the shader map` for 11 compute shaders and `[RED] the dispatched program has no compute shader (or it is not mapped)`. → [`nn::ndve`'s movie enhancement file](../reference/shaders.md#nnndves-movie-enhancement-file) - `draw skipped: no render pipeline (vertex - fragment -)` in a game's final passes; shaders "not in the shader map", all from `agl_ndsr.pck`. → [The NDSR pack's record start](../reference/shaders.md#the-ndsr-packs-record-start) - shaders reported missing at random, and their dumped control sections are garbage (Unity). → [Program keys computed inside `nvnProgramSetShaders`](../reference/shaders.md#program-keys-computed-inside-nvnprogramsetshaders) - `[RED] shader … is not in the shader map` for shaders whose control section and code area are both in the game files, but in different records: dumped (`DM_NVN_SHDUMP`), the control section is one record's and the code area another's. → [Control sections shared among shaders that differ only in their compile information](../reference/shaders.md#control-sections-shared-among-shaders-that-differ-only-in-their-compile-information) - 12 compute shaders (particles, post effects) translated into an endless loop that hung the GPU at the first gameplay scene; SPIRV-Cross failed on 7 shaders instead of 2 (SPIRV-Cross parse failures). → [Exact program start for the decoder](../reference/shaders.md#exact-program-start-for-the-decoder) - GLSLC outputs fail the reader's check and are dropped (44 of DARK SOULS: REMASTERED's `main`'s 72 outputs and most of its archives' pixel shaders). → [GLSLC outputs read through their section headers](../reference/shaders.md#glslc-outputs-read-through-their-section-headers) - `shader_split.py` finds no stage for vertex shaders and stops at the first captured output (`no GLSLC output`). Translated, every post pass and the window draw one texel's colour (a black screen with sound); every varying at (0, 0, 0, 1). → [VertexA and VertexB parts merged into one vertex shader](../reference/shaders.md#vertexa-and-vertexb-parts-merged-into-one-vertex-shader) - a shader build accepts tools that differ from `dmsh_chain.lock`; after an override build, returning to the tested Metal compiler can still restore the override's libraries. → [Tested tools and compiler-specific shader caches](../reference/shaders.md#tested-tools-and-compiler-specific-shader-caches) - after an Xcode update the build stops with `[RED] this Mac's Metal compiler is not the one the shaders were tested with (dm/gfx/tools/dmsh_chain.lock): metal_macosx Apple metal version 32023.922 …`; `xcodebuild -downloadComponent MetalToolchain`, as the message said, downloads the same untested compiler again. → [Metal compiler of a newer Xcode](../reference/shaders.md#metal-compiler-of-a-newer-xcode) - `regress.py` waits for other jobs to end while the only reported jobs are sleeping `MSBuild.dll /nodemode:1 /nodeReuse:true` workers using 0% CPU. → [Idle MSBuild workers block regression measurements](../reference/shaders.md#idle-msbuild-workers-block-regression-measurements) - SPIRV-Cross can't parse the SPIR-V (`nullptr` exception). → [SPIRV-Cross parse failures](../reference/shaders.md#spirv-cross-parse-failures) - `Fragment input(s) user(locnN) mismatching vertex shader output type(s) or not written by vertex shader` and the draw is skipped; the host reports `[RED] failed to create render pipeline (vertex … fragment …)`. Offline packing fails with `pso_offline: metal-tt failed` for the same reason. → [Pixel shader inputs the vertex shader does not write](../reference/shaders.md#pixel-shader-inputs-the-vertex-shader-does-not-write) - outdoors dim and nothing casts a sun shadow (every shadow-map lookup fails). → [Unwritten components of a written output start as (0, 0, 0, 1)](../reference/shaders.md#unwritten-components-of-a-written-output-start-as-0-0-0-1) - rows of dark dots along contour lines of alpha-tested surfaces drawn after a depth pre-pass (Tears of the Kingdom: the stone lattice in front of the Great Sky Island start, as reported by MacNativeGames ae8f4f4; not reproduced here). → [Early fragment tests from the control section](../reference/shaders.md#early-fragment-tests-from-the-control-section) - a simulation or filter that reads neighbouring texels misbehaves though every constant is right. In the translated MSL a variable is declared with no value and read at once (`int _139; int _141 = _139;`), used as a coordinate. On Ocarina of Time: grass whose blades shift at 10 Hz, with a 6-frame cycle in the depth buffer and a wind velocity texture of strong stripes. → [Dead-code removal dropped a coordinate of a multi-output instruction](../reference/shaders.md#dead-code-removal-dropped-a-coordinate-of-a-multi-output-instruction) - the ground kept stale 32×32 blocks where the G-buffer draw failed the depth test: blocks of a stale image where a depth pre-pass and a later pass with other vertex shaders meet (Odyssey: 32×32 blocks on every fourth frame). → [Position invariance across shaders](../reference/shaders.md#position-invariance-across-shaders) - making a pipeline archive prints `Max Unstruct ID 758 in function agc.main in shader 13941 exceeds supported limit`, and one pipeline takes many minutes, in `metal-tt` offline or in the host's prebuild on the device (`Preparing pipelines` holding one count for minutes). The line is a note, not an error: `metal-tt` goes on, exits 0 and writes that pipeline into the archive. → [Front end at -O1: Apple's control-flow lowering](../reference/shaders.md#front-end-at--o1-apples-control-flow-lowering) - the half of Mario facing the camera's left was white (GitHub issue 72, on an iPhone). → [min, max and clamp with a NaN operand](../reference/shaders.md#min-max-and-clamp-with-a-nan-operand) - a pipeline red line for a float output meeting an integer attachment (the red line prints the row to add); a BC encoder's pipeline fails. → [Integer fragment outputs declared by hand](../reference/shaders.md#integer-fragment-outputs-declared-by-hand) - `failed to create render pipeline … output of type float4 is not compatible with a MTLPixelFormatR32Uint color attachment` (or `MTLPixelFormatRGBA16Uint`); every draw into the target skipped. → [Integer entry points for integer colour outputs](../reference/shaders.md#integer-entry-points-for-integer-colour-outputs) - a deferred scene with part of its materials unlit or black: grass, ground and trees dark while wood and characters look right, whole areas of a map black. There may be no red line. A texture dump shows an integer G-buffer target (`fmt=73`, RGBA8Uint) holding only zeros, and the lighting pass reads it. Since this entry, `[RED] shader … writes colour target …, an integer format, as a float`. → [Integer outputs told from float bits](../reference/shaders.md#integer-outputs-told-from-float-bits) - `failed to create render pipeline … Cannot convert attribute …`; draws missing (a pipeline that fails to build). → [Integer-typed vertex inputs fed normalized formats](../reference/shaders.md#integer-typed-vertex-inputs-fed-normalized-formats) - outdoors the whole screen blurred (depth of field out of focus everywhere). → [Depth mode near = 0 needs the per-mode entry points](../reference/shaders.md#depth-mode-near--0-needs-the-per-mode-entry-points) - `SPIRV-Cross threw an exception: Subgroup builtins are not available in this type of function`. → [Subgroup operations rewritten for a one-lane subgroup](../reference/shaders.md#subgroup-operations-rewritten-for-a-one-lane-subgroup) - the tone mapper read an empty LUT and the screen came out a flat blue. → [Geometry shaders that only pick the layer](../reference/shaders.md#geometry-shaders-that-only-pick-the-layer) - `[RED] NVN unimplemented function called: nvnCommandBufferDrawMeshTasks`, and a build that fails with `Ampere instruction 927 ... is not implemented` in shaders the map calls vertex or domain; what they draw is missing. → [NVN2 task and mesh shaders](../reference/shaders.md#nvn2-task-and-mesh-shaders) - large flat panels in front of the sky, the clouds behind them blinking at times, in some places and not others. In a `DM_NVN_PASSDUMP_ALL` dump every task and mesh shader's storage buffer shows as `st3` / `st4 sbufp reg6` or `reg7` `dummy addr=0 size=0`, though the game binds buffers for those stages. → [Task and mesh draws reading the dummy buffer](../reference/shaders.md#task-and-mesh-draws-reading-the-dummy-buffer) - a geometry shader fails to compile with `unknown main0_out`: SPIRV-Cross writes `unknown main0_out main0()` for the geometry stage, and the shader does not build. → [Geometry shaders with no Metal stage](../reference/shaders.md#geometry-shaders-with-no-metal-stage) - the models a passthrough geometry shader draws are missing: its own draw (a depth prepass) shows nothing, and so do the draws that test against that depth for equality. Before the shader loaded at all, the same models showed as black silhouettes. → [Passthrough geometry shaders](../reference/shaders.md#passthrough-geometry-shaders) - `[geometry failed] missing geometry topology buffer` in the build, then `[RED] shader … (geometry) failed to load` and those draws skipped. → [The topology table passed to a helper function](../reference/shaders.md#the-topology-table-passed-to-a-helper-function) - the host's memory watchdog closes the game (at 28.3 GB on Kirby Air Riders, whose Switch 2 has 9 GB), with the Metal heap full of frame arena blocks of 36 or 72 MB; it comes on quickly in a scene full of ribbons. → [A captured draw's vertex IDs far apart](../reference/shaders.md#a-captured-draws-vertex-ids-far-apart) - geometry reader compilation fails with undeclared `gl_BuiltIn_5253` and a scalar `.elements` access. Compiling only the compute kernel also leaves native passthrough geometry without emitted vertices. → [Geometry passthrough and viewport masks in compute](../reference/shaders.md#geometry-passthrough-and-viewport-masks-in-compute) - sorting repeated mesh indices consumes much of the render thread's CPU time. → [Geometry capture indices deduplicated with a bounded bitset](../reference/shaders.md#geometry-capture-indices-deduplicated-with-a-bounded-bitset) - later geometry uses stale shader-written data or appears in the earlier draw's position when draws are combined into a geometry run. → [Geometry runs retain external buffer dependencies](../reference/shaders.md#geometry-runs-retain-external-buffer-dependencies) - the CPU spends substantial replay time checking dependencies among geometry jobs that share many read-only buffers. → [Geometry dependency checks skip read-only pairs](../reference/shaders.md#geometry-dependency-checks-skip-read-only-pairs) - a game whose frames are mostly geometry-shader draws stays GPU-bound by attachment traffic: a `DM_NVN_GPUPROF` frame shows hundreds of two-draw render passes (each geometry draw, then the reopened pass of its raster) and gigabytes of attachment loads and stores, and no `geometry hoist` line ever appears in the log. → [An empty vertex stream kept every geometry draw out of a run](../reference/shaders.md#an-empty-vertex-stream-kept-every-geometry-draw-out-of-a-run) - geometry-heavy rendering spends substantial GPU time compacting the geometry shader's emitted indices. → [Parallel geometry index compaction](../reference/shaders.md#parallel-geometry-index-compaction) - the geometry kernel compiles, but its `_bgv.metal` vertex reader fails with `use of undeclared identifier 'gl_BuiltIn_5253'` and `member reference base type 'int' is not a structure or union`. → [Geometry reader viewport masks](../reference/shaders.md#geometry-reader-viewport-masks) - a passthrough geometry kernel writes beyond its vertex and raw-index scratch regions, and compaction reads the wrong groups; corruption can reach the following primitive-map buffers without a red diagnostic. → [Passthrough geometry output bounds follow input topology](../reference/shaders.md#passthrough-geometry-output-bounds-follow-input-topology) - a geometry kernel compiles and runs its storage-buffer side effects, but contains no `geometry_vb_output` binding and fills its index stream with restart markers; its following raster pass draws no geometry. → [Passthrough geometry kernels lose raster vertices](../reference/shaders.md#passthrough-geometry-kernels-lose-raster-vertices) - geometry-heavy frames have a large submission wall/CPU gap despite short GPU execution; stack samples spend most of the main thread in `geo_draw` → `mdi_wait` → shared-event wait, with index sorting another substantial cost. → [Geometry capture waits for every indexed draw](../reference/shaders.md#geometry-capture-waits-for-every-indexed-draw) - geometry-heavy frames remain GPU-bound after CPU readback waits are removed; encoder timestamps attribute most compaction time to the offset scan rather than the geometry shader or index writes. → [Geometry compaction serial prefix scan](../reference/shaders.md#geometry-compaction-serial-prefix-scan) - `[RED] geometry draw needs 261 MiB of scratch, above the 256 MiB bound` (or `exceeds the capture or invocation bound`); the draw is skipped. → [Geometry draws above the capture scratch bound](../reference/shaders.md#geometry-draws-above-the-capture-scratch-bound) - a geometry shader that reads `PrimitiveID` repeats its visibility decisions or storage addresses after a large draw is split into compute dispatches. → [Split geometry primitive IDs](../reference/shaders.md#split-geometry-primitive-ids) - a large geometry draw crashes in `geo_split` / `memcpy` while reading indices, sometimes preceded by `geometry draw exceeds the capture or invocation bound` for an unexpectedly small child draw. → [Recursive geometry splits retain their original draw range](../reference/shaders.md#recursive-geometry-splits-retain-their-original-draw-range) - geometry draws with transform feedback report `geometry draw cannot capture this pipeline` and write no feedback records after the geometry-job integration. → [Geometry jobs preserve transform-feedback replay](../reference/shaders.md#geometry-jobs-preserve-transform-feedback-replay) - geometry-heavy frames are GPU-bound on the emulation itself. A `DM_NVN_GPUPROF` frame shows, for every geometry draw, a capture pass (`0x0 0c`), a compute encoder and a one-draw reopening of the game's pass, with most of the frame's GPU time in the first two. → [Passthrough geometry shaders drawn by the vertex shader](../reference/shaders.md#passthrough-geometry-shaders-drawn-by-the-vertex-shader) - a pale blue wash over every 3D scene with atmosphere; the HUD is clean, and the albedo and normal targets are right. A 3D table (`texraw`) has data in plane 0 only, and the pass that fills it has no `L … layered pass` line and draws with `gs=-`. → [A passthrough geometry shader that writes the layer](../reference/shaders.md#a-passthrough-geometry-shader-that-writes-the-layer) - a passthrough geometry shader that uses `PrimitiveID` makes different visibility decisions or storage writes after the first 32 triangles when composed into a mesh shader. → [Mesh geometry primitive IDs restart per group](../reference/shaders.md#mesh-geometry-primitive-ids-restart-per-group) - after a pair is added to `geo_mesh.tsv`, `[RED] geometry mesh pipeline: ... Total mesh size (37248) exceeds the maximum mesh size allowed (32768)`, and the frames that draw the pair get much slower than on the compute path (Donkey Kong Bananza: translation from about 10 to 22–31 ms a frame). → [Mesh geometry groups sized to the vertex output](../reference/shaders.md#mesh-geometry-groups-sized-to-the-vertex-output) - a depth prepass of many small geometry-shader draws, drawn as mesh draws, leaves the GPU nearly idle: the per-pass profile (`DM_NVN_GPUPROF`) shows an idle gap before the pass that grows with its draw count (about 2.3 µs a draw), and the GPU counters show vertex-only time at about 4 % occupancy. → [Mesh geometry draws gathered into one dispatch](../reference/shaders.md#mesh-geometry-draws-gathered-into-one-dispatch) - `primitive type 14 not implemented`; patch draws skipped. → [Tessellation stages are not drawn](../reference/shaders.md#tessellation-stages-are-not-drawn) - a Switch 2 game's shaders do not translate (the translator reads Maxwell: 64-bit instructions behind scheduling words, a 0x50-byte SPH), or, rewritten as Maxwell code, UI text draws as solid boxes or not at all. → [Ampere shader code (Switch 2)](../reference/shaders.md#ampere-shader-code-switch-2) - a lit pass far slower on an M1 than the M4 Pro's figures suggest, the time spread over every material that loops over the scene's lights; dropping one material's draws (`DM_NVN_UB`) saved only its share. → [Storage words read one by one](../reference/shaders.md#storage-words-read-one-by-one) - `reflection conversion failed: B binding cp_i_cb3_0_ has no resolved slot number` at load, then `the dispatched program has no compute shader`; in the build, `SUATOM handle in bank 3` or `SURED handle in bank 3`, and bindings of an unrecognized kind for a typed buffer. Compute passes are skipped. → [Images and buffer textures with their handle in a uniform buffer](../reference/shaders.md#images-and-buffer-textures-with-their-handle-in-a-uniform-buffer) - a scene lit black with correct geometry. In `DM_NVN_PASSDUMP`, the lighting shader's bindings show `tex … tid=0 dummy` where the G-buffer should be, and a sampler bound where a texture is expected. → [Texture and sampler words in either order](../reference/shaders.md#texture-and-sampler-words-in-either-order) - objects from a compute-built list flicker: each is in one of two states, on and off irregularly and independently of the others, while the draws are the same frame to frame and the camera is still. Whole groups may vanish or appear in one frame and stay that way until the list's next rebuild. Shots of consecutive frames show the change per frame jumping between two levels. → [A store only a dispatch's first invocation makes](../reference/shaders.md#a-store-only-a-dispatchs-first-invocation-makes) - `metal` runs for hours on a shader of about 100 MB of MSL, mostly indentation, stuck in LICM (`hoistRegion` → `ScalarEvolution::forgetValue`), then the GPU compiler's connection breaks; even `-O0` and finished libraries crash it. Hundreds of forced one-pass loops nest around the program. → [Goto elimination forcing loops around a whole program](../reference/shaders.md#goto-elimination-forcing-loops-around-a-whole-program) - `BRX with no target`, or code about 20 % larger than it should be. → [Ampere jump tables read past their end](../reference/shaders.md#ampere-jump-tables-read-past-their-end) - `Ampere instruction 308` refused; a neural upscaler's programs missing, so the frame never reaches the window (a black 3D scene). → [MUFU.F16](../reference/shaders.md#mufuf16) - a compute shader's results in shared memory land in the wrong elements, or only part of its memory is cleared. An exposure histogram came back with its bins at about four times their index, the scene several stops too dark. → [Scaled shared memory addresses](../reference/shaders.md#scaled-shared-memory-addresses) - `[RED] failed to create compute pipeline: Threadgroup memory size (49152) exceeds the maximum threadgroup memory allowed (32768)`, thousands a run; the dispatch is skipped. → [Compute shared memory past 32 KB](../reference/shaders.md#compute-shared-memory-past-32-kb) - `[RED] shader <key>_b reflection conversion failed: fetch call 0: frag_pos uniform reference out of range`; the shader does not load and its draws are skipped. → [Uniform references past the first kilobyte](../reference/shaders.md#uniform-references-past-the-first-kilobyte) - the GPU hangs (`kIOGPUCommandBufferCallbackErrorHang`) from the first 3D scene on, or frames of about 88 ms, in a shader with a half-float loop. → [HADD2 and HMUL2 with an immediate](../reference/shaders.md#hadd2-and-hmul2-with-an-immediate) - wrong shading where a shader needs a cross product or a 2D rotation of half pairs; on Eden-NS2, which first read the mode as a plain negation of the high lane, sun and cloud shadows were lost. → [HFMA2 .H0_NH1](../reference/shaders.md#hfma2-h0_nh1) - none in the log: everything drawn with an engine's scene data lands on the first instance's transform, or at nothing. In the MSL, a bounds-checked read has a constant index (`vp_s2._m0[0]`) just after a comparison of the register it should use. → [A guarded load whose destination is its address](../reference/shaders.md#a-guarded-load-whose-destination-is-its-address) - the scene goes white with a yellow fringe: a few objects hold the largest value their target can, and bloom spreads it over the picture. Clamping a shader's terms one by one finds a value that is a register's stale contents. Or characters lit from an environment cube turn bright white in certain places only, and the cube's mean is far above its value elsewhere. → [A deferred write under a false guard](../reference/shaders.md#a-deferred-write-under-a-false-guard) - `Ampere instruction f63` (or `f6c`, `364`, `367`) `is not implemented`, or `SURED form 0310e000`, in the build. → [Ampere forms with a handle in a register, and SURED's other operations](../reference/shaders.md#ampere-forms-with-a-handle-in-a-register-and-sureds-other-operations) - `Ampere instruction 21b at … is not implemented` (`…0405721b`) or `Ampere instruction 925 at 0x0 is not implemented` (`040e0200000e4000 …7925`) in the build. → [Ampere BMSK and the read of a covered pixel](../reference/shaders.md#ampere-bmsk-and-the-read-of-a-covered-pixel) - no wrong picture seen so far. In the MSL, a shader with a 0x886 vote has `if (false)` and `false ? a : b` where a uniform predicate guards a value or a branch, and a lane guard on the same number reads `simd_all` or `simd_any` of its own predicate. → [VOTEU writes the uniform predicate](../reference/shaders.md#voteu-writes-the-uniform-predicate) - `[RED] <key>: the translator deleted N bindless accesses` in the build (Losses a shader build reports; `Failed to find handle source for bindless access` in its reflection's notes), for a shader with TXD through a uniform register (0xf6c). The MSL has no gradient sample, and what it read comes back 0. → [TXD through a uniform register kept no handle](../reference/shaders.md#txd-through-a-uniform-register-kept-no-handle) - `Failed to find handle source for bindless access` in the build's translator notes, for a read whose handle is two words of the game's own uniform buffer, and what it read comes back 0. Or nothing in the log: the read binds `fp_t_cb3_<word>` or `fp_t_cb2_<word>`, a texture word with no sampler word, so its sampler is `samp_tex`'s guess, where the shader's other reads of that word bind both. → [Handles built under a guard the read's guard cannot be tied to](../reference/shaders.md#handles-built-under-a-guard-the-reads-guard-cannot-be-tied-to) - `no member named 'gl_PointSize' in 'main0l_out'` and `does not compile` in the build, which still exits 0, then `[RED] <key>: its library builds only without its layer entry points` (Losses a shader build reports). A slice-writing geometry shader on it logs `has no layer entry points`. → [Layer entry points with the point size passed by reference](../reference/shaders.md#layer-entry-points-with-the-point-size-passed-by-reference) - in the build's log, `[RED] <key>: the translator deleted N bindless accesses (<type> N): their results read 0` or `[RED] <key>: its library builds only without its layer, integer output, dual source entry points`, and `[RED] lost without failing: …` with the counts per kind (the NSP script repeats that one line). In `regress.py`, `NEW-FAIL: N shaders with more … than in the baseline`. → [Losses a shader build reports](../reference/shaders.md#losses-a-shader-build-reports) - `Ampere instruction 80d ... (000fc80003fe0000c43211110000780d) is not implemented` for every vertex shader of the game, so nothing draws. → [A guard band cull in every vertex shader (0x80d)](../reference/shaders.md#a-guard-band-cull-in-every-vertex-shader-0x80d) - `Ampere instruction <op> at 0x… is not implemented`, `F2FP.MERGE_C` or `F2I from a float that is not 32-bit` in the shader build; those shaders are left out and their draws and dispatches skipped. → [Ampere instructions new in Pokémon Pokopia](../reference/shaders.md#ampere-instructions-new-in-pokémon-pokopia) - single bright dots at thin far geometry (railings, track edges), changing frame to frame as the camera moves, already in the lit picture before anti-aliasing. Most of them come from another cause (below). → [Comparisons with .FTZ](../reference/shaders.md#comparisons-with-ftz) - `Ampere instruction f55 at 0x… (000fe20000000000000000001a0f7f55) is not implemented` in the shader build; those shaders are left out. → [Barrier moves around warp shuffles](../reference/shaders.md#barrier-moves-around-warp-shuffles) - `Ampere b82 at 0x…: LDC with a bindless bank or an address mode (…00008a00…7b82)` in the shader build; those shaders are left out. → [LDC with the bank in its address register (`.IS`)](../reference/shaders.md#ldc-with-the-bank-in-its-address-register-is) - 64-bit arithmetic in a shader gives wild results: the 64-bit division behind an exposure average returned 893011 for 218, so the exposure stayed at the end of its range. With only the pair fixed it still gave 2 for 340 / 1. → [IMAD.HI adds a register pair, and IMAD.X its carry](../reference/shaders.md#imadhi-adds-a-register-pair-and-imadx-its-carry) - a scene lit by many small lights comes out too dark, with its clustered light lists empty for most clusters. → [NVN2 compute reads its workgroup counts at c0 + 4](../reference/shaders.md#nvn2-compute-reads-its-workgroup-counts-at-c0--4) - `Ampere instruction 361` (or `f60`, `370`, `38d` and others) refused, or hundreds of `Failed to find handle source for bindless access of type "textureCube"` when the handle was taken from the wrong register: units drawn white, the rest of the scene right. → [Texture handles of SDK 22's Ampere code](../reference/shaders.md#texture-handles-of-sdk-22s-ampere-code) - `reflection conversion failed: B binding cp_t_cb196610_10280074Smplr has no resolved slot number` at load, then `the dispatched program has no compute shader`; the shader's image has no slot either (`cp_i_tcb_AA_`). → [NVN2 compute's separate handles in c[0]](../reference/shaders.md#nvn2-computes-separate-handles-in-c0) - `reflection conversion failed: B binding fp_t_cb2_170 has no resolved slot number` at load (the draw is skipped), the build summary counting the binding under *slot was not decoded*; or, once the read's other inputs are known, `Failed to find handle source for bindless access of type "texture2D"` and the read answers 0. `DMSH_BINDLESS_TRACE=1` on a `dmsh_xlate` job prints what a refused handle is made of. → [A handle pair ORed sampler word first](../reference/shaders.md#a-handle-pair-ored-sampler-word-first) - a Switch 2 game's frame rate swings between 60 and 30 fps (Donkey Kong Bananza's own controller, `main+0x204a18`, drops to 30 after two frames of 20 ms from their start to the GPU's end, and comes back after six), and the GPU profile (`DM_NVN_GPUPROF`) shows one compute dispatch of 2-6.5 ms a frame: agl's upscaler network (`agl_ndsr.pck`, shader `7629d857a0a93833`). → [Ampere HMMA through simdgroup_matrix](../reference/shaders.md#ampere-hmma-through-simdgroup_matrix) - a vertex or compute shader reads zeros from NVN's driver segment `c0`. → [Driver-segment reads outside fragment shaders](../reference/shaders.md#driver-segment-reads-outside-fragment-shaders) - flickering hard-edged white tiles (tiled lighting with every tile row getting row 0's or other rows' lights). → [Compute `c0`: dispatch size and uniform buffer table](../reference/shaders.md#compute-c0-dispatch-size-and-uniform-buffer-table) - `[RED] shader ... reflection conversion failed: B binding gp_s0 has no resolved slot number`; a geometry shader reading driver segment `c0` reports that its storage-buffer table base was never measured. → [Geometry-stage storage buffer table](../reference/shaders.md#geometry-stage-storage-buffer-table) - a storage buffer the shader stores to or uses atomically has `rw: false` in its generated reflection; replay does not record its GPU writes for dependent buffer reads. → [Storage-buffer write flag in translation metadata](../reference/shaders.md#storage-buffer-write-flag-in-translation-metadata) - point sprites of size 0 (Odyssey's Cap Kingdom fog never parted around Mario). → [Graphics `c0 + 0x610`: the largest point size](../reference/shaders.md#graphics-c0--0x610-the-largest-point-size) - occlusion queries that always return 0 samples (Z-A: characters' legs folded back from the hips once they walked); every instanced draw's transform taken for instance 0. → [Graphics `c0 + 0x644`: the draw's base instance](../reference/shaders.md#graphics-c0--0x644-the-draws-base-instance) - flat grey or background-coloured triangles with straight edges across part of the scene, changing shape from frame to frame while the camera stands still; dropping the colour pass's fragment shaders in groups (`DM_NVN_SKIP_FS`) did not remove them, as the instances are misplaced in the depth pre-pass too, whose depth the colour pass tests for equality. → [The base instance of indirect draws comes from Metal](../reference/shaders.md#the-base-instance-of-indirect-draws-comes-from-metal) - `[RED] shader … reflection conversion failed: reads driver-bank locations at run time that the replay layer cannot fill: c0 dynamic index c0+0x630`, and that shader's draws are missing; the build notes `Shader instruction Pixld is not implemented` for pixel shaders; `[RED] NVN unimplemented function called: nvnProgramSetSampleShading`. → [Pixel `c0 + 0x620`: the sample index and GLSLC's sample position table](../reference/shaders.md#pixel-c0--0x620-the-sample-index-and-glslcs-sample-position-table) - a menu's labels drawn as plain bars, other menus empty except for the cursor (one pool's textures overwritten by another's); a black screen when IDs past a fixed table read as empty slots. → [Texture and sampler pools with overlapping IDs](../reference/shaders.md#texture-and-sampler-pools-with-overlapping-ids) - red lines from the list of command buffers that bound a non-first pool (6,734 in one DARK SOULS: REMASTERED run). → [Bases of bound handles kept in the command buffer](../reference/shaders.md#bases-of-bound-handles-kept-in-the-command-buffer) - distant walls and floors smeared sideways (DARK SOULS: REMASTERED): tiling textures took a clamp-to-edge sampler and repeated their edge column. → [Handles from uniform buffers take the bound pools' bases](../reference/shaders.md#handles-from-uniform-buffers-take-the-bound-pools-bases) - the 3D scene black, only particles and the HUD drawn; pass dump `B` lines all `tid=0 dummy`. → [Deferred texture binds read at execution](../reference/shaders.md#deferred-texture-binds-read-at-execution) - bindless handles read from a uniform buffer name the wrong texture when the game writes them earlier in the same submission. → [Handles in uniform buffers written earlier in the same submission](../reference/shaders.md#handles-in-uniform-buffers-written-earlier-in-the-same-submission) - a storage buffer reported with `cb_slot` 3, which had no NVN slot. → [Storage buffer addresses in the game's own uniform buffer](../reference/shaders.md#storage-buffer-addresses-in-the-games-own-uniform-buffer) - whatever a shader writes through a pointer it read from memory never happens. The build summary counted `Failed to find storage buffer for global memory operation "Store"`, and the shader's MSL had a store function with an empty body. In Donkey Kong Bananza the tunnel's walls and floor were black and only the loose rocks drew. → [Global memory at an address loaded from memory](../reference/shaders.md#global-memory-at-an-address-loaded-from-memory) - `no resolved slot number`, the shader does not load; the translation has a 32-entry texture-pool array (`fp_t2d_cb0_40000000`, handle type Direct). → [Bindless handles through a loop phi](../reference/shaders.md#bindless-handles-through-a-loop-phi) - none in the log: texture reads come back 0. Particle meshes collapse to a point (their scale reads 0), so effects are missing or show as dark patches. The translator's own message (`Failed to find handle source for bindless access of type "textureBuffer"`) used to be dropped, because `dmsh_xlate`'s accessor had no `Log`; its messages now go into the shader's notes, marked `translator: `, and the build summary counts them apart from unanswered queries. → [Bindless reads whose handle phi also carries other values](../reference/shaders.md#bindless-reads-whose-handle-phi-also-carries-other-values) - the shaders' bindless arrays have no slot and used not to load; the translator falls back to a 32-entry array such as `array<texture_buffer<float>, 32> vp_tb_cb0_40000000`. → [Texture slots picked at run time](../reference/shaders.md#texture-slots-picked-at-run-time) - Ryujinx's fallback arrays (`fp_t2d_cb0_40000000`) in pixel shaders whose handle comes from the game's own uniform buffers; the shaders do not load and their draws are skipped. → [A texture chosen at run time between two uniform-buffer handles](../reference/shaders.md#a-texture-chosen-at-run-time-between-two-uniform-buffer-handles) - `[RED] shader … reflection conversion failed: a texture handle the translator could not trace to one slot (profile key tex_dyn_slots off)`, then `failed to load`, and the draws are skipped: in Mario Party Superstars every character and NPC in a lit scene is a flat grey silhouette (the depth pre-pass draws, the colour pass does not), and the opening scene's pipe is grey. → [Texture handles from game memory index the pools](../reference/shaders.md#texture-handles-from-game-memory-index-the-pools) - the host stops at the shader's first load: `unexpected argument buffer layout: encodedLength=640 maxAid=48`. → [An array of handles in a uniform buffer](../reference/shaders.md#an-array-of-handles-in-a-uniform-buffer) - characters and other moving objects have almost no ambient light: lit only from where the sun reaches, black underneath, while the scenery around them is right. Nothing is red. On Kirby Air Riders a dark red Kirby on a bright course, where the game's own tutorial movie shows him bright pink. → [A table of handles longer than the array](../reference/shaders.md#a-table-of-handles-longer-than-the-array) - `reflection conversion failed: B binding fp_t2ds_cb196614_10570000 has no resolved slot number`, then `failed to load`; those draws are skipped, and the scene is dark or black where it is lit by them. → [An array of uniform-buffer handles with its sampler word in c2](../reference/shaders.md#an-array-of-uniform-buffer-handles-with-its-sampler-word-in-c2) - characters shaded black; a shader indexes a table of cube maps, and every element it reads clamps to the array's last one, which holds no handle. → [A table of handles past the array's length](../reference/shaders.md#a-table-of-handles-past-the-arrays-length) - `shaders with a binding whose slot was not decoded 588`; shadow cascades read through `array<texture2d_array<float>, 32> fp_t2das_cb2_0`. → [An array of handles from the driver table c2](../reference/shaders.md#an-array-of-handles-from-the-driver-table-c2) - `[RED] shader … reflection conversion failed: B binding fp_t2d_cb196610_10570000 has no resolved slot number`, then, with that resolved, `… reads driver-bank locations at run time that the replay layer cannot fill: c2 dynamic index`; the shader does not load and its draws are skipped. → [Arrays of c2 handles cover the whole table, with a separate sampler word](../reference/shaders.md#arrays-of-c2-handles-cover-the-whole-table-with-a-separate-sampler-word) - characters and props glowing white, about 10⁴ too bright, in DRAGON QUEST VII Reimagined's opening cutscene only, while walls and gameplay look right. → [A texture slot that shares its c2 word with an image slot](../reference/shaders.md#a-texture-slot-that-shares-its-c2-word-with-an-image-slot) - `[RED] texture type mismatch: shader … declares slot 128 as Metal type 2, texture ID … is type 7 (NVN target 2, …); bound as is`, for a shader whose MSL has a `texture3d` and a `texture2d` on the same register and only calls `get_width` / `get_height` on the `texture2d`. → [A size query on a 3D texture gets a 2D slot](../reference/shaders.md#a-size-query-on-a-3d-texture-gets-a-2d-slot) - `[RED] shader … reflection conversion failed: 66 bindings, over the limit 64`, then `failed to load`, and the draws with it are dropped (a black map). → [More than 64 bindings in one shader](../reference/shaders.md#more-than-64-bindings-in-one-shader) - the host stops at a shader's first load: `FATAL shader … has an unexpected argument buffer layout: encodedLength=88 maxAid=8` (crash in `c1_store` / `pull_load`), with a storage buffer or image missing from its reflection json. → [Argument buffer members with attributes after their id](../reference/shaders.md#argument-buffer-members-with-attributes-after-their-id) - the replay put a texture resource ID where the shader wanted an address; with the old 64 KB dummy buffer, pointers in the game's objects and in the host's program objects got their upper 4 bytes replaced and the game or the replay crashed, or `kIOGPUCommandBufferCallbackErrorPageFault`, after which macOS ignores the process's command buffers (GitHub issue #101). Later, `[RED] image atomics on a block-linear texture … not followed, the atomics go to a scratch buffer`, and compute shaders with atomics on a 3D image did not build (`array subscript is not an integer`). → [Image atomics](../reference/shaders.md#image-atomics) - `image atomics: unsupported or overflowing IMG extent` at the first dispatch, despite a valid four-byte counter buffer. → [Buffer image reflection keeps its texture type](../reference/shaders.md#buffer-image-reflection-keeps-its-texture-type) - `[RED] image atomics on a texture Metal cannot run them on`, and whatever the shader computes through them is lost: its writes go to a sink. → [Image atomics on a 32-bit colour texture](../reference/shaders.md#image-atomics-on-a-32-bit-colour-texture) - Metal shader validation reports invalid image-atomic stores even with an image-sized scratch buffer; without validation, GPU page faults can freeze rendering. → [Bounds of image atomics](../reference/shaders.md#bounds-of-image-atomics) - the NSP script stops with `captured only 0 run-time shaders` although the game reaches its frame loop with precompiled shaders. → [A GLSL language preamble is not a complete shader](../reference/shaders.md#a-glsl-language-preamble-is-not-a-complete-shader) - shaders missing from the map that no game file holds. → [Built-in shaders compiled with the game's own GLSLC](../reference/shaders.md#built-in-shaders-compiled-with-the-games-own-glslc) - the NSP script stops with `captured only 0 run-time shaders` while the capture run reaches the game's frame loop and runs to the end of its 30 s. → [A run-time compile that waits for a button press](../reference/shaders.md#a-run-time-compile-that-waits-for-a-button-press) - The Mac capture boot submits shader programs but writes no GLSLC capture files. → [Offline coverage after an empty GLSLC capture](../reference/shaders.md#offline-coverage-after-an-empty-glslc-capture) - a null read at `main+0x3316dc` in `nnMain`, right after the window setup (the program object's interface pointers at +0xd0 / +0xd8 both null). → [GLSLC GPU code version against the driver's range](../reference/shaders.md#glslc-gpu-code-version-against-the-drivers-range) - `gl_shaders.py` failed on the captured sources: `ES shaders for SPIR-V require version 310 or higher`. → [GLSL ES 1.00 sources without a `#version` line](../reference/shaders.md#glsl-es-100-sources-without-a-version-line) - `uniform LightEnv { … };` failed with `uniform u_LightEnv: type LightEnv (structs are not implemented)`, so every program that used one was missing from the library. → [Struct uniforms become member rows](../reference/shaders.md#struct-uniforms-become-member-rows) - the pipeline prebuild stops at the same line on every start (`pipeline prebuild: 7000 of 20740 pairs, 1987 built, 5013 already archived, 0 left to the draws, 0 failed`), behind *Preparing pipelines* or, with `DM_PSO_PREPARE=0`, as a black screen while the sound plays on; the NSP script's `[7/7] Pipeline prebuild` does not end (`dmhost` at 0% CPU, `MTLCompilerService` at 100%), and `MTLCompilerService` crash reports (`EXC_CRASH`, `llvm::report_bad_alloc_error`) come every 6 to 10 minutes. The bases built since the last file are never written, so the next start builds them again and stops at the same pair. → [A compile that does not return stalls every flush and draw](../reference/shaders.md#a-compile-that-does-not-return-stalls-every-flush-and-draw) - a self-contained Mac app (`--platform mac-app`) logs `pipeline prebuild: no .../Resources/dm/shader_pairs.tsv, nothing to build` although every shader library is there; it draws no hybrid stand-ins, and each pipeline seen for the first time compiles on the submit thread (frames of 100–550 ms). → [Shader-pair tables in a Mac app](../reference/shaders.md#shader-pair-tables-in-a-mac-app) - `pipeline archive bundled with the app: none for this GPU (...)`: the device builds the bases itself although the app carries an offline archive. → [Offline pipeline archive missing for the device GPU](../reference/shaders.md#offline-pipeline-archive-missing-for-the-device-gpu) - a truncated `.mtl4a` reaches `MTL4ArchiveImpl::loadFromURL`; the bundle reports coverage with `0 of 0 probed bases found`; rebuilt shader libraries reuse an archive of their old binaries; or packing fails with `pso_offline: no base to build` when every eligible pair has function constants, or when the profile's `shader_pairs.tsv` holds only its header (`--platform mac-app`, GitHub issue #338). → [Offline pipeline archive reuse and fallback](../reference/shaders.md#offline-pipeline-archive-reuse-and-fallback) - an unchanged NSP spends minutes in `shader split` after a shader-chain update, on both Mac and iOS builds, although the extracted package is identical. → [Shader extraction reruns after translation-only updates](../reference/shaders.md#shader-extraction-reruns-after-translation-only-updates) - rebuilding an unchanged NSP after a shader-chain update runs `metal-tt` for minutes even when all referenced Metal libraries and pipeline settings remain identical. → [Offline pipeline archive rebuilt after a chain-only update](../reference/shaders.md#offline-pipeline-archive-rebuilt-after-a-chain-only-update) - the host logs `pipeline archive bundled with the app: made for ... this run needs ...`, naming different depths, and pipeline bases compile during play despite a successful archive build. There need not be a `[RED]` line. → [Offline pipeline archive and profile depth disagree](../reference/shaders.md#offline-pipeline-archive-and-profile-depth-disagree) - `pipeline archive bundled with the app: this system cannot open …/applegpu_<gpu>.mtl4a (deployment target for architecture … found in archive … is not compatible with current OS …): the bases are built on the device`. On macOS 26.6 with Xcode 27.1, `t_pso_bundle` failed 10 checks, from `bundle: opened` on, and a Mac app packed there compiled every base on its first start, as without the archive. → [Offline pipeline archive made for another major version](../reference/shaders.md#offline-pipeline-archive-made-for-another-major-version) - `pso_offline.py` holds about 1.8 GB while `metal-tt` builds an archive of 140,036 bases, and the system's memory view shows the build far larger than that (180.5 GB) before `metal-tt` fails or is stopped. → [Python memory during offline pipeline archive preparation](../reference/shaders.md#python-memory-during-offline-pipeline-archive-preparation) - the offline archive stops with only `applegpu-nt command failed`, sometimes after `Max Unstruct ID` lines (a note, not the failure); the macOS kernel log reports `no paging space action` and kills `air-nt` as the largest compressed process. → [Bounded groups for the offline pipeline compiler](../reference/shaders.md#bounded-groups-for-the-offline-pipeline-compiler) - `--platform mac-app` or the iPhone build stops at its pipeline archive stage, after every earlier stage has finished: `[RED] pso_offline: metal-tt failed for applegpu_<gpu> (exit 1)`, then `pso_offline.py exit code 1`. → [A failed pipeline archive stops the whole build](../reference/shaders.md#a-failed-pipeline-archive-stops-the-whole-build) - `[RED] pso_offline: metal-tt failed for applegpu_<gpu> (exit 1)` with only `applegpu-nt command failed` in `metal-tt.<arch>.log`. → [Offline pipeline archive on a full disk](../reference/shaders.md#offline-pipeline-archive-on-a-full-disk) - `[RED] pipeline prewarm: seed list does not exist: …/pso_manifest.tsv` at every start, no `pipeline prewarm list …/pso_user.tsv` line, and the same compile stalls every session in places already visited, while `pso_user.tsv` keeps growing; the pipeline archive gains files every start and is never compacted (Donkey Kong Bananza: 88 files, 7 s to open them). → [The device's prewarm list unread without a seed list](../reference/shaders.md#the-devices-prewarm-list-unread-without-a-seed-list) - the first frame that draws with new programs loads their shader libraries on the submit thread (`[longframe] ... shader libraries N, X ms`): tens of milliseconds with the files cached, seconds when the drive is slow. → [Shader libraries loaded when the program is made](../reference/shaders.md#shader-libraries-loaded-when-the-program-is-made) - at boot, `CRASH sig=5 … pc=_dispatch_once_wait.cold.1` right after the `pipeline bases so far` line, with `bt: pso_prebuild __shmap_load_block_invoke … mtl_prog_prefetch h_nvnProgramSetShaders`. → [The prepare step inside the shader map's once](../reference/shaders.md#the-prepare-step-inside-the-shader-maps-once) - the user cache folder (`getconf DARWIN_USER_CACHE_DIR`, then `com.apple.gpuarchiver/`) fills with `gpuarchiver-*` folders of 0.3–5 MB each, one per pipeline archive flush (456 folders, 2.5 GB after two days). Later folders are larger, up to about 127 MB (an M4 Pro, 2026-10-29: 19 GB in 423 folders after a day of Mac runs and regression checks); why they grew is **open**. A later compile can fail with `cannot open '…/gpuarchiver-…/PersistentState': No such file or directory`. → [Metal's build folders left by pipeline archive flushes](../reference/shaders.md#metals-build-folders-left-by-pipeline-archive-flushes) - a previously working game exits with 139 on every start after pipeline preparation; `dispatch_retain(NULL)` is called by `-[_MTLBinaryArchive materializeAirNTFromOnlineForSlice:entryList:]` under `airntSerializeToURL` and `arch_flush` (issue #342). → [A compaction flush that crashes, then crashes every start](../reference/shaders.md#a-compaction-flush-that-crashes-then-crashes-every-start) - identical render pipelines compile repeatedly under different keys, lengthening startup prewarm and adding pipeline misses during play. → [Pipeline keys omit unused colour state](../reference/shaders.md#pipeline-keys-omit-unused-colour-state) - a vertex shader whose pairs changed was restored unpadded from `cas/`. → [Shader cache key covering the pairs](../reference/shaders.md#shader-cache-key-covering-the-pairs) - an edit to a shader build helper reaches no library: `shader cache: hit` for every shader, and the old MSL is filed under the new chain version. An edit to `dmsh_meshstage.py` did not change the chain version either. → [Shader cache key missing helper modules](../reference/shaders.md#shader-cache-key-missing-helper-modules) - a full build reports successful shaders, but `metal-tt` rejects its pipeline archive with fragment inputs not written by the vertex shader. Fifteen cached vertices lacked default outputs in DRAGON QUEST I & II. → [Partial vertex builds missing paired pixel sources](../reference/shaders.md#partial-vertex-builds-missing-paired-pixel-sources) - a repeated iOS-only shader build crashes with `FileNotFoundError` for `<key>_b.json` in the Mac output directory; requesting only Mac libraries with `IOSOUT` set still compiles iOS side libraries. → [Target selection keeps the shader analysis files in the cache](../reference/shaders.md#target-selection-keeps-the-shader-analysis-files-in-the-cache) - after `scripts/build_ipa_from_nsp.py <NSP folder> --platform mac`, a plain (iOS) run of the script on the same folder succeeds, but the Mac run command the first build printed then logs hundreds of `[RED] failed to load shader <key>_b: cannot open …/shader/cache/b-<chain>/<key>_b.metallib` lines, until `--platform mac` is run again. → [An iOS build after a Mac-only build kept no Mac libraries](../reference/shaders.md#an-ios-build-after-a-mac-only-build-kept-no-mac-libraries) - the build folder of a game (`<id>_build/shader/`) gains about 2 GB for Breath of the Wild with every upstream update that changes the shader chain: after two updates `shader/cache` held `b-157e1b96c8da` (2.1 GB) and `b-a78f966a7b38` (2.3 GB) besides the current one, and the next build added a third. → [Old shader library folders grew a game's build folder with each chain change](../reference/shaders.md#old-shader-library-folders-grew-a-games-build-folder-with-each-chain-change) - `<id>_build/shader/cache/cas/shader/` holds several entries for each shader, and grows by a full set with every upstream update that changes the shader chain. Tears of the Kingdom (seedds/nxnative#1033): 172,014 entries after six builds for 28,669 shaders, 11.85 GB of `.metal` and `.json` that no build read; the test Mac's copy held 934,955, of which the prune (dry run) found 906,286 unused: 70.2 GB of sources and reflection, scanned in 18 minutes on an external SSD. → [Old per-shader cache entries grew a game's build folder with each chain change](../reference/shaders.md#old-per-shader-cache-entries-grew-a-games-build-folder-with-each-chain-change) - the NSP script's Mac or iOS shader step for a game with very large shader packages runs at one or two shaders a second whatever `J` is. Its Python process sits at one full core, mostly system time, while few `metal` compiles run. Pokémon Pokopia (4.4 GB of packages, 131,426 shaders): players reported ETAs of 20 to 200 hours (seedds/nxnative#1036). → [A shader build that keeps its packages in memory runs one worker at a time](../reference/shaders.md#a-shader-build-that-keeps-its-packages-in-memory-runs-one-worker-at-a-time) - the Mac or iOS shader step of a game with a large map still takes many hours with every worker busy, and a `metal -c` of a translated shader takes about 0.7 s of CPU, nearly all in the front end. Optimising adds about 0.1 s, and an empty shader takes 0.025 s. Pokémon Pokopia's 131,426 shaders: about 9 hours on an M4 Pro (seedds/nxnative#1036). → [Each Metal compile instantiates Metal's texture classes again](../reference/shaders.md#each-metal-compile-instantiates-metals-texture-classes-again) - the shader step of a game with large translated sources has fewer Metal compiles running than `J` asks for, and `dmsh_build.py`'s own process stays busy on one core between them. Pokémon Pokopia's sources average 220 KB, and the builder spent about 0.12 s of Python on each shader, all but its system calls under the GIL, which alone would have come to about 4.2 hours of its full build. → [Rewrites that try every character of a large source](../reference/shaders.md#rewrites-that-try-every-character-of-a-large-source) - two builds of the same shaders give different `_bl` or `_bf` libraries for some keys, of the same size, 46 bytes apart, while their MSL is the same. A byte comparison of two library folders reports them, and `regress.py` can report them as changed variants. → [A library that depends on its source's file name](../reference/shaders.md#a-library-that-depends-on-its-sources-file-name) - the Mac or iOS shader step of a game with many pixel shaders spends most of its Metal compiles on libraries that few draws load: Pokémon Pokopia's whole map took 366,805 compiles, about 57% of them for `_ba` and `_bl`, and its runs opened none of the 5,775 of each. → [One compile for a pixel shader's side entry points](../reference/shaders.md#one-compile-for-a-pixel-shaders-side-entry-points) - startup tasks can prepare the same shader more than once, even though only one object enters the warm dictionary. A measured Tears of the Kingdom startup avoided 320 duplicate preparations; this is not a steady-frame-rate claim. → [Concurrent warm tasks prepare each shader once](../reference/shaders.md#concurrent-warm-tasks-prepare-each-shader-once) - the Mac's pipeline prebuild (`DM_PSO_PREBUILD=tool`, the NSP script's `pso_prebuild.log`) runs on far fewer workers than the Mac has: `1 workers` on an M6, where Metroid Prime Remastered's 20,233 pairs took 1,725 s and Link's Awakening's 17,742 took 667 s, and 4 on an M5 Pro, where Donkey Kong Bananza's 21,225 took 6.5 to 7.5 minutes. → [A prebuild pool sized from the Super cores](../reference/shaders.md#a-prebuild-pool-sized-from-the-super-cores) - `fragmentFunction main0 cannot be used to build a pipeline state` (a Metal validation assertion). → [Function constants specialized at load](../reference/shaders.md#function-constants-specialized-at-load) - with Metal 4 pipelines on (the Mac; on iOS `pso_mtl4 on` or `DM_PSO_MTL4=1`), Apple's performance HUD says `Compiled 2 shaders. Total compilation time is 102.70ms. Consider adopting MTL4Compiler for more fine grained compilations` during play, when a shader with function constants loads. → [Functions with function constants specialized by the pipeline, not the library](../reference/shaders.md#functions-with-function-constants-specialized-by-the-pipeline-not-the-library) - a pipeline for a vertex shader that writes `render_target_array_index` cannot be built. → [Layer-writing vertex shaders get the triangle class](../reference/shaders.md#layer-writing-vertex-shaders-get-the-triangle-class) - the picture bright green and white from some scene on, in runs with pipelines compiled on demand (prewarm lists off or short) and in none with `DM_NVN_PREDICT=0`. → [The precompile look-ahead restores the scissor](../reference/shaders.md#the-precompile-look-ahead-restores-the-scissor) - a GPU frame capture (`DM_GPU_CAPTURE`, or Xcode with `MTL_CAPTURE_ENABLED=1`) fails with `Capturing Render pipeline specialization is not supported`, or the capture layer crashes on the pipeline archive; a capture of the `MTLDevice` is refused. → [GPU frame captures need pipelines built through the device](../reference/shaders.md#gpu-frame-captures-need-pipelines-built-through-the-device) - the first boot sat on the loading clock for about a minute, the CPU idle, with every file read done after 12 s. → [A cold Metal cache looks like a long load](../reference/shaders.md#a-cold-metal-cache-looks-like-a-long-load) - hundreds of geometry raster passes in combat, despite support for batching consecutive geometry draws. → [Geometry runs across occlusion query boundaries](../reference/shaders.md#geometry-runs-across-occlusion-query-boundaries) - geometry preparation dominates rendering CPU even after geometry passes have been batched; primitive assembly and capture-index deduplication repeat for unchanged meshes. → [Prepared geometry indices reused after byte comparison](../reference/shaders.md#prepared-geometry-indices-reused-after-byte-comparison) - geometry vertex-capture passes consume substantial GPU time before geometry compute or depth rasterization. → [Geometry capture initializes only missing words](../reference/shaders.md#geometry-capture-initializes-only-missing-words) - Apple's performance HUD (`DM_METAL_HUD=1`) says `Compiled 2 shaders. Total compilation time is 102.70ms. Consider adopting MTL4Compiler for more fine grained compilations` during play, with a dip in the frame-rate graph at that moment, for example when a new room first issues a scissored clear. → [The host's own shaders compiled from source at run time](../reference/shaders.md#the-hosts-own-shaders-compiled-from-source-at-run-time) ## Game state - "stuck" at a screen with one draw per frame. → [Most draws are in command buffers replayed later](../reference/game-state.md#most-draws-are-in-command-buffers-replayed-later) - menus ignore A. → [Buttons mapped by position: B confirms](../reference/game-state.md#buttons-mapped-by-position-b-confirms) - a crash in `main+0x339c00` a second or two into the title, in love-nx's video module teardown (`love::video::theora::Video` → `~Worker`; its thread released the worker that the closing module deletes too). → [Any Lua error quits a LÖVE game](../reference/game-state.md#any-lua-error-quits-a-löve-game) - the TV latency calibration ("press A when you hear the fourth beat") ignores A. → [TV latency calibration's late, beat-timed listening window](../reference/game-state.md#tv-latency-calibrations-late-beat-timed-listening-window) - in a scripted run, a screen goes back by itself right after a confirm; the log shows `swkbd: … → no window, treated as cancel`. → [The software keyboard in scripted runs (`DM_KBD`)](../reference/game-state.md#the-software-keyboard-in-scripted-runs-dm_kbd) - a player join screen that ignores A (a character select with four "L + R to join" slots after the title). → [Player join screens (`hid::StartLrAssignmentMode`)](../reference/game-state.md#player-join-screens-hidstartlrassignmentmode)