@driftengine/core 4.3.0 → 4.4.0

package/src/environment/daylight.ts

@@ -0,0 +1,152 @@
+/**
+ * A day's lighting as a palette keyed by one number, and an exposure that follows it in time.
+ *
+ * **Keyed by any scalar a caller chooses.** A courtyard keys it by the sun's elevation in degrees,
+ * because what the light does there is a function of how high the sun stands; a scene that lerps
+ * between a night and a day by a day factor keys it at 0 and 1 and gets exactly the blend it had.
+ * The palette is data — colours, a density, a strength, an exposure — so which hours exist and what
+ * they look like stay the scene's, and the mechanism is the engine's.
+ *
+ * **Linear between keys, and in stops for exposure.** Colours and densities blend linearly, which
+ * is what every hand-written day cycle in this repository did; exposure blends in log2, because two
+ * keys a stop apart should pass through half a stop and not through the arithmetic mean, which sits
+ * nearer the brighter key. What that gives up is smoothness at a key: the blend has a corner there.
+ * What would make it wrong is a palette so sparse that the corner shows as a change of pace in the
+ * sky, and the answer then is more keys rather than a curve.
+ *
+ * Nothing here allocates after construction: `resolveDaylight` writes into a caller-owned state.
+ */
+import type { Vec3 } from '../math/color.ts';
+
+/** The lighting at one point of the palette's scalar. Every colour is linear and may exceed one. */
+export interface DaylightKey {
+  /** Where on the palette's scalar this key sits: a sun elevation, a day factor, an hour. */
+  readonly at: number;
+  /** The sun's radiance at the surface it lights, which is the directional light while it is up. */
+  readonly sunColor: Readonly<Vec3>;
+  /** The moon's, for whichever part of the palette the moon lights. */
+  readonly moonColor: Readonly<Vec3>;
+  readonly skyTop: Readonly<Vec3>;
+  readonly skyHorizon: Readonly<Vec3>;
+  readonly skyDeep: Readonly<Vec3>;
+  /** The hemisphere's sky half. */
+  readonly ambient: Readonly<Vec3>;
+  /** The hemisphere's ground half: what the floor throws back up. */
+  readonly ambientGround: Readonly<Vec3>;
+  readonly fogColor: Readonly<Vec3>;
+  readonly fogDensity: number;
+  /** How dark a directional shadow is, 0 to 1. */
+  readonly shadowStrength: number;
+  /** The emissive master gain: how strongly lamps and flames read against this light. */
+  readonly emissiveGain: number;
+  /** The exposure a viewer's eye settles on here. Positive; blended in stops. */
+  readonly exposure: number;
+}
+
+/** Keys in ascending order of `at`, validated once. Build with `createDaylightPalette`. */
+export interface DaylightPalette {
+  readonly keys: readonly DaylightKey[];
+}
+
+/** One moment of the palette, written in place by `resolveDaylight`. */
+export interface DaylightState {
+  sunColor: Vec3;
+  moonColor: Vec3;
+  skyTop: Vec3;
+  skyHorizon: Vec3;
+  skyDeep: Vec3;
+  ambient: Vec3;
+  ambientGround: Vec3;
+  fogColor: Vec3;
+  fogDensity: number;
+  shadowStrength: number;
+  emissiveGain: number;
+  exposure: number;
+}
+
+/** Sort and check the keys. Throws at construction, so a bad palette never reaches a frame. */
+export function createDaylightPalette(keys: readonly DaylightKey[]): DaylightPalette {
+  if (keys.length === 0) throw new Error('a daylight palette needs at least one key');
+  const sorted = [...keys].sort((a, b) => a.at - b.at);
+  for (let i = 0; i < sorted.length; i++) {
+    const current = sorted[i] as DaylightKey;
+    if (!(current.exposure > 0)) {
+      throw new Error(`the key at ${current.at} has exposure ${current.exposure}; it must be > 0`);
+    }
+    if (i > 0 && (sorted[i - 1] as DaylightKey).at === current.at) {
+      throw new Error(`a daylight palette has two keys at ${current.at}`);
+    }
+  }
+  return { keys: sorted };
+}
+
+export function createDaylightState(): DaylightState {
+  return {
+    sunColor: [0, 0, 0],
+    moonColor: [0, 0, 0],
+    skyTop: [0, 0, 0],
+    skyHorizon: [0, 0, 0],
+    skyDeep: [0, 0, 0],
+    ambient: [0, 0, 0],
+    ambientGround: [0, 0, 0],
+    fogColor: [0, 0, 0],
+    fogDensity: 0,
+    shadowStrength: 0,
+    emissiveGain: 0,
+    exposure: 1,
+  };
+}
+
+function blendInto(out: Vec3, a: Readonly<Vec3>, b: Readonly<Vec3>, t: number): void {
+  out[0] = a[0] + (b[0] - a[0]) * t;
+  out[1] = a[1] + (b[1] - a[1]) * t;
+  out[2] = a[2] + (b[2] - a[2]) * t;
+}
+
+/** The palette at `at`, into `out`. Past either end the nearest key holds. */
+export function resolveDaylight(
+  at: number,
+  palette: DaylightPalette,
+  out: DaylightState,
+): DaylightState {
+  const keys = palette.keys;
+  let upper = 0;
+  while (upper < keys.length && (keys[upper] as DaylightKey).at < at) upper++;
+  const b = keys[Math.min(upper, keys.length - 1)] as DaylightKey;
+  const a = keys[Math.max(upper - 1, 0)] as DaylightKey;
+  const t = a === b ? 0 : (at - a.at) / (b.at - a.at);
+  blendInto(out.sunColor, a.sunColor, b.sunColor, t);
+  blendInto(out.moonColor, a.moonColor, b.moonColor, t);
+  blendInto(out.skyTop, a.skyTop, b.skyTop, t);
+  blendInto(out.skyHorizon, a.skyHorizon, b.skyHorizon, t);
+  blendInto(out.skyDeep, a.skyDeep, b.skyDeep, t);
+  blendInto(out.ambient, a.ambient, b.ambient, t);
+  blendInto(out.ambientGround, a.ambientGround, b.ambientGround, t);
+  blendInto(out.fogColor, a.fogColor, b.fogColor, t);
+  out.fogDensity = a.fogDensity + (b.fogDensity - a.fogDensity) * t;
+  out.shadowStrength = a.shadowStrength + (b.shadowStrength - a.shadowStrength) * t;
+  out.emissiveGain = a.emissiveGain + (b.emissiveGain - a.emissiveGain) * t;
+  out.exposure = t === 0 ? a.exposure : a.exposure * (b.exposure / a.exposure) ** t;
+  return out;
+}
+
+/**
+ * `current` moved toward `target` over `dtSec`, closing half the distance in stops every
+ * `halfLifeSec`.
+ *
+ * **In time, not per frame**, so a 144 Hz display adapts exactly as fast as a 60 Hz one: the
+ * remaining distance after any number of steps is `2^(−elapsed / halfLife)` of what it was, however
+ * the elapsed time was cut up. A half-life of zero is a cut to the target. Both exposures must be
+ * positive, which is what an exposure is.
+ */
+export function easeExposure(
+  current: number,
+  target: number,
+  dtSec: number,
+  halfLifeSec: number,
+): number {
+  if (halfLifeSec <= 0) return target;
+  if (dtSec <= 0) return current;
+  const closed = 1 - 2 ** (-dtSec / halfLifeSec);
+  return current * (target / current) ** closed;
+}

package/src/geometry/meshConcat.ts

@@ -0,0 +1,100 @@
+/**
+ * Meshes moved and joined as typed arrays: the loader's fast path, with no builder in between.
+ *
+ * **`MeshBuilder` is for building geometry, and a loader was using it to copy geometry.** It
+ * pushes every vertex one number at a time into growable arrays, and it carries the attributes a
+ * procedural mesh has. Streaming a bought courtyard spent seven seconds of its main thread there,
+ * copying each part twice, once to upload it and once into its merge group. Worse, the builder has
+ * no tangent channel, so every normal-mapped part lost the frame its file carried and the shader
+ * fell back to derivatives.
+ *
+ * So `placeMesh` moves a mesh by a fit, or hands it back untouched when the fit is the identity,
+ * and `concatMeshes` joins a group once, into arrays sized in advance. An attribute one member
+ * lacks is filled with the value a mesh without it draws with (`ABSENT_ATTRIBUTE`). One no member
+ * carries is left out, as absent rather than invented.
+ */
+import { ABSENT_ATTRIBUTE } from '../render/vertexDefaults.ts';
+import type { MeshData } from '../render/mesh.ts';
+
+/** The optional per-vertex attributes, with how many floats a vertex each carries. */
+const OPTIONAL = [
+  ['specular', 1],
+  ['tangents', 4],
+  ['uvs', 2],
+  ['emissiveColor', 3],
+  ['roughness', 1],
+  ['grain', 1],
+  ['relief', 1],
+  ['channel', 4],
+  ['joints', 4],
+  ['weights', 4],
+] as const;
+
+/**
+ * `mesh` scaled uniformly and then moved by `x, y, z`. The same object when the fit is the
+ * identity; otherwise a copy of the positions and every other attribute shared, since a uniform
+ * scale turns no normal. Morph deltas are the caller's to scale.
+ */
+export function placeMesh(mesh: MeshData, x: number, y: number, z: number, scale = 1): MeshData {
+  if (x === 0 && y === 0 && z === 0 && scale === 1) return mesh;
+  const from = mesh.positions;
+  const positions = new Float32Array(from.length);
+  for (let i = 0; i + 2 < from.length; i += 3) {
+    positions[i] = (from[i] as number) * scale + x;
+    positions[i + 1] = (from[i + 1] as number) * scale + y;
+    positions[i + 2] = (from[i + 2] as number) * scale + z;
+  }
+  return { ...mesh, positions };
+}
+
+/** `meshes` as one, in order, each member's indices moved past the vertices before it. */
+export function concatMeshes(meshes: readonly MeshData[]): MeshData {
+  const only = meshes[0];
+  if (meshes.length === 1 && only !== undefined) return only;
+  let vertices = 0;
+  let indexCount = 0;
+  for (const mesh of meshes) {
+    vertices += mesh.positions.length / 3;
+    indexCount += mesh.indices.length;
+  }
+  const out: MeshData = {
+    positions: new Float32Array(vertices * 3),
+    normals: new Float32Array(vertices * 3),
+    colors: new Float32Array(vertices * 3),
+    emissive: new Float32Array(vertices),
+    indices: new Uint32Array(indexCount),
+  };
+  const optional = out as unknown as Record<string, Float32Array | undefined>;
+  for (const [key, width] of OPTIONAL) {
+    if (meshes.some((mesh) => mesh[key] !== undefined)) {
+      optional[key] = new Float32Array(vertices * width);
+    }
+  }
+  let vertex = 0;
+  let index = 0;
+  for (const mesh of meshes) {
+    const count = mesh.positions.length / 3;
+    out.positions.set(mesh.positions, vertex * 3);
+    out.normals.set(mesh.normals, vertex * 3);
+    out.colors.set(mesh.colors, vertex * 3);
+    out.emissive.set(mesh.emissive, vertex);
+    for (const [key, width] of OPTIONAL) {
+      const target = optional[key];
+      if (target === undefined) continue;
+      const source = mesh[key];
+      if (source !== undefined) {
+        target.set(source, vertex * width);
+        continue;
+      }
+      const fill = ABSENT_ATTRIBUTE[key] ?? [];
+      for (let v = 0; v < count; v++) {
+        for (let c = 0; c < width; c++) target[(vertex + v) * width + c] = fill[c] ?? 0;
+      }
+    }
+    const from = mesh.indices;
+    for (let i = 0; i < from.length; i++) out.indices[index + i] = (from[i] as number) + vertex;
+    vertex += count;
+    index += from.length;
+  }
+  return out;
+}

package/src/index.ts

@@ -50,6 +50,17 @@ export {
 } from './core/timeCurve.ts';
 export type { TimeCurve, TimeCurveKind, TimeCurveOptions } from './core/timeCurve.ts';
 export { CinematicPlayer } from './cinematic/player.ts';
+export {
+  createCameraPath,
+  createCameraPathSample,
+  sampleCameraPath,
+} from './cinematic/cameraPath.ts';
+export type {
+  CameraPath,
+  CameraPathKey,
+  CameraPathOptions,
+  CameraPathSample,
+} from './cinematic/cameraPath.ts';
 export { defineCinematic, validateCinematic } from './cinematic/script.ts';
 export type {
   CameraKeyframe,
@@ -65,6 +76,13 @@ export {
   moonIllumination,
 } from './environment/celestialClock.ts';
 export type { CelestialSite, CelestialState } from './environment/celestialClock.ts';
+export {
+  createDaylightPalette,
+  createDaylightState,
+  easeExposure,
+  resolveDaylight,
+} from './environment/daylight.ts';
+export type { DaylightKey, DaylightPalette, DaylightState } from './environment/daylight.ts';
 
 export {
   TAU,
@@ -219,6 +237,7 @@ export { createRenderer } from './render/backend/createRenderer.ts';
 export type {
   CreatedRenderer,
   CreateRendererOptions,
+  QualityForBackend,
   RenderPipeline,
 } from './render/backend/createRenderer.ts';
 /*
@@ -361,6 +380,8 @@ export type {
   GlobalFieldCascade,
   GlobalFieldInstance,
 } from './render/gi/globalField.ts';
+export { FIELD_FADE_SEC, LightField } from './render/driftLight/lightField.ts';
+export type { LightFieldOptions, LightFieldSource } from './render/driftLight/lightField.ts';
 export {
   GI_SCREEN_MARCH,
   SCREEN_TRACE_BIAS_M,
@@ -554,6 +575,8 @@ export type {
   WaterReflectionFilterTaps,
 } from './render/renderQuality.ts';
 export { MAX_POINT_LIGHTS, SURFACE_TEXTURE_UNIT } from './render/lightBudget.ts';
+/* The width a light buffer can usefully be with `clusteredLights` on; `createPointLightBuffer`. */
+export { MAX_CLUSTERED_LIGHTS } from './render/clusteredLights.ts';
 export { SurfaceTexture } from './render/surfaceTexture.ts';
 export type { SurfaceMaterial, SurfaceTextureOptions } from './render/surfaceTexture.ts';
 export { DEFAULT_GOVERNOR_LIMITS, ResolutionGovernor } from './render/resolutionGovernor.ts';
@@ -573,6 +596,8 @@ export {
   selectPointLights,
 } from './render/pointLightSelection.ts';
 export type { PointLightBuffer, PointLightSource } from './render/pointLightSelection.ts';
+export { createFlame, flameFrequencyHz, updateFlame } from './render/flameLight.ts';
+export type { Flame, FlameOptions } from './render/flameLight.ts';
 export { computeLightMatrix } from './render/lightMatrix.ts';
 export { PlumeRenderer } from './render/plumeRenderer.ts';
 export { createEnvironment } from './render/backend/webgl2/renderer.ts';
@@ -622,6 +647,7 @@ export { SMOKE_FRAG } from './render/shaders/smoke.ts';
 export { WaterRenderer } from './render/waterRenderer.ts';
 export type { WaterBody, WaterBounds, WaterSettings } from './render/waterRenderer.ts';
 export { MeshBuilder } from './geometry/meshBuilder.ts';
+export { concatMeshes, placeMesh } from './geometry/meshConcat.ts';
 /* A tangent frame, which every map in the material track reads. */
 export { generateTangents } from './geometry/tangents.ts';
 export type { MeshBuildOptions } from './geometry/meshBuilder.ts';
@@ -941,6 +967,12 @@ export {
    * and draw with that one number.
    */
   deviceSnappedCellSize,
+  /*
+   * How many lit cells one text object draws before the rest of its string is cut. Exported so a
+   * caller laying out a runtime string, a readout that grows, can break it before the engine does:
+   * the cut is silent by design, since a clipped message beats a frame that does not render.
+   */
+  MAX_CELLS as MAX_TEXT_CELLS,
   textHeightPx,
   textWidthPx,
 } from './render/textLayout.ts';

package/src/render/backend/createRenderer.ts

@@ -49,6 +49,20 @@ export function pipelineRefusal(
 }
 
 /** Everything about selection a caller may want to decide instead of inherit. */
+/**
+ * The quality to build with, or a function of the backend `createRenderer` chose.
+ *
+ * **A function is how an option only one backend has is asked of that backend alone.** Traced
+ * indirect light and reconstruction are WebGPU's, and WebGL2 refuses either in words when handed
+ * one: right for a consumer who asked for it there, and noise for one who wanted it wherever it
+ * runs, since every device that fell back printed a refusal. Called once for the backend that
+ * draws, and once more for WebGPU's timing request where WebGPU is tried. What would make it wrong
+ * is a consumer needing to know *why* the backend fell back before choosing, which `reason` on the
+ * result says after the fact and nothing says before.
+ */
+export type QualityForBackend =
+  RenderQualityOptions | ((backend: RenderBackend) => RenderQualityOptions);
+
 export interface CreateRendererOptions {
   /**
    * Whether to try WebGPU at all. **Defaults to true**: WebGPU is the backend this engine is
@@ -234,9 +248,11 @@ function presentOnFirstFrame(renderer: RendererApi, splash: MountedSplash): void
  */
 export async function createRenderer(
   canvas: HTMLCanvasElement,
-  quality: RenderQualityOptions = {},
+  quality: QualityForBackend = {},
   options: CreateRendererOptions = {},
 ): Promise<CreatedRenderer> {
+  const qualityFor = (backend: RenderBackend): RenderQualityOptions =>
+    typeof quality === 'function' ? quality(backend) : quality;
   const search = options.search ?? globalThis.location?.search ?? '';
 
   /*
@@ -317,7 +333,7 @@ export async function createRenderer(
   const choice = await selectBackend(
     search,
     options.preferWebGpu ?? true,
-    quality.gpuTiming ?? false,
+    (options.preferWebGpu ?? true) ? (qualityFor('webgpu').gpuTiming ?? false) : false,
     options.probeShaders ?? [],
     budgetMs,
   );
@@ -364,7 +380,7 @@ export async function createRenderer(
       if (settled === TIMED_OUT) {
         device.destroy();
         return built({
-          renderer: new Renderer(canvas, quality),
+          renderer: new Renderer(canvas, qualityFor('webgl2')),
           backend: 'webgl2',
           reason: `WebGPU stalled while ${stage}, fell back after ${budgetMs} ms`,
         });
@@ -385,7 +401,7 @@ export async function createRenderer(
          */
         renderer: new WebGPURenderer(
           surface,
-          resolveRenderQuality(quality),
+          resolveRenderQuality(qualityFor('webgpu')),
           /* The adapter's own words, so the capability clamp has a part number to
              recognise rather than the literal string `WebGPU`. */
           choice.rendererName ?? undefined,
@@ -397,7 +413,7 @@ export async function createRenderer(
       choice.device.destroy();
       const detail = error instanceof Error ? error.message : String(error);
       return built({
-        renderer: new Renderer(canvas, quality),
+        renderer: new Renderer(canvas, qualityFor('webgl2')),
         backend: 'webgl2',
         reason: `WebGPU surface failed, fell back: ${detail}`,
       });
@@ -425,7 +441,7 @@ export async function createRenderer(
     console.warn(`[driftengine] WebGPU was asked for and is not being used: ${choice.reason}`);
   }
   return built({
-    renderer: new Renderer(canvas, quality),
+    renderer: new Renderer(canvas, qualityFor('webgl2')),
     backend: 'webgl2',
     reason: choice.reason,
   });