@downdraft/engine 0.0.0 → 0.1.0

package/core/src/render/lighting/cluster-grid.ts

@@ -0,0 +1,288 @@
+import {
+    CLUSTER_GRID_ENTRY_SIZE,
+    computeClusterCount,
+    computeLightDataBufferSize,
+    computeLightIndexListSize,
+    packClusterUniforms,
+    type ClusterGridConfig
+} from "./cluster-types";
+import { createValidatedShaderModule } from "../shader-validator";
+
+const CLUSTER_BUILD_SHADER = /* wgsl */ `
+struct ClusterUniforms {
+  clusterDims: vec3<u32>,
+  screenWidth: f32,
+  screenHeight: f32,
+  nearPlane: f32,
+  farPlane: f32,
+  numLights: u32,
+  _pad: u32,
+};
+
+struct LightData {
+  position: vec4<f32>,
+  color: vec4<f32>,
+  direction: vec4<f32>,
+  params: vec4<f32>,
+};
+
+struct ClusterEntry {
+  offset: u32,
+  count: u32,
+};
+
+@group(0) @binding(0) var<uniform> uniforms: ClusterUniforms;
+@group(0) @binding(1) var<storage> lightData: array<LightData>;
+@group(0) @binding(2) var<storage, read_write> lightGrid: array<ClusterEntry>;
+@group(0) @binding(3) var<storage, read_write> lightIndexList: array<u32>;
+
+fn logDepth(near: f32, far: f32, slice: f32, numSlices: f32) -> f32 {
+  return near * pow(far / near, slice / numSlices);
+}
+
+fn screenToView(uv: vec2<f32>, screenW: f32, screenH: f32) -> vec2<f32> {
+  let ndc = uv * 2.0 - 1.0;
+  return vec2<f32>(ndc.x * screenW * 0.5, -ndc.y * screenH * 0.5);
+}
+
+fn sphereIntersectsAABB(
+  center: vec3<f32>,
+  radius: f32,
+  minPoint: vec3<f32>,
+  maxPoint: vec3<f32>,
+) -> bool {
+  let closest = clamp(center, minPoint, maxPoint);
+  let dist = length(center - closest);
+  return dist <= radius;
+}
+
+fn coneIntersectsAABB(
+  apex: vec3<f32>,
+  dir: vec3<f32>,
+  range: f32,
+  cosHalfAngle: f32,
+  minPoint: vec3<f32>,
+  maxPoint: vec3<f32>,
+) -> bool {
+  // Simplified: test sphere at midpoint + radius = range * sin(halfAngle) + range*0.5
+  let midPoint = apex + dir * range * 0.5;
+  let sphereRadius = range * 0.5 + range * sin(acos(cosHalfAngle));
+  return sphereIntersectsAABB(midPoint, sphereRadius, minPoint, maxPoint);
+}
+
+@compute @workgroup_size(4, 4, 4)
+fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let clusterDims = uniforms.clusterDims;
+  if (gid.x >= clusterDims.x || gid.y >= clusterDims.y || gid.z >= clusterDims.z) {
+    return;
+  }
+
+  let clusterIdx = gid.x + gid.y * clusterDims.x + gid.z * clusterDims.x * clusterDims.y;
+
+  // Compute cluster AABB in view space
+  let tileSizeX = 2.0 / f32(clusterDims.x);
+  let tileSizeY = 2.0 / f32(clusterDims.y);
+
+  let minNDC = vec2<f32>(
+    f32(gid.x) * tileSizeX - 1.0,
+    f32(gid.y) * tileSizeY - 1.0,
+  );
+  let maxNDC = vec2<f32>(
+    (f32(gid.x) + 1.0) * tileSizeX - 1.0,
+    (f32(gid.y) + 1.0) * tileSizeY - 1.0,
+  );
+
+  let near = uniforms.nearPlane;
+  let far = uniforms.farPlane;
+  let zNear = logDepth(near, far, f32(gid.z), f32(clusterDims.z));
+  let zFar = logDepth(near, far, f32(gid.z + 1.0), f32(clusterDims.z));
+
+  // View-space AABB (approximate using NDC at near plane)
+  let minPoint = vec3<f32>(minNDC.x * zNear, -maxNDC.y * zNear, zNear);
+  let maxPoint = vec3<f32>(maxNDC.x * zNear, -minNDC.y * zNear, zFar);
+
+  var count = 0u;
+  let offset = clusterIdx * ${128}u; // maxLightsPerCluster — will be replaced
+
+  for (var i = 0u; i < uniforms.numLights; i = i + 1u) {
+    let light = lightData[i];
+    let lightType = u32(light.direction.w);
+    let lightRange = light.position.w;
+
+    var intersects = false;
+    if (lightType == 0u) {
+      // Point light — sphere vs AABB
+      intersects = sphereIntersectsAABB(light.position.xyz, lightRange, minPoint, maxPoint);
+    } else if (lightType == 1u) {
+      // Spot light — cone vs AABB
+      let cosAngle = light.params.x;
+      intersects = coneIntersectsAABB(
+        light.position.xyz,
+        light.direction.xyz,
+        lightRange,
+        cosAngle,
+        minPoint,
+        maxPoint,
+      );
+    } else {
+      // Rect area light — approximate as sphere
+      intersects = sphereIntersectsAABB(light.position.xyz, lightRange, minPoint, maxPoint);
+    }
+
+    if (intersects) {
+      if (count < ${128}u) {
+        lightIndexList[offset + count] = i;
+        count = count + 1u;
+      }
+    }
+  }
+
+  lightGrid[clusterIdx] = ClusterEntry(offset, count);
+}
+`;
+
+export class ClusterGrid {
+  private config: ClusterGridConfig;
+  private device: GPUDevice | null = null;
+
+  private uniformBuffer: GPUBuffer | null = null;
+  private lightDataBuffer: GPUBuffer | null = null;
+  private lightGridBuffer: GPUBuffer | null = null;
+  private lightIndexListBuffer: GPUBuffer | null = null;
+
+  private computePipeline: GPUComputePipeline | null = null;
+  private computeBindGroup: GPUBindGroup | null = null;
+
+  private screenWidth = 1920;
+  private screenHeight = 1080;
+  private currentLightCount = 0;
+
+  constructor(config: ClusterGridConfig, device?: GPUDevice | null) {
+    this.config = config;
+    this.device = device ?? null;
+  }
+
+  get clusterCount(): number { return computeClusterCount(this.config); }
+  get lightDataSize(): number { return computeLightDataBufferSize(this.config); }
+  get lightGridSize(): number { return this.clusterCount * CLUSTER_GRID_ENTRY_SIZE; }
+  get lightIndexListSize(): number { return computeLightIndexListSize(this.config) * 4; }
+
+  prepare(device: GPUDevice): void {
+    this.device = device;
+    const clusterCount = this.clusterCount;
+    const maxLightsPerCluster = this.config.maxLightsPerCluster;
+
+    this.uniformBuffer = device.createBuffer({
+      label: "cluster-uniforms",
+      size: 32,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+
+    this.lightDataBuffer = device.createBuffer({
+      label: "cluster-light-data",
+      size: this.lightDataSize,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    });
+
+    this.lightGridBuffer = device.createBuffer({
+      label: "cluster-light-grid",
+      size: this.lightGridSize,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    });
+
+    this.lightIndexListBuffer = device.createBuffer({
+      label: "cluster-light-index-list",
+      size: this.lightIndexListSize,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    });
+
+    const shader = createValidatedShaderModule(device, {
+      code: CLUSTER_BUILD_SHADER.replace(/\$\{128\}u/g, `${maxLightsPerCluster}u`),
+      label: "ClusterGrid.build",
+    });
+
+    this.computePipeline = device.createComputePipeline({
+      label: "cluster-build",
+      layout: "auto",
+      compute: { module: shader, entryPoint: "cs_main" },
+    });
+  }
+
+  updateUniforms(screenWidth: number, screenHeight: number, numLights: number): void {
+    this.screenWidth = screenWidth;
+    this.screenHeight = screenHeight;
+    this.currentLightCount = numLights;
+
+    const packed = packClusterUniforms(this.config, screenWidth, screenHeight, numLights);
+    if (this.device && this.uniformBuffer) {
+      this.device.queue.writeBuffer(this.uniformBuffer, 0, packed as unknown as BufferSource);
+    }
+  }
+
+  updateLightData(lightData: Float32Array): void {
+    if (this.device && this.lightDataBuffer) {
+      this.device.queue.writeBuffer(this.lightDataBuffer, 0, lightData as unknown as BufferSource);
+    }
+  }
+
+  dispatch(encoder: GPUCommandEncoder | null): void {
+    if (this.device && this.computePipeline) {
+      if (!this.computeBindGroup) {
+        this.computeBindGroup = this.device.createBindGroup({
+          layout: this.computePipeline.getBindGroupLayout(0),
+          entries: [
+            { binding: 0, resource: { buffer: this.uniformBuffer! } },
+            { binding: 1, resource: { buffer: this.lightDataBuffer! } },
+            { binding: 2, resource: { buffer: this.lightGridBuffer! } },
+            { binding: 3, resource: { buffer: this.lightIndexListBuffer! } },
+          ],
+        });
+      }
+
+      const pass = encoder!.beginComputePass({ label: "cluster-build" });
+      pass.setPipeline(this.computePipeline);
+      pass.setBindGroup(0, this.computeBindGroup);
+      const wx = Math.ceil(this.config.clusterX / 4);
+      const wy = Math.ceil(this.config.clusterY / 4);
+      const wz = Math.ceil(this.config.clusterZ / 4);
+      pass.dispatchWorkgroups(wx, wy, wz);
+      pass.end();
+    }
+  }
+
+  getLightGridBuffer(): GPUBuffer | null {
+    return this.lightGridBuffer;
+  }
+
+  getLightIndexListBuffer(): GPUBuffer | null {
+    return this.lightIndexListBuffer;
+  }
+
+  getLightDataBuffer(): GPUBuffer | null {
+    return this.lightDataBuffer;
+  }
+
+  getUniformBuffer(): GPUBuffer | null {
+    return this.uniformBuffer;
+  }
+
+  getBindGroupLayout(): GPUBindGroupLayout | null {
+    if (this.computePipeline) {
+      return this.computePipeline.getBindGroupLayout(0);
+    }
+    return null;
+  }
+
+  getConfig(): ClusterGridConfig {
+    return this.config;
+  }
+
+  destroy(): void {
+    if (this.device) {
+      (this.uniformBuffer as GPUBuffer)?.destroy();
+      (this.lightDataBuffer as GPUBuffer)?.destroy();
+      (this.lightGridBuffer as GPUBuffer)?.destroy();
+      (this.lightIndexListBuffer as GPUBuffer)?.destroy();
+    }
+  }
+}

package/core/src/render/lighting/cluster-types.ts

@@ -0,0 +1,193 @@
+import type { Vec3 } from "wgpu-matrix";
+
+export type LightShapeType = 0 | 1 | 2; // 0=point, 1=spot, 2=rect-area
+
+export interface ClusterGridConfig {
+  clusterX: number;
+  clusterY: number;
+  clusterZ: number;
+  maxLightsPerCluster: number;
+  maxTotalLights: number;
+  nearPlane: number;
+  farPlane: number;
+  depthDistributionScale: number;
+}
+
+export const DEFAULT_CLUSTER_CONFIG: ClusterGridConfig = {
+  clusterX: 16,
+  clusterY: 8,
+  clusterZ: 24,
+  maxLightsPerCluster: 128,
+  maxTotalLights: 1024,
+  nearPlane: 0.1,
+  farPlane: 1000.0,
+  depthDistributionScale: 3.0,
+};
+
+export interface GPULightData {
+  position: Vec3;
+  radius: number;
+  color: Vec3;
+  intensity: number;
+  direction: Vec3;
+  type: number;
+  innerConeCos: number;
+  outerConeCos: number;
+  range: number;
+  width: number;
+  height: number;
+  _pad: number;
+  _pad2: number;
+}
+
+export const LIGHT_DATA_SIZE = 64; // 16 floats per light = 64 bytes
+export const LIGHT_DATA_FLOATS = 16;
+
+export interface ClusterUniforms {
+  clusterDimensions: [number, number, number];
+  screenDimensions: [number, number];
+  nearPlane: number;
+  farPlane: number;
+  depthScale: number;
+  numLights: number;
+  _pad: number;
+}
+
+export const CLUSTER_UNIFORM_SIZE = 32; // 8 floats
+
+export const CLUSTER_GRID_FLOATS_PER_ENTRY = 2; // offset, count
+export const CLUSTER_GRID_ENTRY_SIZE = 8; // 2 * u32 = 8 bytes
+
+export function computeClusterCount(config: ClusterGridConfig): number {
+  return config.clusterX * config.clusterY * config.clusterZ;
+}
+
+export function computeLightIndexListSize(config: ClusterGridConfig): number {
+  return computeClusterCount(config) * config.maxLightsPerCluster;
+}
+
+export function computeClusterGridBufferSize(config: ClusterGridConfig): number {
+  return computeClusterCount(config) * CLUSTER_GRID_ENTRY_SIZE;
+}
+
+export function computeLightDataBufferSize(config: ClusterGridConfig): number {
+  return config.maxTotalLights * LIGHT_DATA_SIZE;
+}
+
+export function depthSliceToNear(
+  slice: number,
+  clusterZ: number,
+  near: number,
+  far: number,
+  scale: number,
+): number {
+  const linearDist = near + (far - near) * (slice / clusterZ);
+  return near * Math.pow(far / near, slice / clusterZ);
+}
+
+export function worldDepthToSlice(
+  depth: number,
+  clusterZ: number,
+  near: number,
+  far: number,
+  _scale: number,
+): number {
+  if (depth <= near) return 0;
+  if (depth >= far) return clusterZ - 1;
+  const logDepth = Math.log(depth / near) / Math.log(far / near);
+  return Math.min(Math.floor(logDepth * clusterZ), clusterZ - 1);
+}
+
+export function screenPosToClusterXY(
+  screenX: number,
+  screenY: number,
+  clusterX: number,
+  clusterY: number,
+): [number, number] {
+  const cx = Math.min(Math.floor(screenX * clusterX), clusterX - 1);
+  const cy = Math.min(Math.floor(screenY * clusterY), clusterY - 1);
+  return [cx, cy];
+}
+
+export function clusterIndex3D(
+  cx: number,
+  cy: number,
+  cz: number,
+  clusterX: number,
+  clusterY: number,
+): number {
+  return cx + cy * clusterX + cz * clusterX * clusterY;
+}
+
+export function packLightToStorageBuffer(light: {
+  position: Vec3;
+  color: Vec3;
+  intensity: number;
+  range: number;
+  direction?: Vec3;
+  type?: LightShapeType;
+  innerConeCos?: number;
+  outerConeCos?: number;
+  width?: number;
+  height?: number;
+}): Float32Array {
+  const buf = new Float32Array(LIGHT_DATA_FLOATS);
+  buf[0] = light.position[0];
+  buf[1] = light.position[1];
+  buf[2] = light.position[2];
+  buf[3] = light.range;
+  buf[4] = light.color[0];
+  buf[5] = light.color[1];
+  buf[6] = light.color[2];
+  buf[7] = light.intensity;
+  buf[8] = light.direction ? light.direction[0] : 0;
+  buf[9] = light.direction ? light.direction[1] : 0;
+  buf[10] = light.direction ? light.direction[2] : 0;
+  buf[11] = light.type ?? 0;
+  buf[12] = light.innerConeCos ?? 0;
+  buf[13] = light.outerConeCos ?? 0;
+  buf[14] = light.width ?? 0;
+  buf[15] = light.height ?? 0;
+  return buf;
+}
+
+export function packLightsArray(
+  lights: Array<ReturnType<typeof Object> & {
+    position: Vec3;
+    color: Vec3;
+    intensity: number;
+    range: number;
+    direction?: Vec3;
+    type?: LightShapeType;
+    innerConeCos?: number;
+    outerConeCos?: number;
+    width?: number;
+    height?: number;
+  }>,
+  maxLights: number,
+): Float32Array {
+  const buf = new Float32Array(maxLights * LIGHT_DATA_FLOATS);
+  for (let i = 0; i < Math.min(lights.length, maxLights); i++) {
+    const packed = packLightToStorageBuffer(lights[i]);
+    buf.set(packed, i * LIGHT_DATA_FLOATS);
+  }
+  return buf;
+}
+
+export function packClusterUniforms(
+  config: ClusterGridConfig,
+  screenWidth: number,
+  screenHeight: number,
+  numLights: number,
+): Float32Array {
+  const buf = new Float32Array(8);
+  buf[0] = config.clusterX;
+  buf[1] = config.clusterY;
+  buf[2] = config.clusterZ;
+  buf[3] = screenWidth;
+  buf[4] = screenHeight;
+  buf[5] = config.nearPlane;
+  buf[6] = config.farPlane;
+  buf[7] = numLights;
+  return buf;
+}

package/core/src/render/lighting/ies-parser.ts

@@ -0,0 +1,162 @@
+export interface IESProfile {
+  label: string;
+  photometricType: number;
+  lumens: number;
+  candelaMultiplier: number;
+  numVerticalAngles: number;
+  numHorizontalAngles: number;
+  verticalAngles: Float32Array;
+  horizontalAngles: Float32Array;
+  candelaValues: Float32Array;
+  width: number;
+  height: number;
+}
+
+export interface IESLoadOptions {
+  label?: string;
+  maxTextureSize?: number;
+}
+
+export function parseIES(data: string, options?: IESLoadOptions): IESProfile {
+  const lines = data.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+  let lineIdx = 0;
+
+  const label = options?.label ?? `IES-${Date.now()}`;
+
+  // IES header — "IESNA:LM-63" or just "IESNA"
+  const header = lines[lineIdx++] || "";
+
+  // Skip tilt line
+  const tilt = lines[lineIdx++] || "";
+  void tilt;
+
+  // Read property lines until we hit the numeric data
+  // Properties start with "[" and end with "]"
+  const properties: Record<string, string> = {};
+  while (lineIdx < lines.length && lines[lineIdx].startsWith("[")) {
+    const propLine = lines[lineIdx++];
+    const match = propLine.match(/\[(.*?)\]/);
+    if (match) {
+      const parts = match[1].split("=");
+      if (parts.length === 2) {
+        properties[parts[0].trim()] = parts[1].trim();
+      }
+    }
+  }
+
+  // Now read the numeric data
+  // Line format: <lumens> <candelaMultiplier> <numVerticalAngles> <numHorizontalAngles> <photometricType> <unitsType> <width> <length> <height>
+  const dimsLine = lines[lineIdx++] || "";
+  const dimsParts = dimsLine.split(/\s+/).filter((s) => s.length > 0);
+
+  const lumens = parseFloat(dimsParts[0] || "0");
+  const candelaMultiplier = parseFloat(dimsParts[1] || "1");
+  const numVerticalAngles = parseInt(dimsParts[2] || "0", 10);
+  const numHorizontalAngles = parseInt(dimsParts[3] || "0", 10);
+  const photometricType = parseInt(dimsParts[4] || "1", 10);
+  const width = parseFloat(dimsParts[6] || "0");
+  const height = parseFloat(dimsParts[7] || "0");
+
+  // Read vertical angles
+  const verticalAngles = new Float32Array(numVerticalAngles);
+  let vIdx = 0;
+  while (vIdx < numVerticalAngles && lineIdx < lines.length) {
+    const parts = lines[lineIdx++].split(/\s+/).filter((s) => s.length > 0);
+    parts.forEach((p) => {
+      if (vIdx < numVerticalAngles) {
+        verticalAngles[vIdx++] = parseFloat(p);
+      }
+    });
+  }
+
+  // Read horizontal angles + candela values
+  const horizontalAngles = new Float32Array(numHorizontalAngles);
+  const candelaValues = new Float32Array(numHorizontalAngles * numVerticalAngles);
+  let hIdx = 0;
+  let cIdx = 0;
+
+  while (hIdx < numHorizontalAngles && lineIdx < lines.length) {
+    // First number on the line is the horizontal angle
+    const firstParts = lines[lineIdx++].split(/\s+/).filter((s) => s.length > 0);
+    if (firstParts.length === 0) continue;
+
+    horizontalAngles[hIdx] = parseFloat(firstParts[0]);
+    const remaining = firstParts.slice(1);
+    remaining.forEach((p) => {
+      if (cIdx < candelaValues.length) {
+        candelaValues[cIdx++] = parseFloat(p);
+      }
+    });
+
+    // Read remaining candela values for this horizontal angle
+    while (cIdx < (hIdx + 1) * numVerticalAngles && lineIdx < lines.length) {
+      const parts = lines[lineIdx++].split(/\s+/).filter((s) => s.length > 0);
+      parts.forEach((p) => {
+        if (cIdx < candelaValues.length) {
+          candelaValues[cIdx++] = parseFloat(p);
+        }
+      });
+    }
+    hIdx++;
+  }
+
+  return {
+    label,
+    photometricType,
+    lumens,
+    candelaMultiplier,
+    numVerticalAngles,
+    numHorizontalAngles,
+    verticalAngles,
+    horizontalAngles,
+    candelaValues,
+    width,
+    height,
+  };
+}
+
+export function iesProfileToTextureData(
+  profile: IESProfile,
+  maxWidth: number = 180,
+  maxHeight: number = 90,
+): { data: Float32Array; width: number; height: number } {
+  const width = Math.min(profile.numHorizontalAngles, maxWidth);
+  const height = Math.min(profile.numVerticalAngles, maxHeight);
+  const data = new Float32Array(width * height);
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const hIdx = Math.min(x, profile.numHorizontalAngles - 1);
+      const vIdx = Math.min(y, profile.numVerticalAngles - 1);
+      const candela = profile.candelaValues[hIdx * profile.numVerticalAngles + vIdx];
+      data[y * width + x] = candela * profile.candelaMultiplier;
+    }
+  }
+
+  return { data, width, height };
+}
+
+export function createIESGpuTexture(
+  device: GPUDevice,
+  profile: IESProfile,
+  maxWidth: number = 180,
+  maxHeight: number = 90,
+): GPUTexture {
+  const { data, width, height } = iesProfileToTextureData(profile, maxWidth, maxHeight);
+
+  const texture = device.createTexture({
+    label: `ies-${profile.label}`,
+    size: [width, height],
+    format: "r16float",
+    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+  });
+
+  device.queue.writeTexture(
+    { texture },
+    data as unknown as BufferSource,
+    { bytesPerRow: width * 2, rowsPerImage: height },
+    [width, height],
+  );
+
+  return texture;
+}