@rosetears/aili-pi 0.1.0

package/skills/shader-dev/techniques/voronoi-cellular-noise.md

@@ -0,0 +1,458 @@
+- **IMPORTANT:** All declared `uniform` variables must be used in the shader code, otherwise the compiler will optimize them away. After optimization, `gl.getUniformLocation()` returns `null`, and setting that uniform triggers a WebGL `INVALID_OPERATION` error, which may cause rendering failure. Ensure uniforms like `iTime` are actually used in `main()` (e.g., `float t = iTime * 1.0;`)
+
+# Voronoi & Cellular Noise
+
+## Use Cases
+- Natural textures: cells, cracked soil, stone, skin pores
+- Structured patterns: crystals, honeycombs, shattered glass, mosaics
+- Effects: fire/nebula (fBm stacking), crack generation
+- Procedural materials: cloud noise, terrain height maps, stylized partitioning
+
+## Core Principles
+
+Voronoi noise = **spatial partitioning**: scatter feature points, assign each pixel to the "cell" of its nearest feature point.
+
+Algorithm flow:
+1. `floor` divides into an integer grid; each cell contains a randomly offset feature point
+2. Search the 3x3 (2D) or 3x3x3 (3D) neighborhood for all feature points
+3. Record the nearest distance F1 (optionally second-nearest F2)
+4. Map F1, F2, or F2-F1 to color/height/shape
+
+Distance metrics:
+- Euclidean: `dot(r,r)` (squared, fast) -> final `sqrt`
+- Manhattan: `abs(r.x)+abs(r.y)`
+- Chebyshev: `max(abs(r.x), abs(r.y))`
+
+Exact border distance (two-pass algorithm): `dot(0.5*(mr+r), normalize(r-mr))`
+Rounded borders (harmonic mean): `1/(1/(d2-d1) + 1/(d3-d1))`
+
+## Implementation Steps
+
+### Step 1: Hash Functions
+
+```glsl
+// sin-dot hash (suitable for most cases)
+vec2 hash2(vec2 p) {
+    p = vec2(dot(p, vec2(127.1, 311.7)),
+             dot(p, vec2(269.5, 183.3)));
+    return fract(sin(p) * 43758.5453);
+}
+
+// 3D version
+vec3 hash3(vec3 p) {
+    float n = sin(dot(p, vec3(7.0, 157.0, 113.0)));
+    return fract(vec3(2097152.0, 262144.0, 32768.0) * n);
+}
+
+// High-quality integer hash (ES 3.0+, more uniform)
+vec3 hash3_uint(vec3 p) {
+    uvec3 q = uvec3(ivec3(p)) * uvec3(1597334673U, 3812015801U, 2798796415U);
+    q = (q.x ^ q.y ^ q.z) * uvec3(1597334673U, 3812015801U, 2798796415U);
+    return vec3(q) / float(0xffffffffU);
+}
+```
+
+### Step 2: Basic F1 Voronoi
+
+```glsl
+// Returns (F1 distance, cell ID)
+vec2 voronoi(vec2 x) {
+    vec2 n = floor(x);
+    vec2 f = fract(x);
+    vec3 m = vec3(8.0);
+
+    for (int j = -1; j <= 1; j++)
+    for (int i = -1; i <= 1; i++) {
+        vec2 g = vec2(float(i), float(j));
+        vec2 o = hash2(n + g);
+        vec2 r = g - f + o;
+        float d = dot(r, r);
+        if (d < m.x) {
+            m = vec3(d, o);
+        }
+    }
+    return vec2(sqrt(m.x), m.y + m.z);
+}
+```
+
+### Step 3: F1 + F2 (Edge Detection)
+
+```glsl
+// Returns vec2(F1, F2), edge value = F2 - F1
+vec2 voronoi_f1f2(vec2 x) {
+    vec2 p = floor(x);
+    vec2 f = fract(x);
+    vec2 res = vec2(8.0);
+
+    for (int j = -1; j <= 1; j++)
+    for (int i = -1; i <= 1; i++) {
+        vec2 b = vec2(i, j);
+        vec2 r = b - f + hash2(p + b);
+        float d = dot(r, r);
+        if (d < res.x) {
+            res.y = res.x;
+            res.x = d;
+        } else if (d < res.y) {
+            res.y = d;
+        }
+    }
+    return sqrt(res);
+}
+```
+
+### Step 4: Exact Border Distance (Two-Pass Algorithm)
+
+```glsl
+// Returns vec3(border distance, nearest point offset)
+vec3 voronoi_border(vec2 x) {
+    vec2 ip = floor(x);
+    vec2 fp = fract(x);
+
+    // First pass: find nearest feature point
+    vec2 mg, mr;
+    float md = 8.0;
+    for (int j = -1; j <= 1; j++)
+    for (int i = -1; i <= 1; i++) {
+        vec2 g = vec2(float(i), float(j));
+        vec2 o = hash2(ip + g);
+        vec2 r = g + o - fp;
+        float d = dot(r, r);
+        if (d < md) { md = d; mr = r; mg = g; }
+    }
+
+    // Second pass: exact border distance (5x5 range)
+    md = 8.0;
+    for (int j = -2; j <= 2; j++)
+    for (int i = -2; i <= 2; i++) {
+        vec2 g = mg + vec2(float(i), float(j));
+        vec2 o = hash2(ip + g);
+        vec2 r = g + o - fp;
+        if (dot(mr - r, mr - r) > 0.00001)
+            md = min(md, dot(0.5 * (mr + r), normalize(r - mr)));
+    }
+    return vec3(md, mr);
+}
+```
+
+### Step 5: Feature Point Animation
+
+```glsl
+// Replace static hash inside the neighborhood search loop:
+vec2 o = hash2(n + g);
+o = 0.5 + 0.5 * sin(iTime + 6.2831 * o); // different phase per point
+vec2 r = g - f + o;
+```
+
+### Step 6: Coloring & Visualization
+
+```glsl
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    // Must use iTime, otherwise the compiler will optimize away the uniform
+    float time = iTime * 1.0;
+    vec2 p = fragCoord.xy / iResolution.xy;
+    vec2 uv = p * SCALE;
+
+    vec2 c = voronoi(uv);
+    float dist = c.x;
+    float id   = c.y;
+
+    // Cell coloring (ID-driven palette)
+    vec3 col = 0.5 + 0.5 * cos(id * 6.2831 + vec3(0.0, 1.0, 2.0));
+    // Distance falloff
+    col *= clamp(1.0 - 0.4 * dist * dist, 0.0, 1.0);
+    // Border lines
+    col -= (1.0 - smoothstep(0.08, 0.09, dist));
+
+    fragColor = vec4(col, 1.0);
+}
+```
+
+## Complete Code Template
+
+```glsl
+// === Voronoi Cellular Noise — Complete ShaderToy Template ===
+// Supports F1/F2/F2-F1 modes, multiple distance metrics, animation, exact borders
+
+#define SCALE 8.0            // Cell density
+#define ANIMATE 1            // 0=static, 1=animated
+#define MODE 0               // 0=F1 fill, 1=F2-F1 edges, 2=exact borders
+#define DIST_METRIC 0        // 0=Euclidean, 1=Manhattan, 2=Chebyshev
+
+vec2 hash2(vec2 p) {
+    p = vec2(dot(p, vec2(127.1, 311.7)),
+             dot(p, vec2(269.5, 183.3)));
+    return fract(sin(p) * 43758.5453);
+}
+
+float distFunc(vec2 r) {
+    #if DIST_METRIC == 0
+        return dot(r, r);
+    #elif DIST_METRIC == 1
+        return abs(r.x) + abs(r.y);
+    #elif DIST_METRIC == 2
+        return max(abs(r.x), abs(r.y));
+    #endif
+}
+
+vec2 getPoint(vec2 cellId) {
+    vec2 o = hash2(cellId);
+    #if ANIMATE
+        o = 0.5 + 0.5 * sin(iTime + 6.2831 * o);
+    #endif
+    return o;
+}
+
+vec4 voronoi(vec2 x) {
+    vec2 n = floor(x);
+    vec2 f = fract(x);
+    float d1 = 8.0, d2 = 8.0;
+    vec2 nearestCell = vec2(0.0);
+
+    for (int j = -1; j <= 1; j++)
+    for (int i = -1; i <= 1; i++) {
+        vec2 g = vec2(float(i), float(j));
+        vec2 o = getPoint(n + g);
+        vec2 r = g - f + o;
+        float d = distFunc(r);
+        if (d < d1) {
+            d2 = d1; d1 = d;
+            nearestCell = n + g;
+        } else if (d < d2) {
+            d2 = d;
+        }
+    }
+
+    #if DIST_METRIC == 0
+        d1 = sqrt(d1); d2 = sqrt(d2);
+    #endif
+    return vec4(d1, d2, nearestCell);
+}
+
+vec3 voronoiBorder(vec2 x) {
+    vec2 ip = floor(x);
+    vec2 fp = fract(x);
+
+    vec2 mg, mr;
+    float md = 8.0;
+    for (int j = -1; j <= 1; j++)
+    for (int i = -1; i <= 1; i++) {
+        vec2 g = vec2(float(i), float(j));
+        vec2 o = getPoint(ip + g);
+        vec2 r = g + o - fp;
+        float d = dot(r, r);
+        if (d < md) { md = d; mr = r; mg = g; }
+    }
+
+    md = 8.0;
+    for (int j = -2; j <= 2; j++)
+    for (int i = -2; i <= 2; i++) {
+        vec2 g = mg + vec2(float(i), float(j));
+        vec2 o = getPoint(ip + g);
+        vec2 r = g + o - fp;
+        if (dot(mr - r, mr - r) > 0.00001)
+            md = min(md, dot(0.5 * (mr + r), normalize(r - mr)));
+    }
+    return vec3(md, mr);
+}
+
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    // Must use iTime, otherwise the compiler will optimize away the uniform (especially important when ANIMATE=1)
+    float time = iTime * 1.0;
+    vec2 p = fragCoord.xy / iResolution.xy;
+    p.x *= iResolution.x / iResolution.y;
+    vec2 uv = p * SCALE;
+    vec3 col = vec3(0.0);
+
+    #if MODE == 0
+        vec4 v = voronoi(uv);
+        float id = dot(v.zw, vec2(127.1, 311.7));
+        col = 0.5 + 0.5 * cos(id * 6.2831 + vec3(0.0, 1.0, 2.0));
+        col *= clamp(1.0 - 0.4 * v.x * v.x, 0.0, 1.0);
+        col -= (1.0 - smoothstep(0.08, 0.09, v.x));
+    #elif MODE == 1
+        vec4 v = voronoi(uv);
+        float edge = v.y - v.x;
+        col = vec3(1.0 - smoothstep(0.0, 0.15, edge));
+        col *= vec3(0.2, 0.6, 1.0);
+    #elif MODE == 2
+        vec3 c = voronoiBorder(uv);
+        col = c.x * (0.5 + 0.5 * sin(64.0 * c.x)) * vec3(1.0);
+        col = mix(vec3(1.0, 0.6, 0.0), col, smoothstep(0.04, 0.07, c.x));
+        float dd = length(c.yz);
+        col = mix(vec3(1.0, 0.6, 0.1), col, smoothstep(0.0, 0.12, dd));
+    #endif
+
+    fragColor = vec4(col, 1.0);
+}
+```
+
+## Common Variants
+
+### Variant 1: 3D Voronoi + fBm Fire
+
+```glsl
+#define NUM_OCTAVES 5
+
+vec3 hash3(vec3 p) {
+    float n = sin(dot(p, vec3(7.0, 157.0, 113.0)));
+    return fract(vec3(2097152.0, 262144.0, 32768.0) * n);
+}
+
+float voronoi3D(vec3 p) {
+    vec3 g = floor(p); p = fract(p);
+    float d = 1.0;
+    for (int j = -1; j <= 1; j++)
+    for (int i = -1; i <= 1; i++)
+    for (int k = -1; k <= 1; k++) {
+        vec3 b = vec3(i, j, k);
+        vec3 r = b - p + hash3(g + b);
+        d = min(d, dot(r, r));
+    }
+    return d;
+}
+
+float fbmVoronoi(vec3 p) {
+    vec3 t = vec3(0.0, 0.0, p.z + iTime * 1.5);
+    float tot = 0.0, sum = 0.0, amp = 1.0;
+    for (int i = 0; i < NUM_OCTAVES; i++) {
+        tot += voronoi3D(p + t) * amp;
+        p *= 2.0; t *= 1.5;
+        sum += amp; amp *= 0.5;
+    }
+    return tot / sum;
+}
+
+// Blackbody radiation palette
+vec3 firePalette(float i) {
+    float T = 1400.0 + 1300.0 * i;
+    vec3 L = vec3(7.4, 5.6, 4.4);
+    L = pow(L, vec3(5.0)) * (exp(1.43876719683e5 / (T * L)) - 1.0);
+    return 1.0 - exp(-5e8 / L);
+}
+```
+
+### Variant 2: Rounded Borders (3rd-Order Voronoi)
+
+```glsl
+float voronoiRounded(vec2 p) {
+    vec2 g = floor(p); p -= g;
+    vec3 d = vec3(1.0); // F1, F2, F3
+
+    for (int y = -1; y <= 1; y++)
+    for (int x = -1; x <= 1; x++) {
+        vec2 o = vec2(x, y);
+        o += hash2(g + o) - p;
+        float r = dot(o, o);
+        d.z = max(d.x, max(d.y, min(d.z, r)));
+        d.y = max(d.x, min(d.y, r));
+        d.x = min(d.x, r);
+    }
+    d = sqrt(d);
+    return min(2.0 / (1.0 / max(d.y - d.x, 0.001)
+                    + 1.0 / max(d.z - d.x, 0.001)), 1.0);
+}
+```
+
+### Variant 3: Voronoise (Unified Noise-Voronoi Framework)
+
+```glsl
+#define JITTER 1.0    // 0=regular grid, 1=fully random
+#define SMOOTH 0.0    // 0=sharp Voronoi, 1=smooth noise
+
+vec3 hash3(vec2 p) {
+    vec3 q = vec3(dot(p, vec2(127.1, 311.7)),
+                  dot(p, vec2(269.5, 183.3)),
+                  dot(p, vec2(419.2, 371.9)));
+    return fract(sin(q) * 43758.5453);
+}
+
+float voronoise(vec2 p, float u, float v) {
+    float k = 1.0 + 63.0 * pow(1.0 - v, 6.0);
+    vec2 i = floor(p); vec2 f = fract(p);
+    vec2 a = vec2(0.0);
+    for (int y = -2; y <= 2; y++)
+    for (int x = -2; x <= 2; x++) {
+        vec2 g = vec2(x, y);
+        vec3 o = hash3(i + g) * vec3(u, u, 1.0);
+        vec2 d = g - f + o.xy;
+        float w = pow(1.0 - smoothstep(0.0, 1.414, length(d)), k);
+        a += vec2(o.z * w, w);
+    }
+    return a.x / a.y;
+}
+```
+
+### Variant 4: Crack Texture (Multi-Layer Recursive Voronoi)
+
+```glsl
+#define CRACK_DEPTH 3.0
+#define CRACK_WIDTH 0.0
+#define CRACK_SLOPE 50.0
+
+float ofs = 0.5;
+#define disp(p) (-ofs + (1.0 + 2.0 * ofs) * hash2(p))
+
+// Main loop
+vec4 O = vec4(0.0);
+vec2 U = uv;
+for (float i = 0.0; i < CRACK_DEPTH; i++) {
+    vec2 D = fbm22(U) * 0.67;
+    vec3 H = voronoiBorder(U + D);
+    float d = H.x;
+    d = min(1.0, CRACK_SLOPE * pow(max(0.0, d - CRACK_WIDTH), 1.0));
+    O += vec4(1.0 - d) / exp2(i);
+    U *= 1.5 * rot(0.37);
+}
+```
+
+### Variant 5: Tileable 3D Worley (Cloud Noise)
+
+```glsl
+#define TILE_FREQ 4.0
+
+float worleyTileable(vec3 uv, float freq) {
+    vec3 id = floor(uv); vec3 p = fract(uv);
+    float minDist = 1e4;
+    for (float x = -1.0; x <= 1.0; x++)
+    for (float y = -1.0; y <= 1.0; y++)
+    for (float z = -1.0; z <= 1.0; z++) {
+        vec3 offset = vec3(x, y, z);
+        vec3 h = hash3_uint(mod(id + offset, vec3(freq))) * 0.5 + 0.5;
+        h += offset;
+        vec3 d = p - h;
+        minDist = min(minDist, dot(d, d));
+    }
+    return 1.0 - minDist;
+}
+
+float worleyFbm(vec3 p, float freq) {
+    return worleyTileable(p * freq, freq) * 0.625
+         + worleyTileable(p * freq * 2.0, freq * 2.0) * 0.25
+         + worleyTileable(p * freq * 4.0, freq * 4.0) * 0.125;
+}
+
+float remap(float x, float a, float b, float c, float d) {
+    return (((x - a) / (b - a)) * (d - c)) + c;
+}
+// cloud = remap(perlinNoise, worleyFbm - 1.0, 1.0, 0.0, 1.0);
+```
+
+## Performance & Composition
+
+**Performance:**
+- Use `dot(r,r)` instead of `length` during comparison; only `sqrt` for final output
+- 3D loops can be manually unrolled along the z-axis to reduce nesting
+- Search range: basic F1 uses 3x3; exact borders/Voronoise/extended jitter uses 5x5
+- Hash choice: `sin(dot(...))` is fastest; integer hash is more uniform but requires ES 3.0+
+- fBm layers: 3 is sufficient, 5 is the upper limit
+
+**Combinations:**
+- **+fBm distortion**: `uv + 0.5*fbm22(uv*2.0)` -> organic cell shapes
+- **+Bump Mapping**: finite-difference normal computation -> pseudo-3D bumps
+- **+Palette**: `0.5+0.5*cos(6.2831*(t+vec3(0,0.33,0.67)))` -> rich colors
+- **+Raymarching**: Voronoi distance as part of the SDF -> cellular surfaces
+- **+Multi-scale stacking**: Voronoi at different frequencies stacked -> primary structure + fine detail
+
+## Further Reading
+
+For complete step-by-step tutorials, mathematical derivations, and advanced usage, see [reference](../reference/voronoi-cellular-noise.md)