@driftengine/splats 3.61.0

package/src/splatGl.ts

@@ -0,0 +1,262 @@
+/** 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.ts';
+import { SPLAT_FRAG, SPLAT_VERT } from './shaders/splat.ts';
+import type { SplatData } from './splatData.ts';
+
+/** Texture units this pass borrows. High, so they cannot collide with the lit pass's sixteen. */
+const DATA_UNIT = 12;
+const ORDER_UNIT = 13;
+
+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;
+}
+
+function compile(
+  gl: WebGL2RenderingContext,
+  kind: number,
+  source: string,
+  label: string,
+): WebGLShader {
+  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: WebGL2RenderingContext,
+  splats: SplatData,
+  label: string,
+): Webgl2Splats {
+  checkSplatCapacity(
+    splats.count,
+    gl.getParameter(gl.MAX_TEXTURE_SIZE) as number,
+    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: Record<string, WebGLUniformLocation | null> = {};
+  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: WebGL2RenderingContext,
+  splats: Webgl2Splats,
+  order: Uint32Array,
+  padded: Uint32Array,
+): void {
+  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: WebGL2RenderingContext,
+  splats: Webgl2Splats,
+  packed: Uint32Array,
+  from: number,
+  count: number,
+): void {
+  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: WebGL2RenderingContext,
+  splats: Webgl2Splats,
+  count: number,
+): void {
+  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) as boolean;
+  const depthMaskWas = gl.getParameter(gl.DEPTH_WRITEMASK) as boolean;
+  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: WebGL2RenderingContext, splats: Webgl2Splats): void {
+  gl.deleteProgram(splats.program);
+  gl.deleteVertexArray(splats.vao);
+  gl.deleteTexture(splats.data);
+  gl.deleteTexture(splats.order);
+}

package/src/splatGpu.ts

@@ -0,0 +1,259 @@
+/** 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.ts';
+import { SPLAT_STRIDE, splatRowSource, splatRows, splatTexels } from './splatLayout.ts';
+import type { SplatData } from './splatData.ts';
+
+/*
+ * 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;
+
+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 function createGpuSplats(
+  device: GPUDevice,
+  format: GPUTextureFormat,
+  depthFormat: GPUTextureFormat,
+  samples: number,
+  splats: SplatData,
+  label: string,
+): GpuSplats {
+  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: GPUDevice,
+  splats: GpuSplats,
+  packed: Uint32Array,
+  from: number,
+  count: number,
+): void {
+  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: GPUDevice,
+  splats: GpuSplats,
+  order: Uint32Array,
+  padded: Uint32Array,
+): void {
+  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: GpuSplats): void {
+  splats.data.destroy();
+  splats.order.destroy();
+  splats.vertexUniforms.destroy();
+  splats.fragmentUniforms.destroy();
+}

package/src/splatLayout.ts

@@ -0,0 +1,86 @@
+/** 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: number): number {
+  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: number): number {
+  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: number, maxTextureSize: number, wordsPerSplat = 8): void {
+  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: number): number {
+  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: Uint32Array,
+  firstRow: number,
+  rows: number,
+  wordsPerSplat = 8,
+): Uint32Array {
+  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/src/splatMatrix.ts

@@ -0,0 +1,81 @@
+/** 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: Float32Array, a: ArrayLike<number>, b: ArrayLike<number>): void {
+  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: Float32Array,
+  view: ArrayLike<number>,
+  model: ArrayLike<number>,
+): void {
+  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);