reze-engine 0.40.0 → 0.41.1

package/src/shaders/passes/composite.ts

@@ -2,30 +2,51 @@
 // 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.
 
-/** What a user background effect must define, documented once:
+/** What user effect WGSL may define, documented once. A file declares its own
+ *  mounts by which of these it defines — defining both is how one file is one
+ *  weather system (dark sky behind, rain in front):
  *
  *    fn background(ray: vec3f, uv: vec2f, time: f32) -> vec4f
+ *    fn foreground(ray: vec3f, uv: vec2f, time: f32, depth: f32) -> vec4f
  *
- *  - `ray`  — normalized world-space view direction of this pixel (left-handed,
- *             +Z forward; identical to what the 360 skybox samples by).
- *  - `uv`   — 0..1 across the canvas, origin bottom-left (shadertoy-style).
- *  - `time` — seconds since the effect was applied.
+ *  - `ray`   — normalized world-space view direction of this pixel (left-handed,
+ *              +Z forward; identical to what the 360 skybox samples by).
+ *  - `uv`    — 0..1 across the canvas, origin bottom-left (shadertoy-style).
+ *  - `time`  — seconds since the effect was applied.
+ *  - `depth` — FOREGROUND ONLY. Camera-space distance in metres of whatever the
+ *              scene drew at this pixel, the far plane where it drew nothing.
+ *              Compare a particle's own distance against it and the model
+ *              occludes it; fog needs no comparison at all, its alpha simply IS
+ *              a function of distance.
  *  - `bgResolution()` — canvas size in pixels, for aspect correction.
- *  - declared params arrive as `params.<name>` (f32 or vec3f).
- *  Return display-space sRGB + alpha, 0..1. The effect is a LAYER: it is
- *  over-composited onto the base background (solid color / 360 equirect /
- *  transparent) and sits behind the scene — alpha 0 lets the base show
- *  through, so e.g. a starfield returns stars with a transparent sky. */
+ *  - declared params arrive as `params.<name>` (f32 or vec3f), shared by both.
+ *
+ *  Return display-space sRGB + alpha, 0..1. Both mounts are alpha-composited
+ *  LAYERS, so alpha is what decides how much they replace: a background effect
+ *  at alpha 1 covers the base (solid color / 360 equirect / transparent) and at
+ *  0 lets it through, which is how a starfield is stars over the user's color;
+ *  a foreground at alpha 1 covers the frame. No mode flag anywhere — the alpha
+ *  channel already says it. */
 export type CompositeEffectSource = {
-  /** User WGSL defining `background(...)` (plus any helpers it wants). */
+  /** The user's WGSL verbatim: helpers plus whichever entry points it defines. */
   wgsl: string
-  /** Codegen'd `struct BgParams {...}` + binding decl; empty when no params. */
+  /** Codegen'd `struct EffectParams {...}` + binding decl; empty when no params. */
   paramsDecl: string
+  /** Defines `fn background(...)` — mount under the scene. */
+  hasBackground: boolean
+  /** Defines `fn foreground(...)` — mount over the finished frame. */
+  hasForeground: boolean
 }
 
 const COMPOSITE_HEAD = /* wgsl */ `
@@ -39,7 +60,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
@@ -58,19 +79,23 @@ 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, view transform id, 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: when depth of field is off the scene pass discards depth
-// (TBDR tile memory never spills) and this binding is never read — the whole
-// feature costs one uniform branch. When on, the pass stores depth and the
-// gather below reads sample 0.
+// 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)
@@ -79,6 +104,9 @@ override APPLY_GAMMA: bool = true;
 //           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>;
+// Blender's AgX, as the 57³ lookup it ships as rather than a reconstruction of
+// it. Sampled in the log-encoded E-Gamut space the cube expects — see agxTransform.
+@group(0) @binding(10) var agxLut: texture_3d<f32>;
 
 // Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).
 const FILMIC_LUT_W: f32 = 256.0;
@@ -122,9 +150,78 @@ 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). */
+/** The sRGB display encoding — Blender's "Standard" view transform, which is what
+ *  NPR work uses: no film curve at all, so the colours a graph computes are the
+ *  colours that land. Not a 2.2 power law; sRGB has a linear toe. */
+fn srgb_encode(x: f32) -> f32 {
+  let c = max(x, 0.0);
+  return select(1.055 * pow(c, 1.0 / 2.4) - 0.055, c * 12.92, c <= 0.0031308);
+}
+
+/**
+ * AgX, the chain config.ocio states for "AgX Base Rec.1886" on an sRGB display:
+ *
+ *   scene-linear Rec.709 → 3x3 into FilmLight E-Gamut
+ *   → log2 across 25 stops, [-12.47393, +12.5261] → 0..1
+ *   → the 57³ cube
+ *   → Rec.1886 (pure γ2.4) decoded, then re-encoded as sRGB for the swapchain
+ *
+ * The last step is not pedantry: Rec.1886 is a pure power law and sRGB has a
+ * linear toe, so skipping it lifts the darkest few code values.
+ *
+ * Blender interpolates the cube tetrahedrally and a GPU sampler is trilinear.
+ * The difference is small and confined to saturated gradients; if it ever shows,
+ * tetrahedral is a dozen lines here.
+ */
+fn agxTransform(c: vec3f) -> vec3f {
+  let m = mat3x3<f32>(
+    vec3f(0.55937113, 0.07622071, 0.06552670),
+    vec3f(0.30478326, 0.78797183, 0.16454675),
+    vec3f(0.13584556, 0.13580748, 0.76992653),
+  );
+  let e = m * max(c, vec3f(0.0));
+  // The cube's domain: an unlit pixel would take log2 to -inf, so floor it at
+  // the bottom stop rather than sampling outside the LUT.
+  let t = clamp((log2(max(e, vec3f(1e-10))) + vec3f(12.47393)) / 25.0, vec3f(0.0), vec3f(1.0));
+  // Half-texel inset, so the end stops are the cube's own values and not a blend
+  // with the clamp-to-edge border.
+  let n = 57.0;
+  let uvw = t * ((n - 1.0) / n) + (0.5 / n);
+  let formed = textureSampleLevel(agxLut, bloomSamp, uvw, 0.0).rgb;
+  let linear = pow(max(formed, vec3f(0.0)), vec3f(2.4));
+  return vec3f(srgb_encode(linear.r), srgb_encode(linear.g), srgb_encode(linear.b));
+}
+
+/** Which display transform, chosen per frame at viewU[6].y (0 filmic, 1 standard, 2 agx).
+ *  A uniform branch rather than a pipeline variant: switching is rare, and both
+ *  arms are cheap enough that specialising the pipeline would buy nothing. */
+fn viewTransform(c: vec3f) -> vec3f {
+  let mode = viewU[6].y;
+  if (mode > 1.5) { return agxTransform(c); }
+  if (mode > 0.5) { return vec3f(srgb_encode(c.r), srgb_encode(c.g), srgb_encode(c.b)); }
+  return vec3f(filmic(c.r), filmic(c.g), filmic(c.b));
+}
+
+/** 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:
  *
@@ -218,8 +315,7 @@ const COMPOSITE_BODY = /* wgsl */ `
   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));
+  var disp = max(viewTransform(exposed), vec3f(0.0));
   // Grade the SCENE only, before the display gamma. Deliberately not applied to
   // the background: it keeps a picked background color exactly as picked, and —
   // load-bearing — leaves green-screen mode's key color unshifted so chroma
@@ -236,40 +332,54 @@ 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 * sceneAlpha + bgPm * (1.0 - sceneAlpha), sceneAlpha + bgA * (1.0 - sceneAlpha));
+  // 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
@@ -277,33 +387,41 @@ const EFFECT_CALL = /* wgsl */ `
 // 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?: CompositeEffectSource | null): string {
-  const gated = !effect || !USES_DERIVATIVES.test(effect.wgsl)
+/** 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?: CompositeEffectSource | null): string {
   // sceneAlpha, not alpha: the bokeh gather spreads coverage, so a pixel the
   // sharp scene fully covered can end up needing background behind its blur.
-  return gated ? "&& sceneAlpha < 0.999" : ""
+  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?: CompositeEffectSource | null): string {
-  if (!effect)
-    return (
-      COMPOSITE_HEAD +
-      COMPOSITE_BODY.replace("BG_EFFECT_CALL", NO_EFFECT_CALL).replace("COVERAGE_GATE", coverageGate(null))
-    )
+  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 + 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
   )
 }