feat(compositor): the macOS shader effects pass (Metal)

[EtienneLescot]

Summary

Third PR of agent-written shader effects, section L.3 of docs/shader-effects.md: the macOS (Metal) pass. An effect now draws on macOS, in preview and export alike; with the Windows and Linux passes, every backend draws effects. Targets integration/shader-effects, which carries #1199, #1202 and the Linux pass.

• Translation and compile (shader_fx.rs).
  • naga 24 → MSL, with the prelude's bindings mapped explicitly: texture 0, the sampler inlined as a constexpr (linear, clamp to edge, like sampNV), ctx and params at buffers 2 and 3. Without that map, naga emits [[user(fake0)]], which is not MSL.
  • new_library_with_source and a pipeline state with no blending, on a background thread under its own autorelease pool.
  • checkShaderEffect compiles for Metal too, so "accepted" means "will draw".
  • naga's force_loop_bounding is off. The validation has already proved every loop bounded, and naga's guard (a volatile read on every iteration) cost 7 to 10 % of the pass on an M1.
• The pass (compositor_macos.rs).
  • Same as Windows: the cache, the blocking/non-blocking split and the lane order.
  • Each effect is encoded in the frame's command buffer: a blit of its target into ann_copy, then a render pass that loads the target (an effect may discard).
  • The text target: draw_annotations opened its pass on self.rt; it now takes the texture it draws on. The text layer is cleared in a pass of its own, receives the annotations, goes through its effects, and is drawn over the image by pipeline_fs_tex (premultiplied "over").
• live.rs: every backend draws effects now, so the live view's non-blocking mode and its recompose-on-landing lose their cfg.
• Cargo.toml: msl-out is declared for macOS instead of arriving through wgpu's features.
• Docs: native-compositor.md (the section; the known gap goes, every backend draws), the spec (C.7, D.4, D.5, new H.3, next to the Linux figures), rendering-performance.md, and a row in the e2e log.

Related issue

Part of the shader effects work (#1199, #1202, and the Linux pass on integration/shader-effects).

Type of change

• Feature
• Documentation

Release impact

• No release note needed: nothing is reachable from the app until the document model and the tools land

Desktop impact

• macOS
• Windows and Linux: untouched, apart from live.rs losing a cfg that now covers every backend

Testing

• Rust: cargo test -p openscreen-compositor --lib --tests passes on an M1 (macOS 26.5), 445 lib tests on top of integration/shader-effects. On the Metal device:
  • the six GPU tests of the Windows pass: region, preview landing, broken effect or unknown contract, color parameter, lane order, the three targets;
  • plus a real annotation, which an image effect leaves alone and a text effect repaints, while the image under it stays intact;
  • the MSL bindings, and the spec's C.6 ripple and the two examples of the MCP resource compiling through Metal.
• Calibration (shader_fx_tier_calibration, release, M1): about 0.12 ms per frame() read at 1080p and 0.5 ms at 4K, thirty times the RTX 4070 Ti. A heavy effect (128 reads) costs 16 ms per 1080p frame. The reads still dominate, so the tiers hold.
• Compile time: 120 ms in the median for a new source, up to 375 ms for the first in a process; a known source comes back in 0.4 ms. All of it runs off the render thread.
• End to end, on a local branch with feat(effects): shader effects in the document, and the agent tools #1202 merged in (never pushed), through electron . --user-data-dir=<test profile> mcp, headless:
  • addEffect with a typo is refused in 6 ms at the agent's line; the ripple is accepted in 152 ms, real Metal compile included;
  • exportVideo + getFrames show the ripple after each click;
  • live view against the MP4 (BT.709): 3.1/255 over the frame with the effect, 3.0 without. On the pixels the effect changes, 13 to 16/255 with the effect against 14 to 16 without on the same pixels: codec noise on sharp edges;
  • export of 180 frames at 1752×1080: 2469 ms without, 2428 ms with the ripple. The live view held 29.7 fps at a 30 fps source with and without.
• Not run: Windows and Linux, which this PR barely touches; the editor UI (no effect track yet). No CI runs on a PR to integration/shader-effects (ci.yml triggers on main, feat/ai-edition and release/**).

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: d016aa54-40ab-474a-89d0-fe32d2298bd1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}