@tinypoly/gpu-renderer 0.0.4 → 0.1.0

package/src/lensPass.ts

@@ -0,0 +1,299 @@
+import { createShaderModule } from "./shaderModule.js";
+import { NEUTRAL_WHITE_BALANCE, whiteBalanceMatrix, type GpuRenderSettings } from "./settings.js";
+import { LENS_WGSL } from "./wgsl/lens.wgsl.js";
+
+const UNIFORM_BYTES = 144;
+
+const WORKGROUP = 8;
+
+/** Halving stops once a level would be smaller than this on its short side, or after this many levels. */
+const SMALLEST_LEVEL = 4;
+const MAX_LEVELS = 8;
+
+/** Where chromatic aberration `1` moves red and blue apart, as a share of the distance from the centre. */
+const ABERRATION_SCALE = 0.005;
+
+/** What the lens pass is told about the lens: the settings that reach it, resolved. */
+export interface LensEffects {
+  /** Share of the light the halo takes; zero leaves the pyramid unbuilt. */
+  bloom: number;
+  radius: number;
+  aberration: number;
+  /** Share of the light the aperture's rays take; zero gathers none. */
+  glare: number;
+  /** How many rays, how far they reach as a share of the half diagonal, and the first one's angle in radians. */
+  rays: number;
+  glareLength: number;
+  glareAngle: number;
+  /** A linear sRGB matrix, row by row, or `null` for a neutral white balance. */
+  whiteBalance: number[] | null;
+}
+
+/** The lens effects these settings ask for, or `null` when they ask for none and the pass can be skipped. */
+export function lensEffects(settings: GpuRenderSettings): LensEffects | null {
+  const { bloom, glare, lens, camera } = settings;
+  const intensity = bloom.enabled ? Math.min(1, Math.max(0, bloom.intensity)) : 0;
+  const streaks = glare.enabled ? Math.min(1, Math.max(0, glare.intensity)) : 0;
+  const aberration = Math.max(0, lens.chromaticAberration) * ABERRATION_SCALE;
+  const neutral = !Number.isFinite(camera.whiteBalance) || camera.whiteBalance === NEUTRAL_WHITE_BALANCE;
+  const blades = Math.min(16, Math.max(3, Math.round(Number(glare.blades) || 6)));
+
+  if (intensity <= 0 && streaks <= 0 && aberration <= 0 && neutral) return null;
+
+  return {
+    bloom: intensity,
+    radius: Math.min(0.95, Math.max(0, bloom.radius)),
+    aberration,
+    glare: streaks,
+    // Each blade's edge diffracts into a ray each way: an even count's opposite edges share their rays.
+    rays: blades % 2 === 0 ? blades : blades * 2,
+    glareLength: Math.min(1, Math.max(0, Number(glare.length) || 0)),
+    glareAngle: (Number(glare.rotation) || 0) * Math.PI / 180,
+    whiteBalance: neutral ? null : whiteBalanceMatrix(camera.whiteBalance),
+  };
+}
+
+interface Level {
+  width: number;
+  height: number;
+  /** In texels, in both pyramids. */
+  offset: number;
+}
+
+/** Halved levels of the image, the largest first, until one would be too small to be worth filtering. */
+export function pyramidLevels(width: number, height: number): Level[] {
+  const levels: Level[] = [];
+  let w = width, h = height, offset = 0;
+
+  while (levels.length < MAX_LEVELS) {
+    w = Math.max(1, Math.ceil(w / 2));
+    h = Math.max(1, Math.ceil(h / 2));
+
+    if (levels.length > 0 && Math.min(w, h) < SMALLEST_LEVEL) break;
+
+    levels.push({ width: w, height: h, offset });
+    offset += w * h;
+  }
+
+  return levels;
+}
+
+/** The level the aperture's rays are gathered at: a quarter of the image, where there is one. */
+function streakLevel(levels: Level[]): Level {
+  return levels[Math.min(1, levels.length - 1)];
+}
+
+/**
+ * The lens and the sensor, between the radiance and its display transform: bloom, chromatic aberration and white
+ * balance, into a buffer of linear colour the presentation and the image resolve read in place of the radiance.
+ */
+export class LensPass {
+  private readonly layout: GPUBindGroupLayout;
+  private readonly downsample: GPUComputePipeline;
+  private readonly upsample: GPUComputePipeline;
+  private readonly composite: GPUComputePipeline;
+  private readonly streaks: GPUComputePipeline;
+  /** One uniform buffer per dispatch, so every one of them keeps its own values until the queue runs it. */
+  private readonly uniforms: GPUBuffer[] = [];
+  private readonly values = new ArrayBuffer(UNIFORM_BYTES);
+  private down: GPUBuffer | null = null;
+  private up: GPUBuffer | null = null;
+  private graded: GPUBuffer | null = null;
+  private streaked: GPUBuffer | null = null;
+  private size = "";
+
+  constructor(private readonly device: GPUDevice) {
+    const module = createShaderModule(device, "lens", LENS_WGSL);
+    const storage = (type: GPUBufferBindingType): GPUBindGroupLayoutEntry["buffer"] => ({ type });
+
+    this.layout = device.createBindGroupLayout({
+      label: "lens",
+      entries: [
+        { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+        { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: storage("read-only-storage") },
+        { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: storage("read-only-storage") },
+        { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: storage("storage") },
+        { binding: 4, visibility: GPUShaderStage.COMPUTE, buffer: storage("storage") },
+        { binding: 5, visibility: GPUShaderStage.COMPUTE, buffer: storage("storage") },
+        { binding: 6, visibility: GPUShaderStage.COMPUTE, buffer: storage("storage") },
+      ],
+    });
+
+    const layout = device.createPipelineLayout({ bindGroupLayouts: [this.layout] });
+    const pipeline = (entryPoint: string) => device.createComputePipeline({ layout, compute: { module, entryPoint } });
+
+    this.downsample = pipeline("downsample");
+    this.upsample = pipeline("upsample");
+    this.composite = pipeline("composite");
+    this.streaks = pipeline("streaks");
+  }
+
+  /** The graded image of the last `encode`, one vec4 of linear colour per pixel. */
+  get output(): GPUBuffer | null {
+    return this.graded;
+  }
+
+  private ensure(width: number, height: number, levels: Level[]) {
+    const key = `${width}x${height}`;
+
+    if (key === this.size && this.graded) return;
+
+    this.destroyBuffers();
+    this.size = key;
+
+    const last = levels[levels.length - 1];
+    const texels = Math.max(1, last.offset + last.width * last.height);
+    // A pyramid of one level is copied into the halo as it is, which the two need copy usage for.
+    const usage = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST;
+
+    this.down = this.device.createBuffer({ label: "lens pyramid", size: texels * 16, usage });
+    this.up = this.device.createBuffer({ label: "lens halo", size: texels * 16, usage });
+    this.graded = this.device.createBuffer({ label: "lens output", size: width * height * 16,
+      usage: GPUBufferUsage.STORAGE });
+
+    const streak = streakLevel(levels);
+
+    this.streaked = this.device.createBuffer({ label: "lens rays", size: streak.width * streak.height * 16,
+      usage: GPUBufferUsage.STORAGE });
+  }
+
+  private uniform(index: number): GPUBuffer {
+    while (this.uniforms.length <= index) {
+      this.uniforms.push(this.device.createBuffer({
+        size: UNIFORM_BYTES, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+      }));
+    }
+
+    return this.uniforms[index];
+  }
+
+  /**
+   * Encodes the whole pass over the accumulation (or the denoiser's output, when given) and returns the buffer it
+   * writes, which holds the result once the encoder has run.
+   */
+  encode(encoder: GPUCommandEncoder, accumulation: GPUBuffer, denoised: GPUBuffer | null, width: number,
+    height: number, effects: LensEffects): GPUBuffer {
+    const levels = pyramidLevels(width, height);
+
+    this.ensure(width, height, levels);
+
+    const floats = new Float32Array(this.values), integers = new Uint32Array(this.values);
+    const white = effects.whiteBalance ?? [1, 0, 0, 0, 1, 0, 0, 0, 1];
+    const halo = levels[0];
+    const streak = streakLevel(levels);
+    let used = 0;
+
+    const dispatch = (pipeline: GPUComputePipeline, target: { width: number; height: number },
+      fill: () => void) => {
+      integers.fill(0);
+      integers[0] = width;
+      integers[1] = height;
+      integers[2] = denoised ? 1 : 0;
+      integers[11] = halo.offset;
+      integers[12] = halo.width;
+      integers[13] = halo.height;
+      floats[14] = effects.bloom;
+      floats[15] = effects.radius;
+      floats[16] = effects.aberration;
+      floats[17] = effects.glare;
+      integers[18] = effects.rays;
+      floats[19] = effects.glareLength * Math.hypot(streak.width, streak.height) / 2;
+      integers[32] = streak.width;
+      integers[33] = streak.height;
+      floats[34] = effects.glareAngle;
+      for (let row = 0; row < 3; row++) for (let column = 0; column < 3; column++)
+        floats[20 + row * 4 + column] = white[row * 3 + column];
+      fill();
+
+      const buffer = this.uniform(used++);
+
+      this.device.queue.writeBuffer(buffer, 0, this.values);
+
+      const pass = encoder.beginComputePass({ label: "lens" });
+
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, this.device.createBindGroup({
+        layout: this.layout,
+        entries: [
+          { binding: 0, resource: { buffer } },
+          { binding: 1, resource: { buffer: accumulation } },
+          { binding: 2, resource: { buffer: denoised ?? accumulation } },
+          { binding: 3, resource: { buffer: this.down as GPUBuffer } },
+          { binding: 4, resource: { buffer: this.up as GPUBuffer } },
+          { binding: 5, resource: { buffer: this.graded as GPUBuffer } },
+          { binding: 6, resource: { buffer: this.streaked as GPUBuffer } },
+        ],
+      }));
+      pass.dispatchWorkgroups(Math.ceil(target.width / WORKGROUP), Math.ceil(target.height / WORKGROUP));
+      pass.end();
+    };
+
+    const read = (level: { width: number; height: number; offset: number }) => {
+      integers[4] = level.width;
+      integers[5] = level.height;
+      integers[6] = level.offset;
+    };
+
+    const write = (level: Level) => {
+      integers[8] = level.width;
+      integers[9] = level.height;
+      integers[10] = level.offset;
+    };
+
+    // The rays are gathered from a level of the same pyramid, so either effect builds it.
+    if (effects.bloom > 0 || effects.glare > 0) {
+      levels.forEach((level, k) => dispatch(this.downsample, level, () => {
+        if (k === 0) {
+          read({ width, height, offset: 0 });
+          integers[7] = 1;
+        } else {
+          read(levels[k - 1]);
+        }
+
+        write(level);
+      }));
+    }
+
+    if (effects.glare > 0) {
+      dispatch(this.streaks, streak, () => {
+        read(streak);
+        write({ ...streak, offset: 0 });
+      });
+    }
+
+    if (effects.bloom > 0) {
+      // The smallest level folds into nothing wider; each one above takes the spread of everything below it.
+      for (let k = levels.length - 2; k >= 0; k--) {
+        dispatch(this.upsample, levels[k], () => {
+          read(levels[k + 1]);
+          integers[3] = k === levels.length - 2 ? 1 : 0;
+          write(levels[k]);
+        });
+      }
+
+      // A single level has nothing to fold: the halo is that level as it was filtered.
+      if (levels.length === 1) {
+        encoder.copyBufferToBuffer(this.down as GPUBuffer, 0, this.up as GPUBuffer, 0,
+          levels[0].width * levels[0].height * 16);
+      }
+    }
+
+    dispatch(this.composite, { width, height }, () => {});
+
+    return this.graded as GPUBuffer;
+  }
+
+  private destroyBuffers() {
+    this.down?.destroy();
+    this.up?.destroy();
+    this.graded?.destroy();
+    this.streaked?.destroy();
+    this.down = this.up = this.graded = this.streaked = null;
+  }
+
+  destroy() {
+    this.destroyBuffers();
+    for (const buffer of this.uniforms) buffer.destroy();
+    this.uniforms.length = 0;
+  }
+}

package/src/lightTree.ts

@@ -0,0 +1,172 @@
+/**
+ * A bounding hierarchy over the lights that sit in the scene (emissive triangles, point, spot and rectangular lights),
+ * which lets the integrator pick one by how much it can deliver to the point being shaded rather than by its power
+ * alone: Conty Estevez and Kulla, "Importance Sampling of Many Lights with Adaptive Tree Splitting" (2018), without the
+ * splitting, as Cycles uses it. Every node keeps its box, the power under it and a cone bounding the directions its
+ * lights face; the kernel walks down choosing a child by each one's importance from the shaded point, and walks the same
+ * path up to tell how likely a light a bounce ray hit was to be chosen that way.
+ */
+
+/** A light as the tree sees it: where it is, how strong, which way it faces, and the area density of its points. */
+export interface TreeLight {
+  low: number[];
+  high: number[];
+  /** Radiant intensity scale: what a unit distance away receives, so lights of every kind compare. */
+  power: number;
+  /** The axis its emission is centred on, the half angle of the normals around it, and how far past them it emits. */
+  axis: number[];
+  thetaO: number;
+  thetaE: number;
+  /** Area density of a point on it, one for a point light. */
+  density: number;
+}
+
+/** Sixteen words a node: low and power, high and cos theta_o, axis and cos theta_e, then the links. */
+export const TREE_NODE_WORDS = 16;
+
+/** The high bit of a node's first link marks a leaf, whose low bits are its light's index. */
+export const TREE_LEAF = 0x80000000;
+
+export const TREE_ROOT_PARENT = 0xffffffff;
+
+interface Cone {
+  axis: number[];
+  thetaO: number;
+  thetaE: number;
+}
+
+const dot = (a: number[], b: number[]) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+
+function normalized(v: number[]): number[] {
+  const length = Math.hypot(v[0], v[1], v[2]);
+
+  return length > 0 ? v.map(c => c / length) : [0, 0, 1];
+}
+
+/** Rotates a towards b by an angle, in the plane they span. */
+function rotateTowards(a: number[], b: number[], angle: number): number[] {
+  const along = dot(a, b);
+  const ortho = normalized(b.map((c, k) => c - a[k] * along));
+
+  return normalized(a.map((c, k) => c * Math.cos(angle) + ortho[k] * Math.sin(angle)));
+}
+
+/** The smallest cone bounding two, as Conty and Kulla merge them. */
+export function unionCone(first: Cone, second: Cone): Cone {
+  const [a, b] = first.thetaO >= second.thetaO ? [first, second] : [second, first];
+  const thetaE = Math.max(a.thetaE, b.thetaE);
+  const thetaD = Math.acos(Math.min(1, Math.max(-1, dot(a.axis, b.axis))));
+
+  if (Math.min(thetaD + b.thetaO, Math.PI) <= a.thetaO) return { axis: a.axis, thetaO: a.thetaO, thetaE };
+
+  const thetaO = (a.thetaO + thetaD + b.thetaO) / 2;
+
+  if (thetaO >= Math.PI) return { axis: a.axis, thetaO: Math.PI, thetaE };
+
+  // Two opposite axes have no plane between them: the cone then takes the whole sphere.
+  if (thetaD >= Math.PI - 1e-6) return { axis: a.axis, thetaO: Math.PI, thetaE };
+
+  return { axis: rotateTowards(a.axis, b.axis, thetaO - a.thetaO), thetaO, thetaE };
+}
+
+interface Node {
+  low: number[];
+  high: number[];
+  power: number;
+  cone: Cone;
+  left: number;
+  right: number;
+  parent: number;
+  /** The light of a leaf, or -1. */
+  light: number;
+  density: number;
+}
+
+/**
+ * The tree over these lights, as words for the texture buffer, and the leaf each light ended in. Split at the median
+ * of the longest axis of the centres, which needs no cost model and keeps the depth near log2 of the count.
+ */
+export function buildLightTree(lights: readonly TreeLight[]): { words: Uint32Array; leafOf: Uint32Array } {
+  const nodes: Node[] = [];
+  const leafOf = new Uint32Array(lights.length);
+
+  const build = (indices: number[], parent: number): number => {
+    const index = nodes.length;
+    const low = [Infinity, Infinity, Infinity], high = [-Infinity, -Infinity, -Infinity];
+    let power = 0;
+    let cone: Cone | null = null;
+
+    for (const i of indices) {
+      const light = lights[i];
+
+      for (let k = 0; k < 3; k++) {
+        low[k] = Math.min(low[k], light.low[k]);
+        high[k] = Math.max(high[k], light.high[k]);
+      }
+
+      power += light.power;
+
+      const own = { axis: normalized(light.axis), thetaO: light.thetaO, thetaE: light.thetaE };
+
+      cone = cone ? unionCone(cone, own) : own;
+    }
+
+    const node: Node = { low, high, power, cone: cone as Cone, left: -1, right: -1, parent, light: -1, density: 1 };
+
+    nodes.push(node);
+
+    if (indices.length === 1) {
+      node.light = indices[0];
+      node.density = lights[indices[0]].density;
+      leafOf[indices[0]] = index;
+
+      return index;
+    }
+
+    const centre = (i: number, k: number) => (lights[i].low[k] + lights[i].high[k]) / 2;
+
+    const extent = [0, 1, 2].map(k => {
+      const values = indices.map(i => centre(i, k));
+
+      return Math.max(...values) - Math.min(...values);
+    });
+
+    const axis = extent.indexOf(Math.max(...extent));
+    const sorted = [...indices].sort((a, b) => centre(a, axis) - centre(b, axis));
+    const half = sorted.length >> 1;
+
+    node.left = build(sorted.slice(0, half), index);
+    node.right = build(sorted.slice(half), index);
+
+    return index;
+  };
+
+  if (lights.length) build(lights.map((_, i) => i), TREE_ROOT_PARENT);
+
+  const words = new Uint32Array(nodes.length * TREE_NODE_WORDS);
+  const floats = new Float32Array(words.buffer);
+
+  nodes.forEach((node, k) => {
+    const at = k * TREE_NODE_WORDS;
+
+    floats.set(node.low, at);
+    floats[at + 3] = node.power;
+    floats.set(node.high, at + 4);
+    // A cone that takes the whole sphere is stored as minus one, which the kernel reads as no orientation at all.
+    floats[at + 7] = node.cone.thetaO >= Math.PI ? -1 : Math.cos(node.cone.thetaO);
+    floats.set(node.cone.axis, at + 8);
+    floats[at + 11] = Math.cos(Math.min(node.cone.thetaE, Math.PI));
+
+    if (node.light >= 0) {
+      words[at + 12] = (TREE_LEAF | node.light) >>> 0;
+      floats[at + 13] = node.density;
+    } else {
+      words[at + 12] = node.left;
+      words[at + 13] = node.right;
+    }
+
+    words[at + 14] = node.parent >>> 0;
+  });
+
+  return { words, leafOf };
+}

package/src/lights.ts

@@ -1,4 +1,5 @@
 import type { PackedGeometry } from "./geometry.js";
+import { buildLightTree, type TreeLight } from "./lightTree.js";
 import type { SerializedLight } from "./upstream.js";
 
 /**
@@ -50,8 +51,26 @@ export interface PackedLights {
   ambient: { sky: number[]; ground: number[]; axis: number[] };
   /** How often direct sampling picks the environment rather than a light. Zero when there is nothing to aim at. */
   environmentPick: number;
-  /** Words to append to the texture buffer: a spot light's map index and the matrix that projects it. */
+  /**
+   * Words to append to the texture buffer: a spot light's map index and the matrix that projects it, then the
+   * cumulative probability of every entry and the triangle of every emissive one, packed tight so the two searches the
+   * shader makes over them read four bytes a step instead of a whole entry.
+   */
   extraWords: Uint32Array;
+  /** Where the cumulative probabilities start in the texture buffer, one float per entry. */
+  cdfAt: number;
+  /** Where the emissive entries' triangles start in the texture buffer, one word per emissive entry. */
+  trianglesAt: number;
+  /**
+   * How many leading entries sit in the scene (emissive triangles, point, spot and rectangular lights), which the light
+   * tree picks among; the directional lights and the environment follow them.
+   */
+  localCount: number;
+  /** The chance of picking one of those: exactly the cumulative probability of the last of them. */
+  localPick: number;
+  /** Where the light tree's nodes start in the texture buffer, and the leaf of every local entry; zero for no tree. */
+  treeAt: number;
+  leavesAt: number;
 }
 
 const luminance = (color: ArrayLike<number>) => 0.2126 * color[0] + 0.7152 * color[1] + 0.0722 * color[2];
@@ -120,8 +139,15 @@ interface Candidate {
   write(words: Uint32Array, floats: Float32Array, at: number): void;
   /** Area measure density of a point on it, before the pick probability is folded in. */
   density?: number;
+  /** What the light tree knows of a light that sits in the scene; none for a directional light or the environment. */
+  tree?: TreeLight;
 }
 
+const corners = (points: number[][]) => ({
+  low: [0, 1, 2].map(k => Math.min(...points.map(p => p[k]))),
+  high: [0, 1, 2].map(k => Math.max(...points.map(p => p[k]))),
+});
+
 /**
  * Emissive triangles weighted by the power they radiate (area times emitted luminance), so a large or bright panel is
  * chosen more often than a dim sliver.
@@ -145,11 +171,24 @@ function emissiveTriangles(geometry: PackedGeometry, bounds: Bounds): Candidate[
     const centroid = [0, 1, 2].map(axis =>
       (geometry.positions[at + axis] + geometry.positions[at + 3 + axis] + geometry.positions[at + 6 + axis]) / 3);
 
+    const p = geometry.positions;
+    const e1 = [p[at + 3] - p[at], p[at + 4] - p[at + 1], p[at + 5] - p[at + 2]];
+    const e2 = [p[at + 6] - p[at], p[at + 7] - p[at + 1], p[at + 8] - p[at + 2]];
+
     candidates.push({
       kind: LIGHT_KIND.area,
       // The irradiance it delivers, so a bright panel and a bright lamp are weighed in the same unit.
       weight: glow * area / reach(centroid, bounds) ** 2,
       density: 1 / area,
+      // It radiates from both sides, so its cone is the whole sphere.
+      tree: {
+        ...corners([0, 3, 6].map(v => [p[at + v], p[at + v + 1], p[at + v + 2]])),
+        power: glow * area,
+        axis: normalize([e1[1] * e2[2] - e1[2] * e2[1], e1[2] * e2[0] - e1[0] * e2[2], e1[0] * e2[1] - e1[1] * e2[0]]),
+        thetaO: Math.PI,
+        thetaE: Math.PI / 2,
+        density: 1 / area,
+      },
       write(words, _floats, at) {
         words[at] = LIGHT_KIND.area;
         words[at + 3] = triangle;
@@ -212,6 +251,8 @@ function analyticLight(
     return {
       kind: LIGHT_KIND.point,
       weight: emitted * falloff,
+      tree: { low: [...light.position], high: [...light.position], power: emitted, axis: [0, 0, 1], thetaO: Math.PI,
+        thetaE: Math.PI / 2, density: 1 },
       write: (words, floats, at) => common(words, floats, at, LIGHT_KIND.point),
     };
   }
@@ -231,6 +272,9 @@ function analyticLight(
       kind: LIGHT_KIND.spot,
       // Only the cone is lit, so only that share of the scene can expect anything from it.
       weight: emitted * falloff * (1 - Math.cos(Math.min(light.angle, Math.PI))) / 2,
+      // It shines from its position towards its target, within its outer cone.
+      tree: { low: [...light.position], high: [...light.position], power: emitted, axis: scale(axis, -1),
+        thetaO: Math.min(light.angle, Math.PI), thetaE: 0, density: 1 },
       write(words, floats, at) {
         common(words, floats, at, LIGHT_KIND.spot);
         floats[at + 15] = outer;
@@ -251,10 +295,25 @@ function analyticLight(
     const up = normalize([matrix[4], matrix[5], matrix[6]]);
     const area = Math.max(light.width * light.height, 1e-12);
 
+    const half = [scale(right, light.width / 2), scale(up, light.height / 2)];
+
+    const facing = normalize([
+      right[1] * up[2] - right[2] * up[1], right[2] * up[0] - right[0] * up[2], right[0] * up[1] - right[1] * up[0]]);
+
     return {
       kind: LIGHT_KIND.rect,
       weight: emitted * area / distance ** 2,
       density: 1 / area,
+      // One sided: it lights the side its axes' cross product turns away from, over a hemisphere.
+      tree: {
+        ...corners([[-1, -1], [1, -1], [1, 1], [-1, 1]].map(([a, b]) =>
+          [0, 1, 2].map(k => light.position[k] + half[0][k] * a + half[1][k] * b))),
+        power: emitted * area,
+        axis: scale(facing, -1),
+        thetaO: 0,
+        thetaE: Math.PI / 2,
+        density: 1 / area,
+      },
       write(words, floats, at) {
         common(words, floats, at, LIGHT_KIND.rect);
         floats.set(scale(right, light.width / 2), at + 16);
@@ -334,7 +393,11 @@ export function packLights(
     }]
     : [];
 
-  const candidates = [...areas, ...analytic, ...surrounding];
+  // What sits in the scene first, so the tree's lights are the leading entries; then what lies outside it.
+  const local = analytic.filter(candidate => candidate.tree);
+  const distant = analytic.filter(candidate => !candidate.tree);
+  const candidates = [...areas, ...local, ...distant, ...surrounding];
+  const localCount = areas.length + local.length;
   const total = candidates.reduce((sum, candidate) => sum + candidate.weight, 0);
   const entries = new ArrayBuffer(Math.max(1, candidates.length) * LIGHT_WORDS * 4);
   const words = new Uint32Array(entries);
@@ -353,8 +416,33 @@ export function packLights(
   });
 
   const environmentPick = surrounding.length ? surrounding[0].weight / total : 0;
+  const base = options.extraBase ?? 0;
+  const cdfAt = base + extra.length;
+
+  for (let index = 0; index < candidates.length; index++) extra.push(words[index * LIGHT_WORDS + 1]);
+
+  const trianglesAt = base + extra.length;
+
+  for (let index = 0; index < areas.length; index++) extra.push(words[index * LIGHT_WORDS + 3]);
+
+  let treeAt = 0, leavesAt = 0;
+
+  if (localCount > 0) {
+    const tree = buildLightTree(candidates.slice(0, localCount).map(candidate => candidate.tree as TreeLight));
+
+    treeAt = base + extra.length;
+    for (const word of tree.words) extra.push(word);
+    leavesAt = base + extra.length;
+    for (const leaf of tree.leafOf) extra.push(leaf);
+  }
 
   return {
+    localCount,
+    localPick: localCount > 0 ? floats[(localCount - 1) * LIGHT_WORDS + 1] : 0,
+    treeAt,
+    leavesAt,
+    cdfAt,
+    trianglesAt,
     entries,
     count: candidates.length,
     areaCount: areas.length,