@driftengine/texture 4.0.0

package/src/index.ts

@@ -0,0 +1,175 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * DriftTexture: a texture as a compiled, sampled field rather than an image.
+ *
+ * Every engine in the world treats a texture as a bag of texels. This one treats it as a small
+ * program sampled at `(uv, t, params)` — one object per *material* rather than per channel,
+ * carrying every channel, every level and its own decoder.
+ *
+ * Three consequences fall out of that shape and none of them is available to an image:
+ *
+ * - **Channels compress together**, because they are correlated and compressing them apart throws
+ *   that correlation away.
+ * - **Time is an argument, not a clock**, so an animated texture sampled at simulation time is
+ *   byte-exact under replay — which no other engine's animated texture can claim.
+ * - **The decoder is data walked by one shader**, never a permutation. `ARCHITECTURE.md` measured
+ *   what the other way costs at 196,910 gzipped bytes for a single flag.
+ *
+ * What ships here is the format, the reference decode, the material binding, predictive
+ * residency and the writable overlay. The device interpreter the GPU-driven pipeline samples with
+ * is `@driftengine/core`'s, checked against `decodeCpu` by `scripts/gpu-parity.mjs`.
+ */
+export {
+  CHANNEL_SEMANTICS,
+  isColour,
+  linearToSrgb,
+  needsVarianceMips,
+  normaliseSample,
+  semanticAt,
+  semanticIndex,
+  srgbToLinear,
+} from './semantics.ts';
+export type { ChannelSemantic, ChannelSpec } from './semantics.ts';
+export { reduceNormalMip, toksvigRoughness } from './mipNdf.ts';
+export { createTileIndex, hashTile, internTile, tileSlotCount } from './tileHash.ts';
+export type { TileIndex } from './tileHash.ts';
+export {
+  activationBound,
+  evalNetwork,
+  evalNetworkHalf,
+  halfPrecisionErrorBound,
+  networkWeightCount,
+} from './inference.ts';
+export { HALF_MAX, fromHalfBits, halfWeights, roundHalf, toHalfBits } from './half.ts';
+/*
+ * The operators a small transformer is built from, as references the device kernels are held to:
+ * the second half of the one inference runtime, beside the perceptron's evaluation above.
+ */
+export { addBias, erf, gelu, layerNorm, matmul, softmax } from './tensor/linear.ts';
+export { attention } from './tensor/attention.ts';
+export { resize } from './tensor/resize.ts';
+export { conv2d, convTranspose2d, maxPool2d, patchEmbed } from './tensor/spatial.ts';
+export {
+  createGraphEvaluator,
+  graphForDevice,
+  graphFromStored,
+  graphShapes,
+  validateGraph,
+} from './tensor/graph.ts';
+export { CONSTANT_PREFIX, graphFromWeights } from './tensor/architecture.ts';
+export type { Architecture, GraphBuilder, WeightSource, Weights } from './tensor/architecture.ts';
+export type {
+  GraphEvaluator,
+  GraphNode,
+  GraphTensor,
+  GraphValue,
+  NetworkGraph,
+  StoredGraph,
+} from './tensor/graph.ts';
+export { OPERATORS } from './tensor/operators.ts';
+export type { AttributeValue, Attributes, Operator } from './tensor/operators.ts';
+export type { NetworkShape } from './inference.ts';
+export { flipbookFrame, latentLerpWeights } from './timeNodes.ts';
+export type { LerpWeights } from './timeNodes.ts';
+export {
+  ADDRESS_MODE,
+  ADDRESS_MODE_COUNT,
+  DECODE_OP,
+  MAX_REGISTERS,
+  NODE_STRIDE,
+  addDecodeNode,
+  createDecodeGraph,
+  decodeDecodeGraph,
+  encodeDecodeGraph,
+  graphRegisterCount,
+  nodeA,
+  nodeB,
+  nodeOp,
+  nodeOut,
+  validateDecodeGraph,
+} from './decodeGraph.ts';
+export type { DecodeGraph, DecodeOp } from './decodeGraph.ts';
+export { REMAP_SEMANTICS, createDecodeRegisters, decodeCpu } from './decodeCpu.ts';
+export type { DecodeResources, LatentImage, LatentLevel } from './decodeCpu.ts';
+export { progressiveOrder, usableAt } from './progressive.ts';
+export { arrayDescriptor, assignLayer, createMaterialArray, layerOf } from './materialArray.ts';
+export type { MaterialArray } from './materialArray.ts';
+
+/*
+ * Predictive residency: the half that needs the simulation's save and restore rather than the
+ * renderer. See `residency/predict.ts` for why looking ahead is available here and nowhere else.
+ */
+export { predictViews } from './residency/predict.ts';
+export type { SimulationHandle } from './residency/predict.ts';
+export {
+  TILE_ABSENT,
+  TILE_REQUESTED,
+  TILE_RESIDENT,
+  createResidencyTable,
+  evict,
+  leastRecentlyUsed,
+  markRequested,
+  markResident,
+  residentCount,
+  slotFor,
+  tileState,
+  touchTile,
+} from './residency/table.ts';
+export type { ResidencyTable } from './residency/table.ts';
+export { createPrefetchQueue, enqueue, queueSize, takeBatch } from './residency/queue.ts';
+export type { PrefetchQueue } from './residency/queue.ts';
+export {
+  acquirePage,
+  beginCacheFrame,
+  createPageCache,
+  decodeMode,
+  ensurePageDecoded,
+  occupiedPages,
+  pageDecoded,
+  pageSlot,
+  releasePage,
+  setDecodeMode,
+  takeEvicted,
+} from './residency/pageCache.ts';
+export type { DecodeMode, PageCache, PageCacheOptions, PageDecode } from './residency/pageCache.ts';
+export {
+  clearMissing,
+  createStreamer,
+  forgetMissing,
+  pumpStreamer,
+  streamerInFlight,
+} from './residency/stream.ts';
+export type { Streamer, StreamerOptions, TileSource } from './residency/stream.ts';
+export {
+  ADDRESS_CLAMP,
+  ADDRESS_WRAP,
+  OVERLAY_CHANNELS,
+  compositeOverlay,
+  createOverlay,
+  overlayTileCount,
+  overlayTiles,
+  sampleOverlay,
+  writeOverlay,
+  writtenMaskAt,
+} from './overlay/sparse.ts';
+export type { Overlay, OverlayOptions, OverlayTile } from './overlay/sparse.ts';
+export {
+  JOURNAL_ENTRY_BYTES,
+  JOURNAL_MAGIC,
+  JOURNAL_VERSION,
+  applyOverlayJournal,
+  clearOverlay,
+  createOverlayJournal,
+  decodeOverlayJournal,
+  emptyLike,
+  encodeOverlayJournal,
+  journalLength,
+  recordOverlayWrite,
+  rewindOverlay,
+  truncateJournalFrom,
+} from './overlay/journal.ts';
+export type { OverlayJournal } from './overlay/journal.ts';
+export { runPrediction } from './residency/predictor.ts';
+export { LEVEL_MARGIN, latentTileGrid, tilesForView } from './residency/viewTiles.ts';
+export type { InstanceTileInfo, MaterialTileGrid } from './residency/viewTiles.ts';
+export type { Predictor } from './residency/predictor.ts';

package/src/inference.ts

@@ -0,0 +1,278 @@
+/**
+ * A small network evaluator, and the only one this engine has.
+ *
+ * **Three things use it**: a DriftTexture's decode, reconstruction's refinement tier, and capture's
+ * reconstruction. That is the argument for building it carefully and once — a second inference path
+ * is a second set of numerical conventions to keep in step, and the first symptom of them drifting
+ * is a picture that is slightly wrong everywhere.
+ *
+ * **The constraint that shapes it: WebGPU exposes no hardware matrix units.** The desktop graphics
+ * interfaces reach them through cooperative vectors and the published neural-texture work depends
+ * on that. So the network here has to be small enough that ordinary vector arithmetic suffices,
+ * and its size is decided by measurement against a frame budget rather than by copying an
+ * architecture that assumed hardware this platform does not have.
+ *
+ * **The activation applies to hidden layers and not to the output.** Applying it to the output
+ * clamps every channel into the activation's range, which produces a washed-out picture that a
+ * training loss will not reveal — the network simply learns around it and infers badly.
+ */
+import { fromHalfBits, roundHalf } from './half.ts';
+
+export interface NetworkShape {
+  readonly inputs: number;
+  readonly hidden: readonly number[];
+  readonly outputs: number;
+}
+
+/** How many weights and biases a shape needs, laid out layer by layer. */
+export function networkWeightCount(shape: NetworkShape): number {
+  let total = 0;
+  let previous = shape.inputs;
+  for (const width of shape.hidden) {
+    total += previous * width + width;
+    previous = width;
+  }
+  return total + previous * shape.outputs + shape.outputs;
+}
+
+/** Rectified linear, which is what the generated shader will use too. */
+function activate(value: number): number {
+  return value > 0 ? value : 0;
+}
+
+/**
+ * Evaluate the network, writing `shape.outputs` values into `out`.
+ *
+ * Weights are read in layer order: for each layer, the weight matrix row-major by output, then the
+ * biases. `scratch` must hold at least twice the widest layer and is reused across calls so this
+ * allocates nothing.
+ */
+export function evalNetwork(
+  shape: NetworkShape,
+  weights: Float32Array,
+  input: Float32Array,
+  out: Float32Array,
+  scratch: Float32Array,
+): void {
+  const widest = Math.max(shape.inputs, shape.outputs, ...shape.hidden, 1);
+  let current = scratch.subarray(0, widest);
+  let next = scratch.subarray(widest, widest * 2);
+  for (let i = 0; i < shape.inputs; i += 1) current[i] = input[i] as number;
+
+  let at = 0;
+  let previous = shape.inputs;
+  for (const width of shape.hidden) {
+    for (let o = 0; o < width; o += 1) {
+      let sum = 0;
+      for (let i = 0; i < previous; i += 1) {
+        sum += (current[i] as number) * (weights[at + o * previous + i] as number);
+      }
+      next[o] = activate(sum + (weights[at + width * previous + o] as number));
+    }
+    at += previous * width + width;
+    previous = width;
+    const swap = current;
+    current = next;
+    next = swap;
+  }
+
+  for (let o = 0; o < shape.outputs; o += 1) {
+    let sum = 0;
+    for (let i = 0; i < previous; i += 1) {
+      sum += (current[i] as number) * (weights[at + o * previous + i] as number);
+    }
+    /* No activation here. See the header. */
+    out[o] = sum + (weights[at + shape.outputs * previous + o] as number);
+  }
+}
+
+/*
+ * The most one rounding can move a value of this magnitude: half a unit in the last place, which is
+ * 2^-11 of the value for a normal half-precision number and 2^-25 below them. Single precision's
+ * own rounding, which the reference and the device do too, is the same argument at 2^-24.
+ */
+function halfRounding(magnitude: number): number {
+  return Math.max(magnitude * 2 ** -11, 2 ** -25);
+}
+
+function singleRounding(magnitude: number): number {
+  return Math.max(magnitude * 2 ** -24, 2 ** -150);
+}
+
+/**
+ * How far the half-precision evaluation of this network, at this input, can sit from the
+ * single-precision one.
+ *
+ * **A bound per network rather than one tolerance for all**, because a sampled tolerance is a claim
+ * about the corpus that sampled it — 2,400 networks put the worst relative error at 0.00213, the
+ * device's own corpus reached 0.0039, and 40,000 reached 0.0066. This carries the error instead:
+ * the weights' and the input's own rounding exactly, then half a unit in the last place for every
+ * product, every partial sum and the bias, through each layer — a rectifier moves no error, since
+ * it is one-Lipschitz. **It holds whichever form a device computes**: every operation rounded, or
+ * each multiply-add contracted into a single rounding, which WGSL permits and this project's
+ * development machine does. It assumes no value overflows, which `activationBound` is for.
+ */
+export function halfPrecisionErrorBound(
+  shape: NetworkShape,
+  weights: Float32Array,
+  input: Float32Array,
+): number {
+  let value = Array.from({ length: shape.inputs }, (_, i) => input[i] as number);
+  let error = value.map((x) => Math.abs(roundHalf(x) - x) + singleRounding(Math.abs(x)));
+  let worst = 0;
+  let at = 0;
+  let previous = shape.inputs;
+  const layers = shape.hidden.length + 1;
+  for (let layer = 0; layer < layers; layer += 1) {
+    const width = layer < shape.hidden.length ? (shape.hidden[layer] as number) : shape.outputs;
+    const hidden = layer < shape.hidden.length;
+    const nextValue: number[] = [];
+    const nextError: number[] = [];
+    for (let o = 0; o < width; o += 1) {
+      let exact = 0;
+      let carried = 0;
+      let magnitude = 0;
+      let rounding = 0;
+      for (let i = 0; i < previous; i += 1) {
+        const weight = weights[at + o * previous + i] as number;
+        const drift = Math.abs(roundHalf(weight) - weight);
+        const x = value[i] as number;
+        const e = error[i] as number;
+        exact += x * weight;
+        /* |xh·wh − x·w| ≤ |xh − x|·|wh| + |x|·|wh − w|. */
+        carried += e * (Math.abs(weight) + drift) + Math.abs(x) * drift;
+        const product = (Math.abs(x) + e) * (Math.abs(weight) + drift);
+        magnitude += product + rounding;
+        rounding +=
+          halfRounding(product) +
+          halfRounding(magnitude) +
+          singleRounding(product) +
+          singleRounding(magnitude);
+      }
+      const bias = weights[at + width * previous + o] as number;
+      const biasDrift = Math.abs(roundHalf(bias) - bias);
+      exact += bias;
+      carried += biasDrift;
+      magnitude += Math.abs(bias) + biasDrift + rounding;
+      rounding += halfRounding(magnitude) + singleRounding(magnitude);
+      const total = carried + rounding;
+      if (hidden) {
+        nextValue.push(Math.max(0, exact));
+        nextError.push(total);
+      } else {
+        worst = Math.max(worst, total);
+      }
+    }
+    at += previous * width + width;
+    previous = width;
+    value = nextValue;
+    error = nextError;
+  }
+  return worst;
+}
+
+/**
+ * Evaluate the network as a device with `enable f16` would, writing `shape.outputs` values into
+ * `out`.
+ *
+ * **Every multiply and every add is rounded**, because that is what a sixteen-bit adder does, and
+ * the arithmetic is in doubles so the rounding is the only approximation. The order is the
+ * device's: the weighted inputs summed in index order, then the bias, then the rectifier —
+ * `render/shaders/network.wgsl.ts` in `@driftengine/core` is written to match it.
+ *
+ * `weights` are half-precision bits, as `halfWeights` produces and an `NNET` chunk stores. Inputs
+ * are rounded to half precision on the way in. `scratch` holds at least twice the widest layer.
+ */
+export function evalNetworkHalf(
+  shape: NetworkShape,
+  weights: Uint16Array,
+  input: Float32Array,
+  out: Float32Array,
+  scratch: Float64Array,
+  contract = false,
+): void {
+  const widest = Math.max(shape.inputs, shape.outputs, ...shape.hidden, 1);
+  let current = scratch.subarray(0, widest);
+  let next = scratch.subarray(widest, widest * 2);
+  for (let i = 0; i < shape.inputs; i += 1) current[i] = roundHalf(input[i] as number);
+
+  let at = 0;
+  let previous = shape.inputs;
+  const layers = shape.hidden.length + 1;
+  for (let layer = 0; layer < layers; layer += 1) {
+    const width = layer < shape.hidden.length ? (shape.hidden[layer] as number) : shape.outputs;
+    const hidden = layer < shape.hidden.length;
+    for (let o = 0; o < width; o += 1) {
+      let sum = 0;
+      for (let i = 0; i < previous; i += 1) {
+        const product =
+          (current[i] as number) * fromHalfBits(weights[at + o * previous + i] as number);
+        sum = contract ? roundHalf(sum + product) : roundHalf(sum + roundHalf(product));
+      }
+      sum = roundHalf(sum + fromHalfBits(weights[at + width * previous + o] as number));
+      const value = hidden ? (sum > 0 ? sum : 0) : sum;
+      if (hidden) next[o] = value;
+      else out[o] = value;
+    }
+    at += previous * width + width;
+    previous = width;
+    const swap = current;
+    current = next;
+    next = swap;
+  }
+}
+
+/**
+ * The largest magnitude any product, partial sum or output of the network can reach over the given
+ * input box.
+ *
+ * **What a consumer asks before it chooses half precision.** Past 65,504 the format has no finite
+ * value, and a partial sum can pass that on its way to a total that does not — so this bounds each
+ * neuron by its bias plus the sum of every weight times the largest magnitude its input can take,
+ * which covers every prefix of the sum at once. Intervals are carried through the layers, and a
+ * rectifier clips them, which is what keeps the bound from growing without cause.
+ */
+export function activationBound(
+  shape: NetworkShape,
+  weights: Float32Array,
+  low: Float32Array,
+  high: Float32Array,
+): number {
+  let lower = Array.from({ length: shape.inputs }, (_, i) => low[i] as number);
+  let upper = Array.from({ length: shape.inputs }, (_, i) => high[i] as number);
+  let bound = 0;
+  for (let i = 0; i < shape.inputs; i += 1) {
+    bound = Math.max(bound, Math.abs(lower[i] as number), Math.abs(upper[i] as number));
+  }
+  let at = 0;
+  let previous = shape.inputs;
+  const layers = shape.hidden.length + 1;
+  for (let layer = 0; layer < layers; layer += 1) {
+    const width = layer < shape.hidden.length ? (shape.hidden[layer] as number) : shape.outputs;
+    const hidden = layer < shape.hidden.length;
+    const nextLower: number[] = [];
+    const nextUpper: number[] = [];
+    for (let o = 0; o < width; o += 1) {
+      const bias = weights[at + width * previous + o] as number;
+      let magnitude = Math.abs(bias);
+      let min = bias;
+      let max = bias;
+      for (let i = 0; i < previous; i += 1) {
+        const weight = weights[at + o * previous + i] as number;
+        const a = weight * (lower[i] as number);
+        const b = weight * (upper[i] as number);
+        min += Math.min(a, b);
+        max += Math.max(a, b);
+        magnitude += Math.max(Math.abs(a), Math.abs(b));
+      }
+      bound = Math.max(bound, magnitude);
+      nextLower.push(hidden ? Math.max(0, min) : min);
+      nextUpper.push(hidden ? Math.max(0, max) : max);
+    }
+    at += previous * width + width;
+    previous = width;
+    lower = nextLower;
+    upper = nextUpper;
+  }
+  return bound;
+}

package/src/materialArray.ts

@@ -0,0 +1,67 @@
+/**
+ * Materials as slices of a few texture arrays, which is what WebGPU can bind.
+ *
+ * **This is the binding design, and it is why this package lands in the same wave as the
+ * GPU-driven pipeline rather than later.** WebGPU has no bindless resource access, which is the
+ * usual way a GPU-driven renderer reaches a thousand materials from one indirect draw. A thousand
+ * materials as six thousand independent textures is unreachable. A thousand materials as a
+ * thousand latent slices in a handful of arrays, indexed by a material identifier read from a
+ * storage buffer, is ordinary.
+ *
+ * **Identical content shares a layer.** The tile index already hashes by content, so two materials
+ * whose latents are the same occupy one layer — which is the deduplication paying for itself a
+ * second time, in binding slots rather than in bytes.
+ */
+export interface MaterialArray {
+  /** Layer per material identifier. */
+  layerOf: Map<number, number>;
+  /** Which content hash each layer holds, so identical latents share one. */
+  layerByHash: Map<string, number>;
+  layerCapacity: number;
+  tileSize: number;
+  used: number;
+}
+
+export function createMaterialArray(layerCapacity: number, tileSize: number): MaterialArray {
+  return {
+    layerOf: new Map(),
+    layerByHash: new Map(),
+    layerCapacity,
+    tileSize,
+    used: 0,
+  };
+}
+
+/**
+ * Give this material a layer. Returns it, or -1 when the array is full.
+ *
+ * **Full reports failure rather than evicting.** An eviction here would silently repoint a
+ * material that is still being drawn, which is a texture swap nobody asked for in the middle of a
+ * frame; a caller that runs out needs to know.
+ */
+export function assignLayer(array: MaterialArray, materialId: number, contentHash: string): number {
+  const existing = array.layerOf.get(materialId);
+  if (existing !== undefined) return existing;
+
+  const shared = array.layerByHash.get(contentHash);
+  if (shared !== undefined) {
+    array.layerOf.set(materialId, shared);
+    return shared;
+  }
+
+  if (array.used >= array.layerCapacity) return -1;
+  const layer = array.used;
+  array.used += 1;
+  array.layerByHash.set(contentHash, layer);
+  array.layerOf.set(materialId, layer);
+  return layer;
+}
+
+export function layerOf(array: MaterialArray, materialId: number): number {
+  return array.layerOf.get(materialId) ?? -1;
+}
+
+/** What a bind group needs to know: how many layers and how large each is. */
+export function arrayDescriptor(array: MaterialArray): { layers: number; size: number } {
+  return { layers: array.used, size: array.tileSize };
+}

package/src/mipNdf.ts

@@ -0,0 +1,63 @@
+/**
+ * Mip levels for a normal map that get rougher instead of sparkling.
+ *
+ * **Averaging four normals and renormalising throws away how much they disagreed — and that
+ * disagreement *is* roughness at the smaller scale.** What comes back is a distant surface whose
+ * highlight flickers as the camera moves, which reads as an aliasing problem in the renderer and
+ * is a mip chain problem in the asset.
+ *
+ * Every engine can do this and almost none does it by default, because it needs the mip chain to
+ * write roughness as well as normals — which needs the two to live in one object. In a
+ * DriftTexture they do, which is why this is the default here rather than an option.
+ *
+ * **The reduction adds variance and never removes it.** A surface already rough at the finer level
+ * cannot become smoother by being viewed from further away.
+ */
+
+/**
+ * How much roughness a shortened average normal implies.
+ *
+ * The averaged normal's length falls as the normals it averaged disagree, so `1 - length` is a
+ * direct measure of the variance lost to averaging. Added in variance rather than in roughness,
+ * because variances of independent sources add and roughnesses do not.
+ */
+export function toksvigRoughness(normalLength: number, roughness: number): number {
+  const length = Math.min(1, Math.max(0, normalLength));
+  const added = 1 - length;
+  return Math.sqrt(Math.min(1, roughness * roughness + added));
+}
+
+/**
+ * Reduce a block of normals to one, writing both the direction and the roughness it implies.
+ *
+ * `src` holds `width * height` normals as xyz triples, already unbiased into -1..1.
+ */
+export function reduceNormalMip(
+  src: Float32Array,
+  width: number,
+  height: number,
+  outNormal: Float32Array,
+  outRoughness: Float32Array,
+  baseRoughness = 0,
+): void {
+  let x = 0;
+  let y = 0;
+  let z = 0;
+  const count = width * height;
+  for (let i = 0; i < count; i += 1) {
+    x += src[i * 3] as number;
+    y += src[i * 3 + 1] as number;
+    z += src[i * 3 + 2] as number;
+  }
+  x /= count;
+  y /= count;
+  z /= count;
+
+  /* The length before normalising is the whole signal. Normalising first discards it. */
+  const length = Math.hypot(x, y, z);
+  const k = length > 0 ? 1 / length : 0;
+  outNormal[0] = x * k;
+  outNormal[1] = y * k;
+  outNormal[2] = z * k;
+  outRoughness[0] = toksvigRoughness(length, baseRoughness);
+}