watchOS: Metal-shader post-FX (chromatic aberration, film grain, sun shafts)

[proggeramlug]

Goal

Bloom's post-fx surface includes effects that need per-pixel Metal shaders to implement properly:

• bloom_set_chromatic_aberration(strength) — sample R/G/B at slightly different positions
• bloom_set_film_grain(strength) — time-animated noise overlay
• bloom_set_sun_shafts(...) — radial blur from light source

Today these are stored in watchOS but visually no-op. SwiftUI on watchOS 10+ supports .colorEffect(Shader(function:args:)) which runs Metal shader code against a view's rasterized content.

Scope

Perry-side

Add a new native-library manifest field metal_sources (array of paths) alongside the existing swift_sources. Perry:

1. Compiles each .metal file with xcrun metal -c -target <triple> against the watchOS SDK.
2. Links into a .metallib via xcrun metallib.
3. Copies the .metallib into .app/default.metallib so ShaderLibrary.default picks it up.

Bloom-side

• native/watchos/src/shaders/: three .metal files — chromatic_aberration.metal, film_grain.metal, sun_shafts.metal. Each exports a [[ stitchable ]] half4 <name>(float2 position, half4 color) function.
• BloomWatchApp.swift reads the effect strengths from bloom_watchos_postfx_state, wraps the root view with .colorEffect(Shader(function: .init(library: .default, name: "..."), arguments: [...])) per enabled effect.
• Film grain needs time as a shader arg; sun shafts need the sun position in NDC.

Acceptance

bloom_set_chromatic_aberration(0.5) visibly offsets R/G/B channels near screen edges.
bloom_set_film_grain(0.3) overlays animated noise.
bloom_set_sun_shafts(...) produces radial light streaks from the sun direction.

Related

• watchOS: SCNTechnique-based post-fx for 3D-layer effects #18 landed vignette + exposure via pure SwiftUI (no shaders needed for those)
• Blocked on Perry — file a Perry issue first with the proposed metal_sources field, then implement bloom-side once it's merged.

[proggeramlug]

Update: Perry landed metal_sources (PerryTS/perry#124 → v0.5.146) and the bloom-side shader file is written + stored — native/watchos/shaders/bloom_postfx.metal with three [[ stitchable ]] functions for chromatic aberration, film grain, and sun shafts. bloom_set_* state carries through to a PostFxState snapshot the Swift side can read.

Blocker: SwiftUI's shader-consumer modifiers — .colorEffect(Shader), .layerEffect(Shader), ShaderLibrary — are iOS 17+ / tvOS 17+ / macOS 14+ only. Apple deliberately excluded watchOS. Even with the .metallib correctly bundled (the Perry pipeline works), there's no SwiftUI-level way to attach the shaders to a view on the watch.

Three paths forward, ordered by realism:

1. SCNTechnique-based post-process — SceneKit's pass-based Metal pipeline is available on watchOS. Can load shader functions from default.metallib and apply them as post-passes over the SceneView output. Only processes the 3D layer (2D Canvas overlay would render unaffected over the top), but that's what post-fx is actually for in most games. Filing as a follow-up.

2. Custom MTLCommandQueue offscreen render + SwiftUI bridge — much more invasive, basically replaces SceneView entirely. Probably not worth the complexity.

3. Wait for Apple to ship SwiftUI Shader APIs on watchOS — filed an Apple Feedback, no ETA.

Committed the infrastructure + doc comment explaining all this in BloomWatchApp.swift. Keeping this issue open and filing #18 for the SCNTechnique path.

Commit: [f572f26]