reze-engine 0.39.0 → 0.41.0

package/dist/shaders/passes/composite.js

@@ -2,10 +2,16 @@
 // Bloom tint/intensity applied at combine (EEVEE treats them as combine-stage params, not prefilter).
 //
 // The shader is a TEMPLATE: buildCompositeShader() emits either the base pass or
-// a variant with a user background effect injected (setBackgroundEffect). The
-// effect is background mode 3, a sibling of the 360 equirect (mode 2) — it reuses
-// the same per-pixel view-ray reconstruction and composites in display space
-// under the scene, so it never affects lighting, bloom, or tonemapping.
+// a variant with user WGSL injected at one or both effect MOUNTS (setEffect).
+// The two mounts are the same idea on either side of the scene:
+//
+//   background(...)  under the scene — a sibling of the 360 equirect (mode 2),
+//                    reusing the same per-pixel view-ray reconstruction.
+//   foreground(...)  over the finished frame, handed the scene's depth in metres
+//                    so it can be occluded by whatever it passes behind.
+//
+// Both composite in display space, so neither affects lighting, bloom, or
+// tonemapping, and both are captured by offline export like any background.
 const COMPOSITE_HEAD = /* wgsl */ `
 // Pipeline-override constant: the engine creates two composite pipelines, one
 // with APPLY_GAMMA=false (gamma=1 fast path) and one with APPLY_GAMMA=true.
@@ -17,7 +23,7 @@ override APPLY_GAMMA: bool = true;
 @group(0) @binding(0) var hdrTex: texture_2d<f32>;
 @group(0) @binding(1) var bloomTex: texture_2d<f32>;   // bloomUpTexture mip 0 (full pyramid top)
 @group(0) @binding(2) var bloomSamp: sampler;
-@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 10>;
+@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 11>;
 // Aux mask/alpha texture. .r = bloom mask (unused here; bloom blit uses it).
 // .g = accumulated canvas alpha (what hdr.a carried before the HDR format
 // became rg11b10ufloat). We unpremultiply HDR by this alpha for tonemap, then
@@ -36,18 +42,63 @@ override APPLY_GAMMA: bool = true;
 // viewU[2] = (background.rgb, mode) — display-space sRGB, composited UNDER the
 //            scene post-tonemap. BASE-layer mode: 0 transparent (DOM shows),
 //            1 solid color, 2 = 360 equirect skybox sampled by view ray. A user
-//            WGSL effect is a separate LAYER over the base (viewU[6].y flag).
+//            WGSL effect is a separate LAYER over the base — no mode of its own,
+//            and no on/off uniform either: the pipeline is REBUILT per effect, so
+//            the compiled variant IS the flag.
 // viewU[3] = (camera right, tanHalfFov·aspect); viewU[4] = (camera up, tanHalfFov);
 // viewU[5] = (camera forward, _) — refreshed per frame while skybox/effect active.
-// viewU[6] = (time seconds, effect on/off, canvas width, canvas height).
+// viewU[6] = (time seconds, _, canvas width, canvas height).
 // viewU[7] = (grade offset.rgb, contrast);  viewU[8] = (grade power.rgb, saturation);
 // viewU[9] = (grade slope.rgb, grade on/off) — see grade() below.
+// viewU[10] = (camera world position, _) — refreshed with the basis above.
 // invGamma = 1/gamma precomputed on CPU — avoids a per-pixel divide.
 @group(0) @binding(6) var bgEquirect: texture_2d<f32>;
+// The scene pass's own MSAA depth buffer, bound depth-only. NOT an extra
+// render target: with neither depth of field nor a foreground effect active the
+// scene pass discards depth (TBDR tile memory never spills) and this binding is
+// never read. Either feature makes the pass store it instead, and both read
+// sample 0 — the DoF gather, and linearDepth() for the depth handed to
+// foreground().
+@group(0) @binding(8) var depthTex: texture_depth_multisampled_2d;
+// dofU[0] = (enabled, focusDistance, focusRange, aperture)
+// dofU[1] = (maxBlurRadiusPx, bladeCount, sampleCount, anamorphicRatio)
+// dofU[2] = (projA, projB, _, _) — z-buffer → camera-space depth inversion,
+//           viewZ = projB / (z - projA), rebuilt per frame because near/far
+//           track the camera radius. Cleared depth (1.0) inverts to the far
+//           plane, so empty sky reads as maximally defocused background.
+@group(0) @binding(9) var<uniform> dofU: array<vec4<f32>, 3>;
 
 // Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).
 const FILMIC_LUT_W: f32 = 256.0;
 
+fn linearDepth(coord: vec2<i32>) -> f32 {
+  let z = textureLoad(depthTex, coord, 0);
+  // projA > 1 for every valid z in [0,1], so the divisor never crosses zero.
+  return clamp(dofU[2].y / (z - dofU[2].x), 0.05, 100000.0);
+}
+
+/** Signed circle of confusion in device pixels — negative in front of the
+ *  focus band, positive behind it, zero inside it. */
+fn circleOfConfusion(depth: f32) -> f32 {
+  let focus = max(dofU[0].y, 0.05);
+  let halfRange = max(dofU[0].z * 0.5, 0.01);
+  let delta = depth - focus;
+  let outside = max(abs(delta) - halfRange, 0.0);
+  let radius = min(outside / max(depth, 0.05) * dofU[0].w * dofU[1].x, dofU[1].x);
+  return select(-radius, radius, delta >= 0.0);
+}
+
+/** Premultiplied scene color (HDR + bloom) at an arbitrary pixel, for the
+ *  bokeh gather. Explicit-LOD sampling only — legal in non-uniform flow. */
+fn sceneSample(coord: vec2<i32>, fullSzI: vec2<i32>, fullSz: vec2f) -> vec4f {
+  let p = clamp(coord, vec2<i32>(0), fullSzI - vec2<i32>(1));
+  let sAlpha = textureLoad(maskTex, p, 0).g;
+  let sHdr = textureLoad(hdrTex, p, 0).rgb / max(sAlpha, 1e-6);
+  let sUv = (vec2f(p) + vec2f(0.5)) / fullSz;
+  let sBloom = textureSampleLevel(bloomTex, bloomSamp, sUv, 0.0).rgb * viewU[1].xyz * viewU[1].w;
+  return vec4f((sHdr + sBloom) * sAlpha, sAlpha);
+}
+
 fn filmic(x: f32) -> f32 {
   // Reference checkpoints (Blender 3.6 Filmic MHC, sobotka/filmic-blender
   // look_medium-high-contrast.spi1d): linear 0.18 → ~0.395, linear 1.0 → ~0.83.
@@ -59,9 +110,26 @@ fn filmic(x: f32) -> f32 {
   return textureSampleLevel(filmicLut, bloomSamp, vec2f(u, 0.5), 0.0).r;
 }
 
-/** Canvas size in pixels — for user background effects (aspect correction). */
+/** Canvas size in pixels — for user effects (aspect correction). */
 fn bgResolution() -> vec2f { return viewU[6].zw; }
 
+/** The camera's world position. */
+fn bgCameraPos() -> vec3f { return viewU[10].xyz; }
+
+/** Where in the WORLD the scene drew this pixel — the depth handed to
+ *  foreground() turned into a place. Without it an effect can only think in
+ *  distances from the lens, which is no use to anything that belongs somewhere:
+ *  fog lying on the ground has to know where the ground is.
+ *
+ *  depth measures along the VIEW AXIS, not along the ray, so it is divided by
+ *  the ray's projection onto camera-forward before being walked out. At the far
+ *  plane (nothing drawn) this lands a very long way off, which is what a sky
+ *  should do to anything reading it. */
+fn bgWorldPos(ray: vec3f, depth: f32) -> vec3f {
+  let axis = max(dot(normalize(ray), viewU[5].xyz), 1e-4);
+  return bgCameraPos() + normalize(ray) * (depth / axis);
+}
+
 /** Color grading, applied to the tonemapped SCENE (not the background — see the
  *  call site). The core is ASC CDL, the film-industry interchange standard:
  *
@@ -101,7 +169,59 @@ const COMPOSITE_BODY = /* wgsl */ `
   let intensity = viewU[1].w;
   let bloom = textureSampleLevel(bloomTex, bloomSamp, bloomUv, 0.0).rgb * tint * intensity;
   let combined = straight + bloom;
-  let exposed = combined * exp2(viewU[0].x);
+
+  // ── Depth of field ──
+  // Single-pass golden-angle gather over a polygonal (bladed) disk, in
+  // premultiplied HDR before tonemap. Near-field taps that see focused
+  // background are heavily down-weighted so a sharp subject doesn't bleed into
+  // a blurred foreground; the reverse leak (background bokeh over the subject
+  // edge) is damped less — that soft halo is what real lenses do. Scene layer
+  // only: the composited background (solid / 360 / effect) stays sharp, which
+  // is invisible while it sits at infinity behind a far-blurred stage.
+  var scenePm = vec4f(combined * alpha, alpha);
+  if (dofU[0].x > 0.5) {
+    let centerDepth = linearDepth(coord);
+    let centerCoc = circleOfConfusion(centerDepth);
+    let radius = abs(centerCoc);
+    if (radius > 0.35) {
+      let fullSzI = vec2<i32>(fullSz);
+      let sampleCount = clamp(dofU[1].z, 6.0, 24.0);
+      let blades = clamp(dofU[1].y, 3.0, 12.0);
+      let sector = 6.28318530718 / blades;
+      var accum = scenePm;
+      var weightSum = 1.0;
+      for (var i = 0u; i < 24u; i++) {
+        if (f32(i) >= sampleCount) { break; }
+        let fi = f32(i) + 0.5;
+        let ring = sqrt(fi / sampleCount);
+        let angle = fi * 2.39996323;
+        let localAngle = (fract((angle + 3.14159265359) / sector) - 0.5) * sector;
+        let polygonRadius = cos(3.14159265359 / blades) / max(cos(localAngle), 0.01);
+        var disk = vec2f(cos(angle), sin(angle)) * ring * polygonRadius;
+        disk.x *= max(dofU[1].w, 0.25);
+        let sp = coord + vec2<i32>(round(disk * radius));
+        let cp = clamp(sp, vec2<i32>(0), fullSzI - vec2<i32>(1));
+        let sampleDepth = linearDepth(cp);
+        let sampleCoc = circleOfConfusion(sampleDepth);
+        var w = 1.0;
+        if (centerCoc < 0.0 && sampleDepth > centerDepth + dofU[0].z) {
+          w *= 0.08;
+        } else if (centerCoc > 0.0 && sampleDepth > centerDepth + dofU[0].z * 2.0) {
+          w *= 0.35;
+        }
+        // A tap only contributes where its own blur circle reaches this pixel.
+        let sampleRadius = abs(sampleCoc);
+        w *= mix(0.2, 1.0, smoothstep(ring * radius - 1.0, ring * radius + 1.0, sampleRadius));
+        accum += sceneSample(cp, fullSzI, fullSz) * w;
+        weightSum += w;
+      }
+      scenePm = mix(scenePm, accum / max(weightSum, 1e-5), smoothstep(0.35, 1.75, radius));
+    }
+  }
+  let sceneAlpha = scenePm.a;
+  let sceneStraight = scenePm.rgb / max(sceneAlpha, 1e-6);
+
+  let exposed = sceneStraight * exp2(viewU[0].x);
   let tm = vec3f(filmic(exposed.r), filmic(exposed.g), filmic(exposed.b));
   var disp = max(tm, vec3f(0.0));
   // Grade the SCENE only, before the display gamma. Deliberately not applied to
@@ -120,64 +240,92 @@ const COMPOSITE_BODY = /* wgsl */ `
   let bg = viewU[2];
   var bgA = select(0.0, 1.0, bg.w > 0.5);
   var bgPm = bg.rgb * bgA;  // premultiplied accumulator
-  let fxOn = viewU[6].y > 0.5;
-  if ((bg.w > 1.5 || fxOn) COVERAGE_GATE) {
-    // The equirect and any effect both need this pixel's world-space view ray,
-    // rebuilt from the camera basis. The dome sits at infinity (no parallax) —
-    // PhotoDome-style, display-only.
-    let ndc = vec2f(fragCoord.x / fullSz.x * 2.0 - 1.0, 1.0 - fragCoord.y / fullSz.y * 2.0);
-    let dir = normalize(viewU[5].xyz + ndc.x * viewU[3].w * viewU[3].xyz + ndc.y * viewU[4].w * viewU[4].xyz);
+  // This pixel's world-space view ray, rebuilt from the camera basis — what the
+  // equirect samples by, and what both effect mounts navigate by. The dome sits
+  // at infinity (no parallax): PhotoDome-style, display-only. Hoisted out of the
+  // branch below because the foreground mount is past the end of it; it is pure
+  // arithmetic on uniforms, which every backend sinks into whatever reads it.
+  let ndc = vec2f(fragCoord.x / fullSz.x * 2.0 - 1.0, 1.0 - fragCoord.y / fullSz.y * 2.0);
+  let dir = normalize(viewU[5].xyz + ndc.x * viewU[3].w * viewU[3].xyz + ndc.y * viewU[4].w * viewU[4].xyz);
+  if (BACKGROUND_COND) {
     if (bg.w > 1.5) {
       // LH world (+Z forward): longitude = atan2(x, z), Babylon-PhotoDome convention.
       let su = 0.5 + atan2(dir.x, dir.z) * 0.15915494309;  // 1/(2π)
       let sv = 0.5 - asin(clamp(dir.y, -1.0, 1.0)) * 0.31830988618;  // 1/π
       bgPm = textureSampleLevel(bgEquirect, bloomSamp, vec2f(su, sv), 0.0).rgb;
     }
-    BG_EFFECT_CALL
+    BACKGROUND_CALL
   }
-  return vec4f(disp * alpha + bgPm * (1.0 - alpha), alpha + bgA * (1.0 - alpha));
+  // The frame, premultiplied: scene over background. A var, not the return
+  // expression, because the foreground mount composites onto it.
+  var outRgb = disp * sceneAlpha + bgPm * (1.0 - sceneAlpha);
+  var outA = sceneAlpha + bgA * (1.0 - sceneAlpha);
+  FOREGROUND_CALL
+  return vec4f(outRgb, outA);
 }
 `;
-// Base variant: no effect installed, the flag is never set — the ray block only
-// runs for the equirect, and there is nothing to add. (`dir` may go unused when
-// this compiles with mode<2 shaders; WGSL is fine with an unused let.)
-const NO_EFFECT_CALL = `_ = dir;`;
 // uv flipped to bottom-left origin (shadertoy convention); clamped so a stray
 // effect can't push negatives/NaN into the premultiplied composite. Standard
-// OVER onto the base layer.
-const EFFECT_CALL = /* wgsl */ `
-    if (fxOn) {
-      let bgUv = vec2f(fragCoord.x / fullSz.x, 1.0 - fragCoord.y / fullSz.y);
-      let fx = clamp(background(dir, bgUv, viewU[6].x), vec4f(0.0), vec4f(1.0));
-      bgPm = fx.rgb * fx.a + bgPm * (1.0 - fx.a);
-      bgA = fx.a + bgA * (1.0 - fx.a);
-    }
+// OVER onto the base layer. No `if` around it: the pipeline is rebuilt per
+// effect, so this text only exists in variants whose WGSL defines background().
+const BACKGROUND_CALL = /* wgsl */ `
+    let bgUv = vec2f(fragCoord.x / fullSz.x, 1.0 - fragCoord.y / fullSz.y);
+    let bgFx = clamp(background(dir, bgUv, viewU[6].x), vec4f(0.0), vec4f(1.0));
+    bgPm = bgFx.rgb * bgFx.a + bgPm * (1.0 - bgFx.a);
+    bgA = bgFx.a + bgA * (1.0 - bgFx.a);
+`;
+// Same OVER, one layer later — onto the finished frame rather than onto the
+// base. Ungated by design: a foreground runs at every pixel, including the ones
+// the model covers, because covering them is the point.
+const FOREGROUND_CALL = /* wgsl */ `
+  let fgUv = vec2f(fragCoord.x / fullSz.x, 1.0 - fragCoord.y / fullSz.y);
+  // The scene's own depth, so the effect can tell what is in front of it: a
+  // petal compares its distance against this and lets the model take the pixel,
+  // and fog's alpha is nothing but a function of it. Pixels the scene never drew
+  // read the far plane, so distance fog closes over the backdrop too.
+  let fgFx = clamp(foreground(dir, fgUv, viewU[6].x, linearDepth(coord)), vec4f(0.0), vec4f(1.0));
+  outRgb = fgFx.rgb * fgFx.a + outRgb * (1.0 - fgFx.a);
+  outA = fgFx.a + outA * (1.0 - fgFx.a);
 `;
 // Derivative builtins are illegal in non-uniform control flow (WGSL uniformity
 // analysis rejects the pipeline), so the coverage gate below can only wrap
 // effect code that doesn't use them. Checked textually at build time.
 const USES_DERIVATIVES = /\b(?:fwidth|dpdx|dpdy)(?:Fine|Coarse)?\s*\(/;
-/** Skip the whole background block (equirect sample + effect) behind pixels the
- *  model fully covers — the composite multiplies the result by (1 - alpha) = 0
- *  there anyway, and on a full-screen effect that's a third or more of the frame
- *  (the cost Safari feels most). The equirect uses explicit-LOD sampling, which
- *  is always legal in non-uniform flow; only derivative-using effects must keep
- *  uniform control flow and forgo the gate. */
-function coverageGate(effect) {
-    const gated = !effect || !USES_DERIVATIVES.test(effect.wgsl);
-    return gated ? "&& alpha < 0.999" : "";
+/** The condition on the background block (equirect sample + background effect).
+ *
+ *  Two jobs. It skips the block behind pixels the model fully covers — the
+ *  composite multiplies the result by (1 - alpha) = 0 there anyway, and on a
+ *  full-screen effect that's a third or more of the frame (the cost Safari feels
+ *  most). And with no background effect compiled in, it also skips the block
+ *  entirely unless the equirect needs it.
+ *
+ *  The equirect uses explicit-LOD sampling, which is always legal in non-uniform
+ *  flow; only derivative-using effects must keep uniform control flow and forgo
+ *  the coverage half. The test is textual over the whole file, so a foreground
+ *  that uses fwidth costs the background its gate — conservative, and only ever
+ *  in the direction of correctness. (The foreground mount itself sits in uniform
+ *  flow, so derivatives are always legal there.) */
+function backgroundCondition(effect) {
+    // sceneAlpha, not alpha: the bokeh gather spreads coverage, so a pixel the
+    // sharp scene fully covered can end up needing background behind its blur.
+    const coverage = "sceneAlpha < 0.999";
+    if (!effect?.hasBackground)
+        return `bg.w > 1.5 && ${coverage}`;
+    return USES_DERIVATIVES.test(effect.wgsl) ? "true" : coverage;
 }
 export function buildCompositeShader(effect) {
+    const body = COMPOSITE_BODY.replace("BACKGROUND_COND", backgroundCondition(effect))
+        .replace("BACKGROUND_CALL", effect?.hasBackground ? BACKGROUND_CALL.trim() : "")
+        .replace("FOREGROUND_CALL", effect?.hasForeground ? FOREGROUND_CALL.trim() : "");
     if (!effect)
-        return (COMPOSITE_HEAD +
-            COMPOSITE_BODY.replace("BG_EFFECT_CALL", NO_EFFECT_CALL).replace("COVERAGE_GATE", coverageGate(null)));
+        return COMPOSITE_HEAD + body;
     return (COMPOSITE_HEAD +
-        "\n// ── user background effect (setBackgroundEffect) ──\n" +
+        "\n// ── user effect (setEffect) ──\n" +
         effect.paramsDecl +
         "\n" +
         effect.wgsl +
         "\n" +
-        COMPOSITE_BODY.replace("BG_EFFECT_CALL", EFFECT_CALL.trim()).replace("COVERAGE_GATE", coverageGate(effect)));
+        body);
 }
 /** Kept for compatibility with existing imports (the base, no-effect shader). */
 export const COMPOSITE_SHADER_WGSL = buildCompositeShader(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",