@driftengine/core 4.4.1 → 4.5.0

package/src/render/temporalAa.ts

@@ -154,6 +154,225 @@ export function clipToNeighbourhood(
   return out;
 }
 
+/**
+ * **The anti-flicker: a still pixel's neighbourhood widened by its own flicker.**
+ *
+ * A thread, a crack of light round a door, a leaf finer than a pixel: the jitter catches it in some
+ * phases and misses it in others, and in a phase that misses it the nine taps round a pixel can all
+ * miss it at once. The box collapses onto the background, the history — which had settled on the
+ * thread's share of the pixel — is clipped out, and it grows back a tenth a frame until the next
+ * miss. That is a paused frame flashing at every fine edge, and the clip is doing its job: nothing
+ * in one frame says the thread is still there.
+ *
+ * What does say so is the pixel's own record. **A still camera over a still scene samples every pixel
+ * the same way every period of the jitter, exactly**, so aliasing repeats itself; a surface that moves
+ * across the pixel, a flame, a light that shimmers, does not. So each pixel keeps the mean of its
+ * samples over the last period, the sum it is gathering for this one, how many periods running have
+ * repeated, and the running mean of how far its samples land from their period's mean — and its box
+ * widens by that spread only once two periods running have repeated. Measured on the samples rather
+ * than against the history, because the history is what the clip cuts. **And a sample farther from
+ * its period's mean than the box would widen to is not the flicker the pixel has shown**: something
+ * has arrived, and the count starts again on that frame rather than at the end of the period. **Two, and a mean rather than
+ * one sample**, because one sample repeats by coincidence: stripes sliding across a pixel land on the
+ * same colour at two period starts about as often as not.
+ *
+ * **What it gives up.** A surface arriving over a pixel that was flickering is held back until the
+ * period ends and fails to repeat — at most eight frames, fading a tenth a frame meanwhile; a still
+ * pixel needs three periods before it is helped at all; and a pixel that flickers in a scene that is
+ * itself moving is not helped, since nothing repeats there. Nothing moving past a twentieth of a
+ * pixel a frame is touched, since the reprojection is then what decides.
+ *
+ * **A moving camera had a weaker proof of its own, and it was taken out.** It widened a pixel's box
+ * while its samples swung both ways about their mean, with the record carried through the
+ * reprojection. Measured on a moving courtyard it removed a twentieth of what flickered, and it broke
+ * a sun's shadow line on the floor into dashes that were not there before: the record is read at the
+ * nearest texel, so under sub-pixel motion one pixel widened and its neighbour did not. The resolve
+ * already removes nineteen twentieths of a moving frame's flicker without it. **What would make it wrong** is a jitter
+ * whose sequence does not repeat, where no period is the same twice however still the scene is.
+ */
+
+/** This frame's share of the running spread, and of a period's mean: one period of the jitter. */
+export const FLICKER_MEMORY = 1 / JITTER_PERIOD;
+
+/**
+ * How many spreads a flickering pixel's box widens by. The hardest thread is one missed in a single
+ * phase of eight: that miss needs the box to reach 7/8 of its contrast, and the running spread,
+ * worn down by seven catches that each land an eighth of the contrast from the period's mean, has
+ * fallen to a = 1/8 + (7/8 a + 7/64 − 1/8)·(7/8)⁷ of the contrast by then — 0.181, a steady state
+ * solved by hand — against the 7/32 it averages. Seven eighths over that is 4.8; six leaves room.
+ * Threads caught in a share nearer a half spread more and need fewer.
+ */
+export const FLICKER_WIDTH = 6;
+
+/**
+ * How far apart two periods' means may be, relative to the larger, and still repeat: fully below
+ * this, not at all at twice it. Above an eight-bit record's rounding and a lamp's slow breathing; far
+ * below what anything crossing the pixel does to it.
+ */
+export const FLICKER_REPEAT = 0.05;
+
+/**
+ * How much of the history a pixel proven to repeat keeps, where an unproven one keeps
+ * `TEMPORAL_HISTORY_BLEND`. A settled thread still breathes with the jitter by the share of each
+ * frame's sample that goes into what is shown — a tenth of its contrast at the base blend — and a
+ * pixel that has repeated for two periods has nothing to respond to, so it keeps more: three
+ * hundredths of each frame instead of a tenth. What it costs is a surface arriving inside the
+ * pixel's own swing, which fades in at that rate until the period's check lets it through.
+ */
+export const FLICKER_BLEND = 0.97;
+
+/**
+ * How far last frame's depth may be from the depth a surface should have had there, relative, and
+ * still be that surface: two percent beyond the pixel's own depth swing, taken as the nearest of the
+ * texel where it stood and the four beside it. **The nearest of five and not the one**, because this
+ * frame's sample and last frame's can straddle an edge with nothing moved — the lesson
+ * `recon/resolve.ts` learned the expensive way.
+ *
+ * **And beyond its own swing, because depth aliases the way colour does.** A crack of light round a
+ * door is a pixel whose sample lands on the door in some phases and on what is behind it in others,
+ * so its depth jumps metres with nothing moved, and a test held to two percent reset the record of
+ * exactly the pixels the anti-flicker is for: a held frame went from 5 flickering pixels back to 774.
+ * So each pixel keeps the running mean of how far last frame's depth missed — kept whatever the test
+ * says, since resetting it would stop it ever learning the swing — and the test allows
+ * `FLICKER_WIDTH` of those, as the box does of the colour's. A flat surface's swing is none and its
+ * test stays tight; a surface revealed by the camera is a jump nothing in the pixel's past explains.
+ */
+export const FLICKER_SURFACE = 0.02;
+
+/** Whether a record follows the surface it was kept for: see `FLICKER_SURFACE`. */
+export function sameSurface(expected: number, stood: ArrayLike<number>, swing: number): boolean {
+  return missedBy(expected, stood) <= FLICKER_WIDTH * swing + FLICKER_SURFACE * expected;
+}
+
+/**
+ * How far the nearest of last frame's depths missed the one expected. A depth of nought is a texel
+ * with nothing recorded — the frame after a cut — and is no texel; with none, nothing is missed by
+ * any amount.
+ */
+export function missedBy(expected: number, stood: ArrayLike<number>): number {
+  let nearest = Number.POSITIVE_INFINITY;
+  for (let i = 0; i < stood.length; i++) {
+    const depth = stood[i] as number;
+    if (depth > 0) nearest = Math.min(nearest, Math.abs(depth - expected));
+  }
+  return nearest;
+}
+
+/**
+ * The pixel's depth swing carried on: the running mean of `missedBy`, over a period, and none where
+ * there was nothing to miss — a swing learned from a cut would loosen the test for a whole period.
+ */
+export function nextDepthSwing(swing: number, missed: number): number {
+  return Number.isFinite(missed) ? swing + (missed - swing) * FLICKER_MEMORY : 0;
+}
+
+/**
+ * Reprojected motion in pixels a frame: still below the first, moving from the second. **Small,
+ * because repetition breaks long before motion is visible**: a camera drifting a fifth of a pixel a
+ * frame shifts the grid more than a pixel a period, so nothing repeats, and a ramp to half a pixel
+ * counted that as mostly still and kept vouching for samples that had stopped repeating.
+ */
+export const STILL_FROM = 0.01;
+export const STILL_TO = 0.05;
+
+/**
+ * A pixel's flicker record, in luma: the running spread of its samples about their period's mean,
+ * the sum this period has gathered so far, the last period's mean, and how many periods running have
+ * repeated — none, one or two, as 0, 0.5 and 1.
+ */
+export interface Flicker {
+  spread: number;
+  sum: number;
+  mean: number;
+  repeated: number;
+}
+
+/**
+ * A fresh record for a surface first seen this frame: no spread and nothing repeated. **A
+ * record of another surface is no record**, so the resolve starts one over wherever last frame's
+ * depth says the surface is not the one it followed, before this frame widens by anything.
+ */
+export function freshFlicker(out: Flicker, sample: number): Flicker {
+  out.spread = 0;
+  out.sum = sample * FLICKER_MEMORY;
+  out.mean = sample;
+  out.repeated = 0;
+  return out;
+}
+
+function smoothstep(edge0: number, edge1: number, x: number): number {
+  const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0)));
+  return t * t * (3 - 2 * t);
+}
+
+/** Rec. 709 luma, which is what the record measures in. */
+export function luma(c: readonly [number, number, number]): number {
+  return c[0] * 0.2126 + c[1] * 0.7152 + c[2] * 0.0722;
+}
+
+/** One for a pixel whose reprojection did not move, falling to none at a twentieth of a pixel. */
+export function stillness(motionPixels: number): number {
+  return 1 - smoothstep(STILL_FROM, STILL_TO, motionPixels);
+}
+
+/**
+ * Whether a pixel is proven to repeat this frame: two periods running have, and this frame's sample
+ * lands within the reach of the box it would widen to. A sample beyond that reach is something
+ * arriving, and it disqualifies the frame it lands in as well as the count it carries out.
+ */
+export function proven(record: Flicker, sample: number): boolean {
+  return record.repeated > 0.75 && within(record, sample);
+}
+
+/** Whether this frame's sample lands inside the reach of the box the record would widen to. */
+function within(record: Flicker, sample: number): boolean {
+  return Math.abs(sample - record.mean) <= FLICKER_WIDTH * record.spread + 1 / 255;
+}
+
+/** How far a pixel's box widens this frame: by its spread, once proven, and only while still. */
+export function flickerWidening(record: Flicker, sample: number, still: number): number {
+  return proven(record, sample) ? FLICKER_WIDTH * record.spread * still : 0;
+}
+
+/** How much of the history this frame keeps: the base blend, or more once proven. */
+export function flickerBlend(base: number, record: Flicker, sample: number, still: number): number {
+  return proven(record, sample) ? base + (FLICKER_BLEND - base) * still : base;
+}
+
+/** Whether two periods' means are the same, one to zero. */
+export function repeats(mean: number, previous: number): number {
+  const apart = Math.abs(mean - previous) / Math.max(mean, previous, 1 / 255);
+  return 1 - smoothstep(FLICKER_REPEAT, 2 * FLICKER_REPEAT, apart);
+}
+
+/**
+ * The record carried out, from the one carried in and this frame's sample in luma. `periodStart`
+ * is the first frame of the jitter's period, where the period just gathered is compared with the
+ * one before. Forgotten in proportion to motion — a moving pixel's record would be a record of
+ * somewhere else.
+ */
+export function nextFlicker(
+  out: Flicker,
+  previous: Flicker,
+  sample: number,
+  still: number,
+  periodStart: boolean,
+): Flicker {
+  const apart = Math.abs(sample - previous.mean);
+  let { sum, mean, repeated } = previous;
+  if (apart > FLICKER_WIDTH * previous.spread + 1 / 255) repeated = 0;
+  if (periodStart) {
+    repeated = repeats(sum, mean) > 0.5 ? Math.min(1, repeated + 0.5) : 0;
+    mean = sum;
+    sum = 0;
+  }
+  out.spread = previous.spread + (apart - previous.spread) * FLICKER_MEMORY;
+  out.sum = sum + sample * FLICKER_MEMORY;
+  out.mean = mean;
+  out.repeated = repeated * still;
+  return out;
+}
+
 /**
  * Whether the last frame left a picture this one may sample, and where the jitter has got to.
  *
@@ -185,6 +404,14 @@ export class TemporalHistory {
     return usable;
   }
 
+  /**
+   * Whether this frame samples the first phase of the jitter's period, where the anti-flicker
+   * compares the period just gathered with the one before. One answer for both backends.
+   */
+  get periodStart(): boolean {
+    return this.frameIndex % JITTER_PERIOD === 0;
+  }
+
   /** A resolved picture is now in the history, at the size the frame was opened with. */
   accumulated(): void {
     this.picture = true;

package/src/render/temporalPass.ts

@@ -15,6 +15,9 @@ import { TEMPORAL_RESOLVE_FRAG } from './shaders/temporalResolve.ts';
  * grade all read the scene texture, and reading the unresolved one would grade a stable picture
  * from an unstable source and put the crawl back on screen through the bloom.
  */
+/** The resolve's three outputs: the picture and the two halves of the flicker record. */
+const DRAW_ALL = [0x8ce0, 0x8ce1, 0x8ce2]; // COLOR_ATTACHMENT0, 1, 2
+
 export class TemporalPass {
   private readonly program: WebGLProgram;
   private readonly uniforms: Record<string, WebGLUniformLocation | null>;
@@ -22,6 +25,21 @@ export class TemporalPass {
 
   /** The pair, and which of them the next resolve writes into. */
   private textures: (WebGLTexture | null)[] = [null, null];
+  /**
+   * Each pixel's flicker record, a pair beside the history's and swapped with it: see the
+   * anti-flicker in `temporalAa.ts`. In the history's own format, which holds what the record does —
+   * a change and a sample are colours' luma, and eight bits hold them wherever eight bits hold the
+   * colour.
+   */
+  private records: (WebGLTexture | null)[] = [null, null];
+  /** The rest of each pixel's record — depth, pull and recent swing — beside the first. */
+  private motions: (WebGLTexture | null)[] = [null, null];
+  /**
+   * Whether the records can be half float, which the depth in them needs. Asked of the context
+   * rather than taken from the scene's format, since a record of an eight-bit scene still holds
+   * metres. Without it the anti-flicker is off and the resolve is the one before it existed.
+   */
+  private readonly recordFloat: boolean;
   private framebuffers: (WebGLFramebuffer | null)[] = [null, null];
   private write = 0;
 
@@ -40,6 +58,7 @@ export class TemporalPass {
      */
     private readonly floatColor: boolean,
   ) {
+    this.recordFloat = gl.getExtension('EXT_color_buffer_float') !== null;
     this.program = compileProgram(gl, FULLSCREEN_VERT, TEMPORAL_RESOLVE_FRAG, 'temporalResolve');
     this.uniforms = uniformLocations(gl, this.program, 'temporalPass');
     const vao = gl.createVertexArray();
@@ -55,19 +74,45 @@ export class TemporalPass {
 
     for (let i = 0; i < 2; i++) {
       if (this.textures[i] === null) this.textures[i] = gl.createTexture();
-      gl.bindTexture(gl.TEXTURE_2D, this.textures[i]);
-      if (this.floatColor) {
-        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, width, height, 0, gl.RGBA, gl.HALF_FLOAT, null);
-      } else {
-        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+      if (this.records[i] === null) this.records[i] = gl.createTexture();
+      if (this.motions[i] === null) this.motions[i] = gl.createTexture();
+      for (const texture of [this.textures[i], this.records[i], this.motions[i]]) {
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        if (texture === this.textures[i] ? this.floatColor : this.recordFloat) {
+          /* The depth record is two numbers a pixel: metres, and how far they swing. */
+          const pair = texture === this.motions[i];
+          gl.texImage2D(
+            gl.TEXTURE_2D,
+            0,
+            pair ? gl.RG16F : gl.RGBA16F,
+            width,
+            height,
+            0,
+            pair ? gl.RG : gl.RGBA,
+            gl.HALF_FLOAT,
+            null,
+          );
+        } else {
+          gl.texImage2D(
+            gl.TEXTURE_2D,
+            0,
+            gl.RGBA,
+            width,
+            height,
+            0,
+            gl.RGBA,
+            gl.UNSIGNED_BYTE,
+            null,
+          );
+        }
+        /* Linear, because the history is sampled between texels wherever the reprojection lands;
+           clamped, because a sample that wrapped would pull the far edge of the screen into the
+           corner — and the shader rejects an off-screen reprojection before it can anyway. */
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
       }
-      /* Linear, because the history is sampled between texels wherever the reprojection lands;
-         clamped, because a sample that wrapped would pull the far edge of the screen into the
-         corner — and the shader rejects an off-screen reprojection before it can anyway. */
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
 
       if (this.framebuffers[i] === null) this.framebuffers[i] = gl.createFramebuffer();
       gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffers[i]);
@@ -78,6 +123,22 @@ export class TemporalPass {
         this.textures[i],
         0,
       );
+      gl.framebufferTexture2D(
+        gl.FRAMEBUFFER,
+        gl.COLOR_ATTACHMENT1,
+        gl.TEXTURE_2D,
+        this.records[i],
+        0,
+      );
+      gl.framebufferTexture2D(
+        gl.FRAMEBUFFER,
+        gl.COLOR_ATTACHMENT2,
+        gl.TEXTURE_2D,
+        this.motions[i],
+        0,
+      );
+      /* Per framebuffer, so set once here: the resolve writes the picture and the record. */
+      gl.drawBuffers(DRAW_ALL);
     }
     gl.bindFramebuffer(gl.FRAMEBUFFER, null);
   }
@@ -96,6 +157,8 @@ export class TemporalPass {
     width: number,
     height: number,
     blend: number,
+    periodStart: boolean,
+    depthToViewZ: Float32Array,
   ): WebGLTexture {
     const { gl } = this;
     this.ensureSize(width, height);
@@ -120,10 +183,19 @@ export class TemporalPass {
     gl.activeTexture(gl.TEXTURE2);
     gl.bindTexture(gl.TEXTURE_2D, depth);
     gl.uniform1i(this.uniforms['uDepth'] ?? null, 2);
+    gl.activeTexture(gl.TEXTURE3);
+    gl.bindTexture(gl.TEXTURE_2D, this.records[history]);
+    gl.uniform1i(this.uniforms['uFlicker'] ?? null, 3);
+    gl.activeTexture(gl.TEXTURE4);
+    gl.bindTexture(gl.TEXTURE_2D, this.motions[history]);
+    gl.uniform1i(this.uniforms['uFlickerMotion'] ?? null, 4);
+    gl.uniform4fv(this.uniforms['uDepthToViewZ'] ?? null, depthToViewZ);
+    gl.uniform1f(this.uniforms['uAntiFlicker'] ?? null, this.recordFloat ? 1 : 0);
 
     gl.uniformMatrix4fv(this.uniforms['uReprojection'] ?? null, false, reprojection);
     gl.uniform2f(this.uniforms['uTexel'] ?? null, 1 / width, 1 / height);
     gl.uniform1f(this.uniforms['uHistoryBlend'] ?? null, blend);
+    gl.uniform1f(this.uniforms['uPeriodStart'] ?? null, periodStart ? 1 : 0);
 
     gl.bindVertexArray(this.vao);
     gl.drawArrays(gl.TRIANGLES, 0, 3);
@@ -141,8 +213,12 @@ export class TemporalPass {
     const { gl } = this;
     for (let i = 0; i < 2; i++) {
       if (this.textures[i] !== null) gl.deleteTexture(this.textures[i]);
+      if (this.records[i] !== null) gl.deleteTexture(this.records[i]);
+      if (this.motions[i] !== null) gl.deleteTexture(this.motions[i]);
       if (this.framebuffers[i] !== null) gl.deleteFramebuffer(this.framebuffers[i]);
       this.textures[i] = null;
+      this.records[i] = null;
+      this.motions[i] = null;
       this.framebuffers[i] = null;
     }
     gl.deleteProgram(this.program);

package/src/render/translucentQueue.ts

@@ -3,6 +3,8 @@ import type { ReadonlyMat4 } from 'gl-matrix';
 /* Type-only, and from the backend that declares it — the same import `backend/api.ts` makes,
    for the same reason: the shape belongs to the draw verb and erases at compile time. */
 import type { TranslucentMeshOptions } from './backend/webgl2/renderer.ts';
+import { resolveGlass } from './glass.ts';
+import type { ResolvedGlass } from './glass.ts';
 
 /**
  * The frame's translucent draws, held so they can be submitted more than once.
@@ -51,10 +53,14 @@ export interface TranslucentDraw {
   /** What survives one metre of the medium. Null where the draw named none; otherwise a copy. */
   refractTint: Float32Array | null;
   thicknessM: number;
+  /** Glass, resolved, or null for a draw that is not glass. See `glass.ts`. */
+  glass: ResolvedGlass | null;
 }
 
 /** A record with its storage, reused across frames. */
 interface PooledDraw extends TranslucentDraw {
+  /** Where `glass` points when set: allocated once with the record, never released. */
+  readonly glassStore: ResolvedGlass;
   /** Allocated once and pointed at by `tint` when a draw has one. */
   readonly tintStore: Float32Array;
   /** The same arrangement for the refraction tint: allocated once, never released. */
@@ -77,6 +83,8 @@ function newRecord(): PooledDraw {
     refractTint: null,
     thicknessM: 0,
     refractTintStore: new Float32Array(3),
+    glass: null,
+    glassStore: { transmission: 0, frost: 0, tint: [1, 1, 1] },
   };
 }
 
@@ -84,6 +92,7 @@ export class TranslucentQueue {
   private readonly pool: PooledDraw[] = [];
   private count = 0;
   private refracting = 0;
+  private glassing = 0;
 
   /** How many draws this frame has recorded. */
   get length(): number {
@@ -98,6 +107,11 @@ export class TranslucentQueue {
     return this.refracting > 0;
   }
 
+  /** Whether anything recorded this frame is glass, so the copy it reads needs its mip chain. */
+  get glassy(): boolean {
+    return this.glassing > 0;
+  }
+
   /** How many records are pooled, which a test uses to assert a steady scene stops allocating. */
   get capacity(): number {
     return this.pool.length;
@@ -137,7 +151,11 @@ export class TranslucentQueue {
       record.tint = record.tintStore;
     }
     record.refraction = options.refraction ?? 0;
-    if (record.refraction > 0) this.refracting++;
+    /* Glass reads the copy too, whether or not it bends: see `glass.ts`. */
+    const glassy = resolveGlass(options.glass, record.glassStore);
+    record.glass = glassy ? record.glassStore : null;
+    if (glassy) this.glassing++;
+    if (record.refraction > 0 || glassy) this.refracting++;
     record.thicknessM = options.thicknessM ?? 0;
     const refractTint = options.refractTint ?? null;
     if (refractTint === null) {
@@ -168,5 +186,6 @@ export class TranslucentQueue {
   reset(): void {
     this.count = 0;
     this.refracting = 0;
+    this.glassing = 0;
   }
 }