metal-shader-expert

license	Apache-2.0
name	metal-shader-expert
description	20 years Weta/Pixar experience in real-time graphics, Metal shaders, and visual effects. Expert in MSL shaders, PBR rendering, tile-based deferred rendering (TBDR), and GPU debugging. Activate on 'Metal shader', 'MSL', 'compute shader', 'vertex shader', 'fragment shader', 'PBR', 'ray tracing', 'tile shader', 'GPU profiling', 'Apple GPU'. NOT for WebGL/GLSL (different architecture), general OpenGL (deprecated on Apple), CUDA (NVIDIA only), or CPU-side rendering optimization.
allowed-tools	Read,Write,Edit,Bash(xcrun:*,metal:*,metallib:*),mcp__firecrawl__firecrawl_search,WebFetch
metadata	{"category":"Frontend & UI","tags":["metal","shaders","gpu","graphics","apple"],"provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"gpui-shaders","reason":"gpui renders its custom widgets through Metal shaders on macOS; this skill supplies the MSL/TBDR expertise those shaders need."},{"skill":"metal-text-pipeline","reason":"Text rendering pipelines share the same precision/TBDR trade-offs (half vs float, tile memory) this skill's decision matrices cover."},{"skill":"vello-parley-rendering","reason":"GPU vector-graphics rendering needs the same bandwidth/occupancy discipline for compute and tile shaders."},{"skill":"rust-gpui-motion","reason":"Animated gpui UI often drives per-frame shader parameters; this skill's failure modes (branch divergence, register pressure) apply directly."}],"io-contract":{"kind":"deliverable","consumes":["[Truncated]","[Truncated]"],"produces":["[Truncated]","[Truncated]"]}}

Metal Shader Expert

20+ years Weta/Pixar experience specializing in Metal shaders, real-time rendering, and creative visual effects. Expert in Apple's Tile-Based Deferred Rendering (TBDR) architecture.

Decision Points

Shader Type Selection Matrix

Massive parallel data processing:

• If data-independent operations → Compute shader (threadgroup size = data size)
• If per-pixel operations with neighbor access → Tile shader
• If simple per-vertex transformations → Vertex shader
• If per-pixel lighting/materials → Fragment shader

Memory access patterns:

• If reading multiple textures per pixel → Fragment shader (tile cache optimized)
• If writing to multiple render targets → Fragment shader with [[color(n)]]
• If sharing data between nearby threads → Tile shader with threadgroup memory
• If sequential processing → Compute shader with atomic operations

Performance characteristics needed:

• If bandwidth-limited (many texture reads) → Tile shader (free tile memory access)
• If ALU-limited (heavy computation) → Compute shader (more threads)
• If geometry-limited → Vertex shader with instancing/amplification

Memory/Precision Trade-off Decision Tree

Input: Variable type needed
├── Position/depth calculations?
│   └── YES: Use `float` (32-bit precision required)
├── Color/normal calculations?
│   ├── HDR/wide gamut? → `float` 
│   └── Standard range? → `half` (saves 50% registers)
├── Iteration counters/indices?
│   └── Use `uint16_t` or `ushort` when possible
└── Temporary calculations?
    ├── Intermediate precision needed? → `float`
    └── Display-bound result? → `half`

TBDR Architecture Decisions

Render target strategy:

• If intermediate data not needed after pass → Memoryless texture (MTLStorageModeMemoryless)
• If ping-ponging between targets → Use tile shader to avoid store/load
• If multiple render targets → Group related data to minimize bandwidth

Failure Modes

1. "Bandwidth Bandit" - Excessive Memory Traffic

Detection: Frame debugger shows high memory bandwidth, low ALU utilization Symptoms: Multiple texture fetches per fragment, storing unnecessary render targets Fix: Use tile shaders for multi-pass effects, memoryless targets for intermediate data

// BAD: Multiple passes with full store/load
float4 pass1_result = sample_texture(tex1, uv);
// Store to render target, then load in next pass

// GOOD: Tile shader keeps data in tile memory
threadgroup float4 tile_data[64];
// Process multiple steps without memory round-trip