@downdraft/engine 0.0.0 → 0.1.1

package/libraries/gaussian-splats/src/renderer.ts

@@ -0,0 +1,427 @@
+import { createValidatedShaderModule } from "@downdraft/engine";
+import type { StructView, WgslStruct } from "@downdraft/engine/shader-graph";
+import { f32, mat4x4f, vec2f, vec3f, wgsl } from "@downdraft/engine/shader-graph";
+import { GpuSplatSorter } from "./gpu-sort";
+import type { GaussianSplatData } from "./parser";
+import { packShCoeffs, SH_COEFFS_TOTAL, SH_EVAL_WGSL } from "./sh-eval";
+import type { SortResult } from "./sorter";
+import { TileRasterPipeline, type TileRasterPipelineOptions } from "./tile-raster";
+
+export interface GaussianSplatRendererConfig {
+  /** Max splat count for GPU sort buffer pre-allocation. Default: 1_000_000. */
+  maxSplats?: number;
+  /** Below this count, use CPU sort. Default: 8192. */
+  sortThreshold?: number;
+  /** Sort every N frames (1 = every frame). Default: 1. */
+  sortFrequency?: number;
+  /** Max SH degree to evaluate (0 = DC only, 1-3 = view-dependent). Default: 0. */
+  shDegree?: 0 | 1 | 2 | 3;
+  /** Use tile-based rasterization instead of instanced quads. Default: false. */
+  tileRaster?: boolean;
+  /** Tile raster options (only used when tileRaster is true). */
+  tileRasterOptions?: TileRasterPipelineOptions;
+}
+
+const CameraUniforms: WgslStruct = 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 {
+  private device: GPUDevice | null;
+  private surfaceFormat: GPUTextureFormat;
+  private config: Required<GaussianSplatRendererConfig>;
+  private shaderModule: GPUShaderModule | null = null;
+  private pipeline: GPURenderPipeline | null = null;
+  private cameraBuffer: GPUBuffer | null = null;
+  private _cameraView: StructView | null = null;
+  private _cameraBuf: Float32Array | null = null;
+  private splatBuffer: GPUBuffer | null = null;
+  private bindGroup: GPUBindGroup | null = null;
+  private splatData: GaussianSplatData | null = null;
+  private sortResult: SortResult | null = null;
+  private sorter: GpuSplatSorter | null = null;
+  private frameCount = 0;
+  private _lastDrawBuffer: GPUBuffer | null = null;
+  private shBuffer: GPUBuffer | null = null;
+  private shParamsBuffer: GPUBuffer | null = null;
+  private shParamsData: Uint32Array | null = null;
+  private shEnabled = false;
+  private tileRaster: TileRasterPipeline | null = null;
+  private tileRasterBindGroup: GPUBindGroup | null = null;
+  private _lastTileDrawBuffer: GPUBuffer | null = null;
+
+  constructor(
+    device: GPUDevice | null,
+    surfaceFormat: GPUTextureFormat,
+    config: GaussianSplatRendererConfig = {},
+  ) {
+    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 ?? {},
+    } as Required<GaussianSplatRendererConfig>;
+  }
+
+  prepare(device: GPUDevice): void {
+    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: GaussianSplatData): void {
+    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;
+  }
+
+  private uploadShCoeffs(data: GaussianSplatData): void {
+    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 as unknown as GPUAllowSharedBufferSource);
+      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! as unknown as GPUAllowSharedBufferSource);
+    } 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! as unknown as GPUAllowSharedBufferSource);
+    }
+  }
+
+  updateSort(sortResult: SortResult): void {
+    this.sortResult = sortResult;
+  }
+
+  private ensurePipeline(): void {
+    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: GPURenderPassEncoder,
+    viewProj: number[],
+    cameraPos: [number, number, number],
+    resolution: [number, number],
+  ): void {
+    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! as unknown as GPUAllowSharedBufferSource);
+
+    // 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++;
+  }
+
+  private renderInstancedQuads(
+    passEncoder: GPURenderPassEncoder,
+    drawBuffer: GPUBuffer,
+    count: number,
+  ): void {
+    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: GPUBindGroupEntry[] = [
+        { 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);
+  }
+
+  private renderTileRaster(
+    passEncoder: GPURenderPassEncoder,
+    drawBuffer: GPUBuffer,
+    count: number,
+    viewProj: number[],
+    resolution: [number, number],
+  ): void {
+    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(): void {
+    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;
+  }
+}

package/libraries/gaussian-splats/src/sh-eval.ts

@@ -0,0 +1,211 @@
+// ============================================================================
+// Spherical harmonics evaluation for Gaussian splatting
+//
+// INRIA-format PLY stores SH coefficients as:
+//   f_dc_0..2  — degree-0 DC (3 coeffs, one per RGB channel)
+//   f_rest_0..44 — degrees 1-3 (45 coeffs = 15 per channel × 3 channels)
+//
+// The f_rest layout per splat is: [R0..R14, G0..G14, B0..B14]
+// where each channel has 15 coeffs: 3 (deg 1) + 5 (deg 2) + 7 (deg 3).
+//
+// The DC color is already baked into `GaussianSplatData.color` by the parser.
+// This module handles the "rest" coefficients (degrees 1-3) for view-dependent
+// color: the final color = DC_color + evalSH(coeffs, viewDir).
+// ============================================================================
+
+import type { GaussianSplatData } from "./parser";
+
+// ── Coefficient counts ──
+
+/** SH "rest" coefficients per channel for each degree (degrees 1..N). */
+export const SH_COEFFS_PER_CHANNEL: readonly number[] = [0, 3, 8, 15];
+/** Total SH "rest" coefficients per splat (3 channels) for each degree. */
+export const SH_COEFFS_TOTAL: readonly number[] = [0, 9, 24, 45];
+
+// ── SH basis constants (real spherical harmonics) ──
+
+const SH_C1 = 0.48860251190292;
+const SH_C2: readonly number[] = [
+  1.09256843064181, // Y_2^{-2} = xy
+  1.09256843064181, // Y_2^{-1} = yz
+  0.31539156525252, // Y_2^0 = 3zz - 1
+  1.09256843064181, // Y_2^1 = xz
+  0.546274215320904, // Y_2^2 = xx - yy
+];
+const SH_C3: readonly number[] = [
+  0.59004364580555, // Y_3^{-3} = y(3xx - yy)
+  2.89061144264055,  // Y_3^{-2} = xyz
+  0.457045799464466, // Y_3^{-1} = y(5zz - 1)
+  0.373176332573636, // Y_3^0 = z(5zz - 3)
+  0.457045799464466, // Y_3^1 = x(5zz - 1)
+  1.44530572132028,  // Y_3^2 = z(xx - yy)
+  0.59004364580555, // Y_3^3 = x(xx - 3yy)
+];
+
+// ── Packing ──
+
+/**
+ * Pack SH "rest" coefficients from parsed data, truncated to `maxDegree`.
+ * If the parsed data has degree 3 but the game configures `maxDegree: 1`,
+ * only 9 coeffs/splat (3 per channel) are packed — saving GPU memory.
+ *
+ * Returns an empty Float32Array if `maxDegree === 0` or the data has no SH.
+ */
+export function packShCoeffs(data: GaussianSplatData, maxDegree: number): Float32Array {
+  if (maxDegree <= 0 || data.shDegree <= 0 || data.shCoeffs.length === 0) {
+    return new Float32Array(0);
+  }
+
+  const effectiveDegree = Math.min(maxDegree, data.shDegree);
+  const dstPerChannel = SH_COEFFS_PER_CHANNEL[effectiveDegree];
+  const dstTotal = dstPerChannel * 3;
+  const srcPerChannel = SH_COEFFS_PER_CHANNEL[data.shDegree];
+  const result = new Float32Array(data.count * dstTotal);
+
+  for (let i = 0; i < data.count; i++) {
+    const srcBase = i * (srcPerChannel * 3);
+    const dstBase = i * dstTotal;
+    for (let ch = 0; ch < 3; ch++) {
+      const srcCh = srcBase + ch * srcPerChannel;
+      const dstCh = dstBase + ch * dstPerChannel;
+      for (let c = 0; c < dstPerChannel; c++) {
+        result[dstCh + c] = data.shCoeffs[srcCh + c];
+      }
+    }
+  }
+
+  return result;
+}
+
+// ── WGSL evaluation chunk ──
+
+/**
+ * WGSL chunk for SH evaluation. Insert into the fragment shader.
+ *
+ * Declares:
+ *   @group(0) @binding(2) var<storage, read> shCoeffs: array<f32>;
+ *   @group(0) @binding(3) var<uniform> shParams: ShParams;
+ *
+ * Provides: `fn evalSH(splatIdx: u32, dir: vec3<f32>) -> vec3<f32>`
+ *
+ * The `dir` should be the normalized view direction (cameraPos - splatPos).
+ * Returns the SH color contribution (to be added to the DC color).
+ * Returns vec3(0) when shDegree == 0.
+ */
+export const SH_EVAL_WGSL = /* wgsl */ `
+struct ShParams {
+  shDegree: u32,
+  coeffsPerSplat: u32,
+  _pad0: u32,
+  _pad1: u32,
+}
+
+@group(0) @binding(2) var<storage, read> shCoeffs: array<f32>;
+@group(0) @binding(3) var<uniform> shParams: ShParams;
+
+fn evalSH(splatIdx: u32, dir: vec3<f32>) -> vec3<f32> {
+  if (shParams.shDegree == 0u) {
+    return vec3<f32>(0.0);
+  }
+  let base = splatIdx * shParams.coeffsPerSplat;
+  let cpc = shParams.coeffsPerSplat / 3u;
+  let x = dir.x;
+  let y = dir.y;
+  let z = dir.z;
+  var r = 0.0;
+  var g = 0.0;
+  var b = 0.0;
+
+  if (shParams.shDegree >= 1u) {
+    // Degree 1: 3 coeffs per channel
+    let o = 0u;
+    r += shCoeffs[base + o + 0u] * ${SH_C1} * y;
+    r += shCoeffs[base + o + 1u] * ${SH_C1} * z;
+    r += shCoeffs[base + o + 2u] * ${SH_C1} * x;
+    g += shCoeffs[base + cpc + o + 0u] * ${SH_C1} * y;
+    g += shCoeffs[base + cpc + o + 1u] * ${SH_C1} * z;
+    g += shCoeffs[base + cpc + o + 2u] * ${SH_C1} * x;
+    b += shCoeffs[base + 2u * cpc + o + 0u] * ${SH_C1} * y;
+    b += shCoeffs[base + 2u * cpc + o + 1u] * ${SH_C1} * z;
+    b += shCoeffs[base + 2u * cpc + o + 2u] * ${SH_C1} * x;
+  }
+
+  if (shParams.shDegree >= 2u) {
+    // Degree 2: 5 coeffs per channel (offset 3)
+    let o = 3u;
+    r += shCoeffs[base + o + 0u] * ${SH_C2[0]} * x * y;
+    r += shCoeffs[base + o + 1u] * ${SH_C2[1]} * y * z;
+    r += shCoeffs[base + o + 2u] * ${SH_C2[2]} * (3.0 * z * z - 1.0);
+    r += shCoeffs[base + o + 3u] * ${SH_C2[3]} * x * z;
+    r += shCoeffs[base + o + 4u] * ${SH_C2[4]} * (x * x - y * y);
+    g += shCoeffs[base + cpc + o + 0u] * ${SH_C2[0]} * x * y;
+    g += shCoeffs[base + cpc + o + 1u] * ${SH_C2[1]} * y * z;
+    g += shCoeffs[base + cpc + o + 2u] * ${SH_C2[2]} * (3.0 * z * z - 1.0);
+    g += shCoeffs[base + cpc + o + 3u] * ${SH_C2[3]} * x * z;
+    g += shCoeffs[base + cpc + o + 4u] * ${SH_C2[4]} * (x * x - y * y);
+    b += shCoeffs[base + 2u * cpc + o + 0u] * ${SH_C2[0]} * x * y;
+    b += shCoeffs[base + 2u * cpc + o + 1u] * ${SH_C2[1]} * y * z;
+    b += shCoeffs[base + 2u * cpc + o + 2u] * ${SH_C2[2]} * (3.0 * z * z - 1.0);
+    b += shCoeffs[base + 2u * cpc + o + 3u] * ${SH_C2[3]} * x * z;
+    b += shCoeffs[base + 2u * cpc + o + 4u] * ${SH_C2[4]} * (x * x - y * y);
+  }
+
+  if (shParams.shDegree >= 3u) {
+    // Degree 3: 7 coeffs per channel (offset 8)
+    let o = 8u;
+    r += shCoeffs[base + o + 0u] * ${SH_C3[0]} * y * (3.0 * x * x - y * y);
+    r += shCoeffs[base + o + 1u] * ${SH_C3[1]} * x * y * z;
+    r += shCoeffs[base + o + 2u] * ${SH_C3[2]} * y * (5.0 * z * z - 1.0);
+    r += shCoeffs[base + o + 3u] * ${SH_C3[3]} * z * (5.0 * z * z - 3.0);
+    r += shCoeffs[base + o + 4u] * ${SH_C3[4]} * x * (5.0 * z * z - 1.0);
+    r += shCoeffs[base + o + 5u] * ${SH_C3[5]} * z * (x * x - y * y);
+    r += shCoeffs[base + o + 6u] * ${SH_C3[6]} * x * (x * x - 3.0 * y * y);
+    g += shCoeffs[base + cpc + o + 0u] * ${SH_C3[0]} * y * (3.0 * x * x - y * y);
+    g += shCoeffs[base + cpc + o + 1u] * ${SH_C3[1]} * x * y * z;
+    g += shCoeffs[base + cpc + o + 2u] * ${SH_C3[2]} * y * (5.0 * z * z - 1.0);
+    g += shCoeffs[base + cpc + o + 3u] * ${SH_C3[3]} * z * (5.0 * z * z - 3.0);
+    g += shCoeffs[base + cpc + o + 4u] * ${SH_C3[4]} * x * (5.0 * z * z - 1.0);
+    g += shCoeffs[base + cpc + o + 5u] * ${SH_C3[5]} * z * (x * x - y * y);
+    g += shCoeffs[base + cpc + o + 6u] * ${SH_C3[6]} * x * (x * x - 3.0 * y * y);
+    b += shCoeffs[base + 2u * cpc + o + 0u] * ${SH_C3[0]} * y * (3.0 * x * x - y * y);
+    b += shCoeffs[base + 2u * cpc + o + 1u] * ${SH_C3[1]} * x * y * z;
+    b += shCoeffs[base + 2u * cpc + o + 2u] * ${SH_C3[2]} * y * (5.0 * z * z - 1.0);
+    b += shCoeffs[base + 2u * cpc + o + 3u] * ${SH_C3[3]} * z * (5.0 * z * z - 3.0);
+    b += shCoeffs[base + 2u * cpc + o + 4u] * ${SH_C3[4]} * x * (5.0 * z * z - 1.0);
+    b += shCoeffs[base + 2u * cpc + o + 5u] * ${SH_C3[5]} * z * (x * x - y * y);
+    b += shCoeffs[base + 2u * cpc + o + 6u] * ${SH_C3[6]} * x * (x * x - 3.0 * y * y);
+  }
+
+  return vec3<f32>(r, g, b);
+}
+`;
+
+// ── CPU SH evaluation (for testing / reference) ──
+
+/** Evaluate SH on CPU for a single channel. coeffs = 15 f_rest values for one channel. */
+export function evalSHChannelCPU(coeffs: number[], degree: number, dir: [number, number, number]): number {
+  const [x, y, z] = dir;
+  let result = 0;
+  if (degree >= 1) {
+    result += coeffs[0] * SH_C1 * y;
+    result += coeffs[1] * SH_C1 * z;
+    result += coeffs[2] * SH_C1 * x;
+  }
+  if (degree >= 2) {
+    result += coeffs[3] * SH_C2[0] * x * y;
+    result += coeffs[4] * SH_C2[1] * y * z;
+    result += coeffs[5] * SH_C2[2] * (3 * z * z - 1);
+    result += coeffs[6] * SH_C2[3] * x * z;
+    result += coeffs[7] * SH_C2[4] * (x * x - y * y);
+  }
+  if (degree >= 3) {
+    result += coeffs[8] * SH_C3[0] * y * (3 * x * x - y * y);
+    result += coeffs[9] * SH_C3[1] * x * y * z;
+    result += coeffs[10] * SH_C3[2] * y * (5 * z * z - 1);
+    result += coeffs[11] * SH_C3[3] * z * (5 * z * z - 3);
+    result += coeffs[12] * SH_C3[4] * x * (5 * z * z - 1);
+    result += coeffs[13] * SH_C3[5] * z * (x * x - y * y);
+    result += coeffs[14] * SH_C3[6] * x * (x * x - 3 * y * y);
+  }
+  return result;
+}