@driftengine/core 4.8.7 → 4.10.0

package/src/render/surfaceTexture.ts

@@ -10,7 +10,12 @@
  */
 import type { SurfaceModel } from './surfaceModel.ts';
 import { layerSize, refuseArrayUpdate, sourceSize } from './textureSource.ts';
-import { compressedLayers, planBlocks, refuseBlockUpdate } from './compressedSource.ts';
+import {
+  compressedLayers,
+  isCompressedSource,
+  planBlocks,
+  refuseBlockUpdate,
+} from './compressedSource.ts';
 import type {
   BlockFormat,
   CompressedTextureFormat,
@@ -119,7 +124,7 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
    * which is every light's default too, so a scene that names no channel is lit as it always was.
    *
    * A point or spot light shades this surface only where its `PointLightSet.lightChannels` and this
-   * share a bit — Unreal's lighting channels. A character's own key and rim lights on channel 2,
+   * share a bit — lighting channels. A character's own key and rim lights on channel 2,
    * and the character's materials on 3, light the character and leave the floor around it as the
    * stage's lights alone have it. **What it does not reach**: the sun, the sky and the probes, area
    * lights, DriftLight's volume and the GPU-driven pipeline light every surface whatever its mask.
@@ -153,6 +158,22 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
    * which is the opposite of what the caller asked for.
    */
   occlusionStrength?: number;
+  /**
+   * How much of the environment this material's draws mirror, 0 to 1: the number
+   * `setSurfaceReflectivity` sets for every draw, stated by the material for its own. Absent, its
+   * draws wear the setter's, as every material's did before this existed.
+   *
+   * **Here so a static list can carry it.** A list keeps each entry's material and none of the
+   * renderer's state between draws (`createStaticDraws`), so a stage whose batches each mirror their
+   * own share of a baked reflection says so in the material it records. What it gives up is nothing a
+   * setter could do: one called after this material is set is ignored for the material's draws.
+   */
+  reflectivity?: number;
+  /**
+   * How bright the environment this material's draws reflect is: `setEnvironmentGain`'s number,
+   * stated by the material for its own, and absent the setter's. Held non-negative.
+   */
+  environmentGain?: number;
   /**
    * Scales the emissive map, per channel. Default 1.
    *
@@ -176,14 +197,14 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
   modelMap?: Texture | null;
   /**
    * Whether a lamp's and the sun's highlight on this surface is GGX's own, `π · D · Vis · F · N·L`,
-   * as Unreal and this engine's skin and eye shade it, rather than the engine's lobe scaled to a
-   * peak of one. **False by default**, every surface as it was.
+   * as physically based renderers and this engine's skin and eye shade it, rather than the engine's
+   * lobe scaled to a peak of one. **False by default**, every surface as it was.
    *
    * The peak-normalised lobe is a look control: the specular attribute says how strong a highlight
    * is and roughness how wide, apart. Physical, they are entangled as they are in a real surface —
    * the peak is `1 / (4 α²)` of the light head-on, so a polished surface's highlight is many times
    * the look's and a rough one's lower and broader — and the specular attribute is read as the
-   * reflectance at normal incidence, F0: Unreal's `0.08 × Specular`, 0.04 at its default. Fresnel
+   * reflectance at normal incidence, F0: `0.08 × Specular`, 0.04 at its default. Fresnel
    * then brightens every surface toward grazing, not only a metal. A rectangle's highlight is the
    * lobe integrated over it with the attribute as F0 already, so it is unchanged either way.
    *
@@ -292,7 +313,16 @@ export class SurfaceTexture {
   /** The per-layer effects table, or null for a texture given none. See `surfaceEffects.ts`. */
   private effectsTable: WebGLTexture | null = null;
   /** The block format a compressed texture holds, or null for one uploaded from images. */
-  private readonly blockFormat: BlockFormat | null;
+  private blockFormat: BlockFormat | null;
+  /** How the texture is sampled, kept so blocks swapped in by `update` are sampled the same way. */
+  private readonly sampling: { wrap: number; nearest: boolean; anisotropy: number };
+  /** 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 +357,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 +373,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 +413,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,29 +421,19 @@ 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);
-    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_ARRAY, gl.TEXTURE_MAG_FILTER, nearest ? gl.NEAREST : gl.LINEAR);
-    gl.texParameteri(
-      gl.TEXTURE_2D_ARRAY,
-      gl.TEXTURE_MIN_FILTER,
-      this.mipmapped
-        ? nearest
-          ? gl.NEAREST_MIPMAP_LINEAR
-          : gl.LINEAR_MIPMAP_LINEAR
-        : nearest
-          ? gl.NEAREST
-          : gl.LINEAR,
-    );
-
+    this.sampling = {
+      wrap,
+      nearest: options.filter === 'nearest',
+      anisotropy: options.anisotropy ?? DEFAULT_ANISOTROPY,
+    };
+    this.applySampling(gl);
     if (this.mipmapped && this.blockFormat === null) gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
-    applyAnisotropy(gl, options.anisotropy ?? DEFAULT_ANISOTROPY);
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
 
     /* Half floats, nearest, clamped: a table read by texelFetch, whose every whole number is under
@@ -457,11 +484,22 @@ export class SurfaceTexture {
    * Not a hot path: it re-uploads the whole image and regenerates the chain. A caller
    * doing this every frame at any size wants to know that it costs what it costs.
    */
-  update(gl: WebGL2RenderingContext, source: TexImageSource): void {
+  update(
+    gl: WebGL2RenderingContext,
+    source: TexImageSource | CompressedTextureSource,
+    compressed: readonly CompressedTextureFormat[] = [],
+  ): void {
     if (this.texture === null) return;
     refuseArrayUpdate(this.layers);
+    if (isCompressedSource(source)) {
+      this.swapToBlocks(gl, source, compressed);
+      return;
+    }
     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(
@@ -480,6 +518,56 @@ export class SurfaceTexture {
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
   }
 
+  /**
+   * Blocks in place of the image, behind the same handle: **a new GL object** rather than the
+   * image's levels respecified, because a chain shorter than the image's would leave the levels
+   * past it allocated, and immutable storage could not be respecified at all. Sampled as the image
+   * was, and refused before anything changes where the context does not take the format.
+   */
+  private swapToBlocks(
+    gl: WebGL2RenderingContext,
+    source: CompressedTextureSource,
+    compressed: readonly CompressedTextureFormat[],
+  ): void {
+    const plan = planBlocks([source], this.srgb, compressed);
+    const texture = gl.createTexture();
+    if (texture === null) throw new Error('SurfaceTexture: createTexture failed');
+    this.dropFlat(gl);
+    if (this.texture !== null) gl.deleteTexture(this.texture);
+    this.texture = texture;
+    this.blockFormat = source.format;
+    this.width = source.width;
+    this.height = source.height;
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+    uploadCompressedArray(gl, plan.name, [source], this.mipmapped ? plan.levels : 1);
+    this.applySampling(gl);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+  }
+
+  /**
+   * Wrap, filters and anisotropy on the bound texture. 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.
+   */
+  private applySampling(gl: WebGL2RenderingContext): void {
+    const { wrap, nearest, anisotropy } = this.sampling;
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, wrap);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, wrap);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, nearest ? gl.NEAREST : gl.LINEAR);
+    gl.texParameteri(
+      gl.TEXTURE_2D_ARRAY,
+      gl.TEXTURE_MIN_FILTER,
+      this.mipmapped
+        ? nearest
+          ? gl.NEAREST_MIPMAP_LINEAR
+          : gl.LINEAR_MIPMAP_LINEAR
+        : nearest
+          ? gl.NEAREST
+          : gl.LINEAR,
+    );
+    applyAnisotropy(gl, anisotropy);
+  }
+
   /**
    * Attach the only layer as the bound framebuffer's colour: a scene capture's target, drawn into
    * by `captureScene`. Engine-internal, as `bind` is.
@@ -494,8 +582,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.';