@driftengine/splats 3.61.0

package/dist/splatLayout.d.ts

@@ -0,0 +1,52 @@
+/** How a capture is laid out in its two textures, shared by both backends so they cannot disagree. */
+/**
+ * Splats per row.
+ *
+ * **A power of two, so the shader's divide is a shift** and the two textures index alike: the data
+ * texture is twice this wide because a splat is two texels, and the order texture is exactly this
+ * wide because a slot is one.
+ *
+ * 1024 puts a million splats in 977 rows, comfortably inside WebGL2's guaranteed 2048 — see
+ * `splatRows`, which is where that limit is checked rather than assumed.
+ */
+export declare const SPLAT_STRIDE = 1024;
+/** How many rows a capture of `count` splats needs. Both textures share it. */
+export declare function splatRows(count: number): number;
+/**
+ * Texels one splat occupies in the data texture, from its record width.
+ *
+ * Two for a capture with no view-dependent colour and three for one with the l=1 band. **A
+ * function of the record rather than a constant**, because the width is the *file's* — a `SPLT`
+ * block carries its own `wordsPerSplat` and `FORMAT.md` §4.7 designed it to grow exactly this way.
+ */
+export declare function splatTexels(wordsPerSplat: number): number;
+/**
+ * Refuse a capture that will not fit, naming both numbers.
+ *
+ * **WebGL2 guarantees `MAX_TEXTURE_SIZE` of 2048**, which at two texels a splat is 2,097,152
+ * splats — so the ceiling is stated here rather than re-derived by whoever hits it. A device
+ * usually offers far more; the guaranteed floor is what a refusal has to be written against,
+ * because a capture that loads on a workstation and refuses on a phone is worse than one that
+ * refuses on both. **A capture with view-dependent colour is three texels a splat**, so its width
+ * is 3,072 and a device at the guaranteed floor refuses it — which is the honest answer rather
+ * than a silently narrower row.
+ */
+export declare function checkSplatCapacity(count: number, maxTextureSize: number, wordsPerSplat?: number): void;
+/** Words per row of the data texture: `SPLAT_STRIDE` splats of `wordsPerSplat` each. */
+export declare function splatRowWords(wordsPerSplat: number): number;
+/**
+ * A source covering exactly `rows` whole rows of packed data, starting at `firstRow`.
+ *
+ * **Both backends need this and only one of them had it, which is how it was found.** A texture
+ * upload takes a *rectangle*, and a capture whose splat count is not a multiple of
+ * `SPLAT_STRIDE` ends in a partial row — so a plain `subarray` to the end of the packed data is
+ * shorter than the rectangle it is being handed to. WebGPU refuses that at `submit` and takes the
+ * command buffer with it; WebGL2 raises `INVALID_OPERATION` and *skips the upload*, which is
+ * worse: the last row keeps whatever it held and the capture draws with up to a thousand splats
+ * missing. Measured as 59,585 pixels between the two backends on a streaming load, at the last
+ * block and no earlier.
+ *
+ * Copies only when the tail is short, which is at most once per capture and at most one row —
+ * 32 KB. The whole-row case is the common one and is a view.
+ */
+export declare function splatRowSource(packed: Uint32Array, firstRow: number, rows: number, wordsPerSplat?: number): Uint32Array;

package/dist/splatLayout.js

@@ -0,0 +1,75 @@
+/** How a capture is laid out in its two textures, shared by both backends so they cannot disagree. */
+/**
+ * Splats per row.
+ *
+ * **A power of two, so the shader's divide is a shift** and the two textures index alike: the data
+ * texture is twice this wide because a splat is two texels, and the order texture is exactly this
+ * wide because a slot is one.
+ *
+ * 1024 puts a million splats in 977 rows, comfortably inside WebGL2's guaranteed 2048 — see
+ * `splatRows`, which is where that limit is checked rather than assumed.
+ */
+export const SPLAT_STRIDE = 1024;
+/** How many rows a capture of `count` splats needs. Both textures share it. */
+export function splatRows(count) {
+    return Math.max(1, Math.ceil(count / SPLAT_STRIDE));
+}
+/**
+ * Texels one splat occupies in the data texture, from its record width.
+ *
+ * Two for a capture with no view-dependent colour and three for one with the l=1 band. **A
+ * function of the record rather than a constant**, because the width is the *file's* — a `SPLT`
+ * block carries its own `wordsPerSplat` and `FORMAT.md` §4.7 designed it to grow exactly this way.
+ */
+export function splatTexels(wordsPerSplat) {
+    return wordsPerSplat / 4;
+}
+/**
+ * Refuse a capture that will not fit, naming both numbers.
+ *
+ * **WebGL2 guarantees `MAX_TEXTURE_SIZE` of 2048**, which at two texels a splat is 2,097,152
+ * splats — so the ceiling is stated here rather than re-derived by whoever hits it. A device
+ * usually offers far more; the guaranteed floor is what a refusal has to be written against,
+ * because a capture that loads on a workstation and refuses on a phone is worse than one that
+ * refuses on both. **A capture with view-dependent colour is three texels a splat**, so its width
+ * is 3,072 and a device at the guaranteed floor refuses it — which is the honest answer rather
+ * than a silently narrower row.
+ */
+export function checkSplatCapacity(count, maxTextureSize, wordsPerSplat = 8) {
+    const rows = splatRows(count);
+    const width = SPLAT_STRIDE * splatTexels(wordsPerSplat);
+    if (rows <= maxTextureSize && width <= maxTextureSize)
+        return;
+    throw new Error(`a capture of ${count} splats needs ${width} by ${rows} texels and this device ` +
+        `allows ${maxTextureSize}. At ${SPLAT_STRIDE} splats a row the ceiling is ` +
+        `${SPLAT_STRIDE * maxTextureSize} splats.`);
+}
+/** Words per row of the data texture: `SPLAT_STRIDE` splats of `wordsPerSplat` each. */
+export function splatRowWords(wordsPerSplat) {
+    return SPLAT_STRIDE * wordsPerSplat;
+}
+/**
+ * A source covering exactly `rows` whole rows of packed data, starting at `firstRow`.
+ *
+ * **Both backends need this and only one of them had it, which is how it was found.** A texture
+ * upload takes a *rectangle*, and a capture whose splat count is not a multiple of
+ * `SPLAT_STRIDE` ends in a partial row — so a plain `subarray` to the end of the packed data is
+ * shorter than the rectangle it is being handed to. WebGPU refuses that at `submit` and takes the
+ * command buffer with it; WebGL2 raises `INVALID_OPERATION` and *skips the upload*, which is
+ * worse: the last row keeps whatever it held and the capture draws with up to a thousand splats
+ * missing. Measured as 59,585 pixels between the two backends on a streaming load, at the last
+ * block and no earlier.
+ *
+ * Copies only when the tail is short, which is at most once per capture and at most one row —
+ * 32 KB. The whole-row case is the common one and is a view.
+ */
+export function splatRowSource(packed, firstRow, rows, wordsPerSplat = 8) {
+    const rowWords = splatRowWords(wordsPerSplat);
+    const from = firstRow * rowWords;
+    const needed = rows * rowWords;
+    if (from + needed <= packed.length)
+        return packed.subarray(from, from + needed);
+    const padded = new Uint32Array(needed);
+    padded.set(packed.subarray(from, Math.min(packed.length, from + needed)));
+    return padded;
+}

package/dist/splatMatrix.d.ts

@@ -0,0 +1,29 @@
+/** The two matrix operations this package needs, written once so no two callers disagree. */
+/**
+ * `out = a * b`, column-major, sixteen multiply-adds and no dependency.
+ *
+ * **Written here rather than pulling in `gl-matrix`**: this package needs one matrix product, a
+ * few times a frame, and a runtime dependency is the thing `AGENTS.md` sets a high bar for. It is
+ * in its own module rather than beside either caller because there are two of them — the pass
+ * folding the clip correction into a projection, and the cull building a clip matrix — and two
+ * copies of one decision is the 2026-08-17 rule however short the decision is.
+ */
+export declare function multiplyMat4(out: Float32Array, a: ArrayLike<number>, b: ArrayLike<number>): void;
+/**
+ * Where the camera sits in a capture's own space, from the view and the model matrices.
+ *
+ * **View-dependent colour needs the direction in the frame the coefficients were trained in**, not
+ * in world space: a capture turned, moved or scaled into a scene by `model` has had its whole
+ * lighting rotated with it, and evaluating the harmonics against a world-space direction produces
+ * a sheen that stays put while the capture turns underneath it.
+ *
+ * The camera is the origin of view space, so the point wanted is `inverse(view * model)` applied
+ * to the origin — which is `−inverse(M3) · t` for the product's 3x3 part and its translation
+ * column, and needs no full 4x4 inverse. A singular 3x3 means a model matrix that collapses the
+ * capture to a plane, and the answer is then the origin rather than a division by zero: a capture
+ * with no volume draws nothing whose colour anybody sees.
+ *
+ * Called once a frame per capture, which is what keeps it off the vertex stage where it would be
+ * once per splat times six.
+ */
+export declare function cameraInCaptureSpace(out: Float32Array, view: ArrayLike<number>, model: ArrayLike<number>): void;

package/dist/splatMatrix.js

@@ -0,0 +1,68 @@
+/** The two matrix operations this package needs, written once so no two callers disagree. */
+/**
+ * `out = a * b`, column-major, sixteen multiply-adds and no dependency.
+ *
+ * **Written here rather than pulling in `gl-matrix`**: this package needs one matrix product, a
+ * few times a frame, and a runtime dependency is the thing `AGENTS.md` sets a high bar for. It is
+ * in its own module rather than beside either caller because there are two of them — the pass
+ * folding the clip correction into a projection, and the cull building a clip matrix — and two
+ * copies of one decision is the 2026-08-17 rule however short the decision is.
+ */
+export function multiplyMat4(out, a, b) {
+    for (let column = 0; column < 4; column++) {
+        const b0 = b[column * 4] ?? 0;
+        const b1 = b[column * 4 + 1] ?? 0;
+        const b2 = b[column * 4 + 2] ?? 0;
+        const b3 = b[column * 4 + 3] ?? 0;
+        for (let row = 0; row < 4; row++) {
+            out[column * 4 + row] =
+                (a[row] ?? 0) * b0 +
+                    (a[4 + row] ?? 0) * b1 +
+                    (a[8 + row] ?? 0) * b2 +
+                    (a[12 + row] ?? 0) * b3;
+        }
+    }
+}
+/**
+ * Where the camera sits in a capture's own space, from the view and the model matrices.
+ *
+ * **View-dependent colour needs the direction in the frame the coefficients were trained in**, not
+ * in world space: a capture turned, moved or scaled into a scene by `model` has had its whole
+ * lighting rotated with it, and evaluating the harmonics against a world-space direction produces
+ * a sheen that stays put while the capture turns underneath it.
+ *
+ * The camera is the origin of view space, so the point wanted is `inverse(view * model)` applied
+ * to the origin — which is `−inverse(M3) · t` for the product's 3x3 part and its translation
+ * column, and needs no full 4x4 inverse. A singular 3x3 means a model matrix that collapses the
+ * capture to a plane, and the answer is then the origin rather than a division by zero: a capture
+ * with no volume draws nothing whose colour anybody sees.
+ *
+ * Called once a frame per capture, which is what keeps it off the vertex stage where it would be
+ * once per splat times six.
+ */
+export function cameraInCaptureSpace(out, view, model) {
+    multiplyMat4(PRODUCT, view, model);
+    const m = PRODUCT;
+    const a = m[0] ?? 0, b = m[4] ?? 0, c = m[8] ?? 0;
+    const d = m[1] ?? 0, e = m[5] ?? 0, f = m[9] ?? 0;
+    const g = m[2] ?? 0, h = m[6] ?? 0, i = m[10] ?? 0;
+    const cofactor0 = e * i - f * h;
+    const cofactor1 = f * g - d * i;
+    const cofactor2 = d * h - e * g;
+    const determinant = a * cofactor0 + b * cofactor1 + c * cofactor2;
+    if (determinant === 0 || !Number.isFinite(determinant)) {
+        out[0] = 0;
+        out[1] = 0;
+        out[2] = 0;
+        return;
+    }
+    const inverse = 1 / determinant;
+    const tx = m[12] ?? 0;
+    const ty = m[13] ?? 0;
+    const tz = m[14] ?? 0;
+    out[0] = -(cofactor0 * tx + (c * h - b * i) * ty + (b * f - c * e) * tz) * inverse;
+    out[1] = -(cofactor1 * tx + (a * i - c * g) * ty + (c * d - a * f) * tz) * inverse;
+    out[2] = -(cofactor2 * tx + (b * g - a * h) * ty + (a * e - b * d) * tz) * inverse;
+}
+/** Scratch for the product above, so a frame allocates nothing. */
+const PRODUCT = new Float32Array(16);

package/dist/splatPass.d.ts

@@ -0,0 +1,83 @@
+/** A splat capture as a pass a consumer registers, drawn by whichever backend it is handed. */
+import type { SplatData } from './splatData.ts';
+import type { PassDefinition } from '@driftengine/core';
+/**
+ * What a consumer hands the pass each frame.
+ *
+ * **The camera comes from the caller rather than from the renderer**, because `PassContext`
+ * carries what the *frame* is and not what is being looked at — and a contributed pass has no
+ * business reaching into the renderer for a matrix the caller already has. It is the same shape
+ * every draw verb takes: the caller says where it is looking.
+ */
+export interface SplatView {
+    /**
+     * Column-major, as `Camera` publishes them.
+     *
+     * `ArrayLike<number>` rather than `Float32Array` because that is what `gl-matrix`'s `mat4` is,
+     * and a consumer handing over `camera.view` should not have to cast a matrix the engine gave it.
+     */
+    readonly view: ArrayLike<number>;
+    readonly projection: ArrayLike<number>;
+    /** In pixels, because the ellipse is built in pixel space. */
+    readonly widthPx: number;
+    readonly heightPx: number;
+}
+export interface SplatPass extends PassDefinition {
+    /** Called once a frame, before `drawPass`. Allocates nothing. */
+    setView(view: SplatView): void;
+    /**
+     * A new draw order, far to near. Four bytes a splat, into storage allocated once.
+     *
+     * Until one is set the pass draws nothing: an unsorted capture composited back to front is
+     * wrong at every silhouette, and drawing it anyway would look like a working feature.
+     */
+    setOrder(order: Uint32Array, count: number): void;
+    /**
+     * The capture's own transform, so two captures compose in one scene.
+     *
+     * **Two batches are two orders and there is no order between them**, and that is a real limit
+     * rather than an omission. Each sorter ranks its own splats along the view direction expressed
+     * in that batch's space, so the two are each internally correct and the renderer draws one
+     * batch's whole cloud before the other's. Where they occupy different volumes — a statue and the
+     * room behind it — nothing shows. Where they interpenetrate, the seam is visible as a plane at
+     * which one capture starts winning every blend.
+     *
+     * What that buys is that a batch's positions never move: one transform on the camera instead of
+     * a million on the splats, every frame. What would make it wrong is a scene built from
+     * overlapping parts, where the answer is one batch with one order rather than a merge — merging
+     * two sorted orders is cheap, but the splats would still be drawn from two textures with two
+     * draw calls, so the merge has nowhere to go.
+     */
+    setModel(model: ArrayLike<number>): void;
+    /**
+     * Push a run of splats that has just arrived into the data texture.
+     *
+     * **For a capture that is still streaming**, where the textures were sized for the final count
+     * at registration and are filled block by block — see `SplatCapture`. A caller that packed its
+     * whole capture before registering the pass never needs this: `init` uploads everything.
+     *
+     * Whole rows are re-sent, so calling this with overlapping ranges is correct and merely costs
+     * a few kilobytes; calling it every frame with the whole capture is not, and is the per-frame
+     * upload the scheduler exists to avoid.
+     */
+    uploadSplats(from: number, count: number): void;
+    /**
+     * Whether the capture reaches the frame at all, as of the last `setView`.
+     *
+     * **Read this before asking a sorter for a new order.** A capture out of frame costs one
+     * discarded draw call and a whole linear sort over every splat it has, and the sort is the
+     * expensive half — so the caller's frame should skip `SplatSorter.frame` when this is false.
+     * `draw` checks it too, but by then the sort has already happened.
+     */
+    readonly visible: boolean;
+    readonly count: number;
+}
+/**
+ * Build a pass for one capture.
+ *
+ * **The consumer decides where it lands in the frame**, by calling `drawPass` at that point. The
+ * documented slot is **after opaque and translucent meshes, before particles and light volumes**:
+ * splats are scene content that particles and beams are drawn *through*, and the depth test that
+ * makes the composition work only sees geometry drawn before it.
+ */
+export declare function createSplatPass(splats: SplatData, label?: string): SplatPass;

package/dist/splatPass.js

@@ -0,0 +1,206 @@
+/** A splat capture as a pass a consumer registers, drawn by whichever backend it is handed. */
+import { SPLAT_BINDINGS } from './shaders/generated/splat.wgsl.js';
+import { SPLAT_STRIDE, splatRows, splatTexels } from './splatLayout.js';
+import { cameraInCaptureSpace, multiplyMat4 } from './splatMatrix.js';
+import { splatBoundsVisible } from './splatCull.js';
+import { createWebgl2Splats, disposeWebgl2Splats, drawWebgl2Splats, uploadWebgl2Order, uploadWebgl2SplatRange, } from './splatGl.js';
+import { createGpuSplats, disposeGpuSplats, uploadGpuOrder, uploadGpuSplatRange, } from './splatGpu.js';
+const VERT = SPLAT_BINDINGS.SPLAT_VERT;
+const FRAG = SPLAT_BINDINGS.SPLAT_FRAG;
+const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+/**
+ * Build a pass for one capture.
+ *
+ * **The consumer decides where it lands in the frame**, by calling `drawPass` at that point. The
+ * documented slot is **after opaque and translucent meshes, before particles and light volumes**:
+ * splats are scene content that particles and beams are drawn *through*, and the depth test that
+ * makes the composition work only sees geometry drawn before it.
+ */
+export function createSplatPass(splats, label = 'splats') {
+    let gl = null;
+    let gpu = null;
+    let device = null;
+    const rows = splatRows(splats.count);
+    /* One padded row buffer, reused by every order upload so a re-sort allocates nothing. */
+    const paddedOrder = new Uint32Array(SPLAT_STRIDE * rows);
+    const model = new Float32Array(IDENTITY);
+    let drawCount = 0;
+    let pendingOrder = null;
+    /** A span of newly arrived splats waiting for a WebGL2 context. See `uploadSplats`. */
+    let pendingRange = null;
+    const view = new Float32Array(16);
+    /** The caller's projection, pre-multiplied by the backend's clip correction. */
+    const projection = new Float32Array(16);
+    /**
+     * Where the camera is in the capture's own space, which is where the harmonics were trained.
+     *
+     * Recomputed whenever the view or the model changes rather than every frame, because both are
+     * setters and neither is called more than once a frame. Zero for a capture with no harmonics,
+     * where nothing reads it.
+     */
+    const cameraLocal = new Float32Array(3);
+    const shDegree = splats.shDegree;
+    const texels = splatTexels(splats.wordsPerSplat);
+    /* Identity until `init`, so a `setView` before registration is not silently zeroed. */
+    let clipCorrection = IDENTITY;
+    let viewportX = 1;
+    let viewportY = 1;
+    /* True until the first `setView`, so a caller that never sets one still draws. */
+    let visible = true;
+    const writeVertexUniforms = (target) => {
+        const f = target.vertexFloats;
+        const i = target.vertexInts;
+        i[VERT.fields.uSplatCount.offset / 4] = drawCount;
+        i[VERT.fields.uSplatStride.offset / 4] = SPLAT_STRIDE;
+        i[VERT.fields.uSplatTexels.offset / 4] = texels;
+        i[VERT.fields.uSplatShDegree.offset / 4] = shDegree;
+        f.set(cameraLocal, VERT.fields.uSplatCameraLocal.offset / 4);
+        f.set(view, VERT.fields.uView.offset / 4);
+        f.set(projection, VERT.fields.uProjection.offset / 4);
+        f[VERT.fields.uViewport.offset / 4] = viewportX;
+        f[VERT.fields.uViewport.offset / 4 + 1] = viewportY;
+        f.set(model, VERT.fields.uModel.offset / 4);
+    };
+    return {
+        label,
+        init(passDevice) {
+            /*
+             * **The clip correction the renderer's own verbs use, not a copy of it.** WebGPU's
+             * framebuffer origin is the top-left and OpenGL's is the bottom-left, and the engine settles
+             * that in the matrix rather than in the shaders. This pass takes its camera from its caller,
+             * so it never sees the corrected matrix — without this it drew the world upside down on
+             * WebGPU, which is exactly the first frame that backend ever produced.
+             */
+            clipCorrection = passDevice.clipCorrection;
+            if (passDevice.backend === 'webgl2') {
+                gl = createWebgl2Splats(passDevice.gl, splats, label);
+                return;
+            }
+            device = passDevice.device;
+            gpu = createGpuSplats(passDevice.device, passDevice.format, passDevice.depthFormat, passDevice.samples, splats, label);
+        },
+        setView(next) {
+            view.set(next.view);
+            multiplyMat4(projection, clipCorrection, next.projection);
+            viewportX = next.widthPx;
+            viewportY = next.heightPx;
+            /*
+             * Culled against the caller's **uncorrected** projection, because the frustum planes come
+             * out of it in the convention `mat4.perspective` writes; the corrected one has moved z into
+             * [0, 1] and flipped y, and its near plane would be a different plane.
+             */
+            visible = splatBoundsVisible(next.view, next.projection, model, splats.boundsMin, splats.boundsMax);
+            if (shDegree > 0)
+                cameraInCaptureSpace(cameraLocal, view, model);
+        },
+        setModel(next) {
+            model.set(next);
+            /* The camera's place in the capture's space moves when either matrix does, and a model set
+               after a view would otherwise evaluate the harmonics against the previous placement. */
+            if (shDegree > 0)
+                cameraInCaptureSpace(cameraLocal, view, model);
+        },
+        uploadSplats(from, count) {
+            const first = Math.max(0, Math.min(from, splats.count));
+            const howMany = Math.max(0, Math.min(count, splats.count - first));
+            if (howMany <= 0)
+                return;
+            if (gpu !== null && device !== null) {
+                uploadGpuSplatRange(device, gpu, splats.packed, first, howMany);
+                return;
+            }
+            /*
+             * WebGL2 has no context outside `draw`, so the range is remembered and pushed there — the
+             * same reason `setOrder` holds a pending order. Ranges are merged rather than queued
+             * because they arrive in file order and a merged span re-sends whole rows anyway.
+             */
+            if (pendingRange === null)
+                pendingRange = { from: first, to: first + howMany };
+            else {
+                pendingRange.from = Math.min(pendingRange.from, first);
+                pendingRange.to = Math.max(pendingRange.to, first + howMany);
+            }
+        },
+        setOrder(order, count) {
+            drawCount = Math.max(0, Math.min(count, splats.count));
+            /*
+             * Held rather than uploaded here, because a consumer may sort before the pass has a device:
+             * `registerPass` runs `init` at registration, but a sorter finishing first is ordinary and
+             * dropping its result would leave the capture blank until the view turned again.
+             */
+            pendingOrder = order;
+            if (gl !== null) {
+                // The upload needs a context, which only `draw` is handed on this backend.
+                return;
+            }
+            if (gpu !== null && device !== null) {
+                uploadGpuOrder(device, gpu, order, paddedOrder);
+                pendingOrder = null;
+            }
+        },
+        draw(ctx) {
+            if (drawCount <= 0 || !visible)
+                return;
+            if (ctx.backend === 'webgl2') {
+                if (gl === null)
+                    return;
+                if (pendingRange !== null) {
+                    uploadWebgl2SplatRange(ctx.gl, gl, splats.packed, pendingRange.from, pendingRange.to - pendingRange.from);
+                    pendingRange = null;
+                }
+                if (pendingOrder !== null) {
+                    uploadWebgl2Order(ctx.gl, gl, pendingOrder, paddedOrder);
+                    pendingOrder = null;
+                }
+                const { uniforms } = gl;
+                ctx.gl.useProgram(gl.program);
+                ctx.gl.uniform1i(uniforms['uSplatCount'] ?? null, drawCount);
+                ctx.gl.uniform1i(uniforms['uSplatStride'] ?? null, SPLAT_STRIDE);
+                ctx.gl.uniform1i(uniforms['uSplatTexels'] ?? null, texels);
+                ctx.gl.uniform1i(uniforms['uSplatShDegree'] ?? null, shDegree);
+                ctx.gl.uniform3fv(uniforms['uSplatCameraLocal'] ?? null, cameraLocal);
+                ctx.gl.uniformMatrix4fv(uniforms['uView'] ?? null, false, view);
+                ctx.gl.uniformMatrix4fv(uniforms['uProjection'] ?? null, false, projection);
+                ctx.gl.uniform2f(uniforms['uViewport'] ?? null, viewportX, viewportY);
+                ctx.gl.uniformMatrix4fv(uniforms['uModel'] ?? null, false, model);
+                /* The frame's own grade, per `PassContext`: this is a forward pass and may be last. */
+                ctx.gl.uniform1i(uniforms['uOutputTransform'] ?? null, ctx.outputTransform);
+                ctx.gl.uniform1f(uniforms['uOutputExposure'] ?? null, ctx.outputExposure);
+                drawWebgl2Splats(ctx.gl, gl, drawCount);
+                return;
+            }
+            if (gpu === null || device === null)
+                return;
+            if (pendingOrder !== null) {
+                uploadGpuOrder(device, gpu, pendingOrder, paddedOrder);
+                pendingOrder = null;
+            }
+            writeVertexUniforms(gpu);
+            device.queue.writeBuffer(gpu.vertexUniforms, 0, gpu.vertexScratch);
+            gpu.fragmentInts[FRAG.fields.uOutputTransform.offset / 4] = ctx.outputTransform;
+            gpu.fragmentFloats[FRAG.fields.uOutputExposure.offset / 4] = ctx.outputExposure;
+            device.queue.writeBuffer(gpu.fragmentUniforms, 0, gpu.fragmentScratch);
+            ctx.pass.setPipeline(gpu.pipeline);
+            ctx.pass.setBindGroup(0, gpu.bindGroup);
+            ctx.pass.draw(drawCount * 6);
+        },
+        dispose(passDevice) {
+            if (passDevice.backend === 'webgl2') {
+                if (gl !== null)
+                    disposeWebgl2Splats(passDevice.gl, gl);
+                gl = null;
+                return;
+            }
+            if (gpu !== null)
+                disposeGpuSplats(gpu);
+            gpu = null;
+            device = null;
+        },
+        get visible() {
+            return visible;
+        },
+        get count() {
+            return splats.count;
+        },
+    };
+}

package/dist/splatPly.d.ts

@@ -0,0 +1,14 @@
+/** The `.ply` reader: an ASCII header describing a binary body, as a training run writes it. */
+import type { SplatData } from './splatData.ts';
+/**
+ * Read a `.ply` Gaussian capture.
+ *
+ * **The encodings are the whole of this function's risk.** Scale is stored as its *logarithm* and
+ * opacity as its *logit*, so both are undone here — and here only, because `packSplats` documents
+ * that it takes linear values. Getting the boundary wrong produces a capture that is either
+ * invisible or a solid block, and both have been reported against other viewers as rendering bugs.
+ *
+ * **The file stores rotation as wxyz** — `rot_0` is the real part — and `SplatSource` takes xyzw,
+ * so the reorder happens here for the same reason it happens in the `.splat` reader.
+ */
+export declare function readSplatPly(buffer: ArrayBuffer): SplatData;