| name | compose-shader-expert |
| description | Expert guidance for writing and integrating high-performance AGSL/SkSL shaders in Jetpack Compose and Compose Multiplatform. Trigger this skill whenever the user mentions AGSL, shaders, RenderEffect, custom graphics modifiers, glassmorphism, blur, metaballs, or procedural rendering in Compose, even if they only ask for a simple visual effect. |
Compose Shader Expert
Core guidelines for modern (2025/2026) high-performance AGSL/SkSL shader integration in Jetpack Compose and Compose Multiplatform.
Use progressive disclosure: consult specific reference files for details. Maintain strict token efficiency. Shaders must be optimized for mobile GPUs, branchless, and cached to prevent recompositions and compile spikes.
1. Quick Decision Matrix
| Task / Domain | Action / Pattern | Details |
|---|
| AGSL Syntax & Math | Coordinate mapping, layout(color), premultiplied alpha | Consult syntax-coordinate.md |
| Compose Integration | ShaderBrush, RenderEffect, drawWithCache, graphicsLayer | Consult compose-lifecycle.md |
| GPU Optimization | Branching avoidance, precision choice, register pressure, caching | Consult performance-gpu.md |
| Visual Effects | Glassmorphism, liquid metaballs, noise textures, SDF borders | Consult shader-use-cases.md |
| Special Effects | Glossy 3D Liquid, Topographic Flow, Holographic tilt, Water Ripples | Consult special-effects.md |
2. Directory Structure
All detailed reference materials and scripts are partitioned into subdirectories:
- References:
- syntax-coordinate.md — AGSL vs GLSL differences, coordinate space alignment, color-space management, and alpha premultiplication.
- compose-lifecycle.md — Lifetime management, drawWithCache vs drawBehind, RenderEffect offscreen buffers, custom Modifier.Node optimization, and expect/actual KMP abstraction.
- performance-gpu.md — Mobile GPU branching rules, precision (float vs half), texture fetch bandwidth limits, and shader warm-up/caching.
- shader-use-cases.md — Detailed mathematics, code snippets, and implementation steps for frosted glassmorphism, liquid metaballs, and procedural noise.
- special-effects.md — Detailed recipes and mathematical formulations for Glossy 3D Liquid, Topographic Flow, Holographic tilt card, and Touch-driven Water ripples.
- Scripts:
- validate_shader.py — Python CLI tool to parse shader strings for common performance and AGSL syntax issues.
Always read the specific file containing the details required for the task.
Developers must follow these constraints:
1. Always create and cache shaders inside drawWithCache or graphicsLayer to avoid per-frame allocation.
2. Ensure Y-coordinate mapping is correctly adjusted for AGSL's top-left origin.
3. Keep all custom shader outputs premultiplied.
4. Pass touch coordinates offscreen (e.g. `Offset(-9999f, -9999f)`) when inactive to avoid top-left `(0, 0)` clustering.
5. Avoid looping over discrete particles inside the pixel fragment shader; draw them using Canvas `drawCircle`/`drawPoints` over the shader background for order-of-magnitude performance improvements.
