@driftengine/core 3.63.0 → 4.1.0

package/src/render/screenSpaceReflection.ts

@@ -114,10 +114,24 @@ export interface ScreenSpaceHit {
   v: number;
   /** How far along the ray it was found, world metres. */
   distanceM: number;
+  /**
+   * The closest this ray's whole path came to the edge of the frame, 0 to 0.5. Zero if it left.
+   *
+   * **Fading the *hit* is not enough, and that is what this is for.** `screenEdgeFade` softens a
+   * hit near the border so a reflection leaves rather than being cut off along a line — but a ray
+   * that runs off the edge *before* it hits anything returns no hit at all, and that is still a
+   * line. The two cases are adjacent: one pixel's ray grazes the border and lands, the next
+   * pixel's leaves and answers nothing.
+   *
+   * So the fade has to be driven by how close the *path* came, which only the march can see. A
+   * ray that stayed in the middle of the frame reports 0.5; one that skimmed the border reports
+   * almost nothing and fades out before its neighbour disappears.
+   */
+  margin: number;
 }
 
 export function newScreenSpaceHit(): ScreenSpaceHit {
-  return { hit: false, u: 0, v: 0, distanceM: 0 };
+  return { hit: false, u: 0, v: 0, distanceM: 0, margin: 0 };
 }
 
 /**
@@ -185,6 +199,9 @@ export function traceScreenSpaceRay(
   out.u = 0;
   out.v = 0;
   out.distanceM = 0;
+  out.margin = 0;
+  /* The closest the path has come to the border so far. See `ScreenSpaceHit.margin`. */
+  let margin = 0.5;
 
   const steps = Math.max(1, Math.round(march.steps));
   const ox = origin[0] ?? 0;
@@ -216,6 +233,7 @@ export function traceScreenSpaceRay(
     const y = oy + dy * t;
     const z = oz + dz * t;
     if (!project(x, y, z, UV)) return false;
+    margin = Math.min(margin, edgeMargin(UV[0] ?? 0, UV[1] ?? 0));
 
     const scene = sceneDistance(UV[0] ?? 0, UV[1] ?? 0);
     /* Nothing was drawn here, so there is no surface to cross. Carried rather than treated as a
@@ -267,6 +285,7 @@ export function traceScreenSpaceRay(
       out.u = hitU;
       out.v = hitV;
       out.distanceM = far;
+      out.margin = margin;
       return true;
     }
 
@@ -290,8 +309,23 @@ export function traceScreenSpaceRay(
  */
 export function screenEdgeFade(u: number, v: number, band: number): number {
   if (band <= 0) return u < 0 || u > 1 || v < 0 || v > 1 ? 0 : 1;
-  const nearest = Math.min(u, 1 - u, v, 1 - v);
-  return Math.min(1, Math.max(0, nearest / band));
+  return edgeFade(edgeMargin(u, v), band);
+}
+
+/** How far a screen position is from the nearest border, 0 at it and 0.5 in the middle. */
+export function edgeMargin(u: number, v: number): number {
+  return Math.min(u, 1 - u, v, 1 - v);
+}
+
+/**
+ * A margin turned into a fade, so `screenEdgeFade` and `ScreenSpaceHit.margin` cannot disagree.
+ *
+ * One expression rather than two copies of it — the rule `REFLECTION_EDGE_FADE` states about the
+ * band applied one level down, to the arithmetic the band goes into.
+ */
+export function edgeFade(margin: number, band: number): number {
+  if (band <= 0) return margin < 0 ? 0 : 1;
+  return Math.min(1, Math.max(0, margin / band));
 }
 
 /**

package/src/render/sdfFont.ts

@@ -80,9 +80,11 @@ const SUPPORTED_VERSION = 1;
  * beside a reference and they do not match. Every other required field is checked the same way.
  */
 export function parseSdfFont(document: unknown): SdfFont {
+  // platform: feature probe — a bake and a worker both reach here without one
   if (typeof document !== 'object' || document === null) {
     throw new Error('parseSdfFont: expected a metrics object');
   }
+  // platform: feature probe — guarded by the line above
   const source = document as Record<string, unknown>;
   if (source['version'] !== SUPPORTED_VERSION) {
     throw new Error(

package/src/render/segmentQuads.ts

@@ -1,4 +1,5 @@
 import type { BoltSegments } from './boltPool.ts';
+import type { LineSegments } from './linePoints.ts';
 
 /**
  * How a list of segments becomes triangles, held once for every renderer that draws one.
@@ -90,3 +91,41 @@ export function expandBoltSegments(
   }
   return count;
 }
+
+/**
+ * Expand this frame's segments to their four vertices each, into arrays the caller owns.
+ *
+ * Returns how many segments were written, which is the list's count clamped to the batch's
+ * capacity — a caller that overruns loses its tail rather than its frame, the same rule
+ * `expandBoltSegments` follows. Reads only `LineSegments.from`/`.to`.
+ *
+ * **Both backends call it**, which is the reason it is here: the WebGL2 batch wrote the same walk
+ * inline until 2026-09-19, so the number of segments a batch draws — and so whether it draws at
+ * all, and is counted — was one decision written twice.
+ */
+export function expandLineSegments(
+  data: LineSegments,
+  capacity: number,
+  from: Float32Array,
+  to: Float32Array,
+): number {
+  const count = Math.min(data.count, capacity);
+  for (let s = 0; s < count; s++) {
+    const fx = data.from[s * 3] as number;
+    const fy = data.from[s * 3 + 1] as number;
+    const fz = data.from[s * 3 + 2] as number;
+    const tx = data.to[s * 3] as number;
+    const ty = data.to[s * 3 + 1] as number;
+    const tz = data.to[s * 3 + 2] as number;
+    for (let c = 0; c < 4; c++) {
+      const v = s * 4 + c;
+      from[v * 3] = fx;
+      from[v * 3 + 1] = fy;
+      from[v * 3 + 2] = fz;
+      to[v * 3] = tx;
+      to[v * 3 + 1] = ty;
+      to[v * 3 + 2] = tz;
+    }
+  }
+  return count;
+}

package/src/render/shaders/flat/lobes.ts

@@ -1,6 +1,35 @@
 /** How light falls off with distance, and the specular lobes a highlight is made of. */
 import { POINT_SHADOW_FADE_START } from '../../renderQuality.ts';
 
+/**
+ * How much of a self-lit surface's glow a shadow may take. See the GLSL constant's own comment.
+ *
+ * Exported because the GPU-driven pipeline dims its emission by the same share, and a number two
+ * shaders read is a number that belongs in one place.
+ */
+export const EMISSIVE_SHADOW_SHARE = 0.55;
+
+/**
+ * The narrowest lobe this engine draws, as the distribution's own width.
+ *
+ * **Derived rather than chosen.** These lobes are divided by their own peak, `a2*a2 / (d*d)`, and
+ * the division is guarded at `1e-8` so a mirror cannot divide by nothing. At the peak `d` *is*
+ * `a2`, so the guard starts binding exactly where `a2*a2` reaches `1e-8` — at `a = 0.01` — and
+ * below that it scales the answer instead of protecting it: the peak fell to **0.0039 at roughness
+ * 0.05, 256 times dimmer than at 0.1**, so a polished surface had a fainter highlight than a satin
+ * one. Flooring `a` here keeps the peak at one for every roughness and leaves the guard as the
+ * guard it was meant to be.
+ *
+ * **What it gives up**: a surface smoother than this is drawn at this width rather than narrower.
+ * That is the same trade `sphereLobe` argues below — a reflection narrower than a fragment cannot
+ * be sampled and comes back as speckle — so the floor is where the engine stops pretending to
+ * resolve something it cannot. **What would make it wrong** is a path that integrates the lobe
+ * rather than sampling it at a point, where the narrow tail is carried by the integral;
+ * `prefilter.ts`'s `ggxDistribution` is that path, keeps the honest normalisation, and is
+ * deliberately not this.
+ */
+export const MIN_LOBE_ALPHA = 0.01;
+
 export const LOBES_GLSL = `float shadowReach(float distance, float maxDistance) {
   return 1.0 - smoothstep(
     maxDistance * ${POINT_SHADOW_FADE_START.toFixed(2)},
@@ -53,7 +82,10 @@ const float MAX_FILTER_RADIUS = 0.25;
  * something passed in front of it, which is worse. Just over half reads as an inlay lit
  * from within a deck that is itself in shade.
  */
-const float EMISSIVE_SHADOW_SHARE = 0.55;
+const float EMISSIVE_SHADOW_SHARE = ${EMISSIVE_SHADOW_SHARE};
+
+/* The narrowest lobe this engine draws. See MIN_LOBE_ALPHA in this module for why it is this. */
+const float MIN_LOBE_ALPHA = ${MIN_LOBE_ALPHA};
 
 /*
  * Trowbridge-Reitz, because the width of a highlight is the whole effect.
@@ -77,7 +109,7 @@ const float EMISSIVE_SHADOW_SHARE = 0.55;
  * is a multiply cheaper than the honest spelling as well.
  */
 float specularLobe(float ndh, float roughness) {
-  float a = max(roughness * roughness, 1e-3);
+  float a = max(roughness * roughness, MIN_LOBE_ALPHA);
   float a2 = a * a;
   float d = ndh * ndh * (a2 - 1.0) + 1.0;
   return (a2 * a2) / max(d * d, 1e-8);
@@ -103,7 +135,7 @@ float specularLobe(float ndh, float roughness) {
  * scene ever does, so r/d is large and its highlight is genuinely broad.
  */
 float sphereLobe(float ndh, float roughness, float sourceRadius, float dist) {
-  float a = max(roughness * roughness, 1e-3);
+  float a = max(roughness * roughness, MIN_LOBE_ALPHA);
   float widened = clamp(a + sourceRadius / max(2.0 * dist, 1e-3), a, 1.0);
   float energy = (a / widened) * (a / widened);
   float w2 = widened * widened;

package/src/render/shaders/flat/preamble.ts

@@ -10,6 +10,14 @@ import {
   MAX_LIGHTS_PER_CLUSTER,
   TABLE_WIDTH,
 } from '../../clusteredLights.ts';
+
+/**
+ * How much roughness a relieved or normal-mapped surface gains per unit of relief.
+ *
+ * Exported because the GPU-driven pipeline widens its roughness by a normal map's strength the way
+ * this shader does, and one number read by two shaders is a number that cannot drift between them.
+ */
+export const RELIEF_ROUGHNESS = 0.35;
 import { MAX_SHADOW_FILTER_TAPS } from '../../renderQuality.ts';
 import type { LightBudget } from '../../uniformVectorBudget.ts';
 import { FOG_GLSL } from '../fog.ts';
@@ -48,7 +56,7 @@ in float vRoughness;
  * because the amplitude is known here rather than measured off the screen.
  */
 #define RELIEF_TILT 1.6
-#define RELIEF_ROUGHNESS 0.35
+#define RELIEF_ROUGHNESS ${RELIEF_ROUGHNESS}
 /**
  * The furthest a texture-derived bump may turn the shading normal, as a tangent.
  *
@@ -482,6 +490,22 @@ uniform float uEnvironmentMaxLod;
  * under-sampled and forced to a roughness it does not have.
  */
 uniform float uEnvironmentEdge;
+/**
+ * Whether the probe blend consults what each probe can see, and where those moments are.
+ *
+ * **Zero is off, and off is what every published scene is gated at.** On, each probe's visibility
+ * map is a *layer of this same array*, offset past the radiance layers by the grid's probe count:
+ * two moments a texel, the mean distance to geometry along a direction and the mean of its square.
+ *
+ * **In this array rather than a sampler of its own, and branched at run time rather than compiled
+ * in or out.** A sampler of its own would be a seventeenth on a backend that guarantees sixteen
+ * units — the reason \`environmentProbe\` is a permutation at all — and a permutation flag of its
+ * own would double the generated shader corpus for every consumer, which \`scripts/wgsl.ts\` prices
+ * at 400,728 to 597,638 gzipped bytes. Sharing the array costs neither: no new unit, no new
+ * permutation, and the arithmetic sits behind a branch on this uniform the way the clustered light
+ * table's does.
+ */
+uniform float uProbeVisibilityEnabled;
 /**
  * The level holding the cosine convolution, which is the scene's diffuse ambient.
  *

package/src/render/shaders/flat/probeGrid.ts

@@ -1,5 +1,16 @@
 /** Reading the probe array: which layers a point sits between, and what each of them holds. */
 
+import {
+  PROBE_VISIBILITY_CRUSH,
+  PROBE_VISIBILITY_SHARPNESS,
+  PROBE_VISIBILITY_VARIANCE_FLOOR,
+} from '../../gi/probeVolume.ts';
+
+/** A number as GLSL always reads it as a float, so an integer constant is not an `int`. */
+function glslFloat(value: number): string {
+  return Number.isInteger(value) ? value.toFixed(1) : String(value);
+}
+
 /**
  * The lit pass's half of the grid, and the two things it has to get right.
  *
@@ -83,6 +94,41 @@ vec3 probeRadiance(vec3 dir, float lod, float layer) {
   return mix(fine, coarse, clamp(lod - lo, 0.0, 1.0));
 }
 
+/** Layers of radiance in the array, which is where the visibility moments start. */
+float probeLayerCount() {
+  return uProbeGridCounts.x * uProbeGridCounts.y * uProbeGridCounts.z;
+}
+
+/**
+ * How much of a probe a point can actually see, from one to zero.
+ *
+ * **The same arithmetic as "probeVisibilityWeight", and the constants are interpolated from it**
+ * rather than written again: one in front of what the probe saw along that direction, and behind it
+ * a Chebyshev bound on the variance of the distances the probe recorded — confident where the
+ * geometry is flat, uncertain where it is not, which is exactly where a hard answer would be wrong.
+ *
+ * The variance floor is not a tolerance. A probe facing a flat wall records the same distance in
+ * every direction of its cone, so the variance is exactly zero and the bound becomes a step: one in
+ * front of the wall and zero behind it, with a hard line between them that crawls every time the
+ * probes are rebaked.
+ *
+ * The moments live in the radiance array, offset past its layers by the grid's probe count, at
+ * level zero. See "uProbeVisibilityEnabled".
+ */
+float probeVisible(vec3 fromProbe, float distanceM, float layer) {
+  vec2 moments = textureLod(
+    uEnvironment,
+    vec3(octInsetUv(fromProbe, uEnvironmentEdge), layer + probeLayerCount()),
+    0.0
+  ).rg;
+  if (distanceM <= moments.x) return 1.0;
+  float variance =
+    max(abs(moments.x * moments.x - moments.y), ${glslFloat(PROBE_VISIBILITY_VARIANCE_FLOOR)});
+  float beyond = distanceM - moments.x;
+  float chebyshev = variance / (variance + beyond * beyond);
+  return pow(chebyshev, ${glslFloat(PROBE_VISIBILITY_SHARPNESS)});
+}
+
 /**
  * The grid's diffuse light at a point, trilinear over the eight probes around it.
  *
@@ -101,14 +147,43 @@ vec3 gridIrradiance(vec3 dir, vec3 worldPos) {
   vec3 frac;
   probeCell(worldPos, base, frac);
   vec3 sum = vec3(0.0);
+  /*
+   * **The weights are renormalised rather than used as they fall.** Multiplying by visibility takes
+   * energy out of the blend, and a blend that quietly drops a share of its probes darkens every
+   * bounce — the property "visibleProbes" states and the white furnace rests on.
+   *
+   * And a point every probe is blind to still gets an answer: inside a solid, or in a sealed void
+   * with a probe on each side of a wall, every weight crushes to nothing and the nearest probe
+   * takes the lot. This is the last level of the chain and there is nothing behind it.
+   */
+  float total = 0.0;
+  float nearestDistance = 1.0e30;
+  vec3 nearestColour = vec3(0.0);
   for (int c = 0; c < 8; c++) {
     vec3 corner = vec3(float(c & 1), float((c >> 1) & 1), float((c >> 2) & 1));
     vec3 axisWeight = mix(1.0 - frac, frac, corner);
     float weight = axisWeight.x * axisWeight.y * axisWeight.z;
     if (weight <= 0.0) continue;
-    sum += probeIrradiance(dir, probeLayer(base + corner)) * weight;
+    float layer = probeLayer(base + corner);
+    vec3 colour = probeIrradiance(dir, layer);
+    float kept = weight;
+    if (uProbeVisibilityEnabled > 0.5) {
+      vec3 fromProbe = worldPos - (uProbeGridOrigin + (base + corner) / uProbeGridInvSpacing);
+      float distanceM = length(fromProbe);
+      /* A point standing exactly on a probe is seen by it, and has no direction to ask about. */
+      float seen = distanceM > 0.0 ? probeVisible(fromProbe / distanceM, distanceM, layer) : 1.0;
+      kept = weight * seen;
+      kept = kept < ${glslFloat(PROBE_VISIBILITY_CRUSH)} ? 0.0 : kept;
+      if (distanceM < nearestDistance) {
+        nearestDistance = distanceM;
+        nearestColour = colour;
+      }
+    }
+    sum += colour * kept;
+    total += kept;
   }
-  return sum;
+  if (uProbeVisibilityEnabled <= 0.5) return sum;
+  return total > 0.0 ? sum / total : nearestColour;
 }
 
 /**