@driftengine/splats 3.61.0

package/dist/splatData.js

@@ -0,0 +1,223 @@
+/** The shape every splat reader produces, and the packing that turns it into two GPU texels. */
+import { packHalf2x16 } from './half.js';
+/** How many `uint32`s a splat occupies with no view-dependent colour: two `RGBA32UI` texels. */
+export const SPLAT_WORDS = 8;
+/**
+ * The same with degree-1 view-dependent colour: **one more texel**, and no more than one.
+ *
+ * The costing in `sphericalHarmonics` below is what picked degree 1 and it is worth reading before
+ * anybody raises this. Nine coefficients fit a texel as bytes with a per-splat scale beside them,
+ * which is +50% on the record and on the read; degree 2 is three more texels and degree 3 is six,
+ * and degree 3 alone would put 307 MB a frame through a device already carrying 389.
+ */
+export const SPLAT_WORDS_SH1 = 12;
+/** Three basis functions at l=1, three channels each. */
+export const SPLAT_SH1_COEFFICIENTS = 9;
+/* Scratch for one splat's rotation matrix, so the packing loop allocates nothing. */
+const rotation = new Float32Array(9);
+/**
+ * Turn a source into two texels per splat, and compute the capture's bounds while the loop is open.
+ *
+ * Texel 0 is the three position floats reinterpreted as `uint32` plus the colour as `RGBA8`.
+ * Texel 1 is the six unique terms of the 3x3 covariance as three half pairs, with the fourth
+ * component reserved and written zero.
+ *
+ * **The covariance is computed here and never again.** It is fixed for the lifetime of a capture,
+ * so evaluating it per splat per frame would cost a quaternion-to-matrix and two 3x3 multiplies
+ * for a value that cannot change. What that gives up is six halves of precision against the
+ * source's floats; what would make it wrong is a capture whose splats are animated, which is not a
+ * thing this format can express.
+ */
+export function packSplats(source) {
+    const { count, positions, scales, rotations, colors, opacities, sh1 } = source;
+    expectLength('positions', positions, count * 3);
+    expectLength('scales', scales, count * 3);
+    expectLength('rotations', rotations, count * 4);
+    expectLength('colors', colors, count * 3);
+    expectLength('opacities', opacities, count);
+    if (sh1 !== undefined)
+        expectLength('sh1', sh1, count * SPLAT_SH1_COEFFICIENTS);
+    const wordsPerSplat = sh1 === undefined ? SPLAT_WORDS : SPLAT_WORDS_SH1;
+    const packed = new Uint32Array(count * wordsPerSplat);
+    /* Reinterpreting rather than converting: the shader reads these back with the inverse. */
+    const asFloat = new Float32Array(packed.buffer);
+    const boundsMin = new Float32Array([Infinity, Infinity, Infinity]);
+    const boundsMax = new Float32Array([-Infinity, -Infinity, -Infinity]);
+    const extents = new Float32Array(count);
+    for (let index = 0; index < count; index++) {
+        const at = index * wordsPerSplat;
+        const p = index * 3;
+        const x = positions[p] ?? 0;
+        const y = positions[p + 1] ?? 0;
+        const z = positions[p + 2] ?? 0;
+        asFloat[at] = x;
+        asFloat[at + 1] = y;
+        asFloat[at + 2] = z;
+        if (x < (boundsMin[0] ?? 0))
+            boundsMin[0] = x;
+        if (y < (boundsMin[1] ?? 0))
+            boundsMin[1] = y;
+        if (z < (boundsMin[2] ?? 0))
+            boundsMin[2] = z;
+        if (x > (boundsMax[0] ?? 0))
+            boundsMax[0] = x;
+        if (y > (boundsMax[1] ?? 0))
+            boundsMax[1] = y;
+        if (z > (boundsMax[2] ?? 0))
+            boundsMax[2] = z;
+        /* `unpackUnorm4x8` reads the lowest byte as x, so red goes in the lowest byte. */
+        packed[at + 3] =
+            (byte(colors[p]) |
+                (byte(colors[p + 1]) << 8) |
+                (byte(colors[p + 2]) << 16) |
+                (byte(opacities[index]) << 24)) >>>
+                0;
+        quaternionToMatrix(rotations, index * 4, index);
+        /*
+         * Sigma = R diag(s^2) R^T, six unique terms. Written as a sum over the three columns rather
+         * than as two matrix products, which is the same arithmetic with nothing to allocate: column
+         * j of R scaled by s_j is column j of R*S, and Sigma[i][k] is the dot of rows i and k of that.
+         */
+        const sx = scales[p] ?? 0;
+        const sy = scales[p + 1] ?? 0;
+        const sz = scales[p + 2] ?? 0;
+        extents[index] = Math.max(sx, sy, sz);
+        const w0 = sx * sx;
+        const w1 = sy * sy;
+        const w2 = sz * sz;
+        const r00 = rotation[0] ?? 0;
+        const r01 = rotation[1] ?? 0;
+        const r02 = rotation[2] ?? 0;
+        const r10 = rotation[3] ?? 0;
+        const r11 = rotation[4] ?? 0;
+        const r12 = rotation[5] ?? 0;
+        const r20 = rotation[6] ?? 0;
+        const r21 = rotation[7] ?? 0;
+        const r22 = rotation[8] ?? 0;
+        const xx = r00 * r00 * w0 + r01 * r01 * w1 + r02 * r02 * w2;
+        const xy = r00 * r10 * w0 + r01 * r11 * w1 + r02 * r12 * w2;
+        const xz = r00 * r20 * w0 + r01 * r21 * w1 + r02 * r22 * w2;
+        const yy = r10 * r10 * w0 + r11 * r11 * w1 + r12 * r12 * w2;
+        const yz = r10 * r20 * w0 + r11 * r21 * w1 + r12 * r22 * w2;
+        const zz = r20 * r20 * w0 + r21 * r21 * w1 + r22 * r22 * w2;
+        packed[at + 4] = packHalf2x16(xx, xy);
+        packed[at + 5] = packHalf2x16(xz, yy);
+        packed[at + 6] = packHalf2x16(yz, zz);
+        /*
+         * The extent, as float bits, in what texel one's fourth component would otherwise waste.
+         *
+         * **The GPU never reads it** — the vertex stage takes three of that texel's four components
+         * for the covariance — so this costs the draw nothing and it means a `.drft` splat block can
+         * be exactly the packed record. Carrying a parallel four bytes a splat instead would be
+         * twelve percent on the one payload this engine most wants small. `extents` still exists
+         * beside it because the sort reads it in a tight loop, where reinterpreting bits per access
+         * would not be free. What would make this wrong is a later shader wanting that component for
+         * something else, at which point the block grows a ninth word and says so in its header.
+         */
+        asFloat[at + 7] = extents[index] ?? 0;
+        if (sh1 !== undefined)
+            packSh1(sh1, index, packed, asFloat, at + 8);
+    }
+    /* A capture of nothing has no extent, and Infinity in a bound is a frustum test that never
+       answers. Collapse to the origin, which a zero-count batch never reaches anyway. */
+    if (count === 0) {
+        boundsMin.fill(0);
+        boundsMax.fill(0);
+    }
+    return {
+        count,
+        positions,
+        packed,
+        wordsPerSplat,
+        boundsMin,
+        boundsMax,
+        extents,
+        sphericalHarmonics: 0,
+        shDegree: sh1 === undefined ? 0 : 1,
+    };
+}
+/**
+ * One splat's l=1 band into one `RGBA32UI` texel: nine bytes and a scale.
+ *
+ * **Bytes with a per-splat scale, and both halves of that are the decision.** Nine halves would be
+ * eighteen bytes and would not fit a texel at all; nine bytes against a *capture-wide* range would
+ * fit and would spend most of the range on the few splats with the largest coefficients, leaving
+ * the ordinary ones quantised to a handful of levels. A per-splat scale costs the sixteenth byte —
+ * which is four bytes as a float, filling the texel exactly — and gives every splat the whole
+ * 8-bit range for its own coefficients.
+ *
+ * A splat whose band is all zero gets a scale of zero and nine mid-range bytes, which the shader
+ * multiplies back to exactly zero. That is the common case in a capture's flat regions and it
+ * costs nothing to say so.
+ *
+ * The three spare bytes of the third word are written zero rather than left as whatever the
+ * allocation held: a `.drft` block is compared byte for byte by `drft-diff`, and a record with
+ * uninitialised padding is a file that differs from itself.
+ */
+function packSh1(sh1, index, packed, asFloat, at) {
+    const from = index * SPLAT_SH1_COEFFICIENTS;
+    let scale = 0;
+    for (let k = 0; k < SPLAT_SH1_COEFFICIENTS; k++) {
+        const magnitude = Math.abs(sh1[from + k] ?? 0);
+        if (magnitude > scale)
+            scale = magnitude;
+    }
+    const inverse = scale > 0 ? 1 / scale : 0;
+    /* Centre of the range, which is exactly zero once the scale multiplies it back. */
+    const quantise = (value) => Math.max(0, Math.min(255, Math.round((value ?? 0) * inverse * 127 + 128)));
+    packed[at] =
+        (quantise(sh1[from] ?? 0) |
+            (quantise(sh1[from + 1] ?? 0) << 8) |
+            (quantise(sh1[from + 2] ?? 0) << 16) |
+            (quantise(sh1[from + 3] ?? 0) << 24)) >>>
+            0;
+    packed[at + 1] =
+        (quantise(sh1[from + 4] ?? 0) |
+            (quantise(sh1[from + 5] ?? 0) << 8) |
+            (quantise(sh1[from + 6] ?? 0) << 16) |
+            (quantise(sh1[from + 7] ?? 0) << 24)) >>>
+            0;
+    packed[at + 2] = quantise(sh1[from + 8] ?? 0) >>> 0;
+    asFloat[at + 3] = scale;
+}
+/**
+ * Fill `rotation` from a quaternion at `offset`, normalising on the way.
+ *
+ * **A zero quaternion is a refusal naming the splat**, not a silent identity and not a `NaN` that
+ * reaches the GPU. A NaN covariance produces a splat whose ellipse fails every comparison, which
+ * on most drivers is an invisible splat and on some is one that covers the screen — and neither
+ * points at the file that caused it.
+ */
+function quaternionToMatrix(source, offset, index) {
+    const qx = source[offset] ?? 0;
+    const qy = source[offset + 1] ?? 0;
+    const qz = source[offset + 2] ?? 0;
+    const qw = source[offset + 3] ?? 0;
+    const length = Math.hypot(qx, qy, qz, qw);
+    if (length === 0 || !Number.isFinite(length)) {
+        throw new Error(`splat ${index} carries a rotation of length ${length}, which names no orientation. ` +
+            'A capture with a zero or non-finite quaternion is malformed at the source.');
+    }
+    const x = qx / length;
+    const y = qy / length;
+    const z = qz / length;
+    const w = qw / length;
+    rotation[0] = 1 - 2 * (y * y + z * z);
+    rotation[1] = 2 * (x * y - w * z);
+    rotation[2] = 2 * (x * z + w * y);
+    rotation[3] = 2 * (x * y + w * z);
+    rotation[4] = 1 - 2 * (x * x + z * z);
+    rotation[5] = 2 * (y * z - w * x);
+    rotation[6] = 2 * (x * z - w * y);
+    rotation[7] = 2 * (y * z + w * x);
+    rotation[8] = 1 - 2 * (x * x + y * y);
+}
+function byte(value) {
+    const clamped = Math.max(0, Math.min(1, value ?? 0));
+    return Math.round(clamped * 255);
+}
+function expectLength(name, array, expected) {
+    if (array.length === expected)
+        return;
+    throw new Error(`${name} has ${array.length} entries where a capture of this count needs ${expected}.`);
+}

package/dist/splatGl.d.ts

@@ -0,0 +1,49 @@
+/** The WebGL2 half of the splat pass: two integer textures, one program, no vertex state at all. */
+import type { SplatData } from './splatData.ts';
+export interface Webgl2Splats {
+    readonly program: WebGLProgram;
+    readonly vao: WebGLVertexArrayObject;
+    readonly data: WebGLTexture;
+    readonly order: WebGLTexture;
+    readonly uniforms: Readonly<Record<string, WebGLUniformLocation | null>>;
+    readonly rows: number;
+    /** Two, or three for a capture with view-dependent colour. See `splatTexels`. */
+    readonly texels: number;
+}
+/**
+ * Build the program, the two textures and the empty vertex array.
+ *
+ * **The vertex array holds nothing and still has to exist.** The geometry is `gl_VertexID`
+ * arithmetic, so there is no buffer to describe — but a draw with the default vertex array bound
+ * is invalid in a core WebGL2 context, which `demo/contributedPass.ts` already records.
+ */
+export declare function createWebgl2Splats(gl: WebGL2RenderingContext, splats: SplatData, label: string): Webgl2Splats;
+/**
+ * Upload a new draw order. Four bytes a splat and nothing else moves.
+ *
+ * **`texSubImage2D` into storage allocated once**, never a reallocation: this runs whenever the
+ * view has turned enough to want a re-sort, and allocating a texture per sort is the per-frame
+ * allocation the house rules are about.
+ */
+export declare function uploadWebgl2Order(gl: WebGL2RenderingContext, splats: Webgl2Splats, order: Uint32Array, padded: Uint32Array): void;
+/**
+ * Upload a run of splats that has just arrived, and nothing else.
+ *
+ * **Whole rows at a time**, because `texSubImage2D` takes a rectangle and a partial row is a
+ * second call with different arithmetic for no gain: a row is 1,024 splats, so rounding a block
+ * out to row boundaries re-sends at most 32 KB and the row a block ends in is re-sent once when
+ * the next block completes it. A capture streams in a handful of blocks, so that is a few
+ * kilobytes over a load rather than a per-frame cost.
+ */
+export declare function uploadWebgl2SplatRange(gl: WebGL2RenderingContext, splats: Webgl2Splats, packed: Uint32Array, from: number, count: number): void;
+/**
+ * Draw, and put back every piece of state this borrowed.
+ *
+ * **The contract in `PassDefinition.draw`**: the renderer's own verbs assume what they left, and a
+ * leaked blend function is the class of bug that shows up three scenes away. Depth *test* on and
+ * depth *write* off is the composition claim — a wall in front of a capture occludes it, and a
+ * Gaussian has no surface to occlude anything with, so a cloud that wrote depth would cull its
+ * own tail.
+ */
+export declare function drawWebgl2Splats(gl: WebGL2RenderingContext, splats: Webgl2Splats, count: number): void;
+export declare function disposeWebgl2Splats(gl: WebGL2RenderingContext, splats: Webgl2Splats): void;

package/dist/splatGl.js

@@ -0,0 +1,176 @@
+/** The WebGL2 half of the splat pass: two integer textures, one program, no vertex state at all. */
+import { SPLAT_STRIDE, checkSplatCapacity, splatRowSource, splatRows, splatTexels, } from './splatLayout.js';
+import { SPLAT_FRAG, SPLAT_VERT } from './shaders/splat.js';
+/** Texture units this pass borrows. High, so they cannot collide with the lit pass's sixteen. */
+const DATA_UNIT = 12;
+const ORDER_UNIT = 13;
+function compile(gl, kind, source, label) {
+    const shader = gl.createShader(kind);
+    if (shader === null)
+        throw new Error(`${label}: createShader failed`);
+    gl.shaderSource(shader, source);
+    gl.compileShader(shader);
+    /*
+     * Checked at init and never in the frame, which is the reliability rule: fail fast and loud at
+     * construction with a message somebody can act on, and never throw once the loop is running.
+     */
+    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+        const log = gl.getShaderInfoLog(shader) ?? '(no log)';
+        gl.deleteShader(shader);
+        throw new Error(`${label}: ${log}`);
+    }
+    return shader;
+}
+/**
+ * Build the program, the two textures and the empty vertex array.
+ *
+ * **The vertex array holds nothing and still has to exist.** The geometry is `gl_VertexID`
+ * arithmetic, so there is no buffer to describe — but a draw with the default vertex array bound
+ * is invalid in a core WebGL2 context, which `demo/contributedPass.ts` already records.
+ */
+export function createWebgl2Splats(gl, splats, label) {
+    checkSplatCapacity(splats.count, gl.getParameter(gl.MAX_TEXTURE_SIZE), splats.wordsPerSplat);
+    const texels = splatTexels(splats.wordsPerSplat);
+    const program = gl.createProgram();
+    if (program === null)
+        throw new Error(`${label}: createProgram failed`);
+    const vert = compile(gl, gl.VERTEX_SHADER, SPLAT_VERT, `${label} vertex`);
+    const frag = compile(gl, gl.FRAGMENT_SHADER, SPLAT_FRAG, `${label} fragment`);
+    gl.attachShader(program, vert);
+    gl.attachShader(program, frag);
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+        const log = gl.getProgramInfoLog(program) ?? '(no log)';
+        throw new Error(`${label}: link failed — ${log}`);
+    }
+    /* Attached shaders are reference-counted by the program; deleting the objects frees the source
+       without touching the linked binary. */
+    gl.deleteShader(vert);
+    gl.deleteShader(frag);
+    const names = [
+        'uSplatData',
+        'uSplatOrder',
+        'uSplatCount',
+        'uSplatStride',
+        'uView',
+        'uProjection',
+        'uViewport',
+        'uModel',
+        'uOutputTransform',
+        'uOutputExposure',
+        'uSplatTexels',
+        'uSplatShDegree',
+        'uSplatCameraLocal',
+    ];
+    const uniforms = {};
+    for (const name of names)
+        uniforms[name] = gl.getUniformLocation(program, name);
+    const rows = splatRows(splats.count);
+    const data = gl.createTexture();
+    if (data === null)
+        throw new Error(`${label}: createTexture failed`);
+    gl.bindTexture(gl.TEXTURE_2D, data);
+    /*
+     * `RGBA32UI` with nearest filtering and no mips: the contents are bit patterns rather than
+     * colours, so there is nothing meaningful to interpolate between two splats' packed floats. An
+     * integer format cannot be filtered at all in core WebGL2, which makes this required rather
+     * than merely correct.
+     */
+    gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA32UI, SPLAT_STRIDE * texels, rows);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    /*
+     * Padded to the full rectangle, because `texSubImage2D` of a partial last row is a second call
+     * with different arithmetic and the padding is at most one row of 1024 splats — 32 KB.
+     */
+    const padded = new Uint32Array(SPLAT_STRIDE * texels * rows * 4);
+    padded.set(splats.packed.subarray(0, Math.min(splats.packed.length, padded.length)));
+    gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, SPLAT_STRIDE * texels, rows, gl.RGBA_INTEGER, gl.UNSIGNED_INT, padded);
+    const order = gl.createTexture();
+    if (order === null)
+        throw new Error(`${label}: createTexture failed`);
+    gl.bindTexture(gl.TEXTURE_2D, order);
+    gl.texStorage2D(gl.TEXTURE_2D, 1, gl.R32UI, SPLAT_STRIDE, rows);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    const vao = gl.createVertexArray();
+    if (vao === null)
+        throw new Error(`${label}: createVertexArray failed`);
+    return { program, vao, data, order, uniforms, rows, texels };
+}
+/**
+ * Upload a new draw order. Four bytes a splat and nothing else moves.
+ *
+ * **`texSubImage2D` into storage allocated once**, never a reallocation: this runs whenever the
+ * view has turned enough to want a re-sort, and allocating a texture per sort is the per-frame
+ * allocation the house rules are about.
+ */
+export function uploadWebgl2Order(gl, splats, order, padded) {
+    padded.set(order.subarray(0, Math.min(order.length, padded.length)));
+    gl.bindTexture(gl.TEXTURE_2D, splats.order);
+    gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, SPLAT_STRIDE, splats.rows, gl.RED_INTEGER, gl.UNSIGNED_INT, padded);
+}
+/**
+ * Upload a run of splats that has just arrived, and nothing else.
+ *
+ * **Whole rows at a time**, because `texSubImage2D` takes a rectangle and a partial row is a
+ * second call with different arithmetic for no gain: a row is 1,024 splats, so rounding a block
+ * out to row boundaries re-sends at most 32 KB and the row a block ends in is re-sent once when
+ * the next block completes it. A capture streams in a handful of blocks, so that is a few
+ * kilobytes over a load rather than a per-frame cost.
+ */
+export function uploadWebgl2SplatRange(gl, splats, packed, from, count) {
+    if (count <= 0)
+        return;
+    const firstRow = Math.floor(from / SPLAT_STRIDE);
+    const lastRow = Math.floor((from + count - 1) / SPLAT_STRIDE);
+    const rows = lastRow - firstRow + 1;
+    gl.bindTexture(gl.TEXTURE_2D, splats.data);
+    gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, firstRow, SPLAT_STRIDE * splats.texels, rows, gl.RGBA_INTEGER, gl.UNSIGNED_INT, splatRowSource(packed, firstRow, rows, splats.texels * 4));
+    gl.bindTexture(gl.TEXTURE_2D, null);
+}
+/**
+ * Draw, and put back every piece of state this borrowed.
+ *
+ * **The contract in `PassDefinition.draw`**: the renderer's own verbs assume what they left, and a
+ * leaked blend function is the class of bug that shows up three scenes away. Depth *test* on and
+ * depth *write* off is the composition claim — a wall in front of a capture occludes it, and a
+ * Gaussian has no surface to occlude anything with, so a cloud that wrote depth would cull its
+ * own tail.
+ */
+export function drawWebgl2Splats(gl, splats, count) {
+    if (count <= 0)
+        return;
+    gl.useProgram(splats.program);
+    gl.bindVertexArray(splats.vao);
+    gl.activeTexture(gl.TEXTURE0 + DATA_UNIT);
+    gl.bindTexture(gl.TEXTURE_2D, splats.data);
+    gl.activeTexture(gl.TEXTURE0 + ORDER_UNIT);
+    gl.bindTexture(gl.TEXTURE_2D, splats.order);
+    gl.uniform1i(splats.uniforms['uSplatData'] ?? null, DATA_UNIT);
+    gl.uniform1i(splats.uniforms['uSplatOrder'] ?? null, ORDER_UNIT);
+    const blendWas = gl.getParameter(gl.BLEND);
+    const depthMaskWas = gl.getParameter(gl.DEPTH_WRITEMASK);
+    gl.enable(gl.BLEND);
+    /* Premultiplied `over`, per the plan's decision 1: the fragment stage folds alpha in, so this
+       composes correctly onto a target that already holds opaque geometry. */
+    gl.blendFuncSeparate(gl.ONE, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+    gl.depthMask(false);
+    gl.drawArrays(gl.TRIANGLES, 0, count * 6);
+    gl.depthMask(depthMaskWas);
+    if (!blendWas)
+        gl.disable(gl.BLEND);
+    gl.bindVertexArray(null);
+    gl.activeTexture(gl.TEXTURE0);
+}
+export function disposeWebgl2Splats(gl, splats) {
+    gl.deleteProgram(splats.program);
+    gl.deleteVertexArray(splats.vao);
+    gl.deleteTexture(splats.data);
+    gl.deleteTexture(splats.order);
+}

package/dist/splatGpu.d.ts

@@ -0,0 +1,50 @@
+/** The WebGPU half of the splat pass: the same two integer textures, one pipeline, no vertex state. */
+import type { SplatData } from './splatData.ts';
+export interface GpuSplats {
+    readonly pipeline: GPURenderPipeline;
+    readonly bindGroup: GPUBindGroup;
+    readonly vertexUniforms: GPUBuffer;
+    readonly fragmentUniforms: GPUBuffer;
+    readonly data: GPUTexture;
+    readonly order: GPUTexture;
+    readonly rows: number;
+    /** Two, or three for a capture with view-dependent colour. See `splatTexels`. */
+    readonly texels: number;
+    /**
+     * Scratch for one uniform write, so a frame allocates nothing — **including the views**.
+     *
+     * A `new Float32Array(buffer)` is a view rather than a copy and reads as free, and it is not: it
+     * is an object allocated in the frame loop, once per uniform block per frame, which is exactly
+     * what the house rule forbids. Both views of each block are made here, at construction, and the
+     * pass writes through them.
+     */
+    readonly vertexScratch: ArrayBuffer;
+    readonly vertexFloats: Float32Array;
+    readonly vertexInts: Int32Array;
+    readonly fragmentScratch: ArrayBuffer;
+    readonly fragmentFloats: Float32Array;
+    readonly fragmentInts: Int32Array;
+}
+/**
+ * Build the pipeline, the two textures and the bind group.
+ *
+ * **An explicit bind group layout rather than `layout: 'auto'`, and the reason is the samplers.**
+ * The GLSL declares `usampler2D`, so the transform splits each into a texture and a sampler and
+ * naga emits both — even though the shader only ever calls `textureLoad`. An unused sampler still
+ * has to be bound, and `auto` would infer a **filtering** sampler for it. A `u32` texture is not
+ * filterable in core WebGPU, and binding a filtering sampler beside one is a validation failure
+ * that takes the whole bind group with it — the same trap `AGENTS.md` records against `r32float`.
+ * Declaring the layout says `non-filtering` and `uint`, which is what these are.
+ */
+export declare function createGpuSplats(device: GPUDevice, format: GPUTextureFormat, depthFormat: GPUTextureFormat, samples: number, splats: SplatData, label: string): GpuSplats;
+/**
+ * Upload a run of splats that has just arrived, and nothing else.
+ *
+ * Whole rows, for the reason `uploadWebgl2SplatRange` gives at length: `writeTexture` takes a
+ * rectangle, a row is 1,024 splats, and rounding out to row boundaries costs at most 32 KB
+ * re-sent per block against a second code path for partial rows.
+ */
+export declare function uploadGpuSplatRange(device: GPUDevice, splats: GpuSplats, packed: Uint32Array, from: number, count: number): void;
+/** Upload a new draw order. Four bytes a splat, into storage allocated once. */
+export declare function uploadGpuOrder(device: GPUDevice, splats: GpuSplats, order: Uint32Array, padded: Uint32Array): void;
+export declare function disposeGpuSplats(splats: GpuSplats): void;

package/dist/splatGpu.js

@@ -0,0 +1,180 @@
+/** The WebGPU half of the splat pass: the same two integer textures, one pipeline, no vertex state. */
+import { SPLAT_BINDINGS, SPLAT_FRAG_WGSL, SPLAT_VERT_WGSL, } from './shaders/generated/splat.wgsl.js';
+import { SPLAT_STRIDE, splatRowSource, splatRows, splatTexels } from './splatLayout.js';
+/*
+ * The usage and stage bits as literals, which is the convention every WebGPU pass in core follows:
+ * `GPUTextureUsage` and friends are runtime globals and this package typechecks against a lib that
+ * does not declare them, so naming the numbers is the honest form and the comment is the decoder.
+ */
+const TEXTURE_BINDING_COPY_DST = 0x04 | 0x02;
+const UNIFORM_COPY_DST = 0x0040 | 0x0008;
+const STAGE_VERTEX = 0x1;
+const STAGE_FRAGMENT = 0x2;
+const VERT = SPLAT_BINDINGS.SPLAT_VERT;
+const FRAG = SPLAT_BINDINGS.SPLAT_FRAG;
+/**
+ * Build the pipeline, the two textures and the bind group.
+ *
+ * **An explicit bind group layout rather than `layout: 'auto'`, and the reason is the samplers.**
+ * The GLSL declares `usampler2D`, so the transform splits each into a texture and a sampler and
+ * naga emits both — even though the shader only ever calls `textureLoad`. An unused sampler still
+ * has to be bound, and `auto` would infer a **filtering** sampler for it. A `u32` texture is not
+ * filterable in core WebGPU, and binding a filtering sampler beside one is a validation failure
+ * that takes the whole bind group with it — the same trap `AGENTS.md` records against `r32float`.
+ * Declaring the layout says `non-filtering` and `uint`, which is what these are.
+ */
+export function createGpuSplats(device, format, depthFormat, samples, splats, label) {
+    const rows = splatRows(splats.count);
+    const texels = splatTexels(splats.wordsPerSplat);
+    const data = device.createTexture({
+        label: `${label}.data`,
+        size: { width: SPLAT_STRIDE * texels, height: rows },
+        format: 'rgba32uint',
+        usage: TEXTURE_BINDING_COPY_DST,
+    });
+    const order = device.createTexture({
+        label: `${label}.order`,
+        size: { width: SPLAT_STRIDE, height: rows },
+        format: 'r32uint',
+        usage: TEXTURE_BINDING_COPY_DST,
+    });
+    /*
+     * `bytesPerRow` is the **source** stride, and `writeTexture` does not convert: handing it data
+     * of a different width than the row it is filling is a legal layout that reinterprets bytes.
+     * `AGENTS.md` records that costing a session, so the upload is padded to the full rectangle and
+     * the stride is stated from the format's own texel size.
+     */
+    const padded = new Uint32Array(SPLAT_STRIDE * texels * rows * 4);
+    padded.set(splats.packed.subarray(0, Math.min(splats.packed.length, padded.length)));
+    device.queue.writeTexture({ texture: data }, padded, { bytesPerRow: SPLAT_STRIDE * texels * 16, rowsPerImage: rows }, { width: SPLAT_STRIDE * texels, height: rows });
+    const vertexUniforms = device.createBuffer({
+        label: `${label}.vertexUniforms`,
+        size: VERT.uniformSize,
+        usage: UNIFORM_COPY_DST,
+    });
+    const fragmentUniforms = device.createBuffer({
+        label: `${label}.fragmentUniforms`,
+        size: FRAG.uniformSize,
+        usage: UNIFORM_COPY_DST,
+    });
+    const sampler = device.createSampler({
+        label: `${label}.sampler`,
+        /* Never sampled — declared because the GLSL said `usampler2D`. Non-filtering because a `u32`
+           texture cannot be filtered, and saying otherwise is the validation failure above. */
+        magFilter: 'nearest',
+        minFilter: 'nearest',
+    });
+    const layout = device.createBindGroupLayout({
+        label: `${label}.layout`,
+        entries: [
+            { binding: VERT.uniforms, visibility: STAGE_VERTEX, buffer: { type: 'uniform' } },
+            { binding: FRAG.uniforms, visibility: STAGE_FRAGMENT, buffer: { type: 'uniform' } },
+            {
+                binding: VERT.textures.uSplatData.texture,
+                visibility: STAGE_VERTEX,
+                texture: { sampleType: 'uint' },
+            },
+            {
+                binding: VERT.textures.uSplatData.sampler,
+                visibility: STAGE_VERTEX,
+                sampler: { type: 'non-filtering' },
+            },
+            {
+                binding: VERT.textures.uSplatOrder.texture,
+                visibility: STAGE_VERTEX,
+                texture: { sampleType: 'uint' },
+            },
+            {
+                binding: VERT.textures.uSplatOrder.sampler,
+                visibility: STAGE_VERTEX,
+                sampler: { type: 'non-filtering' },
+            },
+        ],
+    });
+    const bindGroup = device.createBindGroup({
+        label: `${label}.bindGroup`,
+        layout,
+        entries: [
+            { binding: VERT.uniforms, resource: { buffer: vertexUniforms } },
+            { binding: FRAG.uniforms, resource: { buffer: fragmentUniforms } },
+            { binding: VERT.textures.uSplatData.texture, resource: data.createView() },
+            { binding: VERT.textures.uSplatData.sampler, resource: sampler },
+            { binding: VERT.textures.uSplatOrder.texture, resource: order.createView() },
+            { binding: VERT.textures.uSplatOrder.sampler, resource: sampler },
+        ],
+    });
+    const pipeline = device.createRenderPipeline({
+        label,
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: device.createShaderModule({ label: `${label}.vert`, code: SPLAT_VERT_WGSL }),
+            entryPoint: 'main',
+        },
+        fragment: {
+            module: device.createShaderModule({ label: `${label}.frag`, code: SPLAT_FRAG_WGSL }),
+            entryPoint: 'main',
+            targets: [
+                {
+                    format,
+                    /* Premultiplied `over`, matching the WebGL2 half exactly. */
+                    blend: {
+                        color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                    },
+                },
+            ],
+        },
+        primitive: { topology: 'triangle-list' },
+        multisample: { count: samples },
+        /* Tested, never written: a wall in front occludes the capture, and a Gaussian has no surface
+           to occlude with, so a cloud that wrote depth would cull its own tail. */
+        depthStencil: { format: depthFormat, depthWriteEnabled: false, depthCompare: 'less' },
+    });
+    const vertexScratch = new ArrayBuffer(VERT.uniformSize);
+    const fragmentScratch = new ArrayBuffer(FRAG.uniformSize);
+    return {
+        pipeline,
+        bindGroup,
+        vertexUniforms,
+        fragmentUniforms,
+        data,
+        order,
+        rows,
+        texels,
+        vertexScratch,
+        vertexFloats: new Float32Array(vertexScratch),
+        vertexInts: new Int32Array(vertexScratch),
+        fragmentScratch,
+        fragmentFloats: new Float32Array(fragmentScratch),
+        fragmentInts: new Int32Array(fragmentScratch),
+    };
+}
+/**
+ * Upload a run of splats that has just arrived, and nothing else.
+ *
+ * Whole rows, for the reason `uploadWebgl2SplatRange` gives at length: `writeTexture` takes a
+ * rectangle, a row is 1,024 splats, and rounding out to row boundaries costs at most 32 KB
+ * re-sent per block against a second code path for partial rows.
+ */
+export function uploadGpuSplatRange(device, splats, packed, from, count) {
+    if (count <= 0)
+        return;
+    const firstRow = Math.floor(from / SPLAT_STRIDE);
+    const lastRow = Math.floor((from + count - 1) / SPLAT_STRIDE);
+    const rows = lastRow - firstRow + 1;
+    /* Shared with the WebGL2 half rather than written twice: a short tail is a validation failure
+       on this backend and a silently skipped upload on that one, and one of them had the guard. */
+    const source = splatRowSource(packed, firstRow, rows, splats.texels * 4);
+    device.queue.writeTexture({ texture: splats.data, origin: { x: 0, y: firstRow } }, source, { bytesPerRow: SPLAT_STRIDE * splats.texels * 16, rowsPerImage: rows }, { width: SPLAT_STRIDE * splats.texels, height: rows });
+}
+/** Upload a new draw order. Four bytes a splat, into storage allocated once. */
+export function uploadGpuOrder(device, splats, order, padded) {
+    padded.set(order.subarray(0, Math.min(order.length, padded.length)));
+    device.queue.writeTexture({ texture: splats.order }, padded, { bytesPerRow: SPLAT_STRIDE * 4, rowsPerImage: splats.rows }, { width: SPLAT_STRIDE, height: splats.rows });
+}
+export function disposeGpuSplats(splats) {
+    splats.data.destroy();
+    splats.order.destroy();
+    splats.vertexUniforms.destroy();
+    splats.fragmentUniforms.destroy();
+}