Metal Shaders -- MSL for Apple Platforms

Decision Tree

What shader do you need?
|
|-- SwiftUI visual effect?
|   |-- Per-pixel color transform (tint, invert, threshold)?
|   |   -> colorEffect  -> references/swiftui-integration.md#colorEffect
|   |-- Geometric distortion (ripple, wave, lens)?
|   |   -> distortionEffect  -> references/swiftui-integration.md#distortionEffect
|   |-- Multi-sample effect (blur, glow, shadow)?
|   |   -> layerEffect  -> references/swiftui-integration.md#layerEffect
|   \-- Standard filter (blur, edge detect)?
|       -> MPS framework  -> references/metal-performance-shaders.md
|
|-- Post-processing / render pass?
|   |-- Bloom / glow extraction? -> references/fragment-shaders.md#bloom
|   |-- Color grading / LUT?     -> references/fragment-shaders.md#color-grading
|   |-- Vignette?                 -> references/fragment-shaders.md#vignette
|   |-- Chromatic aberration?     -> references/fragment-shaders.md#chromatic-aberration
|   |-- Film grain / CRT?        -> references/fragment-shaders.md#film-grain
|   \-- Gaussian blur?           -> references/fragment-shaders.md#gaussian-blur
|
|-- GPU compute workload?
|   |-- Particle simulation?      -> references/compute-shaders.md#particles
|   |-- Physics / cloth?          -> references/compute-shaders.md#physics
|   |-- Image processing?         -> references/compute-shaders.md#image-processing
|   |-- GPU-driven rendering?     -> references/compute-shaders.md#gpu-driven
|   \-- General parallel work?    -> references/compute-shaders.md#architecture
|
|-- Procedural geometry / volumetrics?
|   |-- SDF scene (shapes, booleans)? -> references/ray-marching.md#sdf
|   |-- Volumetric fog / clouds?      -> references/ray-marching.md#volumetric
|   \-- Full ray marcher?             -> references/ray-marching.md#ray-marcher
|
|-- Procedural noise / textures?
|   |-- Perlin noise?         -> references/noise-functions.md#perlin
|   |-- Simplex noise?        -> references/noise-functions.md#simplex
|   |-- Worley / Voronoi?     -> references/noise-functions.md#worley
|   |-- fBm / fractal layers? -> references/noise-functions.md#fbm
|   \-- Domain warping?       -> references/noise-functions.md#domain-warping
|
\-- Performance / debugging?
    |-- GPU frame capture?    -> references/fragment-shaders.md#debugging
    |-- Occupancy tuning?     -> references/compute-shaders.md#performance
    \-- half vs float?        -> MSL Type Reference below

Quick Reference: Shader Types x Use Cases

| Type | MSL Entry Point | Use Cases | SwiftUI Modifier | Ref | |------|----------------|-----------|------------------|-----| | Fragment (color) | fragment half4 fn(...) | Post-process, color grade, bloom | .colorEffect() | references/fragment-shaders.md | | Fragment (distort) | fragment float2 fn(...) | Ripple, wave, lens warp | .distortionEffect() | references/swiftui-integration.md | | Fragment (layer) | fragment half4 fn(...) | Blur, glow, shadow, multi-sample | .layerEffect() | references/swiftui-integration.md | | Compute (kernel) | kernel void fn(...) | Particles, physics, image proc | N/A (MTLComputeCommandEncoder) | references/compute-shaders.md | | Vertex | vertex VertexOut fn(...) | Mesh deformation, instancing | N/A (render pipeline) | Apple docs |

SwiftUI Integration Cheat Sheet

Three Modifier Types with Exact Signatures

colorEffect  ->  [[ stitchable ]] half4 name(float2 position, half4 color, <args...>)
                 Receives: pixel position + current color
                 Returns: new color

distortionEffect  ->  [[ stitchable ]] float2 name(float2 position, <args...>)
                      Receives: pixel position
                      Returns: source coordinate to sample from
                      Requires: maxSampleOffset

layerEffect  ->  [[ stitchable ]] half4 name(float2 position, SwiftUI::Layer layer, <args...>)
                 Receives: pixel position + layer (can sample any coordinate)
                 Returns: new color
                 Requires: maxSampleOffset

Swift-Side Parameter Passing

.colorEffect(ShaderLibrary.myShader(
    .float(time),           // float
    .float2(CGSize(w, h)),  // float2
    .color(.red),           // half4
    .image(Image("tex")),   // texture2d
    .data(Data(...))        // device buffer
))

TimelineView Animation Pattern

TimelineView(.animation) { timeline in
    let time = timeline.date.timeIntervalSinceReferenceDate
    content
        .colorEffect(ShaderLibrary.pulse(.float(time)))
}

MSL Type Quick Reference

| MSL Type | Bytes | Use For | Notes | |----------|-------|---------|-------| | half | 2 | Scalars (color, alpha) | Prefer over float for color math | | half4 | 8 | Colors (RGBA) | Standard SwiftUI color type | | float | 4 | Position, time, angles | Full precision when needed | | float2 | 8 | UV coords, positions | Standard position type | | float3 | 12 | 3D position, RGB | | | float4 | 16 | Homogeneous coords | | | float4x4 | 64 | Transform matrices | | | texture2d<half> | -- | Color textures | Use half access for perf | | texture2d<float> | -- | Data textures (normals, depth) | When precision matters | | uint2 | 8 | Thread position | thread_position_in_grid | | ushort2 | 4 | Thread position (small) | Save registers |

Key MSL Qualifiers

| Qualifier | Meaning | |-----------|---------| | [[ stitchable ]] | Function can be called from SwiftUI shader modifiers | | [[ position ]] | Vertex output clip-space position | | [[ color(0) ]] | Fragment output to color attachment 0 | | [[ stage_in ]] | Interpolated vertex output → fragment input | | [[ thread_position_in_grid ]] | Global thread ID in compute | | [[ thread_position_in_threadgroup ]] | Local thread ID in threadgroup | | [[ threadgroup_position_in_grid ]] | Threadgroup ID | | [[ threads_per_threadgroup ]] | Threadgroup dimensions | | constant | Read-only buffer (uniform) | | device | Read/write buffer (SSBO) | | threadgroup | Shared memory within threadgroup | | thread | Per-thread local |

Performance Rules (Top 10)

1. Use half over float for color math -- conversions are free on Apple GPU
2. Minimize texture samples -- each sample is expensive; cache in registers
3. Branch-free code -- SIMD groups execute both branches; use mix()/select() instead of if
4. Threadgroup size = multiple of threadExecutionWidth (typically 32) -- avoids wasted lanes
5. Memory coalescing -- adjacent threads should access adjacent memory addresses
6. Avoid threadgroup bank conflicts -- stagger access patterns or pad shared arrays
7. Early termination in ray marching -- if (totalAlpha > 0.99) break;
8. Separable filters -- 2-pass (H+V) is O(2N) vs O(N^2) for 2D convolution
9. Texture-based noise lookup vs computed -- precompute for static noise, compute for animated
10. Profile with GPU Frame Capture in Xcode before optimizing -- measure, don't guess

Cross-References

| Skill | Relation | |-------|----------| | orb | T5 Metal ripple shader -- practical SwiftUI shader example | | swiftui-animation | Animation-driven shader parameters (TimelineView, spring) | | vfx-spell-effects | Effect composition using these shader patterns | | swiftui-expert-skill | SwiftUI view lifecycle for shader integration | | swiftui-performance-audit | Diagnosing GPU-related SwiftUI perf issues |

Key Resources

• Metal Shading Language Specification (PDF)
• Metal Overview -- Apple Developer
• Metal Performance Shaders
• Metal in SwiftUI -- Jacob Bartlett
• Metal Shaders in SwiftUI -- Hacking with Swift
• Inferno -- 17 SwiftUI Metal Shaders
• The Book of Shaders -- Noise
• Ray Marching & SDFs -- Jamie Wong
• SDF Primitives -- Inigo Quilez
• Ray Marching Distance Fields -- Inigo Quilez

Technique Map

• Shader type routing — colorEffect (per-pixel), distortionEffect (geometric), layerEffect (multi-sample); because each modifier has distinct signature and use case.
• Stitchable qualifier — Required for SwiftUI shader modifiers; because enables function call from SwiftUI.
• half over float for color — Use half/half4 for color math; because conversions are free on Apple GPU; reduces register pressure.
• Branch-free code — Use mix()/select() instead of if; because SIMD groups execute both branches; branches cost.
• Profile with GPU Frame Capture — Measure before optimizing; because guessing causes wrong optimizations.
• Threadgroup size = multiple of 32 — Align to threadExecutionWidth; because avoids wasted SIMD lanes.
• Separable filters — 2-pass H+V for blur; because O(2N) vs O(N²) for 2D convolution.

Technique Notes

MSL types: half4 for colors, float2 for positions. Swift passes .float(time), .float2(CGSize), .color(), .image(). TimelineView drives animation. References: fragment-shaders.md, compute-shaders.md, ray-marching.md, noise-functions.md.

---

Prompt Architect Overlay

Role Definition: Metal shader expert for Apple platforms. Covers MSL, SwiftUI stitchable effects (colorEffect, distortionEffect, layerEffect), MPS, compute shaders, ray marching, and GPU performance.

Input Contract: Accepts shader type (visual effect, post-process, compute, procedural), target (SwiftUI, Metal pipeline), and performance constraints. Code or description of desired effect.

Output Contract: MSL code with correct signatures, Swift integration snippet, performance considerations. Routes to appropriate reference (fragment, compute, ray-marching, noise). Decision tree for shader type selection.

Edge Cases & Fallbacks: If SwiftUI modifier not working→verify stitchable, maxSampleOffset. If performance issue→profile first; check half vs float, texture samples, branch-free. If cross-platform→note iOS 17+ for SwiftUI shaders.