@driftengine/core 4.5.0 → 4.6.0

package/src/render/surfaceTexture.ts

@@ -1,4 +1,16 @@
-/** A GPU image the caller supplies, sampled by the flat shader as surface colour. */
+/**
+ * A GPU image the caller supplies, sampled by the flat shader as surface colour — or several, as
+ * the layers of one array.
+ *
+ * **Every surface texture is an array; a plain image is an array of one.** The lit pass has three of
+ * WebGL2's guaranteed sixteen texture units free, so a second set of array samplers beside the 2D
+ * ones was never affordable. Making the one set of samplers arrays costs no unit, and a one-layer
+ * array samples exactly as a 2D texture does. A mesh names its layer per vertex (`MeshData.layers`),
+ * so a merged block wearing forty facades is one draw.
+ */
+import { isSourceList, layerSize, refuseArrayUpdate, sourceSize } from './textureSource.ts';
+import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from './surfaceEffects.ts';
+import type { SurfaceLayerEffect } from './surfaceEffects.ts';
 
 /**
  * How a texture behaves past its edges and between its texels.
@@ -103,6 +115,12 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
 }
 
 export interface SurfaceTextureOptions {
+  /**
+   * What each layer does beyond its picture — rooms behind windows, windows lit by night, wear,
+   * animation, staying dry — one entry a layer, `undefined` for a layer with none. Read only where
+   * this texture is a material's albedo. See `surfaceEffects.ts`.
+   */
+  effects?: readonly (SurfaceLayerEffect | undefined)[];
   /**
    * `repeat` tiles the image, `clamp` stretches its edge texels.
    *
@@ -189,11 +207,23 @@ export class SurfaceTexture {
   /** Whether the sampler decodes sRGB on fetch. See `colorSpace`. */
   private readonly srgb: boolean;
 
+  /** How many images the array holds: 1 for `createSurfaceTexture`, the list's length otherwise. */
+  readonly layers: number;
+  /** The per-layer effects table, or null for a texture given none. See `surfaceEffects.ts`. */
+  private effectsTable: WebGLTexture | null = null;
+
+  /**
+   * One image, or an array of images that must share one size (`layerSize` refuses otherwise).
+   * Uploaded unflipped either way; see the constructor body for why.
+   */
   constructor(
     gl: WebGL2RenderingContext,
-    source: TexImageSource,
+    source: TexImageSource | readonly TexImageSource[],
     options: SurfaceTextureOptions = {},
   ) {
+    const sources: readonly TexImageSource[] = isSourceList(source) ? source : [source];
+    const { width, height } = layerSize(sources);
+    this.layers = sources.length;
     const texture = gl.createTexture();
     if (texture === null) throw new Error('SurfaceTexture: createTexture failed');
     this.texture = texture;
@@ -202,7 +232,7 @@ export class SurfaceTexture {
 
     const wrap = (options.wrap ?? 'repeat') === 'repeat' ? gl.REPEAT : gl.CLAMP_TO_EDGE;
 
-    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
     /*
      * **Not flipped, and this used to be, which is the bug it is written down for.**
      *
@@ -224,24 +254,45 @@ export class SurfaceTexture {
      *
      * A caller that was mirroring its own canvas to cancel this must stop.
      */
-    gl.texImage2D(
-      gl.TEXTURE_2D,
+    /* Allocated mutable rather than with texStorage3D, so `update` can hand a one-layer texture a
+       new size, as texImage2D always could. Each layer is then written in place. */
+    gl.texImage3D(
+      gl.TEXTURE_2D_ARRAY,
       0,
       this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA,
+      width,
+      height,
+      sources.length,
+      0,
       gl.RGBA,
       gl.UNSIGNED_BYTE,
-      source,
+      null,
     );
+    for (let layer = 0; layer < sources.length; layer++) {
+      gl.texSubImage3D(
+        gl.TEXTURE_2D_ARRAY,
+        0,
+        0,
+        0,
+        layer,
+        width,
+        height,
+        1,
+        gl.RGBA,
+        gl.UNSIGNED_BYTE,
+        sources[layer] as TexImageSource,
+      );
+    }
 
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, wrap);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, wrap);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, wrap);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, wrap);
     /* Nearest where the caller said their pixels are the subject; see `filter`. The mip chain is
        still blended between levels, because that is minification and this option is about
        magnification. */
     const nearest = options.filter === 'nearest';
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, nearest ? gl.NEAREST : gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, nearest ? gl.NEAREST : gl.LINEAR);
     gl.texParameteri(
-      gl.TEXTURE_2D,
+      gl.TEXTURE_2D_ARRAY,
       gl.TEXTURE_MIN_FILTER,
       this.mipmapped
         ? nearest
@@ -252,9 +303,41 @@ export class SurfaceTexture {
           : gl.LINEAR,
     );
 
-    if (this.mipmapped) gl.generateMipmap(gl.TEXTURE_2D);
+    if (this.mipmapped) gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
     applyAnisotropy(gl, options.anisotropy ?? DEFAULT_ANISOTROPY);
-    gl.bindTexture(gl.TEXTURE_2D, null);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+
+    /* Half floats, nearest, clamped: a table read by texelFetch, whose every whole number is under
+       what a half holds exactly. */
+    const effects = options.effects ?? [];
+    if (effects.length > 0) {
+      const table = gl.createTexture();
+      if (table === null) throw new Error('SurfaceTexture: createTexture failed');
+      gl.bindTexture(gl.TEXTURE_2D, table);
+      gl.texImage2D(
+        gl.TEXTURE_2D,
+        0,
+        gl.RGBA16F,
+        SURFACE_EFFECT_TEXELS,
+        effects.length,
+        0,
+        gl.RGBA,
+        gl.FLOAT,
+        packSurfaceEffects(effects),
+      );
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+      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);
+      gl.bindTexture(gl.TEXTURE_2D, null);
+      this.effectsTable = table;
+    }
+  }
+
+  /** Bind the effects table to `unit`, or `fallback` for a texture given none. */
+  bindEffects(gl: WebGL2RenderingContext, unit: number, fallback: WebGLTexture): void {
+    gl.activeTexture(gl.TEXTURE0 + unit);
+    gl.bindTexture(gl.TEXTURE_2D, this.effectsTable ?? fallback);
   }
 
   /**
@@ -270,30 +353,38 @@ export class SurfaceTexture {
    */
   update(gl: WebGL2RenderingContext, source: TexImageSource): void {
     if (this.texture === null) return;
-    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    refuseArrayUpdate(this.layers);
+    const { width, height } = sourceSize(source);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
     /* Unflipped, matching the constructor. See it for why, and for what it cost. */
-    gl.texImage2D(
-      gl.TEXTURE_2D,
+    gl.texImage3D(
+      gl.TEXTURE_2D_ARRAY,
       0,
       this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA,
+      width,
+      height,
+      1,
+      0,
       gl.RGBA,
       gl.UNSIGNED_BYTE,
       source,
     );
-    if (this.mipmapped) gl.generateMipmap(gl.TEXTURE_2D);
-    gl.bindTexture(gl.TEXTURE_2D, null);
+    if (this.mipmapped) gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
   }
 
   /** Bind to a unit for sampling. Engine-internal: the renderer owns unit assignment. */
   bind(gl: WebGL2RenderingContext, unit: number): void {
     gl.activeTexture(gl.TEXTURE0 + unit);
-    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
   }
 
   dispose(gl: WebGL2RenderingContext): void {
     if (this.texture === null) return;
     gl.deleteTexture(this.texture);
     this.texture = null;
+    if (this.effectsTable !== null) gl.deleteTexture(this.effectsTable);
+    this.effectsTable = null;
   }
 }
 
@@ -311,5 +402,5 @@ function applyAnisotropy(gl: WebGL2RenderingContext, requested: number): void {
     gl.getExtension('WEBKIT_EXT_texture_filter_anisotropic');
   if (ext === null) return;
   const max = gl.getParameter(ext.MAX_TEXTURE_MAX_ANISOTROPY_EXT) as number;
-  gl.texParameterf(gl.TEXTURE_2D, ext.TEXTURE_MAX_ANISOTROPY_EXT, Math.min(requested, max));
+  gl.texParameterf(gl.TEXTURE_2D_ARRAY, ext.TEXTURE_MAX_ANISOTROPY_EXT, Math.min(requested, max));
 }

package/src/render/temporalAa.ts

@@ -204,6 +204,49 @@ export const FLICKER_MEMORY = 1 / JITTER_PERIOD;
  */
 export const FLICKER_WIDTH = 6;
 
+/**
+ * The two numbers the proof takes from the jitter's period: how much of a period one frame is, and
+ * how many spreads a proven pixel's box widens by. This resolve's are `FLICKER_MEMORY` and
+ * `FLICKER_WIDTH`; a reconstruction jitters along a longer sequence and needs its own.
+ */
+export interface FlickerRule {
+  readonly memory: number;
+  readonly width: number;
+}
+
+/** The temporal resolve's own: eight phases. */
+export const TEMPORAL_FLICKER: FlickerRule = { memory: FLICKER_MEMORY, width: FLICKER_WIDTH };
+
+/**
+ * The running spread of the hardest thread — one caught in a single phase of `phases` — just before
+ * its catch, as a share of its contrast: the steady state `FLICKER_WIDTH`'s comment solves for eight
+ * phases, solved for any. With m one over the period and r = (1 − m)^(p − 1), the seven, or p − 1,
+ * misses that wear it down: a = (m + ((p − 1)m² − m)·r) / (1 − (1 − m)·r).
+ */
+function hardestSpread(phases: number): number {
+  const m = 1 / phases;
+  const r = (1 - m) ** (phases - 1);
+  return (m + ((phases - 1) * m * m - m) * r) / (1 - (1 - m) * r);
+}
+
+/** How many of those spreads the hardest thread's catch lands from its period's mean. */
+function widthNeeded(phases: number): number {
+  return (1 - 1 / phases) / hardestSpread(phases);
+}
+
+/**
+ * The rule for a jitter of `phases` positions. **The width keeps the room `FLICKER_WIDTH` leaves over
+ * what eight phases need** — 4.8 — in proportion: a longer period wears the spread down further
+ * between catches, so over eighteen phases the hardest thread needs eleven spreads, and a box that
+ * reached six reset the count of exactly the pixels this is for.
+ */
+export function flickerRule(phases: number): FlickerRule {
+  return {
+    memory: 1 / phases,
+    width: (FLICKER_WIDTH * widthNeeded(phases)) / widthNeeded(JITTER_PERIOD),
+  };
+}
+
 /**
  * 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
@@ -292,9 +335,13 @@ export interface Flicker {
  * 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 {
+export function freshFlicker(
+  out: Flicker,
+  sample: number,
+  rule: FlickerRule = TEMPORAL_FLICKER,
+): Flicker {
   out.spread = 0;
-  out.sum = sample * FLICKER_MEMORY;
+  out.sum = sample * rule.memory;
   out.mean = sample;
   out.repeated = 0;
   return out;
@@ -320,23 +367,38 @@ export function stillness(motionPixels: number): number {
  * 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);
+export function proven(
+  record: Flicker,
+  sample: number,
+  rule: FlickerRule = TEMPORAL_FLICKER,
+): boolean {
+  return record.repeated > 0.75 && within(record, sample, rule);
 }
 
 /** 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;
+function within(record: Flicker, sample: number, rule: FlickerRule): boolean {
+  return Math.abs(sample - record.mean) <= rule.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;
+export function flickerWidening(
+  record: Flicker,
+  sample: number,
+  still: number,
+  rule: FlickerRule = TEMPORAL_FLICKER,
+): number {
+  return proven(record, sample, rule) ? rule.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;
+export function flickerBlend(
+  base: number,
+  record: Flicker,
+  sample: number,
+  still: number,
+  rule: FlickerRule = TEMPORAL_FLICKER,
+): number {
+  return proven(record, sample, rule) ? base + (FLICKER_BLEND - base) * still : base;
 }
 
 /** Whether two periods' means are the same, one to zero. */
@@ -349,7 +411,8 @@ export function repeats(mean: number, previous: number): number {
  * 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.
+ * somewhere else. `rule` is this resolve's eight phases unless a caller jitters along another
+ * sequence, as a reconstruction does.
  */
 export function nextFlicker(
   out: Flicker,
@@ -357,17 +420,18 @@ export function nextFlicker(
   sample: number,
   still: number,
   periodStart: boolean,
+  rule: FlickerRule = TEMPORAL_FLICKER,
 ): Flicker {
   const apart = Math.abs(sample - previous.mean);
   let { sum, mean, repeated } = previous;
-  if (apart > FLICKER_WIDTH * previous.spread + 1 / 255) repeated = 0;
+  if (apart > rule.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.spread = previous.spread + (apart - previous.spread) * rule.memory;
+  out.sum = sum + sample * rule.memory;
   out.mean = mean;
   out.repeated = repeated * still;
   return out;

package/src/render/textureSource.ts

@@ -0,0 +1,72 @@
+/**
+ * The size of an image a caller hands over, and the one rule a texture array adds to it: every
+ * layer the same size.
+ *
+ * Backend-neutral, because both backends upload the same `TexImageSource` and must agree on its
+ * size, and on refusing an array whose layers disagree, before either touches a device.
+ */
+
+export interface SourceSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+/** Width and height of any `TexImageSource`: a video by its frame, everything else by its own size. */
+export function sourceSize(source: TexImageSource): SourceSize {
+  const candidate = source as {
+    width?: number;
+    height?: number;
+    videoWidth?: number;
+    videoHeight?: number;
+  };
+  const width = candidate.videoWidth ?? candidate.width ?? 0;
+  const height = candidate.videoHeight ?? candidate.height ?? 0;
+  return { width: Math.max(1, width), height: Math.max(1, height) };
+}
+
+/**
+ * The one size every layer of an array shares, or a refusal naming the first that differs.
+ *
+ * **Refused rather than resized**, because an array layer has no size of its own — the device
+ * allocates one size for all of them — and quietly scaling a 128-pixel sign up to a 512 array, or a
+ * facade down, is a decision about quality the caller should make where they can see it. Sorting
+ * images into arrays by size is theirs; this makes sure they did.
+ */
+export function layerSize(sources: readonly TexImageSource[]): SourceSize {
+  const first = sources[0];
+  if (first === undefined) {
+    throw new Error('createSurfaceTextureArray: an array needs at least one image');
+  }
+  const size = sourceSize(first);
+  for (let layer = 1; layer < sources.length; layer++) {
+    const next = sourceSize(sources[layer] as TexImageSource);
+    if (next.width !== size.width || next.height !== size.height) {
+      throw new Error(
+        `createSurfaceTextureArray: layer ${layer} is ${next.width}×${next.height} and layer 0 is ` +
+          `${size.width}×${size.height}. Every layer of an array is one size on the device; group ` +
+          'images into arrays by size, or scale them to one, before building the array.',
+      );
+    }
+  }
+  return size;
+}
+
+/** Whether a constructor argument is a list of images rather than one. */
+export function isSourceList(
+  source: TexImageSource | readonly TexImageSource[],
+): source is readonly TexImageSource[] {
+  return Array.isArray(source);
+}
+
+/**
+ * `update` replaces the one image of a plain texture. An array's layers are its identity — a
+ * block's facades by index — and replacing "the image" of a forty-layer array has no single
+ * meaning, so it is refused rather than guessed at.
+ */
+export function refuseArrayUpdate(layers: number): void {
+  if (layers === 1) return;
+  throw new Error(
+    `updateSurfaceTexture: this texture is an array of ${layers} layers, and update replaces the ` +
+      'one image of a plain texture. Build a new array for new layers.',
+  );
+}

package/src/render/vertexDefaults.ts

@@ -90,6 +90,8 @@ export const ABSENT_ATTRIBUTE: Readonly<Record<string, readonly number[]>> = {
    * the thing being measured.
    */
   channel: [0, 1, 1, 1],
+  /* Layer 0: the only image a plain texture has, and the first of an array. */
+  layers: [0],
 };
 
 /**