@driftengine/texture 4.0.0

package/dist/tensor/spatial.js

@@ -0,0 +1,131 @@
+/**
+ * The spatial operators: convolution, its transpose, a patch embedding and max pooling. Resizing is
+ * `resize.ts`'s.
+ *
+ * **Channel-major images, one at a time** — `[channels][height][width]`, the layout the upstream
+ * frameworks call NCHW with a batch of one — and **weights in the upstream layout**: a convolution's
+ * `[out][in][kh][kw]`, a transposed convolution's `[in][out][kh][kw]`. A converted checkpoint is
+ * then read as it was stored, and a rearrangement is never a place for a transposed weight to hide.
+ */
+/**
+ * `out[cout][oh][ow]` from `input[cin][h][w]`, with `oh = ⌊(h + 2·padding − kh)/stride⌋ + 1` and
+ * likewise `ow`. `bias` may be null.
+ *
+ * **Grouped, the channels split into `groups` runs** and output `o` reads only the run `o` falls in:
+ * the weight is `[cout][cin / groups][kh][kw]`, as the upstream stores it, and a depthwise
+ * convolution is `groups = cin = cout`.
+ */
+export function conv2d(out, input, cin, h, w, weight, bias, cout, kh, kw, stride, padding, groups = 1) {
+    const oh = Math.floor((h + 2 * padding - kh) / stride) + 1;
+    const ow = Math.floor((w + 2 * padding - kw) / stride) + 1;
+    const inPerGroup = cin / groups;
+    const outPerGroup = cout / groups;
+    for (let o = 0; o < cout; o += 1) {
+        const first = Math.floor(o / outPerGroup) * inPerGroup;
+        for (let y = 0; y < oh; y += 1) {
+            for (let x = 0; x < ow; x += 1) {
+                let sum = bias === null ? 0 : bias[o];
+                for (let c = 0; c < inPerGroup; c += 1) {
+                    for (let ky = 0; ky < kh; ky += 1) {
+                        const sy = y * stride - padding + ky;
+                        if (sy < 0 || sy >= h)
+                            continue;
+                        for (let kx = 0; kx < kw; kx += 1) {
+                            const sx = x * stride - padding + kx;
+                            if (sx < 0 || sx >= w)
+                                continue;
+                            sum +=
+                                input[((first + c) * h + sy) * w + sx] *
+                                    weight[((o * inPerGroup + c) * kh + ky) * kw + kx];
+                        }
+                    }
+                }
+                out[(o * oh + y) * ow + x] = sum;
+            }
+        }
+    }
+}
+/**
+ * `out[cout][oh][ow]` from `input[cin][h][w]`, with `oh = (h − 1)·stride − 2·padding + kh`: each input
+ * pixel spread over the kernel at its strided place, which is how a decoder head upsamples.
+ */
+export function convTranspose2d(out, input, cin, h, w, weight, bias, cout, kh, kw, stride, padding) {
+    const oh = (h - 1) * stride - 2 * padding + kh;
+    const ow = (w - 1) * stride - 2 * padding + kw;
+    for (let o = 0; o < cout; o += 1) {
+        const value = bias === null ? 0 : bias[o];
+        for (let i = 0; i < oh * ow; i += 1)
+            out[o * oh * ow + i] = value;
+    }
+    for (let c = 0; c < cin; c += 1) {
+        for (let y = 0; y < h; y += 1) {
+            for (let x = 0; x < w; x += 1) {
+                const pixel = input[(c * h + y) * w + x];
+                for (let o = 0; o < cout; o += 1) {
+                    for (let ky = 0; ky < kh; ky += 1) {
+                        const ty = y * stride - padding + ky;
+                        if (ty < 0 || ty >= oh)
+                            continue;
+                        for (let kx = 0; kx < kw; kx += 1) {
+                            const tx = x * stride - padding + kx;
+                            if (tx < 0 || tx >= ow)
+                                continue;
+                            const at = (o * oh + ty) * ow + tx;
+                            out[at] =
+                                out[at] +
+                                    pixel * weight[((c * cout + o) * kh + ky) * kw + kx];
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+/**
+ * A patch embedding: a convolution with stride and kernel both `patch`, written token-major —
+ * `out[tokens][dim]`, tokens row by row — which is the order a transformer reads them in.
+ */
+export function patchEmbed(out, image, cin, h, w, weight, bias, dim, patch) {
+    const rows = Math.floor(h / patch);
+    const cols = Math.floor(w / patch);
+    for (let ty = 0; ty < rows; ty += 1) {
+        for (let tx = 0; tx < cols; tx += 1) {
+            const token = ty * cols + tx;
+            for (let o = 0; o < dim; o += 1) {
+                let sum = bias === null ? 0 : bias[o];
+                for (let c = 0; c < cin; c += 1) {
+                    for (let ky = 0; ky < patch; ky += 1) {
+                        for (let kx = 0; kx < patch; kx += 1) {
+                            sum +=
+                                image[(c * h + ty * patch + ky) * w + tx * patch + kx] *
+                                    weight[((o * cin + c) * patch + ky) * patch + kx];
+                        }
+                    }
+                }
+                out[token * dim + o] = sum;
+            }
+        }
+    }
+}
+/**
+ * `out[channels][oh][ow]`, each the largest of its `kernel`-square window at `stride`, with
+ * `oh = ⌊(h − kernel)/stride⌋ + 1`: no padding, and a ragged last row or column dropped, as
+ * PyTorch's `max_pool2d` does without `ceil_mode`.
+ */
+export function maxPool2d(out, input, channels, h, w, kernel, stride) {
+    const oh = Math.floor((h - kernel) / stride) + 1;
+    const ow = Math.floor((w - kernel) / stride) + 1;
+    for (let c = 0; c < channels; c += 1) {
+        for (let y = 0; y < oh; y += 1) {
+            for (let x = 0; x < ow; x += 1) {
+                let largest = Number.NEGATIVE_INFINITY;
+                for (let ky = 0; ky < kernel; ky += 1) {
+                    for (let kx = 0; kx < kernel; kx += 1) {
+                        largest = Math.max(largest, input[(c * h + y * stride + ky) * w + x * stride + kx]);
+                    }
+                }
+                out[(c * oh + y) * ow + x] = largest;
+            }
+        }
+    }
+}

package/dist/tensor/spatialOperators.d.ts

@@ -0,0 +1,2 @@
+import { type Operator } from './operatorKit.ts';
+export declare const SPATIAL_OPERATORS: readonly (readonly [string, Operator])[];

package/dist/tensor/spatialOperators.js

@@ -0,0 +1,138 @@
+/** The spatial operators' rows: convolution, its transpose, patch embedding, resizing, pooling. */
+import { resize } from './resize.js';
+import { conv2d, convTranspose2d, maxPool2d, patchEmbed } from './spatial.js';
+import { num } from './operatorKit.js';
+/*
+ * A resize's `stepHeight` and `stepWidth`: the source pixels one destination pixel covers, where
+ * that is not the ratio of the sizes — PyTorch's interpolate handed a scale factor samples by the
+ * factor's inverse, and DINOv2's positional embeddings are resized that way. Both or neither.
+ */
+function stepOf(attributes) {
+    const height = attributes['stepHeight'];
+    const width = attributes['stepWidth'];
+    return typeof height === 'number' && typeof width === 'number' ? [height, width] : undefined;
+}
+/* A resize's mode, bilinear when none is named, and undefined for one the runtime lacks. */
+function modeOf(attributes) {
+    const mode = attributes['mode'] ?? 'bilinear';
+    return mode === 'bilinear' || mode === 'bicubic' || mode === 'nearest' ? mode : undefined;
+}
+export const SPATIAL_OPERATORS = [
+    [
+        'conv2d',
+        {
+            ranks: [3, 4, 1],
+            arity: [2, 3],
+            shape: ([x, w], attributes) => {
+                const [c, h, width] = x;
+                const [o, ci, kh, kw] = w;
+                const groups = num(attributes, 'groups', 1);
+                if (c % groups !== 0)
+                    return `x's ${c} channels do not split into ${groups} groups`;
+                if (o % groups !== 0)
+                    return `the weight's ${o} outputs do not split into ${groups} groups`;
+                if (c !== ci * groups)
+                    return `x has ${c} channels and the weight takes ${ci * groups}`;
+                const stride = num(attributes, 'stride', 1);
+                const padding = num(attributes, 'padding', 0);
+                return [
+                    o,
+                    Math.floor((h + 2 * padding - kh) / stride) + 1,
+                    Math.floor((width + 2 * padding - kw) / stride) + 1,
+                ];
+            },
+            evaluate: ([x, w, b], [xs, ws], attributes, out) => {
+                const [c, h, width] = xs;
+                const [o, , kh, kw] = ws;
+                conv2d(out, x, c, h, width, w, b ?? null, o, kh, kw, num(attributes, 'stride', 1), num(attributes, 'padding', 0), num(attributes, 'groups', 1));
+            },
+        },
+    ],
+    [
+        'convTranspose2d',
+        {
+            ranks: [3, 4, 1],
+            arity: [2, 3],
+            shape: ([x, w], attributes) => {
+                const [c, h, width] = x;
+                const [ci, o, kh, kw] = w;
+                if (c !== ci)
+                    return `x has ${c} channels and the weight takes ${ci}`;
+                const stride = num(attributes, 'stride', 1);
+                const padding = num(attributes, 'padding', 0);
+                return [o, (h - 1) * stride - 2 * padding + kh, (width - 1) * stride - 2 * padding + kw];
+            },
+            evaluate: ([x, w, b], [xs, ws], attributes, out) => {
+                const [c, h, width] = xs;
+                const [, o, kh, kw] = ws;
+                convTranspose2d(out, x, c, h, width, w, b ?? null, o, kh, kw, num(attributes, 'stride', 1), num(attributes, 'padding', 0));
+            },
+        },
+    ],
+    [
+        'patchEmbed',
+        {
+            ranks: [3, 4, 1],
+            arity: [2, 3],
+            shape: ([x, w], attributes) => {
+                const [c, h, width] = x;
+                const [dim, ci] = w;
+                if (c !== ci)
+                    return `x has ${c} channels and the weight takes ${ci}`;
+                const patch = num(attributes, 'patch');
+                return [Math.floor(h / patch) * Math.floor(width / patch), dim];
+            },
+            evaluate: ([x, w, b], [xs, ws], attributes, out) => {
+                const [c, h, width] = xs;
+                patchEmbed(out, x, c, h, width, w, b ?? null, ws[0], num(attributes, 'patch'));
+            },
+        },
+    ],
+    [
+        'resize',
+        {
+            ranks: [3],
+            arity: [1, 1],
+            shape: ([x], attributes) => {
+                const stepped = ['stepHeight', 'stepWidth'].filter((name) => name in attributes).length;
+                if (stepped === 1)
+                    return 'a step is given for one axis and not the other';
+                if (stepped === 2 && attributes['alignCorners'] === true) {
+                    return 'a step has no meaning with aligned corners, which fix the corners instead';
+                }
+                const mode = modeOf(attributes);
+                if (mode === undefined)
+                    return `the runtime has no resize mode "${String(attributes['mode'])}"`;
+                if (mode === 'nearest' && attributes['alignCorners'] === true) {
+                    return 'nearest has no aligned corners, as PyTorch has none';
+                }
+                return [x[0], num(attributes, 'height'), num(attributes, 'width')];
+            },
+            evaluate: ([x], [xs], attributes, out) => {
+                const [c, h, width] = xs;
+                const mode = modeOf(attributes) ?? 'bilinear';
+                resize(out, x, c, h, width, num(attributes, 'height'), num(attributes, 'width'), mode, attributes['alignCorners'] === true, stepOf(attributes));
+            },
+        },
+    ],
+    [
+        'maxPool2d',
+        {
+            ranks: [3],
+            arity: [1, 1],
+            shape: ([x], attributes) => {
+                const [c, h, w] = x;
+                const kernel = num(attributes, 'kernel');
+                const stride = num(attributes, 'stride', kernel);
+                if (kernel > h || kernel > w)
+                    return `a window of ${kernel} does not fit ${h} × ${w}`;
+                return [c, Math.floor((h - kernel) / stride) + 1, Math.floor((w - kernel) / stride) + 1];
+            },
+            evaluate: ([x], [xs], attributes, out) => {
+                const [c, h, w] = xs;
+                const kernel = num(attributes, 'kernel');
+                maxPool2d(out, x, c, h, w, kernel, num(attributes, 'stride', kernel));
+            },
+        },
+    ],
+];

package/dist/tileHash.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Content addressing for latent tiles: the same surface stored once however many assets use it.
+ *
+ * **One mechanism doing three jobs**, which is why it earns its own module rather than being a
+ * detail of the encoder. The hash is the deduplication key, the streaming unit and the cache key —
+ * so a tile that arrives for one material is already resident for the other thirty-nine that share
+ * it.
+ *
+ * **No seed, no platform dependency, and nothing that varies per process.** A hash that changes
+ * between runs makes the baker non-reproducible, which breaks every content comparison downstream
+ * and does it silently, because the output is still valid — just different.
+ */
+/** FNV-1a over 64 bits, carried as two 32-bit halves because JavaScript has no 64-bit integer. */
+export declare function hashTile(bytes: Uint8Array, offset?: number, length?: number): string;
+export interface TileIndex {
+    /** Slot per hash. */
+    slots: Map<string, number>;
+    /** The bytes each slot holds. */
+    bytes: Uint8Array[];
+}
+export declare function createTileIndex(): TileIndex;
+/**
+ * Give this tile a slot, reusing the one its content already has.
+ *
+ * Returns the slot. Two calls with identical content return the same slot and store one copy,
+ * which is the whole of the deduplication.
+ */
+export declare function internTile(index: TileIndex, hash: string, bytes: Uint8Array): number;
+export declare function tileSlotCount(index: TileIndex): number;

package/dist/tileHash.js

@@ -0,0 +1,50 @@
+/**
+ * Content addressing for latent tiles: the same surface stored once however many assets use it.
+ *
+ * **One mechanism doing three jobs**, which is why it earns its own module rather than being a
+ * detail of the encoder. The hash is the deduplication key, the streaming unit and the cache key —
+ * so a tile that arrives for one material is already resident for the other thirty-nine that share
+ * it.
+ *
+ * **No seed, no platform dependency, and nothing that varies per process.** A hash that changes
+ * between runs makes the baker non-reproducible, which breaks every content comparison downstream
+ * and does it silently, because the output is still valid — just different.
+ */
+/** FNV-1a over 64 bits, carried as two 32-bit halves because JavaScript has no 64-bit integer. */
+export function hashTile(bytes, offset = 0, length = bytes.length - offset) {
+    let lo = 0x84222325;
+    let hi = 0xcbf29ce4;
+    for (let i = 0; i < length; i += 1) {
+        lo ^= bytes[offset + i];
+        /* 64-bit multiply by the FNV prime 0x100000001b3, split across the two halves. */
+        const loLow = lo & 0xffff;
+        const loHigh = lo >>> 16;
+        const l0 = loLow * 0x01b3;
+        const l1 = loHigh * 0x01b3 + (l0 >>> 16);
+        const newLo = ((l1 << 16) | (l0 & 0xffff)) >>> 0;
+        hi = (Math.imul(hi, 0x01b3) + Math.imul(lo, 0x0100) + (l1 >>> 16)) >>> 0;
+        lo = newLo;
+    }
+    return (hi >>> 0).toString(16).padStart(8, '0') + (lo >>> 0).toString(16).padStart(8, '0');
+}
+export function createTileIndex() {
+    return { slots: new Map(), bytes: [] };
+}
+/**
+ * Give this tile a slot, reusing the one its content already has.
+ *
+ * Returns the slot. Two calls with identical content return the same slot and store one copy,
+ * which is the whole of the deduplication.
+ */
+export function internTile(index, hash, bytes) {
+    const existing = index.slots.get(hash);
+    if (existing !== undefined)
+        return existing;
+    const slot = index.bytes.length;
+    index.slots.set(hash, slot);
+    index.bytes.push(bytes);
+    return slot;
+}
+export function tileSlotCount(index) {
+    return index.bytes.length;
+}

package/dist/timeNodes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Time as a sampling argument, which is what makes an animated texture replay-exact.
+ *
+ * **`t` is the caller's, from the simulation's clock, and is never read from a platform.** Every
+ * other engine's animated texture reads a wall clock, so replaying the same simulation shows
+ * different texels — which matters for a rollback session, for a deterministic capture, and for
+ * every automated visual comparison this repository runs.
+ *
+ * **Latent interpolation is why a long animation is nearly free.** A sixty-frame animation shares
+ * one latent and moves only the time slice, so it costs a little more than one frame rather than
+ * sixty times one.
+ */
+/** Which frame of a flipbook this time lands on. Never negative, never past the end. */
+export declare function flipbookFrame(t: number, frames: number, fps: number, loop: boolean): number;
+export interface LerpWeights {
+    a: number;
+    b: number;
+    mix: number;
+}
+/**
+ * The two keys surrounding this time, and how far between them it sits.
+ *
+ * At or past the end it lands on the last key with no mix, rather than wrapping — a caller that
+ * wants looping says so by wrapping `t` before calling.
+ */
+export declare function latentLerpWeights(t: number, keyCount: number, duration: number, out: LerpWeights): void;

package/dist/timeNodes.js

@@ -0,0 +1,48 @@
+/**
+ * Time as a sampling argument, which is what makes an animated texture replay-exact.
+ *
+ * **`t` is the caller's, from the simulation's clock, and is never read from a platform.** Every
+ * other engine's animated texture reads a wall clock, so replaying the same simulation shows
+ * different texels — which matters for a rollback session, for a deterministic capture, and for
+ * every automated visual comparison this repository runs.
+ *
+ * **Latent interpolation is why a long animation is nearly free.** A sixty-frame animation shares
+ * one latent and moves only the time slice, so it costs a little more than one frame rather than
+ * sixty times one.
+ */
+/** Which frame of a flipbook this time lands on. Never negative, never past the end. */
+export function flipbookFrame(t, frames, fps, loop) {
+    if (frames <= 0)
+        return 0;
+    const raw = Math.floor(t * fps);
+    if (loop) {
+        /* Modulo that stays non-negative for negative time, which `%` alone does not. */
+        return ((raw % frames) + frames) % frames;
+    }
+    return Math.min(frames - 1, Math.max(0, raw));
+}
+/**
+ * The two keys surrounding this time, and how far between them it sits.
+ *
+ * At or past the end it lands on the last key with no mix, rather than wrapping — a caller that
+ * wants looping says so by wrapping `t` before calling.
+ */
+export function latentLerpWeights(t, keyCount, duration, out) {
+    if (keyCount <= 1 || duration <= 0) {
+        out.a = 0;
+        out.b = 0;
+        out.mix = 0;
+        return;
+    }
+    const spans = keyCount - 1;
+    const position = Math.min(spans, Math.max(0, (t / duration) * spans));
+    const index = Math.min(spans - 1, Math.floor(position));
+    out.a = index;
+    out.b = index + 1;
+    out.mix = position - index;
+    if (position >= spans) {
+        out.a = spans - 1;
+        out.b = spans;
+        out.mix = 1;
+    }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@driftengine/texture",
+  "version": "4.0.0",
+  "description": "DriftTexture: a texture as a compiled, sampled field rather than an image",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@driftengine/core": "4.0.0"
+  },
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/texture"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgl",
+    "webgpu",
+    "typescript",
+    "texture",
+    "compression",
+    "materials"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/build.mjs @driftengine/texture"
+  }
+}