@downdraft/engine 0.1.1 → 0.2.0

package/dist/libraries/gaussian-splats/src/parser.js

@@ -0,0 +1,297 @@
+// ============================================================================
+// Gaussian splat parsers — PLY (ascii + binary_little_endian) and .splat
+//
+// Outputs a Structure-of-Arrays (SoA) `GaussianSplatData` for direct GPU upload:
+//   position:  Float32Array(count * 3)
+//   scale:     Float32Array(count * 3)   — exp()-transformed
+//   rotation:  Float32Array(count * 4)   — quaternion w,x,y,z, normalized
+//   color:     Float32Array(count * 4)   — r,g,b (DC color) + a (opacity sigmoid)
+//   shCoeffs:  Float32Array(count * SH_REST_COEFFS_PER_DEGREE[shDegree])
+//              raw f_rest coefficients (empty when shDegree === 0)
+//
+// The single-splat `GaussianSplat` tuple type is kept as an escape hatch for
+// callers that want one splat at a time (e.g. debugging, CPU-side queries).
+// ============================================================================
+import { assertBounds, assertCount, MAX_VERTEX_COUNT } from "@downdraft/engine";
+// ── SH coefficient counts ──
+//
+// INRIA PLY stores 3 DC coefficients (f_dc_0..2) and up to 45 "rest"
+// coefficients (f_rest_0..44). The DC term is degree-0; the rest terms cover
+// degrees 1..N. Total SH coeffs for degree N = 3 * (N+1)^2 per splat
+// (3 channels × (N+1)^2 basis functions). DC = 3*1 = 3; rest = total - DC.
+//
+//   degree 0 → 0  rest coeffs (DC only)
+//   degree 1 → 9  rest coeffs (f_rest_0..8)
+//   degree 2 → 24 rest coeffs (f_rest_0..23)
+//   degree 3 → 45 rest coeffs (f_rest_0..44)
+export const SH_REST_COEFFS_PER_DEGREE = [0, 9, 24, 45];
+export const MAX_SH_DEGREE = 3;
+export const SH_REST_COEFFS_MAX = SH_REST_COEFFS_PER_DEGREE[MAX_SH_DEGREE]; // 45
+// ── Helpers ──
+/** SH C0 coefficient → color: color = 0.5 + C0 * 0.282095. */
+const SH_C0 = 0.28209479177387814;
+/** Opacity sigmoid: alpha = 1 / (1 + exp(-opacity)). */
+function sigmoidOpacity(o) {
+    return 1.0 / (1.0 + Math.exp(-o));
+}
+/** Detect SH degree from the number of f_rest properties. */
+function detectShDegree(propertyNames) {
+    let restCount = 0;
+    propertyNames.forEach((name) => {
+        if (name.startsWith("f_rest_"))
+            restCount++;
+    });
+    if (restCount >= 45)
+        return 3;
+    if (restCount >= 24)
+        return 2;
+    if (restCount >= 9)
+        return 1;
+    return 0;
+}
+/** Normalize a quaternion (w, x, y, z) in place into a Float32Array slice. */
+function normalizeQuat(out, base, w, x, y, z) {
+    const len = Math.sqrt(w * w + x * x + y * y + z * z);
+    const inv = len > 0 ? 1.0 / len : 1.0;
+    out[base] = w * inv;
+    out[base + 1] = x * inv;
+    out[base + 2] = y * inv;
+    out[base + 3] = z * inv;
+}
+/** Build an empty (zeroed) GaussianSplatData for `count` splats at `shDegree`. */
+function emptySplatData(count, shDegree, version) {
+    const restCoeffs = SH_REST_COEFFS_PER_DEGREE[shDegree] ?? 0;
+    return {
+        count,
+        shDegree,
+        version,
+        position: new Float32Array(count * 3),
+        scale: new Float32Array(count * 3),
+        rotation: new Float32Array(count * 4),
+        color: new Float32Array(count * 4),
+        shCoeffs: restCoeffs > 0 ? new Float32Array(count * restCoeffs) : new Float32Array(0),
+    };
+}
+// ── PLY header parsing ──
+function readPLYHeader(data) {
+    const text = new TextDecoder().decode(data.slice(0, 2048));
+    const lines = text.split("\n");
+    let vertexCount = 0;
+    const properties = [];
+    const propertyNames = [];
+    let format = "ascii";
+    let headerBytes = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line === "end_header") {
+            // Compute byte offset: sum of (line length + 1 for newline) up to and
+            // including the "end_header" line.
+            let bytes = 0;
+            for (let j = 0; j <= i; j++) {
+                bytes += lines[j].length + 1;
+            }
+            headerBytes = bytes;
+            break;
+        }
+        if (line.startsWith("format")) {
+            format = line.split(/\s+/)[1];
+        }
+        if (line.startsWith("element vertex")) {
+            vertexCount = parseInt(line.split(/\s+/)[2], 10);
+        }
+        if (line.startsWith("property")) {
+            properties.push(line);
+            const parts = line.split(/\s+/);
+            propertyNames.push(parts[parts.length - 1]);
+        }
+    }
+    const shDegree = detectShDegree(propertyNames);
+    return { vertexCount, properties, propertyNames, format, headerBytes, shDegree };
+}
+// ── PLY parsing ──
+export function parsePLY(data) {
+    const header = readPLYHeader(data);
+    assertCount("splats", header.vertexCount, MAX_VERTEX_COUNT);
+    if (header.vertexCount === 0) {
+        return emptySplatData(0, header.shDegree, 1);
+    }
+    if (header.format === "ascii") {
+        return parsePLYAscii(data, header);
+    }
+    if (header.format === "binary_little_endian") {
+        return parsePLYBinaryLE(data, header);
+    }
+    // Unknown format — return empty rather than throw (callers check count).
+    return emptySplatData(0, 0, 1);
+}
+function parsePLYAscii(data, header) {
+    const text = new TextDecoder().decode(data);
+    const lines = text.split("\n");
+    let dataStart = 0;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === "end_header") {
+            dataStart = i + 1;
+            break;
+        }
+    }
+    const count = header.vertexCount;
+    const result = emptySplatData(count, header.shDegree, 1);
+    const propIndex = {};
+    header.propertyNames.forEach((name, i) => { propIndex[name] = i; });
+    const restCoeffs = SH_REST_COEFFS_PER_DEGREE[header.shDegree] ?? 0;
+    for (let i = 0; i < count && dataStart + i < lines.length; i++) {
+        const parts = lines[dataStart + i].trim().split(/\s+/).map(Number);
+        if (parts.length < 3)
+            continue;
+        const i3 = i * 3;
+        const i4 = i * 4;
+        // Position
+        result.position[i3] = parts[propIndex["x"] ?? 0] ?? 0;
+        result.position[i3 + 1] = parts[propIndex["y"] ?? 1] ?? 0;
+        result.position[i3 + 2] = parts[propIndex["z"] ?? 2] ?? 0;
+        // Scale (exp-transform)
+        const s0 = propIndex["scale_0"] !== undefined ? parts[propIndex["scale_0"]] : Math.log(0.01);
+        const s1 = propIndex["scale_1"] !== undefined ? parts[propIndex["scale_1"]] : Math.log(0.01);
+        const s2 = propIndex["scale_2"] !== undefined ? parts[propIndex["scale_2"]] : Math.log(0.01);
+        result.scale[i3] = Math.exp(s0);
+        result.scale[i3 + 1] = Math.exp(s1);
+        result.scale[i3 + 2] = Math.exp(s2);
+        // Rotation (quaternion w,x,y,z, normalized)
+        const rw = propIndex["rot_0"] !== undefined ? parts[propIndex["rot_0"]] : 1;
+        const rx = propIndex["rot_1"] !== undefined ? parts[propIndex["rot_1"]] : 0;
+        const ry = propIndex["rot_2"] !== undefined ? parts[propIndex["rot_2"]] : 0;
+        const rz = propIndex["rot_3"] !== undefined ? parts[propIndex["rot_3"]] : 0;
+        normalizeQuat(result.rotation, i4, rw, rx, ry, rz);
+        // DC color + opacity
+        const r = propIndex["f_dc_0"] !== undefined ? parts[propIndex["f_dc_0"]] : 0.5;
+        const g = propIndex["f_dc_1"] !== undefined ? parts[propIndex["f_dc_1"]] : 0.5;
+        const b = propIndex["f_dc_2"] !== undefined ? parts[propIndex["f_dc_2"]] : 0.5;
+        const o = propIndex["opacity"] !== undefined ? parts[propIndex["opacity"]] : 0;
+        result.color[i4] = Math.max(0, Math.min(1, 0.5 + r * SH_C0));
+        result.color[i4 + 1] = Math.max(0, Math.min(1, 0.5 + g * SH_C0));
+        result.color[i4 + 2] = Math.max(0, Math.min(1, 0.5 + b * SH_C0));
+        result.color[i4 + 3] = sigmoidOpacity(o);
+        // SH rest coefficients
+        if (restCoeffs > 0) {
+            const shBase = i * restCoeffs;
+            for (let c = 0; c < restCoeffs; c++) {
+                const key = `f_rest_${c}`;
+                result.shCoeffs[shBase + c] = propIndex[key] !== undefined ? parts[propIndex[key]] : 0;
+            }
+        }
+    }
+    return result;
+}
+function parsePLYBinaryLE(data, header) {
+    const offset = header.headerBytes;
+    const count = header.vertexCount;
+    const stride = header.properties.length * 4; // all float32
+    assertBounds("splats binary data", offset, count * stride, data.byteLength);
+    const view = new DataView(data.buffer, data.byteOffset + offset, count * stride);
+    const result = emptySplatData(count, header.shDegree, 1);
+    const propIndex = {};
+    header.propertyNames.forEach((name, i) => { propIndex[name] = i; });
+    const restCoeffs = SH_REST_COEFFS_PER_DEGREE[header.shDegree] ?? 0;
+    for (let i = 0; i < count; i++) {
+        const base = i * stride;
+        const i3 = i * 3;
+        const i4 = i * 4;
+        // Position
+        result.position[i3] = view.getFloat32(base + (propIndex["x"] ?? 0) * 4, true);
+        result.position[i3 + 1] = view.getFloat32(base + (propIndex["y"] ?? 1) * 4, true);
+        result.position[i3 + 2] = view.getFloat32(base + (propIndex["z"] ?? 2) * 4, true);
+        // Scale (exp-transform)
+        const s0 = propIndex["scale_0"] !== undefined ? view.getFloat32(base + propIndex["scale_0"] * 4, true) : Math.log(0.01);
+        const s1 = propIndex["scale_1"] !== undefined ? view.getFloat32(base + propIndex["scale_1"] * 4, true) : Math.log(0.01);
+        const s2 = propIndex["scale_2"] !== undefined ? view.getFloat32(base + propIndex["scale_2"] * 4, true) : Math.log(0.01);
+        result.scale[i3] = Math.exp(s0);
+        result.scale[i3 + 1] = Math.exp(s1);
+        result.scale[i3 + 2] = Math.exp(s2);
+        // Rotation (quaternion w,x,y,z, normalized)
+        const rw = propIndex["rot_0"] !== undefined ? view.getFloat32(base + propIndex["rot_0"] * 4, true) : 1;
+        const rx = propIndex["rot_1"] !== undefined ? view.getFloat32(base + propIndex["rot_1"] * 4, true) : 0;
+        const ry = propIndex["rot_2"] !== undefined ? view.getFloat32(base + propIndex["rot_2"] * 4, true) : 0;
+        const rz = propIndex["rot_3"] !== undefined ? view.getFloat32(base + propIndex["rot_3"] * 4, true) : 0;
+        normalizeQuat(result.rotation, i4, rw, rx, ry, rz);
+        // DC color + opacity
+        const r = propIndex["f_dc_0"] !== undefined ? view.getFloat32(base + propIndex["f_dc_0"] * 4, true) : 0.5;
+        const g = propIndex["f_dc_1"] !== undefined ? view.getFloat32(base + propIndex["f_dc_1"] * 4, true) : 0.5;
+        const b = propIndex["f_dc_2"] !== undefined ? view.getFloat32(base + propIndex["f_dc_2"] * 4, true) : 0.5;
+        const o = propIndex["opacity"] !== undefined ? view.getFloat32(base + propIndex["opacity"] * 4, true) : 0;
+        result.color[i4] = Math.max(0, Math.min(1, 0.5 + r * SH_C0));
+        result.color[i4 + 1] = Math.max(0, Math.min(1, 0.5 + g * SH_C0));
+        result.color[i4 + 2] = Math.max(0, Math.min(1, 0.5 + b * SH_C0));
+        result.color[i4 + 3] = sigmoidOpacity(o);
+        // SH rest coefficients
+        if (restCoeffs > 0) {
+            const shBase = i * restCoeffs;
+            for (let c = 0; c < restCoeffs; c++) {
+                const key = `f_rest_${c}`;
+                result.shCoeffs[shBase + c] = propIndex[key] !== undefined
+                    ? view.getFloat32(base + propIndex[key] * 4, true)
+                    : 0;
+            }
+        }
+    }
+    return result;
+}
+// ── .splat parsing ──
+//
+// The antimatter15 .splat format is a 32-byte-per-splat binary blob with no
+// SH coefficients. Layout: position(3f) | scale(3f) | color(4u8) | rotation(4u8).
+// This parser reads the float32 position/scale fields; the u8 color/rotation
+// fields are read and converted to float.
+export function parseSplat(data) {
+    const stride = 32;
+    const count = Math.floor(data.byteLength / stride);
+    assertCount("splats", count, MAX_VERTEX_COUNT);
+    if (count === 0) {
+        return emptySplatData(0, 0, 2);
+    }
+    const view = new DataView(data.buffer, data.byteOffset, count * stride);
+    const result = emptySplatData(count, 0, 2);
+    for (let i = 0; i < count; i++) {
+        const base = i * stride;
+        const i3 = i * 3;
+        const i4 = i * 4;
+        // Position (float32 × 3)
+        result.position[i3] = view.getFloat32(base, true);
+        result.position[i3 + 1] = view.getFloat32(base + 4, true);
+        result.position[i3 + 2] = view.getFloat32(base + 8, true);
+        // Scale (float32 × 3, exp-transform)
+        result.scale[i3] = Math.exp(view.getFloat32(base + 12, true));
+        result.scale[i3 + 1] = Math.exp(view.getFloat32(base + 16, true));
+        result.scale[i3 + 2] = Math.exp(view.getFloat32(base + 20, true));
+        // Color (u8 × 4, normalized to 0..1)
+        result.color[i4] = view.getUint8(base + 24) / 255;
+        result.color[i4 + 1] = view.getUint8(base + 25) / 255;
+        result.color[i4 + 2] = view.getUint8(base + 26) / 255;
+        result.color[i4 + 3] = view.getUint8(base + 27) / 255;
+        // Rotation (u8 × 4 → quaternion, normalized)
+        const rw = view.getUint8(base + 28) / 127.5 - 1;
+        const rx = view.getUint8(base + 29) / 127.5 - 1;
+        const ry = view.getUint8(base + 30) / 127.5 - 1;
+        const rz = view.getUint8(base + 31) / 127.5 - 1;
+        normalizeQuat(result.rotation, i4, rw, rx, ry, rz);
+    }
+    return result;
+}
+// ── Dispatch ──
+export function parseGaussianSplatFile(data, format = "ply") {
+    if (format === "splat")
+        return parseSplat(data);
+    return parsePLY(data);
+}
+// ── Escape hatch: extract a single splat as a tuple ──
+/** Extract splat `i` as a tuple (escape hatch for debugging / CPU queries). */
+export function getSplat(data, i) {
+    const i3 = i * 3;
+    const i4 = i * 4;
+    return {
+        position: [data.position[i3], data.position[i3 + 1], data.position[i3 + 2]],
+        scale: [data.scale[i3], data.scale[i3 + 1], data.scale[i3 + 2]],
+        rotation: [data.rotation[i4], data.rotation[i4 + 1], data.rotation[i4 + 2], data.rotation[i4 + 3]],
+        color: [data.color[i4], data.color[i4 + 1], data.color[i4 + 2], data.color[i4 + 3]],
+        opacity: data.color[i4 + 3],
+    };
+}

package/dist/libraries/gaussian-splats/src/renderer.js

@@ -0,0 +1,368 @@
+import { createValidatedShaderModule } from "@downdraft/engine";
+import { f32, mat4x4f, vec2f, vec3f, wgsl } from "@downdraft/engine/shader-graph";
+import { GpuSplatSorter } from "./gpu-sort.js";
+import { packShCoeffs, SH_COEFFS_TOTAL, SH_EVAL_WGSL } from "./sh-eval.js";
+import { TileRasterPipeline } from "./tile-raster.js";
+const CameraUniforms = wgsl.struct("CameraUniforms", {
+    viewProj: mat4x4f,
+    cameraPos: vec3f,
+    _pad: f32,
+    resolution: vec2f,
+    _pad2: vec2f,
+});
+const GAUSSIAN_SPLAT_SHADER = `
+${CameraUniforms.wgsl}
+${SH_EVAL_WGSL}
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+@group(0) @binding(1) var splatData: array<vec4<f32>>;
+
+struct VertexInput {
+  @builtin(vertex_index) vertexIndex: u32,
+  @builtin(instance_index) instanceIndex: u32,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) color: vec4<f32>,
+  @location(1) uv: vec2<f32>,
+  @location(2) viewDir: vec3<f32>,
+  @location(3) @interpolate(flat, either) splatIdx: u32,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> VertexOutput {
+  var output: VertexOutput;
+  let splatIdx = input.instanceIndex;
+  let corner = input.vertexIndex;
+
+  let pos = vec3<f32>(
+    splatData[splatIdx * 3].x,
+    splatData[splatIdx * 3].y,
+    splatData[splatIdx * 3].z,
+  );
+  let scale = vec3<f32>(
+    splatData[splatIdx * 3 + 1].x,
+    splatData[splatIdx * 3 + 1].y,
+    splatData[splatIdx * 3 + 1].z,
+  );
+  let color = vec4<f32>(
+    splatData[splatIdx * 3 + 2].x,
+    splatData[splatIdx * 3 + 2].y,
+    splatData[splatIdx * 3 + 2].z,
+    splatData[splatIdx * 3 + 2].w,
+  );
+
+  let offsets = array<vec2<f32>, 4>(
+    vec2<f32>(-1.0, -1.0),
+    vec2<f32>(1.0, -1.0),
+    vec2<f32>(1.0, 1.0),
+    vec2<f32>(-1.0, 1.0),
+  );
+
+  let cornerOffset = offsets[corner] * scale.xy;
+  let clipPos = camera.viewProj * vec4<f32>(pos, 1.0);
+  output.clipPosition = vec4<f32>(
+    clipPos.x + cornerOffset.x * clipPos.w * 0.01,
+    clipPos.y + cornerOffset.y * clipPos.w * 0.01,
+    clipPos.z,
+    clipPos.w,
+  );
+  output.color = color;
+  output.uv = offsets[corner];
+  output.viewDir = normalize(camera.cameraPos - pos);
+  output.splatIdx = splatIdx;
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  let dist = dot(input.uv, input.uv);
+  if (dist > 1.0) {
+    discard;
+  }
+  let alpha = exp(-dist * 2.0);
+  let shContrib = evalSH(input.splatIdx, input.viewDir);
+  return vec4<f32>(input.color.rgb + shContrib, input.color.a * alpha);
+}
+`;
+export class GaussianSplatRenderer {
+    device;
+    surfaceFormat;
+    config;
+    shaderModule = null;
+    pipeline = null;
+    cameraBuffer = null;
+    _cameraView = null;
+    _cameraBuf = null;
+    splatBuffer = null;
+    bindGroup = null;
+    splatData = null;
+    sortResult = null;
+    sorter = null;
+    frameCount = 0;
+    _lastDrawBuffer = null;
+    shBuffer = null;
+    shParamsBuffer = null;
+    shParamsData = null;
+    shEnabled = false;
+    tileRaster = null;
+    tileRasterBindGroup = null;
+    _lastTileDrawBuffer = null;
+    constructor(device, surfaceFormat, config = {}) {
+        this.device = device;
+        this.surfaceFormat = surfaceFormat;
+        this.config = {
+            maxSplats: config.maxSplats ?? 1_000_000,
+            sortThreshold: config.sortThreshold ?? 8192,
+            sortFrequency: config.sortFrequency ?? 1,
+            shDegree: config.shDegree ?? 0,
+            tileRaster: config.tileRaster ?? false,
+            tileRasterOptions: config.tileRasterOptions ?? {},
+        };
+    }
+    prepare(device) {
+        if (!this.device)
+            this.device = device;
+        if (!this.shaderModule && this.device) {
+            this.shaderModule = createValidatedShaderModule(this.device, { code: GAUSSIAN_SPLAT_SHADER, label: "GaussianSplatRenderer" });
+        }
+        if (!this.cameraBuffer && this.device) {
+            this.cameraBuffer = this.device.createBuffer({
+                size: 96,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+            this._cameraBuf = new Float32Array(CameraUniforms.floatCount);
+            this._cameraView = CameraUniforms.view(this._cameraBuf);
+        }
+        if (!this.sorter && this.device) {
+            this.sorter = new GpuSplatSorter(this.device, {
+                maxSplats: this.config.maxSplats,
+                threshold: this.config.sortThreshold,
+            });
+            this.sorter.prepare(this.device);
+        }
+        if (!this.shParamsBuffer && this.device) {
+            this.shParamsData = new Uint32Array(4);
+            this.shParamsBuffer = this.device.createBuffer({
+                label: "splat-sh-params",
+                size: 16,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+        }
+        if (!this.tileRaster && this.config.tileRaster && this.device) {
+            this.tileRaster = new TileRasterPipeline(this.device, this.config.tileRasterOptions);
+            this.tileRaster.prepare(this.device);
+        }
+    }
+    setData(data) {
+        this.splatData = data;
+        if (!this.device || !data)
+            return;
+        // Pack SoA arrays into the shader's vec4-strided layout:
+        //   [pos.xyz, _] [scale.xyz, _] [color.rgb, color.a] per splat (12 floats).
+        // color.a already includes the opacity sigmoid (folded in by the parser).
+        const count = data.count;
+        const splatArray = new Float32Array(count * 12);
+        for (let i = 0; i < count; i++) {
+            const i3 = i * 3;
+            const i4 = i * 4;
+            const o = i * 12;
+            splatArray[o] = data.position[i3];
+            splatArray[o + 1] = data.position[i3 + 1];
+            splatArray[o + 2] = data.position[i3 + 2];
+            splatArray[o + 3] = 0;
+            splatArray[o + 4] = data.scale[i3];
+            splatArray[o + 5] = data.scale[i3 + 1];
+            splatArray[o + 6] = data.scale[i3 + 2];
+            splatArray[o + 7] = 0;
+            splatArray[o + 8] = data.color[i4];
+            splatArray[o + 9] = data.color[i4 + 1];
+            splatArray[o + 10] = data.color[i4 + 2];
+            splatArray[o + 11] = data.color[i4 + 3];
+        }
+        if (this.splatBuffer)
+            this.splatBuffer.destroy();
+        this.splatBuffer = this.device.createBuffer({
+            size: splatArray.byteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(this.splatBuffer, 0, splatArray.buffer);
+        // Pack + upload SH coefficients (degrees 1..shDegree)
+        this.uploadShCoeffs(data);
+        // Reset bind group cache — the splat buffer changed
+        this._lastDrawBuffer = null;
+    }
+    uploadShCoeffs(data) {
+        const device = this.device;
+        const maxDegree = this.config.shDegree;
+        const coeffs = packShCoeffs(data, maxDegree);
+        this.shEnabled = coeffs.length > 0;
+        if (this.shBuffer) {
+            this.shBuffer.destroy();
+            this.shBuffer = null;
+        }
+        if (this.shEnabled) {
+            this.shBuffer = device.createBuffer({
+                label: "splat-sh-coeffs",
+                size: coeffs.byteLength,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+            device.queue.writeBuffer(this.shBuffer, 0, coeffs.buffer);
+            const coeffsPerSplat = SH_COEFFS_TOTAL[maxDegree];
+            this.shParamsData[0] = maxDegree;
+            this.shParamsData[1] = coeffsPerSplat;
+            this.shParamsData[2] = 0;
+            this.shParamsData[3] = 0;
+            device.queue.writeBuffer(this.shParamsBuffer, 0, this.shParamsData);
+        }
+        else {
+            // shDegree = 0 → evalSH returns vec3(0); still upload zeroed params
+            this.shParamsData[0] = 0;
+            this.shParamsData[1] = 0;
+            this.shParamsData[2] = 0;
+            this.shParamsData[3] = 0;
+            device.queue.writeBuffer(this.shParamsBuffer, 0, this.shParamsData);
+        }
+    }
+    updateSort(sortResult) {
+        this.sortResult = sortResult;
+    }
+    ensurePipeline() {
+        if (this.pipeline || !this.device || !this.shaderModule || !this.cameraBuffer)
+            return;
+        this.pipeline = this.device.createRenderPipeline({
+            layout: "auto",
+            vertex: {
+                module: this.shaderModule,
+                entryPoint: "vs_main",
+            },
+            fragment: {
+                module: this.shaderModule,
+                entryPoint: "fs_main",
+                targets: [{
+                        format: this.surfaceFormat,
+                        blend: {
+                            color: { srcFactor: "src-alpha", dstFactor: "one", operation: "add" },
+                            alpha: { srcFactor: "one", dstFactor: "one", operation: "add" },
+                        },
+                    }],
+            },
+            primitive: { topology: "triangle-strip" },
+            depthStencil: {
+                format: "depth32float",
+                depthWriteEnabled: false,
+                depthCompare: "less",
+            },
+        });
+    }
+    render(passEncoder, viewProj, cameraPos, resolution) {
+        if (!this.device || !this.splatData || !this.cameraBuffer || !this.splatBuffer)
+            return;
+        const count = this.splatData.count;
+        // Write camera uniforms (used by instanced-quad path)
+        const camView = this._cameraView;
+        camView.set("viewProj", viewProj);
+        camView.set("cameraPos", cameraPos);
+        camView.set("_pad", 0);
+        camView.set("resolution", resolution);
+        camView.set("_pad2", [0, 0]);
+        this.device.queue.writeBuffer(this.cameraBuffer, 0, this._cameraBuf);
+        // Sort + compact: determine which buffer to draw from.
+        // On sort frames, run the GPU/CPU sort and compact into a sorted buffer.
+        // On non-sort frames (sortFrequency > 1), reuse the last compacted buffer.
+        let drawBuffer = this.splatBuffer;
+        const shouldSort = this.frameCount % this.config.sortFrequency === 0;
+        if (shouldSort && this.sorter && count > 0) {
+            const compacted = this.sorter.sortAndCompact(cameraPos, this.splatBuffer, this.splatData, count);
+            if (compacted)
+                drawBuffer = compacted;
+        }
+        if (this.config.tileRaster && this.tileRaster) {
+            this.renderTileRaster(passEncoder, drawBuffer, count, viewProj, resolution);
+        }
+        else {
+            this.renderInstancedQuads(passEncoder, drawBuffer, count);
+        }
+        this.frameCount++;
+    }
+    renderInstancedQuads(passEncoder, drawBuffer, count) {
+        this.ensurePipeline();
+        if (!this.pipeline || !this.splatBuffer || !this.device)
+            return;
+        // (Re)create bind group if the draw buffer changed
+        if (drawBuffer !== this._lastDrawBuffer) {
+            const entries = [
+                { binding: 0, resource: { buffer: this.cameraBuffer } },
+                { binding: 1, resource: { buffer: drawBuffer } },
+            ];
+            // SH bindings (binding 2 = coeffs, binding 3 = params).
+            // The shader always declares these bindings; when SH is disabled,
+            // bind a 16-byte placeholder buffer (shParams has shDegree=0 → evalSH returns 0).
+            if (this.shBuffer && this.shEnabled) {
+                entries.push({ binding: 2, resource: { buffer: this.shBuffer } });
+                entries.push({ binding: 3, resource: { buffer: this.shParamsBuffer } });
+            }
+            else {
+                // Bind shParamsBuffer for both slots — it has shDegree=0 so evalSH is a no-op.
+                // The coeffs binding still needs a valid storage buffer; reuse shParamsBuffer.
+                entries.push({ binding: 2, resource: { buffer: this.shParamsBuffer } });
+                entries.push({ binding: 3, resource: { buffer: this.shParamsBuffer } });
+            }
+            this.bindGroup = this.device.createBindGroup({
+                layout: this.pipeline.getBindGroupLayout(0),
+                entries,
+            });
+            this._lastDrawBuffer = drawBuffer;
+        }
+        passEncoder.setPipeline(this.pipeline);
+        passEncoder.setBindGroup(0, this.bindGroup);
+        passEncoder.draw(4, count);
+    }
+    renderTileRaster(passEncoder, drawBuffer, count, viewProj, resolution) {
+        if (!this.tileRaster || count === 0)
+            return;
+        const [width, height] = resolution;
+        // Bin splats into tiles (compute pass)
+        const { tileCounts, tileIndices } = this.tileRaster.binSplats(drawBuffer, count, viewProj, width, height);
+        // Write raster uniforms
+        this.tileRaster.writeRasterUniforms(width, height);
+        // (Re)create bind group if the draw buffer changed
+        if (drawBuffer !== this._lastTileDrawBuffer) {
+            this.tileRasterBindGroup = this.tileRaster.createRasterBindGroup(drawBuffer, tileCounts, tileIndices);
+            this._lastTileDrawBuffer = drawBuffer;
+        }
+        const pipeline = this.tileRaster.getRasterPipeline();
+        if (!pipeline || !this.tileRasterBindGroup)
+            return;
+        passEncoder.setPipeline(pipeline);
+        passEncoder.setBindGroup(0, this.tileRasterBindGroup);
+        passEncoder.draw(3); // Full-screen triangle
+    }
+    destroy() {
+        this.cameraBuffer?.destroy();
+        this.splatBuffer?.destroy();
+        this.pipeline?.destroy();
+        this.shaderModule?.destroy();
+        this.sorter?.destroy();
+        this.shBuffer?.destroy();
+        this.shParamsBuffer?.destroy();
+        this.tileRaster?.destroy();
+        // GPUBindGroup has no destroy() — just null it.
+        this.cameraBuffer = null;
+        this._cameraView = null;
+        this._cameraBuf = null;
+        this.splatBuffer = null;
+        this.pipeline = null;
+        this.shaderModule = null;
+        this.bindGroup = null;
+        this.sorter = null;
+        this._lastDrawBuffer = null;
+        this.shBuffer = null;
+        this.shParamsBuffer = null;
+        this.shParamsData = null;
+        this.tileRaster = null;
+        this.tileRasterBindGroup = null;
+        this._lastTileDrawBuffer = null;
+    }
+}