@downdraft/engine 0.1.1 → 0.2.0

package/dist/libraries/gaussian-splats/src/gpu-sort.js

@@ -0,0 +1,506 @@
+// ============================================================================
+// GpuSplatSorter — GPU radix sort + splat buffer compaction
+//
+// Sorts splats back-to-front by camera distance using a GPU radix sort
+// (4-bit radix, 8 passes for u32 keys). After sorting, compacts the splat
+// buffer into sorted order so the instanced-quad draw renders correctly.
+//
+// For small splat counts (below `threshold`), falls back to a CPU merge sort
+// and uploads the sorted indices — the compact pass still runs on GPU.
+//
+// Algorithm reference: KoS-Y1/Web-GS-Renderer (radix_parallel.wgsl) and
+// Scthe/gaussian-splatting-webgpu, both MIT-licensed. Ported to raw WGSL
+// with the engine's buffer management patterns.
+// ============================================================================
+import { createValidatedShaderModule } from "@downdraft/engine";
+import { sortSplats } from "./sorter.js";
+// ── WGSL kernels ──
+const DISTANCES_WGSL = /* wgsl */ `
+struct SortUniforms {
+  cameraPos: vec3<f32>,
+  count: u32,
+  pass: u32,
+  _pad0: u32,
+  _pad1: u32,
+}
+
+@group(0) @binding(0) var<uniform> u: SortUniforms;
+@group(0) @binding(1) var<storage, read> splatData: array<vec4<f32>>;
+@group(0) @binding(2) var<storage, read_write> keys: array<u32>;
+@group(0) @binding(3) var<storage, read_write> indices: array<u32>;
+
+fn floatToSortableKey(f: f32) -> u32 {
+  let bits = bitcast<u32>(f);
+  if ((bits & 0x80000000u) != 0u) {
+    return ~bits;
+  }
+  return bits | 0x80000000u;
+}
+
+@compute @workgroup_size(64)
+fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let idx = gid.x;
+  if (idx >= u.count) { return; }
+  // Position is the first vec4 of each 3-vec4 splat block
+  let pos = splatData[idx * 3u].xyz;
+  let d = pos - u.cameraPos;
+  let dist = dot(d, d);
+  // Invert key so ascending radix sort → descending distance (back-to-front)
+  keys[idx] = ~floatToSortableKey(dist);
+  indices[idx] = idx;
+}
+`;
+const HISTOGRAM_WGSL = /* wgsl */ `
+struct SortUniforms {
+  cameraPos: vec3<f32>,
+  count: u32,
+  pass: u32,
+  _pad0: u32,
+  _pad1: u32,
+}
+
+@group(0) @binding(0) var<uniform> u: SortUniforms;
+@group(0) @binding(1) var<storage, read> keys: array<u32>;
+@group(0) @binding(2) var<storage, read_write> histogram: array<u32, 16>;
+
+@compute @workgroup_size(64)
+fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  if (gid.x >= u.count) { return; }
+  let shift = u.pass * 4u;
+  let digit = (keys[gid.x] >> shift) & 0xFu;
+  atomicAdd(&histogram[digit], 1u);
+}
+`;
+const PREFIX_SUM_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<storage, read> histogram: array<u32, 16>;
+@group(0) @binding(1) var<storage, read_write> prefixSum: array<u32, 16>;
+
+@compute @workgroup_size(16)
+fn cs_main(@builtin(local_invocation_id) lid: vec3<u32>) {
+  let i = lid.x;
+  // Exclusive prefix sum over 16 elements (Hillis-Steele, 1 pass for N=16)
+  var val: u32 = 0u;
+  if (i > 0u) { val = histogram[i - 1u]; }
+  prefixSum[i] = val;
+  // For 16 elements, a single sequential scan in thread 0 is simplest and correct.
+  // But we already wrote the exclusive sum above using histogram[i-1].
+  // This is correct because each thread reads histogram[i-1] directly — no
+  // inter-thread dependency for an exclusive sum of 16 elements where each
+  // output only depends on inputs before it.
+}
+`;
+const SCATTER_WGSL = /* wgsl */ `
+struct SortUniforms {
+  cameraPos: vec3<f32>,
+  count: u32,
+  pass: u32,
+  _pad0: u32,
+  _pad1: u32,
+}
+
+@group(0) @binding(0) var<uniform> u: SortUniforms;
+@group(0) @binding(1) var<storage, read> keysIn: array<u32>;
+@group(0) @binding(2) var<storage, read> indicesIn: array<u32>;
+@group(0) @binding(3) var<storage, read> prefixSum: array<u32, 16>;
+@group(0) @binding(4) var<storage, read_write> scatterCounter: array<u32, 16>;
+@group(0) @binding(5) var<storage, read_write> keysOut: array<u32>;
+@group(0) @binding(6) var<storage, read_write> indicesOut: array<u32>;
+
+@compute @workgroup_size(64)
+fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  if (gid.x >= u.count) { return; }
+  let shift = u.pass * 4u;
+  let digit = (keysIn[gid.x] >> shift) & 0xFu;
+  let offset = atomicAdd(&scatterCounter[digit], 1u);
+  let pos = prefixSum[digit] + offset;
+  keysOut[pos] = keysIn[gid.x];
+  indicesOut[pos] = indicesIn[gid.x];
+}
+`;
+const COMPACT_WGSL = /* wgsl */ `
+struct CompactUniforms {
+  count: u32,
+  _pad0: u32,
+  _pad1: u32,
+  _pad2: u32,
+}
+
+@group(0) @binding(0) var<uniform> u: CompactUniforms;
+@group(0) @binding(1) var<storage, read> splatData: array<vec4<f32>>;
+@group(0) @binding(2) var<storage, read> indices: array<u32>;
+@group(0) @binding(3) var<storage, read_write> compacted: array<vec4<f32>>;
+
+@compute @workgroup_size(64)
+fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  if (gid.x >= u.count) { return; }
+  let srcIdx = indices[gid.x];
+  let dstBase = gid.x * 3u;
+  let srcBase = srcIdx * 3u;
+  compacted[dstBase] = splatData[srcBase];
+  compacted[dstBase + 1u] = splatData[srcBase + 1u];
+  compacted[dstBase + 2u] = splatData[srcBase + 2u];
+}
+`;
+// ── Constants ──
+const WORKGROUP_SIZE = 64;
+const NUM_PASSES = 8; // 32 bits / 4-bit radix
+const SPLAT_VECS = 3; // vec4s per splat (12 floats)
+const SPLAT_BYTES = SPLAT_VECS * 16; // 48 bytes per splat
+// ── Sort uniform layout (32 bytes) ──
+// cameraPos(3f) + count(1u) + pass(1u) + pad(2u) = 8 × 4 = 32 bytes
+const SORT_UNIFORM_SIZE = 32;
+export class GpuSplatSorter {
+    device = null;
+    maxSplats;
+    threshold;
+    // Pipelines
+    distancesPipeline = null;
+    histogramPipeline = null;
+    prefixSumPipeline = null;
+    scatterPipeline = null;
+    compactPipeline = null;
+    // Bind group layouts
+    distancesBGL = null;
+    histogramBGL = null;
+    prefixSumBGL = null;
+    scatterBGL = null;
+    compactBGL = null;
+    // Buffers
+    sortUniformBuffer = null;
+    sortUniformData = null;
+    sortUniformFloats = null;
+    sortUniformUints = null;
+    compactUniformBuffer = null;
+    compactUniformData = null;
+    keyBuffers = null;
+    indexBuffers = null;
+    histogramBuffer = null;
+    prefixSumBuffer = null;
+    scatterCounterBuffer = null;
+    zeroBuffer = null;
+    compactedBuffer = null;
+    // Which ping-pong buffer set is the "current" read source (0 or 1)
+    currentSet = 0;
+    // CPU-side index upload buffer (for CPU fallback)
+    cpuIndexUploadBuffer = null;
+    constructor(device, options = {}) {
+        this.maxSplats = options.maxSplats ?? 1_000_000;
+        this.threshold = options.threshold ?? 8192;
+        if (device)
+            this.prepare(device);
+    }
+    prepare(device) {
+        if (this.device === device && this.distancesPipeline)
+            return;
+        this.device = device;
+        this.createPipelines(device);
+        this.createBuffers(device);
+    }
+    createPipelines(device) {
+        // ── Bind group layouts ──
+        this.distancesBGL = device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+                { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+            ],
+        });
+        this.histogramBGL = device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+            ],
+        });
+        this.prefixSumBGL = device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+            ],
+        });
+        this.scatterBGL = device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+                { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+                { binding: 4, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+                { binding: 5, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+                { binding: 6, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+            ],
+        });
+        this.compactBGL = device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+                { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+            ],
+        });
+        // ── Shader modules ──
+        const distancesModule = createValidatedShaderModule(device, { code: DISTANCES_WGSL, label: "GpuSort.distances" });
+        const histogramModule = createValidatedShaderModule(device, { code: HISTOGRAM_WGSL, label: "GpuSort.histogram" });
+        const prefixSumModule = createValidatedShaderModule(device, { code: PREFIX_SUM_WGSL, label: "GpuSort.prefixSum" });
+        const scatterModule = createValidatedShaderModule(device, { code: SCATTER_WGSL, label: "GpuSort.scatter" });
+        const compactModule = createValidatedShaderModule(device, { code: COMPACT_WGSL, label: "GpuSort.compact" });
+        // ── Pipelines ──
+        this.distancesPipeline = device.createComputePipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.distancesBGL] }),
+            compute: { module: distancesModule, entryPoint: "cs_main" },
+        });
+        this.histogramPipeline = device.createComputePipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.histogramBGL] }),
+            compute: { module: histogramModule, entryPoint: "cs_main" },
+        });
+        this.prefixSumPipeline = device.createComputePipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.prefixSumBGL] }),
+            compute: { module: prefixSumModule, entryPoint: "cs_main" },
+        });
+        this.scatterPipeline = device.createComputePipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.scatterBGL] }),
+            compute: { module: scatterModule, entryPoint: "cs_main" },
+        });
+        this.compactPipeline = device.createComputePipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.compactBGL] }),
+            compute: { module: compactModule, entryPoint: "cs_main" },
+        });
+    }
+    createBuffers(device) {
+        const maxSplatBytes = this.maxSplats * 4; // u32 or f32 per splat
+        // Sort uniforms (32 bytes)
+        this.sortUniformData = new ArrayBuffer(SORT_UNIFORM_SIZE);
+        this.sortUniformFloats = new Float32Array(this.sortUniformData);
+        this.sortUniformUints = new Uint32Array(this.sortUniformData);
+        this.sortUniformBuffer = device.createBuffer({
+            label: "splat-sort-uniforms",
+            size: SORT_UNIFORM_SIZE,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        // Compact uniforms (16 bytes)
+        this.compactUniformData = new Uint32Array(4);
+        this.compactUniformBuffer = device.createBuffer({
+            label: "splat-compact-uniforms",
+            size: 16,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        // Key + index ping-pong buffers
+        this.keyBuffers = [
+            device.createBuffer({ label: "splat-keys-A", size: maxSplatBytes, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST }),
+            device.createBuffer({ label: "splat-keys-B", size: maxSplatBytes, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST }),
+        ];
+        this.indexBuffers = [
+            device.createBuffer({ label: "splat-indices-A", size: maxSplatBytes, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST }),
+            device.createBuffer({ label: "splat-indices-B", size: maxSplatBytes, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST }),
+        ];
+        // Histogram (16 u32s = 64 bytes)
+        this.histogramBuffer = device.createBuffer({
+            label: "splat-histogram",
+            size: 64,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+        });
+        // Prefix sum (16 u32s = 64 bytes)
+        this.prefixSumBuffer = device.createBuffer({
+            label: "splat-prefix-sum",
+            size: 64,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        // Scatter counter (16 u32s = 64 bytes)
+        this.scatterCounterBuffer = device.createBuffer({
+            label: "splat-scatter-counter",
+            size: 64,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        // Zero buffer (64 bytes of zeros, for clearing histogram + scatter counter)
+        this.zeroBuffer = device.createBuffer({
+            label: "splat-zero",
+            size: 64,
+            usage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE,
+        });
+        // Initialize zero buffer
+        const zeroData = new Uint32Array(16);
+        device.queue.writeBuffer(this.zeroBuffer, 0, zeroData);
+        // Compacted splat buffer (maxSplats * 48 bytes)
+        this.compactedBuffer = device.createBuffer({
+            label: "splat-compacted",
+            size: this.maxSplats * SPLAT_BYTES,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        // CPU index upload buffer
+        this.cpuIndexUploadBuffer = new Uint32Array(this.maxSplats);
+    }
+    /**
+     * Sort splats by camera distance (back-to-front) and compact the splat buffer.
+     * Returns a GPUBuffer containing the compacted, sorted splat data (3 vec4s per splat).
+     * The returned buffer is valid until the next call to `sortAndCompact()`.
+     */
+    sortAndCompact(cameraPos, splatBuffer, splatData, count) {
+        if (!this.device || count === 0)
+            return null;
+        if (count < this.threshold && splatData) {
+            return this.cpuSortAndCompact(cameraPos, splatBuffer, splatData, count);
+        }
+        return this.gpuSortAndCompact(cameraPos, splatBuffer, count);
+    }
+    // ── CPU fallback ──
+    cpuSortAndCompact(cameraPos, splatBuffer, splatData, count) {
+        const device = this.device;
+        const { indices } = sortSplats(splatData, cameraPos);
+        // Upload sorted indices (reversed for back-to-front: sortSplats returns
+        // nearest-first, we need farthest-first for alpha blending)
+        const upload = this.cpuIndexUploadBuffer;
+        for (let i = 0; i < count; i++) {
+            upload[i] = indices[count - 1 - i];
+        }
+        device.queue.writeBuffer(this.indexBuffers[0], 0, upload.subarray(0, count));
+        // Run compact pass
+        this.runCompact(splatBuffer, this.indexBuffers[0], count);
+        return this.compactedBuffer;
+    }
+    // ── GPU radix sort ──
+    gpuSortAndCompact(cameraPos, splatBuffer, count) {
+        const device = this.device;
+        const workgroups = Math.ceil(count / WORKGROUP_SIZE);
+        // ── Compute distances + initialize indices ──
+        this.writeSortUniforms(cameraPos, count, 0);
+        const distBindGroup = device.createBindGroup({
+            layout: this.distancesBGL,
+            entries: [
+                { binding: 0, resource: { buffer: this.sortUniformBuffer } },
+                { binding: 1, resource: { buffer: splatBuffer } },
+                { binding: 2, resource: { buffer: this.keyBuffers[0] } },
+                { binding: 3, resource: { buffer: this.indexBuffers[0] } },
+            ],
+        });
+        let enc = device.createCommandEncoder();
+        let pass = enc.beginComputePass();
+        pass.setPipeline(this.distancesPipeline);
+        pass.setBindGroup(0, distBindGroup);
+        pass.dispatchWorkgroups(workgroups);
+        pass.end();
+        device.queue.submit([enc.finish()]);
+        // ── 8 radix passes ──
+        this.currentSet = 0;
+        for (let p = 0; p < NUM_PASSES; p++) {
+            this.writeSortUniforms(cameraPos, count, p);
+            const readSet = this.currentSet;
+            const writeSet = 1 - readSet;
+            enc = device.createCommandEncoder();
+            // Clear histogram
+            enc.copyBufferToBuffer(this.zeroBuffer, 0, this.histogramBuffer, 0, 64);
+            // Histogram pass
+            const histBindGroup = device.createBindGroup({
+                layout: this.histogramBGL,
+                entries: [
+                    { binding: 0, resource: { buffer: this.sortUniformBuffer } },
+                    { binding: 1, resource: { buffer: this.keyBuffers[readSet] } },
+                    { binding: 2, resource: { buffer: this.histogramBuffer } },
+                ],
+            });
+            pass = enc.beginComputePass();
+            pass.setPipeline(this.histogramPipeline);
+            pass.setBindGroup(0, histBindGroup);
+            pass.dispatchWorkgroups(workgroups);
+            pass.end();
+            // Prefix sum pass
+            const prefixBindGroup = device.createBindGroup({
+                layout: this.prefixSumBGL,
+                entries: [
+                    { binding: 0, resource: { buffer: this.histogramBuffer } },
+                    { binding: 1, resource: { buffer: this.prefixSumBuffer } },
+                ],
+            });
+            pass = enc.beginComputePass();
+            pass.setPipeline(this.prefixSumPipeline);
+            pass.setBindGroup(0, prefixBindGroup);
+            pass.dispatchWorkgroups(1);
+            pass.end();
+            // Clear scatter counter
+            enc.copyBufferToBuffer(this.zeroBuffer, 0, this.scatterCounterBuffer, 0, 64);
+            // Scatter pass
+            const scatterBindGroup = device.createBindGroup({
+                layout: this.scatterBGL,
+                entries: [
+                    { binding: 0, resource: { buffer: this.sortUniformBuffer } },
+                    { binding: 1, resource: { buffer: this.keyBuffers[readSet] } },
+                    { binding: 2, resource: { buffer: this.indexBuffers[readSet] } },
+                    { binding: 3, resource: { buffer: this.prefixSumBuffer } },
+                    { binding: 4, resource: { buffer: this.scatterCounterBuffer } },
+                    { binding: 5, resource: { buffer: this.keyBuffers[writeSet] } },
+                    { binding: 6, resource: { buffer: this.indexBuffers[writeSet] } },
+                ],
+            });
+            pass = enc.beginComputePass();
+            pass.setPipeline(this.scatterPipeline);
+            pass.setBindGroup(0, scatterBindGroup);
+            pass.dispatchWorkgroups(workgroups);
+            pass.end();
+            device.queue.submit([enc.finish()]);
+            // Ping-pong: next pass reads from the set we just wrote to
+            this.currentSet = writeSet;
+        }
+        // ── Compact: reorder splat buffer using sorted indices ──
+        this.runCompact(splatBuffer, this.indexBuffers[this.currentSet], count);
+        return this.compactedBuffer;
+    }
+    runCompact(splatBuffer, indexBuffer, count) {
+        const device = this.device;
+        // Update compact uniforms
+        this.compactUniformData[0] = count;
+        device.queue.writeBuffer(this.compactUniformBuffer, 0, this.compactUniformData);
+        const compactBindGroup = device.createBindGroup({
+            layout: this.compactBGL,
+            entries: [
+                { binding: 0, resource: { buffer: this.compactUniformBuffer } },
+                { binding: 1, resource: { buffer: splatBuffer } },
+                { binding: 2, resource: { buffer: indexBuffer } },
+                { binding: 3, resource: { buffer: this.compactedBuffer } },
+            ],
+        });
+        const enc = device.createCommandEncoder();
+        const pass = enc.beginComputePass();
+        pass.setPipeline(this.compactPipeline);
+        pass.setBindGroup(0, compactBindGroup);
+        pass.dispatchWorkgroups(Math.ceil(count / WORKGROUP_SIZE));
+        pass.end();
+        device.queue.submit([enc.finish()]);
+    }
+    writeSortUniforms(cameraPos, count, passIdx) {
+        const f = this.sortUniformFloats;
+        const u = this.sortUniformUints;
+        f[0] = cameraPos[0];
+        f[1] = cameraPos[1];
+        f[2] = cameraPos[2];
+        u[3] = count;
+        u[4] = passIdx;
+        u[5] = 0;
+        u[6] = 0;
+        this.device.queue.writeBuffer(this.sortUniformBuffer, 0, this.sortUniformData);
+    }
+    destroy() {
+        this.sortUniformBuffer?.destroy();
+        this.compactUniformBuffer?.destroy();
+        this.keyBuffers?.forEach((b) => b.destroy());
+        this.indexBuffers?.forEach((b) => b.destroy());
+        this.histogramBuffer?.destroy();
+        this.prefixSumBuffer?.destroy();
+        this.scatterCounterBuffer?.destroy();
+        this.zeroBuffer?.destroy();
+        this.compactedBuffer?.destroy();
+        this.sortUniformBuffer = null;
+        this.compactUniformBuffer = null;
+        this.keyBuffers = null;
+        this.indexBuffers = null;
+        this.histogramBuffer = null;
+        this.prefixSumBuffer = null;
+        this.scatterCounterBuffer = null;
+        this.zeroBuffer = null;
+        this.compactedBuffer = null;
+        this.sortUniformData = null;
+        this.sortUniformFloats = null;
+        this.sortUniformUints = null;
+        this.compactUniformData = null;
+        this.cpuIndexUploadBuffer = null;
+        this.device = null;
+    }
+}

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

@@ -0,0 +1,8 @@
+export { GpuSplatSorter } from "./gpu-sort.js";
+export { getSplat, MAX_SH_DEGREE, parseGaussianSplatFile, parsePLY, parseSplat, SH_REST_COEFFS_MAX, SH_REST_COEFFS_PER_DEGREE } from "./parser.js";
+export { GaussianSplatRenderer } from "./renderer.js";
+export { evalSHChannelCPU, packShCoeffs, SH_COEFFS_PER_CHANNEL, SH_COEFFS_TOTAL, SH_EVAL_WGSL } from "./sh-eval.js";
+export { filterByDistance, sortSplats } from "./sorter.js";
+export { DEFAULT_MAX_SPLATS_PER_TILE, DEFAULT_TILE_SIZE, TileRasterPipeline } from "./tile-raster.js";
+// Declarative library descriptor
+export { GaussianSplatsLib, GaussianSplatsTok } from "./library.js";

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

@@ -0,0 +1,44 @@
+// ============================================================================
+// GaussianSplatsLib — declarative engine library descriptor for @downdraft/engine/libraries/gaussian-splats
+//
+// Games declare `libraries: [GaussianSplatsLib]` (or with config override) in
+// their GameModule. The host creates the GaussianSplatRenderer (renderer-side)
+// and exposes it via a typed token.
+//
+// Games that need full control can still import GaussianSplatRenderer directly
+// (escape hatch).
+// ============================================================================
+import { resourceToken } from "@downdraft/engine";
+import { GaussianSplatRenderer } from "./renderer.js";
+// ── Typed tokens (DI) ──
+/** Token for the renderer-side gaussian splat renderer. Inject in renderer passes. */
+export const GaussianSplatsTok = resourceToken("gaussian-splats:renderer");
+// ── Descriptor ──
+export const GaussianSplatsLib = {
+    name: "gaussian-splats",
+    version: "1.0.0",
+    provides: [GaussianSplatsTok],
+    // Renderer-side only — no sim system.
+    renderer: {
+        init(config, ctx) {
+            const format = config.surfaceFormat ?? ctx.format;
+            const renderer = new GaussianSplatRenderer(ctx.device, format, {
+                maxSplats: config.maxSplats,
+                sortThreshold: config.sortThreshold,
+                sortFrequency: config.sortFrequency,
+                shDegree: config.shDegree,
+                tileRaster: config.tileRaster,
+                tileRasterOptions: config.tileRasterOptions,
+            });
+            renderer.prepare(ctx.device);
+            ctx.provide(GaussianSplatsTok, renderer);
+            return renderer;
+        },
+        dispose(renderer) {
+            renderer.destroy();
+        },
+    },
+    defaultConfig: {
+        surfaceFormat: "bgra8unorm",
+    },
+};