@driftengine/core 4.9.0 → 4.10.0

package/src/render/shaders/outputTransform.ts

@@ -48,20 +48,8 @@ vec3 highlightShoulder(vec3 c) {
 }
 `;
 
-/**
- * `uOutputTransform` and `uOutputExposure`, the fit, and `applyOutputTransform`.
- *
- * Declares its own two uniforms, so including it is the whole of what a fragment stage has to
- * do besides calling it. Both are ints and floats rather than defines because the choice is a
- * caller's, per draw, and a permutation per output transform would double a pipeline count for
- * a branch that costs one compare.
- */
-export const OUTPUT_TRANSFORM_GLSL = `
-/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder then sRGB. See renderQuality.ts. */
-uniform int uOutputTransform;
-/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */
-uniform float uOutputExposure;
-
+/** The fit and `applyOutputTransform`, below whichever declaration of the two uniforms. */
+const OUTPUT_TRANSFORM_BODY_GLSL = `
 /*
  * ACES: the reference fit, not the cheap one.
  *
@@ -128,3 +116,31 @@ vec3 applyOutputTransform(vec3 c) {
   return linearToSrgb(c);
 }
 `;
+
+/**
+ * `uOutputTransform` and `uOutputExposure`, the fit, and `applyOutputTransform`.
+ *
+ * Declares its own two uniforms, so including it is the whole of what a fragment stage has to
+ * do besides calling it. Both are ints and floats rather than defines because the choice is a
+ * caller's, per draw, and a permutation per output transform would double a pipeline count for
+ * a branch that costs one compare.
+ */
+export const OUTPUT_TRANSFORM_GLSL = `
+/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder then sRGB. See renderQuality.ts. */
+uniform int uOutputTransform;
+/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */
+uniform float uOutputExposure;
+${OUTPUT_TRANSFORM_BODY_GLSL}`;
+
+/**
+ * The same, for the lit stage, whose two uniforms live in its material block: a draw that opts out
+ * of the grade sets them, so they change with the material and not with the pass. See
+ * `hoistUniformBlock` in `scripts/wgsl/transform.mjs`. Text otherwise identical, so WebGL2 runs
+ * the same program it always has.
+ */
+export const LIT_OUTPUT_TRANSFORM_GLSL = `
+/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder then sRGB. See renderQuality.ts. */
+uniform int uOutputTransform; // wgsl:material
+/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */
+uniform float uOutputExposure; // wgsl:material
+${OUTPUT_TRANSFORM_BODY_GLSL}`;

package/src/render/shaders/vertexChannel.ts

@@ -39,6 +39,33 @@ uniform float uWindTime;
 uniform vec2 uWindSpatialPhase;
 `;
 
+/**
+ * The same, for the lit stage, whose wind lives in its view block: the frame's and not the draw's,
+ * so a draw's own block does not change when the wind does. See `hoistUniformBlock` in
+ * `scripts/wgsl/transform.mjs`. Text otherwise identical, so WebGL2 runs the same program it always
+ * has; the depth stage keeps the unmarked chunk, having no view block.
+ */
+export const LIT_CHANNEL_ATTRIBUTE = `
+layout(location = 13) in vec4 aChannel;
+
+/*
+ * The frame's wind, already converted by \`resolveScatterDeform\` — a normalised direction, metres
+ * of bend, a gust amplitude and a scaled clock.
+ *
+ * **The same numbers the scatter batch reads, and that is the rule rather than an economy.** A
+ * second conversion here would be a second wind however identical its inputs, and the failure is
+ * not localised: it shows up as a scene that does not cohere, a canopy leaning one way while the
+ * grass beneath it leans another, with no single element looking wrong. See "One wind, sampled
+ * once" in AGENTS.md.
+ */
+uniform vec2 uWindDirection; // wgsl:view
+uniform float uWindSpeed; // wgsl:view
+uniform float uWindGust; // wgsl:view
+uniform float uWindTime; // wgsl:view
+/* Spatial frequency of the travelling gust, per metre. */
+uniform vec2 uWindSpatialPhase; // wgsl:view
+`;
+
 /**
  * Where the wind puts a vertex, given how much of it that vertex takes.
  *

package/src/render/staticDraws.ts

@@ -0,0 +1,95 @@
+/**
+ * Draws that do not change between frames, captured once from an enumeration and replayed into any
+ * colour pass: what `createStaticDraws` keeps, and the one rule both backends replay it by.
+ *
+ * **Captured, not referenced.** An enumeration is a closure over the caller's state, written to
+ * allocate nothing, so it hands a sink its scratch: the matrix it fills for every entry and the
+ * count it rewrites for the next batch. A list kept across frames copies both when it is made, so
+ * what it draws is what the enumeration said then. Meshes, batches and materials are held by
+ * reference: they are the caller's, and disposing one a list still holds is the caller's error.
+ *
+ * **Rigid meshes and instanced batches only.** A skinned mesh is posed every frame and a scatter
+ * batch bends with every frame's wind, so neither can be kept, and both are refused by name rather
+ * than captured in the pose they happened to have. A caller draws them each frame as it always has.
+ *
+ * What a backend does with the list is its own: WebGL2 replays the entries every frame through
+ * the scene-caster path, and WebGPU records them once into a render bundle per view. See
+ * `RendererApi.createStaticDraws` for what a caller is promised, which is the same on both.
+ */
+import type { InstancedHandle, MeshHandle } from './backend/api.ts';
+import type { MeshInstances } from './instances.ts';
+import type { SceneCasterMaterial, ShadowCasterSink, ShadowCasters } from './shadowCasters.ts';
+
+/** A list from `createStaticDraws`. Opaque but for its size. */
+export interface StaticDrawsHandle {
+  /** How many entries it holds: meshes and batches, a batch counting once. */
+  readonly draws: number;
+}
+
+/** One captured entry. */
+export type StaticEntry =
+  | {
+      readonly kind: 'mesh';
+      readonly mesh: MeshHandle;
+      readonly model: Float32Array;
+      readonly material: SceneCasterMaterial;
+    }
+  | {
+      readonly kind: 'instanced';
+      readonly batch: InstancedHandle;
+      readonly data: MeshInstances;
+      readonly material: SceneCasterMaterial;
+    };
+
+/** What both backends hold: the entries, and whether the list has been disposed. */
+export interface StaticDrawsList extends StaticDrawsHandle {
+  readonly entries: readonly StaticEntry[];
+  disposed: boolean;
+}
+
+/** Enumerate `casters` once into a list. Allocates: it runs when the list is made, not per frame. */
+export function captureStaticDraws(casters: ShadowCasters): StaticDrawsList {
+  const entries: StaticEntry[] = [];
+  const sink: ShadowCasterSink = {
+    mesh: (mesh, model, material) => {
+      entries.push({
+        kind: 'mesh',
+        mesh,
+        model: new Float32Array(model as Float32Array),
+        material: material ?? null,
+      });
+    },
+    instanced: (batch, data, material) => {
+      /* The batch's placements are on the device already; the count is the caller's scratch. */
+      entries.push({ kind: 'instanced', batch, data: { ...data }, material: material ?? null });
+    },
+    skinnedMesh: () => {
+      throw new Error(
+        'createStaticDraws: a skinned mesh is posed every frame, so a list kept across frames ' +
+          'cannot hold one. Draw it each frame, with drawMesh or drawSceneCasters.',
+      );
+    },
+    scatter: () => {
+      throw new Error(
+        'createStaticDraws: a scatter batch bends with every frame’s wind, so a list kept across ' +
+          'frames cannot hold one. Draw it each frame with drawScatter.',
+      );
+    },
+  };
+  casters(sink);
+  return {
+    entries,
+    get draws() {
+      return entries.length;
+    },
+    disposed: false,
+  };
+}
+
+/** Hand every entry to `sink`, in the order it was captured. */
+export function replayStaticDraws(list: StaticDrawsList, sink: ShadowCasterSink): void {
+  for (const entry of list.entries) {
+    if (entry.kind === 'mesh') sink.mesh(entry.mesh, entry.model, entry.material);
+    else sink.instanced?.(entry.batch, entry.data, entry.material);
+  }
+}

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,9 @@ 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;
@@ -404,27 +427,13 @@ export class SurfaceTexture {
       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
@@ -475,9 +484,17 @@ 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;
@@ -501,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.