@driftengine/splats 3.61.0

package/dist/splatBudget.js

@@ -0,0 +1,45 @@
+/** How many splats a device should be asked to draw, before anybody has measured that device. */
+import { isWeakGpuFamily } from '@driftengine/core';
+/**
+ * The count a part this engine has no evidence against is asked to draw.
+ *
+ * **This is an estimate and it is not measured, which is the first thing to know about it.**
+ * `AGENTS.md` says fidelity is cut on a measurement and not on a fear, and the measurement that
+ * settles this one is a frame time from a real mid-range Android phone drawing a real capture —
+ * which this repository does not have. What is here instead is the arithmetic: a splat pass is
+ * fill-bound, a splat at ±2σ covers a few dozen blended fragments, and a mid-range mobile part has
+ * something under half a gigapixel a frame of blended fill at 60 Hz. Four hundred thousand splats
+ * is what that budget divides into, and it is the range published mobile viewers of this technique
+ * report.
+ *
+ * **What it costs if it is too low** is a capture thinner than the device could have drawn, which
+ * is visible as a sparser cloud and nothing worse. **What would make it wrong** is a measurement,
+ * in either direction, and a consumer holding one should pass its own number rather than wait for
+ * this line to be corrected. `docs/IMPROVEMENTS.md` carries it as an open measurement.
+ */
+export const SPLAT_BUDGET_DEFAULT = 400_000;
+/**
+ * The count a part measured to struggle with the good profile is asked to draw.
+ *
+ * The same estimate against the family `isWeakGpuFamily` names — an Adreno 619 measured at 156 ms
+ * a frame on this engine's desktop profile, an Adreno 710 at 112 ms, a UHD 630 unplayable
+ * fullscreen. Those are three to ten times the frame time the default is reasoned against, so this
+ * is the default cut by that factor rather than a second guess.
+ */
+export const SPLAT_BUDGET_WEAK = 120_000;
+/**
+ * The budget to hand `SplatSorter` when the consumer has no number of its own.
+ *
+ * Takes the renderer's own name — `renderer.rendererName`, which every backend answers — rather
+ * than reaching for an adapter itself, because `AGENTS.md`'s rule is that a package takes a
+ * platform capability as a parameter and never queries one.
+ *
+ * **An unknown part is not weak**, which is `isWeakGpuFamily`'s own decision and the reason it is
+ * reused rather than re-tabulated here: a device table is wrong about every GPU nobody has tested,
+ * and guessing weak on the unknown thins a capture for every part released after this line.
+ */
+export function defaultSplatBudget(rendererName) {
+    if (rendererName !== undefined && isWeakGpuFamily(rendererName))
+        return SPLAT_BUDGET_WEAK;
+    return SPLAT_BUDGET_DEFAULT;
+}

package/dist/splatCapture.d.ts

@@ -0,0 +1,76 @@
+/** A capture that fills up as its blocks arrive, sized once from the count the first one names. */
+import type { SplatData } from './splatData.ts';
+export interface SplatCaptureOptions {
+    /** Splats in the whole capture. Every array is allocated for this and never grows. */
+    readonly total: number;
+    /** The whole capture's extent, which a `.drft` block carries in its own header. */
+    readonly boundsMin: ArrayLike<number>;
+    readonly boundsMax: ArrayLike<number>;
+    /** Coefficients the source carried, of which the shader reads the first band. Recorded. */
+    readonly sphericalHarmonics?: number;
+    /**
+     * Words in one record, from the block's own header.
+     *
+     * **Taken from the file rather than assumed**, which is what `FORMAT.md` §4.7 designed the field
+     * for: a capture with degree-1 view-dependent colour writes twelve where one without writes
+     * eight, and a streaming reader that hard-coded the width would read the second block's records
+     * at the wrong offset and draw a cloud of noise. Defaults to `SPLAT_WORDS` so a caller with no
+     * container behind it is unaffected.
+     */
+    readonly wordsPerSplat?: number;
+}
+/** Where a block landed, so a caller uploads what arrived rather than the whole texture. */
+export interface SplatAppend {
+    readonly from: number;
+    readonly count: number;
+}
+/**
+ * A capture assembled from blocks, one `.drft` chunk at a time.
+ *
+ * **Allocated once at the final count and filled progressively**, which is what makes a streaming
+ * load cost nothing extra: the GPU textures are sized for the whole capture at registration, each
+ * block is a sub-upload into storage that already exists, and the drawn count rises. Growing an
+ * array as blocks land would mean reallocating and re-uploading a capture's worth of texels
+ * several times during a load, which is more work than the load itself.
+ *
+ * **Every block is a sparse version of the whole capture**, because the container writes them
+ * that way — see `coarseFirstOrder`. So a prefix of the arrived splats is a recognisable place at
+ * lower density rather than one finished corner, and the load opens on something worth looking
+ * at. That property lives in the writer; what lives here is that nothing is re-ordered or
+ * re-allocated on the way in.
+ *
+ * The unarrived tail is zeroed, which puts it at the origin with no size. Nothing draws it: the
+ * caller sorts and draws `ready` splats and the sorter is told the same number.
+ */
+export declare class SplatCapture {
+    readonly data: SplatData;
+    private arrived;
+    private readonly words;
+    constructor(options: SplatCaptureOptions);
+    /** How many splats have landed. The count to sort, to draw and to upload up to. */
+    get ready(): number;
+    /**
+     * Copy one block's records in, deriving what the CPU needs from what the file carried.
+     *
+     * **Positions and extents come back out of the records rather than being stored beside them**,
+     * which is the whole reason a `.drft` splat block is thirty-two bytes a splat rather than
+     * forty-eight: the first three words are the position's own float bits and the eighth is the
+     * extent's. See `packSplats`, which is what puts them there.
+     */
+    append(records: Uint32Array, count: number): SplatAppend;
+}
+/**
+ * A whole capture in one go, for a caller that read the file rather than streamed it.
+ *
+ * The same assembly `SplatCapture` does per block, without the object — `readDrft` hands back
+ * every block already joined, so there is nothing left to append to.
+ */
+export declare function splatsFromRecords(source: {
+    readonly count: number;
+    readonly records: Uint32Array;
+    readonly boundsMin: ArrayLike<number>;
+    readonly boundsMax: ArrayLike<number>;
+    readonly sphericalHarmonics?: number;
+    /** The block's own record width. See `SplatCaptureOptions.wordsPerSplat`. */
+    readonly wordsPerSplat?: number;
+}): SplatData;

package/dist/splatCapture.js

@@ -0,0 +1,108 @@
+/** A capture that fills up as its blocks arrive, sized once from the count the first one names. */
+import { SPLAT_WORDS, SPLAT_WORDS_SH1 } from './splatData.js';
+/**
+ * A capture assembled from blocks, one `.drft` chunk at a time.
+ *
+ * **Allocated once at the final count and filled progressively**, which is what makes a streaming
+ * load cost nothing extra: the GPU textures are sized for the whole capture at registration, each
+ * block is a sub-upload into storage that already exists, and the drawn count rises. Growing an
+ * array as blocks land would mean reallocating and re-uploading a capture's worth of texels
+ * several times during a load, which is more work than the load itself.
+ *
+ * **Every block is a sparse version of the whole capture**, because the container writes them
+ * that way — see `coarseFirstOrder`. So a prefix of the arrived splats is a recognisable place at
+ * lower density rather than one finished corner, and the load opens on something worth looking
+ * at. That property lives in the writer; what lives here is that nothing is re-ordered or
+ * re-allocated on the way in.
+ *
+ * The unarrived tail is zeroed, which puts it at the origin with no size. Nothing draws it: the
+ * caller sorts and draws `ready` splats and the sorter is told the same number.
+ */
+export class SplatCapture {
+    data;
+    arrived = 0;
+    words;
+    constructor(options) {
+        const total = Math.max(0, options.total);
+        this.words = options.wordsPerSplat ?? SPLAT_WORDS;
+        this.data = {
+            count: total,
+            positions: new Float32Array(total * 3),
+            packed: new Uint32Array(total * this.words),
+            wordsPerSplat: this.words,
+            shDegree: this.words >= SPLAT_WORDS_SH1 ? 1 : 0,
+            extents: new Float32Array(total),
+            boundsMin: new Float32Array([
+                options.boundsMin[0] ?? 0,
+                options.boundsMin[1] ?? 0,
+                options.boundsMin[2] ?? 0,
+            ]),
+            boundsMax: new Float32Array([
+                options.boundsMax[0] ?? 0,
+                options.boundsMax[1] ?? 0,
+                options.boundsMax[2] ?? 0,
+            ]),
+            sphericalHarmonics: options.sphericalHarmonics ?? 0,
+        };
+    }
+    /** How many splats have landed. The count to sort, to draw and to upload up to. */
+    get ready() {
+        return this.arrived;
+    }
+    /**
+     * Copy one block's records in, deriving what the CPU needs from what the file carried.
+     *
+     * **Positions and extents come back out of the records rather than being stored beside them**,
+     * which is the whole reason a `.drft` splat block is thirty-two bytes a splat rather than
+     * forty-eight: the first three words are the position's own float bits and the eighth is the
+     * extent's. See `packSplats`, which is what puts them there.
+     */
+    append(records, count) {
+        if (count < 0 || this.arrived + count > this.data.count) {
+            throw new Error(`splats: a block of ${count} splats lands at ${this.arrived} in a capture of ` +
+                `${this.data.count} splats, which does not fit`);
+        }
+        if (records.length < count * this.words) {
+            throw new Error(`splats: ${count} splats need ${count * this.words} entries and the block has ` +
+                `${records.length}`);
+        }
+        const from = this.arrived;
+        this.data.packed.set(records.subarray(0, count * this.words), from * this.words);
+        /*
+         * Reinterpreting, not converting — the same inverse the shader applies. Going through a
+         * `Float32Array` view of the destination rather than of the source, because the source may be
+         * a view over the file at any four-byte offset and the destination is this capture's own
+         * buffer at a known one.
+         */
+        const asFloat = new Float32Array(this.data.packed.buffer);
+        for (let slot = 0; slot < count; slot++) {
+            const splat = from + slot;
+            const at = splat * this.words;
+            this.data.positions[splat * 3] = asFloat[at] ?? 0;
+            this.data.positions[splat * 3 + 1] = asFloat[at + 1] ?? 0;
+            this.data.positions[splat * 3 + 2] = asFloat[at + 2] ?? 0;
+            this.data.extents[splat] = asFloat[at + 7] ?? 0;
+        }
+        this.arrived += count;
+        return { from, count };
+    }
+}
+/**
+ * A whole capture in one go, for a caller that read the file rather than streamed it.
+ *
+ * The same assembly `SplatCapture` does per block, without the object — `readDrft` hands back
+ * every block already joined, so there is nothing left to append to.
+ */
+export function splatsFromRecords(source) {
+    const capture = new SplatCapture({
+        total: source.count,
+        boundsMin: source.boundsMin,
+        boundsMax: source.boundsMax,
+        ...(source.wordsPerSplat === undefined ? {} : { wordsPerSplat: source.wordsPerSplat }),
+        ...(source.sphericalHarmonics === undefined
+            ? {}
+            : { sphericalHarmonics: source.sphericalHarmonics }),
+    });
+    capture.append(source.records, source.count);
+    return capture.data;
+}

package/dist/splatCull.d.ts

@@ -0,0 +1,25 @@
+/** Whether a capture's own bounding box reaches the frame at all, decided before anything sorts. */
+/**
+ * Is any part of the box `[boundsMin, boundsMax]` inside the frustum?
+ *
+ * The box is in the **capture's own space**, which is why this takes the model matrix rather than
+ * a world-space box: `SplatData` computes its bounds while the packing loop is open, in whatever
+ * frame the capture was authored in, and moving the box every frame would be work to reach the
+ * same answer as moving the planes.
+ *
+ * **Answered before the sort, not after, and that is where the saving is.** Drawing a capture that
+ * is out of frame costs one draw call the rasteriser throws away; *sorting* it costs a linear pass
+ * over every splat it has, in a worker, for a picture nobody sees. Culling after the sort would
+ * save the cheap half.
+ *
+ * **Conservative: a box that touches the frustum is visible.** The test is whether some plane has
+ * the whole box behind it, which is exact for rejection and admits a few boxes near a corner that
+ * are outside every plane pairwise but inside none singly. What that costs is a sort for a capture
+ * just off the corner of the frame; what would make it wrong is the opposite error, which loses a
+ * picture — so the asymmetry is deliberate.
+ *
+ * `projection` is the caller's own, **before** the backend's clip correction: the planes below are
+ * the OpenGL convention that `mat4.perspective` produces, and a corrected matrix has moved z into
+ * [0, 1] and flipped y, so the near plane extracted from one would be wrong.
+ */
+export declare function splatBoundsVisible(view: ArrayLike<number>, projection: ArrayLike<number>, model: ArrayLike<number>, boundsMin: ArrayLike<number>, boundsMax: ArrayLike<number>): boolean;

package/dist/splatCull.js

@@ -0,0 +1,80 @@
+/** Whether a capture's own bounding box reaches the frame at all, decided before anything sorts. */
+import { multiplyMat4 } from './splatMatrix.js';
+/* Scratch at module scope, so a per-frame visibility test allocates nothing. Safe to share
+   between two batches because this is synchronous: no second call runs inside one. */
+const viewModel = new Float32Array(16);
+const clip = new Float32Array(16);
+/** Six planes, four numbers each: a, b, c, d with `a x + b y + c z + d >= 0` inside. */
+const planes = new Float32Array(24);
+/**
+ * Is any part of the box `[boundsMin, boundsMax]` inside the frustum?
+ *
+ * The box is in the **capture's own space**, which is why this takes the model matrix rather than
+ * a world-space box: `SplatData` computes its bounds while the packing loop is open, in whatever
+ * frame the capture was authored in, and moving the box every frame would be work to reach the
+ * same answer as moving the planes.
+ *
+ * **Answered before the sort, not after, and that is where the saving is.** Drawing a capture that
+ * is out of frame costs one draw call the rasteriser throws away; *sorting* it costs a linear pass
+ * over every splat it has, in a worker, for a picture nobody sees. Culling after the sort would
+ * save the cheap half.
+ *
+ * **Conservative: a box that touches the frustum is visible.** The test is whether some plane has
+ * the whole box behind it, which is exact for rejection and admits a few boxes near a corner that
+ * are outside every plane pairwise but inside none singly. What that costs is a sort for a capture
+ * just off the corner of the frame; what would make it wrong is the opposite error, which loses a
+ * picture — so the asymmetry is deliberate.
+ *
+ * `projection` is the caller's own, **before** the backend's clip correction: the planes below are
+ * the OpenGL convention that `mat4.perspective` produces, and a corrected matrix has moved z into
+ * [0, 1] and flipped y, so the near plane extracted from one would be wrong.
+ */
+export function splatBoundsVisible(view, projection, model, boundsMin, boundsMax) {
+    multiplyMat4(viewModel, view, model);
+    multiplyMat4(clip, projection, viewModel);
+    /*
+     * Gribb and Hartmann: the clip-space inequalities `-w <= x <= w` and so on are linear in the
+     * object-space point, so each is a plane whose coefficients are a sum or difference of two rows
+     * of the matrix. A row of a column-major matrix is every fourth entry, which is why the strides
+     * below look transposed.
+     */
+    for (let axis = 0; axis < 3; axis++) {
+        for (let component = 0; component < 4; component++) {
+            const w = clip[component * 4 + 3] ?? 0;
+            const a = clip[component * 4 + axis] ?? 0;
+            /* Two planes per axis: w + a is the low side, w - a the high one. */
+            planes[axis * 8 + component] = w + a;
+            planes[axis * 8 + 4 + component] = w - a;
+        }
+    }
+    const minX = boundsMin[0] ?? 0;
+    const minY = boundsMin[1] ?? 0;
+    const minZ = boundsMin[2] ?? 0;
+    const maxX = boundsMax[0] ?? 0;
+    const maxY = boundsMax[1] ?? 0;
+    const maxZ = boundsMax[2] ?? 0;
+    for (let plane = 0; plane < 6; plane++) {
+        const at = plane * 4;
+        const a = planes[at] ?? 0;
+        const b = planes[at + 1] ?? 0;
+        const c = planes[at + 2] ?? 0;
+        const d = planes[at + 3] ?? 0;
+        /*
+         * The box's corner **furthest along this plane's normal**, picked component by component.
+         * Testing that one decides the whole box: if even the corner most in front of the plane is
+         * behind it, all eight are — six dot products rather than forty-eight.
+         *
+         * **The opposite corner is the trap, and it looks equally plausible.** Taking the corner
+         * furthest *behind* the plane rejects every box that is partly behind one, which throws away
+         * any capture straddling the near plane and any capture the camera is standing inside — the
+         * two cases a room-scale capture is made of. Both are asserted in `splatCull.test.ts` for
+         * that reason, and both failed on the first writing of this line.
+         */
+        const x = a >= 0 ? maxX : minX;
+        const y = b >= 0 ? maxY : minY;
+        const z = c >= 0 ? maxZ : minZ;
+        if (a * x + b * y + c * z + d < 0)
+            return false;
+    }
+    return true;
+}

package/dist/splatData.d.ts

@@ -0,0 +1,177 @@
+/** The shape every splat reader produces, and the packing that turns it into two GPU texels. */
+/** How many `uint32`s a splat occupies with no view-dependent colour: two `RGBA32UI` texels. */
+export declare 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 declare const SPLAT_WORDS_SH1 = 12;
+/** Three basis functions at l=1, three channels each. */
+export declare const SPLAT_SH1_COEFFICIENTS = 9;
+/**
+ * A capture as a reader hands it over: linear values, one array per attribute.
+ *
+ * **Linear, and that boundary is load-bearing.** A `.ply` from a training run stores scale as its
+ * logarithm and opacity as its logit, and undoing both is the *reader's* job rather than this
+ * one's. Getting the boundary wrong produces a capture that is either invisible or a solid block,
+ * and both have been reported against other viewers — because both look like a rendering fault.
+ */
+export interface SplatSource {
+    readonly count: number;
+    /** Three per splat, in the capture's own space. */
+    readonly positions: Float32Array;
+    /** Three per splat: the Gaussian's standard deviation along each of its own axes, in metres. */
+    readonly scales: Float32Array;
+    /**
+     * Four per splat, **xyzw**, normalised here rather than trusted.
+     *
+     * **Both file formats store wxyz and this does not**, which is a deliberate seam: `xyzw` is what
+     * `gl-matrix` uses and what every other quaternion in this engine is, so a consumer building a
+     * source by hand is not asked to learn a second convention for one type. Each reader reorders on
+     * the way in, in one line, at the point where the file's order is already on screen.
+     */
+    readonly rotations: Float32Array;
+    /**
+     * Three per splat, 0 to 1, **linear**.
+     *
+     * Not sRGB-decoded, which is what every reference viewer does and is also what is correct here:
+     * a capture's colour comes from a spherical-harmonic DC term, which is linear radiance, and this
+     * engine shades and composites in linear and grades once at the end. What would make it wrong is
+     * a capture authored by a tool that baked a display transform into the DC term — which produces
+     * a washed-out cloud, not a subtly wrong one.
+     */
+    readonly colors: Float32Array;
+    /** One per splat, 0 to 1, already through the logistic if the format stored a logit. */
+    readonly opacities: Float32Array;
+    /**
+     * The l=1 spherical-harmonic band, nine per splat, or absent for a capture that has none.
+     *
+     * **Interleaved by basis function and then by channel** — `Y(1,−1).rgb`, `Y(1,0).rgb`,
+     * `Y(1,1).rgb` — which is *not* how a `.ply` stores them. That file is channel-major, all
+     * fifteen of red before all fifteen of green, and the reader transposes on the way in for the
+     * reason every other reordering in this package happens there: the file's own order is on
+     * screen at exactly one place, and a shader that had to know it would be a second copy of a
+     * convention nothing checks.
+     *
+     * Raw coefficients, signed, in the same units the training run wrote — the band constant is the
+     * shader's to apply, like `SH_C0` is the reader's for the DC term.
+     */
+    readonly sh1?: Float32Array;
+}
+/**
+ * A capture packed for the GPU, plus the two things the CPU still needs.
+ *
+ * **`positions` survives packing because the sorter reads it every time the view turns**, and it is
+ * the only per-splat attribute that does. Everything else is in `packed` and is never looked at
+ * again by JavaScript.
+ *
+ * **This takes ownership of the arrays handed to `packSplats`.** They are twelve and four bytes a
+ * splat, so copying a million-splat capture would be sixteen megabytes of duplicate to no purpose;
+ * the cost is that a caller must not go on mutating a source after packing it, which is stated
+ * here because nothing enforces it.
+ */
+export interface SplatData {
+    readonly count: number;
+    /** Three per splat. See above: the sorter's input, and the reason this is not packed away. */
+    readonly positions: Float32Array;
+    /**
+     * `wordsPerSplat` per splat — texel 0 is position and colour, texel 1 is the covariance, and
+     * texel 2 is the l=1 band where the capture carries one.
+     */
+    readonly packed: Uint32Array;
+    /**
+     * `SPLAT_WORDS` or `SPLAT_WORDS_SH1`. Everything that indexes `packed` reads this rather than a
+     * constant, and `FORMAT.md` §4.7 anticipated exactly this: a `SPLT` block already carries its
+     * own `wordsPerSplat` and says "a capture that carries spherical-harmonic coefficients later
+     * fits by raising it and nothing else".
+     */
+    readonly wordsPerSplat: number;
+    /** The capture's axis-aligned extent, for the frustum test that precedes a sort. */
+    readonly boundsMin: Float32Array;
+    readonly boundsMax: Float32Array;
+    /**
+     * One per splat: the largest of its three standard deviations, in the capture's own units.
+     *
+     * **What the budget ranks by, and the second attribute that survives packing.** A splat's
+     * contribution to the picture is roughly how many pixels it covers, which is its world extent
+     * over its distance to the camera; the distance is per-frame and this is the half that is not.
+     * The largest sigma bounds the projected radius from above for every orientation, so it ranks
+     * correctly without a per-splat projection.
+     *
+     * What it costs is **four bytes a splat** — four megabytes at a million, on top of the twelve
+     * `positions` already keeps — and it is paid whether or not a capture is ever budgeted, because
+     * packing cannot know. What would make it wrong is a capture of extremely flat splats seen
+     * edge-on, where the largest sigma is a poor estimate of the pixels covered and this
+     * over-ranks them; the honest fix there is the projected radius, which is per-frame work this
+     * deliberately avoids.
+     */
+    readonly extents: Float32Array;
+    /**
+     * How many `f_rest_*` coefficients the source carried, of which this kept the first band.
+     *
+     * Zero for a format that has none. **Nine are read as of 2026-08-27 and the rest are not**, and
+     * the costing that decided which is below, kept because it is the argument against raising it.
+     *
+     * ## What view-dependent colour costs, costed 2026-08-27 and built the same day
+     *
+     * A splat with no harmonics is `SPLAT_WORDS` uint32s — two `RGBA32UI` texels, **32 bytes** — and
+     * the vertex stage runs **six times a splat**, because the quad is two unindexed triangles and
+     * `SPLAT_VERT` says why. Every invocation fetches every texel, so the data texture is read at
+     * **192 bytes a splat a frame** before any texture cache.
+     *
+     * A degree-`n` expansion carries `((n+1)^2 − 1) * 3` coefficients:
+     *
+     * | Degree | Coefficients | Extra texels | Bytes a splat | Read a splat a frame |
+     * |---|---|---|---|---|
+     * | 0 | 0 | 0 | 32 | 192 |
+     * | 1 **(built)** | 9 | 1 | 48 | 288 |
+     * | 2 | 24 | 3 | 80 | 480 |
+     * | 3 | 45 | 6 | 128 | 768 |
+     *
+     * **Against the mobile budget of `SPLAT_BUDGET_DEFAULT`, 400,000 splats**: 76.8 MB a frame at
+     * degree 0, 115.2 at degree 1, 192 at degree 2 and **307.2 at degree 3**. `docs/CAPABILITIES.md`
+     * records a mid-range phone already moving **388.7 MB a frame of attachment traffic**, so degree 3
+     * would very nearly double the memory traffic of a frame on the device that is already the
+     * constraint — and the texture itself would grow from 12.8 MB to 51 MB, which is the mistake
+     * `lightBudget.ts`'s shadow pool records making once already.
+     *
+     * **Degree 1 is the band that earns its texel.** The l=1 lobe is broad and directional — it is
+     * what makes glass, a wet surface and a polished floor read as themselves — where degrees 2 and 3
+     * are the sharp specular detail that costs four and six times as much. Nine coefficients fit one
+     * texel as **bytes with a per-splat scale beside them**, rather than halves: nine halves is 18
+     * bytes and would not fit, and a per-splat scale spends the sixteenth byte on the accuracy that
+     * quantising to a capture-wide range would have thrown away.
+     *
+     * **What is still unmeasured**, and it is the number that would refine this: how much of the 6x
+     * amplification a real texture cache absorbs, since six consecutive invocations read the same
+     * texels. Answering it needs a GPU timing of the splat pass against a capture, and this checkout
+     * has none — `demo/dev/public/` being uncommitted.
+     */
+    readonly sphericalHarmonics: number;
+    /**
+     * How many bands of that expansion this capture actually carries: 0 or 1.
+     *
+     * Separate from `sphericalHarmonics`, which counts what the *source* had — a `.ply` written at
+     * degree 3 reports 45 there and 1 here, because forty-five coefficients arrived and nine were
+     * kept. The two disagreeing is the honest state rather than a discrepancy.
+     */
+    readonly shDegree: 0 | 1;
+}
+/**
+ * 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 declare function packSplats(source: SplatSource): SplatData;