@driftengine/texture 4.0.0

package/dist/residency/predict.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Running the world forward to see what it will need, then putting it back.
+ *
+ * **This is the part no competitor can copy, and the reason is not the code.** The state of the art
+ * in texture streaming is reactive: the documentation for the most widely deployed implementation
+ * says so in as many words — streaming is *reactive by nature*, because the processor cannot know a
+ * tile is needed until after a frame has already needed it. Hence pop-in, and hence the further
+ * limitation that passes which write no feedback can sample tiles they are unable to request.
+ *
+ * That is true only of an engine that cannot run its simulation forward and put it back. This one
+ * can, and already does every frame for the netcode. So residency is decided by looking at where
+ * the camera *will* be:
+ *
+ * ```text
+ * every engine                    DriftEngine
+ * ────────────                    ───────────
+ * render frame N                  save the simulation
+ * read the feedback buffer        advance it N frames, deterministic, no rendering
+ *   ↓ two to three frames late    sample which tiles those views want
+ * request the tiles               restore
+ * pop-in                          prefetch → resident before it is ever visible
+ * ```
+ *
+ * **The simulation is taken as a handle the caller supplies**, in the save/restore shape
+ * `@driftengine/network`'s `Snapshotter` already uses, for two reasons: this package must not
+ * import a simulation, and a consumer with their own loop has to be able to supply their own.
+ *
+ * **A misprediction costs a wasted fetch and nothing else.** The tile arrives late, exactly as it
+ * would in a reactive engine — so the floor of this mechanism is everyone else's ceiling.
+ */
+/**
+ * What prediction needs from a simulation.
+ *
+ * Save and restore rather than a snapshot value, matching `Snapshotter` in the network package:
+ * the buffer is the handle's own and is reused, so predicting allocates nothing.
+ */
+export interface SimulationHandle {
+    /** Capture the current state into the handle's own storage. */
+    save(): void;
+    /** Put back what `save` captured. */
+    restore(): void;
+    /** Advance one fixed step. Deterministic, and the same step the simulation really runs. */
+    advance(dt: number): void;
+    /** Write the current view matrix into `out`, sixteen floats. */
+    viewAt(out: Float32Array): void;
+}
+/**
+ * Fill `out` with one view matrix per predicted frame, and leave the simulation exactly as found.
+ *
+ * Returns how many views were written — fewer than `frames` when `out` cannot hold them all.
+ *
+ * **Saved once and restored once**, however many frames are predicted: the intermediate states are
+ * not wanted, only the views they imply.
+ */
+export declare function predictViews(sim: SimulationHandle, frames: number, dt: number, out: Float32Array): number;

package/dist/residency/predict.js

@@ -0,0 +1,51 @@
+/**
+ * Running the world forward to see what it will need, then putting it back.
+ *
+ * **This is the part no competitor can copy, and the reason is not the code.** The state of the art
+ * in texture streaming is reactive: the documentation for the most widely deployed implementation
+ * says so in as many words — streaming is *reactive by nature*, because the processor cannot know a
+ * tile is needed until after a frame has already needed it. Hence pop-in, and hence the further
+ * limitation that passes which write no feedback can sample tiles they are unable to request.
+ *
+ * That is true only of an engine that cannot run its simulation forward and put it back. This one
+ * can, and already does every frame for the netcode. So residency is decided by looking at where
+ * the camera *will* be:
+ *
+ * ```text
+ * every engine                    DriftEngine
+ * ────────────                    ───────────
+ * render frame N                  save the simulation
+ * read the feedback buffer        advance it N frames, deterministic, no rendering
+ *   ↓ two to three frames late    sample which tiles those views want
+ * request the tiles               restore
+ * pop-in                          prefetch → resident before it is ever visible
+ * ```
+ *
+ * **The simulation is taken as a handle the caller supplies**, in the save/restore shape
+ * `@driftengine/network`'s `Snapshotter` already uses, for two reasons: this package must not
+ * import a simulation, and a consumer with their own loop has to be able to supply their own.
+ *
+ * **A misprediction costs a wasted fetch and nothing else.** The tile arrives late, exactly as it
+ * would in a reactive engine — so the floor of this mechanism is everyone else's ceiling.
+ */
+/**
+ * Fill `out` with one view matrix per predicted frame, and leave the simulation exactly as found.
+ *
+ * Returns how many views were written — fewer than `frames` when `out` cannot hold them all.
+ *
+ * **Saved once and restored once**, however many frames are predicted: the intermediate states are
+ * not wanted, only the views they imply.
+ */
+export function predictViews(sim, frames, dt, out) {
+    const capacity = Math.floor(out.length / 16);
+    const wanted = Math.min(frames, capacity);
+    if (wanted <= 0)
+        return 0;
+    sim.save();
+    for (let i = 0; i < wanted; i += 1) {
+        sim.advance(dt);
+        sim.viewAt(out.subarray(i * 16, i * 16 + 16));
+    }
+    sim.restore();
+    return wanted;
+}

package/dist/residency/predictor.d.ts

@@ -0,0 +1,16 @@
+import type { SimulationHandle } from './predict.ts';
+export interface Predictor<T> {
+    /** What this view needs, most important first. Fills `out` and returns how many. */
+    needs(view: Float32Array, out: T[], budget: number): number;
+    /** Whether this item is already here. */
+    resident(item: T): boolean;
+    /** Ask for it. Lower priority is sooner. */
+    request(item: T, priority: number): void;
+}
+/**
+ * Advance the simulation, ask the predictor what each predicted view needs, and put it back.
+ *
+ * Returns how many requests were made. `budget` bounds the total across every predicted frame
+ * rather than per frame, so a near frame cannot be starved by a distant one filling the queue.
+ */
+export declare function runPrediction<T>(sim: SimulationHandle, predictor: Predictor<T>, frames: number, dt: number, budget: number): number;

package/dist/residency/predictor.js

@@ -0,0 +1,44 @@
+/**
+ * Prediction, generic over what is being streamed.
+ *
+ * **Written generic now rather than generalised later, and the reason is a contract rather than
+ * tidiness.** Wave 4B streams world cells by exactly this mechanism. Writing the tile case against
+ * a concrete type would mean a second speculative-advance implementation there — and therefore a
+ * second place for "put the simulation back exactly" to be got wrong, in a subsystem where being
+ * wrong means the world runs at double speed only when streaming is enabled.
+ *
+ * One prediction, two consumers.
+ */
+import { predictViews } from './predict.js';
+const VIEWS = new Float32Array(16 * 32);
+const WANTED = [];
+/**
+ * Advance the simulation, ask the predictor what each predicted view needs, and put it back.
+ *
+ * Returns how many requests were made. `budget` bounds the total across every predicted frame
+ * rather than per frame, so a near frame cannot be starved by a distant one filling the queue.
+ */
+export function runPrediction(sim, predictor, frames, dt, budget) {
+    const horizon = Math.min(frames, Math.floor(VIEWS.length / 16));
+    const count = predictViews(sim, horizon, dt, VIEWS);
+    let requested = 0;
+    const out = WANTED;
+    for (let frame = 0; frame < count && requested < budget; frame += 1) {
+        const view = VIEWS.subarray(frame * 16, frame * 16 + 16);
+        const wanted = predictor.needs(view, out, budget - requested);
+        for (let i = 0; i < wanted && requested < budget; i += 1) {
+            const item = out[i];
+            if (predictor.resident(item))
+                continue;
+            /*
+             * Priority is how far ahead the frame is, so nearer frames come first — and within a frame,
+             * the place the predictor named the item in, as a fraction that never reaches the next
+             * frame. A frame's priority alone would tie its items, and a queue breaks a tie however it
+             * likes; a budget that cut the frame short would then keep an arbitrary part of it.
+             */
+            predictor.request(item, frame + i / wanted);
+            requested += 1;
+        }
+    }
+    return requested;
+}

package/dist/residency/queue.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What to fetch next, ordered by how soon it will be needed.
+ *
+ * **That ordering is not available to a reactive system at all.** Everything a feedback buffer
+ * reports is already needed; there is nothing to rank. Prediction produces a horizon, so a tile
+ * wanted in one frame can outrank one wanted in eight — which is the difference between spending a
+ * limited byte budget well and spending it arbitrarily.
+ *
+ * **A full queue drops its worst entry rather than refusing the best one.** Refusing on arrival
+ * would discard exactly the tiles a late prediction found most urgent.
+ */
+export interface PrefetchQueue {
+    /** Priority per hash. Lower is sooner, so it sorts naturally. */
+    priority: Map<string, number>;
+    capacity: number;
+}
+export declare function createPrefetchQueue(capacity: number): PrefetchQueue;
+export declare function enqueue(queue: PrefetchQueue, hash: string, priority: number): void;
+export declare function queueSize(queue: PrefetchQueue): number;
+/**
+ * Take the next batch, soonest first, within a byte budget.
+ *
+ * **Residency is checked here rather than at enqueue**, because it may have changed in between —
+ * a tile requested eight frames ahead may well have arrived by the time its turn comes.
+ */
+export declare function takeBatch(queue: PrefetchQueue, isResident: (hash: string) => boolean, bytesBudget: number, tileBytes: number, out: string[]): number;

package/dist/residency/queue.js

@@ -0,0 +1,52 @@
+export function createPrefetchQueue(capacity) {
+    return { priority: new Map(), capacity };
+}
+export function enqueue(queue, hash, priority) {
+    const existing = queue.priority.get(hash);
+    /* One entry per tile, keeping the better claim on it. */
+    if (existing !== undefined) {
+        if (priority < existing)
+            queue.priority.set(hash, priority);
+        return;
+    }
+    queue.priority.set(hash, priority);
+    if (queue.priority.size <= queue.capacity)
+        return;
+    let worst = '';
+    let worstPriority = -Infinity;
+    for (const [key, value] of queue.priority) {
+        if (value > worstPriority) {
+            worstPriority = value;
+            worst = key;
+        }
+    }
+    queue.priority.delete(worst);
+}
+export function queueSize(queue) {
+    return queue.priority.size;
+}
+/**
+ * Take the next batch, soonest first, within a byte budget.
+ *
+ * **Residency is checked here rather than at enqueue**, because it may have changed in between —
+ * a tile requested eight frames ahead may well have arrived by the time its turn comes.
+ */
+export function takeBatch(queue, isResident, bytesBudget, tileBytes, out) {
+    const ordered = [...queue.priority.entries()].sort((a, b) => a[1] - b[1] || (a[0] < b[0] ? -1 : 1));
+    let spent = 0;
+    let written = 0;
+    for (const [hash] of ordered) {
+        if (isResident(hash)) {
+            queue.priority.delete(hash);
+            continue;
+        }
+        if (spent + tileBytes > bytesBudget)
+            break;
+        out[written] = hash;
+        written += 1;
+        spent += tileBytes;
+        queue.priority.delete(hash);
+    }
+    out.length = written;
+    return written;
+}

package/dist/residency/stream.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Getting the bytes, and giving up on the ones that are not coming.
+ *
+ * **A tile that will not arrive stops being waited for.** That is the whole of this file's
+ * difficulty. A fetch that resolves with nothing — a tile the container does not hold, a name from
+ * a stale index, a range the server refused — leaves the tile marked requested and its slot
+ * occupied forever if nobody handles it. A handful of those and the in-flight budget is gone, so
+ * every subsequent fetch is refused and **streaming stops entirely**, with no error anywhere: the
+ * world simply never finishes loading, and the last thing that happened was unrelated.
+ *
+ * So a missing tile is remembered as missing. Not evicted-and-forgotten, which asks for it again on
+ * the next pump and turns one absent tile into a fetch every frame; and not left requested, which
+ * is the leak. `forgetMissing` exists because "missing" is a fact about a container and a caller
+ * that mounts a different one is entitled to ask again.
+ *
+ * **The source is the caller's.** What a tile's bytes are behind — a `.drft` container, a range
+ * request, a file — is not this package's business, and a streamer that knew would be a streamer
+ * every host had to agree with. It is one method returning a promise of bytes or nothing.
+ *
+ * **Nothing here awaits.** `pumpStreamer` starts work and returns; a source that never resolves
+ * costs an in-flight slot and nothing else. A streamer that awaited its own fetches would stall the
+ * frame that called it, which is the failure streaming exists to avoid.
+ */
+import { type ResidencyTable } from './table.ts';
+import { type PageCache } from './pageCache.ts';
+/** Where a tile's bytes come from. Resolving `null` means the source does not have it. */
+export interface TileSource {
+    fetch(hash: string): Promise<Uint8Array | null>;
+}
+export interface StreamerOptions {
+    /**
+     * How many fetches may be outstanding at once.
+     *
+     * A bound rather than none, because an unbounded streamer asked for a thousand tiles opens a
+     * thousand connections and finishes none of them sooner.
+     */
+    readonly maxInFlight?: number;
+}
+export interface Streamer {
+    readonly source: TileSource;
+    readonly table: ResidencyTable;
+    readonly cache: PageCache;
+    readonly maxInFlight: number;
+    /** Tiles asked for and not yet answered. */
+    readonly inFlight: Set<string>;
+    /** Tiles the source answered `null` for. Not asked for again until forgotten. */
+    readonly missing: Set<string>;
+    /** Fetches that landed after their tile had been evicted. Counted, not silently dropped. */
+    stale: number;
+    /** Fetches that landed with no page free to put them in. The tile stays absent and is retried. */
+    deferred: number;
+    /** Fetches whose bytes were larger than a page. A container and a cache disagreeing. */
+    oversize: number;
+}
+export declare function createStreamer(source: TileSource, table: ResidencyTable, cache: PageCache, options?: StreamerOptions): Streamer;
+export declare function streamerInFlight(streamer: Streamer): number;
+/** Stop calling a tile missing, so the next pump asks for it again. */
+export declare function forgetMissing(streamer: Streamer, hash: string): void;
+export declare function clearMissing(streamer: Streamer): void;
+/**
+ * Ask for the first `count` tiles of `batch` that are worth asking for. Returns how many were sent.
+ *
+ * Skips anything already resident, already in flight, or known missing — which is what makes
+ * calling this every frame with the same batch correct rather than a fetch storm.
+ */
+export declare function pumpStreamer(streamer: Streamer, batch: readonly string[], count: number): number;

package/dist/residency/stream.js

@@ -0,0 +1,142 @@
+/**
+ * Getting the bytes, and giving up on the ones that are not coming.
+ *
+ * **A tile that will not arrive stops being waited for.** That is the whole of this file's
+ * difficulty. A fetch that resolves with nothing — a tile the container does not hold, a name from
+ * a stale index, a range the server refused — leaves the tile marked requested and its slot
+ * occupied forever if nobody handles it. A handful of those and the in-flight budget is gone, so
+ * every subsequent fetch is refused and **streaming stops entirely**, with no error anywhere: the
+ * world simply never finishes loading, and the last thing that happened was unrelated.
+ *
+ * So a missing tile is remembered as missing. Not evicted-and-forgotten, which asks for it again on
+ * the next pump and turns one absent tile into a fetch every frame; and not left requested, which
+ * is the leak. `forgetMissing` exists because "missing" is a fact about a container and a caller
+ * that mounts a different one is entitled to ask again.
+ *
+ * **The source is the caller's.** What a tile's bytes are behind — a `.drft` container, a range
+ * request, a file — is not this package's business, and a streamer that knew would be a streamer
+ * every host had to agree with. It is one method returning a promise of bytes or nothing.
+ *
+ * **Nothing here awaits.** `pumpStreamer` starts work and returns; a source that never resolves
+ * costs an in-flight slot and nothing else. A streamer that awaited its own fetches would stall the
+ * frame that called it, which is the failure streaming exists to avoid.
+ */
+import { TILE_ABSENT, TILE_REQUESTED, evict, markRequested, markResident, tileState, } from './table.js';
+import { acquirePage, takeEvicted } from './pageCache.js';
+export function createStreamer(source, table, cache, options = {}) {
+    return {
+        source,
+        table,
+        cache,
+        maxInFlight: Math.max(1, Math.floor(options.maxInFlight ?? 8)),
+        inFlight: new Set(),
+        missing: new Set(),
+        stale: 0,
+        deferred: 0,
+        oversize: 0,
+    };
+}
+export function streamerInFlight(streamer) {
+    return streamer.inFlight.size;
+}
+/** Stop calling a tile missing, so the next pump asks for it again. */
+export function forgetMissing(streamer, hash) {
+    streamer.missing.delete(hash);
+}
+export function clearMissing(streamer) {
+    streamer.missing.clear();
+}
+/**
+ * Ask for the first `count` tiles of `batch` that are worth asking for. Returns how many were sent.
+ *
+ * Skips anything already resident, already in flight, or known missing — which is what makes
+ * calling this every frame with the same batch correct rather than a fetch storm.
+ */
+export function pumpStreamer(streamer, batch, count) {
+    let sent = 0;
+    /* A bound on the loop rather than a correctness check — the `undefined` guard below is what
+       makes a short batch behave, and a perturbation removing this one fails no test. It stays
+       because without it `pumpStreamer(s, [], 1e9)` spins a billion times to do nothing. */
+    const wanted = Math.min(count, batch.length);
+    for (let at = 0; at < wanted; at += 1) {
+        if (streamer.inFlight.size >= streamer.maxInFlight)
+            break;
+        const hash = batch[at];
+        if (hash === undefined)
+            continue;
+        if (streamer.missing.has(hash))
+            continue;
+        /* Already asked for. Usually the table says so too, but not after an eviction while the fetch
+           was still out: the tile is absent again and a second fetch of bytes already on their way is
+           exactly what a content-addressed store makes pointless. */
+        if (streamer.inFlight.has(hash))
+            continue;
+        if (tileState(streamer.table, hash) !== TILE_ABSENT)
+            continue;
+        markRequested(streamer.table, hash);
+        streamer.inFlight.add(hash);
+        sent += 1;
+        /*
+         * Not awaited: this returns to the frame that called it. A rejection is treated exactly as a
+         * missing tile, because from here they are the same fact — the bytes are not coming — and a
+         * streamer that let one through would be the leak this file is about, arriving by the one path
+         * nobody writes a test for.
+         */
+        void streamer.source
+            .fetch(hash)
+            .then((bytes) => {
+            land(streamer, hash, bytes);
+        })
+            .catch(() => {
+            land(streamer, hash, null);
+        });
+    }
+    return sent;
+}
+function land(streamer, hash, bytes) {
+    streamer.inFlight.delete(hash);
+    /*
+     * Evicted while in flight. Its slot belongs to somebody else now, so these bytes go nowhere —
+     * and the tile is left absent rather than resurrected, because whatever evicted it decided it
+     * was not wanted and this arriving late does not change that.
+     */
+    if (tileState(streamer.table, hash) !== TILE_REQUESTED) {
+        streamer.stale += 1;
+        return;
+    }
+    if (bytes === null) {
+        evict(streamer.table, hash);
+        streamer.missing.add(hash);
+        return;
+    }
+    if (bytes.length > streamer.cache.pageBytes) {
+        /* A truncation here would be a tile that decodes to something nobody authored, found weeks
+           later as a corrupt-looking texture. Refused, counted, and left absent. */
+        streamer.oversize += 1;
+        evict(streamer.table, hash);
+        streamer.missing.add(hash);
+        return;
+    }
+    const slot = acquirePage(streamer.cache, hash);
+    if (slot < 0) {
+        /* Every page is in use by this frame. The tile stays absent, so the next pump asks again. */
+        streamer.deferred += 1;
+        evict(streamer.table, hash);
+        return;
+    }
+    drainEvictions(streamer);
+    streamer.cache.bytes.set(bytes, slot * streamer.cache.pageBytes);
+    markResident(streamer.table, hash, slot);
+}
+/**
+ * Tell the table about pages the cache took, so nothing is called resident in a slot it lost.
+ *
+ * The one piece of wiring between the two structures, and the reason `takeEvicted` exists: a table
+ * still pointing at a reused slot hands a frame another tile's bytes.
+ */
+function drainEvictions(streamer) {
+    const taken = [];
+    takeEvicted(streamer.cache, taken);
+    for (const hash of taken)
+        evict(streamer.table, hash);
+}

package/dist/residency/table.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What is here, what is on its way, and what is not.
+ *
+ * **The tile the current frame is sampling is never evicted.** That is the one rule this structure
+ * exists to enforce: an eviction policy that can reclaim a tile in use produces a frame drawn
+ * against a page somebody else is writing, which is a corruption rather than a stall and does not
+ * look like a streaming problem at all.
+ */
+export declare const TILE_ABSENT = 0;
+export declare const TILE_REQUESTED = 1;
+export declare const TILE_RESIDENT = 2;
+export interface ResidencyTable {
+    state: Map<string, number>;
+    slot: Map<string, number>;
+    /** Monotonic counter standing in for time, so eviction needs no clock. */
+    touchedAt: Map<string, number>;
+    clock: number;
+    capacity: number;
+}
+export declare function createResidencyTable(capacity: number): ResidencyTable;
+export declare function tileState(table: ResidencyTable, hash: string): number;
+export declare function markRequested(table: ResidencyTable, hash: string): void;
+export declare function markResident(table: ResidencyTable, hash: string, slot: number): void;
+/** Say this tile is in use now, so eviction will not take it. */
+export declare function touchTile(table: ResidencyTable, hash: string): void;
+export declare function evict(table: ResidencyTable, hash: string): void;
+export declare function slotFor(table: ResidencyTable, hash: string): number;
+export declare function residentCount(table: ResidencyTable): number;
+/**
+ * The least recently used resident tiles, oldest first, **excluding anything touched since
+ * `since`**.
+ *
+ * The exclusion is the point. A caller passes the clock value from the start of the frame, and
+ * everything this frame has sampled is off the table.
+ */
+export declare function leastRecentlyUsed(table: ResidencyTable, since: number, out: string[], count: number): number;

package/dist/residency/table.js

@@ -0,0 +1,72 @@
+/**
+ * What is here, what is on its way, and what is not.
+ *
+ * **The tile the current frame is sampling is never evicted.** That is the one rule this structure
+ * exists to enforce: an eviction policy that can reclaim a tile in use produces a frame drawn
+ * against a page somebody else is writing, which is a corruption rather than a stall and does not
+ * look like a streaming problem at all.
+ */
+export const TILE_ABSENT = 0;
+export const TILE_REQUESTED = 1;
+export const TILE_RESIDENT = 2;
+export function createResidencyTable(capacity) {
+    return { state: new Map(), slot: new Map(), touchedAt: new Map(), clock: 0, capacity };
+}
+export function tileState(table, hash) {
+    return table.state.get(hash) ?? TILE_ABSENT;
+}
+export function markRequested(table, hash) {
+    /* An already-resident tile is not re-requested: that is a second fetch of bytes we hold. */
+    if (tileState(table, hash) !== TILE_ABSENT)
+        return;
+    table.state.set(hash, TILE_REQUESTED);
+}
+export function markResident(table, hash, slot) {
+    table.state.set(hash, TILE_RESIDENT);
+    table.slot.set(hash, slot);
+    touchTile(table, hash);
+}
+/** Say this tile is in use now, so eviction will not take it. */
+export function touchTile(table, hash) {
+    table.clock += 1;
+    table.touchedAt.set(hash, table.clock);
+}
+export function evict(table, hash) {
+    table.state.delete(hash);
+    table.slot.delete(hash);
+    table.touchedAt.delete(hash);
+}
+export function slotFor(table, hash) {
+    return table.slot.get(hash) ?? -1;
+}
+export function residentCount(table) {
+    let count = 0;
+    for (const state of table.state.values())
+        if (state === TILE_RESIDENT)
+            count += 1;
+    return count;
+}
+/**
+ * The least recently used resident tiles, oldest first, **excluding anything touched since
+ * `since`**.
+ *
+ * The exclusion is the point. A caller passes the clock value from the start of the frame, and
+ * everything this frame has sampled is off the table.
+ */
+export function leastRecentlyUsed(table, since, out, count) {
+    const candidates = [];
+    for (const [hash, state] of table.state) {
+        if (state !== TILE_RESIDENT)
+            continue;
+        const at = table.touchedAt.get(hash) ?? 0;
+        if (at > since)
+            continue;
+        candidates.push({ hash, at });
+    }
+    candidates.sort((a, b) => a.at - b.at || (a.hash < b.hash ? -1 : 1));
+    const written = Math.min(count, candidates.length);
+    for (let i = 0; i < written; i += 1)
+        out[i] = candidates[i].hash;
+    out.length = written;
+    return written;
+}