@driftengine/core 4.8.2 → 4.8.4

package/src/render/clothPlacement.ts

@@ -0,0 +1,114 @@
+/**
+ * Where a cloth-bound vertex goes: the reference for what the vertex stage computes.
+ *
+ * A render vertex bound to a simulation triangle (particles a, b, c) sits at its barycentric point
+ * — `a·(1 − u − v) + b·u + c·v` — raised `offset` along the triangle's normal; its normal turns as
+ * the triangle turned since rest. The turn is the rotation from the triangle's rest frame
+ * to its frame now, each frame built from its first edge and its normal, so a vertex beside the
+ * triangle, a fold's width away, moves as the cloth moves rather than as its skeleton does.
+ *
+ * **A vertex bound to one particle** — all three indices equal — sits on it and keeps its normal:
+ * a single point has no frame to turn by. That is how a binding says "follow this particle".
+ *
+ * **A reference, as `recon/motionVectors.ts` is**: nothing at run time calls it. The vertex stage in
+ * `shaders/clothBinding.ts` and the cloth motion stage in `shaders/recon/motion.wgsl.ts` are the
+ * same arithmetic for the device, and nothing but a device holds them to this — the source tests
+ * pin where the shader moves a vertex, not the numbers it moves it by. `demo/dev/skinnedCloth.html`
+ * is where the two backends were compared, and they agree to two levels in 255.
+ */
+
+/** Where a placement lands, written into caller-owned arrays. */
+export interface ClothPlacement {
+  readonly position: Float64Array;
+  readonly normal: Float64Array;
+}
+
+const NOW = new Float64Array(9);
+const REST = new Float64Array(9);
+
+/** A triangle's frame — first edge, normal × edge, normal — as three columns, into `out`. */
+function frame(
+  particles: ArrayLike<number>,
+  a: number,
+  b: number,
+  c: number,
+  out: Float64Array,
+): void {
+  const ex = (particles[b * 3] as number) - (particles[a * 3] as number);
+  const ey = (particles[b * 3 + 1] as number) - (particles[a * 3 + 1] as number);
+  const ez = (particles[b * 3 + 2] as number) - (particles[a * 3 + 2] as number);
+  const fx = (particles[c * 3] as number) - (particles[a * 3] as number);
+  const fy = (particles[c * 3 + 1] as number) - (particles[a * 3 + 1] as number);
+  const fz = (particles[c * 3 + 2] as number) - (particles[a * 3 + 2] as number);
+  let nx = ey * fz - ez * fy;
+  let ny = ez * fx - ex * fz;
+  let nz = ex * fy - ey * fx;
+  const nl = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+  nx /= nl;
+  ny /= nl;
+  nz /= nl;
+  const el = Math.sqrt(ex * ex + ey * ey + ez * ez) || 1;
+  const tx = ex / el;
+  const ty = ey / el;
+  const tz = ez / el;
+  out[0] = tx;
+  out[1] = ty;
+  out[2] = tz;
+  out[3] = ny * tz - nz * ty;
+  out[4] = nz * tx - nx * tz;
+  out[5] = nx * ty - ny * tx;
+  out[6] = nx;
+  out[7] = ny;
+  out[8] = nz;
+}
+
+/** Place one vertex: `now` and `rest` are particle positions, three floats each. */
+export function clothPlace(
+  now: ArrayLike<number>,
+  rest: ArrayLike<number>,
+  a: number,
+  b: number,
+  c: number,
+  u: number,
+  v: number,
+  offset: number,
+  restNormal: readonly [number, number, number],
+  out: ClothPlacement,
+): void {
+  if (a === b && b === c) {
+    out.position[0] = now[a * 3] as number;
+    out.position[1] = now[a * 3 + 1] as number;
+    out.position[2] = now[a * 3 + 2] as number;
+    out.normal[0] = restNormal[0];
+    out.normal[1] = restNormal[1];
+    out.normal[2] = restNormal[2];
+    return;
+  }
+  frame(now, a, b, c, NOW);
+  frame(rest, a, b, c, REST);
+  const w = 1 - u - v;
+  for (let k = 0; k < 3; k++) {
+    out.position[k] =
+      (now[a * 3 + k] as number) * w +
+      (now[b * 3 + k] as number) * u +
+      (now[c * 3 + k] as number) * v +
+      (NOW[6 + k] as number) * offset;
+  }
+  /* Turned by now × restᵀ: the rest normal in the rest frame's terms, rebuilt in the frame now. */
+  const t =
+    (REST[0] as number) * restNormal[0] +
+    (REST[1] as number) * restNormal[1] +
+    (REST[2] as number) * restNormal[2];
+  const s =
+    (REST[3] as number) * restNormal[0] +
+    (REST[4] as number) * restNormal[1] +
+    (REST[5] as number) * restNormal[2];
+  const n =
+    (REST[6] as number) * restNormal[0] +
+    (REST[7] as number) * restNormal[1] +
+    (REST[8] as number) * restNormal[2];
+  for (let k = 0; k < 3; k++) {
+    out.normal[k] =
+      (NOW[k] as number) * t + (NOW[3 + k] as number) * s + (NOW[6 + k] as number) * n;
+  }
+}

package/src/render/compressedSource.ts

@@ -0,0 +1,198 @@
+/**
+ * A block-compressed image a caller hands to `createSurfaceTexture`, and the one decision about it
+ * both backends share: whether this device takes it as blocks.
+ *
+ * **Uploaded as it is, or not at all.** A BC texture costs a byte a texel on the GPU (BC7) or half
+ * of one (BC1) against four for RGBA, and keeps the mip chain its author built rather than one a box
+ * filter makes. A device that cannot sample the format — most phones, which have ASTC and ETC2 —
+ * gets nothing from the blocks, and the engine does not decode them here: core ships no decoder.
+ * The loader in `@driftengine/assets` asks `uploadsCompressed` first and decodes at load where the
+ * answer is no; a caller handing a source this device cannot take is refused by name.
+ *
+ * Backend-neutral, because both backends must agree on what they accept before either touches a
+ * device. `BlockFormat` is the same union `@driftengine/drft` names `BcFormat`; core imports nothing
+ * from that package, and a format added there without a twin here fails where the loader passes one
+ * to the other, at compile time.
+ */
+
+/** BC1 to BC5 and BC7. BC6H and the signed forms are not among them. */
+export type BlockFormat = 'bc1' | 'bc2' | 'bc3' | 'bc4' | 'bc5' | 'bc7';
+
+/** A format as a device offers it: the colour space is part of the name, as WebGPU's are. */
+export type CompressedTextureFormat =
+  'bc1' | 'bc1-srgb' | 'bc2' | 'bc2-srgb' | 'bc3' | 'bc3-srgb' | 'bc4' | 'bc5' | 'bc7' | 'bc7-srgb';
+
+/** Block-compressed texels with their stored mip chain, level 0 first. */
+export interface CompressedTextureSource {
+  readonly format: BlockFormat;
+  readonly width: number;
+  readonly height: number;
+  readonly levels: readonly Uint8Array[];
+}
+
+/** What `createSurfaceTexture` takes: an image, or blocks. */
+export type SurfaceSource = TexImageSource | CompressedTextureSource;
+
+/**
+ * The layers as blocks, or null where every one is an image. An array mixing the two is refused:
+ * one GPU texture has one format.
+ */
+export function compressedLayers(
+  sources: readonly SurfaceSource[],
+): readonly CompressedTextureSource[] | null {
+  let count = 0;
+  for (const source of sources) if (isCompressedSource(source)) count++;
+  if (count === 0) return null;
+  if (count !== sources.length) {
+    throw new Error(
+      'createSurfaceTextureArray: some layers are blocks and some are images, and one texture has ' +
+        'one format. Decode the blocks, or build the array from blocks alone.',
+    );
+  }
+  return sources as readonly CompressedTextureSource[];
+}
+
+/** Bytes per 4x4 block. */
+export const BLOCK_BYTES: Readonly<Record<BlockFormat, number>> = {
+  bc1: 8,
+  bc2: 16,
+  bc3: 16,
+  bc4: 8,
+  bc5: 16,
+  bc7: 16,
+};
+
+/** Whether `source` is a compressed source rather than an image. */
+export function isCompressedSource(source: unknown): source is CompressedTextureSource {
+  const candidate = source as { format?: unknown; levels?: unknown } | null;
+  return (
+    typeof candidate === 'object' &&
+    candidate !== null &&
+    typeof candidate.format === 'string' &&
+    Array.isArray(candidate.levels)
+  );
+}
+
+/** The format a device would have to offer, or null for one with no sRGB form. */
+export function compressedFormatName(
+  format: BlockFormat,
+  srgb: boolean,
+): CompressedTextureFormat | null {
+  if (!srgb) return format;
+  return format === 'bc4' || format === 'bc5' ? null : `${format}-srgb`;
+}
+
+/**
+ * Whether a `width` by `height` source in `format` uploads as blocks on a device offering
+ * `available`. Level 0 must be whole blocks each way: WebGPU refuses any other size for a BC
+ * texture, and WebGL2's S3TC extension says the same, so a 6x6 image is decoded rather than
+ * refused. What would make that wrong is a device that pads; none is relied on here.
+ */
+export function uploadsCompressed(
+  format: BlockFormat,
+  srgb: boolean,
+  width: number,
+  height: number,
+  available: readonly CompressedTextureFormat[],
+): boolean {
+  const name = compressedFormatName(format, srgb);
+  return name !== null && width % 4 === 0 && height % 4 === 0 && available.includes(name);
+}
+
+/** The bytes level `level` of a `width` by `height` image takes: whole blocks, one at least. */
+function levelBytes(format: BlockFormat, width: number, height: number, level: number): number {
+  const w = Math.max(1, width >> level);
+  const h = Math.max(1, height >> level);
+  return Math.ceil(w / 4) * Math.ceil(h / 4) * BLOCK_BYTES[format];
+}
+
+/**
+ * How many levels the layers carry, after checking each is the size its place requires and every
+ * layer matches the first. Refuses by name: a short level uploaded anyway is a device error at
+ * submit, which on WebGPU is a frame that draws nothing and says so somewhere else.
+ */
+export function compressedLevels(layers: readonly CompressedTextureSource[]): number {
+  const first = layers[0];
+  if (first === undefined)
+    throw new Error('createSurfaceTexture: an array needs at least one image');
+  const { format, width, height } = first;
+  const count = first.levels.length;
+  const most = Math.floor(Math.log2(Math.max(1, width, height))) + 1;
+  if (count < 1 || count > most) {
+    throw new Error(
+      `createSurfaceTexture: ${count} levels for a ${width}x${height} image, which has at least 1 ` +
+        `and at most ${most}`,
+    );
+  }
+  for (let layer = 0; layer < layers.length; layer++) {
+    const source = layers[layer] as CompressedTextureSource;
+    if (
+      source.format !== format ||
+      source.width !== width ||
+      source.height !== height ||
+      source.levels.length !== count
+    ) {
+      throw new Error(
+        `createSurfaceTexture: layer ${layer} is ${source.width}x${source.height} ` +
+          `${source.format.toUpperCase()} with ${source.levels.length} levels, and layer 0 is ` +
+          `${width}x${height} ${format.toUpperCase()} with ${count}. Every layer of an array is one ` +
+          'format, size and chain on the device.',
+      );
+    }
+    for (let level = 0; level < count; level++) {
+      const want = levelBytes(format, width, height, level);
+      const got = (source.levels[level] as Uint8Array).length;
+      if (got !== want) {
+        throw new Error(
+          `createSurfaceTexture: level ${level} of a ${width}x${height} ${format.toUpperCase()} ` +
+            `image is ${want} bytes, and ${got} were given`,
+        );
+      }
+    }
+  }
+  return count;
+}
+
+/** What a refusal names: the format, its colour space, and what the device offers instead. */
+export function compressedRefusal(
+  format: BlockFormat,
+  srgb: boolean,
+  width: number,
+  height: number,
+  available: readonly CompressedTextureFormat[],
+): string {
+  const asked = `${format.toUpperCase()}${srgb ? ' sRGB' : ''} at ${width}x${height}`;
+  const offered = available.length === 0 ? 'no BC format' : available.join(', ');
+  return (
+    `createSurfaceTexture: this device cannot take ${asked} as blocks — it offers ${offered}, and ` +
+    'a BC texture must be whole 4x4 blocks at level 0. Decode it first (decodeBc in ' +
+    '@driftengine/assets), or ask renderer.compressedFormats before choosing.'
+  );
+}
+
+/** The format name and level count blocks upload as here, or a refusal naming why they cannot. */
+export function planBlocks(
+  blocks: readonly CompressedTextureSource[],
+  srgb: boolean,
+  compressed: readonly CompressedTextureFormat[],
+): { readonly name: CompressedTextureFormat; readonly levels: number } {
+  const { format, width, height } = blocks[0] as CompressedTextureSource;
+  const name = compressedFormatName(format, srgb);
+  if (name === null || !uploadsCompressed(format, srgb, width, height, compressed)) {
+    throw new Error(compressedRefusal(format, srgb, width, height, compressed));
+  }
+  return { name, levels: compressedLevels(blocks) };
+}
+
+/**
+ * `update` replaces pixels with an image, and a texture holding blocks has no pixels to replace:
+ * its format is the blocks', and an image would be a different texture. Refused rather than
+ * quietly reallocated, so the handle a draw holds keeps meaning what it meant.
+ */
+export function refuseBlockUpdate(format: BlockFormat | null): void {
+  if (format === null) return;
+  throw new Error(
+    `updateSurfaceTexture: this texture holds ${format.toUpperCase()} blocks, and update replaces ` +
+      'an image. Build a new texture for new contents.',
+  );
+}

package/src/render/cutoutCaster.ts

@@ -13,19 +13,34 @@
  */
 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;
+  /** 1 for a dithered edge, which a caster draws with a pattern that does not move. */
+  readonly dithered: 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;
+  dithered: number;
+  u: number;
+  v: number;
+  uOffset: number;
+  vOffset: number;
+} = {
   albedo: null,
   cutoff: 0,
+  dithered: 0,
   u: 1,
   v: 1,
+  uOffset: 0,
+  vOffset: 0,
 };
 
 /** The cutout `material` casts, or null for an ordinary caster. */
@@ -38,7 +53,10 @@ export function cutoutOf<Texture>(
   if (albedo === null || !(cutoff > 0)) return null;
   answer.albedo = albedo;
   answer.cutoff = cutoff;
+  answer.dithered = material.cutoutMode === 'dithered' ? 1 : 0;
   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/cutoutDither.ts

@@ -0,0 +1,99 @@
+/**
+ * A cutout whose edge is a share of the pixel rather than a line through it.
+ *
+ * **Why.** A hard alpha test draws a strand of hair, an eyelash or a fringe of leaves as a stair of
+ * whole pixels: a card's alpha falls off over a few texels and the test turns that into on and off.
+ * A dithered cutout keeps each pixel with a probability, the share of it the texture covers, and
+ * something downstream then averages the pattern back into coverage. What can average it depends on
+ * the frame, so the material asks for the smooth edge and the renderer decides, per frame, how:
+ *
+ * - **A temporal resolve (TAA or DriftTR)**: the pixel is kept against a threshold that moves every
+ *   frame, and the resolve integrates the pattern over its history into coverage.
+ * - **A multisampled frame**: the share goes to the GPU as alpha-to-coverage, which turns it into
+ *   that many of the pixel's samples.
+ * - **Neither**: the hard test, because a dither nothing resolves is grain on the screen.
+ *
+ * **What it gives up**: a dithered edge under a temporal resolve is soft by one history's worth of
+ * blur and ghosts slightly behind a fast card, which is the resolve's own trade; and under
+ * multisampling the share is quantised to the sample count, five levels at four samples. **What
+ * would make it wrong** is a pass that tests depth for equality against the main pass and discards
+ * differently from it; the caster and the lit pass take their keep from the same two functions here.
+ */
+
+/** What a material asks for. `'hard'` is every cutout that shipped before this. */
+export type CutoutMode = 'hard' | 'dithered';
+
+/** What the frame does with it: 0, 1 and 2 in the shader's `uCutout.y`. */
+export type CutoutResolve = 'hard' | 'dither' | 'coverage';
+
+/** The shader's number for a resolve. */
+export const CUTOUT_RESOLVE_CODE: Readonly<Record<CutoutResolve, number>> = Object.freeze({
+  hard: 0,
+  dither: 1,
+  coverage: 2,
+});
+
+/**
+ * How a cutout is drawn this frame. A temporal resolve is preferred over multisampling when a frame
+ * has both, because it resolves every share and multisampling only the sample count's.
+ */
+export function resolveCutout(mode: CutoutMode, temporal: boolean, samples: number): CutoutResolve {
+  if (mode !== 'dithered') return 'hard';
+  if (temporal) return 'dither';
+  if (samples > 1) return 'coverage';
+  return 'hard';
+}
+
+/**
+ * The share of a pixel a cutout keeps, from its alpha: half at the cutoff, ramping over a band
+ * twice the distance to the nearer end. At a cutoff of a half that is alpha itself.
+ */
+export function cutoutShare(alpha: number, cutoff: number): number {
+  const band = Math.max(2 * Math.min(cutoff, 1 - cutoff), 1e-4);
+  return Math.min(Math.max((alpha - cutoff) / band + 0.5, 0), 1);
+}
+
+/**
+ * The temporal step of the noise below, per frame: Jimenez's constant (2014), which moves the
+ * pattern across the tile rather than stepping each pixel's threshold.
+ *
+ * **A golden-ratio step per pixel was tried and measured, and it is not better.** It spreads a still
+ * pixel's thresholds evenly over time, which reads like the cure for grain; on a card of strands
+ * under TAA it left 12.9 levels of grain against this one's 11.7. The floor is the resolve's own: it
+ * keeps nine tenths of its history, so the newest frame's kept-or-not pattern is a tenth of the
+ * picture, about ten levels of grain at a half share whatever sequence chose it.
+ */
+const NOISE_FRAME_STEP = 5.588238;
+
+/**
+ * The threshold a pixel's share is compared against: interleaved gradient noise (Jimenez,
+ * "Next Generation Post Processing in Call of Duty: Advanced Warfare", 2014), offset by the frame so
+ * the pattern moves. `x` and `y` are pixel centres, as `gl_FragCoord.xy` is.
+ */
+export function ditherThreshold(x: number, y: number, frame: number): number {
+  const px = x + NOISE_FRAME_STEP * frame;
+  const py = y + NOISE_FRAME_STEP * frame;
+  const inner = 0.06711056 * px + 0.00583715 * py;
+  const f = 52.9829189 * (inner - Math.floor(inner));
+  return f - Math.floor(f);
+}
+
+/**
+ * The two functions in GLSL, for the lit pass and every caster that keeps the same pixels.
+ *
+ * `cutoutKeeps(share, pixel, frame)` is the dithered test; `cutoutShare(alpha, cutoff)` is also what
+ * a coverage frame writes as alpha. Frame is a float the renderer counts and wraps, so the noise's
+ * argument stays small enough for a half-precision device.
+ */
+export const CUTOUT_DITHER_GLSL = `
+float cutoutShare(float alpha, float cutoff) {
+  float band = max(2.0 * min(cutoff, 1.0 - cutoff), 1e-4);
+  return clamp((alpha - cutoff) / band + 0.5, 0.0, 1.0);
+}
+
+bool cutoutKeeps(float share, vec2 pixel, float frame) {
+  vec2 p = pixel + vec2(${NOISE_FRAME_STEP.toFixed(6)} * frame);
+  float noise = fract(52.9829189 * fract(dot(p, vec2(0.06711056, 0.00583715))));
+  return share > noise;
+}
+`;

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/eyeRefraction.ts

@@ -0,0 +1,72 @@
+/**
+ * The eye model's refraction, as `shaders/flat/eye.ts` computes it: the reference its tests hold the
+ * arithmetic to, and nothing at run time calls it.
+ *
+ * **An iris is seen through a cornea**, a few millimetres of clear fluid above it with an index near
+ * water's, so it is not where it is painted: the eye's ray bends at the cornea toward the axis and
+ * meets the iris plane somewhere else, and the iris seems to lie deeper and to shift as the eye
+ * turns away. The lit stage moves the iris's texture coordinate by that shift before any map of
+ * the material is read, so the whole iris — colour, relief, its own channels — moves as one.
+ *
+ * **The shift**: refract the view at the cornea's surface, follow the refracted ray down until it
+ * has descended the cornea's height above the iris plane along the eye's axis, and take what it
+ * travelled across the plane. Head-on it is nothing; at an angle θ to a flat cornea it is
+ * `height · tan(asin(sin θ / ior))`. The plane is perpendicular to the axis, so a cornea seen
+ * almost edge-on sends the ray along it: the descent is floored, which bounds the shift at about a
+ * thousand times the height rather than letting it run to infinity at the limb.
+ */
+import type { Vec3 } from '../math/color.ts';
+
+/** Schlick's base for the cornea's highlight, at the model's default index 1.336. */
+export const CORNEA_F0 = ((1 - 1.336) / (1 + 1.336)) ** 2;
+
+/** How slowly a refracted ray may descend toward the iris plane before it is held there. */
+export const EYE_MIN_DESCENT = 1e-3;
+
+/** GLSL's `refract`, into `out`: the transmitted direction, or zeros past total internal reflection. */
+export function refract(incident: Vec3, normal: Vec3, eta: number, out: Float64Array): void {
+  const d = normal[0] * incident[0] + normal[1] * incident[1] + normal[2] * incident[2];
+  const k = 1 - eta * eta * (1 - d * d);
+  if (k < 0) {
+    out.fill(0);
+    return;
+  }
+  const s = eta * d + Math.sqrt(k);
+  for (let c = 0; c < 3; c++) out[c] = eta * (incident[c] as number) - s * (normal[c] as number);
+}
+
+/**
+ * How far across the iris plane the eye's ray lands from where it entered the cornea, in metres,
+ * into `out`: `toEye` and `normal` at the cornea, `axis` the eye's, all unit vectors; `height` the
+ * cornea's height above the iris plane there.
+ */
+export function eyeRefractionShift(
+  toEye: Vec3,
+  normal: Vec3,
+  axis: Vec3,
+  ior: number,
+  height: number,
+  out: Float64Array,
+): void {
+  const ray = new Float64Array(3);
+  refract([-toEye[0], -toEye[1], -toEye[2]], normal, 1 / ior, ray);
+  const descent = Math.max(
+    -((ray[0] as number) * axis[0] + (ray[1] as number) * axis[1] + (ray[2] as number) * axis[2]),
+    EYE_MIN_DESCENT,
+  );
+  const reach = height / descent;
+  const along =
+    ((ray[0] as number) * axis[0] + (ray[1] as number) * axis[1] + (ray[2] as number) * axis[2]) *
+    reach;
+  for (let c = 0; c < 3; c++) out[c] = (ray[c] as number) * reach - axis[c] * along;
+}
+
+/**
+ * Where the iris is, without a map: 1 inside `irisRadius` of the texture's centre, 0 outside, across
+ * an edge `edge` wide — a limbus, not a cut.
+ */
+export function irisMask(u: number, v: number, irisRadius: number, edge: number): number {
+  const r = Math.hypot(u - 0.5, v - 0.5);
+  const t = Math.min(Math.max((r - (irisRadius - edge)) / (2 * edge), 0), 1);
+  return 1 - t * t * (3 - 2 * t);
+}

package/src/render/glCompressed.ts

@@ -0,0 +1,86 @@
+/**
+ * BC on WebGL2: which formats this context samples, and the upload of a stored chain.
+ *
+ * **Four extensions, each a different subset**, and the names a device offers are read off them:
+ * `WEBGL_compressed_texture_s3tc` is BC1 to BC3, its `_srgb` twin their sRGB forms,
+ * `EXT_texture_compression_rgtc` BC4 and BC5, and `EXT_texture_compression_bptc` BC7 in both. A
+ * desktop GPU usually has all four and a phone none, which is why the loader decodes there.
+ *
+ * BC1 is uploaded as `COMPRESSED_RGBA_S3TC_DXT1_EXT` rather than the RGB one, so a three-colour
+ * block's fourth index is transparent here as it is on WebGPU, whose only BC1 is `bc1-rgba-unorm`.
+ *
+ * The stored levels are uploaded as they are and no chain is generated: `generateMipmap` cannot
+ * write a compressed format, and the chain its author stored is the better one anyway. A chain that
+ * stops before 1x1 sets `TEXTURE_MAX_LEVEL` to its last level, or the texture is incomplete and
+ * samples black.
+ */
+import type { CompressedTextureFormat, CompressedTextureSource } from './compressedSource.ts';
+
+/** The constants each extension defines, written out so a missing extension cannot be read for one. */
+const INTERNAL: Readonly<Record<CompressedTextureFormat, number>> = {
+  bc1: 0x83f1, // COMPRESSED_RGBA_S3TC_DXT1_EXT
+  bc2: 0x83f2, // COMPRESSED_RGBA_S3TC_DXT3_EXT
+  bc3: 0x83f3, // COMPRESSED_RGBA_S3TC_DXT5_EXT
+  'bc1-srgb': 0x8c4d, // COMPRESSED_SRGB_ALPHA_S3TC_DXT1_EXT
+  'bc2-srgb': 0x8c4e, // COMPRESSED_SRGB_ALPHA_S3TC_DXT3_EXT
+  'bc3-srgb': 0x8c4f, // COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT
+  bc4: 0x8dbb, // COMPRESSED_RED_RGTC1_EXT
+  bc5: 0x8dbd, // COMPRESSED_RED_GREEN_RGTC2_EXT
+  bc7: 0x8e8c, // COMPRESSED_RGBA_BPTC_UNORM_EXT
+  'bc7-srgb': 0x8e8d, // COMPRESSED_SRGB_ALPHA_BPTC_UNORM_EXT
+};
+
+const BY_EXTENSION: readonly (readonly [string, readonly CompressedTextureFormat[]])[] = [
+  ['WEBGL_compressed_texture_s3tc', ['bc1', 'bc2', 'bc3']],
+  ['WEBGL_compressed_texture_s3tc_srgb', ['bc1-srgb', 'bc2-srgb', 'bc3-srgb']],
+  ['EXT_texture_compression_rgtc', ['bc4', 'bc5']],
+  ['EXT_texture_compression_bptc', ['bc7', 'bc7-srgb']],
+];
+
+/**
+ * The BC formats this context samples, enabling each extension that offers some. Enabling is what
+ * `getExtension` does, and a format is only legal in an upload once it has been called.
+ */
+export function glCompressedFormats(gl: WebGL2RenderingContext): CompressedTextureFormat[] {
+  const out: CompressedTextureFormat[] = [];
+  for (const [name, formats] of BY_EXTENSION) {
+    if (gl.getExtension(name) !== null) out.push(...formats);
+  }
+  return out;
+}
+
+/**
+ * Upload `layers`, every one of `levels` levels, to the bound `TEXTURE_2D_ARRAY` as `name`, and cap
+ * the chain at what was stored. The caller has checked the sources and the device.
+ */
+export function uploadCompressedArray(
+  gl: WebGL2RenderingContext,
+  name: CompressedTextureFormat,
+  layers: readonly CompressedTextureSource[],
+  levels: number,
+): void {
+  const first = layers[0] as CompressedTextureSource;
+  for (let level = 0; level < levels; level++) {
+    let size = 0;
+    for (const layer of layers) size += (layer.levels[level] as Uint8Array).length;
+    const data = new Uint8Array(size);
+    let at = 0;
+    for (const layer of layers) {
+      const bytes = layer.levels[level] as Uint8Array;
+      data.set(bytes, at);
+      at += bytes.length;
+    }
+    gl.compressedTexImage3D(
+      gl.TEXTURE_2D_ARRAY,
+      level,
+      INTERNAL[name],
+      Math.max(1, first.width >> level),
+      Math.max(1, first.height >> level),
+      layers.length,
+      0,
+      data,
+    );
+  }
+  gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_BASE_LEVEL, 0);
+  gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAX_LEVEL, levels - 1);
+}

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);