@driftengine/texture 4.0.0

package/src/overlay/journal.ts

@@ -0,0 +1,218 @@
+/**
+ * A scorch mark is in the input log, so a replay burns the same wall.
+ *
+ * **Runtime-mutable textures normally break replay.** The marks are not part of the simulation and
+ * nothing records them, so a recording plays back a world where the walls are clean — and the
+ * failure has the worst possible shape: nothing goes wrong at the time, everything looks right, and
+ * the recording is wrong forever. Anybody who later debugs from it is debugging a session that did
+ * not happen.
+ *
+ * Here a write is recorded in the same log the input goes into, so replaying a session reproduces
+ * the exact mark in the exact place — and the same mechanism means a rollback un-draws what the
+ * rolled-back frames drew, because rolling back an overlay *is* rebuilding it from the journal up
+ * to the frame you rolled back to. An overlay cannot be snapshotted the way the world is: it is
+ * sparse and unbounded, and a snapshot per frame of something that grows is the cost the sparseness
+ * was for.
+ *
+ * **Applying does not clear, and rewinding does.** A replay that always cleared could not be used
+ * to catch up frame by frame, which is what a live session does. `rewindOverlay` is the one that
+ * puts the world back, and it says so in its name.
+ *
+ * **The journal is truncated on rollback, and forgetting that is the bug.** Re-simulating after a
+ * rollback records its writes again; the frames that did not happen must not still be in the log,
+ * or a replay from the start draws both the mark that happened and the one that was undone.
+ */
+import { createOverlay, writeOverlay, type Overlay } from './sparse.ts';
+
+/** Bytes an entry takes on the wire: two `u32` and four `f32`. */
+export const JOURNAL_ENTRY_BYTES = 24;
+/** `"DOVJ"`, little-endian, as every other record in this package spells its magic. */
+export const JOURNAL_MAGIC = 0x4a564f44;
+export const JOURNAL_VERSION = 1;
+
+export interface OverlayJournal {
+  /** One frame number an entry. */
+  frames: Int32Array;
+  /** One channel index an entry. */
+  channels: Int32Array;
+  /** Four values an entry: u, v, radius, value. */
+  values: Float32Array;
+  count: number;
+}
+
+export function createOverlayJournal(capacity = 256): OverlayJournal {
+  const size = Math.max(1, Math.floor(capacity));
+  return {
+    frames: new Int32Array(size),
+    channels: new Int32Array(size),
+    values: new Float32Array(size * 4),
+    count: 0,
+  };
+}
+
+function grow(journal: OverlayJournal): void {
+  if (journal.count < journal.frames.length) return;
+  const size = journal.frames.length * 2;
+  const frames = new Int32Array(size);
+  const channels = new Int32Array(size);
+  const values = new Float32Array(size * 4);
+  frames.set(journal.frames);
+  channels.set(journal.channels);
+  values.set(journal.values);
+  journal.frames = frames;
+  journal.channels = channels;
+  journal.values = values;
+}
+
+/**
+ * Record a write. Stored as `f32`, which is what makes the encoding round-trip exactly.
+ *
+ * A journal of `f64` written out as `f32` reproduces a *nearly* identical mark, and "nearly" in a
+ * replay is a divergence that appears at the worst moment — the fingerprint that no longer matches
+ * a recording, for a reason nobody would look for in a texture.
+ */
+export function recordOverlayWrite(
+  journal: OverlayJournal,
+  frame: number,
+  u: number,
+  v: number,
+  radius: number,
+  channel: number,
+  value: number,
+): void {
+  grow(journal);
+  const at = journal.count;
+  journal.frames[at] = frame;
+  journal.channels[at] = channel;
+  journal.values[at * 4] = u;
+  journal.values[at * 4 + 1] = v;
+  journal.values[at * 4 + 2] = radius;
+  journal.values[at * 4 + 3] = value;
+  journal.count += 1;
+}
+
+export function journalLength(journal: OverlayJournal): number {
+  return journal.count;
+}
+
+/**
+ * Forget every entry from `frame` onward. What a rollback owes the journal.
+ *
+ * Entries are recorded in frame order, so this is a truncation rather than a filter — and where
+ * they are not, the scan below still removes exactly the right ones.
+ */
+export function truncateJournalFrom(journal: OverlayJournal, frame: number): number {
+  let kept = 0;
+  for (let at = 0; at < journal.count; at += 1) {
+    if ((journal.frames[at] as number) >= frame) continue;
+    if (kept !== at) {
+      journal.frames[kept] = journal.frames[at] as number;
+      journal.channels[kept] = journal.channels[at] as number;
+      for (let c = 0; c < 4; c += 1) {
+        journal.values[kept * 4 + c] = journal.values[at * 4 + c] as number;
+      }
+    }
+    kept += 1;
+  }
+  const dropped = journal.count - kept;
+  journal.count = kept;
+  return dropped;
+}
+
+/** Apply every entry up to and including `upToFrame`, onto whatever the overlay already holds. */
+export function applyOverlayJournal(
+  overlay: Overlay,
+  journal: OverlayJournal,
+  upToFrame: number,
+): number {
+  let applied = 0;
+  for (let at = 0; at < journal.count; at += 1) {
+    if ((journal.frames[at] as number) > upToFrame) continue;
+    writeOverlay(
+      overlay,
+      journal.values[at * 4] as number,
+      journal.values[at * 4 + 1] as number,
+      journal.values[at * 4 + 2] as number,
+      journal.channels[at] as number,
+      journal.values[at * 4 + 3] as number,
+    );
+    applied += 1;
+  }
+  return applied;
+}
+
+/** Throw away every written tile. The overlay keeps its shape and holds nothing. */
+export function clearOverlay(overlay: Overlay): void {
+  overlay.tiles.clear();
+}
+
+/**
+ * Put the overlay back to how it was at `upToFrame`: clear, then replay.
+ *
+ * Rebuilt rather than undone, because a write is not invertible — two marks on one texel leave no
+ * record of what was underneath, and an overlay that tried to undo would need a history per texel,
+ * which is the dense layer the whole design exists to avoid.
+ */
+export function rewindOverlay(
+  overlay: Overlay,
+  journal: OverlayJournal,
+  upToFrame: number,
+): number {
+  clearOverlay(overlay);
+  return applyOverlayJournal(overlay, journal, upToFrame);
+}
+
+/** An overlay with the same shape as `like` and nothing written. What a replay starts from. */
+export function emptyLike(like: Overlay): Overlay {
+  return createOverlay(like.tileSize, {
+    tilesAcross: like.tilesAcross,
+    addressMode: like.addressMode,
+  });
+}
+
+export function encodeOverlayJournal(journal: OverlayJournal): Uint8Array {
+  const bytes = new Uint8Array(12 + journal.count * JOURNAL_ENTRY_BYTES);
+  const view = new DataView(bytes.buffer);
+  view.setUint32(0, JOURNAL_MAGIC, true);
+  view.setUint32(4, JOURNAL_VERSION, true);
+  view.setUint32(8, journal.count, true);
+  for (let at = 0; at < journal.count; at += 1) {
+    const base = 12 + at * JOURNAL_ENTRY_BYTES;
+    view.setInt32(base, journal.frames[at] as number, true);
+    view.setInt32(base + 4, journal.channels[at] as number, true);
+    for (let c = 0; c < 4; c += 1) {
+      view.setFloat32(base + 8 + c * 4, journal.values[at * 4 + c] as number, true);
+    }
+  }
+  return bytes;
+}
+
+/**
+ * Read a journal back. Null where the bytes are not one.
+ *
+ * Null rather than a partial journal: a replay against half a log is a session that diverges partway
+ * through for no visible reason, which is worse than one that refuses to start.
+ */
+export function decodeOverlayJournal(bytes: Uint8Array): OverlayJournal | null {
+  if (bytes.byteLength < 12) return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.getUint32(0, true) !== JOURNAL_MAGIC) return null;
+  if (view.getUint32(4, true) !== JOURNAL_VERSION) return null;
+  const count = view.getUint32(8, true);
+  if (bytes.byteLength !== 12 + count * JOURNAL_ENTRY_BYTES) return null;
+
+  const journal = createOverlayJournal(Math.max(1, count));
+  for (let at = 0; at < count; at += 1) {
+    const base = 12 + at * JOURNAL_ENTRY_BYTES;
+    recordOverlayWrite(
+      journal,
+      view.getInt32(base, true),
+      view.getFloat32(base + 8, true),
+      view.getFloat32(base + 12, true),
+      view.getFloat32(base + 16, true),
+      view.getInt32(base + 4, true),
+      view.getFloat32(base + 20, true),
+    );
+  }
+  return journal;
+}

package/src/overlay/sparse.ts

@@ -0,0 +1,275 @@
+/**
+ * A texture that can be written to at runtime, without allocating a layer for what nobody touched.
+ *
+ * **Sparse, so that a scorch mark on one wall does not allocate a layer for the building.** Only
+ * written tiles exist; an unwritten coordinate reports nothing written and the base is used
+ * unchanged. That is the difference between a decal system a game can leave on for a whole level
+ * and one somebody turns off because of the memory.
+ *
+ * **Written is tracked per texel *and* per channel.** A scorch darkens the albedo and leaves the
+ * normal alone, so compositing has to know which channels a texel had written rather than treating
+ * a written texel as wholly overwritten. One byte a texel, one bit a channel — which caps the
+ * channel count at eight and is stated where the array is declared rather than discovered.
+ *
+ * **Two numbers are needed to turn a UV into a texel, and the plan gave one.** `tileSize` is texels
+ * per tile edge and says nothing about how much of the surface a tile covers; `tilesAcross` is what
+ * closes it. Without both, a radius in UV has no length in texels and every write is either the
+ * whole surface or a single texel depending on which guess was made.
+ *
+ * **The address mode is the base texture's**, not this file's opinion. `DecodeGraph` carries one —
+ * 0 clamps outside the unit square and 1 wraps — and an overlay that disagreed would put a mark on
+ * the far side of a wall from where somebody aimed, on exactly the textures that wrap.
+ */
+import { hashTile } from '../tileHash.ts';
+
+/** How many channels a texel carries. One bit each in the written mask, so this cannot exceed 8. */
+export const OVERLAY_CHANNELS = 4;
+
+export const ADDRESS_CLAMP = 0;
+export const ADDRESS_WRAP = 1;
+
+export interface OverlayTile {
+  readonly tx: number;
+  readonly ty: number;
+  /** `tileSize * tileSize * OVERLAY_CHANNELS` values. */
+  readonly texels: Float32Array;
+  /** One byte a texel; bit `c` is set where channel `c` has been written. */
+  readonly written: Uint8Array;
+  /** Content hash, recomputed lazily after a write. Empty means stale. */
+  hash: string;
+}
+
+export interface OverlayOptions {
+  /** Tiles across the unit square. With `tileSize`, this fixes the texel density. */
+  readonly tilesAcross?: number;
+  /** `ADDRESS_CLAMP` or `ADDRESS_WRAP`. Take it from the base texture's `DecodeGraph`. */
+  readonly addressMode?: number;
+}
+
+export interface Overlay {
+  /** Texels along a tile edge. */
+  readonly tileSize: number;
+  /** Tiles along the unit square's edge. */
+  readonly tilesAcross: number;
+  /** Texels along the whole unit square's edge: `tileSize * tilesAcross`. */
+  readonly resolution: number;
+  readonly addressMode: number;
+  /** Written tiles only, keyed `"tx,ty"`. An untouched tile does not exist. */
+  readonly tiles: Map<string, OverlayTile>;
+}
+
+export function createOverlay(tileSize: number, options: OverlayOptions = {}): Overlay {
+  const size = Math.max(1, Math.floor(tileSize));
+  const across = Math.max(1, Math.floor(options.tilesAcross ?? 16));
+  return {
+    tileSize: size,
+    tilesAcross: across,
+    resolution: size * across,
+    addressMode: options.addressMode === ADDRESS_WRAP ? ADDRESS_WRAP : ADDRESS_CLAMP,
+    tiles: new Map<string, OverlayTile>(),
+  };
+}
+
+function key(tx: number, ty: number): string {
+  return `${String(tx)},${String(ty)}`;
+}
+
+function tileAt(overlay: Overlay, tx: number, ty: number, make: boolean): OverlayTile | null {
+  const at = key(tx, ty);
+  const held = overlay.tiles.get(at);
+  if (held !== undefined) return held;
+  if (!make) return null;
+  const texels = overlay.tileSize * overlay.tileSize;
+  const tile: OverlayTile = {
+    tx,
+    ty,
+    texels: new Float32Array(texels * OVERLAY_CHANNELS),
+    written: new Uint8Array(texels),
+    hash: '',
+  };
+  overlay.tiles.set(at, tile);
+  return tile;
+}
+
+/**
+ * A texel coordinate brought inside the surface, or `-1` where it is outside and the mode clamps.
+ *
+ * `-1` rather than a clamped edge texel under `ADDRESS_CLAMP`: clamping a *write* would smear the
+ * whole edge of the texture with whatever somebody aimed past it, which is a visible band rather
+ * than the nothing they expected. Clamping a *read* is right, and `sampleOverlay` does that.
+ */
+function wrapTexel(overlay: Overlay, texel: number, forWrite: boolean): number {
+  const size = overlay.resolution;
+  if (overlay.addressMode === ADDRESS_WRAP) return ((texel % size) + size) % size;
+  if (texel >= 0 && texel < size) return texel;
+  return forWrite ? -1 : Math.min(size - 1, Math.max(0, texel));
+}
+
+/**
+ * Write `value` into one channel of every texel within `radius` of `(u, v)`.
+ *
+ * A disc rather than a square, because a square decal is a square nobody asked for, and the radius
+ * is in UV so a caller reasons in surface fractions rather than in whatever resolution this is.
+ */
+export function writeOverlay(
+  overlay: Overlay,
+  u: number,
+  v: number,
+  radius: number,
+  channel: number,
+  value: number,
+): number {
+  if (channel < 0 || channel >= OVERLAY_CHANNELS) return 0;
+  const size = overlay.resolution;
+  const centreX = u * size;
+  const centreY = v * size;
+  const reach = Math.max(0, radius) * size;
+
+  const from = Math.floor(centreX - reach);
+  const to = Math.ceil(centreX + reach);
+  const top = Math.floor(centreY - reach);
+  const bottom = Math.ceil(centreY + reach);
+
+  let touched = 0;
+  for (let y = top; y <= bottom; y += 1) {
+    for (let x = from; x <= to; x += 1) {
+      /* Texel centres, so a radius of half a texel marks one texel rather than none or four. */
+      const dx = x + 0.5 - centreX;
+      const dy = y + 0.5 - centreY;
+      if (dx * dx + dy * dy > reach * reach) continue;
+
+      const wx = wrapTexel(overlay, x, true);
+      const wy = wrapTexel(overlay, y, true);
+      if (wx < 0 || wy < 0) continue;
+
+      /*
+       * The tile is found from the *wrapped* texel, which is what makes a write near a boundary
+       * land in both tiles: the loop runs over one continuous span and each texel finds its own
+       * tile. A version that found one tile and wrote into it leaves a hard edge at every seam —
+       * the defect that looks like the decal was clipped and is usually blamed on the mesh.
+       */
+      const tile = tileAt(
+        overlay,
+        Math.floor(wx / overlay.tileSize),
+        Math.floor(wy / overlay.tileSize),
+        true,
+      ) as OverlayTile;
+      const local = (wy % overlay.tileSize) * overlay.tileSize + (wx % overlay.tileSize);
+      tile.texels[local * OVERLAY_CHANNELS + channel] = value;
+      tile.written[local] = (tile.written[local] as number) | (1 << channel);
+      tile.hash = '';
+      touched += 1;
+    }
+  }
+  return touched;
+}
+
+/**
+ * Read every channel at a coordinate into `out`. False where nothing has been written there.
+ *
+ * False is the ordinary answer and the important one: it is what tells a sampler to use the base
+ * unchanged rather than compositing a zero over it.
+ */
+export function sampleOverlay(overlay: Overlay, u: number, v: number, out: Float32Array): boolean {
+  const size = overlay.resolution;
+  const x = wrapTexel(overlay, Math.floor(u * size), false);
+  const y = wrapTexel(overlay, Math.floor(v * size), false);
+  const tile = tileAt(
+    overlay,
+    Math.floor(x / overlay.tileSize),
+    Math.floor(y / overlay.tileSize),
+    false,
+  );
+  if (tile === null) return false;
+
+  const local = (y % overlay.tileSize) * overlay.tileSize + (x % overlay.tileSize);
+  if ((tile.written[local] ?? 0) === 0) return false;
+  for (let c = 0; c < OVERLAY_CHANNELS; c += 1) {
+    out[c] = tile.texels[local * OVERLAY_CHANNELS + c] as number;
+  }
+  return true;
+}
+
+/** Which channels have been written at a coordinate, as a bit per channel. Zero for none. */
+export function writtenMaskAt(overlay: Overlay, u: number, v: number): number {
+  const size = overlay.resolution;
+  const x = wrapTexel(overlay, Math.floor(u * size), false);
+  const y = wrapTexel(overlay, Math.floor(v * size), false);
+  const tile = tileAt(
+    overlay,
+    Math.floor(x / overlay.tileSize),
+    Math.floor(y / overlay.tileSize),
+    false,
+  );
+  if (tile === null) return 0;
+  return tile.written[(y % overlay.tileSize) * overlay.tileSize + (x % overlay.tileSize)] ?? 0;
+}
+
+/**
+ * A tile's content hash, computed once per write rather than once per call.
+ *
+ * **A cost guard, not a correctness one**, and it does not change an answer — a perturbation
+ * removing it fails no test and is expected to. It stays because `overlayTiles` is called every
+ * frame to decide uploads, and hashing is bytes: four hundred written tiles of 64×64×4 floats took
+ * **79 ms uncached and 0.061 ms cached**, measured 2026-09-15. The first of those is a frame
+ * budget spent several times over to learn that nothing changed.
+ */
+function hashOf(overlay: Overlay, tile: OverlayTile): string {
+  if (tile.hash !== '') return tile.hash;
+  /* The written mask is hashed with the values: two tiles holding the same numbers where one of
+     them wrote a zero and the other did not are different tiles, and compositing proves it. */
+  const bytes = new Uint8Array(tile.texels.buffer.byteLength + tile.written.byteLength);
+  bytes.set(new Uint8Array(tile.texels.buffer), 0);
+  bytes.set(tile.written, tile.texels.buffer.byteLength);
+  tile.hash = hashTile(bytes);
+  return tile.hash;
+}
+
+/**
+ * The distinct content hashes of the written tiles, into `out`. Returns how many.
+ *
+ * **Distinct, because an identical mark in two places is one thing to store.** The same blast
+ * scorch on twenty crates is twenty tiles in memory — each is written in place and they diverge the
+ * moment anything else touches one — and one page to upload, which is where the cost actually is.
+ * Hashed exactly as a base tile is, by `hashTile`, so the two live in one address space.
+ */
+export function overlayTiles(overlay: Overlay, out: string[]): number {
+  out.length = 0;
+  const seen = new Set<string>();
+  for (const tile of overlay.tiles.values()) {
+    const hash = hashOf(overlay, tile);
+    if (seen.has(hash)) continue;
+    seen.add(hash);
+    out.push(hash);
+  }
+  out.sort();
+  return out.length;
+}
+
+/** How many tiles hold a written texel. What a memory readout shows. */
+export function overlayTileCount(overlay: Overlay): number {
+  return overlay.tiles.size;
+}
+
+/**
+ * Put the overlay over the base, channel by channel, into `out`.
+ *
+ * **`written` is a parameter because the plan's signature had no way to say which texels and
+ * channels were touched**, and without it compositing either overwrites everything — so one scorch
+ * mark erases the base across the whole tile — or guesses from a sentinel value, which is a value
+ * somebody eventually writes on purpose.
+ */
+export function compositeOverlay(
+  out: Float32Array,
+  base: Float32Array,
+  overlay: Float32Array,
+  written: Uint8Array,
+): void {
+  for (let texel = 0; texel < written.length; texel += 1) {
+    const mask = written[texel] as number;
+    for (let c = 0; c < OVERLAY_CHANNELS; c += 1) {
+      const at = texel * OVERLAY_CHANNELS + c;
+      out[at] = (mask & (1 << c)) === 0 ? (base[at] as number) : (overlay[at] as number);
+    }
+  }
+}

package/src/progressive.ts

@@ -0,0 +1,60 @@
+/**
+ * The order tiles are sent in, so a material is usable long before it is complete.
+ *
+ * **There is precedent in this repository and this follows it.** `drft/coarseFirst.ts` opens a
+ * splat capture in a fourteenth of its bytes through a Morton quantisation and a bit-reversal
+ * walk, and the principle is the same: a prefix of the stream should be spread over the whole
+ * image rather than filling one corner of it.
+ *
+ * **Bit-reversal is what spreads it.** Counting 0, 1, 2, 3 fills left to right; counting with the
+ * index's bits reversed visits 0, 4, 2, 6, 1, 5, 3, 7 — every prefix roughly uniform over the
+ * range, so an interrupted download is a coarse version of the whole material rather than a sharp
+ * version of part of it.
+ */
+
+function reverseBits(value: number, bits: number): number {
+  let out = 0;
+  for (let i = 0; i < bits; i += 1) out = (out << 1) | ((value >>> i) & 1);
+  return out >>> 0;
+}
+
+/**
+ * Fill `out` with the order to send `tileCount` tiles in. Returns how many were written.
+ *
+ * A permutation: every tile appears exactly once, which the test asserts because an ordering that
+ * drops one is a material that never completes and never says why.
+ */
+export function progressiveOrder(tileCount: number, out: Uint32Array): number {
+  if (tileCount <= 0) return 0;
+  const bits = Math.max(1, Math.ceil(Math.log2(tileCount)));
+  const span = 1 << bits;
+  let written = 0;
+  for (let i = 0; i < span; i += 1) {
+    const tile = reverseBits(i, bits);
+    /* The reversal walks a power-of-two range; anything past the real count is skipped. */
+    if (tile < tileCount) {
+      out[written] = tile;
+      written += 1;
+    }
+  }
+  return written;
+}
+
+/**
+ * What level this many received bytes supports.
+ *
+ * Levels rise monotonically with bytes, which is what lets a loader show something immediately and
+ * refine without ever going backwards.
+ */
+export function usableAt(
+  bytesReceived: number,
+  tileBytes: number,
+  tileCount: number,
+): { level: number; complete: boolean } {
+  if (tileBytes <= 0 || tileCount <= 0) return { level: 0, complete: true };
+  const tiles = Math.min(tileCount, Math.floor(bytesReceived / tileBytes));
+  const complete = tiles >= tileCount;
+  /* Each doubling of received tiles is one more level of detail. */
+  const level = tiles <= 0 ? 0 : Math.floor(Math.log2(tiles)) + 1;
+  return { level, complete };
+}