@driftengine/core 4.8.7 → 4.9.0

package/src/render/surfaceOverlay.ts

@@ -0,0 +1,195 @@
+/**
+ * What a draw lays over its surface beyond its material: a rim of light, an emissive overlay that
+ * dissolves the surface away, and a second normal map blended in by region. Set per draw with
+ * `RendererApi.setSurfaceOverlay`, so one character's whole set of materials changes together
+ * while another's does not.
+ *
+ * **Per draw and held, like `setEnvironmentGain`**: set before a character's draws, cleared after,
+ * and every draw between them wears it. **Images come from one atlas** (`maps`), each named by the
+ * rectangle it occupies — a scale and an offset in the atlas's uv — because the lit stage binds every
+ * sampler a device is guaranteed and has none left for a texture of its own: the atlas is bound in
+ * the slot the frame's refraction copy takes, which an opaque surface never reads. A draw that both
+ * refracts and wears an overlay's images keeps its refraction and loses the images, said once.
+ *
+ * **Fifteen vectors of numbers**, in the material's uniform block. WebGPU has the room; WebGL2 has
+ * room where its device reports more than the lit stage's 254 vectors, and refuses the overlay in
+ * words where it does not. See `packSurfaceOverlay` for the layout.
+ */
+import type { Vec3 } from '../math/color.ts';
+import type { SurfaceTextureHandle } from './backend/api.ts';
+
+/** Where an image sits in the atlas: its size and its corner, each in the atlas's uv. */
+export interface OverlayRegion {
+  readonly scale: readonly [number, number];
+  readonly offset: readonly [number, number];
+}
+
+/**
+ * Light along the silhouette: the edge `(1 - N·V)^falloff`, leaning toward normals that face up,
+ * raised to a contrast, times a noise laid in screen space, a slow pulse and a mask, in a colour.
+ * Added to what the surface emits, and not gated on the night as emission is: it is a glow the
+ * surface wears, not light it gives off.
+ */
+export interface SurfaceRim {
+  readonly colour: Vec3;
+  /** How bright, 0 for none. Multiplied with `alpha`. */
+  readonly intensity: number;
+  readonly alpha?: number;
+  /** The edge's exponent: larger keeps the rim nearer the silhouette. 1.5 unless given. */
+  readonly falloff?: number;
+  /**
+   * How far the rim leans toward normals that face up: the weight is `(N·up · ½ + ½)^upward`, so
+   * 0 is no lean. 0.4 unless given.
+   */
+  readonly upward?: number;
+  /** The exponent the whole edge is raised to. 1 unless given. */
+  readonly contrast?: number;
+  /** A noise image laid in screen space and scrolled, the rim taken times it, clamped to 1. */
+  readonly noise?: {
+    readonly region: OverlayRegion;
+    /** Screens a second, along x and y. */
+    readonly scroll?: readonly [number, number];
+    /** Repeats across the screen's height. 1 unless given. */
+    readonly tiling?: number;
+  };
+  /** A pulse `½ + ½ sin(rate · t)`, held between `low` and `high`, on `Environment.surfaceTime`. */
+  readonly pulse?: { readonly rate: number; readonly low: number; readonly high: number };
+  /** A mask in the mesh's uv where the rim is erased: the rim times `1 - weight · mask`. */
+  readonly mask?: { readonly region: OverlayRegion; readonly weight: number };
+}
+
+/**
+ * The surface cut away where a noise in its uv falls under `threshold`, with a glowing band just
+ * above it, and a colour laid over the surface through the same noise.
+ */
+export interface SurfaceDissolve {
+  readonly noise: { readonly region: OverlayRegion; readonly tiling?: readonly [number, number] };
+  /** 0 keeps everything; 1 cuts everything. */
+  readonly threshold: number;
+  /** The band's width, in the noise's own units. 0.05 unless given. */
+  readonly edge?: number;
+  /** The band's light. */
+  readonly edgeColour?: Vec3;
+  readonly edgeIntensity?: number;
+  /** A colour laid over the surface through the noise, as light, and how much of it. */
+  readonly overlay?: { readonly colour: Vec3; readonly amount: number };
+}
+
+/**
+ * A second normal map blended into the surface's by six region weights, read through two masks:
+ * the first mask's red, green and blue carry regions 1 to 3, the second's regions 4 to 6. A face's
+ * expressions, or veins brought up all over.
+ */
+export interface SurfaceWrinkle {
+  readonly normal: OverlayRegion;
+  readonly masks: readonly [OverlayRegion, OverlayRegion];
+  readonly weights: readonly [number, number, number, number, number, number];
+}
+
+/**
+ * What a draw lays over its surface beyond its material, for `setSurfaceOverlay`: a rim, a dissolve
+ * and wrinkles, each optional, and the atlas their images are regions of.
+ */
+export interface SurfaceOverlay {
+  /**
+   * The atlas every image above is a region of. Absent: no image is read whatever regions are
+   * named — rims are smooth, nothing dissolves and nothing wrinkles — because the slot then holds a
+   * stand-in whose colour would read as a noise and a mask.
+   */
+  readonly maps?: SurfaceTextureHandle;
+  readonly rim?: SurfaceRim;
+  readonly dissolve?: SurfaceDissolve;
+  readonly wrinkle?: SurfaceWrinkle;
+}
+
+/** Vectors the overlay takes in the material's block: `uOverlay[OVERLAY_VECTORS]`. */
+export const OVERLAY_VECTORS = 15;
+/** Floats `packSurfaceOverlay` fills. */
+export const OVERLAY_FLOATS = OVERLAY_VECTORS * 4;
+
+const finite = (value: number | undefined, fallback: number): number =>
+  value !== undefined && Number.isFinite(value) ? value : fallback;
+
+function region(out: Float32Array, at: number, r: OverlayRegion | undefined | null): void {
+  out[at] = finite(r?.scale[0], 0);
+  out[at + 1] = finite(r?.scale[1], 0);
+  out[at + 2] = finite(r?.offset[0], 0);
+  out[at + 3] = finite(r?.offset[1], 0);
+}
+
+/**
+ * An overlay as the shader reads it, into `out` (`OVERLAY_FLOATS`); all zeros for `null`, which is
+ * no overlay. A region with a zero scale is an image not given, and its term reads as none — a
+ * noise of 1, a mask of 0, no wrinkle — and every region is one without `maps`. Fifteen vectors:
+ *
+ * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim)
+ * - 1: falloff, upward lean, contrast, mask weight
+ * - 2: the rim's noise region; 3: its scroll along x and y, its tiling, the pulse's rate
+ * - 4: the pulse's low and high (1 and 1 where none)
+ * - 5: the rim's mask region
+ * - 6: the dissolve's noise region (a zero scale is no dissolve); 7: its tiling, threshold, edge
+ * - 8: the edge's light and its strength; 9: the laid-over colour and its amount
+ * - 10: the wrinkle normal's region; 11 and 12: the two masks'; 13 and 14: the six weights
+ */
+export function packSurfaceOverlay(overlay: SurfaceOverlay | null, out: Float32Array): void {
+  out.fill(0);
+  if (overlay === null) return;
+  /* No atlas, no region: see `SurfaceOverlay.maps`. */
+  const images = overlay.maps !== undefined;
+  const rim = overlay.rim;
+  if (rim !== undefined) {
+    out[0] = finite(rim.colour[0], 0);
+    out[1] = finite(rim.colour[1], 0);
+    out[2] = finite(rim.colour[2], 0);
+    out[3] = Math.max(0, finite(rim.intensity, 0) * finite(rim.alpha, 1));
+    out[4] = Math.max(0, finite(rim.falloff, 1.5));
+    out[5] = Math.max(0, finite(rim.upward, 0.4));
+    out[6] = Math.max(0, finite(rim.contrast, 1));
+    out[7] = rim.mask === undefined ? 0 : Math.min(Math.max(finite(rim.mask.weight, 0), 0), 1);
+    region(out, 8, images ? rim.noise?.region : null);
+    out[12] = finite(rim.noise?.scroll?.[0], 0);
+    out[13] = finite(rim.noise?.scroll?.[1], 0);
+    out[14] = Math.max(0, finite(rim.noise?.tiling, 1));
+    out[15] = finite(rim.pulse?.rate, 0);
+    out[16] = rim.pulse === undefined ? 1 : finite(rim.pulse.low, 1);
+    out[17] = rim.pulse === undefined ? 1 : finite(rim.pulse.high, 1);
+    region(out, 20, images ? rim.mask?.region : null);
+  }
+  const dissolve = overlay.dissolve;
+  if (dissolve !== undefined) {
+    region(out, 24, images ? dissolve.noise.region : null);
+    out[28] = finite(dissolve.noise.tiling?.[0], 1);
+    out[29] = finite(dissolve.noise.tiling?.[1], 1);
+    out[30] = Math.min(Math.max(finite(dissolve.threshold, 0), 0), 1);
+    out[31] = Math.max(1e-4, finite(dissolve.edge, 0.05));
+    const edge = dissolve.edgeColour ?? [0, 0, 0];
+    out[32] = finite(edge[0], 0);
+    out[33] = finite(edge[1], 0);
+    out[34] = finite(edge[2], 0);
+    out[35] = Math.max(0, finite(dissolve.edgeIntensity, 1));
+    const laid = dissolve.overlay;
+    if (laid !== undefined) {
+      out[36] = finite(laid.colour[0], 0);
+      out[37] = finite(laid.colour[1], 0);
+      out[38] = finite(laid.colour[2], 0);
+      out[39] = Math.max(0, finite(laid.amount, 0));
+    }
+  }
+  const wrinkle = overlay.wrinkle;
+  if (wrinkle !== undefined) {
+    region(out, 40, images ? wrinkle.normal : null);
+    region(out, 44, images ? wrinkle.masks[0] : null);
+    region(out, 48, images ? wrinkle.masks[1] : null);
+    for (let i = 0; i < 6; i++) {
+      out[52 + i] = Math.min(Math.max(finite(wrinkle.weights[i], 0), 0), 1);
+    }
+  }
+}
+
+/** Whether an overlay lays anything at all, so a renderer can leave the lit switch off. */
+export function overlayLays(overlay: SurfaceOverlay | null): boolean {
+  return (
+    overlay !== null &&
+    (overlay.rim !== undefined || overlay.dissolve !== undefined || overlay.wrinkle !== undefined)
+  );
+}

package/src/render/surfaceTexture.ts

@@ -293,6 +293,13 @@ export class SurfaceTexture {
   private effectsTable: WebGLTexture | null = null;
   /** The block format a compressed texture holds, or null for one uploaded from images. */
   private readonly blockFormat: BlockFormat | null;
+  /** Level 0's size, which `flatLayer` copies; kept as `update` changes it. */
+  private width = 0;
+  private height = 0;
+  /** The texture's storage format, which `flatLayer`'s copy matches so the copy converts nothing. */
+  private readonly storage: number;
+  /** Layer 0 as a plain 2D texture, made by `flatLayer` and dropped when the pixels change. */
+  private flat: WebGLTexture | null = null;
 
   /**
    * One image, or an array of images that must share one size (`layerSize` refuses otherwise).
@@ -327,6 +334,9 @@ export class SurfaceTexture {
       this.layers = 1;
       this.blockFormat = null;
       this.mipmapped = false;
+      this.width = capture.width;
+      this.height = capture.height;
+      this.storage = capture.float ? gl.RGBA16F : gl.RGBA8;
       gl.texStorage3D(
         gl.TEXTURE_2D_ARRAY,
         1,
@@ -340,6 +350,9 @@ export class SurfaceTexture {
       this.layers = baked.layers.length;
       this.blockFormat = null;
       this.mipmapped = false;
+      this.width = baked.width;
+      this.height = baked.height;
+      this.storage = gl.RGBA8;
       /* A typed array refuses either flag set, so both are put down here rather than assumed. */
       gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
       gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
@@ -377,6 +390,7 @@ export class SurfaceTexture {
          `generateMipmap` cannot write a compressed format. */
       this.layers = blocks.length;
       this.blockFormat = (blocks[0] as CompressedTextureSource).format;
+      this.storage = gl.NONE;
       this.mipmapped = (options.mipmap ?? true) && plan.levels > 1;
       uploadCompressedArray(gl, plan.name, blocks, this.mipmapped ? plan.levels : 1);
     } else {
@@ -384,6 +398,10 @@ export class SurfaceTexture {
       this.layers = sources.length;
       this.blockFormat = null;
       this.mipmapped = options.mipmap ?? true;
+      const { width, height } = layerSize(sources);
+      this.width = width;
+      this.height = height;
+      this.storage = this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA8;
       uploadImages(gl, sources, this.srgb);
     }
     gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, wrap);
@@ -462,6 +480,9 @@ export class SurfaceTexture {
     refuseArrayUpdate(this.layers);
     refuseBlockUpdate(this.blockFormat);
     const { width, height } = sourceSize(source);
+    this.width = width;
+    this.height = height;
+    this.dropFlat(gl);
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
     /* Unflipped, matching the constructor. See it for why, and for what it cost. */
     gl.texImage3D(
@@ -494,8 +515,54 @@ export class SurfaceTexture {
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
   }
 
+  /**
+   * Layer 0 as a plain 2D texture: what a `sampler2D` can be handed, which an array cannot. Copied
+   * the first time it is asked for, by a framebuffer blit into storage of the same format, and kept
+   * until `update` or `dispose`. Engine-internal: a surface overlay's atlas is bound where the
+   * lit stage's one 2D image slot is (`surfaceOverlay.ts`).
+   *
+   * **Null for blocks**, which no framebuffer can read; the caller says so. What it costs is a copy
+   * of level 0 in memory beside the array, and the bindings of both framebuffer targets, which are
+   * read back before the blit and put back after it — a sync query, paid once per image.
+   */
+  flatLayer(gl: WebGL2RenderingContext): WebGLTexture | null {
+    if (this.texture === null || this.blockFormat !== null) return null;
+    if (this.flat !== null) return this.flat;
+    const flat = gl.createTexture();
+    const read = gl.createFramebuffer();
+    const draw = gl.createFramebuffer();
+    if (flat === null || read === null || draw === null) return null;
+    gl.bindTexture(gl.TEXTURE_2D, flat);
+    gl.texStorage2D(gl.TEXTURE_2D, 1, this.storage, this.width, this.height);
+    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);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    const heldRead = gl.getParameter(gl.READ_FRAMEBUFFER_BINDING) as WebGLFramebuffer | null;
+    const heldDraw = gl.getParameter(gl.DRAW_FRAMEBUFFER_BINDING) as WebGLFramebuffer | null;
+    gl.bindFramebuffer(gl.READ_FRAMEBUFFER, read);
+    gl.framebufferTextureLayer(gl.READ_FRAMEBUFFER, gl.COLOR_ATTACHMENT0, this.texture, 0, 0);
+    gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, draw);
+    gl.framebufferTexture2D(gl.DRAW_FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, flat, 0);
+    const [w, h] = [this.width, this.height];
+    gl.blitFramebuffer(0, 0, w, h, 0, 0, w, h, gl.COLOR_BUFFER_BIT, gl.NEAREST);
+    gl.bindFramebuffer(gl.READ_FRAMEBUFFER, heldRead);
+    gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, heldDraw);
+    gl.deleteFramebuffer(read);
+    gl.deleteFramebuffer(draw);
+    this.flat = flat;
+    return flat;
+  }
+
+  private dropFlat(gl: WebGL2RenderingContext): void {
+    if (this.flat !== null) gl.deleteTexture(this.flat);
+    this.flat = null;
+  }
+
   dispose(gl: WebGL2RenderingContext): void {
     if (this.texture === null) return;
+    this.dropFlat(gl);
     gl.deleteTexture(this.texture);
     this.texture = null;
     if (this.effectsTable !== null) gl.deleteTexture(this.effectsTable);

package/src/render/temporalAa.ts

@@ -451,6 +451,17 @@ export class TemporalHistory {
   private picture = false;
   private width = 0;
   private height = 0;
+  /** Whether this frame of the renderer's has opened one of the sequence, and what it answered. */
+  private opened = false;
+  private answer = false;
+
+  /**
+   * A frame of the renderer's began: the next `openFrame` opens a frame of the sequence. Called at
+   * `beginFrame`, by both backends.
+   */
+  nextFrame(): void {
+    this.opened = false;
+  }
 
   /**
    * Open a frame at this target size, and answer whether the history may be sampled.
@@ -458,13 +469,22 @@ export class TemporalHistory {
    * **The jitter advances whether or not it may be.** Holding the sequence still on the frames a
    * resize or a cut discarded would sample the same position twice running, which is one sample
    * and not two.
+   *
+   * **Once a frame, however many times it is asked.** A renderer asks where the scene's camera
+   * arrives, and a frame binds that camera again after a scene capture or anything else that bound
+   * another; each asking opened a frame of its own, so the sequence stepped twice in such a frame
+   * and the edges of the picture swam. Asked again, it gives the answer it gave. What it gives up:
+   * a size changed between two asks in one frame is seen at the next frame, not at once.
    */
   openFrame(width: number, height: number): boolean {
+    if (this.opened) return this.answer;
+    this.opened = true;
     this.frameIndex++;
     const usable = this.picture && width === this.width && height === this.height;
     if (!usable) this.picture = false;
     this.width = width;
     this.height = height;
+    this.answer = usable;
     return usable;
   }
 

package/src/render/vertexDefaults.ts

@@ -113,8 +113,18 @@ export const OUTPUT_TRANSFORM_CODE: Readonly<Record<string, number>> = {
   srgb: 1,
   aces: 2,
   shoulder: 3,
+  filmic: 4,
 };
 
+/**
+ * The code a **forward** pass grades with: the transform's own, except `filmic`, which only the
+ * composite carries the constants for, and which a pass grading itself therefore draws as `aces`.
+ * Both backends' `gradeCode` read this, so neither can hand a forward stage a code it lacks.
+ */
+export function forwardTransformCode(transform: string): number {
+  return transform === 'filmic' ? 2 : (OUTPUT_TRANSFORM_CODE[transform] ?? 0);
+}
+
 /**
  * How far the speed rush reaches, and how far a motion-blurred pixel may travel, both in UV.
  *
@@ -123,3 +133,21 @@ export const OUTPUT_TRANSFORM_CODE: Readonly<Record<string, number>> = {
  */
 export const RUSH_REACH_UV = 0.012;
 export const MOTION_BLUR_MAX_UV = 0.03;
+
+/**
+ * A longest smear as `setCameraMotionBlur` takes it: a share of the frame, above zero and at most
+ * half, and the default where the number is not one. Shared, so both backends cap one way.
+ */
+export function clampMotionShare(share: number): number {
+  return Number.isFinite(share) && share > 0 ? Math.min(share, 0.5) : MOTION_BLUR_MAX_UV;
+}
+
+/**
+ * Said once where a draw names where it was last frame and the frame blurs by motion, but keeps no
+ * motion target to blur that draw by: each object's own motion is drawn only under a
+ * reconstruction on WebGPU, and anywhere else the camera's motion alone smears the frame.
+ */
+export const OBJECT_BLUR_UNKEPT =
+  "[driftengine] motion blur follows each draw's own motion only under a reconstruction " +
+  "(DriftTR, WebGPU), which draws the motion target it reads; here the camera's motion alone " +
+  'blurs the frame, and a moving object is smeared only as the camera moved past it.';