@driftengine/core 4.8.6 → 4.9.0

package/src/render/surfaceTexture.ts

@@ -23,6 +23,8 @@ import type { SurfaceLayerEffect } from './surfaceEffects.ts';
 import type { CutoutMode } from './cutoutDither.ts';
 import { isLightmapTexels } from './lightmap.ts';
 import type { LightmapTexels } from './lightmap.ts';
+import { isSceneCaptureTexels } from './sceneCapture.ts';
+import type { SceneCaptureTexels } from './sceneCapture.ts';
 
 /**
  * How a texture behaves past its edges and between its texels.
@@ -172,6 +174,24 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
    * that is not a colour.
    */
   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.
+   *
+   * 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
+   * 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.
+   *
+   * On the standard, lightmap and anisotropic models. Skin and the eye are physical already; hair
+   * keeps its own three lobes. **What it gives up**: the look's independence of strength and width,
+   * and an 8-bit frame clips the brighter peak without `hdrScene`.
+   */
+  physicalSpecular?: boolean;
 }
 
 export interface SurfaceTextureOptions {
@@ -273,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).
@@ -281,14 +308,16 @@ export class SurfaceTexture {
    */
   constructor(
     gl: WebGL2RenderingContext,
-    source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels,
+    source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels | SceneCaptureTexels,
     options: SurfaceTextureOptions = {},
     compressed: readonly CompressedTextureFormat[] = [],
   ) {
-    /* A lightmap's page: half floats, uploaded as they are. See `lightmap.ts`. */
+    /* A scene capture's target: one empty layer the renderer draws into. See `sceneCapture.ts`. */
+    const capture = isSceneCaptureTexels(source) ? source : null;
+    /* A lightmap's page: two layers of bytes, uploaded as they are. See `lightmap.ts`. */
     const baked = isLightmapTexels(source) ? source : null;
     const listed = (
-      baked !== null ? [] : Array.isArray(source) ? source : [source]
+      baked !== null || capture !== null ? [] : Array.isArray(source) ? source : [source]
     ) as readonly SurfaceSource[];
     const blocks = compressedLayers(listed);
     this.srgb = (options.colorSpace ?? 'linear') === 'srgb';
@@ -300,31 +329,68 @@ export class SurfaceTexture {
     const wrap = (options.wrap ?? 'repeat') === 'repeat' ? gl.REPEAT : gl.CLAMP_TO_EDGE;
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
 
-    if (baked !== null) {
+    if (capture !== null) {
+      /* Immutable storage, one level: a framebuffer attachment, and radiance read linear. */
+      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,
+        capture.float ? gl.RGBA16F : gl.RGBA8,
+        capture.width,
+        capture.height,
+        1,
+      );
+    } else if (baked !== null) {
       /* No chain: a page is read at its own resolution, and a level of it would blend regions. */
-      this.layers = baked.layers;
+      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);
+      /* Bytes, and read by `texelFetch` alone: the shader decodes and filters. See `lightmap.ts`. */
       gl.texImage3D(
         gl.TEXTURE_2D_ARRAY,
         0,
-        gl.RGBA16F,
+        gl.RGBA8,
         baked.width,
         baked.height,
-        baked.layers,
+        this.layers,
         0,
         gl.RGBA,
-        gl.HALF_FLOAT,
-        baked.texels,
+        gl.UNSIGNED_BYTE,
+        null,
       );
+      /* A layer at a time, so a page's arrays are uploaded where they lie rather than joined. */
+      for (let layer = 0; layer < this.layers; layer++) {
+        gl.texSubImage3D(
+          gl.TEXTURE_2D_ARRAY,
+          0,
+          0,
+          0,
+          layer,
+          baked.width,
+          baked.height,
+          1,
+          gl.RGBA,
+          gl.UNSIGNED_BYTE,
+          baked.layers[layer] as Uint8Array,
+        );
+      }
     } else if (blocks !== null && plan !== null) {
       /* The stored chain, or level 0 alone where no chain was asked for. Nothing is generated:
          `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 {
@@ -332,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);
@@ -410,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(
@@ -428,14 +501,68 @@ export class SurfaceTexture {
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
   }
 
+  /**
+   * Attach the only layer as the bound framebuffer's colour: a scene capture's target, drawn into
+   * by `captureScene`. Engine-internal, as `bind` is.
+   */
+  attachColor(gl: WebGL2RenderingContext): void {
+    gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, this.texture, 0, 0);
+  }
+
   /** 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_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.';