@aethervtt/shard-render 0.0.1

package/dist/camera.d.ts

@@ -0,0 +1,83 @@
+import { type Infer } from '@aethervtt/shard-core';
+/** Light presets in lux, paired with the exposure presets below. */
+export declare const LightPresets: {
+    readonly 'direct-sun': 100000;
+    readonly daylight: 10000;
+    readonly overcast: 1000;
+    readonly indoor: 400;
+    readonly twilight: 10;
+    readonly moonlight: 0.3;
+};
+export type LightPreset = keyof typeof LightPresets;
+/** EV100 from scene illuminance (incident-light meter, ISO 100): EV100 = log2(lux / 2.5). */
+export declare function ev100FromIlluminance(lux: number): number;
+/** Exposure presets in EV100, matched to the light presets. */
+export declare const ExposurePresets: {
+    readonly sunny: number;
+    readonly daylight: number;
+    readonly overcast: number;
+    readonly indoor: number;
+    readonly twilight: number;
+};
+export type ExposurePreset = keyof typeof ExposurePresets;
+/** Illuminance for a preset name or a number (lux). */
+export declare const lux: (value: LightPreset | number) => number;
+/** EV100 for a preset name or a number. */
+export declare const ev100: (value: ExposurePreset | number) => number;
+/** The multiplier from scene luminance to display, for an EV100 (Lagarde & de Rousiers, 2014). */
+export declare function exposureScale(ev: number): number;
+/** EV100 from photographic settings: log2(N² / t · 100 / S). */
+export declare function ev100FromCamera(aperture: number, shutterSpeed: number, iso: number): number;
+export declare const Exposure: import("@aethervtt/shard-core").ComponentDef<{
+    readonly ev100: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const Camera3d: import("@aethervtt/shard-core").ComponentDef<{
+    readonly projection: import("@aethervtt/shard-core").FieldType<"orthographic" | "perspective", "u8">;
+    readonly fovY: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly near: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly orthoHeight: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly far: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly order: import("@aethervtt/shard-core").FieldType<number, "i32">;
+    readonly clearColor: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly target: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"RenderTarget"> | null, "object">;
+    readonly active: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;
+export type Camera3dValue = Infer<typeof Camera3d>;
+export declare const PhysicalCamera: import("@aethervtt/shard-core").ComponentDef<{
+    readonly aperture: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly shutterSpeed: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly iso: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly sensorHeight: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly focalLength: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+/** A 2D camera: orthographic, looking down -Z. Use as `world.spawn(...camera2d({ height: 20 }))`. */
+export declare function camera2d(options?: {
+    height?: number;
+    order?: number;
+    clearColor?: [number, number, number, number];
+}): readonly [readonly [import("@aethervtt/shard-core").ComponentDef<{
+    readonly projection: import("@aethervtt/shard-core").FieldType<"orthographic" | "perspective", "u8">;
+    readonly fovY: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly near: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly orthoHeight: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly far: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly order: import("@aethervtt/shard-core").FieldType<number, "i32">;
+    readonly clearColor: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly target: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"RenderTarget"> | null, "object">;
+    readonly active: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>, {
+    readonly projection: 'orthographic';
+    readonly orthoHeight: number;
+    readonly order: number;
+    readonly clearColor?: [number, number, number, number] | undefined;
+}], readonly [import("@aethervtt/shard-core").ComponentDef<{
+    readonly translation: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+    readonly rotation: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Quat, "f32">;
+    readonly scale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+}>, {
+    readonly translation: [number, number, number];
+}]];
+/** PhysicalCamera → Exposure (and fovY when a focal length is set). */
+export declare const applyPhysicalCameras: import("@aethervtt/shard-core").SystemDef<{
+    q: import("@aethervtt/shard-core").Query;
+}>;

package/dist/camera.js

@@ -0,0 +1,163 @@
+import { defineComponent, defineSystem, t } from "@aethervtt/shard-core";
+import { Transform } from "@aethervtt/shard-transform";
+const LightPresets = {
+  "direct-sun": 1e5,
+  daylight: 1e4,
+  overcast: 1e3,
+  indoor: 400,
+  twilight: 10,
+  moonlight: 0.3
+};
+function ev100FromIlluminance(lux2) {
+  return Math.log2(lux2 / 2.5);
+}
+const ExposurePresets = {
+  sunny: ev100FromIlluminance(LightPresets["direct-sun"]),
+  daylight: ev100FromIlluminance(LightPresets.daylight),
+  overcast: ev100FromIlluminance(LightPresets.overcast),
+  indoor: ev100FromIlluminance(LightPresets.indoor),
+  twilight: ev100FromIlluminance(LightPresets.twilight)
+};
+const lux = (value) => typeof value === "number" ? value : LightPresets[value];
+const ev100 = (value) => typeof value === "number" ? value : ExposurePresets[value];
+function exposureScale(ev) {
+  return 1 / (1.2 * 2 ** ev);
+}
+function ev100FromCamera(aperture, shutterSpeed, iso) {
+  return Math.log2(aperture * aperture / shutterSpeed * (100 / iso));
+}
+const Exposure = defineComponent(
+  "render/Exposure",
+  {
+    ev100: t.f32({
+      default: ExposurePresets.daylight,
+      presets: ExposurePresets,
+      description: "How bright the scene may be. Match it to the light: EV100 = log2(lux / 2.5)."
+    })
+  },
+  {
+    description: "Camera exposure in EV100. Presets: sunny 15.3, daylight 12, overcast 8.6, indoor 7.3, twilight 2."
+  }
+);
+const Camera3d = defineComponent(
+  "render/Camera3d",
+  {
+    projection: t.enum(["perspective", "orthographic"]),
+    fovY: t.f32({
+      default: 60,
+      min: 1,
+      max: 179,
+      unit: "deg",
+      description: "Vertical field of view."
+    }),
+    near: t.f32({
+      default: 0.1,
+      min: 1e-4,
+      unit: "m",
+      description: "Near plane. Far is infinite."
+    }),
+    orthoHeight: t.f32({
+      default: 10,
+      min: 1e-4,
+      unit: "m",
+      description: "View height for orthographic."
+    }),
+    far: t.f32({
+      default: 1e3,
+      min: 1e-3,
+      unit: "m",
+      description: "Far plane, orthographic only."
+    }),
+    order: t.i32({ description: "Lower renders first." }),
+    clearColor: t.color({
+      default: [56e-4, 65e-4, 91e-4, 1],
+      description: "Background (linear)."
+    }),
+    target: t.handle("RenderTarget", { description: "Offscreen target, or null for the window." }),
+    active: t.bool({
+      default: true,
+      description: "Renders when true. An inactive camera keeps its settings and transform but draws nothing."
+    })
+  },
+  {
+    description: "Renders the scene from this entity, looking down its -Z axis.",
+    requires: [Transform, Exposure]
+  }
+);
+const PhysicalCamera = defineComponent(
+  "render/PhysicalCamera",
+  {
+    aperture: t.f32({ default: 4, min: 0.5, description: "f-stop." }),
+    shutterSpeed: t.f32({
+      default: 1 / 125,
+      min: 1e-5,
+      unit: "s",
+      description: "Exposure time."
+    }),
+    iso: t.f32({ default: 100, min: 1, description: "Sensor sensitivity." }),
+    sensorHeight: t.f32({
+      default: 24,
+      min: 1,
+      unit: "mm",
+      description: "Sensor height (35mm film: 24)."
+    }),
+    focalLength: t.f32({
+      min: 0,
+      unit: "mm",
+      description: "Lens focal length. When > 0, sets Camera3d.fovY from the sensor height."
+    })
+  },
+  {
+    description: "Photographic camera settings. When present, they set Exposure (and fovY).",
+    requires: [Camera3d]
+  }
+);
+function camera2d(options = {}) {
+  return [
+    [
+      Camera3d,
+      {
+        projection: "orthographic",
+        orthoHeight: options.height ?? 10,
+        order: options.order ?? 0,
+        ...options.clearColor ? { clearColor: options.clearColor } : {}
+      }
+    ],
+    [Transform, { translation: [0, 0, 100] }]
+  ];
+}
+const applyPhysicalCameras = defineSystem({
+  name: "render/physical-camera",
+  description: "Sets Exposure and fovY from PhysicalCamera settings.",
+  setup: (world) => ({ q: world.query({ with: [PhysicalCamera, Camera3d, Exposure] }) }),
+  run: ({ q }) => {
+    for (const table of q.tables) {
+      const aperture = table.column(PhysicalCamera, "aperture");
+      const shutter = table.column(PhysicalCamera, "shutterSpeed");
+      const iso = table.column(PhysicalCamera, "iso");
+      const sensor = table.column(PhysicalCamera, "sensorHeight");
+      const focal = table.column(PhysicalCamera, "focalLength");
+      const ev = table.column(Exposure, "ev100");
+      const fov = table.column(Camera3d, "fovY");
+      for (let i = 0; i < table.count; i++) {
+        ev[i] = ev100FromCamera(aperture[i], shutter[i], iso[i]);
+        if (focal[i] > 0) fov[i] = 2 * Math.atan(sensor[i] / (2 * focal[i])) * 180 / Math.PI;
+      }
+      table.markChanged(Exposure);
+    }
+  }
+});
+export {
+  Camera3d,
+  Exposure,
+  ExposurePresets,
+  LightPresets,
+  PhysicalCamera,
+  applyPhysicalCameras,
+  camera2d,
+  ev100,
+  ev100FromCamera,
+  ev100FromIlluminance,
+  exposureScale,
+  lux
+};

package/dist/clusters.d.ts

@@ -0,0 +1,68 @@
+import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
+import type { LightRecord } from './lights.js';
+import type { CameraData } from './view.js';
+/** Cluster grid: 16×9 screen tiles × 24 exponential depth slices. */
+export declare const CLUSTER_X = 16;
+export declare const CLUSTER_Y = 9;
+export declare const CLUSTER_Z = 24;
+export declare const CLUSTER_COUNT: number;
+export declare const MAX_LIGHTS_PER_CLUSTER = 128;
+/** Floats per entry in a view's light list: view-space position + range, axis + cos(outer). */
+export declare const VIEW_LIGHT_FLOATS = 12;
+/** Cluster slice range for a camera: near to `clusterFar` (default: far plane, or 1 km). */
+export declare function clusterRange(cam: CameraData, clusterFar: number): [number, number];
+/**
+ * A view's clustering inputs: the visible lights in view space. Built on the CPU each frame from the
+ * light store (frustum-tested), read by the GPU cluster pass and by `clusterLightsCpu`.
+ */
+export declare class ViewLightList {
+    count: number;
+    data: Float32Array<ArrayBuffer>;
+    u32: Uint32Array<ArrayBuffer>;
+    /** The records of the visible lights, in list order. */
+    readonly records: LightRecord[];
+    /** Fills the list with lights whose influence sphere intersects the camera frustum. */
+    build(cam: CameraData, lights: readonly (LightRecord | undefined)[], high: number): void;
+}
+/**
+ * The view-space AABB of cluster (x, y, z), written as [minX, minY, minZ, maxX, maxY, maxZ].
+ * Mirrors `cluster_aabb` in `shard::lighting::cluster` operation for operation, in f32.
+ */
+export declare function clusterAabb(out: Float32Array, x: number, y: number, z: number, near: number, far: number, proj: ArrayLike<number>, orthographic: boolean): Float32Array;
+/** Whether a view-space light (sphere, or cone for spots) touches a cluster AABB. Mirrors WGSL. */
+export declare function lightTouchesCluster(box: Float32Array, light: Float32Array, o: number): boolean;
+/** Every cluster's view-space AABB, 8 floats each (min.xyz, 0, max.xyz, 0), for a camera. */
+export declare function clusterAabbs(out: Float32Array, cam: CameraData, clusterFar: number): Float32Array;
+/** A key for what the cluster AABBs depend on. */
+export declare function clusterKey(cam: CameraData, clusterFar: number): string;
+/** CPU clustering with the same results as the GPU pass: per cluster, the light slots. */
+export declare function clusterLightsCpu(list: ViewLightList, cam: CameraData, clusterFar: number): {
+    counts: Uint32Array;
+    indices: Uint32Array;
+    maxCount: number;
+    overflows: number;
+};
+/** Cluster statistics from the GPU, one or two frames late. */
+export interface ClusterStats {
+    maxLightsPerCluster: number;
+    overflows: number;
+}
+/** A view's GPU cluster buffers: light list in, counts + indices out, stats read back. */
+export declare class ClusterBuffers {
+    readonly lightList: GpuBuffer;
+    /** counts[CLUSTER_COUNT], then indices[CLUSTER_COUNT × MAX_LIGHTS_PER_CLUSTER]. */
+    readonly clusters: GpuBuffer;
+    readonly stats: GpuBuffer;
+    readonly aabbs: GpuBuffer;
+    private aabbKey;
+    private aabbGeneration;
+    private readonly aabbData;
+    readonly stats0: Uint32Array<ArrayBuffer>;
+    latest: ClusterStats;
+    private readonly readbacks;
+    private readonly gpu;
+    constructor(gpu: GpuContext, label: string);
+    upload(list: ViewLightList, cam: CameraData, clusterFar: number): void;
+    /** Copies stats to a readback buffer; resolves into `latest` when mapped. */
+    readback(encoder: GPUCommandEncoder): (() => void) | undefined;
+}

package/dist/clusters.js

@@ -0,0 +1,288 @@
+import { GpuBuffer } from "@aethervtt/shard-gpu";
+const CLUSTER_X = 16;
+const CLUSTER_Y = 9;
+const CLUSTER_Z = 24;
+const CLUSTER_COUNT = CLUSTER_X * CLUSTER_Y * CLUSTER_Z;
+const MAX_LIGHTS_PER_CLUSTER = 128;
+const VIEW_LIGHT_FLOATS = 12;
+function clusterRange(cam, clusterFar) {
+  const near = Math.max(cam.near, 1e-4);
+  const far = clusterFar > 0 ? clusterFar : cam.orthographic && cam.far > 0 ? cam.far : 1e3;
+  return [near, Math.max(far, near * 1.01)];
+}
+class ViewLightList {
+  count = 0;
+  data = new Float32Array(4 + 64 * VIEW_LIGHT_FLOATS);
+  u32 = new Uint32Array(this.data.buffer);
+  /** The records of the visible lights, in list order. */
+  records = [];
+  /** Fills the list with lights whose influence sphere intersects the camera frustum. */
+  build(cam, lights, high) {
+    const f = cam.frustum;
+    const v = cam.view;
+    this.records.length = 0;
+    let n = 0;
+    for (let s = 0; s < high; s++) {
+      const r = lights[s];
+      if (!r?.alive || r.range <= 0) continue;
+      let inside = true;
+      for (let p = 0; p < 24; p += 4) {
+        if (f[p] * r.x + f[p + 1] * r.y + f[p + 2] * r.z + f[p + 3] < -r.range) {
+          inside = false;
+          break;
+        }
+      }
+      if (!inside) continue;
+      const o = 4 + n * VIEW_LIGHT_FLOATS;
+      if (o + VIEW_LIGHT_FLOATS > this.data.length) {
+        const grown = new Float32Array(this.data.length * 2);
+        grown.set(this.data);
+        this.data = grown;
+        this.u32 = new Uint32Array(grown.buffer);
+      }
+      const d = this.data;
+      d[o] = v[0] * r.x + v[4] * r.y + v[8] * r.z + v[12];
+      d[o + 1] = v[1] * r.x + v[5] * r.y + v[9] * r.z + v[13];
+      d[o + 2] = v[2] * r.x + v[6] * r.y + v[10] * r.z + v[14];
+      d[o + 3] = r.range;
+      d[o + 4] = v[0] * r.dx + v[4] * r.dy + v[8] * r.dz;
+      d[o + 5] = v[1] * r.dx + v[5] * r.dy + v[9] * r.dz;
+      d[o + 6] = v[2] * r.dx + v[6] * r.dy + v[10] * r.dz;
+      d[o + 7] = r.cosOuter;
+      this.u32[o + 8] = r.slot;
+      this.u32[o + 9] = 0;
+      this.u32[o + 10] = 0;
+      this.u32[o + 11] = 0;
+      this.records.push(r);
+      n++;
+    }
+    this.count = n;
+    this.u32[0] = n;
+  }
+}
+const f32 = Math.fround;
+function clusterAabb(out, x, y, z, near, far, proj, orthographic) {
+  const ratio = f32(far / near);
+  const d0 = f32(near * f32(ratio ** f32(z / CLUSTER_Z)));
+  const d1 = f32(near * f32(ratio ** f32((z + 1) / CLUSTER_Z)));
+  const x0 = f32(-1 + f32(f32(2 * x) / CLUSTER_X));
+  const x1 = f32(-1 + f32(f32(2 * (x + 1)) / CLUSTER_X));
+  const y1 = f32(1 - f32(f32(2 * y) / CLUSTER_Y));
+  const y0 = f32(1 - f32(f32(2 * (y + 1)) / CLUSTER_Y));
+  const p00 = proj[0];
+  const p11 = proj[5];
+  let minX;
+  let maxX;
+  let minY;
+  let maxY;
+  if (orthographic) {
+    minX = f32(f32(x0 - proj[12]) / p00);
+    maxX = f32(f32(x1 - proj[12]) / p00);
+    minY = f32(f32(y0 - proj[13]) / p11);
+    maxY = f32(f32(y1 - proj[13]) / p11);
+  } else {
+    const ax = f32(f32(x0 * d0) / p00);
+    const bx = f32(f32(x0 * d1) / p00);
+    const cx = f32(f32(x1 * d0) / p00);
+    const dx = f32(f32(x1 * d1) / p00);
+    minX = Math.min(ax, bx, cx, dx);
+    maxX = Math.max(ax, bx, cx, dx);
+    const ay = f32(f32(y0 * d0) / p11);
+    const by = f32(f32(y0 * d1) / p11);
+    const cy = f32(f32(y1 * d0) / p11);
+    const dy = f32(f32(y1 * d1) / p11);
+    minY = Math.min(ay, by, cy, dy);
+    maxY = Math.max(ay, by, cy, dy);
+  }
+  out[0] = minX;
+  out[1] = minY;
+  out[2] = -d1;
+  out[3] = maxX;
+  out[4] = maxY;
+  out[5] = -d0;
+  return out;
+}
+function lightTouchesCluster(box, light, o) {
+  const px = light[o];
+  const py = light[o + 1];
+  const pz = light[o + 2];
+  const range = light[o + 3];
+  const cx = Math.min(Math.max(px, box[0]), box[3]);
+  const cy = Math.min(Math.max(py, box[1]), box[4]);
+  const cz = Math.min(Math.max(pz, box[2]), box[5]);
+  const ex = f32(cx - px);
+  const ey = f32(cy - py);
+  const ez = f32(cz - pz);
+  if (f32(f32(f32(ex * ex) + f32(ey * ey)) + f32(ez * ez)) > f32(range * range)) return false;
+  const cosOuter = light[o + 7];
+  if (cosOuter < -1) return true;
+  const sx = f32(f32(f32(box[0] + box[3]) * 0.5) - px);
+  const sy = f32(f32(f32(box[1] + box[4]) * 0.5) - py);
+  const sz = f32(f32(f32(box[2] + box[5]) * 0.5) - pz);
+  const hx = f32(f32(box[3] - box[0]) * 0.5);
+  const hy = f32(f32(box[4] - box[1]) * 0.5);
+  const hz = f32(f32(box[5] - box[2]) * 0.5);
+  const radius = f32(Math.sqrt(f32(f32(f32(hx * hx) + f32(hy * hy)) + f32(hz * hz))));
+  const lenSq = f32(f32(f32(sx * sx) + f32(sy * sy)) + f32(sz * sz));
+  const v1 = f32(f32(f32(sx * light[o + 4]) + f32(sy * light[o + 5])) + f32(sz * light[o + 6]));
+  const sinOuter = f32(Math.sqrt(Math.max(0, f32(1 - f32(cosOuter * cosOuter)))));
+  const closest = f32(
+    f32(cosOuter * f32(Math.sqrt(Math.max(0, f32(lenSq - f32(v1 * v1)))))) - f32(v1 * sinOuter)
+  );
+  if (closest > radius) return false;
+  if (v1 > f32(radius + range)) return false;
+  if (v1 < -radius) return false;
+  return true;
+}
+function clusterAabbs(out, cam, clusterFar) {
+  const [near, far] = clusterRange(cam, clusterFar);
+  const box = new Float32Array(6);
+  for (let c = 0; c < CLUSTER_COUNT; c++) {
+    const x = c % CLUSTER_X;
+    const y = Math.floor(c / CLUSTER_X) % CLUSTER_Y;
+    const z = Math.floor(c / (CLUSTER_X * CLUSTER_Y));
+    clusterAabb(box, x, y, z, near, far, cam.proj, cam.orthographic);
+    out[c * 8] = box[0];
+    out[c * 8 + 1] = box[1];
+    out[c * 8 + 2] = box[2];
+    out[c * 8 + 4] = box[3];
+    out[c * 8 + 5] = box[4];
+    out[c * 8 + 6] = box[5];
+  }
+  return out;
+}
+function clusterKey(cam, clusterFar) {
+  const [near, far] = clusterRange(cam, clusterFar);
+  const p = cam.proj;
+  return `${near}|${far}|${p[0]}|${p[5]}|${p[12]}|${p[13]}|${cam.orthographic}`;
+}
+function clusterLightsCpu(list, cam, clusterFar) {
+  const aabbs = clusterAabbs(new Float32Array(CLUSTER_COUNT * 8), cam, clusterFar);
+  const counts = new Uint32Array(CLUSTER_COUNT);
+  const indices = new Uint32Array(CLUSTER_COUNT * MAX_LIGHTS_PER_CLUSTER);
+  const box = new Float32Array(6);
+  const light = new Float32Array(list.data.buffer);
+  const u32 = list.u32;
+  let maxCount = 0;
+  let overflows = 0;
+  for (let c = 0; c < CLUSTER_COUNT; c++) {
+    box[0] = aabbs[c * 8];
+    box[1] = aabbs[c * 8 + 1];
+    box[2] = aabbs[c * 8 + 2];
+    box[3] = aabbs[c * 8 + 4];
+    box[4] = aabbs[c * 8 + 5];
+    box[5] = aabbs[c * 8 + 6];
+    let n = 0;
+    for (let i = 0; i < list.count; i++) {
+      const o = 4 + i * VIEW_LIGHT_FLOATS;
+      if (!lightTouchesCluster(box, light, o)) continue;
+      if (n < MAX_LIGHTS_PER_CLUSTER) indices[c * MAX_LIGHTS_PER_CLUSTER + n] = u32[o + 8];
+      n++;
+    }
+    counts[c] = Math.min(n, MAX_LIGHTS_PER_CLUSTER);
+    if (n > maxCount) maxCount = n;
+    if (n > MAX_LIGHTS_PER_CLUSTER) overflows++;
+  }
+  return { counts, indices, maxCount, overflows };
+}
+class ClusterBuffers {
+  lightList;
+  /** counts[CLUSTER_COUNT], then indices[CLUSTER_COUNT × MAX_LIGHTS_PER_CLUSTER]. */
+  clusters;
+  stats;
+  aabbs;
+  aabbKey = "";
+  aabbGeneration = -1;
+  aabbData = new Float32Array(CLUSTER_COUNT * 8);
+  stats0 = new Uint32Array(4);
+  latest = { maxLightsPerCluster: 0, overflows: 0 };
+  readbacks = [];
+  gpu;
+  constructor(gpu, label) {
+    this.gpu = gpu;
+    this.lightList = new GpuBuffer(gpu, {
+      label: `${label}/light-list`,
+      usage: GPUBufferUsage.STORAGE,
+      size: (4 + 64 * VIEW_LIGHT_FLOATS) * 4
+    });
+    this.clusters = new GpuBuffer(gpu, {
+      label: `${label}/clusters`,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+      size: CLUSTER_COUNT * (1 + MAX_LIGHTS_PER_CLUSTER) * 4
+    });
+    this.aabbs = new GpuBuffer(gpu, {
+      label: `${label}/cluster-aabbs`,
+      usage: GPUBufferUsage.STORAGE,
+      size: CLUSTER_COUNT * 8 * 4
+    });
+    this.stats = new GpuBuffer(gpu, {
+      label: `${label}/cluster-stats`,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+      size: 16
+    });
+  }
+  upload(list, cam, clusterFar) {
+    const key = clusterKey(cam, clusterFar);
+    if (key !== this.aabbKey || this.aabbGeneration !== this.gpu.generation) {
+      this.aabbKey = key;
+      this.aabbGeneration = this.gpu.generation;
+      this.aabbs.write(clusterAabbs(this.aabbData, cam, clusterFar));
+    }
+    this.lightList.write(list.data, 0, 0, 4 + Math.max(1, list.count) * VIEW_LIGHT_FLOATS);
+    this.stats.write(this.stats0);
+  }
+  /** Copies stats to a readback buffer; resolves into `latest` when mapped. */
+  readback(encoder) {
+    const gen = this.gpu.generation;
+    let rb = this.readbacks.find((r) => !r.busy && r.generation === gen);
+    if (!rb && this.readbacks.length < 3) {
+      rb = {
+        buffer: this.gpu.device.createBuffer({
+          label: "cluster-stats/readback",
+          size: 16,
+          usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+        }),
+        busy: false,
+        generation: gen
+      };
+      this.readbacks.push(rb);
+    }
+    if (!rb) {
+      for (let i = this.readbacks.length - 1; i >= 0; i--)
+        if (this.readbacks[i].generation !== gen) this.readbacks.splice(i, 1);
+      return void 0;
+    }
+    encoder.copyBufferToBuffer(this.stats.buffer, 0, rb.buffer, 0, 16);
+    rb.busy = true;
+    const target = rb;
+    return () => {
+      target.buffer.mapAsync(GPUMapMode.READ).then(
+        () => {
+          const v = new Uint32Array(target.buffer.getMappedRange().slice(0));
+          target.buffer.unmap();
+          target.busy = false;
+          this.latest = { maxLightsPerCluster: v[0], overflows: v[1] };
+        },
+        () => {
+          target.busy = false;
+        }
+      );
+    };
+  }
+}
+export {
+  CLUSTER_COUNT,
+  CLUSTER_X,
+  CLUSTER_Y,
+  CLUSTER_Z,
+  ClusterBuffers,
+  MAX_LIGHTS_PER_CLUSTER,
+  VIEW_LIGHT_FLOATS,
+  ViewLightList,
+  clusterAabb,
+  clusterAabbs,
+  clusterKey,
+  clusterLightsCpu,
+  clusterRange,
+  lightTouchesCluster
+};

package/dist/culling-shaders.d.ts

@@ -0,0 +1,2 @@
+/** WGSL for GPU culling (see culling.ts; the CPU path in instances.ts mirrors every test). */
+export declare const CULLING_SHADERS: Record<string, string>;