@driftengine/core 4.8.1 → 4.8.3

package/src/render/cutoutCaster.ts

@@ -13,19 +13,30 @@
  */
 import type { SurfaceMaterial } from './surfaceTexture.ts';
 
-/** A cutout caster's texture, its cutoff and its UV scale. */
+/** A cutout caster's texture, its cutoff and its UV scale and offset. */
 export interface CutoutCaster<Texture> {
   readonly albedo: Texture;
   readonly cutoff: number;
   readonly u: number;
   readonly v: number;
+  readonly uOffset: number;
+  readonly vOffset: number;
 }
 
-const answer: { albedo: unknown; cutoff: number; u: number; v: number } = {
+const answer: {
+  albedo: unknown;
+  cutoff: number;
+  u: number;
+  v: number;
+  uOffset: number;
+  vOffset: number;
+} = {
   albedo: null,
   cutoff: 0,
   u: 1,
   v: 1,
+  uOffset: 0,
+  vOffset: 0,
 };
 
 /** The cutout `material` casts, or null for an ordinary caster. */
@@ -40,5 +51,7 @@ export function cutoutOf<Texture>(
   answer.cutoff = cutoff;
   answer.u = material.uScale ?? 1;
   answer.v = material.vScale ?? 1;
+  answer.uOffset = material.uOffset ?? 0;
+  answer.vOffset = material.vOffset ?? 0;
   return answer as CutoutCaster<Texture>;
 }

package/src/render/decalPass.ts

@@ -7,6 +7,7 @@ import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.ts';
 import { compileProgram, uniformLocations } from './shader.ts';
 import { DECAL_PROJECT_FRAG } from './shaders/decalProject.ts';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.ts';
+import { blendKeeping } from './sceneCoverage.ts';
 
 /**
  * Drawn decals on WebGL2: one scissored triangle per mark, multiplied into the finished scene.
@@ -66,7 +67,7 @@ export class DecalPass {
     gl.depthMask(false);
     gl.disable(gl.CULL_FACE);
     gl.enable(gl.BLEND);
-    gl.blendFunc(gl.ZERO, gl.SRC_COLOR);
+    blendKeeping(gl, gl.ZERO, gl.SRC_COLOR);
     gl.enable(gl.SCISSOR_TEST);
 
     /* Unit 0, chosen rather than inherited: `bindTexture` binds to whichever unit is active, and

package/src/render/globalMediumPass.ts

@@ -7,6 +7,7 @@ import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.ts';
 import { compileProgram, uniformLocations } from './shader.ts';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.ts';
 import { MEDIUM_FRAG, MEDIUM_UPSAMPLE_FRAG } from './shaders/globalMedium.ts';
+import { blendCovering, blendTransmitting } from './sceneCoverage.ts';
 
 /** What the march needs about the light, which is the sun and the sky and nothing else. */
 export interface MediumLight {
@@ -270,7 +271,7 @@ export class GlobalMediumPass {
     gl.depthMask(false);
     gl.disable(gl.CULL_FACE);
     gl.enable(gl.BLEND);
-    gl.blendFuncSeparate(gl.ONE, gl.SRC_ALPHA, gl.ZERO, gl.ONE);
+    blendTransmitting(gl, gl.ONE, gl.SRC_ALPHA);
 
     gl.useProgram(this.upsample);
     gl.bindVertexArray(this.vao);
@@ -293,7 +294,7 @@ export class GlobalMediumPass {
     gl.activeTexture(gl.TEXTURE0);
     gl.bindTexture(gl.TEXTURE_2D, null);
     /* Back to the blend every other pass in this renderer assumes it inherits. */
-    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
     gl.disable(gl.BLEND);
     gl.depthMask(true);
     gl.enable(gl.DEPTH_TEST);

package/src/render/lineBatch.ts

@@ -2,6 +2,7 @@ import { compileProgram, uniformLocations } from './shader.ts';
 import { LINE_FRAG, LINE_VERT } from './shaders/line.ts';
 import { buildSegmentQuads, expandLineSegments } from './segmentQuads.ts';
 import type { LineSegments } from './linePoints.ts';
+import { blendCovering, blendKeeping } from './sceneCoverage.ts';
 
 /**
  * One draw call for a polyline with a real width — an audio waveform, a trail, a plotted
@@ -102,7 +103,8 @@ export class LineBatch {
   drawTo(gl: WebGL2RenderingContext, segmentCount: number, additive = false): void {
     if (segmentCount === 0) return;
     gl.enable(gl.BLEND);
-    gl.blendFunc(gl.SRC_ALPHA, additive ? gl.ONE : gl.ONE_MINUS_SRC_ALPHA);
+    if (additive) blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
+    else blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
     gl.depthMask(false);
     // The quad billboards toward the view direction the same way a bolt's does — see
     // `line.ts`'s own `cross(dir, view)` — so its winding can flip with the camera exactly

package/src/render/mapsWithoutUvs.ts

@@ -0,0 +1,43 @@
+/**
+ * Saying, once a mesh, that a material's maps cannot be read on it.
+ *
+ * **A mesh with no texture coordinates reads one constant coordinate**, so every map bound to it
+ * samples a single texel: an emissive map makes nothing glow, a normal map tilts nothing, and the
+ * frame is identical pixel for pixel with and without the material's images. Found when an example's
+ * burning logs never glowed — `MeshBuilder` writes no coordinates unless `build({ planarUvs: true })`
+ * asks — and nothing said why. One decision for both backends, each calling it from its draw.
+ *
+ * Once per mesh, held weakly: a mesh drawn every frame is said once, and a disposed one is
+ * forgotten. **What it gives up** is a material shared between a textured mesh and an untextured one
+ * on purpose, which is said once for the untextured one and is then quiet.
+ */
+import type { SurfaceMaterial } from './surfaceTexture.ts';
+
+const told = new WeakSet<object>();
+
+/**
+ * Whether a material binds a map that is a picture: albedo, normal or emissive.
+ *
+ * **Not ORM**, because a one-colour ORM map is how a draw sets a constant roughness and metalness,
+ * and read at one texel it is exactly that constant — the materials example draws its spheres so.
+ * The three counted here are pictures nobody binds to be read at one point.
+ */
+export function materialHasMaps(material: SurfaceMaterial<unknown> | null): boolean {
+  if (material === null) return false;
+  return (
+    (material.albedo ?? null) !== null ||
+    (material.normal ?? null) !== null ||
+    (material.emissive ?? null) !== null
+  );
+}
+
+/** Warn the first time `mesh`, which has no coordinates, is drawn with a picture map bound. */
+export function noteMapsWithoutUvs(mesh: object, hasUvs: boolean, materialHasMaps: boolean): void {
+  if (hasUvs || !materialHasMaps || told.has(mesh)) return;
+  told.add(mesh);
+  console.warn(
+    '[driftengine] a mesh with no texture coordinates is drawn with an albedo, normal or emissive ' +
+      'map, which it cannot read: every map samples one texel. Give the mesh `uvs` — ' +
+      '`MeshBuilder.build({ planarUvs: true })` writes them — or draw it without the maps.',
+  );
+}

package/src/render/mesh.ts

@@ -136,6 +136,8 @@ export class Mesh {
   readonly bounds: Bounds = createBounds();
   /** Whether this mesh carries a rig, which decides which flat program draws it. */
   readonly isSkinned: boolean;
+  /** Whether it has texture coordinates, without which a material's maps read one texel. */
+  readonly hasUvs: boolean;
 
   /**
    * This mesh's morph deltas, or null for geometry that does not deform.
@@ -190,6 +192,7 @@ export class Mesh {
   constructor(gl: WebGL2RenderingContext, data: MeshData, dynamic = false, spread = false) {
     validateMeshData(data);
     this.spread = spread;
+    this.hasUvs = data.uvs !== undefined;
     boundsOfPositions(data.positions, this.bounds);
     this.positionFloats = data.positions.length;
     const vao = gl.createVertexArray();

package/src/render/oitPass.ts

@@ -1,6 +1,7 @@
 import { compileProgram, uniformLocations } from './shader.ts';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.ts';
 import { OIT_RESOLVE_FRAG } from './shaders/oitResolve.ts';
+import { blendTransmitting } from './sceneCoverage.ts';
 
 /**
  * Order-independent transparency on WebGL2: two targets, two passes over the same geometry, and a
@@ -179,7 +180,7 @@ export class OitPass {
     gl.depthMask(false);
     gl.disable(gl.CULL_FACE);
     gl.enable(gl.BLEND);
-    gl.blendFunc(gl.ONE_MINUS_SRC_ALPHA, gl.SRC_ALPHA);
+    blendTransmitting(gl, gl.ONE_MINUS_SRC_ALPHA, gl.SRC_ALPHA);
 
     gl.useProgram(this.program);
     gl.activeTexture(gl.TEXTURE0);

package/src/render/particleBatch.ts

@@ -2,6 +2,7 @@ import { compileProgram, uniformLocations } from './shader.ts';
 import { particleShaders, type ParticleMaterial } from './particleMaterial.ts';
 import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from './shaders/particle.ts';
 import type { ParticleInstances } from './particlePool.ts';
+import { blendCovering, blendKeeping } from './sceneCoverage.ts';
 
 /**
  * One draw call for a live particle pool: one camera-facing quad per particle, or a
@@ -239,8 +240,8 @@ export class ParticleBatch {
   drawTo(gl: WebGL2RenderingContext, count: number): void {
     if (count === 0) return;
     gl.enable(gl.BLEND);
-    if (this.blend === 'additive') gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
-    else gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    if (this.blend === 'additive') blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
+    else blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
     gl.depthMask(false);
     gl.disable(gl.CULL_FACE);
 

package/src/render/particlePool.ts

@@ -21,7 +21,11 @@ import type { Vec3 } from '../math/color.ts';
 export interface ParticleInstances {
   /** World position, three floats each. */
   positions: Float32Array;
-  /** Metres across, and radians of roll about the particle's own axis. */
+  /**
+   * Metres from the centre to an edge, a half-width: the quad spans twice this. Then radians of
+   * roll about the particle's own axis. This said metres across until 4.8.3, and a caller who took
+   * it at its word drew every particle twice as wide as meant.
+   */
   sizes: Float32Array;
   spins: Float32Array;
   /** Linear colour, three floats each. */
@@ -72,7 +76,7 @@ export interface ParticlePoolOptions {
   capacity: number;
   /** Seconds a particle lives. */
   lifeSec: number;
-  /** Size at birth and at death, metres. */
+  /** Size at birth and at death: metres from the centre to an edge, so the quad is twice as wide. */
   sizeStart: number;
   sizeEnd: number;
   /** Colour at birth and at death. */
@@ -117,6 +121,15 @@ export class ParticlePool {
    * together.
    */
   private readonly seedOf: Float32Array;
+  /**
+   * Where each slot's particle sits in the drawn streams, or -1 where it sits nowhere.
+   *
+   * **What lets `emit` draw a particle the frame it is born.** The streams are compacted, so a
+   * slot's entry is wherever `update` last put it; an emit into a slot that has one overwrites
+   * that entry, and an emit into one that has none appends. Without it a new particle waited for
+   * the next `update` to be drawn at all.
+   */
+  private readonly drawnAt: Int32Array;
   private next = 0;
 
   constructor(private readonly options: ParticlePoolOptions) {
@@ -138,6 +151,7 @@ export class ParticlePool {
     this.spin = new Float32Array(capacity);
     this.scale = new Float32Array(capacity).fill(1);
     this.seedOf = new Float32Array(capacity);
+    this.drawnAt = new Int32Array(capacity).fill(-1);
   }
 
   /** How many particles are alive. */
@@ -184,6 +198,18 @@ export class ParticlePool {
     this.spin[i] = (hash - Math.floor(hash)) * Math.PI * 2;
     this.scale[i] = sizeScale;
     this.seedOf[i] = seed;
+    /*
+     * Drawn now, at birth, rather than at the next `update`: into the entry this slot already
+     * has when it is taking over a particle that was drawn, and onto the end otherwise.
+     */
+    const held = this.drawnAt[i] as number;
+    const at = held >= 0 ? held : this.particles.count;
+    this.writeDrawn(i, at, 0, x, y, z, vx, vy, vz);
+    if (held < 0) {
+      this.drawnAt[i] = at;
+      this.instances.count = at + 1;
+      this.particles.count = at + 1;
+    }
   }
 
   /**
@@ -198,11 +224,15 @@ export class ParticlePool {
     let count = 0;
     for (let i = 0; i < this.age.length; i++) {
       const age = this.age[i] as number;
-      if (age === Infinity) continue;
+      if (age === Infinity) {
+        this.drawnAt[i] = -1;
+        continue;
+      }
       const life = this.life[i] as number;
       const next = age + dt;
       if (next >= life) {
         this.age[i] = Infinity;
+        this.drawnAt[i] = -1;
         continue;
       }
       this.age[i] = next;
@@ -222,68 +252,89 @@ export class ParticlePool {
       this.y[i] = py;
       this.z[i] = pz;
 
-      const t = next / life;
-      const size = (o.sizeStart + (o.sizeEnd - o.sizeStart) * t) * (this.scale[i] as number);
-      const r =
-        (o.colorStart[0] as number) + ((o.colorEnd[0] as number) - (o.colorStart[0] as number)) * t;
-      const g =
-        (o.colorStart[1] as number) + ((o.colorEnd[1] as number) - (o.colorStart[1] as number)) * t;
-      const b =
-        (o.colorStart[2] as number) + ((o.colorEnd[2] as number) - (o.colorStart[2] as number)) * t;
-      /*
-       * Colour carries the fade rather than an alpha channel: the instanced
-       * path multiplies a tint into the base mesh and has no per-instance
-       * opacity, and for an additive puff darkening to nothing *is* fading out.
-       * It also means the effect needs no blend-state change.
-       */
-      const fade = 1 - t * t;
-      writeInstance(
-        this.instances,
-        count,
-        px,
-        py,
-        pz,
-        size,
-        this.spin[i] as number,
-        r * fade,
-        g * fade,
-        b * fade,
-        0,
-        0,
-        0,
-      );
-      /*
-       * The same particle for a material that has a real opacity channel. Colour
-       * is written *unfaded* here, because dimming it is the scatter path's
-       * workaround and doing both would fade twice — a puff that vanished at half
-       * its life while still occluding what was behind it.
-       */
-      const p = this.particles;
-      const alphaStart = o.alphaStart ?? 1;
-      const alphaEnd = o.alphaEnd ?? 0;
-      p.positions[count * 3] = px;
-      p.positions[count * 3 + 1] = py;
-      p.positions[count * 3 + 2] = pz;
-      p.sizes[count] = size;
-      p.spins[count] = this.spin[i] as number;
-      p.colors[count * 3] = r;
-      p.colors[count * 3 + 1] = g;
-      p.colors[count * 3 + 2] = b;
-      p.alphas[count] = alphaStart + (alphaEnd - alphaStart) * t;
-      p.ages[count] = t;
-      p.seeds[count] = this.seedOf[i] as number;
-      p.velocities[count * 3] = vx;
-      p.velocities[count * 3 + 1] = vy;
-      p.velocities[count * 3 + 2] = vz;
+      this.drawnAt[i] = count;
+      this.writeDrawn(i, count, next / life, px, py, pz, vx, vy, vz);
       count++;
     }
     this.instances.count = count;
     this.particles.count = count;
   }
 
+  /**
+   * One particle's entry in both drawn streams, at `t` of its life: what `update` writes for every
+   * live particle and `emit` for a new one, so the two cannot disagree about what a particle looks
+   * like.
+   */
+  private writeDrawn(
+    i: number,
+    count: number,
+    t: number,
+    px: number,
+    py: number,
+    pz: number,
+    vx: number,
+    vy: number,
+    vz: number,
+  ): void {
+    const o = this.options;
+    const size = (o.sizeStart + (o.sizeEnd - o.sizeStart) * t) * (this.scale[i] as number);
+    const r =
+      (o.colorStart[0] as number) + ((o.colorEnd[0] as number) - (o.colorStart[0] as number)) * t;
+    const g =
+      (o.colorStart[1] as number) + ((o.colorEnd[1] as number) - (o.colorStart[1] as number)) * t;
+    const b =
+      (o.colorStart[2] as number) + ((o.colorEnd[2] as number) - (o.colorStart[2] as number)) * t;
+    /*
+     * Colour carries the fade rather than an alpha channel: the instanced
+     * path multiplies a tint into the base mesh and has no per-instance
+     * opacity, and for an additive puff darkening to nothing *is* fading out.
+     * It also means the effect needs no blend-state change.
+     */
+    const fade = 1 - t * t;
+    writeInstance(
+      this.instances,
+      count,
+      px,
+      py,
+      pz,
+      size,
+      this.spin[i] as number,
+      r * fade,
+      g * fade,
+      b * fade,
+      0,
+      0,
+      0,
+    );
+    /*
+     * The same particle for a material that has a real opacity channel. Colour
+     * is written *unfaded* here, because dimming it is the scatter path's
+     * workaround and doing both would fade twice — a puff that vanished at half
+     * its life while still occluding what was behind it.
+     */
+    const p = this.particles;
+    const alphaStart = o.alphaStart ?? 1;
+    const alphaEnd = o.alphaEnd ?? 0;
+    p.positions[count * 3] = px;
+    p.positions[count * 3 + 1] = py;
+    p.positions[count * 3 + 2] = pz;
+    p.sizes[count] = size;
+    p.spins[count] = this.spin[i] as number;
+    p.colors[count * 3] = r;
+    p.colors[count * 3 + 1] = g;
+    p.colors[count * 3 + 2] = b;
+    p.alphas[count] = alphaStart + (alphaEnd - alphaStart) * t;
+    p.ages[count] = t;
+    p.seeds[count] = this.seedOf[i] as number;
+    p.velocities[count * 3] = vx;
+    p.velocities[count * 3 + 1] = vy;
+    p.velocities[count * 3 + 2] = vz;
+  }
+
   /** Drop everything, for a respawn or a scene change. */
   clear(): void {
     this.age.fill(Infinity);
+    this.drawnAt.fill(-1);
     this.instances.count = 0;
     this.particles.count = 0;
     this.next = 0;

package/src/render/pass.ts

@@ -125,6 +125,18 @@ export type PassContext = {
       readonly pass: GPURenderPassEncoder;
       /** The frame's jitter, the same array `PrepareContext.jitter` held. */
       readonly jitter: Float32Array;
+      /**
+       * The colour format, depth format and sample count of the pass this draw lands in, which a
+       * pipeline set on it must match exactly.
+       *
+       * **Not always the device's.** `PassDevice` says what the frame is; a pass drawn after
+       * `endFrame` lands on the canvas, at the canvas's format and one sample, where the frame is
+       * the scene target at the scene's samples. A pass that is drawn in both places keeps a
+       * pipeline for each and chooses here; one built only from the device is refused by the other.
+       */
+      readonly format: GPUTextureFormat;
+      readonly depthFormat: GPUTextureFormat;
+      readonly samples: number;
     }
 );
 

package/src/render/plumeRenderer.ts

@@ -6,6 +6,7 @@ import { plumeShaders, type PlumeMaterial } from './plumeMaterial.ts';
 import { buildPlumeGeometry } from './plumeGeometry.ts';
 import type { Atmosphere } from './atmosphere.ts';
 import type { Vec3 } from '../math/color.ts';
+import { blendCovering, blendKeeping } from './sceneCoverage.ts';
 
 /**
  * Batched camera-facing quads for volumetric effects — flames, smoke, steam,
@@ -202,8 +203,8 @@ export class PlumeRenderer {
     bindAtmosphere(gl, u, atmosphere, atmosphereCameraY, underwaterEnabled);
 
     gl.enable(gl.BLEND);
-    if (this.blend === 'additive') gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
-    else gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    if (this.blend === 'additive') blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
+    else blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
     gl.depthMask(false);
     gl.disable(gl.CULL_FACE);
 

package/src/render/renderQuality.ts

@@ -20,8 +20,14 @@ import { PREFILTER_SAMPLE_COUNTS } from './prefilterEnvMap.ts';
  * `aces` adds filmic tone mapping before that, rolling highlights off instead of
  * clipping them flat. Together they are what three.js does by default, which is why a
  * world ported from it looks wrong until this exists.
+ *
+ * `shoulder` keeps sRGB's midtones exactly and eases only the highlights: past 0.8 the brightest
+ * channel rolls toward 1 and the other two are scaled with it, so an overbright red spark stays
+ * red where `srgb` clips each channel and turns its core pink and wide. It is the curve a ported
+ * game's own resolve applied — for a port that has to match one — and it has none of ACES's toe or
+ * desaturation. See `HIGHLIGHT_SHOULDER_GLSL` for the arithmetic.
  */
-export type OutputTransform = 'none' | 'srgb' | 'aces';
+export type OutputTransform = 'none' | 'srgb' | 'aces' | 'shoulder';
 
 /**
  * The three settings whose accepted values are a closed set, written as one.
@@ -69,7 +75,8 @@ export interface RenderQuality {
    * chooses is a look rather than a standard — three.js uses 1/0.6 and says so. This
    * engine holds no opinion and takes the number from whoever is authoring the world, so
    * that matching another renderer, or simply preferring a different grade, is a setting
-   * rather than a patch. Ignored when `outputTransform` is not `aces`.
+   * rather than a patch. Scales into `aces` and into `shoulder`, the two curves; ignored by
+   * `none` and `srgb`, which have none.
    */
   readonly outputExposure: number;
   /**
@@ -194,12 +201,13 @@ export interface RenderQuality {
    * existed: a pane casts nothing at all.
    *
    * Nothing is allocated until a glass caster first reaches a shadow, so a scene with no glass pays
-   * no memory and no pass whatever this says. **The lit shader is the exception**: `'full'` and
-   * `'half'` compile the glass lookup into it, and a lookup that finds no glass and returns at its
-   * first line still costs the lit pass its registers — measured on the courtyard at night, 0.27 ms
-   * at 720p on WebGPU, 0.42 ms on WebGL2 and 1.2 ms at 4K. `'off'` compiles none of it, so a world
-   * that never casts through glass is that much faster for saying so. What would make `'full'` wrong
-   * is a phone budget with a lot of glass; that is what `'half'` is for. See `glassShadow.ts`.
+   * no memory and no pass whatever this says. **Nor any shader, since 4.8.2**: the lit shader is
+   * built without the glass lookup and rebuilt with it when the first glass caster reaches a shadow.
+   * A lookup that finds no glass still cost the lit pass its registers — measured on the courtyard at
+   * night, 0.27 ms at 720p on WebGPU, 0.42 ms on WebGL2 and 1.2 ms at 4K — and from 4.5.0 to 4.8.1
+   * every scene paid it, glass or none: about 30% of the lit shader's instructions, which on a phone
+   * was the lit pass. `'off'` never rebuilds. What would make `'full'` wrong is a phone budget with a
+   * lot of glass; that is what `'half'` is for. See `glassShadow.ts`.
    */
   readonly glassShadows: GlassShadows;
   /** Horizontal world-space reach over which a directional shadow dissolves. */

package/src/render/sceneCoverage.ts

@@ -0,0 +1,78 @@
+/**
+ * What a blended draw into the scene does to its alpha, which holds how much of each pixel is still
+ * the opaque surface — the share ambient occlusion is allowed to darken.
+ *
+ * **Occlusion is applied in the composite, from the depth the opaque world left**, after every
+ * translucent draw has landed, and a particle or a pane writes no depth: so a puff of smoke in front
+ * of a wall was darkened by the corner behind it. Reported from a game as walls and two figures
+ * standing behind a cloud showing through it as outlines, and nothing at all with occlusion off.
+ *
+ * So the scene's alpha is a running share. The frame clears it to 1 and an opaque draw writes 1,
+ * which is the whole of the surface; then each draw blended in front of it says which of three
+ * things it is, and the composite darkens `share` of the pixel and leaves the rest:
+ *
+ * - **It covers**: glass, smoke, water, a line, text in the world, a panel. The share falls by what
+ *   the draw lets through, `share * (1 - a)`.
+ * - **It transmits**: the medium, the order-independent composite. Its alpha already *is* what gets
+ *   through, `share * a`.
+ * - **It keeps**: light added to the surface or a layer of the surface itself — caustics, a light
+ *   volume, a bolt, a wet film, a decal, a reflection. The share is unchanged.
+ *
+ * **What it gives up** is added light in front of an occluded corner: a glow or a spark adds to the
+ * pixel and keeps the share, so the composite darkens what it added along with the surface — which
+ * is how every blended draw behaved before this, and one multiply cannot tell the two apart. **What
+ * would make it wrong** is an opaque pass writing an alpha below 1: its surface would then take less
+ * occlusion than it should, which is the safe direction, and is the lit shader's own case at a
+ * cutout's edge or under a per-vertex alpha lane.
+ *
+ * **It survives the temporal passes.** A temporal resolve passes the frame's alpha through, since
+ * it is a fact about this frame and takes no history; a reconstruction reads it from the scene it
+ * rebuilt into the picture it shows, and the blended draws that land after it cover that picture.
+ *
+ * **One pipeline does not take part**: the GPU-driven pass blends its own surfaces into a target
+ * whose alpha is the mask its blit reads to tell a drawn pixel from an undrawn one, and that blit
+ * writes the share back to 1. Its panes still take the occlusion of what they cover. What would
+ * close it is a channel for that mask other than alpha.
+ *
+ * A contributed pass drawing something blended into the scene states the same thing for its own
+ * pipeline with `SCENE_ALPHA_COVERS`, `SCENE_ALPHA_TRANSMITS` or `SCENE_ALPHA_KEEPS`.
+ */
+
+/** A blended draw that covers the surface by its alpha: `share * (1 - a)`. */
+export const SCENE_ALPHA_COVERS: GPUBlendComponent = {
+  srcFactor: 'zero',
+  dstFactor: 'one-minus-src-alpha',
+  operation: 'add',
+};
+
+/** A draw whose alpha is what gets through it, a transmittance or a revealage: `share * a`. */
+export const SCENE_ALPHA_TRANSMITS: GPUBlendComponent = {
+  srcFactor: 'zero',
+  dstFactor: 'src-alpha',
+  operation: 'add',
+};
+
+/** Light added to the surface, or a layer of it: the share unchanged. */
+export const SCENE_ALPHA_KEEPS: GPUBlendComponent = {
+  srcFactor: 'zero',
+  dstFactor: 'one',
+  operation: 'add',
+};
+
+/**
+ * The same three on WebGL2, as the alpha half of `blendFuncSeparate` beside the colour half a
+ * caller already had. `src` and `dst` are the colour factors.
+ */
+export function blendCovering(gl: WebGL2RenderingContext, src: number, dst: number): void {
+  gl.blendFuncSeparate(src, dst, gl.ZERO, gl.ONE_MINUS_SRC_ALPHA);
+}
+
+/** `SCENE_ALPHA_TRANSMITS` on WebGL2, beside the colour factors `src` and `dst`. */
+export function blendTransmitting(gl: WebGL2RenderingContext, src: number, dst: number): void {
+  gl.blendFuncSeparate(src, dst, gl.ZERO, gl.SRC_ALPHA);
+}
+
+/** `SCENE_ALPHA_KEEPS` on WebGL2, beside the colour factors `src` and `dst`. */
+export function blendKeeping(gl: WebGL2RenderingContext, src: number, dst: number): void {
+  gl.blendFuncSeparate(src, dst, gl.ZERO, gl.ONE);
+}

package/src/render/sdfTextRenderer.ts

@@ -7,6 +7,7 @@ import { compileProgram, uniformLocations } from './shader.ts';
 import { SDF_TEXT_FRAG, SDF_TEXT_VERT } from './shaders/sdfText.ts';
 import type { SurfaceTexture } from './surfaceTexture.ts';
 import { SDF_TEXT_TEXTURE_UNIT } from './lightBudget.ts';
+import { blendCovering } from './sceneCoverage.ts';
 
 /**
  * Text from a signed distance field, on WebGL2.
@@ -144,7 +145,7 @@ export class SdfTextRenderer {
      */
     gl.depthMask(false);
     gl.enable(gl.BLEND);
-    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
 
     this.atlas.bind(gl, SDF_TEXT_TEXTURE_UNIT);
 

package/src/render/shaders/depth.ts

@@ -60,12 +60,13 @@ ${CHANNEL_BEND}
 
 #if CUTOUT
 /*
- * **What a cutout caster adds, and where.** The UV at location 5, where every mesh carries it; two
+ * **What a cutout caster adds, and where.** The UV at location 5, where every mesh carries it; three
  * uniforms declared after every other, so no field of the plain variant moves and a binder written
  * against it stays right for this one; and two outputs after vLightPosition, which keeps location 0.
  */
 layout(location = 5) in vec3 aUv;
 uniform vec2 uUvScale;
+uniform vec2 uUvOffset;
 uniform float uAlphaCutout;
 #endif
 
@@ -104,7 +105,7 @@ void main() {
   vLightPosition = uLightViewProj * vec4(bent, world.w);
   gl_Position = vLightPosition;
 #if CUTOUT
-  vUv = vec3(aUv.xy * uUvScale, aUv.z);
+  vUv = vec3(aUv.xy * uUvScale + uUvOffset, aUv.z);
   vAlphaCutout = uAlphaCutout;
 #endif
 #if GLASS