@driftengine/core 4.8.3 → 4.8.4

package/src/render/surfaceModel.ts

@@ -0,0 +1,274 @@
+/**
+ * A material's shading model: how its surface answers light, when the standard model is not what
+ * it is made of — brushed metal, hair, skin, an eye.
+ *
+ * **A frozen descriptor, made once by a factory, carrying a kind and that model's numbers.** The
+ * standard model is `null`, exactly today's shader, and a scene that never names a model compiles
+ * nothing of any of them: each is a pipeline constant of its own (`MODEL_ANISOTROPIC` and the rest
+ * in `shaders/flat/models.ts`), off in every pipeline but the ones a material asks for.
+ *
+ * **Two vectors of numbers a material, and no more.** The lit stage's eight-light build is 254 of
+ * the 256 uniform vectors an Adreno 740 offers, so a model's numbers are packed into
+ * `uModelParams[2]` — the last component of the second says whether a model map is bound — and
+ * every model fits. See `packModel` for each layout.
+ *
+ * **The eye's axis is the one number that moves.** It is the eye's forward direction in the world,
+ * which a turning head or a glance changes every frame; the lit stage has no room left for another
+ * varying (sixteen, WebGPU's ceiling), so the renderer turns the descriptor's mesh-local axis by
+ * the draw's model matrix and the eye's joint each draw, with `eyeAxisInWorld`.
+ */
+import type { Vec3 } from '../math/color.ts';
+
+/** Strands of brushed metal, satin or hair-like fibre: a highlight stretched across them. */
+export interface AnisotropicModel {
+  readonly kind: 'anisotropic';
+  /** 0 to 1: how far the highlight is stretched along the tangent. */
+  readonly strength: number;
+  /** Radians, turning the stretch's direction from the tangent toward the bitangent. */
+  readonly rotation: number;
+}
+
+/**
+ * Hair: three lobes along the strand, which is the mesh's tangent, running from root to tip
+ * (`hairLobes.ts`). A model map's green turns each strand's tilt by up to half of it either way and
+ * its blue is occlusion.
+ */
+export interface HairModel {
+  readonly kind: 'hair';
+  /**
+   * Radians the cuticle's scales tilt the strand's surface: positive moves the white highlight
+   * toward the root and the coloured one toward the tip. A card whose tangent runs tip to root
+   * takes it negative.
+   */
+  readonly shift: number;
+  /** 0 to 1: the light scattered through many strands, tinted by their colour. */
+  readonly scatter: number;
+  /** How strongly light from behind glows through: the transmitted lobe. */
+  readonly backlit: number;
+}
+
+/** Skin: light scattered beneath the surface, reddening its terminator and its thin parts. */
+export interface SkinModel {
+  readonly kind: 'skin';
+  /** The colour light keeps travelling beneath the surface — the mean free path, as a colour. */
+  readonly scatterColor: Vec3;
+  /** Metres: how far light travels beneath it before it leaves. */
+  readonly radius: number;
+  /** 0 to 1: how much a light behind a thin part shows through it. */
+  readonly transmission: number;
+  /** Which of up to eight profiles the screen-space scattering blurs this skin by. */
+  readonly profile: number;
+}
+
+/** An eye: an iris seen through a cornea, which refracts it, under a mirror-smooth highlight. */
+export interface EyeModel {
+  readonly kind: 'eye';
+  /** The iris's radius, in texture coordinates from the centre of the eye's map. */
+  readonly irisRadius: number;
+  /** Metres from the cornea down to the iris. */
+  readonly irisDepth: number;
+  /** The cornea's index of refraction. */
+  readonly ior: number;
+  /** How smooth the cornea's highlight is. */
+  readonly corneaRoughness: number;
+  /** The eye's forward direction, in the mesh's own space at its bind pose. */
+  readonly axis: Vec3;
+  /** The joint the eye turns with, or -1 for an eye placed by its model matrix alone. */
+  readonly joint: number;
+}
+
+/** Every model a material can name, by its `kind`: see `SurfaceMaterial.model`. */
+export type SurfaceModel = AnisotropicModel | HairModel | SkinModel | EyeModel;
+/** A model's name, which also picks its pipeline switch: `SURFACE_MODEL_SWITCH`. */
+export type SurfaceModelKind = SurfaceModel['kind'];
+
+/** Every kind, in the order the lit stage declares their switches. */
+export const SURFACE_MODEL_KINDS: readonly SurfaceModelKind[] = [
+  'anisotropic',
+  'hair',
+  'skin',
+  'eye',
+];
+
+/** The lit stage's switch for each kind. */
+export const SURFACE_MODEL_SWITCH: Readonly<Record<SurfaceModelKind, string>> = {
+  anisotropic: 'MODEL_ANISOTROPIC',
+  hair: 'MODEL_HAIR',
+  skin: 'MODEL_SKIN',
+  eye: 'MODEL_EYE',
+};
+
+/** Floats a material's model takes: `uModelParams[2]`. */
+export const MODEL_PARAM_FLOATS = 8;
+
+function check(model: string, name: string, value: number, low: number, high: number): number {
+  if (!Number.isFinite(value) || value < low || value > high) {
+    throw new Error(`${model}: ${name} must be from ${low} to ${high}, not ${String(value)}`);
+  }
+  return value;
+}
+
+function unit(model: string, name: string, v: Vec3): Vec3 {
+  const length = Math.hypot(v[0], v[1], v[2]);
+  if (!(length > 1e-6))
+    throw new Error(`${model}: ${name} must be a direction, not [${v.join(', ')}]`);
+  return [v[0] / length, v[1] / length, v[2] / length];
+}
+
+/** Brushed metal and the like, after glTF's `KHR_materials_anisotropy`: a strength and a turn. */
+export function anisotropicModel(
+  options: { strength?: number; rotation?: number } = {},
+): AnisotropicModel {
+  return Object.freeze({
+    kind: 'anisotropic',
+    strength: check('anisotropicModel', 'strength', options.strength ?? 1, 0, 1),
+    rotation: check(
+      'anisotropicModel',
+      'rotation',
+      options.rotation ?? 0,
+      -2 * Math.PI,
+      2 * Math.PI,
+    ),
+  });
+}
+
+/** Hair, along the mesh's tangent from root to tip. A tilt of 3°, within the 2.5° to 5° measured. */
+export function hairModel(
+  options: { shift?: number; scatter?: number; backlit?: number } = {},
+): HairModel {
+  return Object.freeze({
+    kind: 'hair',
+    shift: check('hairModel', 'shift', options.shift ?? (3 * Math.PI) / 180, -0.5, 0.5),
+    scatter: check('hairModel', 'scatter', options.scatter ?? 0.7, 0, 1),
+    backlit: check('hairModel', 'backlit', options.backlit ?? 1, 0, 4),
+  });
+}
+
+/** Skin. The defaults are a fair skin's: a red mean free path a little over a centimetre long. */
+export function skinModel(
+  options: { scatterColor?: Vec3; radius?: number; transmission?: number; profile?: number } = {},
+): SkinModel {
+  const color = options.scatterColor ?? [0.85, 0.35, 0.22];
+  for (let c = 0; c < 3; c++) check('skinModel', 'scatterColor', color[c] as number, 0, 1);
+  const profile = check('skinModel', 'profile', options.profile ?? 0, 0, 7);
+  if (!Number.isInteger(profile))
+    throw new Error(`skinModel: profile must be a whole number, not ${profile}`);
+  return Object.freeze({
+    kind: 'skin',
+    scatterColor: Object.freeze([color[0], color[1], color[2]]) as unknown as Vec3,
+    radius: check('skinModel', 'radius', options.radius ?? 0.012, 0, 0.1),
+    transmission: check('skinModel', 'transmission', options.transmission ?? 0.5, 0, 1),
+    profile,
+  });
+}
+
+/** An eye. The defaults are a human eye's, its axis along the mesh's +Z. */
+export function eyeModel(
+  options: {
+    irisRadius?: number;
+    irisDepth?: number;
+    ior?: number;
+    corneaRoughness?: number;
+    axis?: Vec3;
+    joint?: number;
+  } = {},
+): EyeModel {
+  const joint = options.joint ?? -1;
+  if (!Number.isInteger(joint) || joint < -1) {
+    throw new Error(`eyeModel: joint must be a joint index or -1, not ${String(joint)}`);
+  }
+  return Object.freeze({
+    kind: 'eye',
+    irisRadius: check('eyeModel', 'irisRadius', options.irisRadius ?? 0.15, 0.001, 0.5),
+    irisDepth: check('eyeModel', 'irisDepth', options.irisDepth ?? 0.003, 0, 0.02),
+    ior: check('eyeModel', 'ior', options.ior ?? 1.336, 1, 2),
+    corneaRoughness: check('eyeModel', 'corneaRoughness', options.corneaRoughness ?? 0.02, 0, 1),
+    axis: Object.freeze(unit('eyeModel', 'axis', options.axis ?? [0, 0, 1])) as unknown as Vec3,
+    joint,
+  });
+}
+
+/**
+ * A model's numbers into `out` — eight floats, `uModelParams[0]` then `[1]` — and whether a model
+ * map is bound into the last. Zeros for the standard model. An eye's axis goes in with the
+ * descriptor's own until the draw turns it: see `eyeAxisInWorld`.
+ *
+ * - anisotropic: strength, cos and sin of the rotation · −, −, −, map
+ * - hair: shift, scatter, backlit, − · −, −, −, map
+ * - skin: the scatter colour, radius · transmission, profile, −, map
+ * - eye: iris radius, iris depth, ior, cornea roughness · the axis, map
+ */
+export function packModel(model: SurfaceModel | null, mapped: boolean, out: Float32Array): void {
+  out.fill(0);
+  if (model === null) return;
+  out[7] = mapped ? 1 : 0;
+  switch (model.kind) {
+    case 'anisotropic':
+      out[0] = model.strength;
+      out[1] = Math.cos(model.rotation);
+      out[2] = Math.sin(model.rotation);
+      return;
+    case 'hair':
+      out[0] = model.shift;
+      out[1] = model.scatter;
+      out[2] = model.backlit;
+      return;
+    case 'skin':
+      out[0] = model.scatterColor[0];
+      out[1] = model.scatterColor[1];
+      out[2] = model.scatterColor[2];
+      out[3] = model.radius;
+      out[4] = model.transmission;
+      out[5] = model.profile;
+      return;
+    case 'eye':
+      out[0] = model.irisRadius;
+      out[1] = model.irisDepth;
+      out[2] = model.ior;
+      out[3] = model.corneaRoughness;
+      out[4] = model.axis[0];
+      out[5] = model.axis[1];
+      out[6] = model.axis[2];
+      return;
+  }
+}
+
+/**
+ * An eye's axis in the world for one draw, into `out[at…at+2]`: the descriptor's mesh-local axis
+ * turned by its joint's palette entry, where it names one and a palette is set, and then by the
+ * draw's model matrix — the turn its vertices take, without the translation. Normalised, because
+ * a palette carries a joint's scale.
+ */
+export function eyeAxisInWorld(
+  model: EyeModel,
+  placement: ArrayLike<number>,
+  palette: ArrayLike<number> | null,
+  out: Float32Array,
+  at: number,
+): void {
+  let [x, y, z] = model.axis;
+  const j = model.joint * 16;
+  if (palette !== null && model.joint >= 0 && j + 16 <= palette.length) {
+    const px =
+      (palette[j] as number) * x + (palette[j + 4] as number) * y + (palette[j + 8] as number) * z;
+    const py =
+      (palette[j + 1] as number) * x +
+      (palette[j + 5] as number) * y +
+      (palette[j + 9] as number) * z;
+    const pz =
+      (palette[j + 2] as number) * x +
+      (palette[j + 6] as number) * y +
+      (palette[j + 10] as number) * z;
+    x = px;
+    y = py;
+    z = pz;
+  }
+  const m = placement;
+  const wx = (m[0] as number) * x + (m[4] as number) * y + (m[8] as number) * z;
+  const wy = (m[1] as number) * x + (m[5] as number) * y + (m[9] as number) * z;
+  const wz = (m[2] as number) * x + (m[6] as number) * y + (m[10] as number) * z;
+  const length = Math.hypot(wx, wy, wz) || 1;
+  out[at] = wx / length;
+  out[at + 1] = wy / length;
+  out[at + 2] = wz / length;
+}

package/src/render/surfaceTexture.ts

@@ -8,9 +8,19 @@
  * array samples exactly as a 2D texture does. A mesh names its layer per vertex (`MeshData.layers`),
  * so a merged block wearing forty facades is one draw.
  */
-import { isSourceList, layerSize, refuseArrayUpdate, sourceSize } from './textureSource.ts';
+import type { SurfaceModel } from './surfaceModel.ts';
+import { layerSize, refuseArrayUpdate, sourceSize } from './textureSource.ts';
+import { compressedLayers, planBlocks, refuseBlockUpdate } from './compressedSource.ts';
+import type {
+  BlockFormat,
+  CompressedTextureFormat,
+  CompressedTextureSource,
+  SurfaceSource,
+} from './compressedSource.ts';
+import { uploadCompressedArray } from './glCompressed.ts';
 import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from './surfaceEffects.ts';
 import type { SurfaceLayerEffect } from './surfaceEffects.ts';
+import type { CutoutMode } from './cutoutDither.ts';
 
 /**
  * How a texture behaves past its edges and between its texels.
@@ -81,8 +91,20 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
    */
   uOffset?: number;
   vOffset?: number;
-  /** Alpha below which a fragment is discarded. See `uAlbedoCutout`. */
+  /** Alpha below which a fragment is discarded. See `uCutout`. */
   cutout?: number;
+  /**
+   * How the cutout's edge is drawn: `'hard'`, the default and every cutout before 4.8.4, or
+   * `'dithered'`, which keeps a pixel by the share of it the texture covers so a strand of hair, a
+   * lash or a fringe of leaves has a soft edge instead of a stair of pixels.
+   *
+   * **The frame decides how a dithered edge is resolved**, because the material cannot know: under a
+   * temporal resolve (TAA or DriftTR) the pattern moves every frame and the resolve averages it;
+   * multisampled, the share goes to the GPU as alpha-to-coverage; with neither, the test is hard,
+   * since a dither nothing averages is grain. A translucent draw tests hard whatever this says. See
+   * `cutoutDither.ts`.
+   */
+  cutoutMode?: CutoutMode;
   /**
    * Whether both faces are seen: glTF's `doubleSided`, what a curtain or a leaf card is. Drawn
    * without culling, and a back face is lit as its front, with the normal turned to the viewer.
@@ -123,6 +145,19 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
    * consumer who wants a bound map twice as bright asks here rather than rebuilding the mesh.
    */
   emissiveScale?: readonly [number, number, number];
+  /**
+   * How the surface answers light, when the standard model is not what it is made of: brushed
+   * metal, hair, skin, an eye — `anisotropicModel`, `hairModel`, `skinModel`, `eyeModel`. Null or
+   * absent is the standard model, exactly as before. **A pipeline of its own**, compiled the first
+   * time a draw asks, so a scene that names no model pays for none. See `surfaceModel.ts`.
+   */
+  model?: SurfaceModel | null;
+  /**
+   * The model's own channels, in the albedo's coordinates and layers; what each channel means is
+   * the model's to say. Absent, each model takes its own neutral. Sampled linear, like any map
+   * that is not a colour.
+   */
+  modelMap?: Texture | null;
 }
 
 export interface SurfaceTextureOptions {
@@ -222,79 +257,45 @@ export class SurfaceTexture {
   readonly layers: number;
   /** 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;
 
   /**
    * One image, or an array of images that must share one size (`layerSize` refuses otherwise).
-   * Uploaded unflipped either way; see the constructor body for why.
+   * Uploaded unflipped either way; see the constructor body for why. Or blocks, uploaded as they are
+   * where `compressed` — the formats this context samples — has theirs; see `compressedSource.ts`.
    */
   constructor(
     gl: WebGL2RenderingContext,
-    source: TexImageSource | readonly TexImageSource[],
+    source: SurfaceSource | readonly SurfaceSource[],
     options: SurfaceTextureOptions = {},
+    compressed: readonly CompressedTextureFormat[] = [],
   ) {
-    const sources: readonly TexImageSource[] = isSourceList(source) ? source : [source];
-    const { width, height } = layerSize(sources);
-    this.layers = sources.length;
+    const listed = (Array.isArray(source) ? source : [source]) as readonly SurfaceSource[];
+    const blocks = compressedLayers(listed);
+    this.srgb = (options.colorSpace ?? 'linear') === 'srgb';
+    /* Refused before anything is allocated, so a refusal leaves no texture behind. */
+    const plan = blocks === null ? null : planBlocks(blocks, this.srgb, compressed);
     const texture = gl.createTexture();
     if (texture === null) throw new Error('SurfaceTexture: createTexture failed');
     this.texture = texture;
-    this.mipmapped = options.mipmap ?? true;
-    this.srgb = (options.colorSpace ?? 'linear') === 'srgb';
-
     const wrap = (options.wrap ?? 'repeat') === 'repeat' ? gl.REPEAT : gl.CLAMP_TO_EDGE;
-
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
-    /*
-     * **Not flipped, and this used to be, which is the bug it is written down for.**
-     *
-     * The flip was here with a comment saying every source is a 2D drawing surface whose Y
-     * runs down from the top-left, so without it "every texture arrives mirrored". That is
-     * true of a canvas and **WebGL ignores `UNPACK_FLIP_Y_WEBGL` entirely for an
-     * `ImageBitmap`**, which carries its own orientation. So the two source types the same
-     * method accepts arrived the opposite way up from each other, and nothing caught it
-     * because every canvas-sourced texture in this repository was symmetric under a vertical
-     * flip: eroded noise, a radial halo, a sleeve blurred to 24 pixels and back. One consumer
-     * painted lettering to a canvas beside a sleeve decoded as a bitmap and the text was
-     * upside down.
-     *
-     * **Made to agree by dropping the flip rather than by extending it**, and the direction
-     * is a deliberate choice about blast radius rather than a coin toss: `drftLoader` builds
-     * every model texture from an `ImageBitmap`, so flipping bitmaps to match canvases would
-     * turn over every painted surface on every loaded model. Dropping it changes only
-     * canvas-sourced textures, and every one of those that exists today is symmetric.
-     *
-     * A caller that was mirroring its own canvas to cancel this must stop.
-     */
-    /* Allocated mutable rather than with texStorage3D, so `update` can hand a one-layer texture a
-       new size, as texImage2D always could. Each layer is then written in place. */
-    gl.texImage3D(
-      gl.TEXTURE_2D_ARRAY,
-      0,
-      this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA,
-      width,
-      height,
-      sources.length,
-      0,
-      gl.RGBA,
-      gl.UNSIGNED_BYTE,
-      null,
-    );
-    for (let layer = 0; layer < sources.length; layer++) {
-      gl.texSubImage3D(
-        gl.TEXTURE_2D_ARRAY,
-        0,
-        0,
-        0,
-        layer,
-        width,
-        height,
-        1,
-        gl.RGBA,
-        gl.UNSIGNED_BYTE,
-        sources[layer] as TexImageSource,
-      );
-    }
 
+    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.mipmapped = (options.mipmap ?? true) && plan.levels > 1;
+      uploadCompressedArray(gl, plan.name, blocks, this.mipmapped ? plan.levels : 1);
+    } else {
+      const sources = listed as readonly TexImageSource[];
+      this.layers = sources.length;
+      this.blockFormat = null;
+      this.mipmapped = options.mipmap ?? true;
+      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
@@ -314,7 +315,7 @@ export class SurfaceTexture {
           : gl.LINEAR,
     );
 
-    if (this.mipmapped) gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
+    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);
 
@@ -345,7 +346,6 @@ export class SurfaceTexture {
     }
   }
 
-  /** Bind the effects table to `unit`, or `fallback` for a texture given none. */
   /** Whether this texture carries an effects table, which the lit program reads only once one exists. */
   get hasEffects(): boolean {
     return this.effectsTable !== null;
@@ -370,6 +370,7 @@ export class SurfaceTexture {
   update(gl: WebGL2RenderingContext, source: TexImageSource): void {
     if (this.texture === null) return;
     refuseArrayUpdate(this.layers);
+    refuseBlockUpdate(this.blockFormat);
     const { width, height } = sourceSize(source);
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
     /* Unflipped, matching the constructor. See it for why, and for what it cost. */
@@ -404,6 +405,65 @@ export class SurfaceTexture {
   }
 }
 
+/** Images into the bound array, level 0 of each layer; the chain, if any, is generated after. */
+function uploadImages(
+  gl: WebGL2RenderingContext,
+  sources: readonly TexImageSource[],
+  srgb: boolean,
+): void {
+  const { width, height } = layerSize(sources);
+  /*
+   * **Not flipped, and this used to be, which is the bug it is written down for.**
+   *
+   * The flip was here with a comment saying every source is a 2D drawing surface whose Y
+   * runs down from the top-left, so without it "every texture arrives mirrored". That is
+   * true of a canvas and **WebGL ignores `UNPACK_FLIP_Y_WEBGL` entirely for an
+   * `ImageBitmap`**, which carries its own orientation. So the two source types the same
+   * method accepts arrived the opposite way up from each other, and nothing caught it
+   * because every canvas-sourced texture in this repository was symmetric under a vertical
+   * flip: eroded noise, a radial halo, a sleeve blurred to 24 pixels and back. One consumer
+   * painted lettering to a canvas beside a sleeve decoded as a bitmap and the text was
+   * upside down.
+   *
+   * **Made to agree by dropping the flip rather than by extending it**, and the direction
+   * is a deliberate choice about blast radius rather than a coin toss: `drftLoader` builds
+   * every model texture from an `ImageBitmap`, so flipping bitmaps to match canvases would
+   * turn over every painted surface on every loaded model. Dropping it changes only
+   * canvas-sourced textures, and every one of those that exists today is symmetric.
+   *
+   * A caller that was mirroring its own canvas to cancel this must stop.
+   */
+  /* Allocated mutable rather than with texStorage3D, so `update` can hand a one-layer texture a
+       new size, as texImage2D always could. Each layer is then written in place. */
+  gl.texImage3D(
+    gl.TEXTURE_2D_ARRAY,
+    0,
+    srgb ? gl.SRGB8_ALPHA8 : gl.RGBA,
+    width,
+    height,
+    sources.length,
+    0,
+    gl.RGBA,
+    gl.UNSIGNED_BYTE,
+    null,
+  );
+  for (let layer = 0; layer < sources.length; layer++) {
+    gl.texSubImage3D(
+      gl.TEXTURE_2D_ARRAY,
+      0,
+      0,
+      0,
+      layer,
+      width,
+      height,
+      1,
+      gl.RGBA,
+      gl.UNSIGNED_BYTE,
+      sources[layer] as TexImageSource,
+    );
+  }
+}
+
 /**
  * Set anisotropic filtering when the driver offers it, and stay silent when it does not.
  *

package/src/render/vertexDefaults.ts

@@ -67,6 +67,13 @@ export const ABSENT_ATTRIBUTE: Readonly<Record<string, readonly number[]>> = {
    */
   joints: [0, 0, 0, 0],
   weights: [1, 0, 0, 0],
+  /**
+   * The second four influences, absent: all zero, so a four-influence mesh drawn through a pipeline
+   * built for eight adds nothing. **Not the first set's trap**: there a zero sum collapses the
+   * vertex, here the first set already sums to one and zero is exactly "no more influences".
+   */
+  joints2: [0, 0, 0, 0],
+  weights2: [0, 0, 0, 0],
   /**
    * The four-lane channel: planted, fully sunlit, opaque, and a reserved lane.
    *

package/dist/math/exact.d.ts

@@ -1,76 +0,0 @@
-/**
- * Transcendentals that give the same bits on every JavaScript engine.
- *
- * **Not more accurate than `Math`, and that is not what they are for.** These are within a couple
- * of units in the last place of correctly rounded, which is about what a platform `sin` gives you.
- * What they are is *reproducible*: ECMAScript declines to specify `sin`, `cos`, `exp`, `acos` and
- * eighteen more, so two engines may differ by an ulp, and an ulp is enough to make two peers running
- * the same simulation disagree — first invisibly, then completely.
- *
- * `scripts/determinism.mjs` is the gate that refuses the unspecified ones inside the simulation set
- * and names the twenty-two. Its header carries the other half of the argument: `+ - * /` are IEEE
- * 754 operations by specification, JavaScript permits no fused-multiply-add contraction, and
- * `Math.sqrt` is required correctly rounded and is *not* on that list. **So everything below uses
- * only those five operations**, which is the whole design: reproducibility by construction rather
- * than by hoping two engines chose the same algorithm.
- *
- * ---
- *
- * ## What is here, and what is deliberately not
- *
- * `exactSin`, `exactCos`, `exactExp`, `exactAcos` and `exactLog`. Five, because five is what the
- * engine and its first consumer actually reach for: the terrain binding's slope angle needs `acos`,
- * a lockstep fixture rotating anything needs `sin` and `cos`, exponential decay needs `exp`, and a
- * detector's box prior is a logit of the patch grid, which needs `log`.
- *
- * **`atan2` is absent.** It is the obvious fifth and nothing here needs one: `shape.ts` sorts by a
- * comparison key computed from two in-plane axes rather than by an angle, and `joints.ts` compares
- * a quaternion component against a half-angle's sine. *Reversed by* a site that genuinely needs a
- * signed angle from two components, at which point it arrives with its own golden vectors.
- *
- * ## Nothing in core imports these
- *
- * Deliberately. `core-only` is the one size figure in this repository that every consumer pays, and
- * a module reachable from `createRenderer` is in it whether anybody calls it or not. These are
- * reached by the script bindings and by consumers who ask for them, so tree-shaking keeps them out
- * of a bundle that does not, which is measured rather than assumed.
- *
- * ## The coefficients
- *
- * The polynomial and rational coefficients are fdlibm's, which is the ancestor of most platform
- * libms and is public domain. They are written as literals: **a literal is the same number on
- * every engine, which is the only property being bought.** Their provenance matters less than their
- * fixity — a coefficient somebody re-derived to one more digit is a different function, and
- * `exact.test.ts`'s golden bit patterns are what would catch that.
- */
-/** `Math.sin`, reproducibly. NaN in, NaN out; an infinity answers NaN, as `Math.sin` does. */
-export declare function exactSin(x: number): number;
-/** `Math.cos`, reproducibly. */
-export declare function exactCos(x: number): number;
-/**
- * `Math.exp`, reproducibly.
- *
- * Reduce by a multiple of ln 2 into [-ln2/2, ln2/2], sum the Taylor series there, and scale by a
- * power of two. **A degree-14 series and not a shorter minimax**, because on that interval the
- * fifteenth term is about 4e-20 — below the precision of a double — so the series is exact to the
- * representation and there is nothing a fitted polynomial would buy.
- */
-export declare function exactExp(x: number): number;
-/**
- * `Math.log`, reproducibly: fdlibm's algorithm, which is also V8's.
- *
- * Take the power of two out as `k` and leave a significand in [√2/2, √2), so that `f = m - 1` is
- * small either side of zero; then log(1 + f) = f - f²/2 + s·(f²/2 + R(s²)) with s = f/(2 + f), and
- * `k·ln 2` added back in two parts so the large part loses nothing. The exponent is read and the
- * significand rescaled through the double's own words — integer operations, not transcendentals.
- */
-export declare function exactLog(x: number): number;
-/**
- * `Math.acos`, reproducibly. Outside [-1, 1] this answers NaN, as `Math.acos` does.
- *
- * Three branches rather than one, and the split at ±0.5 is the reason it is accurate near the ends:
- * `acos` has infinite derivative at ±1, so a polynomial in `x` loses its footing there. Substituting
- * `s = sqrt((1 ∓ x)/2)` moves the awkward point to zero, where a polynomial is comfortable — which
- * is also why `sqrt` being exactly rounded matters here rather than being a convenience.
- */
-export declare function exactAcos(x: number): number;