[paul-hammant]

Step 5 of docs/aether_quote_design.md section 9: MSL from the quoted shaders' trees. No Metal renderer yet. Section 11 sets no narrower first step, and #312 (the Metal backend) waits on the Vulkan performance pass. So this PR does the part that is clearly in scope: the MSL, compiled and checked. Section 11 now lists the Metal-path options for Nic.

No aether change was needed. Quote's trees carry everything the dialect reads, so this builds on the pinned 0.834.0 and needs no release.

Commits

1. ae3d.gpu: the quoted shaders written as MSL (gpu.METAL). emit_msl, emit_vertex_msl and emit_screen_vertex_msl reuse the GLSL emitter's expressions and statements, with a CALL_MSL column in the call table. The rules:

   • Conventions are Vulkan's. Each vertex shader negates its position's y as it returns it.
   • Nothing is global. Blocks are passed as struct references, and each texture is passed with its sampler. Helpers that read in place are handed those values by name.
   • std140 by hand. Block structs use packed_float3 and float4 arrays, and every offset and size is a static_assert.
   • Stage interfaces. Varyings are at [[user(locnK)]], attributes at the table's [[attribute(n)]], and colour outputs are four lanes wide.
   • Bindings. Set N is at [[buffer(N)]], storage buffers at 8 + k, and textures/samplers follow capture order.
   • GLSL is unchanged. The dialect is set only while MSL is written.

   tests/test_gpu_msl (no GPU) checks this.

2. generate_shaders. Writes all 41 MSL files to src/ae3d/metal, and --check byte-compares them. The GLSL, vkscene and SPIR-V are unchanged.

3. msl_check. tools/mslc.m uses Metal's own compiler through the device, with every warning an error except four noise groups. scripts/msl_check.sh runs it, and ./ci.sh runs that on macOS. xcrun metal also runs where Xcode's Metal Toolchain is installed; it is a separate download and is not on the M6.

4. docs. Section 9 item 5 and section 11 "What it buys MSL": the rules, how they are held, and three ways to a Metal path, with a recommendation.

Verification (M6, Aether 0.834.0, glslang 16.6.0)

• generate_shaders --check: 95 generated files are current (53 GLSL, vkscene, 41 MSL), and the SPIR-V (892,276 B) is what glslang 16.6.0 makes. The GLSL and SPIR-V are unchanged by this PR.

• scripts/msl_check.sh: all 41 files compile clean with every warning an error.

• Against MoltenVK's own MSL of the same SPIR-V (SPIRV-Cross, logged with MVK_CONFIG_DEBUG=1 from test_backend_parity):

  • all 41 files paired;
  • stage interfaces are equal (attributes, varying locations, colour outputs). This found the four-lane output widening, which is now matched;
  • 506 of ae3d.gpu's offsets, asserted on MoltenVK's own block structs, compile.

  This checks interfaces and layouts, not arithmetic.

• tests/test_gpu_msl: 33 checks pass, with 0 leaks.

• Negative controls. Each of these fails as it should:

  • a hand-edited .metal (--check);
  • an offset off by four (static_assert);
  • an unused local (warning promoted to error);
  • vec3 as float3 (--check + 13 asserts + test);
  • y left unflipped (test);
  • an array read without its lane (compiler + test);
  • an in-place helper not handed its capture (compiler + test);
  • the dialect leaking into OpenGL's names (test);
  • MoltenVK's struct off by four, and an interface moved (comparison).

• The existing bar:

  • frames_against: 59 frames against origin/main, 0 differ;
  • Khronos validation with sync at 1x and 4x (parity, zombie_city, street_drive, test_water_sky, test_crowd_render): 0 errors, 0 warnings;
  • full local ./ci.sh: green at e262954 (8 hardware skips); the run at bd52d7c failed only the leaks check on test_gpu_msl, fixed by e262954;
  • aether-linux-x64 lanes: lane_some 108 builds, 0 failed, 0 warnings (test_gpu_msl and test_gpu_lit added); lane_all gcc and clang 263 each, 0 failed, 0 warnings; test_gpu_msl and generate --check pass on Linux x86_64.

• PR CI: 10/10 green. macos-2 timed out at 25 min on its first run, with every suite up to then ok (Step 6, the scene: per-camera and per-world blocks, the scene's shaders quoted #838 changed ae3d.gpu too and its macos-2 took 14 min). It passed on a rerun in 8m37s.

For Nic

• Metal path: pick one of three.

  1. Our MSL through MoltenVK's MSL-source shader modules. This means a binding rule, not a backend, and frames are then held to the SPIR-V path.
  2. A Metal harness for the screen passes.
  3. The Metal backend #312 backend.

  Recommended: 1, then 3 after Metal backend #312's groundwork.

• Binding model. It uses discrete arguments, not the argument buffers section 11 first mentioned.

• xcrun metal was not run. It needs the Metal Toolchain download (xcodebuild -downloadComponent MetalToolchain). The device compiler, with stricter flags, stands in.

• scene_rq_vk.frag is still hand-written. It has no MSL.

🤖 Generated with Claude Code