@driftengine/core 4.2.1 → 4.4.0

package/src/render/shaders/localExposure.ts

@@ -0,0 +1,154 @@
+/**
+ * Local exposure: each region of the frame brought part of the way toward the frame's own
+ * brightness, so shade and sun can both be read in one picture.
+ *
+ * **A tone curve maps one range, and a sunlit courtyard is two.** Measured in a bought courtyard at
+ * noon, the shaded arcades hold a fiftieth of the light the sunlit paving does, which is what the
+ * place is: a canyon lit mostly by its own walls. Exposed for the paving the arcades go to black,
+ * exposed for the arcades the paving goes to white, and no curve fixes both, because a curve is a
+ * function of a pixel's brightness and the same brightness has to mean shade in one place and sun in
+ * another. A photographer brackets; an eye adapts by region. This is the second.
+ *
+ * **A bilateral grid over the exposure meter's tiles.** The grid pass writes, for each of the
+ * meter's 32 × 32 tiles and each of ten two-stop bands of log luminance, the sum and the share of
+ * the tile's taps that fell in that band, and in an eleventh block the tile's mean. The composite
+ * reads the grid at the pixel's place and in the pixel's own band, filtered in both, so a shaded
+ * pixel beside sunlit ones takes the shade's level rather than the tile's: that is what keeps the
+ * lift from haloing across the edge of a shadow. The band's level is blended 0.4 toward the tile's
+ * mean, which is what stops a texture's own light and dark being flattened into one another.
+ *
+ * **The gain is `strength · (held − local)` stops**, clamped to three: at 0.5 a region five stops
+ * under the frame is lifted two and a half, and one two over is brought down one. The held value is
+ * eye adaptation's, so the frame as a whole still adapts and regions are moved relative to it.
+ *
+ * What it gives up is some of the contrast between regions, which is the point, and a halo a tile
+ * wide where two regions share a band and differ in brightness. What would make it wrong is a scene
+ * whose drama is the contrast itself: a single shaft into a dark room wants the room dark, and the
+ * strength is the caller's for that reason.
+ */
+import { METER_GRID, METER_MAX_LOG2, METER_MIN_LOG2, METER_TAPS } from './exposure.ts';
+
+/** Bands of log luminance, and how many stops each is wide. */
+export const LOCAL_BINS = 10;
+export const LOCAL_BIN_STOPS = (METER_MAX_LOG2 - METER_MIN_LOG2) / LOCAL_BINS;
+/** The grid's width in texels: a block of tiles per band, and one for the tiles' means. */
+export const LOCAL_GRID_WIDTH = METER_GRID * (LOCAL_BINS + 1);
+/** How far a pixel's band level is blended toward its tile's mean. */
+export const LOCAL_BLURRED_BLEND = 0.4;
+/** The furthest a region is moved either way, in stops. */
+export const LOCAL_RANGE_STOPS = 3;
+
+const BLOCKS = (LOCAL_BINS + 1).toFixed(1);
+const GRID = METER_GRID.toFixed(1);
+const MIN = METER_MIN_LOG2.toFixed(1);
+const MAX = METER_MAX_LOG2.toFixed(1);
+const STOPS = LOCAL_BIN_STOPS.toFixed(1);
+const LAST = (LOCAL_BINS - 1).toFixed(1);
+
+/**
+ * The grid: one texel a tile a band. Each reads its tile's 8 × 8 taps, as the meter does, and keeps
+ * the ones in its band; the last block keeps them all. Sum and count are both divided by the taps,
+ * so the filtered pair in the composite is still a weighted mean.
+ */
+export const EXPOSURE_LOCAL_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+/** The finished scene, in scene light, before any exposure or curve. */
+uniform highp sampler2D uScene;
+
+out vec2 fragColor;
+
+void main() {
+  float uvBlock = vUv.x * ${BLOCKS};
+  float band = floor(uvBlock);
+  vec2 corner = vec2(fract(uvBlock), vUv.y) - vec2(0.5 / ${GRID});
+  float sum = 0.0;
+  float count = 0.0;
+  for (int y = 0; y < ${METER_TAPS}; y++) {
+    for (int x = 0; x < ${METER_TAPS}; x++) {
+      vec2 uv = corner + (vec2(float(x), float(y)) + 0.5) / ${(METER_GRID * METER_TAPS).toFixed(1)};
+      vec3 c = textureLod(uScene, uv, 0.0).rgb;
+      float level = clamp(log2(max(dot(c, vec3(0.2126, 0.7152, 0.0722)), 1e-8)), ${MIN}, ${MAX});
+      float tapBand = floor(clamp((level - ${MIN}) / ${STOPS}, 0.0, ${LAST}));
+      float kept = band > ${LAST} || tapBand == band ? 1.0 : 0.0;
+      sum += level * kept;
+      count += kept;
+    }
+  }
+  fragColor = vec2(sum, count) / ${(METER_TAPS * METER_TAPS).toFixed(1)};
+}
+`;
+
+/**
+ * The composite's half. Needs `AUTO_EXPOSURE_GLSL` before it, for the held brightness.
+ *
+ * A block is read clamped half a texel inside its own tiles, so the filter never reaches into the
+ * neighbouring band's block. Every fetch is at level zero: the grid has one level, and the branch
+ * on the strength above them is uniform but the pixel's band is not.
+ */
+export const LOCAL_EXPOSURE_GLSL = `
+/** How far each region is brought toward the frame, 0 to 1. 0 is off and the whole of the off path. */
+uniform float uLocalExposure;
+/** The bilateral grid: a block of tiles per band of brightness, and one of the tiles' means. */
+uniform highp sampler2D uExposureLocal;
+
+vec2 localBlock(vec2 uv, float block) {
+  vec2 inside = clamp(uv, vec2(0.5 / ${GRID}), vec2(1.0 - 0.5 / ${GRID}));
+  return textureLod(uExposureLocal, vec2((block + inside.x) / ${BLOCKS}, inside.y), 0.0).rg;
+}
+
+float localExposureGain(vec2 uv, vec3 light) {
+  if (uLocalExposure <= 0.0) return 1.0;
+  float held = texelFetch(uExposureHeld, ivec2(0, 0), 0).r;
+  float pixel = clamp(log2(max(dot(light, vec3(0.2126, 0.7152, 0.0722)), 1e-8)), ${MIN}, ${MAX});
+  float b = (pixel - ${MIN}) / ${STOPS} - 0.5;
+  float lower = clamp(floor(b), 0.0, ${LAST});
+  float upper = min(lower + 1.0, ${LAST});
+  vec2 banded = mix(localBlock(uv, lower), localBlock(uv, upper), clamp(b - lower, 0.0, 1.0));
+  float tileMean = localBlock(uv, ${LOCAL_BINS.toFixed(1)}).r;
+  float bilateral = banded.y > 1e-3 ? banded.x / banded.y : tileMean;
+  float local = mix(bilateral, tileMean, ${LOCAL_BLURRED_BLEND.toFixed(1)});
+  float stops = uLocalExposure * (held - local);
+  return exp2(clamp(stops, -${LOCAL_RANGE_STOPS.toFixed(1)}, ${LOCAL_RANGE_STOPS.toFixed(1)}));
+}
+`;
+
+const clamp = (value: number, low: number, high: number): number =>
+  Math.min(Math.max(value, low), high);
+
+/** The two bands a pixel at `pixelLog2` reads, and how much of the upper, as the shader finds them. */
+export function localBin(pixelLog2: number): { lower: number; upper: number; weight: number } {
+  const pixel = clamp(pixelLog2, METER_MIN_LOG2, METER_MAX_LOG2);
+  const b = (pixel - METER_MIN_LOG2) / LOCAL_BIN_STOPS - 0.5;
+  const lower = clamp(Math.floor(b), 0, LOCAL_BINS - 1);
+  return { lower, upper: Math.min(lower + 1, LOCAL_BINS - 1), weight: clamp(b - lower, 0, 1) };
+}
+
+/** A pixel's local level from its two bands' sums and counts and its tile's mean, as the shader. */
+export function sliceLocal(
+  sumLower: number,
+  countLower: number,
+  sumUpper: number,
+  countUpper: number,
+  weight: number,
+  tileMean: number,
+): number {
+  const sum = sumLower + (sumUpper - sumLower) * weight;
+  const count = countLower + (countUpper - countLower) * weight;
+  const bilateral = count > 1e-3 ? sum / count : tileMean;
+  return bilateral + (tileMean - bilateral) * LOCAL_BLURRED_BLEND;
+}
+
+/** A region's gain for a local level and the frame's held one at `strength`, as the composite. */
+export function localExposureGain(localLog2: number, heldLog2: number, strength: number): number {
+  if (!(strength > 0)) return 1;
+  const stops = strength * (heldLog2 - localLog2);
+  return 2 ** clamp(stops, -LOCAL_RANGE_STOPS, LOCAL_RANGE_STOPS);
+}
+
+/** A local exposure strength as the shader takes it: 0 to 1, anything else off. */
+export function clampLocalExposure(strength: number): number {
+  return Number.isFinite(strength) ? clamp(strength, 0, 1) : 0;
+}

package/src/render/shaders/prefilter.ts

@@ -39,6 +39,12 @@ import { OCTAHEDRAL_GLSL } from './octahedral.ts';
  */
 export const PREFILTER_FRAG = `#version 300 es
 precision highp float;
+/*
+ * highp int as well, because the radical inverse below is a 32-bit bit reversal and the fragment
+ * default for int and uint is mediump. A driver that computes mediump in sixteen bits returns 0
+ * for every sample, and every cosine sample of the diffuse level lands on its own normal.
+ */
+precision highp int;
 
 ${OCTAHEDRAL_GLSL}
 

package/src/render/shaders/rush.ts

@@ -22,9 +22,17 @@
 /* The vertex stage is `FULLSCREEN_VERT`, shared with the occlusion pass and its blur. */
 import { glslSceneDepthToNdc } from '../depthConvention.ts';
 import { DEPTH_OF_FIELD_GLSL } from './depthOfField.ts';
+import { AUTO_EXPOSURE_GLSL } from './exposure.ts';
+import { LOCAL_EXPOSURE_GLSL } from './localExposure.ts';
+import { FILM_LOOK_GLSL } from './filmLook.ts';
 
 export const RUSH_FRAG = `#version 300 es
 precision highp float;
+/*
+ * highp int as well, for the film grain's hash, which multiplies and shifts uints. The fragment
+ * default is mediump, and a sixteen-bit driver would hand back a hash of sixteen bits.
+ */
+precision highp int;
 
 in vec2 vUv;
 
@@ -135,6 +143,11 @@ uniform float uBloomStrength;
  */
 uniform vec3 uVeilColor;
 uniform float uVeilAlpha;
+${FILM_LOOK_GLSL}
+
+/* Eye adaptation's held brightness and the gain it asks for. See exposure.ts. */
+${AUTO_EXPOSURE_GLSL}
+${LOCAL_EXPOSURE_GLSL}
 
 /**
  * The colour grade: a lookup table over display values, sampled after the tone map.
@@ -293,6 +306,24 @@ vec3 cameraBlur(vec3 scene) {
   return sum / 9.0;
 }
 
+/**
+ * Everything after the light is complete, in the order the header of each step argues: the lens
+ * darkens its corners in scene light, the curve and the grade turn light into a picture, the veil
+ * fades it, and the print's grain sits on what is left. One function, so the two exits of \`main\`
+ * cannot finish a frame differently.
+ */
+vec3 finish(vec3 light) {
+  /*
+   * The eye's adaptation, in scene light and before the lens, as a camera's exposure would be; and
+   * each region's share of it, read from the light before either scales it, because that is the
+   * light the grid measured.
+   */
+  float local = localExposureGain(vUv, light);
+  light *= autoExposureGain() * local;
+  vec3 lensed = withVignette(light, vUv, vec2(textureSize(uScene, 0)));
+  return withGrain(withVeil(applyColourGrade(grade(lensed))), gl_FragCoord.xy);
+}
+
 void main() {
   vec3 scene = textureLod(uScene, vUv, 0.0).rgb;
   if (uMotionStrength > 0.0) scene = cameraBlur(scene);
@@ -330,7 +361,7 @@ void main() {
   float edge = smoothstep(inner, 1.0, radius);
   float amount = edge * uStrength;
   if (amount <= 0.0) {
-    fragColor = vec4(withVeil(applyColourGrade(grade(withBloom(scene * ao)))), 1.0);
+    fragColor = vec4(finish(withBloom(scene * ao)), 1.0);
     return;
   }
 
@@ -349,9 +380,6 @@ void main() {
   }
   vec3 blurred = sum / 7.0;
 
-  fragColor = vec4(
-    withVeil(applyColourGrade(grade(withBloom(mix(scene, blurred, amount) * ao)))),
-    1.0
-  );
+  fragColor = vec4(finish(withBloom(mix(scene, blurred, amount) * ao)), 1.0);
 }
 `;

package/src/render/shaders/tangentFrame.ts

@@ -56,7 +56,9 @@ export const TANGENT_FRAME_GLSL = `mat3 tangentFrame(vec3 n, vec3 worldPos, vec2
    * generateTangents does the same per vertex and says why: dropping it is a normal map that
    * shears wherever the geometry curves.
    */
-  vec3 attrT = normalize(tangent.xyz - n * dot(n, tangent.xyz));
+  vec3 along = tangent.xyz - n * dot(n, tangent.xyz);
+  float alongSq = dot(along, along);
+  vec3 attrT = along * inversesqrt(max(alongSq, 1e-12));
   /*
    * The bitangent's sign, which is the whole reason w is stored. An artist mapping the left and
    * right of a model onto one patch of texture gives one side a mirrored frame, and a bitangent
@@ -64,7 +66,17 @@ export const TANGENT_FRAME_GLSL = `mat3 tangentFrame(vec3 n, vec3 worldPos, vec2
    */
   vec3 attrB = cross(n, attrT) * tangent.w;
 
-  vec3 t = hasTangents != 0 ? attrT : derivedT;
-  vec3 b = hasTangents != 0 ? attrB : derivedB;
+  /*
+   * **And only where there is a frame to keep.** A tangent parallel to its normal, or two that
+   * nearly cancel across one triangle at a mirrored seam, leaves nothing after the subtraction,
+   * and a normalised nothing is NaN. One such pixel in one probe face was a whole courtyard drawn
+   * black: a probe convolves its faces into every direction, and the bounce carries that into
+   * every other probe. So where nothing is left, the derived frame stands in. What it gives up is a
+   * direction on a pixel that had none; what would make it wrong is a threshold large enough to
+   * catch a frame that is merely short, and a unit tangent interpolated is nowhere near 1e-4.
+   */
+  bool framed = hasTangents != 0 && alongSq > 1e-8;
+  vec3 t = framed ? attrT : derivedT;
+  vec3 b = framed ? attrB : derivedB;
   return mat3(t, b, n);
 }`;

package/src/render/shaders/temporalResolve.ts

@@ -111,6 +111,44 @@ vec3 clipToNeighbourhood(vec3 history, vec3 lo, vec3 hi) {
   return centre + offset / ratio;
 }
 
+/*
+ * **The history read through a Catmull-Rom filter, not a bilinear one.**
+ *
+ * The reprojection lands between texels nearly everywhere, and a bilinear fetch there is a small blur;
+ * applied to a picture that is itself last frame's blend, it compounds every frame, so a still camera
+ * settled on a picture measurably softer than one frame of it. A courtyard's stone read as out of
+ * focus beside the same frame with the resolve off. Catmull-Rom passes a straight ramp through exactly
+ * and keeps the edge between two texels an edge, which is what the history is for.
+ *
+ * Five bilinear fetches rather than sixteen point ones: the middle two weights of each axis share a
+ * fetch placed between them, and the four corners, which carry a few hundredths, are left out and
+ * the rest renormalised. Its negative lobes can ring past what the frame holds, which the
+ * neighbourhood clip after it takes back, and the floor at zero keeps a float target out of the
+ * negatives meanwhile.
+ */
+vec3 historyCatmullRom(vec2 uv) {
+  vec2 size = 1.0 / uTexel;
+  vec2 at = uv * size;
+  vec2 base = floor(at - 0.5) + 0.5;
+  vec2 f = at - base;
+  vec2 w0 = f * (-0.5 + f * (1.0 - 0.5 * f));
+  vec2 w1 = 1.0 + f * f * (-2.5 + 1.5 * f);
+  vec2 w2 = f * (0.5 + f * (2.0 - 1.5 * f));
+  vec2 w3 = f * f * (-0.5 + 0.5 * f);
+  vec2 w12 = w1 + w2;
+  vec2 at0 = (base - 1.0) * uTexel;
+  vec2 at3 = (base + 2.0) * uTexel;
+  vec2 at12 = (base + w2 / w12) * uTexel;
+  vec3 sum =
+    textureLod(uHistory, vec2(at12.x, at0.y), 0.0).rgb * (w12.x * w0.y) +
+    textureLod(uHistory, vec2(at0.x, at12.y), 0.0).rgb * (w0.x * w12.y) +
+    textureLod(uHistory, at12, 0.0).rgb * (w12.x * w12.y) +
+    textureLod(uHistory, vec2(at3.x, at12.y), 0.0).rgb * (w3.x * w12.y) +
+    textureLod(uHistory, vec2(at12.x, at3.y), 0.0).rgb * (w12.x * w3.y);
+  float weight = w12.x * w0.y + w0.x * w12.y + w12.x * w12.y + w3.x * w12.y + w12.x * w3.y;
+  return max(sum / weight, vec3(0.0));
+}
+
 void main() {
   vec3 current = textureLod(uScene, vUv, 0.0).rgb;
 
@@ -143,7 +181,7 @@ void main() {
   vec3 lo;
   vec3 hi;
   neighbourhood(lo, hi);
-  vec3 history = textureLod(uHistory, wasUv, 0.0).rgb;
+  vec3 history = historyCatmullRom(wasUv);
   vec3 bounded = clipToNeighbourhood(history, lo, hi);
 
   fragColor = vec4(mix(current, bounded, uHistoryBlend), 1.0);

package/src/render/shadowCasters.ts

@@ -27,9 +27,11 @@ import type { SurfaceTextureHandle } from './backend/api.ts';
  * enumeration serves the directional cascade and every point-light cubemap.
  *
  * **Every draw may also carry its material, which is what lets one enumeration serve a colour
- * pass as well as a depth one.** A depth pass ignores it, correctly: a material cannot change a
- * depth, which is why this interface was right to carry only a handle, a matrix and a palette for
- * as long as depth was the only thing replaying it. What that cost was measured from outside. A
+ * pass as well as a depth one.** A depth pass reads one thing from it, since 4.4.0: whether the
+ * caster is a cutout (`cutoutOf`), so a leaf card casts the leaf rather than the card. Everything
+ * else a material says cannot change a depth, which is why this interface carried only a handle, a
+ * matrix and a palette for as long as depth was the only thing replaying it — and why, until then,
+ * every alpha-cut surface cast its whole quad. What that cost was measured from outside. A
  * consumer wanting the scene from a second viewpoint — a mirror, a probe face — had one option,
  * which was to run its whole draw path again; the first attempt to avoid it replayed this sink
  * into the mirror and got **every car unpainted**, because the list carries no material. So the

package/src/render/shadowMap.ts

@@ -9,6 +9,7 @@
  * "zero textures" rule is about the art direction (no image assets in the
  * payload), and nothing here adds a byte to it.
  */
+import { SHADOW_DEPTH_CLEAR } from './depthConvention.ts';
 import { DEFAULT_RENDER_QUALITY } from './renderQuality.ts';
 
 export class ShadowMap {
@@ -54,6 +55,19 @@ export class ShadowMap {
       throw new Error(`ShadowMap: framebuffer incomplete (0x${status.toString(16)})`);
     }
 
+    /*
+     * **Cleared once, here, to the far plane, because nothing else says what the texture holds.**
+     * WebGL zeroes it, and a zero compared with `LEQUAL` is an occluder at the light itself, so
+     * a layer no pass has drawn put the whole world in shade. ANGLE on Vulkan hands the same
+     * texture back reading 1, which is lit, and that is what every capture here ran on: a scene
+     * with a second depth layer it never peeled lost its sun only under ANGLE's GL backend, the
+     * one Chrome on Linux runs by default. The frame's clear value is borrowed and put back.
+     */
+    const frameClear = gl.getParameter(gl.DEPTH_CLEAR_VALUE) as number;
+    gl.clearDepth(SHADOW_DEPTH_CLEAR);
+    gl.clear(gl.DEPTH_BUFFER_BIT);
+    gl.clearDepth(frameClear);
+
     gl.bindFramebuffer(gl.FRAMEBUFFER, null);
     gl.bindTexture(gl.TEXTURE_2D, null);
   }

package/src/render/surfaceTexture.ts

@@ -60,6 +60,11 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
   vScale?: number;
   /** Alpha below which a fragment is discarded. See `uAlbedoCutout`. */
   cutout?: number;
+  /**
+   * Whether both faces are seen: glTF's `doubleSided`, what a curtain or a leaf card is. Drawn
+   * without culling, and a back face is lit as its front, with the normal turned to the viewer.
+   */
+  doubleSided?: boolean;
   /**
    * How hard the normal map turns the shading normal.
    *