@rosetears/aili-pi 0.1.0

package/skills/shader-dev/reference/ray-marching.md

@@ -0,0 +1,396 @@
+# Ray Marching Detailed Reference
+
+This document serves as a detailed reference for the Ray Marching Skill, covering prerequisites, step-by-step tutorials, mathematical derivations, and advanced usage.
+
+## Prerequisites
+
+- **GLSL Basics**: uniforms, varyings, built-in functions (`mix`, `clamp`, `smoothstep`, `normalize`, `dot`, `cross`, `reflect`, `refract`)
+- **Vector Math**: dot product, cross product, vector normalization, matrix multiplication
+- **Coordinate Systems**: transformations from screen space to NDC to view space to world space
+- **Basic Lighting Models**: diffuse (Lambertian), specular (Phong/Blinn-Phong)
+
+## Implementation Steps in Detail
+
+### Step 1: UV Coordinate Normalization and Ray Direction Computation
+
+**What**: Convert pixel coordinates to normalized coordinates in the [-1,1] range, and compute the ray direction from the camera.
+
+**Why**: This establishes the mapping from screen pixels to the 3D world. Dividing by `iResolution.y` preserves the aspect ratio; the z component controls the field of view.
+
+```glsl
+// Method A: Concise version (common for quick prototyping)
+vec2 uv = (2.0 * fragCoord - iResolution.xy) / iResolution.y;
+vec3 ro = vec3(0.0, 0.0, -3.0);             // Ray origin (camera position)
+vec3 rd = normalize(vec3(uv, 1.0));          // Ray direction, z=1.0 gives ~90° FOV
+
+// Method B: Precise FOV control
+vec2 xy = fragCoord - iResolution.xy / 2.0;
+float z = iResolution.y / tan(radians(FOV) / 2.0); // FOV is adjustable: field of view in degrees
+vec3 rd = normalize(vec3(xy, -z));
+```
+
+### Step 2: Building the Camera Matrix (Look-At)
+
+**What**: Construct a view matrix from the camera position, target point, and up direction, then transform the view-space ray direction into world space.
+
+**Why**: Without a camera matrix, the ray direction is fixed along -Z. With a Look-At matrix, the camera can be freely positioned and rotated.
+
+```glsl
+mat3 setCamera(vec3 ro, vec3 ta, float cr) {
+    vec3 cw = normalize(ta - ro);                     // Forward direction
+    vec3 cp = vec3(sin(cr), cos(cr), 0.0);            // Up reference (cr controls roll)
+    vec3 cu = normalize(cross(cw, cp));                // Right direction
+    vec3 cv = cross(cu, cw);                           // Up direction
+    return mat3(cu, cv, cw);
+}
+
+// Usage:
+mat3 ca = setCamera(ro, ta, 0.0);
+vec3 rd = ca * normalize(vec3(uv, FOCAL_LENGTH)); // FOCAL_LENGTH adjustable: 1.0~3.0, larger = narrower FOV
+```
+
+### Step 3: Defining the Scene SDF
+
+**What**: Write a function that returns the signed distance from any point in space to the nearest surface.
+
+**Why**: The SDF is the core of Ray Marching — it simultaneously defines geometry and step distance.
+
+```glsl
+// --- Basic SDF Primitives ---
+float sdSphere(vec3 p, float r) {
+    return length(p) - r;
+}
+
+float sdBox(vec3 p, vec3 b) {
+    vec3 d = abs(p) - b;
+    return min(max(d.x, max(d.y, d.z)), 0.0) + length(max(d, 0.0));
+}
+
+float sdTorus(vec3 p, vec2 t) {
+    return length(vec2(length(p.xz) - t.x, p.y)) - t.y;
+}
+
+// --- CSG Boolean Operations ---
+float opUnion(float a, float b)        { return min(a, b); }
+float opSubtraction(float a, float b)  { return max(a, -b); }
+float opIntersection(float a, float b) { return max(a, b); }
+
+// --- Smooth Boolean Operations (organic blending) ---
+float smin(float a, float b, float k) {
+    float h = max(k - abs(a - b), 0.0);
+    return min(a, b) - h * h * 0.25 / k;  // k adjustable: blend radius, 0.1~0.5
+}
+
+// --- Spatial Transforms ---
+// Translation: apply inverse translation to the sample point
+// Rotation: multiply the sample point by a rotation matrix
+// Scaling: p /= s, result *= s
+
+// --- Scene Composition Example ---
+float map(vec3 p) {
+    float d = sdSphere(p - vec3(0.0, 0.5, 0.0), 0.5);   // Sphere
+    d = opUnion(d, p.y);                                    // Add ground plane
+    d = smin(d, sdBox(p - vec3(1.0, 0.3, 0.0), vec3(0.3)), 0.2); // Smooth blend with box
+    return d;
+}
+```
+
+### Step 4: Core Ray Marching Loop
+
+**What**: Iteratively step along the ray direction, using the SDF value at each step to determine the advance distance, and check whether the ray has hit a surface or exceeded the maximum range.
+
+**Why**: Sphere Tracing guarantees that each step advances the maximum safe distance (without penetrating surfaces), taking large steps in open areas and automatically slowing down near surfaces.
+
+```glsl
+#define MAX_STEPS 128   // Adjustable: max step count, 64~256, more = more precise but slower
+#define MAX_DIST 100.0  // Adjustable: max travel distance
+#define SURF_DIST 0.001 // Adjustable: surface hit threshold, 0.0001~0.01
+
+float rayMarch(vec3 ro, vec3 rd) {
+    float t = 0.0;
+    for (int i = 0; i < MAX_STEPS; i++) {
+        vec3 p = ro + t * rd;
+        float d = map(p);
+        if (d < SURF_DIST) return t;   // Surface hit
+        t += d;
+        if (t > MAX_DIST) break;        // Out of range
+    }
+    return -1.0; // No hit
+}
+```
+
+### Step 5: Normal Estimation
+
+**What**: Compute the surface normal at the hit point using the numerical gradient of the SDF.
+
+**Why**: Normals are the foundation of lighting calculations. The gradient direction of the SDF is the surface normal direction.
+
+```glsl
+// Method A: Central differences (6 SDF calls, straightforward)
+vec3 calcNormal(vec3 p) {
+    vec2 e = vec2(0.001, 0.0);  // e.x adjustable: differentiation step size
+    return normalize(vec3(
+        map(p + e.xyy) - map(p - e.xyy),
+        map(p + e.yxy) - map(p - e.yxy),
+        map(p + e.yyx) - map(p - e.yyx)
+    ));
+}
+
+// Method B: Tetrahedron trick (4 SDF calls, prevents compiler inline bloat, recommended)
+vec3 calcNormal(vec3 pos) {
+    vec3 n = vec3(0.0);
+    for (int i = 0; i < 4; i++) {
+        vec3 e = 0.5773 * (2.0 * vec3((((i+3)>>1)&1), ((i>>1)&1), (i&1)) - 1.0);
+        n += e * map(pos + 0.001 * e);
+    }
+    return normalize(n);
+}
+```
+
+### Step 6: Lighting and Shading
+
+**What**: Compute Phong lighting (ambient + diffuse + specular) at the hit point.
+
+**Why**: Give SDF surfaces realistic shading with highlights and shadow gradients.
+
+```glsl
+vec3 shade(vec3 p, vec3 rd) {
+    vec3 nor = calcNormal(p);
+    vec3 lightDir = normalize(vec3(0.6, 0.35, 0.5));   // Light direction (adjustable)
+    vec3 viewDir = -rd;
+    vec3 halfDir = normalize(lightDir + viewDir);
+
+    // Diffuse
+    float diff = clamp(dot(nor, lightDir), 0.0, 1.0);
+    // Specular
+    float spec = pow(clamp(dot(nor, halfDir), 0.0, 1.0), SHININESS); // SHININESS adjustable: 8~64
+    // Ambient + sky light
+    float sky = sqrt(clamp(0.5 + 0.5 * nor.y, 0.0, 1.0));
+
+    vec3 col = vec3(0.2, 0.2, 0.25);             // Material base color (adjustable)
+    vec3 lin = vec3(0.0);
+    lin += diff * vec3(1.3, 1.0, 0.7) * 2.2;     // Main light
+    lin += sky  * vec3(0.4, 0.6, 1.15) * 0.6;    // Sky light
+    lin += vec3(0.25) * 0.55;                      // Fill light
+    col *= lin;
+    col += spec * vec3(1.3, 1.0, 0.7) * 5.0;     // Specular highlight
+
+    return col;
+}
+```
+
+### Step 7: Post-Processing (Gamma Correction and Tone Mapping)
+
+**What**: Convert linear lighting results to sRGB space and apply tone mapping to prevent overexposure.
+
+**Why**: GPU computations are done in linear space, but displays require gamma-corrected values. Tone mapping compresses HDR values into the [0,1] range.
+
+```glsl
+// Gamma correction
+col = pow(col, vec3(0.4545));  // i.e., 1/2.2
+
+// Optional: Reinhard tone mapping (before gamma)
+col = col / (1.0 + col);
+
+// Optional: Vignette
+vec2 q = fragCoord / iResolution.xy;
+col *= 0.5 + 0.5 * pow(16.0 * q.x * q.y * (1.0 - q.x) * (1.0 - q.y), 0.25);
+```
+
+## Common Variants in Detail
+
+### 1. Volumetric Ray Marching
+
+**Difference from the basic version**: Instead of finding a surface intersection, the ray advances in **fixed steps**, accumulating density/color at each step. Used for flames, smoke, and clouds.
+
+**Key modified code**:
+```glsl
+#define VOL_STEPS 150       // Adjustable: volume sample count
+#define VOL_STEP_SIZE 0.05  // Adjustable: step size
+
+// Density field (built with FBM noise)
+float fbmDensity(vec3 p) {
+    float den = 0.2 - p.y;                                    // Base height falloff
+    vec3 q = p - vec3(0.0, 1.0, 0.0) * iTime;
+    float f  = 0.5000 * noise(q); q = q * 2.02 - vec3(0.0, 1.0, 0.0) * iTime;
+          f += 0.2500 * noise(q); q = q * 2.03 - vec3(0.0, 1.0, 0.0) * iTime;
+          f += 0.1250 * noise(q); q = q * 2.01 - vec3(0.0, 1.0, 0.0) * iTime;
+          f += 0.0625 * noise(q);
+    return den + 4.0 * f;
+}
+
+// Volumetric marching main function
+vec3 volumetricMarch(vec3 ro, vec3 rd) {
+    vec4 sum = vec4(0.0);
+    float t = 0.05;
+    for (int i = 0; i < VOL_STEPS; i++) {
+        vec3 pos = ro + t * rd;
+        float den = fbmDensity(pos);
+        if (den > 0.0) {
+            den = min(den, 1.0);
+            vec3 col = mix(vec3(1.0, 0.5, 0.05), vec3(0.48, 0.53, 0.5),
+                           clamp(pos.y * 0.5, 0.0, 1.0));  // Fire-to-smoke color gradient
+            col *= den;
+            col.a = den * 0.6;
+            col.rgb *= col.a;
+            sum += col * (1.0 - sum.a);                     // Front-to-back compositing
+            if (sum.a > 0.99) break;                         // Early exit
+        }
+        t += VOL_STEP_SIZE;
+    }
+    return clamp(sum.rgb, 0.0, 1.0);
+}
+```
+
+### 2. CSG Scene Construction (Constructive Solid Geometry)
+
+**Difference from the basic version**: Combines multiple SDF primitives using `min` (union), `max` (intersection), and `max(a,-b)` (subtraction), along with rotation/translation transforms to create complex mechanical parts.
+
+**Key modified code**:
+```glsl
+float sceneSDF(vec3 p) {
+    p = rotateY(iTime * 0.5) * p;                                // Rotate entire scene
+
+    float sphere = sdSphere(p, 1.2);
+    float cube = sdBox(p, vec3(0.9));
+    float cyl = sdCylinder(p, vec2(0.4, 2.0));                   // Vertical cylinder
+    float cylX = sdCylinder(p.yzx, vec2(0.4, 2.0));              // X-axis cylinder (swizzled)
+    float cylZ = sdCylinder(p.xzy, vec2(0.4, 2.0));              // Z-axis cylinder
+
+    // Sphere ∩ Cube - three-axis cylinders = nut shape
+    return opSubtraction(
+        opIntersection(sphere, cube),
+        opUnion(cyl, opUnion(cylX, cylZ))
+    );
+}
+```
+
+### 3. Physically-Based Volumetric Scattering
+
+**Difference from the basic version**: Uses physically correct extinction coefficients, scattering coefficients, and transmittance formulas, with volumetric shadows (marching toward the light source to compute transmittance). Based on Frostbite engine's energy-conserving integration formula.
+
+**Key modified code**:
+```glsl
+void getParticipatingMedia(out float sigmaS, out float sigmaE, vec3 pos) {
+    float heightFog = 0.3 * clamp((7.0 - pos.y), 0.0, 1.0);  // Height fog
+    sigmaS = 0.02 + heightFog;                                  // Scattering coefficient
+    sigmaE = max(0.000001, sigmaS);                              // Extinction coefficient (includes absorption)
+}
+
+// Energy-conserving scattering integral (Frostbite improved version)
+vec3 S = lightColor * sigmaS * phaseFunction() * volShadow;     // Incoming light
+vec3 Sint = (S - S * exp(-sigmaE * stepLen)) / sigmaE;          // Integrate current step
+scatteredLight += transmittance * Sint;                          // Accumulate
+transmittance *= exp(-sigmaE * stepLen);                         // Update transmittance
+```
+
+### 4. Glow Accumulation
+
+**Difference from the basic version**: During the Ray March loop, additionally tracks the closest distance from the ray to the surface `dM`. Even without a hit, this produces a glow effect. Commonly used for glowing spheres and plasma.
+
+**Key modified code**:
+```glsl
+vec2 rayMarchWithGlow(vec3 ro, vec3 rd) {
+    float t = 0.0;
+    float dMin = MAX_DIST;                    // Track minimum distance
+    for (int i = 0; i < MAX_STEPS; i++) {
+        vec3 p = ro + t * rd;
+        float d = map(p);
+        if (d < dMin) dMin = d;               // Update closest distance
+        if (d < SURF_DIST) break;
+        t += d;
+        if (t > MAX_DIST) break;
+    }
+    return vec2(t, dMin);
+}
+
+// Add glow based on dMin during shading
+float glow = 0.02 / max(dMin, 0.001);        // Closer = brighter
+col += glow * vec3(1.0, 0.8, 0.9);
+```
+
+### 5. Refraction and Bidirectional Marching (Interior Marching)
+
+**Difference from the basic version**: After hitting a surface, computes the refraction direction and marches **inside the object in reverse** (negating the SDF) to find the exit point. Can achieve glass, water, and liquid metal effects.
+
+**Key modified code**:
+```glsl
+// Bidirectional marching: determine SDF sign based on whether the origin is inside or outside
+float castRay(vec3 ro, vec3 rd) {
+    float sign = (map(ro) < 0.0) ? -1.0 : 1.0;   // Negate distance if inside
+    float t = 0.0;
+    for (int i = 0; i < 120; i++) {
+        float h = sign * map(ro + rd * t);
+        if (abs(h) < 0.0001 || t > 12.0) break;
+        t += h;
+    }
+    return t;
+}
+
+// Refraction: after hitting the outer surface, march inside along the refracted direction
+vec3 refDir = refract(rd, nor, IOR);                // IOR adjustable: index of refraction, e.g., 0.9
+float t2 = 2.0;
+for (int i = 0; i < 50; i++) {
+    float h = map(hitPos + refDir * t2);
+    t2 -= h;                                         // Reverse marching (from inside outward)
+    if (abs(h) > 3.0) break;
+}
+vec3 nor2 = calcNormal(hitPos + refDir * t2);        // Exit point normal
+```
+
+## Performance Optimization in Detail
+
+### 1. Reducing SDF Call Count
+
+- Use the tetrahedron trick for normal computation (4 calls instead of 6 with central differences)
+- Use `min(iFrame,0)` as the loop start value to prevent the compiler from unrolling and inlining map() multiple times
+
+### 2. Bounding Box Acceleration
+
+Perform AABB ray intersection before marching to skip empty regions:
+```glsl
+vec2 tb = iBox(ro - center, rd, halfSize);
+if (tb.x < tb.y && tb.y > 0.0) { /* Only march inside the box */ }
+```
+
+### 3. Adaptive Precision
+
+- Scale the hit threshold with distance: `SURF_DIST * (1.0 + t * 0.1)` — distant surfaces don't need high precision
+- Clamp step size: `t += clamp(h, 0.01, 0.2)` — prevent individual steps from being too large or too small
+
+### 4. Early Exit
+
+- In volume rendering: `if (sum.a > 0.99) break;` — stop immediately when opaque
+- In shadow computation: `if (res < 0.004) break;` — stop when fully occluded
+
+### 5. Reducing map() Complexity
+
+- Use simplified SDFs for distant objects
+- First test with a cheap bounding SDF; only compute the expensive precise SDF when `sdBox(p, bound) < currentMin`
+
+### 6. Anti-Aliasing
+
+- Supersampling (AA=2 means 2x2 sampling, 4 rays per pixel), but at 4x performance cost
+- In volume rendering, use dithering instead of supersampling to reduce banding artifacts
+
+## Combination Suggestions in Detail
+
+### 1. Ray Marching + FBM Noise
+
+Use fractal noise to perturb SDF surfaces for terrain and rock textures, or build volumetric density fields to render clouds/smoke.
+
+### 2. Ray Marching + Domain Warping
+
+Apply spatial distortions (twist, bend, repeat) to sample points to create infinitely repeating corridors or twisted surreal geometry.
+
+### 3. Ray Marching + PBR Materials
+
+SDF provides geometry; combine with Cook-Torrance BRDF, environment map reflections, and Fresnel terms for realistic metal/dielectric materials.
+
+### 4. Ray Marching + Post-Processing
+
+Multi-pass architecture: the first Buffer performs Ray Marching and outputs color + depth (stored in the alpha channel); the second pass applies depth of field (DOF), motion blur, and tone mapping.
+
+### 5. Ray Marching + Procedural Animation
+
+Drive SDF primitive positions/sizes/blend coefficients with time parameters, combined with easing functions (smoothstep, parabolic) to create character animations without a skeletal system.