Shader authoring

my-effect/
├── metadata.json       # required. Describes the effect.
├── effect.frag         # required. Main fragment shader.
├── zone.vert           # optional. Custom vertex shader.
├── buffer.frag         # optional. Enables multipass (one ping-pong buffer).
└── common.glsl         # optional. Shader-local helpers (if you don't use the shared one).

{
    "id": "my-effect",
    "name": "My Effect",
    "category": "Cyberpunk",
    "description": "What this effect looks like and how it reacts.",
    "author": "Your Name",
    "version": "1.0",

    "fragmentShader": "effect.frag",
    "vertexShader": "zone.vert",

    "wallpaper": false,
    "multipass": false,
    "bufferShader": "buffer.frag",
    "bufferFeedback": false,
    "bufferScale": 1.0,
    "bufferWrap": "clamp",
    "bufferFilter": "linear",

    "depthBuffer": false,

    "parameters": [
        {"id": "speed",    "name": "Speed",    "group": "Motion",     "type": "float", "slot": 0, "default": 1.0,  "min": 0.0, "max": 4.0},
        {"id": "mixAmt",   "name": "Mix",      "group": "Appearance", "type": "float", "slot": 1, "default": 0.5,  "min": 0.0, "max": 1.0},
        {"id": "useGlow",  "name": "Glow",     "group": "Appearance", "type": "bool",  "slot": 2, "default": true},
        {"id": "primary",  "name": "Primary",  "group": "Colors",     "type": "color", "slot": 0, "default": "#3B82F6"},
        {"id": "accent",   "name": "Accent",   "group": "Colors",     "type": "color", "slot": 1, "default": "#22D3EE"}
    ]
}

#version 450
#include <common.glsl>
#include <multipass.glsl>     // if multipass: true
#include <audio.glsl>         // if using audio reactivity
#include <textures.glsl>      // if declaring image parameters
#include <depth.glsl>         // if depthBuffer: true

#version 450
#include <common.glsl>

layout(location = 0) in vec2 vTexCoord;
layout(location = 1) in vec2 vFragCoord;
layout(location = 0) out vec4 fragColor;

void main() {
    vec2 uv = vTexCoord;
    vec3 color = vec3(0.0);
    // ...
    fragColor = vec4(color, 1.0) * qt_Opacity;
}

// Continuous-phase time. Uses angle addition on (iTimeHi, iTime) so the
// result stays stable after iTime wraps. Use for sin/cos animations.
float timeSin(float speed);
float timeSin(float speed, float offset);
float timeCos(float speed);
float timeCos(float speed, float offset);

// Resolution-independent pixel scale factor (iResolution.y / 1080).
// Multiply pixel-space constants by this so border widths, glow radii,
// chromatic aberration read the same on a 4K monitor as on 1080p.
float pxScale();

// Convert vTexCoord (Y-down) to pixel-space fragCoord (Y-up canonical).
vec2 fragCoordFromTexCoord(vec2 uv);

// Clamp color to [0,1], apply qt_Opacity, and premultiply alpha.
// Use for the final fragColor assignment — Qt Quick and Wayland
// compositors expect premultiplied alpha (rgb * alpha).
vec4 clampFragColor(vec4 color);

// Constants
const float PI;
const float TAU;
const float K_TIME_WRAP;   // 1024.0

// uZoneLabels is a texture strip of per-zone glyphs. These helpers
// composite it over your background color so zone numbers / titles
// read regardless of the effect underneath.
vec2 labelsUv(vec2 fragCoord);
vec4 compositeLabels(vec4 color, vec2 uv, sampler2D labelsTex);
vec4 compositeLabelsWithUv(vec4 color, vec2 fragCoord);

// Normalized rect → pixel-space position and size
vec2 zoneRectPos(vec4 rect);    // rect.xy * iResolution
vec2 zoneRectSize(vec4 rect);   // rect.zw * iResolution

// 0..1 UV inside a zone given the fragment's pixel coordinates
vec2 zoneLocalUV(vec2 fragCoord, vec2 rectPos, vec2 rectSize);

// "Alive" vs "dormant" zone state. Highlighted zones animate;
// non-highlighted ones are static. Use these to drive intensity,
// color saturation, and motion amplitude.
float zoneVitality(bool isHighlighted);
vec3  vitalityDesaturate(vec3 col, float vitality);
float vitalityScale(float dormant, float alive, float vitality);

// Deterministic hashes — cheap, no texture fetch.
float hash11(float n);
float hash21(vec2  p);
vec2  hash22(vec2  p);

// Smooth value noise.
float noise1D(float x);
float noise2D(vec2 p);
float angularNoise(float angle, float freq, float seed);

// Rounded box SDF. p: sample pos (centered), b: half-size, r: corner radius.
// Positive outside the shape, negative inside.
float sdRoundedBox(vec2 p, vec2 b, float r);

// Soft edge for a distance field. borderWidth: transition half-width in
// the same units as d.
float softBorder(float d, float borderWidth);

// Exponential-falloff glow from an SDF edge.
float expGlow(float d, float falloff, float strength);

// Standard "source over" alpha blend. Expects straight (non-premultiplied) alpha.
vec4 blendOver(vec4 dst, vec4 src);

// Rec.601 luminance.
float luminance(vec3 c);

// Pick the first non-black color — useful when a user param may be
// unset and you want to fall back to a sensible default.
vec3 colorWithFallback(vec3 color, vec3 fallback);

// Correct: Y-flip handled by the helper
vec2 uv = channelUv(0, fragCoordFromTexCoord(vTexCoord));
vec4 prev = texture(iChannel0, uv);

// Wrong: skips the Y-flip, content renders upside-down
vec4 prev = texture(iChannel0, vTexCoord);

// buffer.frag — smeared accumulation of the previous frame (feedback ON)
#version 450
#include <common.glsl>
#include <multipass.glsl>

layout(location = 0) in vec2 vTexCoord;
layout(location = 1) in vec2 vFragCoord;
layout(location = 0) out vec4 fragColor;

void main() {
    vec2 uv = channelUv(0, vFragCoord);
    vec4 prev = texture(iChannel0, uv);

    vec3 newColor = /* compute something fresh */;
    fragColor = vec4(mix(prev.rgb * 0.94, newColor, 0.08), 1.0);
}

#version 450
#include <common.glsl>
#include <depth.glsl>

layout(location = 0) in vec2 vTexCoord;
layout(location = 0) out vec4  fragColor;
layout(location = 1) out float oDepth;   // depth write

void main() {
    // Read previous-pass depth to decide whether to composite
    float prevDepth = readDepth(vTexCoord);

    vec3  color   = /* ... */;
    float myDepth = /* 0 (near) .. 1 (far) */;

    fragColor = clampFragColor(vec4(color, 1.0));
    oDepth    = myDepth;
}