WIP: feat(macos): Vulkan on Metal: pinned host imports, the unified-memory budget, Metal's cache folder and KosmicKrisp #846

Draft

mooki wants to merge 21 commits from mooki/Longshot:mac/topic-vulkan-on-metal into main

pull from: mooki/Longshot:mac/topic-vulkan-on-metal

merge into: MagicBeanDev:main

MagicBeanDev:main

Conversation 1 Commits 21 Files changed 164 +18020 -308

mooki commented 2026-11-15 17:39:38 +00:00

Member

• Copy link
• Copy Markdown

Type: feat · Risk: medium · Tested on: macOS 26.7.1, Apple M4 Max (arm64; x86_64 under Rosetta) · Needs: Windows and Linux, any GPU

Why

On a Mac the game's Vulkan renderer runs on Metal through a driver (MoltenVK, or KosmicKrisp through the Vulkan loader), and
four things it needs there were missing. Guest memory imported into Vulkan could be replaced or discarded while the GPU still
used it, and a renderer whose startup failed part-way left what it had made behind (on every platform). The GPU has no memory
of its own on a Mac, yet the renderer took Metal's recommended working set (53 GB on a 64 GB Mac) as its allowance, so nothing
gave memory back while the Mac ran out (run #22 lost the device). Metal keeps its compiled shader cache under /var/folders,
which a sandboxed start cannot open, so every start compiled every pipeline again. And the macOS package carried MoltenVK
only, so KosmicKrisp, LunarG's conformant Vulkan 1.4 driver on Metal, could not be measured. This PR is that layer of the macOS
port, on top of the macOS host (the topic before it). See #420.

What changed

Every macOS host import is pinned in the executable until its last Vulkan owner is gone, and a failed startup gives back what
it made (that rollback, the recorder's drain before it and the move-only import owners apply on every platform); on a Mac's
unified memory the renderer's GPU allowance follows what the Mac has free; RX_VK_METAL_CACHE_DIR points Metal's cache at a
chosen folder; and the macOS package can carry the Vulkan loader with MoltenVK (the default) and KosmicKrisp (opt-in,
RX_VK_DRIVER=kosmickrisp). The four original pull requests, in commit order:

• import pins and startup rollback (c1fa25a4; Was: #491):
  macOS: DarwinImportBacking and the move-only DarwinImportView in gpu/vk/vk_memory.cpp (range arithmetic in the new
  gpu/vk/darwin_import.h) pin each import's whole backing through two new MkwVkHost callbacks (gpu/vk/vk_api.h, Apple
  MKWVK_API_VERSION 25; Windows and Linux keep main's 23), filled by host/rx_backend.c; host/posix/win32_posix.c's
  waveOutOpen resolves the executable's audio service (host/hos_sdl.c) instead of a weak import. Every platform:
  replay_start_rollback() in gpu/vk/vk_replay.cpp and vma_startup_rollback() in gpu/vk/vk_vma.cpp unwind a failed
  startup; vmaDestroyAllocator is a recorder drain boundary (gpu/vk/vk_recorder.h, vk_work.h); import pools are moved,
  not copied, with one destroy_import(); on Linux MessageBoxA closes its extra dlopen reference and waveOutOpen checks
  its allocations. Tests: tests/test_darwin_renderer.py, tests/test_darwin_audio_service.py (new); eight existing checks
  that build vk_memory.cpp or the audio route follow the moved Pool and the new callbacks.
• the unified-memory budget (45e1d666; Was: #642): on a
  Mac's unified memory vram_usage() in gpu/vk/vk_vma.cpp answers the least of the driver's allowance, RAM less this
  process's CPU memory less a reserve, and what the GPU holds plus what the system has available less a margin
  (gpu/vk/system_memory.h and gpu/vk/unified_budget.h, new); spare capture buffers (vk_memory.cpp) and idle staging
  (unified_memory_watch() in vk_texture.cpp) are not kept past 90% of it; a vk: unified memory line splits the GPU's
  memory into the renderer's and Metal's own. All inside __APPLE__; RX_VK_UNIFIED_BUDGET=0 turns it off. Test:
  tests/test_unified_budget.py (new).
• Metal's cache folder (01630d4b; Was: #653):
  RX_VK_METAL_CACHE_DIR=<folder> (macOS only, off by default) hands the folder to Metal before the Vulkan library loads and
  logs after the device whether Metal took it (gpu/vk/metal_cache.h, new; gpu/vk/vk_main.cpp). Test:
  tests/test_metal_cache_dir.py (new).
• the Vulkan loader with KosmicKrisp and MoltenVK (7df74b12; Was:
  #654): with the optional build inputs LONGSHOT_VULKAN_LOADER
  (and LONGSHOT_KOSMICKRISP, arm64) the macOS package carries LunarG's loader and each driver with a manifest beside it, and
  at startup host/posix/darwin_vulkan.c and host/hos_main.c point the loader at MoltenVK unless RX_VK_DRIVER=kosmickrisp;
  without the loader input the package is as before (nx2/darwin_build.py, nx2/darwin_package.py). Tests:
  tests/test_vk_darwin_admission.py (the driver choice, 27 cases), tests/test_macos_package.py,
  tests/display_startup_failure_test.cpp.
• docs: docs/development.md (the switches' rows and the macOS build inputs), gpu/vk/VULKAN.md.

Measurements

Verdict: works. The members' tests fail on main (or are new) and pass here on arm64 and on x86_64 under Rosetta; in the
macOS port's game runs (integration builds) the allowance read the system (10.2-20.8 GB against the driver's 53,084 MB),
Metal took the chosen cache folder in every start that set it (denied cache opens from about 1.5 per compile to 0), and
MoltenVK through the packaged loader prepared all 38,809 programs in 58.0 s while KosmicKrisp prepared 1,607 in 1,770 s and
never reached the title (so MoltenVK stays the default). The full suite at this head: 576 passed, 15 failed, 17 skipped against
main's 543/33/17 on this Mac (and topic 1's 572/15/17), with no check failing that passes on main.

Baseline: the game rows are the macOS port's integration builds, arm64, MoltenVK 1.4.2 (main does not run on macOS): the
allowance, before integration 552cc3d4 (run #23, whose read gate never opened: the driver's allowance, as main), after
e7730869 and 6962f8fb (runs #24, #26); the cache, before aefe6b0a (run #4), after f32adfa2 and a7711f3c (runs
#5-#8); the drivers, one build 09f9a171 with both drivers packaged (run #20 KosmicKrisp, run #21 MoltenVK). The game-free
rows compare with main (the tests do not exist there, or fail there) and run at this head.

Hardware: macOS 26.7.1, Apple M4 Max (40-core GPU), MoltenVK 1.4.2, KosmicKrisp from LunarG's Vulkan SDK 1.4.363.1, 16-core
CPU, 64 GB
Scene: game-free fixtures; the game rows: Hyrule Field from the field-dawn save (the allowance), the start-up precompile and
the title (the cache and the drivers), windowless, defaults
Method: each member's test before and after (two interleaved runs in the members' own runs); at this head each once per
architecture; the game rows: the vk: unified memory, cache and precompile lines of each run's longshot_log.txt, one run each
How to reproduce: the tests under Testing; RX_VK_UNIFIED_BUDGET=0 gives the old allowance on the same build;
RX_VK_METAL_CACHE_DIR=<folder> in a sandbox that denies /var/folders; RX_VK_DRIVER=kosmickrisp on a loader package

	Before: main @ aa95d35f	After: this PR @ 7df74b12
#491: test_darwin_renderer.py, test_darwin_audio_service.py	fail (no DarwinImportBacking, no WaveAudioOpenFn route)	pass, arm64 and x86_64: 133,262 startup/ABI/resource checks, 688 import-owner checks, 352 startup allocation failures each rolled back
#642: renderer's GPU allowance (game)	53,084 MB, the driver's (run #23)	10,160-15,881 MB (run #24), 10.2-20.8 GB (run #26), every line read the system
#653: denied Metal cache opens (game)	about 1.5 per compile (run #4)	0 (runs #5-#8); a second process made each pipeline 83x faster from the folder (2.6 against 214.8 ms, probe)
#654: start-up precompile through the loader (game)	(MoltenVK loaded directly)	MoltenVK: 38,809 of 38,809 in 58.0 s, title reached (run #21); KosmicKrisp: 1,607 of 38,809 in 1,770 s, no title (run #20)
full game-free suite on this Mac	543 passed, 33 failed, 17 skipped	576 passed, 15 failed, 17 skipped

c2-renderer-both: PASS: 352 exact startup allocation failures, Apple25 typed host callback wiring, serial/parallel resources and rollback; no Vulkan driver
c2-admission-x86_64: PASS: fixed non-Apple ABI: version 23, size 368, all 46 named offsets; Apple version 25, size 400, typed callbacks at 368/376/384/392
c2-unified-x86_64: unified_budget: all checks passed
#24 (e7730869): allowed 14547 MB (driver 53084; by RAM 37282; by free 14547: 0 in use, 22739 available - 8192 kept)

Flags and settings

Three new macOS switches and two optional macOS build inputs; none is read on Windows or Linux.

Flag	What it is	Before this PR	After this PR	Effect	Helps / doesn't help / untested	Recommendation
RX_VK_UNIFIED_BUDGET	=0: the GPU's allowance is the driver's again	(no switch; the driver's allowance)	on, on a Mac's unified memory; ignored elsewhere	the renderer's budgets follow what the Mac has free; the vk: unified memory line	helps: a Mac under memory pressure; doesn't help: memory Metal or MoltenVK hold themselves; untested: Macs with 8-32 GB, KosmicKrisp	on for everyone on macOS; =0 only to compare
RX_VK_METAL_CACHE_DIR=<folder>	the folder Metal keeps its shader cache in	(no switch: Metal's per-user folder under /var/folders)	unset: unchanged; set: that folder, or a NOT applied line and unchanged	a sandboxed or carried start gets a warm Metal cache	helps: sandboxed starts, caches carried between runs; doesn't help: a normal player start; untested: a start that made a window first	off by default; set it for sandboxed or reproducible runs
RX_VK_DRIVER	macOS: kosmickrisp or moltenvk, the packaged driver the loader is given	(no switch)	unset: MoltenVK	which driver runs on a loader package	kosmickrisp: measurement only (run #20 did not reach the title)	unset
LONGSHOT_VULKAN_LOADER	macOS build input: LunarG's libvulkan.1.dylib	not read	optional, unset	packaged with a manifest per driver; the game picks the driver at startup	lets one package carry both drivers; MoltenVK through the loader ran starts #21-#26	set it (with MoltenVK) for packages that should measure KosmicKrisp
LONGSHOT_KOSMICKRISP	macOS build input: the SDK's libvulkan_kosmickrisp.dylib	not read	optional, unset; arm64 builds only, needs the loader	packages KosmicKrisp and its manifest	only for measuring KosmicKrisp	arm64 measurement builds only

Testing

Tested: on macOS 26.7.1, Apple M4 Max, at this head 7df74b12 (a clean worktree):

• The four member pull requests' own tests, deduplicated, on arm64 and on x86_64 under Rosetta (each test's --arch x86_64
  or its fixture built with clang++ -arch x86_64): test_vk_darwin_admission (each arch), test_darwin_audio_service and
  test_darwin_renderer (both arches in one run), test_unified_budget, test_metal_cache_dir, test_display_startup_failure,
  test_vk_darwin_sdl, test_vendor_fixes (each arch), test_macos_build_flags and test_macos_package (both arches in one
  run, and the VulkanDriverPackage cases), and #491's 12 named checks through tests/run_all.py (arm64): 18 runs, 18 exit 0
  (admission: Apple version 25, size 400, the non-Apple ABI main's version 23, size 368; package 29 tests OK; build flags 16
  tests OK; 12 passed, 0 failed).
• python -I -B tests/run_all.py through tools/ls-suite.py at this head: 576 passed, 15 failed, 17 skipped, against main
  aa95d35f's 543/33/17 on this Mac, compared by test name: no check that passes on main fails here. Against topic 1's head
  (572/15/17) the only differences are this PR's four new tests, passing (test_darwin_audio_service, test_darwin_renderer,
  test_metal_cache_dir, test_unified_budget); against main, topic 1's differences as its description lists them (11 new
  tests, 17 checks fixed, test_appimage_package_retry skipped on macOS, test_dav1d_av1 running). The 15 failures fail on main
  too, on this Mac: test_readback_late, test_appimage_player_build, test_options_budget_once, test_vk_pgo,
  test_crash_dialog, test_walk_key, test_lift_cleanup_error, test_game_layout, test_options_path,
  test_make_game_cache, test_cpm_discovery, test_pipeline_tour, test_linux_preflight, test_env_on, test_split_giants.
• The renderer's link check at this head (each mkwvk:: name one gpu/vk file declares and another defines; each defining
  .cpp compiled with the tree's own renderer_flags(), arm64 and x86_64): 0 of 597 declared names lack a definition, 66 of
  66 objects compiled, 544 cross-file symbols per architecture all defined.
• Off Apple (unifdef -U__APPLE__ of every changed non-test C/C++ file against topic 1's head, compared as tokens): the
  differences are #491's stated every-platform parts: vk_replay.cpp (replay_start_rollback), vk_vma.cpp
  (vma_startup_rollback, the allocator published after it is made), vk_internal.h (their declarations), vk_recorder.h
  and vk_work.h (the vmaDestroyAllocator boundary), vk_memory.cpp (move-only pools, destroy_import()) and
  host/posix/win32_posix.c (Linux: MessageBoxA's dlclose, waveOutOpen's checks); and #642's vk_texture.cpp, whose
  only difference is const uint64_t keep_now = keep; used where keep was, the same value. The four new headers
  (darwin_import.h, system_memory.h, unified_budget.h, metal_cache.h) are included only inside __APPLE__ blocks;
  vk_api.h, vk_main.cpp, hos_main.c, hos_sdl.c, hos_sdl.h, darwin_vulkan.c, darwin_vulkan.h and rx_backend.c
  are the base's text there.
• macOS game runs with these commits in the stack (integration builds carrying this topic's members): arm64, windowless: run
  E9a on I41 78ec1c47: a 1,197 s hold in play, 12 of 12 must-shows, 0 skipped draws, a clean end
  (reports/2026-11-15-mac-perf-E9.md); x86_64 under Rosetta: run #34 on I38 3f872b0c: 16 m 52 s of play, every draw
  drawn, 19 of 19 checks, a clean exit (reports/2026-11-14-mac-startup-34-x86_64.md).

Not tested: Windows and Linux: nothing was built or run there (the test request below), so neither a startup that fails
part-way there nor the recorder modes (RX_VK_RECORDER=defer/thread) through such a failure; a real Vulkan device on this
head (the tests use recording stand-ins); a Mac with 8-32 GB of RAM, where the allowance gives back early; a start that makes
its window before the renderer loads Vulkan (RX_VK_METAL_CACHE_DIR would log NOT applied); KosmicKrisp beyond run #20;
macOS 14.4 and 15 (the deployment target is 14.4; every run was on 26.7.1); an Intel Mac.

Must be tested:

• Windows and Linux, any GPU: build this PR and main aa95d35f the same way, run python -I -B tests/run_all.py on each and
  start each to the title, expecting the new test_darwin_renderer, test_darwin_audio_service, test_unified_budget and
  test_metal_cache_dir to pass or skip with their macOS reason, no other check to change status, and the vk: lines to match
  main's (Test Farm: @Beanstalk windows linux, build, run_all and start to the title)

Risks

What could break: every platform: the startup rollback runs only after a failed startup, and the import moves and
queue-slot order keep the same owners and release calls; the recorder boundary costs a relaxed load and a branch with the
recorder off. These touch the renderer's import path, which nobody has run in a game on Windows or Linux. macOS: a Mac short
of memory gives textures, spare capture buffers and idle staging back sooner (a re-upload hitch; floor 1 GB); a package built
with the loader now loads MoltenVK through it (system-wide implicit layers load, as for any Vulkan app).

Turning it off: RX_VK_UNIFIED_BUDGET=0; leave RX_VK_METAL_CACHE_DIR and RX_VK_DRIVER unset; build without
LONGSHOT_VULKAN_LOADER; otherwise revert the PR.

Compatibility: saves, longshot_options.ini and the shader and pipeline caches are unchanged (none of the changed files
is in the translator's stamp; vk_api.h is not hashed since #370). The vk ABI: MKWVK_API_VERSION is 25 on macOS only (two
callbacks appended to MkwVkHost): the macOS executable and renderer are built together; Windows and Linux keep main's 23 with
the same structure. On macOS new log lines appear (vk: unified memory, the cache check, the driver choice); switching to
KosmicKrisp starts a new pipeline cache.

Issues

See #420. The macOS topic PRs, merged in this order; "topic N" in each description means these: 1 #845 (macos-host), 2 #846 (vulkan-on-metal, on 1), 3 #847 (mvk-descriptor-limits), 4 #848 (shader-backend, on 2, 3 and #431), 5 #849 (precompile-metal, on 4), 6 #850 (draw-path, on 4), 7 #851 (draw-path-quads-mesh, on 6, #705 and #707), 8 #852 (mac-perf, on 7).

Checklist

Everyone

• One topic.
• The title is a Conventional Commit (type(scope): description) of the status line's type.
• Why gives the reason plainly and links the issues that fit (the tracker searched).
• Measurements has a verdict, or one line saying why there is nothing to measure.
• Testing names what was tested, what wasn't, and what must still be tested, where and how.
• Rebased on current main: on aa95d35f (through topic 1).
• python -I -B tests/run_all.py passes (any failure that also fails on main is named). (macOS: 576/15/17, the 15 failures also fail on main, named under Testing; Windows and Linux: the test request.)
• No game files, dumps, build output or generated files.
• third_party/ untouched (a new folder with a PROVENANCE.md instead).
• The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

• AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
• Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
• MKWVK_API_VERSION bumped (gpu/vk/vk_api.h's MkwVkHost or MkwVkRenderer changed).
• A game-free test added for the fix, failing on main and passing here.
• A check under tests/ that reads changed source updated in this PR, not weakened.
• Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Not built there yet: the test request.)
• Docs updated.

**Type:** feat · **Risk:** medium · **Tested on:** macOS 26.7.1, Apple M4 Max (arm64; x86_64 under Rosetta) · **Needs:** Windows and Linux, any GPU ## Why On a Mac the game's Vulkan renderer runs on Metal through a driver (MoltenVK, or KosmicKrisp through the Vulkan loader), and four things it needs there were missing. Guest memory imported into Vulkan could be replaced or discarded while the GPU still used it, and a renderer whose startup failed part-way left what it had made behind (on every platform). The GPU has no memory of its own on a Mac, yet the renderer took Metal's recommended working set (53 GB on a 64 GB Mac) as its allowance, so nothing gave memory back while the Mac ran out (run #22 lost the device). Metal keeps its compiled shader cache under `/var/folders`, which a sandboxed start cannot open, so every start compiled every pipeline again. And the macOS package carried MoltenVK only, so KosmicKrisp, LunarG's conformant Vulkan 1.4 driver on Metal, could not be measured. This PR is that layer of the macOS port, on top of the macOS host (the topic before it). See #420. ## What changed Every macOS host import is pinned in the executable until its last Vulkan owner is gone, and a failed startup gives back what it made (that rollback, the recorder's drain before it and the move-only import owners apply on every platform); on a Mac's unified memory the renderer's GPU allowance follows what the Mac has free; `RX_VK_METAL_CACHE_DIR` points Metal's cache at a chosen folder; and the macOS package can carry the Vulkan loader with MoltenVK (the default) and KosmicKrisp (opt-in, `RX_VK_DRIVER=kosmickrisp`). The four original pull requests, in commit order: - import pins and startup rollback (`c1fa25a4`; Was: [#491](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/491)): macOS: `DarwinImportBacking` and the move-only `DarwinImportView` in `gpu/vk/vk_memory.cpp` (range arithmetic in the new `gpu/vk/darwin_import.h`) pin each import's whole backing through two new `MkwVkHost` callbacks (`gpu/vk/vk_api.h`, Apple `MKWVK_API_VERSION` 25; Windows and Linux keep main's 23), filled by `host/rx_backend.c`; `host/posix/win32_posix.c`'s `waveOutOpen` resolves the executable's audio service (`host/hos_sdl.c`) instead of a weak import. Every platform: `replay_start_rollback()` in `gpu/vk/vk_replay.cpp` and `vma_startup_rollback()` in `gpu/vk/vk_vma.cpp` unwind a failed startup; `vmaDestroyAllocator` is a recorder drain boundary (`gpu/vk/vk_recorder.h`, `vk_work.h`); import pools are moved, not copied, with one `destroy_import()`; on Linux `MessageBoxA` closes its extra `dlopen` reference and `waveOutOpen` checks its allocations. Tests: `tests/test_darwin_renderer.py`, `tests/test_darwin_audio_service.py` (new); eight existing checks that build `vk_memory.cpp` or the audio route follow the moved `Pool` and the new callbacks. - the unified-memory budget (`45e1d666`; Was: [#642](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/642)): on a Mac's unified memory `vram_usage()` in `gpu/vk/vk_vma.cpp` answers the least of the driver's allowance, RAM less this process's CPU memory less a reserve, and what the GPU holds plus what the system has available less a margin (`gpu/vk/system_memory.h` and `gpu/vk/unified_budget.h`, new); spare capture buffers (`vk_memory.cpp`) and idle staging (`unified_memory_watch()` in `vk_texture.cpp`) are not kept past 90% of it; a `vk: unified memory` line splits the GPU's memory into the renderer's and Metal's own. All inside `__APPLE__`; `RX_VK_UNIFIED_BUDGET=0` turns it off. Test: `tests/test_unified_budget.py` (new). - Metal's cache folder (`01630d4b`; Was: [#653](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/653)): `RX_VK_METAL_CACHE_DIR=<folder>` (macOS only, off by default) hands the folder to Metal before the Vulkan library loads and logs after the device whether Metal took it (`gpu/vk/metal_cache.h`, new; `gpu/vk/vk_main.cpp`). Test: `tests/test_metal_cache_dir.py` (new). - the Vulkan loader with KosmicKrisp and MoltenVK (`7df74b12`; Was: [#654](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/654)): with the optional build inputs `LONGSHOT_VULKAN_LOADER` (and `LONGSHOT_KOSMICKRISP`, arm64) the macOS package carries LunarG's loader and each driver with a manifest beside it, and at startup `host/posix/darwin_vulkan.c` and `host/hos_main.c` point the loader at MoltenVK unless `RX_VK_DRIVER=kosmickrisp`; without the loader input the package is as before (`nx2/darwin_build.py`, `nx2/darwin_package.py`). Tests: `tests/test_vk_darwin_admission.py` (the driver choice, 27 cases), `tests/test_macos_package.py`, `tests/display_startup_failure_test.cpp`. - docs: `docs/development.md` (the switches' rows and the macOS build inputs), `gpu/vk/VULKAN.md`. ## Measurements **Verdict:** works. The members' tests fail on main (or are new) and pass here on arm64 and on x86_64 under Rosetta; in the macOS port's game runs (integration builds) the allowance read the system (10.2-20.8 GB against the driver's 53,084 MB), Metal took the chosen cache folder in every start that set it (denied cache opens from about 1.5 per compile to 0), and MoltenVK through the packaged loader prepared all 38,809 programs in 58.0 s while KosmicKrisp prepared 1,607 in 1,770 s and never reached the title (so MoltenVK stays the default). The full suite at this head: 576 passed, 15 failed, 17 skipped against main's 543/33/17 on this Mac (and topic 1's 572/15/17), with no check failing that passes on main. Baseline: the game rows are the macOS port's integration builds, arm64, MoltenVK 1.4.2 (main does not run on macOS): the allowance, before integration `552cc3d4` (run #23, whose read gate never opened: the driver's allowance, as main), after `e7730869` and `6962f8fb` (runs #24, #26); the cache, before `aefe6b0a` (run #4), after `f32adfa2` and `a7711f3c` (runs #5-#8); the drivers, one build `09f9a171` with both drivers packaged (run #20 KosmicKrisp, run #21 MoltenVK). The game-free rows compare with main (the tests do not exist there, or fail there) and run at this head. Hardware: macOS 26.7.1, Apple M4 Max (40-core GPU), MoltenVK 1.4.2, KosmicKrisp from LunarG's Vulkan SDK 1.4.363.1, 16-core CPU, 64 GB Scene: game-free fixtures; the game rows: Hyrule Field from the field-dawn save (the allowance), the start-up precompile and the title (the cache and the drivers), windowless, defaults Method: each member's test before and after (two interleaved runs in the members' own runs); at this head each once per architecture; the game rows: the `vk: unified memory`, cache and precompile lines of each run's longshot_log.txt, one run each How to reproduce: the tests under Testing; `RX_VK_UNIFIED_BUDGET=0` gives the old allowance on the same build; `RX_VK_METAL_CACHE_DIR=<folder>` in a sandbox that denies `/var/folders`; `RX_VK_DRIVER=kosmickrisp` on a loader package | | Before: main @ aa95d35f | After: this PR @ 7df74b12 | |---|---|---| | #491: `test_darwin_renderer.py`, `test_darwin_audio_service.py` | fail (no `DarwinImportBacking`, no `WaveAudioOpenFn` route) | pass, arm64 and x86_64: 133,262 startup/ABI/resource checks, 688 import-owner checks, 352 startup allocation failures each rolled back | | #642: renderer's GPU allowance (game) | 53,084 MB, the driver's (run #23) | 10,160-15,881 MB (run #24), 10.2-20.8 GB (run #26), every line read the system | | #653: denied Metal cache opens (game) | about 1.5 per compile (run #4) | 0 (runs #5-#8); a second process made each pipeline 83x faster from the folder (2.6 against 214.8 ms, probe) | | #654: start-up precompile through the loader (game) | (MoltenVK loaded directly) | MoltenVK: 38,809 of 38,809 in 58.0 s, title reached (run #21); KosmicKrisp: 1,607 of 38,809 in 1,770 s, no title (run #20) | | full game-free suite on this Mac | 543 passed, 33 failed, 17 skipped | 576 passed, 15 failed, 17 skipped | ``` c2-renderer-both: PASS: 352 exact startup allocation failures, Apple25 typed host callback wiring, serial/parallel resources and rollback; no Vulkan driver c2-admission-x86_64: PASS: fixed non-Apple ABI: version 23, size 368, all 46 named offsets; Apple version 25, size 400, typed callbacks at 368/376/384/392 c2-unified-x86_64: unified_budget: all checks passed #24 (e7730869): allowed 14547 MB (driver 53084; by RAM 37282; by free 14547: 0 in use, 22739 available - 8192 kept) ``` ### Flags and settings Three new macOS switches and two optional macOS build inputs; none is read on Windows or Linux. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `RX_VK_UNIFIED_BUDGET` | `=0`: the GPU's allowance is the driver's again | (no switch; the driver's allowance) | on, on a Mac's unified memory; ignored elsewhere | the renderer's budgets follow what the Mac has free; the `vk: unified memory` line | helps: a Mac under memory pressure; doesn't help: memory Metal or MoltenVK hold themselves; untested: Macs with 8-32 GB, KosmicKrisp | on for everyone on macOS; `=0` only to compare | | `RX_VK_METAL_CACHE_DIR=<folder>` | the folder Metal keeps its shader cache in | (no switch: Metal's per-user folder under `/var/folders`) | unset: unchanged; set: that folder, or a `NOT applied` line and unchanged | a sandboxed or carried start gets a warm Metal cache | helps: sandboxed starts, caches carried between runs; doesn't help: a normal player start; untested: a start that made a window first | off by default; set it for sandboxed or reproducible runs | | `RX_VK_DRIVER` | macOS: `kosmickrisp` or `moltenvk`, the packaged driver the loader is given | (no switch) | unset: MoltenVK | which driver runs on a loader package | `kosmickrisp`: measurement only (run #20 did not reach the title) | unset | | `LONGSHOT_VULKAN_LOADER` | macOS build input: LunarG's `libvulkan.1.dylib` | not read | optional, unset | packaged with a manifest per driver; the game picks the driver at startup | lets one package carry both drivers; MoltenVK through the loader ran starts #21-#26 | set it (with MoltenVK) for packages that should measure KosmicKrisp | | `LONGSHOT_KOSMICKRISP` | macOS build input: the SDK's `libvulkan_kosmickrisp.dylib` | not read | optional, unset; arm64 builds only, needs the loader | packages KosmicKrisp and its manifest | only for measuring KosmicKrisp | arm64 measurement builds only | ## Testing **Tested:** on macOS 26.7.1, Apple M4 Max, at this head `7df74b12` (a clean worktree): - The four member pull requests' own tests, deduplicated, on arm64 and on x86_64 under Rosetta (each test's `--arch x86_64` or its fixture built with `clang++ -arch x86_64`): `test_vk_darwin_admission` (each arch), `test_darwin_audio_service` and `test_darwin_renderer` (both arches in one run), `test_unified_budget`, `test_metal_cache_dir`, `test_display_startup_failure`, `test_vk_darwin_sdl`, `test_vendor_fixes` (each arch), `test_macos_build_flags` and `test_macos_package` (both arches in one run, and the `VulkanDriverPackage` cases), and #491's 12 named checks through `tests/run_all.py` (arm64): 18 runs, 18 exit 0 (admission: Apple version 25, size 400, the non-Apple ABI main's version 23, size 368; package 29 tests OK; build flags 16 tests OK; 12 passed, 0 failed). - `python -I -B tests/run_all.py` through `tools/ls-suite.py` at this head: 576 passed, 15 failed, 17 skipped, against main `aa95d35f`'s 543/33/17 on this Mac, compared by test name: no check that passes on main fails here. Against topic 1's head (572/15/17) the only differences are this PR's four new tests, passing (`test_darwin_audio_service`, `test_darwin_renderer`, `test_metal_cache_dir`, `test_unified_budget`); against main, topic 1's differences as its description lists them (11 new tests, 17 checks fixed, `test_appimage_package_retry` skipped on macOS, `test_dav1d_av1` running). The 15 failures fail on main too, on this Mac: `test_readback_late`, `test_appimage_player_build`, `test_options_budget_once`, `test_vk_pgo`, `test_crash_dialog`, `test_walk_key`, `test_lift_cleanup_error`, `test_game_layout`, `test_options_path`, `test_make_game_cache`, `test_cpm_discovery`, `test_pipeline_tour`, `test_linux_preflight`, `test_env_on`, `test_split_giants`. - The renderer's link check at this head (each `mkwvk::` name one `gpu/vk` file declares and another defines; each defining `.cpp` compiled with the tree's own `renderer_flags()`, arm64 and x86_64): 0 of 597 declared names lack a definition, 66 of 66 objects compiled, 544 cross-file symbols per architecture all defined. - Off Apple (`unifdef -U__APPLE__` of every changed non-test C/C++ file against topic 1's head, compared as tokens): the differences are #491's stated every-platform parts: `vk_replay.cpp` (`replay_start_rollback`), `vk_vma.cpp` (`vma_startup_rollback`, the allocator published after it is made), `vk_internal.h` (their declarations), `vk_recorder.h` and `vk_work.h` (the `vmaDestroyAllocator` boundary), `vk_memory.cpp` (move-only pools, `destroy_import()`) and `host/posix/win32_posix.c` (Linux: `MessageBoxA`'s `dlclose`, `waveOutOpen`'s checks); and #642's `vk_texture.cpp`, whose only difference is `const uint64_t keep_now = keep;` used where `keep` was, the same value. The four new headers (`darwin_import.h`, `system_memory.h`, `unified_budget.h`, `metal_cache.h`) are included only inside `__APPLE__` blocks; `vk_api.h`, `vk_main.cpp`, `hos_main.c`, `hos_sdl.c`, `hos_sdl.h`, `darwin_vulkan.c`, `darwin_vulkan.h` and `rx_backend.c` are the base's text there. - macOS game runs with these commits in the stack (integration builds carrying this topic's members): arm64, windowless: run E9a on I41 `78ec1c47`: a 1,197 s hold in play, 12 of 12 must-shows, 0 skipped draws, a clean end (`reports/2026-11-15-mac-perf-E9.md`); x86_64 under Rosetta: run #34 on I38 `3f872b0c`: 16 m 52 s of play, every draw drawn, 19 of 19 checks, a clean exit (`reports/2026-11-14-mac-startup-34-x86_64.md`). **Not tested:** Windows and Linux: nothing was built or run there (the test request below), so neither a startup that fails part-way there nor the recorder modes (`RX_VK_RECORDER=defer`/`thread`) through such a failure; a real Vulkan device on this head (the tests use recording stand-ins); a Mac with 8-32 GB of RAM, where the allowance gives back early; a start that makes its window before the renderer loads Vulkan (`RX_VK_METAL_CACHE_DIR` would log `NOT applied`); KosmicKrisp beyond run #20; macOS 14.4 and 15 (the deployment target is 14.4; every run was on 26.7.1); an Intel Mac. **Must be tested:** - Windows and Linux, any GPU: build this PR and main `aa95d35f` the same way, run `python -I -B tests/run_all.py` on each and start each to the title, expecting the new `test_darwin_renderer`, `test_darwin_audio_service`, `test_unified_budget` and `test_metal_cache_dir` to pass or skip with their macOS reason, no other check to change status, and the `vk:` lines to match main's (Test Farm: @Beanstalk windows linux, build, run_all and start to the title) ## Risks **What could break:** every platform: the startup rollback runs only after a failed startup, and the import moves and queue-slot order keep the same owners and release calls; the recorder boundary costs a relaxed load and a branch with the recorder off. These touch the renderer's import path, which nobody has run in a game on Windows or Linux. macOS: a Mac short of memory gives textures, spare capture buffers and idle staging back sooner (a re-upload hitch; floor 1 GB); a package built with the loader now loads MoltenVK through it (system-wide implicit layers load, as for any Vulkan app). **Turning it off:** `RX_VK_UNIFIED_BUDGET=0`; leave `RX_VK_METAL_CACHE_DIR` and `RX_VK_DRIVER` unset; build without `LONGSHOT_VULKAN_LOADER`; otherwise revert the PR. **Compatibility:** saves, `longshot_options.ini` and the shader and pipeline caches are unchanged (none of the changed files is in the translator's stamp; `vk_api.h` is not hashed since #370). The vk ABI: `MKWVK_API_VERSION` is 25 on macOS only (two callbacks appended to `MkwVkHost`): the macOS executable and renderer are built together; Windows and Linux keep main's 23 with the same structure. On macOS new log lines appear (`vk: unified memory`, the cache check, the driver choice); switching to KosmicKrisp starts a new pipeline cache. ## Issues See #420. The macOS topic PRs, merged in this order; "topic N" in each description means these: 1 #845 (macos-host), 2 #846 (vulkan-on-metal, on 1), 3 #847 (mvk-descriptor-limits), 4 #848 (shader-backend, on 2, 3 and #431), 5 #849 (precompile-metal, on 4), 6 #850 (draw-path, on 4), 7 #851 (draw-path-quads-mesh, on 6, #705 and #707), 8 #852 (mac-perf, on 7). ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`: on `aa95d35f` (through topic 1). - [ ] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). (macOS: 576/15/17, the 15 failures also fail on main, named under Testing; Windows and Linux: the test request.) - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [x] `MKWVK_API_VERSION` bumped (`gpu/vk/vk_api.h`'s `MkwVkHost` or `MkwVkRenderer` changed). - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Not built there yet: the test request.) - [x] Docs updated.

mooki added 21 commits 2026-11-15 17:39:40 +00:00

test: teach the game-free runner about macOS ... e81d4af47a

Was: #454 (#454), branch mac/run-all at 264f826a7c (Sweep3, on main aa95d35f).

Its own commits, squashed:
- test: teach the game-free runner about macOS (45c54bc6f)
- test: skip main's new Windows-only guard check on macOS, and undo the SDK's vsnprintf macro in a fixture (264f826a7)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(runtime): compile host jumps and pause hints on macOS arm64 ... 441182e2c2

Was: #477 (#477), branch mac/arm64-host at 0f021f29c1 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(runtime): compile host jumps and pause hints on macOS arm64 (0f021f29c)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(runtime): preserve guest pages when discarding on macOS ... 10e52402b7

Was: #478 (#478), branch mac/guest-memory at dfb71ec850 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(runtime): preserve guest pages when discarding on macOS (b668404c8)
- fix(runtime): retain guest-page rounding in Darwin memory wrappers (e9c77d9f3)
- test(runtime): cut main's int hos_commit in the Darwin guest-memory test (7e737ce0f)
- test(runtime): follow main's HLE call counts in the Darwin guest-memory fixture (dfb71ec85)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(runtime): translate macOS fault contexts on both CPU routes ... 9784b1b5a6

Was: #436 (#436), branch mac/fault-contexts at bccfd1c2e9 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(runtime): translate macOS fault contexts on both CPU routes (08940fb3d)
- test(runtime): keep Darwin fault checks native by default (7d7f99dcb)
- test(runtime): classify the fault bridge's fatal _exit in main's exit inventory (bccfd1c2e)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(runtime): add macOS waits and deadlines, shared by host and renderer ... a492f0ac52

Was: #437 (#437), branch mac/waits at beb8a2881a (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(runtime): port Win32 waits and deadlines to macOS (2f05d007f)
- test(runtime): link Darwin waits into the pointer fixture (ef081688d)
- fix(macos): share address wait state through the executable (186a461c5)
- docs(runtime): describe the executable-owned macOS address-wait state (beb8a2881)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

feat(vk): add macOS Vulkan loader and device admission ... 58bdbdc027

Was: #438 (#438), branch mac/vk-admission at 681e37081d (Sweep3, on main aa95d35f).

Its own commits, squashed:
- feat(vk): add macOS Vulkan loader and device admission (6f34d00bc)
- test(vk): use semantic admission contracts (fdd161190)
- test(vk): follow main's LoadLibraryA and float-add choice in the admission fixture (3e088644f)
- test(vk): pin the admission ABI at main's version 23 and macOS 24 (4f4ca3c73)
- fix(macos): a window without Vulkan extensions ends as a clean exit, as main's exit inventory asks (681e37081)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

feat(macos): native Darwin threads, fibers, restart, process I/O and profiler ... 6e36141173

Was: #490 (#490), branch mac/darwin-host at 162a39dcd3 (Sweep3, on main aa95d35f).

It was stacked on #436, #437, #438, #454, #477, #478; their changes are the earlier commits here.

Its own commits, squashed:
- feat(macos): complete Darwin host lifecycle and diagnostics (71a9ed0bb)
- fix(macos): integrate profile consumers and joined-thread shutdown (f420761ab)
- docs(macos): describe Darwin profile symbol loading (04e40191a)
- test(macos): integration fix: cut the tagged HThread in the waits fixture (9c18e64c4)
- test(macos): integration fix: stub the kept startup in the display fixture (5f8d511e6)
- test(macos): integration fix: prof symbols run on macOS, not a skip (a1e73d31e)
- test(macos): the memory-notice fixture runs the Darwin query (f4d7aaf76)
- fix(macos): a failed swap query still shows the low-RAM notice (28ed288a2)
- test(macos): the Darwin LoadLibraryA keeps dlerror()'s text for hos_load_error (52faf1d3d)
- fix(macos): integration fix: main's process affinity for new threads is Linux-only (61ec2411b)
- fix(macos): the POSIX main's end after the game's thread marks the clean end, as main's exit inventory asks (162a39dcd)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

build(macos): discover dual-architecture toolchains and form Mach-O commands ... f68637f873

Was: #453 (#453), branch mac/build-flags at 8ca4bff7a4 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- build(macos): discover dual-architecture toolchains and form Mach-O commands (499e3853a)
- test(macos): default real link fixtures to the process architecture (f6f6f042c)
- test(macos): isolate synthetic command paths from the test host (7c846ae91)
- build(macos): keep third_party/a64-kit as it is; nx2/darwin_toolchain.py makes its commands Mach-O (88054c966)
- build(macos): follow main's one-way renderer build and CPU target in the moved build code (a5b02633d)
- test(macos): the frozen Windows/Linux build arrays are main e090cc48's (c3009e01c)
- test: main's third-party objects test reads build.py with this PR's macOS names (8ca4bff7a)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

build(macos): classify Darwin helpers and package a relocatable macOS 14.4 dylib set ... 9a1094dac0

Was: #479 (#479), branch mac/build-complete at 1bd269c7e2 (Sweep3, on main aa95d35f).

It was stacked on #437, #453; their changes are the earlier commits here.

Its own commits, squashed:
- build(macos): complete strict standalone dependency packaging (9424b4886)
- fix(macos): bind SDL3, imports and archive members to their real formats (8ad0e3265)
- fix(macos): keep the lazy-bind library ordinal across DONE (48f6ec02b)
- build(macos): take the architecture and SDK from darwin_toolchain when packaging (5ce85548c)
- build(macos): no prebuilt renderer on macOS either, as main has none (1bd269c7e)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(builder): account for available memory and compiler children on macOS ... 2540028349

Was: #455 (#455), branch mac/mem-gate at 82c2e10341 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(builder): account for available memory and compiler children on macOS (8f8e03b7f)
- fix(builder): avoid stale Darwin available-memory snapshots (5240e431a)
- fix(builder): keep Darwin RSS behind the shared tree backend (82c2e1034)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(runtime): support control bridge Unix sockets on macOS ... 1b3354a0e7

Was: #456 (#456), branch mac/control-sockets at fc2f104050 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(runtime): support control bridge Unix sockets on macOS (5fc3fe390)
- test(control): link the bridge's macOS socket helpers into test_oot_state_tap's fixture (fc2f10405)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

test(control): wait until the bridge listens, and reap it when a quit check fails ... 68d940cae0

Was: #457 (#457), branch mac/control-quit at fe3e8c9178 (Sweep3, on main aa95d35f).

It was stacked on #456; their changes are the earlier commits here.

Its own commits, squashed:
- test(control): quit's parent waits for its bridge to listen, and a failed check ends the bridge it forked (fe3e8c917)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(vk): preserve cache file reservations on macOS ... eb8d5573f6

Was: #476 (#476), branch mac/cache-files at 7e561fbb53 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(vk): preserve cache file reservations on macOS (7e561fbb5)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(macos): serialize guest memory ownership on 16 KiB pages and pin imported backing ... 570a527793

Was: #480 (#480), branch mac/guest-16k at 657b780359 (Sweep3, on main aa95d35f).

It was stacked on #436, #478; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(macos): serialize guest backing and native-page watch lifetimes (d7d999b92)
- fix(macos): retain pending watch faults across protection changes (a6a3e9e98)
- fix(macos): make the guest-memory changes Apple-only; Windows and Linux keep main's code (126d7bd67)
- docs(macos): describe the guest window's one owner, import pins and native-page watches (657b78035)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(macos): build vk_programs, vk_shader and the debug tools on Darwin ... 98c070dcfd

Was: #492 (#492), branch mac/renderer-compile at 59f750aa38 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(macos): the renderer's last two files compile on Darwin (7ee5fd584)
- fix(macos): the debug tools are compiled on Darwin too (82b2d6606)
- test(macos): the debug tools check reads hos_oot_player_seen's body too (59f750aa3)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(runtime): build and keep crash records on macOS ... e5a1034360

Was: #511 (#511), branch mac/crash-records at c4d95017aa (Sweep3, on main aa95d35f).

It was stacked on #436; their changes are the earlier commits here.

Its own commits, squashed:
- fix(runtime): take the macOS report run id from getentropy (d3e86ddd7)
- fix(runtime): read crash-record memory and modules without /proc on macOS (aa039e142)
- test(runtime): build the crash-record fixture on macOS (adebf9dbb)
- test(runtime): link the macOS fault bridge into the crash-record fixture (c4d95017a)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(control): keep command-line sessions alive on macOS ... 40c1c5f5f8

Was: #516 (#516), branch mac/longshot-ctl-darwin at 3b9d3cfa2a (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(control): tell macOS processes apart by their sysctl start time (56f4ca876)
- test(control): compare launch's data folder with the resolved run folder (3b9d3cfa2)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(macos): pin Vulkan host imports until their last owner, and unwind failed startups ... c1fa25a4b2

Was: #491 (#491), branch mac/renderer-correctness at 695f6859dc (Sweep3, on main aa95d35f).

It was stacked on #438, #480; their changes are the earlier commits here.

Its own commits, squashed:
- fix(macos): pin renderer imports through final resource ownership (db82a0f23)
- test(macos): cut the non-Apple Pool and import route in three more fixtures (6cee76eb1)
- fix(vk): drain the recorder before startup rollback destroys the allocator (18c05be52)
- test(macos): follow main's #324 and #250 in the Darwin renderer fixture (c099f5da6)
- test(vk): follow the moved Pool in test_mirror_gpu_only's cut (165bf7e61)
- fix(macos): the import pin callbacks are macOS host API version 25 (fa691b55b)
- fix(macos): vk_memory.cpp compiles on macOS: #324's evicted_pools declaration is not Apple's (695f6859d)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(macos): on unified memory the GPU's allowance is what the Mac's RAM leaves, not Metal's working set ... 45e1d66607

Was: #642 (#642), branch mac/gpu-budget at 09978824a0 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- feat(vk): read the Mac's system memory for the renderer (gpu/vk/system_memory.h) (ba1952096)
- fix(macos): on unified memory the GPU's allowance is what the Mac's RAM leaves, not Metal's working set (632636ee0)
- fix(macos): vk_work.h stays vk_vma.cpp's last include (0e63a1dc1)
- fix(macos): the unified budget reads the system's memory at its first ask (5240eade7)
- docs(macos): RX_VK_UNIFIED_BUDGET in the switch table (09978824a)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

feat(macos): RX_VK_METAL_CACHE_DIR keeps Metal's shader cache in a chosen folder ... 01630d4b6e

Was: #653 (#653), branch mac/metal-cache at db50cf3d26 (Sweep3, on main aa95d35f).

It was stacked on #438; their changes are the earlier commits here.

Its own commits, squashed:
- feat(macos): Metal's shader cache in a folder the caller names (db50cf3d2)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

feat(macos): ship the Vulkan loader with KosmicKrisp and MoltenVK, MoltenVK the default ... 7df74b124d

Was: #654 (#654), branch mac/kosmickrisp at 9d34f9a1c8 (Sweep3, on main aa95d35f).

It was stacked on #438, #479; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- feat(macos): ship the Vulkan loader with KosmicKrisp and MoltenVK, chosen at startup (fbd562421)
- test(macos): the driver package fixture takes the architecture and SDK from darwin_toolchain (3472d670c)
- fix(macos): type the driver manifest's ICD record for Pyright (296b5347b)
- fix(macos): MoltenVK is the default Vulkan driver on every macOS (86c017e42)
- test(macos): the display fixture counts longshot_env.txt's loads on Apple only (9d34f9a1c)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>

BeanIssues added the

kind

feature

area/renderer

platform/macos

labels 2026-11-15 17:39:45 +00:00

mooki referenced this pull request 2026-11-15 17:41:20 +00:00

WIP: feat(macos): run the host on macOS: build, runtime, control, crash records and the Vulkan loader #845

mooki referenced this pull request 2026-11-15 17:41:28 +00:00

WIP: fix(vk): MoltenVK's descriptor limits in descriptor sets #847

mooki referenced this pull request 2026-11-15 17:41:31 +00:00

WIP: feat(vk): the SPIR-V back end on MoltenVK and guest spans past one device allocation #848

mooki referenced this pull request 2026-11-15 17:41:35 +00:00

WIP: fix(macos): MoltenVK's precompile and pipelines on Metal #849

mooki referenced this pull request 2026-11-15 17:41:40 +00:00

WIP: fix(macos): draw-path emulation on MoltenVK #850

mooki referenced this pull request 2026-11-15 17:41:44 +00:00

WIP: fix(macos): the Mac halves of indirect quads and mesh count draws #851

mooki referenced this pull request 2026-11-15 17:41:48 +00:00

WIP: perf(macos): Mac performance on MoltenVK #852

mooki referenced this pull request 2026-11-15 18:07:38 +00:00

fix(macos): pin Vulkan host imports until their last owner, and unwind failed startups #491

mooki referenced this pull request 2026-11-15 18:07:40 +00:00

fix(macos): on unified memory the GPU's allowance is what the Mac's RAM leaves, not Metal's working set #642

mooki referenced this pull request 2026-11-15 18:07:42 +00:00

feat(macos): RX_VK_METAL_CACHE_DIR keeps Metal's shader cache in a chosen folder #653

mooki referenced this pull request 2026-11-15 18:07:44 +00:00

feat(macos): ship the Vulkan loader with KosmicKrisp and MoltenVK, MoltenVK the default #654

mooki referenced this pull request 2026-11-15 18:14:44 +00:00

Idea: a native macOS build (Apple silicon, x86-64 under Rosetta) with Vulkan on Metal through MoltenVK #420

HumanBean commented 2026-11-15 18:49:15 +00:00

Owner

• Copy link
• Copy Markdown

This conflicts with main and is built on top of the macOS series (it carries the commits of #845 and others below it). nx2/build.py, nx2/make_game.py and docs/development.md conflict with #577 (the WebGPU renderer removed from the Windows build). Please rebase onto current main once its base PR #845 lands or is rebased; I didn't touch it because a rebase here would have to be redone after that.

This conflicts with `main` and is built on top of the macOS series (it carries the commits of https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/845 and others below it). `nx2/build.py`, `nx2/make_game.py` and `docs/development.md` conflict with https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/577 (the WebGPU renderer removed from the Windows build). Please rebase onto current `main` once its base PR https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/845 lands or is rebased; I didn't touch it because a rebase here would have to be redone after that.

Some checks failed

Hide checks

CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped

Details

CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped

Details

CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped

Details

Third-party parts / The same as upstream (pull_request) Has been skipped

Details

Website / Website on Cloudflare (pull_request_target) Has been skipped

Details

CI / Conventional Commit title (pull_request) Successful in 14s

Details

CI / Workflow lint (actionlint) (pull_request) Successful in 19s

Details

Guide screenshots / Guide images and local UI source review (pull_request) Failing after 17s

Details

Third-party parts / As their notes say (pull_request) Successful in 31s

Details

PR description / Description follows the template (pull_request_target) Successful in 22s

Details

This pull request has changes conflicting with the target branch.

• docs/development.md
• gpu/vk/vk_memory.cpp
• gpu/vk/vk_texture.cpp
• nx2/build.py
• nx2/make_game.py

View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Merge commit title WIP: feat(macos): Vulkan on Metal: pinned host imports, the unified-memory budget, Metal's cache folder and KosmicKrisp (#846)

Merge commit body Reviewed-on: https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/846

WIP: feat(macos): Vulkan on Metal: pinned host imports, the unified-memory budget, Metal's cache folder and KosmicKrisp (#846) Reviewed-on: https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/846 Copy merge commit message

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u 'mac/topic-vulkan-on-metal:mooki-mac/topic-vulkan-on-metal'

git switch 'mooki-mac/topic-vulkan-on-metal'

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area/accessibility

Barriers for people with disabilities

  

area/audio

Sound and music

  

area/input

Controllers, keyboard, mouse

  

area/install

Installing, updating, building from your game

  

area/menu

In-game menu and settings

  

area/renderer

Vulkan renderer, shaders, effects

  

area/saves

Save files

  

area/upscaling

DLSS, FSR, frame generation

  

beanstalk: approved @ 1697603

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 2c5a62e

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 4fd82b7

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 64d6d09

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 6f91fae

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 70a78f9

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 8d361dc

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 9d8356e

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ abf2227

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ d82f202

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ e5f1e40

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ ee8ab5f

Set by Beanstalk for show; the farm's database is what counts

  

ci: approved

A maintainer approved CircleCI for this fork PR (sticky; removed after 14 quiet days)

  

good first issue

A good start for a new contributor

  

gpu/amd

AMD GPUs

  

gpu/igpu

Integrated GPUs

  

gpu/intel

Intel GPUs

  

gpu/nvidia

NVIDIA GPUs

  

help wanted

Extra hands or knowledge wanted

  

kind

bug

Something doesn't work as it should

  

kind

chore

Build, CI, dependencies, tidying

  

kind

docs

Documentation

  

kind

feature

A new feature or an improvement

  

kind

performance

Frame rate, frame time, loading, memory

  

kind

question

A question rather than a change

  

needs measurements

Waiting for before/after measurements

  

platform/linux

Affects Linux (a change for every system carries both Windows and Linux)

  

platform/macos

macOS (Apple silicon or Intel Macs)

  

platform/steam-deck

Steam Deck

  

platform/windows

Affects Windows (a change for every system carries both Windows and Linux)

  

preview

Maintainers: deploy a preview of this PR's website (read its changes first). Removed after the run.

  

priority

critical

Crashes, data loss, or blocks most players

  

priority

high

Important: next in line

  

priority

low

Nice to have

  

regression

Worked in an earlier build, broken in a newer one: highest priority, above other bugs

  

status

blocked

Waits on something else first

  

status

confirmed

Reproduced or agreed on

  

status

duplicate

Already reported or proposed

  

status

invalid

Not a problem in this project

  

status

needs-info

Waiting for more information from the reporter

  

status

wontfix

Will not be worked on

  

testing wanted

Wanted: a test on other hardware (posts a test request in #test-requests)

  

ci: approved

No labels

area/accessibility

area/audio

area/input

area/install

area/menu

area/renderer

area/saves

area/upscaling

beanstalk: approved @ 1697603

beanstalk: approved @ 2c5a62e

beanstalk: approved @ 4fd82b7

beanstalk: approved @ 64d6d09

beanstalk: approved @ 6f91fae

beanstalk: approved @ 70a78f9

beanstalk: approved @ 8d361dc

beanstalk: approved @ 9d8356e

beanstalk: approved @ abf2227

beanstalk: approved @ d82f202

beanstalk: approved @ e5f1e40

beanstalk: approved @ ee8ab5f

ci: approved

good first issue

gpu/amd

gpu/igpu

gpu/intel

gpu/nvidia

help wanted

kind

bug

kind

chore

kind

docs

kind

feature

kind

performance

kind

question

needs measurements

platform/linux

platform/macos

platform/steam-deck

platform/windows

preview

priority

critical

priority

high

priority

low

regression

status

blocked

status

confirmed

status

duplicate

status

invalid

status

needs-info

status

wontfix

testing wanted

ci: approved

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

MagicBeanDev/Longshot!846

No description provided.