@driftengine/core 4.4.2 → 4.6.0

package/src/render/mesh.ts

@@ -58,14 +58,6 @@ const ATTR_JOINTS = 11;
  */
 const ATTR_CHANNEL = 13;
 
-/**
- * The locations `attachInstances` claims, which a plain draw through the same array must not read.
- *
- * Eleven to fourteen are the model matrix's columns and fifteen is the tint. **Thirteen is also
- * the channel**, and eleven and twelve are the skinning pair — which cannot collide, because
- * `flatVert` refuses skinning with instancing. See `draw`.
- */
-const INSTANCE_COLUMNS = [11, 12, 13, 14, 15] as const;
 const ATTR_WEIGHTS = 12;
 
 /**
@@ -95,6 +87,9 @@ function applyConstant(
 export class Mesh {
   private readonly vao: WebGLVertexArrayObject;
   private readonly buffers: WebGLBuffer[] = [];
+  /** Every attribute bound from a buffer, so a batch can build a vertex array of its own. */
+  private readonly layout: { location: number; buffer: WebGLBuffer; size: number }[] = [];
+  private indexBuffer: WebGLBuffer | null = null;
   /**
    * The position and normal buffers, kept so `update` can rewrite them.
    *
@@ -104,7 +99,8 @@ export class Mesh {
   private readonly deformable: { positions: WebGLBuffer; normals: WebGLBuffer } | null = null;
   /** How many floats the position buffer holds, so an update of the wrong size is refused. */
   private readonly positionFloats: number;
-  private readonly indexCount: number;
+  /** Indices one draw of it issues; the batch-size rule reads it (`cullsInstances`). */
+  readonly indexCount: number;
   /**
    * The constant values this mesh's *absent* attributes are shaded with, re-applied on
    * every draw.
@@ -227,7 +223,13 @@ export class Mesh {
     if (data.uvs === undefined) {
       gl.disableVertexAttribArray(ATTR_UV);
       this.constants.push({ location: ATTR_UV, value: ABSENT_ATTRIBUTE['uvs'] });
+    } else if (data.layers !== undefined) {
+      /* The texture-array layer rides as the third coordinate — every vertex location is spent —
+         so a layered mesh uploads (u, v, layer) packed. See `MeshData.layers`. */
+      this.attachAttribute(gl, ATTR_UV, packUvLayers(data.uvs, data.layers), 3);
     } else {
+      /* Two components; the shader's vec3 reads z as 0 by the GL rule for a missing component,
+         which is layer 0 — the only layer a plain texture has. */
       this.attachAttribute(gl, ATTR_UV, data.uvs, 2);
     }
 
@@ -313,6 +315,7 @@ export class Mesh {
     if (indexBuffer === null) throw new Error('createBuffer failed');
     this.buffers.push(indexBuffer);
     gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+    this.indexBuffer = indexBuffer;
     this.allocate(gl, gl.ELEMENT_ARRAY_BUFFER, indexBuffer, data.indices, gl.STATIC_DRAW);
 
     gl.bindVertexArray(null);
@@ -322,28 +325,11 @@ export class Mesh {
   draw(gl: WebGL2RenderingContext): void {
     gl.bindVertexArray(this.vao);
     /*
-     * **A mesh with a batch has the instance columns enabled on this very array, and location 13
-     * is the channel.** `attachInstances` claims 11 to 14 for the model matrix and 15 for the
-     * tint; a `Mesh` owns one vertex array, so those bindings are still live for a *plain* draw
-     * through it — and `aChannel` then reads the third column of instance zero's matrix instead
-     * of the absent-attribute constant. For a placement with no rotation that column is
-     * `(0, 0, 1, 0)`, so `aChannel.y` is zero, `vSkyDirect = aChannel.y` scales the directional
-     * term to nothing, and the mesh renders lit by the hemispheric ambient alone — correct
-     * normals, correct albedo, no error, no warning.
-     *
-     * Found on `demo/instancing.ts`, which exists to draw two ranks of one box the two ways and
-     * compare them: the `drawMesh` rank's top face read (51, 30, 21) against the `drawInstanced`
-     * rank's (218, 110, 59), and 51 is exactly the ambient. WebGPU has no array to share and drew
-     * them alike, which is what made it visible at all.
-     *
-     * Disabled here and put back by `drawInstances`, rather than given the batch an array of its
-     * own: that is the larger change this class's own note about two batches already contemplates,
-     * and it wants one for a different reason. Three calls on a mesh that has a batch and none on
-     * a mesh that does not.
+     * No instance columns to disable: a batch draws through a vertex array of its own
+     * (`createInstanceArray`), so this array never carries them. It used to, and location 13 — the
+     * channel — then read the third column of instance zero's matrix on a plain draw, which lit a
+     * mesh by ambient alone on this backend and not the other.
      */
-    if (this.instanced) {
-      for (const location of INSTANCE_COLUMNS) gl.disableVertexAttribArray(location);
-    }
     // The VAO restores the arrays; these it cannot. See `constants`.
     for (const constant of this.constants) {
       const value = constant.value;
@@ -353,35 +339,30 @@ export class Mesh {
   }
 
   /**
-   * Bind one buffer's per-instance attributes to this mesh's vertex array.
+   * A vertex array for one instanced batch: every attribute this mesh binds from a buffer, its index
+   * buffer, and the batch's instance columns — the model matrix at 11 to 14, the tint at 15.
    *
-   * **One batch per mesh, and the vertex array is why.** A `Mesh` owns exactly one, so a second
-   * batch would rebind locations 11 to 15 on the array the first still draws through — and what
-   * comes out is one batch's instances placed by the other's matrices, which reads as a transform
-   * bug in the consumer's own code rather than as a misuse of this.
-   *
-   * **What would make it wrong** is a consumer legitimately wanting two batches of one mesh,
-   * which wants a vertex array per batch rather than a flag here.
+   * **A batch owns its own array**, which is what lets a mesh have more than one batch: a prop drawn
+   * once per region is one mesh and a batch per region. With one array a mesh had one batch, since a
+   * second would rebind the columns the first draws through and place one batch's instances by the
+   * other's matrices. The arrays share every buffer, so a batch costs its instances and nothing of
+   * the geometry. The caller deletes what this returns.
    */
-  attachInstances(gl: WebGL2RenderingContext, buffer: WebGLBuffer, stride: number): void {
-    if (this.instanced) {
-      throw new Error(
-        'Mesh: this mesh already has an instanced batch — a Mesh owns one vertex array, so a ' +
-          'second batch would rebind the attributes the first draws through.',
-      );
+  createInstanceArray(
+    gl: WebGL2RenderingContext,
+    instances: WebGLBuffer,
+    stride: number,
+  ): WebGLVertexArrayObject {
+    const vao = gl.createVertexArray();
+    if (vao === null) throw new Error('createVertexArray failed');
+    gl.bindVertexArray(vao);
+    for (const attribute of this.layout) {
+      gl.bindBuffer(gl.ARRAY_BUFFER, attribute.buffer);
+      gl.enableVertexAttribArray(attribute.location);
+      gl.vertexAttribPointer(attribute.location, attribute.size, gl.FLOAT, false, 0, 0);
     }
-    this.instanced = true;
-    this.instanceBuffer = buffer;
-    this.instanceStride = stride;
-    gl.bindVertexArray(this.vao);
-    this.bindInstanceColumns(gl, buffer);
-    gl.bindVertexArray(null);
-  }
-
-  /** The instance columns, bound. Called at attach and again after a plain draw disabled them. */
-  private bindInstanceColumns(gl: WebGL2RenderingContext, buffer: WebGLBuffer): void {
-    const stride = this.instanceStride;
-    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, this.indexBuffer);
+    gl.bindBuffer(gl.ARRAY_BUFFER, instances);
     /* Four vec4 columns then a vec3 tint: a mat4 is not a vertex attribute in GLSL ES 300. */
     for (let column = 0; column < 4; column += 1) {
       const location = 11 + column;
@@ -392,24 +373,17 @@ export class Mesh {
     gl.enableVertexAttribArray(15);
     gl.vertexAttribPointer(15, 3, gl.FLOAT, false, stride, 64);
     gl.vertexAttribDivisor(15, 1);
+    gl.bindVertexArray(null);
+    return vao;
   }
 
-  private instanceBuffer: WebGLBuffer | null = null;
-  private instanceStride = 0;
-
-  /** Whether `attachInstances` has already claimed locations 11 to 15 on this mesh's array. */
-  private instanced = false;
-
-  /**
-   * Draw `count` instances through the attributes `attachInstances` bound.
-   *
-   * The constants are re-applied exactly as `draw` does — a vertex array restores the arrays and
-   * not the constant attributes, and an absent optional attribute is a constant here.
-   */
-  drawInstances(gl: WebGL2RenderingContext, count: number): void {
-    gl.bindVertexArray(this.vao);
-    /* Put back what `draw` disabled, if a plain draw of this mesh came first. See its note. */
-    if (this.instanceBuffer !== null) this.bindInstanceColumns(gl, this.instanceBuffer);
+  /** Draw `count` instances through a batch's own vertex array. See `createInstanceArray`. */
+  drawInstancesThrough(
+    gl: WebGL2RenderingContext,
+    vao: WebGLVertexArrayObject,
+    count: number,
+  ): void {
+    gl.bindVertexArray(vao);
     for (const constant of this.constants) {
       const value = constant.value;
       applyConstant(gl, constant.location, value);
@@ -472,6 +446,7 @@ export class Mesh {
     this.allocate(gl, gl.ARRAY_BUFFER, buffer, data, usage);
     gl.enableVertexAttribArray(location);
     gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+    this.layout.push({ location, buffer, size });
     return buffer;
   }
 
@@ -579,3 +554,15 @@ export function createMeshIncremental(
   const mesh = new Mesh(gl, data, dynamic, true);
   return { mesh, upload: mesh.uploads(gl) };
 }
+
+/** Texture coordinates and layers interleaved as (u, v, layer), one row a vertex. */
+export function packUvLayers(uvs: Float32Array, layers: Float32Array): Float32Array {
+  const count = layers.length;
+  const packed = new Float32Array(count * 3);
+  for (let v = 0; v < count; v++) {
+    packed[v * 3] = uvs[v * 2] as number;
+    packed[v * 3 + 1] = uvs[v * 2 + 1] as number;
+    packed[v * 3 + 2] = layers[v] as number;
+  }
+  return packed;
+}

package/src/render/occlusion.ts

@@ -39,6 +39,9 @@ import type { Bounds } from '../math/bounds.ts';
 /** What an unwritten texel holds: the far plane, which occludes nothing. */
 const FAR = 1;
 
+/** Texels a tested rectangle may span at the level it is read from. See `boxBehind`. */
+const TEXELS_ACROSS = 8;
+
 export interface OcclusionOptions {
   /** Texels across. The height follows the aspect. */
   readonly width: number;
@@ -189,15 +192,47 @@ export class OcclusionBuffer {
     const radius = bounds.radius * Math.max(sx, sy, sz);
 
     /* The cube that contains the sphere, which contains the object. Conservative twice over. */
+    return this.boxBehind(x - radius, y - radius, z - radius, x + radius, y + radius, z + radius);
+  }
+
+  /**
+   * Whether a world-space box is entirely behind the declared occluders — the tighter question for
+   * something that is a box, where the cube around its sphere reaches far past it. **A flat region
+   * is the case it exists for**: a city block's sphere is half as deep underground as it is wide,
+   * nothing there occludes it, and the sphere test abstains for every block in the city. False
+   * whenever anything is uncertain, exactly as `occluded`.
+   */
+  occludedBox(min: ArrayLike<number>, max: ArrayLike<number>): boolean {
+    if (this.occluders === 0) return false;
+    if (!this.built) this.buildPyramid();
+    return this.boxBehind(
+      min[0] ?? 0,
+      min[1] ?? 0,
+      min[2] ?? 0,
+      max[0] ?? 0,
+      max[1] ?? 0,
+      max[2] ?? 0,
+    );
+  }
+
+  /** The shared test: a world box's corners projected, its rectangle tested against the pyramid. */
+  private boxBehind(
+    loX: number,
+    loY: number,
+    loZ: number,
+    hiX: number,
+    hiY: number,
+    hiZ: number,
+  ): boolean {
     let minX = Infinity;
     let minY = Infinity;
     let minZ = Infinity;
     let maxX = -Infinity;
     let maxY = -Infinity;
     for (let corner = 0; corner < 8; corner++) {
-      const px = corner & 1 ? x + radius : x - radius;
-      const py = corner & 2 ? y + radius : y - radius;
-      const pz = corner & 4 ? z + radius : z - radius;
+      const px = corner & 1 ? hiX : loX;
+      const py = corner & 2 ? hiY : loY;
+      const pz = corner & 4 ? hiZ : loZ;
       if (!this.project(px, py, pz, 0)) return false;
       minX = Math.min(minX, CORNERS[0] ?? 0);
       maxX = Math.max(maxX, CORNERS[0] ?? 0);
@@ -212,13 +247,22 @@ export class OcclusionBuffer {
     if (minX < 0 || minY < 0 || maxX > width || maxY > height) return false;
 
     /*
-     * The coarsest level whose texel is at least as wide as the rectangle, so the test reads at
-     * most two texels each way. `Math.log2` would say the same thing and is one of the calls this
-     * repository's determinism gate refuses elsewhere; a shift loop says it in integers.
+     * The coarsest level at which the rectangle spans at most `TEXELS_ACROSS` texels, so the test
+     * reads at most that many plus one each way. `Math.log2` would say the same thing and is one of
+     * the calls this repository's determinism gate refuses elsewhere; a shift loop says it in integers.
+     *
+     * **Eight, not one, since 2026-09-30.** At one the level's texel was as wide as the rectangle, and
+     * two such texels aligned to the grid span up to twice it — so anything whose rectangle came near
+     * an occluder's edge, or the buffer's own unwritten border row, read unwritten texels and
+     * abstained. That was every city region behind a row of buildings, whose rectangle sits just
+     * under the skyline; measured on a box seven metres wide behind a wall filling the view, which
+     * one abstained at and eight culls. Reading up to 81 texels instead of 4 costs a few dozen
+     * compares and keeps the answer exactly as conservative: the maximum over every texel the
+     * rectangle touches.
      */
     let level = 0;
     let span = Math.max(maxX - minX, maxY - minY);
-    while (span > 1 && level + 1 < this.levels.length) {
+    while (span > TEXELS_ACROSS && level + 1 < this.levels.length) {
       span *= 0.5;
       level++;
     }

package/src/render/pointGlassTint.ts

@@ -0,0 +1,250 @@
+import { mat3 } from 'gl-matrix';
+
+import { createEmptyTexture2D } from './emptyTexture.ts';
+import { pointShadowFaceRotation } from './pointShadowImage.ts';
+import { compileProgram, uniformLocations } from './shader.ts';
+import {
+  OCTAHEDRAL_RESOLVE_TINT_FRAG,
+  OCTAHEDRAL_RESOLVE_VERT,
+} from './shaders/octahedralResolve.ts';
+
+/** Filled per resolved face, at module scope, because a bake runs inside the frame's budget. */
+const faceRotation = mat3.create();
+const CLEAR = new Float32Array([1, 1, 1, 1]);
+
+/**
+ * What a lamp's light keeps through glass: an RGBA8 array of one layer a light, parallel to the
+ * point shadow array and indexed by the light, not by the interleaved depth layer. RGB is the
+ * product of every pane's `transmission × (1 − F) × tint`, A the product of their clarities
+ * (`glassShadow.ts`).
+ *
+ * **Drawn a face at a time, as the depth is**: into a face-sized colour scratch cleared to white,
+ * with a multiplying blend and no depth test, then resolved into the face's region of the layer by
+ * `OCTAHEDRAL_RESOLVE_TINT_FRAG`. One scratch for the whole engine, for the reason
+ * `PointShadowArray` gives for its own.
+ *
+ * **Which faces hold glass is remembered, six bits a layer**, so a face with no glass and none to
+ * forget costs nothing, and a face that inherited a previous owner's glass is cleared. **The chain
+ * frost reads is rebuilt once a round**, for the layers the round touched, through a 2D staging
+ * chain: `generateMipmap` on an array rebuilds every layer, which is the whole pool's texels for one
+ * lamp's glass. What that costs is one layer of memory with its chain — 5.6 MB at 1024, 1.4 MB at
+ * `'half'` — and a copy out and back per touched layer.
+ */
+export class PointGlassTint {
+  readonly texture: WebGLTexture;
+  readonly edge: number;
+
+  private readonly layers: number;
+  private readonly levels: number;
+  private readonly faceSize: number;
+  private readonly scratch: WebGLTexture;
+  private readonly scratchFramebuffer: WebGLFramebuffer;
+  private readonly staging: WebGLTexture;
+  private readonly framebuffer: WebGLFramebuffer;
+  private readonly readFramebuffer: WebGLFramebuffer;
+  /** Parked on the resolve's unit while the scratch is a render target; see `beginFace`. */
+  private readonly parked: WebGLTexture;
+  private readonly program: WebGLProgram;
+  private readonly uniforms: Record<string, WebGLUniformLocation>;
+  private readonly vao: WebGLVertexArrayObject;
+  /** Six bits a layer: which faces' regions hold glass. */
+  private readonly heldFaces: Uint8Array;
+  /** Layers whose level 0 changed since the chain was last rebuilt. */
+  private readonly dirty: Uint8Array;
+
+  constructor(gl: WebGL2RenderingContext, faceSize: number, edge: number, layers: number) {
+    this.edge = edge;
+    this.layers = layers;
+    this.faceSize = faceSize;
+    this.levels = Math.floor(Math.log2(Math.max(1, edge))) + 1;
+    this.heldFaces = new Uint8Array(layers);
+    this.dirty = new Uint8Array(layers);
+
+    this.texture = colourTexture(gl, gl.TEXTURE_2D_ARRAY, this.levels, edge, layers);
+    this.scratch = colourTexture(gl, gl.TEXTURE_2D, 1, faceSize, 1);
+    this.staging = colourTexture(gl, gl.TEXTURE_2D, this.levels, edge, 1);
+    this.parked = createEmptyTexture2D(gl);
+    this.scratchFramebuffer = framebufferOf(gl);
+    this.framebuffer = framebufferOf(gl);
+    this.readFramebuffer = framebufferOf(gl);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.scratchFramebuffer);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.scratch, 0);
+
+    this.program = compileProgram(
+      gl,
+      OCTAHEDRAL_RESOLVE_VERT,
+      OCTAHEDRAL_RESOLVE_TINT_FRAG,
+      'octahedralResolveTint',
+    );
+    this.uniforms = uniformLocations(gl, this.program, 'octahedralResolveTint');
+    const vao = gl.createVertexArray();
+    if (vao === null) throw new Error('PointGlassTint: createVertexArray failed');
+    this.vao = vao;
+
+    /* Every layer born clear: a light no pane has reached lets everything through. */
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    for (let layer = 0; layer < layers; layer++) {
+      gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, this.texture, 0, layer);
+      gl.clearBufferfv(gl.COLOR, 0, CLEAR);
+    }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    /* Once, for every layer: white all the way down. */
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
+    gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+  }
+
+  /** Whether `face` of `layer` holds glass: a face that does must be cleared before it is reused. */
+  held(layer: number, face: number): boolean {
+    return (((this.heldFaces[layer] ?? 0) >> face) & 1) === 1;
+  }
+
+  /**
+   * Bind the colour scratch, clear it to white, and set the multiplying state.
+   *
+   * The previous resolve left the scratch bound for sampling on unit 0, and it is about to be the
+   * target: parked first, for the reason `PointShadowArray.beginFace` gives.
+   */
+  beginFace(gl: WebGL2RenderingContext): void {
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, this.parked);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.scratchFramebuffer);
+    gl.viewport(0, 0, this.faceSize, this.faceSize);
+    gl.clearBufferfv(gl.COLOR, 0, CLEAR);
+    gl.disable(gl.DEPTH_TEST);
+    gl.depthMask(false);
+    gl.enable(gl.BLEND);
+    gl.blendEquation(gl.FUNC_ADD);
+    gl.blendFuncSeparate(gl.DST_COLOR, gl.ZERO, gl.DST_ALPHA, gl.ZERO);
+  }
+
+  /**
+   * Copy the scratch into `face`'s region of `layer`, and remember whether it held glass.
+   *
+   * Leaves depth testing and writing on, which is what the next face's casters expect: the depth
+   * resolve that runs before them turns both on, and this one ran after it and turned them off.
+   */
+  resolveFace(gl: WebGL2RenderingContext, layer: number, face: number, drawn: boolean): void {
+    gl.disable(gl.BLEND);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, this.texture, 0, layer);
+    gl.viewport(0, 0, this.edge, this.edge);
+    gl.useProgram(this.program);
+    gl.bindVertexArray(this.vao);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, this.scratch);
+    gl.uniform1i(this.uniforms['uFace'] ?? null, 0);
+    gl.uniform1i(this.uniforms['uFaceIndex'] ?? null, face);
+    gl.uniformMatrix3fv(
+      this.uniforms['uFaceRotation'] ?? null,
+      false,
+      pointShadowFaceRotation(face, faceRotation),
+    );
+    gl.uniform1f(this.uniforms['uEdge'] ?? null, this.edge);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    gl.bindVertexArray(null);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.enable(gl.DEPTH_TEST);
+    gl.depthMask(true);
+
+    const bit = 1 << face;
+    const was = this.heldFaces[layer] ?? 0;
+    this.heldFaces[layer] = drawn ? was | bit : was & ~bit;
+    this.dirty[layer] = 1;
+  }
+
+  /** Rebuild the chain of every layer touched since the last call, one layer at a time. */
+  fillMips(gl: WebGL2RenderingContext): void {
+    for (let layer = 0; layer < this.layers; layer++) {
+      if (this.dirty[layer] !== 1) continue;
+      this.dirty[layer] = 0;
+      /* Level 0 out into the staging chain, which mipmaps as one 2D texture. */
+      gl.bindFramebuffer(gl.READ_FRAMEBUFFER, this.readFramebuffer);
+      gl.framebufferTextureLayer(gl.READ_FRAMEBUFFER, gl.COLOR_ATTACHMENT0, this.texture, 0, layer);
+      gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.framebuffer);
+      gl.framebufferTexture2D(
+        gl.DRAW_FRAMEBUFFER,
+        gl.COLOR_ATTACHMENT0,
+        gl.TEXTURE_2D,
+        this.staging,
+        0,
+      );
+      blit(gl, this.edge, this.edge);
+      gl.bindTexture(gl.TEXTURE_2D, this.staging);
+      gl.generateMipmap(gl.TEXTURE_2D);
+      gl.bindTexture(gl.TEXTURE_2D, null);
+      /* And every level after it back into the layer. */
+      for (let level = 1; level < this.levels; level++) {
+        const size = Math.max(1, this.edge >> level);
+        gl.framebufferTexture2D(
+          gl.READ_FRAMEBUFFER,
+          gl.COLOR_ATTACHMENT0,
+          gl.TEXTURE_2D,
+          this.staging,
+          level,
+        );
+        gl.framebufferTextureLayer(
+          gl.DRAW_FRAMEBUFFER,
+          gl.COLOR_ATTACHMENT0,
+          this.texture,
+          level,
+          layer,
+        );
+        blit(gl, size, size);
+      }
+      gl.bindFramebuffer(gl.READ_FRAMEBUFFER, null);
+      gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, null);
+    }
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    gl.deleteFramebuffer(this.scratchFramebuffer);
+    gl.deleteFramebuffer(this.framebuffer);
+    gl.deleteFramebuffer(this.readFramebuffer);
+    gl.deleteTexture(this.texture);
+    gl.deleteTexture(this.scratch);
+    gl.deleteTexture(this.staging);
+    gl.deleteTexture(this.parked);
+    gl.deleteProgram(this.program);
+    gl.deleteVertexArray(this.vao);
+  }
+}
+
+/** A colour texture with `levels` levels: nearest for a single level, trilinear for a chain. */
+function colourTexture(
+  gl: WebGL2RenderingContext,
+  target: number,
+  levels: number,
+  edge: number,
+  layers: number,
+): WebGLTexture {
+  const texture = gl.createTexture();
+  if (texture === null) throw new Error('PointGlassTint: createTexture failed');
+  gl.bindTexture(target, texture);
+  if (target === gl.TEXTURE_2D_ARRAY) {
+    gl.texStorage3D(target, levels, gl.RGBA8, edge, edge, layers);
+  } else {
+    gl.texStorage2D(target, levels, gl.RGBA8, edge, edge);
+  }
+  gl.texParameteri(
+    target,
+    gl.TEXTURE_MIN_FILTER,
+    levels > 1 ? gl.LINEAR_MIPMAP_LINEAR : gl.NEAREST,
+  );
+  gl.texParameteri(target, gl.TEXTURE_MAG_FILTER, levels > 1 ? gl.LINEAR : gl.NEAREST);
+  gl.texParameteri(target, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(target, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  gl.bindTexture(target, null);
+  return texture;
+}
+
+function framebufferOf(gl: WebGL2RenderingContext): WebGLFramebuffer {
+  const framebuffer = gl.createFramebuffer();
+  if (framebuffer === null) throw new Error('PointGlassTint: createFramebuffer failed');
+  return framebuffer;
+}
+
+/** The bound read framebuffer's colour into the bound draw framebuffer's, texel for texel. */
+function blit(gl: WebGL2RenderingContext, width: number, height: number): void {
+  gl.blitFramebuffer(0, 0, width, height, 0, 0, width, height, gl.COLOR_BUFFER_BIT, gl.NEAREST);
+}

package/src/render/pointLightSelection.ts

@@ -2,6 +2,8 @@
 
 import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from './clusteredLights.ts';
 import { MAX_POINT_LIGHTS, POINT_SHADOW_POOL } from './lightBudget.ts';
+import { gatherLights } from './lightGrid.ts';
+import type { LightGrid } from './lightGrid.ts';
 
 export const DEFAULT_POINT_LIGHT_VIEW_RANGE = 180;
 
@@ -43,8 +45,15 @@ const FADE_BAND_M = 40;
  */
 const CONTENTION_BAND_M = 3;
 
-/** Sort keys for the shadow list, which is ordered independently of the shaded one. */
-const shadowRank = new Float32Array(POINT_SHADOW_POOL);
+/**
+ * Sort keys for the shadow list, which is ordered independently of the shaded one.
+ *
+ * **Float64, and ties broken by source index**, the shaded list's rule. These were single precision
+ * compared against a double, so which of two lamps exactly as far away came first depended on
+ * which way the distance happened to round — and on the order the lamps were met, which is what a
+ * grid changes. Now the list is the same whatever order its candidates arrive in.
+ */
+const shadowRank = new Float64Array(POINT_SHADOW_POOL);
 
 /**
  * Every light in range this frame, by source index and squared distance, before the nearest are
@@ -344,6 +353,58 @@ export function selectPointLights(
   castX = x,
   castY = y,
   castZ = z,
+): void {
+  choose(sources, null, sources.length, x, y, z, out, timeSeconds, viewRange, castX, castY, castZ);
+}
+
+/**
+ * `selectPointLights` over a grid's sources, looking only at the lights near the eye: the same
+ * choice, tie for tie, for a world of thousands of fixed lights that the plain scan would visit
+ * every frame. See `lightGrid.ts` for why the result is the scan's exactly.
+ */
+export function selectGridLights(
+  grid: LightGrid,
+  x: number,
+  y: number,
+  z: number,
+  out: PointLightBuffer,
+  timeSeconds = 0,
+  viewRange = DEFAULT_POINT_LIGHT_VIEW_RANGE,
+  castX = x,
+  castY = y,
+  castZ = z,
+): void {
+  const count = gatherLights(grid, x, y, z, viewRange + grid.maxRadius);
+  choose(
+    grid.sources,
+    grid.gathered,
+    count,
+    x,
+    y,
+    z,
+    out,
+    timeSeconds,
+    viewRange,
+    castX,
+    castY,
+    castZ,
+  );
+}
+
+/** The choice itself, over every source or over the ones `visit` names, in source order. */
+function choose(
+  sources: readonly PointLightSource[],
+  visit: Int32Array | null,
+  visitCount: number,
+  x: number,
+  y: number,
+  z: number,
+  out: PointLightBuffer,
+  timeSeconds: number,
+  viewRange: number,
+  castX: number,
+  castY: number,
+  castZ: number,
 ): void {
   out.count = 0;
   out.shadowCount = 0;
@@ -362,7 +423,8 @@ export function selectPointLights(
   let cutSq = Infinity;
   let candidateCount = 0;
 
-  for (let sourceIndex = 0; sourceIndex < sources.length; sourceIndex++) {
+  for (let visited = 0; visited < visitCount; visited++) {
+    const sourceIndex = visit === null ? visited : (visit[visited] as number);
     const light = sources[sourceIndex];
     if (light === undefined) continue;
     /*
@@ -431,7 +493,13 @@ export function selectPointLights(
     const castDistanceSq = cx * cx + cy * cy + cz * cz;
     if (castDistanceSq >= light.radius * light.radius) continue;
     let shadowSlot = out.shadowCount;
-    while (shadowSlot > 0 && (shadowRank[shadowSlot - 1] ?? 0) > castDistanceSq) shadowSlot--;
+    while (
+      shadowSlot > 0 &&
+      ((shadowRank[shadowSlot - 1] ?? 0) > castDistanceSq ||
+        ((shadowRank[shadowSlot - 1] ?? 0) === castDistanceSq &&
+          (out.shadowIndex[shadowSlot - 1] ?? -1) > sourceIndex))
+    )
+      shadowSlot--;
     if (shadowSlot >= POINT_SHADOW_POOL) continue;
     const lastShadow = Math.min(out.shadowCount, POINT_SHADOW_POOL - 1);
     for (let index = lastShadow; index > shadowSlot; index--) {