@rosetears/aili-pi 0.1.0

package/skills/shader-dev/techniques/multipass-buffer.md

@@ -0,0 +1,922 @@
+### Standalone HTML Complete Shader Template (Must Be Strictly Followed)
+
+**IMPORTANT: The following template can be copied directly; every line must be strictly followed**:
+
+**Vertex Shader** (common to all shaders):
+```glsl
+#version 300 es
+in vec4 iPosition;
+void main() {
+    gl_Position = iPosition;
+}
+```
+
+**Fragment Shader Buffer A Example** (particle physics simulation):
+```glsl
+#version 300 es
+precision highp float;
+
+// IMPORTANT: Critical: uniforms must be declared; ShaderToy's iTime/iResolution etc. are global variables
+uniform float iTime;
+uniform vec2 iResolution;
+uniform int iFrame;
+uniform vec4 iMouse;
+
+// IMPORTANT: Critical: mainImage parameters need manual extraction
+// ShaderToy: void mainImage(out vec4 fragColor, in vec2 fragCoord)
+// Adapted to:
+out vec4 fragColor;
+void main() {
+    vec2 fragCoord = gl_FragCoord.xy;
+    vec2 uv = fragCoord / iResolution;
+
+    // IMPORTANT: Critical: texture2D → texture
+    vec4 prev = texture(iChannel0, uv);
+
+    // ... particle physics logic ...
+
+    fragColor = vec4(pos, vel);
+}
+```
+
+**Fragment Shader Image Example**:
+```glsl
+#version 300 es
+precision highp float;
+
+uniform float iTime;
+uniform vec2 iResolution;
+uniform int iFrame;
+uniform vec4 iMouse;
+uniform sampler2D iChannel0;
+
+out vec4 fragColor;
+
+void main() {
+    vec2 fragCoord = gl_FragCoord.xy;
+    vec2 uv = fragCoord / iResolution;
+
+    // IMPORTANT: Critical: texture2D → texture, mainImage → standard main
+    vec4 col = texture(iChannel0, uv);
+
+    // Rendering logic
+    col = col / (1.0 + col);  // Tone mapping
+
+    fragColor = col;
+}
+```
+
+**IMPORTANT: Common GLSL ES 3.00 Errors** (must be avoided):
+1. **#version must be on the first line** - Any comments/blank lines will cause "version directive must occur on the first line" error
+2. **in/out qualifiers** - WebGL1's attribute/varying must be changed to in/out in ES3
+3. **texture function** - ES3 uses `texture(sampler, uv)`, not `texture2D(sampler, uv)`
+4. **Type strictness** - `vec4 = float` is illegal, must use `vec4(v, v, v, v)` or `vec4(v)` or `vec4(vec3(v), 1.0)`
+
+## Standalone HTML Multi-Channel Framebuffer Implementation
+
+**IMPORTANT: Multi-Channel Rendering Pipeline Core Pitfalls**: ShaderToy code requires manual Framebuffer rendering pipeline implementation. The following template demonstrates the correct approach:
+
+```javascript
+// Correct multi-channel Framebuffer creation
+const NUM_BUFFERS = 2;  // Buffer A, Buffer B
+const buffers = [];
+const textures = [];
+
+// Check float texture linear filtering extension
+const ext = gl.getExtension('EXT_color_buffer_float');
+const floatLinear = gl.getExtension('OES_texture_float_linear');
+
+// Each Buffer needs an independent Framebuffer + texture
+for (let i = 0; i < NUM_BUFFERS; i++) {
+    const texture = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+
+    // IMPORTANT: Critical: Must use UNSIGNED_BYTE format without EXT_color_buffer_float extension!
+    // RGBA16F/RGBA32F require the extension, otherwise GL_INVALID_OPERATION
+    // Float textures need EXT_color_buffer_float; RGBA16F supports HDR data
+    if (ext) {
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, width, height, 0, gl.RGBA, gl.FLOAT, null);
+    } else {
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+    }
+
+    // IMPORTANT: Critical: Texture parameters must be set, otherwise GL_INVALID_FRAMEBUFFER
+    // IMPORTANT: Float textures use NEAREST, or require OES_texture_float_linear extension for LINEAR
+    // IMPORTANT: Critical: Float textures must use CLAMP_TO_EDGE wrap mode; REPEAT is not supported for float textures
+    // IMPORTANT: Critical: Must fall back to UNSIGNED_BYTE format without EXT_color_buffer_float extension
+    const filterMode = (ext && floatLinear) ? gl.LINEAR : gl.NEAREST;
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filterMode);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filterMode);
+    // IMPORTANT: Must use CLAMP_TO_EDGE: float textures do not support REPEAT
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+
+    const fbo = gl.createFramebuffer();
+    gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+
+    // IMPORTANT: Critical: Check Framebuffer completeness
+    const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+    if (status !== gl.FRAMEBUFFER_COMPLETE) {
+        console.error("Framebuffer incomplete:", status);
+    }
+
+    textures.push(texture);
+    buffers.push(fbo);
+}
+gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+
+// Render loop: render to Buffer first, then render to screen
+function render() {
+    // 1. Render to Buffer A (self-feedback reads previous Buffer)
+    gl.bindFramebuffer(gl.FRAMEBUFFER, buffers[0]);
+    gl.viewport(0, 0, width, height);
+    // Bind previous frame texture to iChannel0
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, textures[1]);  // Read from other Buffer
+    // Set uniforms etc...
+    // Execute shader rendering
+
+    // 2. Swap Buffers (simulate self-feedback)
+    // IMPORTANT: Critical: Must swap textures for next frame reading; FBO handles remain unchanged
+    [textures[0], textures[1]] = [textures[1], textures[0]];
+
+    // 3. Render to screen
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    // Bind Buffer result to texture
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, textures[0]);
+    // Execute Image pass shader
+}
+```
+
+**IMPORTANT: Common Errors** (JavaScript/WebGL side):
+1. **Missing texture parameters** - Must set `TEXTURE_MIN_FILTER`, `TEXTURE_MAG_FILTER`, `TEXTURE_WRAP_S/T`
+2. **Missing Framebuffer completeness check** - `gl.checkFramebufferStatus()` must return `FRAMEBUFFER_COMPLETE` before use
+3. **Float texture extension** - `gl.RGBA16F` requires `EXT_color_buffer_float` extension, otherwise fall back to `gl.UNSIGNED_BYTE`
+4. **Buffer ping-pong error** - Self-feedback must use 2 independent FBOs alternating read/write; a single FBO + texture swap causes "Feedback loop" error
+5. **Particle system empty texture initialization** - Textures are empty before the first frame; shaders reading default values cause render failure — must execute initPass() to pre-render
+
+# Multi-Pass Buffer Techniques
+
+## Use Cases
+
+When single-frame computation cannot achieve the desired effect and cross-frame data persistence or multi-stage processing pipelines are needed, use multi-pass buffers:
+
+- **Temporal accumulation**: Motion blur, TAA, progressive rendering
+- **Physics simulation**: Fluids, reaction-diffusion, particle systems
+- **Persistent state**: Game state, particle positions/velocities, interaction history
+- **Deferred rendering**: G-Buffer → post-processing → compositing
+- **Post-processing chains**: HDR Bloom (downsample → blur → composite)
+- **Iterative solvers**: Poisson solver, vorticity confinement, multi-scale computation
+
+## Core Principles
+
+Multi-pass buffers split the rendering pipeline into multiple Buffers, each outputting a texture as input for the next stage.
+
+### Self-Feedback
+A Buffer reads its own previous frame output, achieving cross-frame state persistence: `x(n+1) = f(x(n))`
+```
+Buffer A (frame N) reads → Buffer A (frame N-1) output
+```
+
+### Pipeline Chaining
+Multiple Buffers process in sequence:
+```
+Buffer A (geometry) → Buffer B (blur H) → Buffer C (blur V) → Image (compositing)
+```
+
+### Structured Data Storage
+Specific pixels serve as data registers, read precisely via `texelFetch`:
+```
+texel (0,0) = ball position+velocity (vec4)
+texel (1,0) = paddle position
+texel (x,1)-(x,12) = brick grid state
+```
+
+### Key Mathematical Patterns
+
+- **Fluid self-advection**: `newPos = texture(buf, uv - dt * velocity * texelSize)`
+- **Gaussian blur**: `sum += texture(buf, uv + offset_i) * weight_i`
+- **Temporal blending**: `result = mix(newFrame, prevFrame, blendWeight)`
+- **Vorticity confinement**: `vortForce = curl × normalize(gradient(|curl|))`
+
+## Implementation Steps
+
+### Step 1: Minimal Self-Feedback Loop
+
+Buffer A (iChannel0 → Buffer A self-feedback):
+```glsl
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec2 uv = fragCoord / iResolution.xy;
+
+    vec4 prev = texture(iChannel0, uv);
+
+    // New content: procedural noise contour lines
+    float n = noise(vec3(uv * 8.0, 0.1 * iTime));
+    float v = sin(6.2832 * 10.0 * n);
+    v = smoothstep(1.0, 0.0, 0.5 * abs(v) / fwidth(v));
+    vec4 newContent = 0.5 + 0.5 * sin(12.0 * n + vec4(0, 2.1, -2.1, 0));
+
+    // Decay + offset blending
+    vec4 decayed = exp(-33.0 / iResolution.y) * texture(iChannel0, (fragCoord + vec2(1.0, sin(iTime))) / iResolution.xy);
+    fragColor = mix(decayed, newContent, v);
+
+    // Initialization guard
+    if (iFrame < 4) fragColor = vec4(0.5);
+}
+```
+
+Image (iChannel0 → Buffer A):
+```glsl
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    fragColor = texture(iChannel0, fragCoord / iResolution.xy);
+}
+```
+
+### Step 2: Fluid Self-Advection
+
+Buffer A (iChannel0 → Buffer A self-feedback):
+```glsl
+#define ROT_NUM 5
+#define SCALE_NUM 20
+
+const float ang = 6.2832 / float(ROT_NUM);
+mat2 m = mat2(cos(ang), sin(ang), -sin(ang), cos(ang));
+
+float getRot(vec2 pos, vec2 b) {
+    vec2 p = b;
+    float rot = 0.0;
+    for (int i = 0; i < ROT_NUM; i++) {
+        rot += dot(texture(iChannel0, fract((pos + p) / iResolution.xy)).xy - vec2(0.5),
+                   p.yx * vec2(1, -1));
+        p = m * p;
+    }
+    return rot / float(ROT_NUM) / dot(b, b);
+}
+
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec2 pos = fragCoord;
+    float rnd = fract(sin(float(iFrame) * 12.9898) * 43758.5453);
+    vec2 b = vec2(cos(ang * rnd), sin(ang * rnd));
+
+    // Multi-scale rotation sampling
+    vec2 v = vec2(0);
+    float bbMax = 0.7 * iResolution.y;
+    bbMax *= bbMax;
+    for (int l = 0; l < SCALE_NUM; l++) {
+        if (dot(b, b) > bbMax) break;
+        vec2 p = b;
+        for (int i = 0; i < ROT_NUM; i++) {
+            v += p.yx * getRot(pos + p, b);
+            p = m * p;
+        }
+        b *= 2.0;
+    }
+
+    // Self-advection
+    fragColor = texture(iChannel0, fract((pos + v * vec2(-1, 1) * 2.0) / iResolution.xy));
+
+    // Center driving force
+    vec2 scr = (fragCoord / iResolution.xy) * 2.0 - 1.0;
+    fragColor.xy += 0.01 * scr / (dot(scr, scr) / 0.1 + 0.3);
+
+    if (iFrame <= 4) fragColor = texture(iChannel1, fragCoord / iResolution.xy);
+}
+```
+
+### Step 3-4: Navier-Stokes Solver + Chained Acceleration
+
+Buffer A / B / C use identical code (via Common tab's `solveFluid`):
+```glsl
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec2 uv = fragCoord / iResolution.xy;
+    vec2 w = 1.0 / iResolution.xy;
+
+    vec4 lastMouse = texelFetch(iChannel0, ivec2(0, 0), 0);
+    vec4 data = solveFluid(iChannel0, uv, w, iTime, iMouse.xyz, lastMouse.xyz);
+
+    if (iFrame < 20) data = vec4(0.5, 0, 0, 0);
+    if (fragCoord.y < 1.0) data = iMouse;  // Mouse state storage
+
+    fragColor = data;
+}
+```
+
+iChannel bindings: A→C(prev frame), B→A, C→B — 3 iterations per frame.
+
+### Step 5: Separable Gaussian Blur
+
+Buffer B (horizontal, iChannel0 → source Buffer) — Buffer C vertical direction is analogous, using y-axis offset:
+```glsl
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec2 pixelSize = 1.0 / iResolution.xy;
+    vec2 uv = fragCoord * pixelSize;
+    float h = pixelSize.x;
+    vec4 sum = vec4(0.0);
+    // 9-tap Gaussian (sigma ≈ 2.0)
+    sum += texture(iChannel0, fract(vec2(uv.x - 4.0*h, uv.y))) * 0.05;
+    sum += texture(iChannel0, fract(vec2(uv.x - 3.0*h, uv.y))) * 0.09;
+    sum += texture(iChannel0, fract(vec2(uv.x - 2.0*h, uv.y))) * 0.12;
+    sum += texture(iChannel0, fract(vec2(uv.x - 1.0*h, uv.y))) * 0.15;
+    sum += texture(iChannel0, fract(vec2(uv.x,          uv.y))) * 0.16;
+    sum += texture(iChannel0, fract(vec2(uv.x + 1.0*h, uv.y))) * 0.15;
+    sum += texture(iChannel0, fract(vec2(uv.x + 2.0*h, uv.y))) * 0.12;
+    sum += texture(iChannel0, fract(vec2(uv.x + 3.0*h, uv.y))) * 0.09;
+    sum += texture(iChannel0, fract(vec2(uv.x + 4.0*h, uv.y))) * 0.05;
+    fragColor = vec4(sum.xyz / 0.98, 1.0);
+}
+```
+
+### Step 6: Structured State Storage
+
+```glsl
+// Register address definitions
+const ivec2 txBallPosVel = ivec2(0, 0);
+const ivec2 txPaddlePos  = ivec2(1, 0);
+const ivec2 txPoints     = ivec2(2, 0);
+const ivec2 txState      = ivec2(3, 0);
+const ivec4 txBricks     = ivec4(0, 1, 13, 12);
+
+vec4 loadValue(ivec2 addr) {
+    return texelFetch(iChannel0, addr, 0);
+}
+
+void storeValue(ivec2 addr, vec4 val, inout vec4 fragColor, ivec2 currentPixel) {
+    fragColor = (currentPixel == addr) ? val : fragColor;
+}
+
+void storeValue(ivec4 rect, vec4 val, inout vec4 fragColor, ivec2 currentPixel) {
+    fragColor = (currentPixel.x >= rect.x && currentPixel.y >= rect.y &&
+                 currentPixel.x <= rect.z && currentPixel.y <= rect.w) ? val : fragColor;
+}
+
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    ivec2 px = ivec2(fragCoord - 0.5);
+    if (fragCoord.x > 14.0 || fragCoord.y > 14.0) discard;
+
+    vec4 ballPosVel = loadValue(txBallPosVel);
+    float paddlePos = loadValue(txPaddlePos).x;
+    float points = loadValue(txPoints).x;
+
+    if (iFrame == 0) {
+        ballPosVel = vec4(0.0, -0.8, 0.6, 1.0);
+        paddlePos = 0.0;
+        points = 0.0;
+    }
+
+    // ... game logic update ...
+
+    fragColor = loadValue(px);
+    storeValue(txBallPosVel, ballPosVel, fragColor, px);
+    storeValue(txPaddlePos, vec4(paddlePos, 0, 0, 0), fragColor, px);
+    storeValue(txPoints, vec4(points, 0, 0, 0), fragColor, px);
+}
+```
+
+### Step 7: Mouse State Inter-Frame Tracking
+
+```glsl
+// Method 1: First-row pixel storage
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec2 uv = fragCoord / iResolution.xy;
+    vec2 w = 1.0 / iResolution.xy;
+    vec4 lastMouse = texelFetch(iChannel0, ivec2(0, 0), 0);
+    // ... simulation logic ...
+    if (fragCoord.y < 1.0) fragColor = iMouse;
+}
+
+// Method 2: Fixed UV region storage
+vec2 mouseDelta() {
+    vec2 pixelSize = 1.0 / iResolution.xy;
+    float eighth = 1.0 / 8.0;
+    vec4 oldMouse = texture(iChannel2, vec2(7.5 * eighth, 2.5 * eighth));
+    vec4 nowMouse = vec4(iMouse.xy / iResolution.xy, iMouse.zw / iResolution.xy);
+    if (oldMouse.z > pixelSize.x && oldMouse.w > pixelSize.y &&
+        nowMouse.z > pixelSize.x && nowMouse.w > pixelSize.y) {
+        return nowMouse.xy - oldMouse.xy;
+    }
+    return vec2(0.0);
+}
+```
+
+## Complete Code Template
+
+A fully runnable fluid simulation shader (self-feedback + vorticity confinement + mouse interaction + color advection).
+
+### Common tab
+
+```glsl
+#define DT 0.15
+#define VORTICITY_AMOUNT 0.11
+#define VISCOSITY 0.55
+#define PRESSURE_K 0.2
+#define FORCE_RADIUS 0.001
+#define FORCE_STRENGTH 0.001
+#define VELOCITY_DECAY 1e-4
+
+float mag2(vec2 p) { return dot(p, p); }
+
+vec2 emitter1(float t) { t *= 0.62; return vec2(0.12, 0.5 + sin(t) * 0.2); }
+vec2 emitter2(float t) { t *= 0.62; return vec2(0.88, 0.5 + cos(t + 1.5708) * 0.2); }
+
+vec4 solveFluid(sampler2D smp, vec2 uv, vec2 w, float time, vec3 mouse, vec3 lastMouse) {
+    vec4 data = textureLod(smp, uv, 0.0);
+    vec4 tr = textureLod(smp, uv + vec2(w.x, 0), 0.0);
+    vec4 tl = textureLod(smp, uv - vec2(w.x, 0), 0.0);
+    vec4 tu = textureLod(smp, uv + vec2(0, w.y), 0.0);
+    vec4 td = textureLod(smp, uv - vec2(0, w.y), 0.0);
+
+    vec3 dx = (tr.xyz - tl.xyz) * 0.5;
+    vec3 dy = (tu.xyz - td.xyz) * 0.5;
+    vec2 densDif = vec2(dx.z, dy.z);
+
+    data.z -= DT * dot(vec3(densDif, dx.x + dy.y), data.xyz);
+
+    vec2 laplacian = tu.xy + td.xy + tr.xy + tl.xy - 4.0 * data.xy;
+    vec2 viscForce = vec2(VISCOSITY) * laplacian;
+
+    data.xyw = textureLod(smp, uv - DT * data.xy * w, 0.0).xyw;
+
+    vec2 newForce = vec2(0);
+    newForce += 0.75 * vec2(0.0003, 0.00015) / (mag2(uv - emitter1(time)) + 0.0001);
+    newForce -= 0.75 * vec2(0.0003, 0.00015) / (mag2(uv - emitter2(time)) + 0.0001);
+
+    if (mouse.z > 1.0 && lastMouse.z > 1.0) {
+        vec2 vv = clamp((mouse.xy * w - lastMouse.xy * w) * 400.0, -6.0, 6.0);
+        newForce += FORCE_STRENGTH / (mag2(uv - mouse.xy * w) + FORCE_RADIUS) * vv;
+    }
+
+    data.xy += DT * (viscForce - PRESSURE_K / DT * densDif + newForce);
+    data.xy = max(vec2(0), abs(data.xy) - VELOCITY_DECAY) * sign(data.xy);
+
+    data.w = (tr.y - tl.y - tu.x + td.x);
+    vec2 vort = vec2(abs(tu.w) - abs(td.w), abs(tl.w) - abs(tr.w));
+    vort *= VORTICITY_AMOUNT / length(vort + 1e-9) * data.w;
+    data.xy += vort;
+
+    data.y *= smoothstep(0.5, 0.48, abs(uv.y - 0.5));
+    data = clamp(data, vec4(vec2(-10), 0.5, -10.0), vec4(vec2(10), 3.0, 10.0));
+
+    return data;
+}
+```
+
+### Buffer A / B / C (Fluid Sub-Steps 1/2/3)
+
+iChannel bindings: A←C(prev frame), B←A, C←B
+
+```glsl
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec2 uv = fragCoord / iResolution.xy;
+    vec2 w = 1.0 / iResolution.xy;
+    vec4 lastMouse = texelFetch(iChannel0, ivec2(0, 0), 0);
+    vec4 data = solveFluid(iChannel0, uv, w, iTime, iMouse.xyz, lastMouse.xyz);
+    if (iFrame < 20) data = vec4(0.5, 0, 0, 0);
+    if (fragCoord.y < 1.0) data = iMouse;
+    fragColor = data;
+}
+```
+
+### Buffer D (Color Advection, iChannel0 → Buffer C, iChannel1 → Buffer D self-feedback)
+
+```glsl
+#define COLOR_DECAY 0.004
+#define COLOR_ADVECT_SCALE 3.0
+
+vec3 getPalette(float x, vec3 c1, vec3 c2, vec3 p1, vec3 p2) {
+    float x2 = fract(x / 2.0);
+    x = fract(x);
+    mat3 m = mat3(c1, p1, c2);
+    mat3 m2 = mat3(c2, p2, c1);
+    float omx = 1.0 - x;
+    vec3 pws = vec3(omx * omx, 2.0 * omx * x, x * x);
+    return clamp(mix(m * pws, m2 * pws, step(x2, 0.5)), 0.0, 1.0);
+}
+
+vec4 palette1(float x) {
+    return vec4(getPalette(-x, vec3(0.2, 0.5, 0.7), vec3(0.9, 0.4, 0.1),
+                vec3(1.0, 1.2, 0.5), vec3(1.0, -0.4, 0.0)), 1.0);
+}
+vec4 palette2(float x) {
+    return vec4(getPalette(-x, vec3(0.4, 0.3, 0.5), vec3(0.9, 0.75, 0.4),
+                vec3(0.1, 0.8, 1.3), vec3(1.25, -0.1, 0.1)), 1.0);
+}
+
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec2 uv = fragCoord / iResolution.xy;
+    vec2 w = 1.0 / iResolution.xy;
+
+    vec2 velo = textureLod(iChannel0, uv, 0.0).xy;
+    vec4 col = textureLod(iChannel1, uv - DT * velo * w * COLOR_ADVECT_SCALE, 0.0);
+
+    vec2 mo = iMouse.xy / iResolution.xy;
+    vec4 lastMouse = texelFetch(iChannel1, ivec2(0, 0), 0);
+    if (iMouse.z > 1.0 && lastMouse.z > 1.0) {
+        float str = smoothstep(-0.5, 1.0, length(mo - lastMouse.xy / iResolution.xy));
+        col += str * 0.0009 / (pow(length(uv - mo), 1.7) + 0.002) * palette2(-iTime * 0.7);
+    }
+
+    col += 0.0025 / (0.0005 + pow(length(uv - emitter1(iTime)), 1.75)) * DT * 0.12 * palette1(iTime * 0.05);
+    col += 0.0025 / (0.0005 + pow(length(uv - emitter2(iTime)), 1.75)) * DT * 0.12 * palette2(iTime * 0.05 + 0.675);
+
+    if (iFrame < 20) col = vec4(0.0);
+    col = clamp(col, 0.0, 5.0);
+    col = max(col - (0.0001 + col * COLOR_DECAY) * 0.5, 0.0);
+
+    if (fragCoord.y < 1.0 && fragCoord.x < 1.0) col = iMouse;
+    fragColor = col;
+}
+```
+
+### Image (iChannel0 → Buffer D)
+
+```glsl
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec4 col = textureLod(iChannel0, fragCoord / iResolution.xy, 0.0);
+    if (fragCoord.y < 1.0 || fragCoord.y >= iResolution.y - 1.0) col = vec4(0);
+    fragColor = col;
+}
+```
+
+## Common Variants
+
+### Variant 1: TAA Temporal Accumulation Anti-Aliasing
+
+```glsl
+// Buffer A: Sub-pixel jittered rendering
+vec2 jitter = vec2(rand(uv + sin(iTime)), rand(uv + 1.0 + sin(iTime))) / iResolution.xy;
+vec3 eyevec = normalize(vec3(((uv + jitter) * 2.0 - 1.0) * vec2(aspect, 1.0), fov));
+float blendWeight = 0.9;
+color = mix(color, texture(iChannel_self, uv).rgb, blendWeight);
+
+// Buffer C (TAA): YCoCg neighborhood clamping to prevent ghosting
+vec3 newYCC = RGBToYCoCg(newFrame);
+vec3 histYCC = RGBToYCoCg(history);
+vec3 colorAvg = ...; vec3 colorVar = ...;
+vec3 sigma = sqrt(max(vec3(0), colorVar - colorAvg * colorAvg));
+histYCC = clamp(histYCC, colorAvg - 0.75 * sigma, colorAvg + 0.75 * sigma);
+result = YCoCgToRGB(mix(newYCC, histYCC, 0.95));
+```
+
+### Variant 2: Deferred Rendering G-Buffer
+
+```glsl
+// Buffer A: G-Buffer output
+col.xy = (normal * camMat * 0.5 + 0.5).xy;  // Normal
+col.z = 1.0 - abs((t * rd) * camMat).z / DMAX;  // Depth
+col.w = dot(lightDir, nor) * 0.5 + 0.5;  // Diffuse
+
+// Buffer B: Edge detection
+float checkSame(vec4 center, vec4 sample) {
+    vec2 diffNormal = abs(center.xy - sample.xy) * Sensitivity.x;
+    float diffDepth = abs(center.z - sample.z) * Sensitivity.y;
+    return (diffNormal.x + diffNormal.y < 0.1 && diffDepth < 0.1) ? 1.0 : 0.0;
+}
+```
+
+### Variant 3: HDR Bloom
+
+```glsl
+// Buffer B: MIP pyramid (multi-level downsampling packed into one texture)
+vec2 CalcOffset(float octave) {
+    vec2 offset = vec2(0);
+    vec2 padding = vec2(10.0) / iResolution.xy;
+    offset.x = -min(1.0, floor(octave / 3.0)) * (0.25 + padding.x);
+    offset.y = -(1.0 - 1.0 / exp2(octave)) - padding.y * octave;
+    offset.y += min(1.0, floor(octave / 3.0)) * 0.35;
+    return offset;
+}
+// Image: Accumulate multi-level bloom + Reinhard tone mapping
+bloom += Grab(coord, 1.0, CalcOffset(0.0)) * 1.0;
+bloom += Grab(coord, 2.0, CalcOffset(1.0)) * 1.5;
+color = pow(color, vec3(1.5));
+color = color / (1.0 + color);
+```
+
+### Variant 4: Reaction-Diffusion System
+
+```glsl
+// Buffer A: Gray-Scott reaction-diffusion
+vec2 uv_red = uv + vec2(dx.x, dy.x) * pixelSize * 8.0;
+float new_val = texture(iChannel0, fract(uv_red)).x;
+new_val += (noise.x - 0.5) * 0.0025 - 0.002;
+new_val -= (texture(iChannel_blur, fract(uv_red)).x -
+            texture(iChannel_self, fract(uv_red)).x) * 0.047;
+```
+
+### Variant 5: Multi-Scale MIP Fluid
+
+```glsl
+for (int i = 0; i < NUM_SCALES; i++) {
+    float mip = float(i);
+    float stride = float(1 << i);
+    vec4 t = stride * vec4(texel, -texel.y, 0);
+    vec2 d = textureLod(sampler, fract(uv + t.ww), mip).xy;
+    float w = WEIGHT_FUNCTION;
+    result += w * computation(neighbors);
+}
+```
+
+### Variant 6: Particle System (Position-Velocity Storage)
+
+**IMPORTANT: Particle System Implementation Key**: Particle state is stored in texture pixels, one particle per pixel. Rendering must iterate over the particle texture for sampling.
+
+**Buffer A (Particle Physics Simulation)**:
+```glsl
+// Each texture pixel stores one particle: xy=position, zw=velocity
+
+// IMPORTANT: Critical: hash function must return vec2! Returning float causes type mismatch errors
+vec2 hash2(vec2 p) {
+    return fract(sin(mat2(127.1, 311.7, 269.5, 183.3) * p) * 43758.5453);
+}
+
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec2 uv = fragCoord / iResolution.xy;
+    vec4 prev = texture(iChannel0, uv);
+
+    vec2 pos = prev.xy;
+    vec2 vel = prev.zw;
+
+    // IMPORTANT: Initialization guard: use integer comparison + pixel-coordinate-based random (avoids particle overlap when time is too small)
+    if (iFrame < 3) {
+        // Use fragCoord (pixel coordinates) to ensure each particle has a unique position, independent of time
+        // IMPORTANT: Critical: hash2 returns vec2, assign directly to pos/vel
+        pos = hash2(fragCoord * 0.01 + vec2(1.7, 9.3));
+        vel = (hash2(fragCoord * 0.01 + vec2(5.3, 2.8)) - 0.5) * 0.02;
+        fragColor = vec4(pos, vel);
+        return;
+    }
+
+    // Physics update
+    vel *= 0.98;  // Damping
+
+    // Mouse interaction
+    vec2 mouse = iMouse.xy / iResolution.xy;
+    if (iMouse.z > 0.0) {
+        vec2 toMouse = mouse - pos;
+        vel += normalize(toMouse + 0.001) * 0.0005 / (length(toMouse) + 0.1);
+    }
+
+    // Motion
+    pos += vel * 60.0 * 0.016;
+    pos = fract(pos);  // Boundary wrapping
+
+    fragColor = vec4(pos, vel);
+}
+```
+
+**Image (Render Particles)**:
+```glsl
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec2 uv = fragCoord / iResolution.xy;
+    vec2 w = 1.0 / iResolution.xy;
+
+    vec3 color = vec3(0.02, 0.02, 0.05);  // Dark background
+
+    // Iterate over particle texture for sampling (performance-sensitive, balance sample count)
+    float glow = 0.0;
+    for (float y = 0.0; y < 1.0; y += 0.02) {  // IMPORTANT: Step size determines sampling density
+        for (float x = 0.0; x < 1.0; x += 0.02) {
+            vec4 particle = texture(iChannel0, vec2(x, y));
+            vec2 pPos = particle.xy;
+            float dist = length(uv - pPos);
+            float size = 0.01 + length(particle.zw) * 0.3;
+            glow += exp(-dist * dist / (size * size)) * 0.15;
+        }
+    }
+
+    // Particle glow
+    color += vec3(0.3, 0.6, 1.0) * glow;
+
+    // Vignette
+    color *= 1.0 - length(uv - 0.5) * 0.8;
+
+    // Tone mapping
+    color = color / (1.0 + color);
+
+    fragColor = vec4(color, 1.0);
+}
+```
+
+**Key Points**:
+- Buffer A self-feedback: iChannel0 → Buffer A
+- Image reads: iChannel0 → Buffer A (particle state)
+- Step size 0.02 produces 2500 samples; adjust based on performance
+- Particle size varies with velocity: `size = 0.01 + length(vel) * 0.3`
+
+**Complete JavaScript Rendering Pipeline (Particle System 3-Pass)**:
+```javascript
+// Particle system needs 4 Framebuffers (2 each for Buffer A and Buffer B ping-pong) + screen output
+// Buffer A: Particle physics (self-feedback) - uses FBO 0/1 ping-pong
+// Buffer B: Density accumulation (reads Buffer A) - uses FBO 2/3 ping-pong
+// Image: Final rendering (reads Buffer A + Buffer B)
+
+// IMPORTANT: Critical: Must use 2 FBOs for ping-pong! Single FBO + texture swap causes
+// "Feedback loop formed between Framebuffer and active Texture" error
+const buffers = [null, null, null, null];  // [A_FBO0, A_FBO1, B_FBO0, B_FBO1]
+const textures = [null, null, null, null];  // [A_tex0, A_tex1, B_tex0, B_tex1]
+
+function createBuffers() {
+    // Buffer A: 2 FBOs for ping-pong
+    for (let i = 0; i < 2; i++) {
+        const tex = createTexture();
+        textures[i] = tex;
+
+        const fbo = gl.createFramebuffer();
+        gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, tex, 0);
+        buffers[i] = fbo;
+    }
+    // Buffer B: 2 FBOs for ping-pong
+    for (let i = 0; i < 2; i++) {
+        const tex = createTexture();
+        textures[2 + i] = tex;
+
+        const fbo = gl.createFramebuffer();
+        gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, tex, 0);
+        buffers[2 + i] = fbo;
+    }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+}
+
+// IMPORTANT: Critical: Initialization pre-rendering - must execute before the first frame!
+// Empty textures cause particle initialization failure (reading 0,0,0,0 makes all particles overlap)
+let aReadIdx = 0;  // Current read FBO index (0 or 1)
+let bReadIdx = 0;  // Buffer B current read FBO index (0 or 1)
+
+function initPass() {
+    // ===== Buffer A Initialization =====
+    // Render first frame using FBO 0
+    gl.bindFramebuffer(gl.FRAMEBUFFER, buffers[0]);
+    gl.viewport(0, 0, width, height);
+    gl.useProgram(programBufferA);
+    setupAttribute(programBufferA);
+    // Bind FBO 1's texture as input (not yet rendered, but avoids binding errors)
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, textures[1]);
+    gl.uniform1i(gl.getUniformLocation(programBufferA, 'iChannel0'), 0);
+    gl.uniform2f(gl.getUniformLocation(programBufferA, 'iResolution'), width, height);
+    gl.uniform1f(gl.getUniformLocation(programBufferA, 'iTime'), 0);
+    gl.uniform1i(gl.getUniformLocation(programBufferA, 'iFrame'), 0);
+    gl.uniform4f(gl.getUniformLocation(programBufferA, 'iMouse'), 0, 0, 0, 0);
+    gl.drawArrays(gl.TRIANGLES, 0, 6);
+
+    // Render second frame using FBO 1 (iFrame=1)
+    gl.bindFramebuffer(gl.FRAMEBUFFER, buffers[1]);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, textures[0]);  // Read FBO 0's result
+    gl.uniform1i(gl.getUniformLocation(programBufferA, 'iFrame'), 1);
+    gl.drawArrays(gl.TRIANGLES, 0, 6);
+
+    // Render one more frame to ensure initialization is complete
+    gl.bindFramebuffer(gl.FRAMEBUFFER, buffers[0]);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, textures[1]);
+    gl.uniform1i(gl.getUniformLocation(programBufferA, 'iFrame'), 2);
+    gl.drawArrays(gl.TRIANGLES, 0, 6);
+
+    // ===== Buffer B Initialization =====
+    gl.bindFramebuffer(gl.FRAMEBUFFER, buffers[2]);  // B_FBO0
+    gl.viewport(0, 0, width, height);
+    gl.useProgram(programBufferB);
+    setupAttribute(programBufferB);
+
+    // Bind latest Buffer A result (FBO 0's result)
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, textures[0]);
+    gl.uniform1i(gl.getUniformLocation(programBufferB, 'iChannel0'), 0);
+
+    // Bind Buffer B previous frame (FBO 3's texture, not yet rendered)
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, textures[3]);
+    gl.uniform1i(gl.getUniformLocation(programBufferB, 'iChannel1'), 1);
+
+    gl.uniform2f(gl.getUniformLocation(programBufferB, 'iResolution'), width, height);
+    gl.uniform1f(gl.getUniformLocation(programBufferB, 'iTime'), 0);
+    gl.uniform1i(gl.getUniformLocation(programBufferB, 'iFrame'), 0);
+    gl.drawArrays(gl.TRIANGLES, 0, 6);
+
+    // Buffer B second frame
+    gl.bindFramebuffer(gl.FRAMEBUFFER, buffers[3]);  // B_FBO1
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, textures[1]);  // Buffer A latest
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, textures[2]);  // Buffer B FBO0 result
+    gl.uniform1i(gl.getUniformLocation(programBufferB, 'iFrame'), 1);
+    gl.drawArrays(gl.TRIANGLES, 0, 6);
+
+    // Initialize ping-pong indices
+    aReadIdx = 0;  // Next frame reads FBO 0
+    bReadIdx = 0;  // Next frame reads FBO 2
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+}
+
+function render() {
+    // ===== Pass 1: Buffer A (Particle Physics Self-Feedback) =====
+    // aReadIdx = 0: read FBO 0, write FBO 1
+    // aReadIdx = 1: read FBO 1, write FBO 0
+    const aWriteIdx = 1 - aReadIdx;
+
+    // Write to target FBO (not the current read FBO)
+    gl.bindFramebuffer(gl.FRAMEBUFFER, buffers[aWriteIdx]);
+    gl.viewport(0, 0, width, height);
+
+    // Read previous frame Buffer A texture (from current read FBO's texture)
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, textures[aReadIdx]);
+    gl.uniform1i(uniformsBufferA.iChannel0, 0);
+
+    gl.uniform2f(uniformsBufferA.iResolution, width, height);
+    gl.uniform1f(uniformsBufferA.iTime, time);
+    gl.uniform1i(uniformsBufferA.iFrame, frameCount);
+    gl.uniform4f(uniformsBufferA.iMouse, mouse.x, mouse.y, mouse.z, mouse.w);
+
+    // Render particle physics
+    gl.useProgram(programBufferA);
+    gl.drawArrays(gl.TRIANGLES, 0, 6);
+
+    // Switch read index
+    aReadIdx = aWriteIdx;
+
+    // ===== Pass 2: Buffer B (Density Field) =====
+    const bWriteIdx = 1 - bReadIdx;
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, buffers[2 + bWriteIdx]);  // B_FBO0 or B_FBO1
+    gl.viewport(0, 0, width, height);
+
+    // Bind current Buffer A particle state (use latest Buffer A result)
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, textures[aReadIdx]);  // A latest result
+    gl.uniform1i(uniformsBufferB.iChannel0, 0);
+
+    // Bind previous frame Buffer B density (for accumulation)
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, textures[2 + bReadIdx]);  // B_read
+    gl.uniform1i(uniformsBufferB.iChannel1, 1);
+
+    gl.uniform2f(uniformsBufferB.iResolution, width, height);
+    gl.uniform1f(uniformsBufferB.iTime, time);
+    gl.uniform1i(uniformsBufferB.iFrame, frameCount);
+
+    // Render density accumulation
+    gl.useProgram(programBufferB);
+    gl.drawArrays(gl.TRIANGLES, 0, 6);
+
+    // Switch Buffer B read index
+    bReadIdx = bWriteIdx;
+
+    // ===== Pass 3: Image (Final Rendering to Screen) =====
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.viewport(0, 0, width, height);
+
+    // Bind Buffer A particles (use latest Buffer A result)
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, textures[aReadIdx]);
+    gl.uniform1i(uniformsImage.iChannel0, 0);
+
+    // Bind Buffer B density (use latest Buffer B result)
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, textures[2 + bReadIdx]);
+    gl.uniform1i(uniformsImage.iChannel1, 1);
+
+    gl.uniform2f(uniformsImage.iResolution, width, height);
+    gl.uniform1f(uniformsImage.iTime, time);
+    gl.uniform1i(uniformsImage.iFrame, frameCount);
+    gl.uniform4f(uniformsImage.iMouse, mouse.x, mouse.y, mouse.z, mouse.w);
+
+    // Render to screen
+    gl.useProgram(programImage);
+    gl.drawArrays(gl.TRIANGLES, 0, 6);
+}
+```
+
+**IMPORTANT: Key Points**:
+- **Must use 2 FBOs for ping-pong**: Each Buffer needs two independent FBOs (read FBO + write FBO); a single FBO + texture swap causes "Feedback loop" error
+- Use FBO index switching (not texture swapping): bind target FBO when writing, bind source texture when reading
+- Image pass binds the latest Buffer results (obtained via read index)
+
+## Performance & Composition
+
+**Performance Optimization**:
+- Separable blur: N² → 2N samples
+- Bilinear tap trick: 5 samples replace 9-tap Gaussian
+- MIP sampling replaces large kernels: `textureLod` at high MIP levels ≈ large-range average
+- `discard` outside data regions to skip unnecessary computation
+- RGBA channel packing: velocity(xy) + density(z) + curl(w) in one vec4
+- Chained sub-steps: A→B→C same code for 3x simulation speed
+- `if (dot(b,b) > bbMax) break;` adaptive early exit
+- `iFrame < 20` progressive initialization to prevent explosion
+
+**Typical Composition Patterns**:
+- **Fluid + Lighting**: Fluid buffer → Image computes gradient normals → diffuse + specular
+- **Fluid + Color Advection**: Separate Buffer tracks color field, advected by velocity field
+- **Scene + Bloom + TAA**: 4-Buffer pipeline (render → downsample → blur → composite tone mapping)
+- **G-Buffer + Screen-Space Effects**: 2-Buffer without temporal feedback (geometry → edge/SSAO/SSR → stylized compositing)
+- **State Storage + Visualization Separation**: Buffer A pure logic + Image pure rendering (`texelFetch` reads state + distance field drawing)
+
+## Further Reading
+
+For complete step-by-step tutorials, mathematical derivations, and advanced usage, see [reference](../reference/multipass-buffer.md)